A vehicle-mounted embedded sensing platform that autonomously detects road anomalies, geo-tags them with real-time GPS, and streams telemetry to a live web dashboard.
- Overview
- Live Dashboard Preview
- System Architecture
- Hardware Platform
- Sensor Subsystems
- Firmware Architecture
- Communication Protocol
- Road Event Classification
- Web Dashboard & Backend
- Repository Structure
- Getting Started
- Team
- Concepts Demonstrated
- Future Improvements
- Current Status
The Road Condition Monitoring System is a complete end-to-end embedded IoT platform that mounts on an RC vehicle and autonomously surveys road surface quality in real time.
The STM32F446RE microcontroller fuses data from an IMU, ultrasonic rangefinder, and GPS receiver to detect and geo-tag road anomalies — potholes and rough patches. Classified events are forwarded over UART to an ESP32-S3 Wi-Fi gateway, which uploads them to a Python backend for live visualization on a Leaflet.js map dashboard.
| Capability | |
|---|---|
| Multi-sensor fusion — IMU shock detection cross-validated with ultrasonic surface profiling | |
| GPS geo-tagging — NMEA GPGGA parsing with interrupt-driven ring-buffer architecture | |
| Inter-MCU telemetry — Structured ASCII packet protocol over STM32 ↔ ESP32 UART link | |
| Cloud uplink — HTTP POST pipeline from ESP32 to Python REST API | |
| Live dashboard — Color-coded map markers with per-event shock & distance metrics | |
| Vehicle integration — 3D-printed sensor mounts on a custom RC chassis |
Real-time Leaflet.js map showing pothole (🔴) and rough road (🟠) events, with per-event shock magnitude, GPS coordinates, and timestamp.
┌──────────────┐ I²C ┌───────────────────────────────────────────────────┐
│ LSM6DS3 IMU │───────► │ │
└──────────────┘ │ │ UART ┌───────────┐ Wi-Fi ┌────────────────┐
│ STM32F446RE │────────► │ ESP32-S3 │─────────►│ Backend Server │
┌──────────────┐ TIM5 │ │ └───────────┘ └───────┬────────┘
│ HC-SR04 │───────► │ • Sensor acquisition & fusion │ │
└──────────────┘ │ • Event classification (pothole / rough road) │ ▼
│ • GPS stream parsing (NMEA GPGGA) │ ┌────────────────┐
┌──────────────┐ UART │ • Telemetry packet generation │ │ Web Dashboard │
│ NEO-6M GPS │───────► │ │ │ (Leaflet.js) │
└──────────────┘ └───────────────────────────────────────────────────┘ └────────────────┘
Data flows from raw sensor readings all the way to a browser-rendered map in under a second.
| Component | Role |
|---|---|
| STM32F446RE | Primary sensing & processing node — sensor drivers, event classification, telemetry generation |
| ESP32-S3 | Communication gateway — Wi-Fi HTTP uplink + BLE-based RC vehicle control |
| Device | Interface | Function |
|---|---|---|
| LSM6DS3 | I²C | 6-axis IMU — accelerometer for shock detection |
| HC-SR04 | TIM5 Input Capture | Ultrasonic rangefinder — road surface profiling |
| NEO-6M | UART | GPS receiver — position, altitude & time |
| TB6612FNG | GPIO / PWM | Dual motor driver — RC vehicle drive control |
| Link | Nodes | Protocol |
|---|---|---|
| I²C | STM32 ↔ LSM6DS3 | Register-level IMU configuration & data read |
| UART1 | STM32 ↔ NEO-6M | NMEA 0183 GPS stream (interrupt-driven) |
| UART2 | STM32 ↔ ESP32 | Structured ASCII telemetry packets |
| Wi-Fi | ESP32 ↔ Backend | HTTP POST (JSON telemetry) |
| BLE | Phone ↔ ESP32 | RC vehicle real-time control |
The accelerometer continuously monitors vehicle dynamics. A low-pass gravity estimation filter runs every sample to cleanly isolate vertical shock from static gravity:
Raw Accelerometer Output (x, y, z)
│
▼ exponential low-pass (α = 0.1)
Gravity Vector Estimate [gx, gy, gz]
│
▼ vector subtraction
Dynamic Acceleration [ax, ay, az]
│
▼ dot product with gravity unit vector
Vertical Shock Magnitude (g-units)
│
▼ threshold comparison
Road Event Trigger ──► Pothole / Rough Road
Implemented: I²C init & WHO_AM_I validation · ODR & full-scale configuration · gravity estimation · low-pass filtering · vertical shock extraction · real-time interrupt processing
TIM5 hardware input capture measures the echo pulse duration to calculate chassis-to-road distance with microsecond precision:
STM32 GPIO Trigger ──► 10 μs pulse
│
▼
HC-SR04 emits ultrasonic burst
│
▼
Echo Pin HIGH
│ ◄─── TIM5 Capture (rising edge)
▼
Echo Pin LOW
│ ◄─── TIM5 Capture (falling edge)
│
▼
Δt = t_fall − t_rise
│
▼
Distance = (Δt × 343 m/s) / 2
Implemented: TIM5 input capture · rising & falling edge detection · hardware-timed pulse width measurement · non-blocking interrupt-driven acquisition
The GPS module streams NMEA 0183 sentences continuously. The firmware implements a ring-buffer producer–consumer architecture to parse GPS data without ever blocking the main control loop:
UART3 RX Interrupt ──► Ring Buffer (producer — ISR context)
│
▼
Main Loop polls (consumer)
│
▼
NMEA Sentence Reconstruction
│
▼
GPGGA Parser
│
▼
┌─────────────────┼──────────────────┐
▼ ▼ ▼
UTC Time Lat / Lon Altitude
Fix Quality Satellite Count
Implemented: UART interrupt handling · circular ring buffer · stream-based NMEA reconstruction · GPGGA sentence parsing · UTC time, lat/lon, altitude, fix quality, satellite count
The repository ships two STM32 firmware variants (HAL-based and bare-metal) alongside the ESP32 gateway sketch.
main.c ← System init, sensor loop, event classification, packet dispatch
├── LSM6DS3.c / .h ← I²C IMU driver — init, read, gravity filter, shock extraction
├── HC_SR04.c / .h ← TIM5 input-capture ultrasonic driver
├── NEO_6M.c / .h ← Interrupt-driven GPS UART + ring buffer + GPGGA parser
└── ESP32.c / .h ← UART telemetry framing & transmission to ESP32
main.c ← Bare-metal system init and application loop
├── lsm6ds3.c / .h ← Direct register-level IMU driver (no HAL)
├── hc-sr04.c / .h ← Register-level TIM5 driver
├── NEO_6M.c / .h ← Bare-metal UART + ring buffer
└── esp32_comms.c / .h ← Low-level UART telemetry TX
The bare-metal variant is provided as an educational reference demonstrating the same functionality at the register level, without relying on the STM32 HAL abstraction layer.
road_surface_monitor.ino
├── STM32 UART reception & packet parsing
├── Dynamic baseline tracking for ultrasonic depth calculation
├── Wi-Fi connection management with status logging
├── HTTP POST telemetry upload to backend API
└── BLE UART service for real-time RC vehicle control
The STM32 generates structured ASCII telemetry packets over UART. Two event types are defined:
| Event | Packet Format |
|---|---|
| Rough Road | R,<shock_g>,<latitude>,<longitude>,<utc_timestamp> |
| Pothole | P,<shock_g>,<distance_cm>,<latitude>,<longitude>,<utc_timestamp> |
Example packets:
R,1.82,12.971598,77.594562,134502.00
P,2.47,18.30,12.971598,77.594562,134512.00
The ESP32 parses these, enriches with device_id, and HTTP POSTs to the backend:
POST /api/ingest HTTP/1.1
Host: 10.x.x.x:8000
Content-Type: application/json
{
"device_id": "esp32-car-01",
"event": "pothole",
"shock": 2.47,
"distance": 18.30,
"lat": 12.971598,
"lon": 77.594562,
"timestamp": "134512.00"
}The Python backend (server.py) exposes a minimal REST API:
| Endpoint | Method | Description |
|---|---|---|
/api/ingest |
POST |
Receive & store telemetry from ESP32 |
/api/events |
GET |
Retrieve all logged road events |
/ |
GET |
Serve the web dashboard |
The frontend (index.html + app.js) renders all events on an interactive Leaflet.js map with color-coded markers and per-event metric cards:
| Marker | Event Type |
|---|---|
| 🔴 Red | Pothole — high-severity surface deviation (IMU + ultrasonic confirmed) |
| 🟠 Orange | Rough Road — vibration-based surface anomaly (IMU only) |
Stack: Python · Leaflet.js · Vanilla JS · CSS Custom Properties · Groq AI integration
road-condition-monitoring-system/
│
├── firmware-stm32-hal/ ← Primary STM32 firmware (STM32CubeIDE / HAL)
│ ├── Core/
│ │ ├── Src/ ← main.c, LSM6DS3.c, HC_SR04.c, NEO_6M.c, ESP32.c
│ │ └── Inc/ ← Header files for all modules
│ └── Drivers/ ← CMSIS + ST HAL drivers (auto-generated)
│
├── firmware-stm32-baremetal/ ← Register-level reference implementation
│ ├── Core/
│ │ ├── Src/ ← main.c, lsm6ds3.c, hc-sr04.c, NEO_6M.c, esp32_comms.c
│ │ └── Inc/
│ └── Drivers/
│
├── firmware-esp32/
│ └── road_surface_monitor.ino ← ESP32 Wi-Fi gateway + BLE RC control
│
├── web-dashboard/
│ ├── server.py ← Python backend REST API
│ ├── app.js ← Frontend map logic & live event rendering
│ ├── index.html ← Dashboard UI shell
│ ├── styles.css ← Dark-theme stylesheet
│ └── .env.example ← Environment variable template
│
├── model-design/
│ └── Front Leg.stl ← 3D-printable sensor mount (FDM-ready)
│
└── docs/
└── images/ ← ← ← Put all your README images here
├── banner.png
├── dashboard.png
├── dashboard-detail.gif
├── architecture.png
├── hardware.png
├── wiring.png
├── imu-signal.png
└── gps-track.png
- STM32CubeIDE — for STM32 firmware
- Arduino IDE with ESP32 board support
- Python 3.9+ — for the backend server
- ST-Link V2/V3 debugger — for flashing the STM32
# In STM32CubeIDE:
File → Import → General → Existing Projects into Workspace
# Choose one of:
# firmware-stm32-hal/ ← recommended (HAL-based)
# firmware-stm32-baremetal/ ← advanced (register-level)
# Build (Ctrl+B) then flash via Run → Debug (ST-Link)# Open in Arduino IDE:
firmware-esp32/road_surface_monitor.ino
# Edit the Wi-Fi & server credentials:
const char* WIFI_SSID = "your_ssid";
const char* WIFI_PASS = "your_password";
const char* SERVER_URL = "http://<your-server-ip>:8000/api/ingest";
# Board: ESP32S3 Dev Module
# Flash via Arduino IDE → Upload (Ctrl+U)cd web-dashboard
# Copy env template and add your API key
cp .env.example .env
# Edit .env: GROQ_API_KEY=your_key_here
# Install Python dependencies
pip install -r requirements.txt
# Start the server
python server.py
# Dashboard is live at:
# http://localhost:8000|
Adarsh Udupa
Firmware Lead & Embedded Integration STM32 system architecture · main.c integration ·
LSM6DS3 I²C driver · gravity estimation algorithm ·
vertical shock extraction · HC-SR04 timer input-capture driver ·
end-to-end subsystem coordination
|
Sumed Sreedhar
GPS Systems & Telemetry Architecture NEO-6M interrupt-driven UART driver · ring buffer architecture · NMEA sentence reconstruction · GPGGA parsing · STM32 ↔ ESP32 packet protocol design · ESP32 firmware · Wi-Fi telemetry pipeline |
|
Tanmay Tiwari
Backend & IoT Infrastructure Python REST API · database integration · telemetry ingestion pipeline · web dashboard (Leaflet.js) · data visualization · cloud communication architecture · Groq AI integration |
Pratham Banda
Mechanical Design & Hardware Integration RC vehicle chassis design · AutoCAD modelling · 3D-printed sensor mounts · TB6612FNG motor driver integration · power distribution · vehicle wiring & assembly · hardware-level system testing |
Click to expand the full list
Embedded Systems
- Bare-metal register-level peripheral programming
- STM32 HAL abstraction layer usage
- Interrupt-driven firmware architecture
- Timer input capture (TIM5)
- I²C peripheral integration
- UART multi-channel communication
- Non-blocking sensor acquisition
Signal Processing & Algorithms
- Low-pass gravity estimation filter
- Dynamic acceleration extraction via vector projection
- Threshold-based event detection
- Ring buffer / circular buffer implementation
- Producer–consumer data flow pattern
Communication & Networking
- Inter-MCU UART protocol design
- Structured telemetry packet framing
- NMEA 0183 GPS stream parsing
- Wi-Fi HTTP/REST client (ESP32)
- BLE UART service (ESP32 ↔ mobile)
Systems Design
- Distributed embedded processing architecture
- Multi-sensor data fusion fundamentals
- End-to-end embedded-to-cloud data pipeline
- Firmware modularization & driver abstraction
- IoT system integration
| Enhancement | Description |
|---|---|
| Coordinate Precision | GPS decimal-degree conversion & HDOP-based accuracy filtering |
| Local Logging | SD card buffering for offline operation in GPS/Wi-Fi dead zones |
| Adaptive Thresholds | Self-calibrating event detection that learns road baseline per session |
| Kalman Filtering | Optimal sensor fusion for improved vertical shock estimation |
| ML Classification | On-device or edge neural network for road condition categorization |
| Cloud Analytics | Historical data aggregation, heatmaps & trend dashboards |
| Mobile Companion App | Real-time monitoring + RC control in a single mobile app |
| V2X Integration | Vehicle-to-infrastructure telemetry broadcast protocol |
| Crowdsourced Mapping | Multi-device deployment feeding a shared city-wide road quality map |
Functional prototype — All subsystems integrated and field-tested.
| Subsystem | Status |
|---|---|
| LSM6DS3 IMU shock detection | Working |
| HC-SR04 ultrasonic ranging | Working |
| NEO-6M GPS acquisition | Working |
| STM32 ↔ ESP32 UART telemetry | Working |
| ESP32 Wi-Fi HTTP upload | Working |
| Python backend REST API | Working |
| Leaflet.js map dashboard | Working |
| BLE RC vehicle control | Working |
| 3D-printed sensor mount | Designed & printed |
| Bare-metal reference firmware | Complete |







