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.

---

Table of Contents

• Overview
• Key Features
• System Architecture
• Repository Structure
• Firmware Modules
• Hardware
• Getting Started
• Configuration
• ⚠️ Before You Publish — Security Checklist
• Author
• 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

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/ 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 in KiCad. Gerber + drill files are included for direct ordering. Enclosure — open the .iam/.ipt files in Ahmeds_Enclosure/ with Autodesk Inventor.

Getting Started

Prerequisites

• Arduino IDE (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 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:

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.

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 or Apache-2.0 license.