Smart Vehicle Tracking & Theft Prevention System

A smart vehicle security system. It watches a vehicle's GPS location, detects if someone is trying to steal it, shows the car's path on a live map, and lets you download a PDF security report of where the car has been.

---

How the System Works (In Simple Terms)

Think of this project as three parts working together:

1. The Smart Car (Device Layer): We use a virtual microcontroller chip (called ESP32) inside a web simulator to act as our car. It sends out data like GPS coordinates, current speed, and whether the ignition engine is ON or OFF.
2. The Postman (Communication Layer): An online server acts as a mailbox. The simulated car drops its coordinates into the mailbox. A python script on your computer (mqtt_listener.py) acts as the postman: it constantly checks the mailbox, downloads the letters, and writes them down into files on your computer.
3. The Screen (Visualization Layer): A Streamlit web dashboard loads those files and displays them in a clean web browser window. It draws a line map of the route path, updates the speed gauge, logs events like "Ignition Switched ON", and compiles PDF reports.

---

System Map

graph TD
    A[Simulated Car / ESP32] -->|Sends updates| B[Online Mailbox / MQTT Broker]
    B -->|Downloads updates| C[Postman Script / mqtt_listener.py]
    C -->|Saves state files| D[Data Files on Your Computer]
    D -->|Displays metrics & maps| E[Web Dashboard Screen]

Loading

---

Folders and Files Map

Here is where everything is located:

• Vehicle_Tracker_ESP32/: Contains the code for the virtual smart car that runs in the browser simulator.
• dashboard/: Contains the website files.
  • app.py: The main welcome page of the dashboard.
  • mqtt_listener.py: The background postman script that grabs coordinates and saves them.
  • event_engine.py: A script that watches for status updates (like moving vs parked) and logs them.
  • analytics.py: A script that calculates total distance travelled and average speeds.
  • report_generator.py: A script that builds the PDF report document.
  • pages/: Folder containing sub-pages (Live tracking map, Geofencing bounds check, System diagnostic panels, and PDF downloader).
  • data/: Folder where logs, route paths, and statistics are stored.

---

Step-by-Step Installation Guide (For Beginners)

Follow these steps exactly to run the system on your computer.

Step 1: Install Python and VS Code

You will need two free programs installed:

1. Python: The engine that runs our scripts.
   • Download from: https://www.python.org/downloads/
   • Crucial Step: During installation, check the box at the bottom that says "Add Python to PATH" before clicking Install.
2. VS Code: A text editor where we run the commands.
   • Download and install from: https://code.visualstudio.com/

Step 2: Open the Project in VS Code

1. Launch VS Code.
2. In the top menu, click File -> Open Folder...
3. Choose the IoT-Vehicle-Tracking-Theft-Prevention-System folder.

Step 3: Open the Terminal and Setup Dependencies

We will run commands in a command terminal panel.

1. In VS Code, click Terminal in the top menu -> New Terminal. A black panel opens at the bottom.
2. Type these commands one by one, pressing Enter after each:

   # 1. Create a virtual folder to keep our packages isolated
   python -m venv venv
   
   # 2. Activate the folder (Mac/Linux users)
   source venv/bin/activate
   
   # 2. Activate the folder (Windows users - if using command prompt)
   # venv\Scripts\activate.bat
   
   # 3. Install all required software packages
   pip install -r dashboard/requirements.txt

Step 4: Start the Postman Listener

1. In that same terminal tab, type this command and press Enter:

   python dashboard/mqtt_listener.py

2. You should see text output saying Starting MQTT Telemetry Listener... followed by Connected to MQTT Broker.
3. Keep this terminal open and running. It is now listening for the virtual car.

Step 5: Start the Dashboard Website

We need to start the website server:

1. Open a new terminal tab by clicking the + (plus) icon in the terminal panel header.
2. Type these commands and press Enter:

   # Activate virtual folder
   source venv/bin/activate
   
   # Start the website
   streamlit run dashboard/app.py

3. VS Code will automatically open your web browser to http://localhost:8501. Your website dashboard is now live!

Step 6: Play the Virtual Car Simulation

1. Open your browser and navigate to the Wokwi ESP32 simulator page (you can find the link or configuration in the project).
2. Click the green Play button inside Wokwi.
3. The virtual car starts transmitting! You will see coordinates, speed graphs, and map lines update instantly on your dashboard.

---

How to Test the Security Features

To see the platform in action, follow these tests:

• Test Geofence Violation Warning:
  1. On the simulator panel, drag the coordinate slide controls to move the virtual car outside its circular home boundary zone.
  2. The dashboard alert banner will immediately change from green to orange, displaying GEOFENCE WARNING.
• Test Theft Protection Alarm:
  1. Press the ARM button on the simulator circuit to lock the car.
  2. The dashboard security mode will change to ARMED.
  3. Move the coordinates slider to simulate movement.
  4. Because the car is locked, the system detects a threat! The alert banner turns red, displaying THEFT ALERT. The simulator LED will flash, and the buzzer sounds.
• Generate Security Report:
  1. Go to the Vehicle Intelligence page using the sidebar menu.
  2. Click the Generate Security Report button.
  3. A formatted PDF summary page detailing trip speeds, coordinates, geofence breaches, and event times will download directly to your computer.