Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
344a8b8e4This file is pinned to the selected release. Download the original to open it in your design tool.
# FleetGuard 🛡️🚚
**A self-contained IoT telematics device for fleet & logistics vehicles — GPS tracking, fuel-theft detection, tamper/security alarms, and offline-resilient cloud reporting.**
> Built around an **ESP32** and a **SIM7600G 4G LTE + GPS** modem, FleetGuard rides inside the vehicle, talks to a companion OBD2 node over ESP-NOW, watches its own sensors, and streams everything to the cloud over MQTT. When the network drops, it buffers to flash and uploads automatically once it's back — nothing is lost.
<p>
<img alt="Platform" src="https://img.shields.io/badge/platform-ESP32-blue">
<img alt="Modem" src="https://img.shields.io/badge/cellular-SIM7600G%204G%20LTE-success">
<img alt="Firmware" src="https://img.shields.io/badge/firmware-Arduino%2FC%2B%2B-orange">
<img alt="PCB" src="https://img.shields.io/badge/PCB-KiCad-purple">
<img alt="Enclosure" src="https://img.shields.io/badge/enclosure-Autodesk%20Inventor-red">
</p>
---
## Table of Contents
- [Overview](#overview)
- [Key Features](#key-features)
- [System Architecture](#system-architecture)
- [Repository Structure](#repository-structure)
- [Firmware Modules](#firmware-modules)
- [Hardware](#hardware)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [⚠️ Before You Publish — Security Checklist](#️-before-you-publish--security-checklist)
- [Author](#author)
- [License](#license)
---
## Overview
FleetGuard is a complete, field-deployable vehicle-telematics unit designed for the logistics industry. It is a **two-node system**:
1. **The Tracker (main node)** — an ESP32 + SIM7600G module that lives in the vehicle. It owns the cellular link, the GPS, the security sensors, the local fuel-level probe, and the offline buffer.
2. **The OBD2 node (companion)** — a second ESP that plugs into the vehicle's OBD2 port (via an ELM327 adapter), reads engine data (speed, RPM, fuel level, coolant, etc.), and broadcasts it to the tracker over **ESP-NOW** — a direct peer-to-peer radio link that needs no Wi-Fi router.
The repository also includes **three standalone bench/diagnostic sketches** (battery gauge, current monitor, fuel-level probe), the **custom PCB**, the **3D-printed enclosure**, and the **bill of materials** — i.e. everything required to reproduce the device end to end.
## Key Features
- 📍 **Live GPS tracking** — position read directly from the SIM7600G, cached to NVS so the last known location survives reboots and deep sleep.
- ☁️ **4G cloud reporting over MQTT** — periodic telemetry plus instant alarms published to an MQTT broker.
- 🛢️ **Fuel-theft detection (3 independent checks):**
1. On-device analog probe drops ≥10 % within 1 second (siphoning).
2. OBD2-reported fuel level drops ≥10 % within 10 minutes.
3. Fuel cap opened but no refuel detected within 5 minutes (classic siphon pattern).
- 🚨 **Tamper & cargo security** — 4 monitored inputs: device case, fuel cap, and two cargo doors (magnetic reed switches). Any breach raises an immediate cloud alarm.
- 💾 **Offline resilience** — if the network is down, events are written to internal flash (LittleFS) and uploaded automatically when connectivity returns.
- 🔋 **Smart power management** — heartbeat-driven sleep: stays awake while the engine is on, deep-sleeps for 1 hour when the vehicle has been parked for 5 minutes (modem RF off via `CFUN=4`), and wakes instantly on any sensor trigger (RTC-capable pins).
- 📡 **Router-free inter-node link** — ESP-NOW peer-to-peer between the tracker and the OBD2 node.
## System Architecture
```mermaid
flowchart LR
subgraph Vehicle
OBD[OBD2 Node\nESP32 + ELM327] -- ESP-NOW --> TRK
SENS[Security sensors\nCase / Fuel cap / 2x Cargo door] --> TRK
FUEL[Analog fuel probe] --> TRK
TRK[FleetGuard Tracker\nESP32 + SIM7600G]
FLASH[(LittleFS\noffline buffer)] <--> TRK
end
TRK -- 4G LTE / MQTT --> BROKER[(MQTT Broker)]
TRK -- GPS --> SAT((GNSS))
BROKER --> DASH[Fleet Dashboard]
```
## Repository Structure
```
FleetGuard/
├── Ahmeds_Final_Code/ # ⭐ Main tracker firmware (ESP32 + SIM7600G, MQTT, GPS, sleep, security)
│ └── Ahmeds_Final_Code.ino
├── Ahmeds_Battery_Percentage/ # Standalone: 1S LiPo fuel gauge (MAX17048) + Wi-Fi dashboard
│ └── Ahmeds_Battery_Percentage.ino
├── Ahmeds_Current_Sensor/ # Standalone: INA226 current/power monitor + Wi-Fi dashboard
│ └── Ahmeds_Current_Sensor.ino
├── Ahmeds_Fuel_Level/ # Standalone: analog fuel-probe reader + Wi-Fi dashboard
│ └── Ahmeds_Fuel_Level.ino
├── Ahmeds_PCB/ # KiCad project + Gerber/drill manufacturing files (JLCPCB)
├── Ahmeds_Enclosure/ # Autodesk Inventor 3D enclosure (case top/bottom + PCB assembly)
└── Ahmeds_BOM/ # Bill of materials (v1 and v2)
```
## Firmware Modules
| Sketch | Role | Connectivity | Highlights |
| --- | --- | --- | --- |
| **Ahmeds_Final_Code** | Production tracker | 4G LTE (SIM7600G), MQTT, ESP-NOW | GPS, fuel-theft x3, 4 security inputs, offline flash buffer, deep sleep |
| **Ahmeds_Battery_Percentage** | Bench tool | Wi-Fi AP (`FleetGuard` → `192.168.4.1`) | MAX17048 fuel gauge, live WebSocket dashboard, CSV log |
| **Ahmeds_Current_Sensor** | Bench tool | Wi-Fi STA (fixed IP) | INA226 current/voltage/power, peak + coulomb-counted Ah, waveform |
| **Ahmeds_Fuel_Level** | Bench tool | Wi-Fi AP (`FleetGuard` → `192.168.4.1`) | Smoothed/calibrated tank %, theft & refuel detection |
> The three bench sketches were used to characterize the sensors individually before the logic was integrated into the production tracker firmware.
## Hardware
Core components (see [`Ahmeds_BOM/`](Ahmeds_BOM/) for the full costed list):
| Category | Part |
| --- | --- |
| MCU | ESP32-WROOM (Wi-Fi + Bluetooth) |
| Cellular + GPS | SIM7600G (4G LTE) |
| OBD2 interface | ELM327 (Bluetooth/Wi-Fi) |
| Current sensing | INA226 / ACS712 |
| Battery gauge | MAX17048 / ZB2L3 tester |
| Power | 18650 cells (9000 mAh) · 1S 15A BMS · TP5100 charger · XL6009 / MT3608 boost · LM2596 buck |
| Fuel probe (bench) | Water-level sensor (stand-in for a real capacitive/resistive sender) |
| Fabrication | Custom 4-layer-ready KiCad PCB (manufactured at JLCPCB) |
| Mechanical | Custom Autodesk Inventor enclosure (top + bottom + PCB mount) |
**PCB** — open [`Ahmeds_PCB/Try.kicad_pro`](Ahmeds_PCB/) in [KiCad](https://www.kicad.org/). Gerber + drill files are included for direct ordering.
**Enclosure** — open the `.iam`/`.ipt` files in [`Ahmeds_Enclosure/`](Ahmeds_Enclosure/) with [Autodesk Inventor](https://www.autodesk.com/products/inventor).
## Getting Started
### Prerequisites
- [Arduino IDE](https://www.arduino.cc/en/software) (or arduino-cli) with the **ESP32 board package** installed.
- Required libraries: `TinyGSM`, `PubSubClient`, `ArduinoJson`, `LittleFS` (bundled with ESP32 core), and for the bench sketches `arduinoWebSockets` (Markus Sattler) and `INA226`.
### Flashing the tracker
1. Open `Ahmeds_Final_Code/Ahmeds_Final_Code.ino` in the Arduino IDE.
2. Select your ESP32 board and the correct COM port.
3. Set the partition scheme to one that includes a SPIFFS/LittleFS region.
4. Update the [configuration](#configuration) values for your SIM and broker.
5. Upload, then open the Serial Monitor at **115200 baud**.
Serial commands: `saved` dumps the offline queue · `clear` wipes the offline log.
## Configuration
Edit these near the top of `Ahmeds_Final_Code.ino`:
```cpp
const char* apn = "internet"; // your SIM's APN
const char* mqtt_server = "broker.hivemq.com"; // MQTT broker (move to your own for production)
const int mqtt_port = 1883;
const char* mqtt_topic = "monztrack/device01/gps";
```
Pin map (ESP32-WROOM):
| Label | Pin | Function |
| --- | --- | --- |
| `ESP32_TX_PIN` | 12 | → SIM7600 RX |
| `ESP32_RX_PIN` | 14 | ← SIM7600 TX |
| `PWRKEY_PIN` | 27 | SIM7600 power key |
| `PIN_S1` | 33 | Device-case tamper |
| `PIN_S2` | 32 | Fuel-cap switch |
| `PIN_MAG1` | 15 | Cargo door 1 |
| `PIN_MAG2` | 18 | Cargo door 2 (no deep-sleep wake) |
| `FUEL_PIN` | 34 | Analog fuel probe (ADC1) |
## ⚠️ Before You Publish — Security Checklist
This repository is configured to be **public**. Keep these points in mind:
- 🔑 **Demo Wi-Fi credentials are in the source.** All sketches use the SSID `FleetGuard` with password `A12345678a`. Because the repo is public, anyone can read this password — it's fine for bench testing, but **change it before deploying a real device.**
- 🌐 **Public MQTT broker** (`broker.hivemq.com`) — anyone can subscribe to your topic. Move to a private, authenticated broker for production.
Recommended for production: move secrets into a `secrets.h` (git-ignored) or build flags, use a unique per-device Wi-Fi password, and add MQTT username/password + TLS.
## Author
**Ahmed Yousef Saeed Khalifa**
Project: *SGU Logistics — FleetGuard*
## License
© Ahmed Yousef Saeed Khalifa. All rights reserved. See [LICENSE](LICENSE).
> The source headers declare "All rights reserved." If you'd prefer this to be open-source (so others can use, study, and contribute), replace `LICENSE` with an [MIT](https://choosealicense.com/licenses/mit/) or [Apache-2.0](https://choosealicense.com/licenses/apache-2.0/) license.