4.7 KiB
4.7 KiB
ESP32 Hacking Project
Overview
Firmware and tooling for ESP32 CSI (Channel State Information) sensors used for passive wireless sensing, device tracking, and security monitoring (OPSEC/OSINT/Purple team).
Goals
- Custom ESP32 firmware with remote management, OTA updates, adaptive sampling
- BLE scanning and WiFi probe/deauth detection for device intelligence
- CSI-based presence detection without cameras
- Flask REST API backend for data aggregation and OSINT queries
- Fleet management for multiple sensors
Components
| Component | Location | Description |
|---|---|---|
| Firmware | get-started/csi_recv_router/ |
ESP32 sensor firmware (C, ESP-IDF) |
| CLI Tools | ~/git/esp-tools/ |
esp-ctl, esp-fleet, esp-ota |
| Flask API | ~/git/esp32-web/ |
REST API backend (v0.1.5, Python, Flask) |
Current State
Firmware: v1.11.0 (+ unreleased v1.12 changes)
- 3x ESP32-DevKitC V1 deployed with custom firmware
- 31 UDP commands (ALERT, HELP, CONFIG, FACTORY, STATUS, PING, LOG, CSI, CALIBRATE, PRESENCE, ...)
- 28 NVS-persisted configuration keys
- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
- Remote management via UDP commands (port 5501)
- OTA firmware updates (HTTP/HTTPS) with rollback
- Presence detection via CSI baseline calibration
- Multi-channel scanning for broader WiFi coverage
- BLE fingerprinting (company_id, tx_power, flags)
- LED quiet mode (default off, solid on motion/presence)
Web Backend: v0.1.5
- Flask + SQLAlchemy + SQLite (WAL mode)
- UDP collector (all 5 sensor streams)
- REST API: sensors, devices, alerts, probes, events, stats, export, zones
- Intelligence dashboard: vendor treemap, SSID graph, fingerprint clusters, presence timeline
- 3D floorplan, OpenAPI/Swagger, 77 tests passing
Hardware
| Device | Chip | IP Address | Location |
|---|---|---|---|
| muddy-storm | ESP32-WROOM-32 | 192.168.129.29 | Living Room |
| amber-maple | ESP32-WROOM-32 | 192.168.129.30 | Office |
| hollow-acorn | ESP32-WROOM-32 | 192.168.129.31 | Kitchen |
Network Ports
| Port | Protocol | Direction | Description |
|---|---|---|---|
| 5500 | UDP | Sensors → Flask | Sensor data streams (CSI, BLE, probes, alerts, events) |
| 5500 | TCP | Clients → Flask | REST API (HTTP) |
| 5501 | UDP | Flask → Sensors | Sensor commands |
Data Streams (UDP 5500)
| Stream | Format | Use Case |
|---|---|---|
| CSI_DATA | hostname,count,mac,rssi,... | Motion/presence detection |
| BLE_DATA | hostname,mac,rssi,type,name,company_id,tx_power,flags | Device fingerprinting |
| PROBE_DATA | hostname,mac,rssi,ssid,channel | Device tracking, SSID enumeration |
| ALERT_DATA | hostname,type,source,target,rssi | Wireless IDS (deauth detection) |
| EVENT | hostname,key=value pairs | Motion, presence, calibration events |
Software Stack
| Component | Version | Purpose |
|---|---|---|
| ESP-IDF | v5.5.2 | Firmware development framework |
| Flask | 3.x | REST API backend |
| SQLAlchemy | 2.x | Database ORM |
| SQLite/PostgreSQL | - | Data storage |
| podman | - | Container runtime |
Key Paths
| Path | Description |
|---|---|
~/git/esp32-hacking/ |
This project (firmware sources, docs) |
~/git/esp32-web/ |
Flask API backend (v0.1.5) |
~/git/esp-tools/ |
CLI tools (esp-ctl, esp-fleet, esp-ota) |
~/esp/esp-idf/ |
ESP-IDF toolchain |
API Endpoints
Base URL: http://<host>:5500/api/v1
| Method | Endpoint | Description |
|---|---|---|
| GET | /sensors |
List sensors with status |
| GET | /sensors/<id> |
Sensor detail |
| GET | /sensors/<id>/config |
Sensor configuration |
| PUT | /sensors/<id>/config |
Update sensor config |
| POST | /sensors/<id>/command |
Send UDP command |
| POST | /sensors/<id>/ota |
Trigger OTA update |
| POST | /sensors/<id>/calibrate |
Trigger calibration |
| GET | /devices |
List discovered devices |
| GET | /devices/<id> |
Device detail |
| GET | /alerts |
Alert feed with filters |
| GET | /probes |
Probe requests |
| GET | /events |
Sensor events |
| GET | /stats |
Aggregate statistics |
| GET | /zones |
List zones |
| POST | /zones |
Create zone |
| PUT | /zones/<id> |
Update zone |
| GET | /export/devices.csv |
Export devices |
| GET | /intelligence/* |
Vendor treemap, SSID graph, fingerprints, presence |