esp32-hacking/PROJECT.md

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.10.3 (+ unreleased v1.11 changes)

• 3x ESP32-DevKitC V1 deployed with custom firmware
• 27 UDP commands (HELP, CONFIG, FACTORY, STATUS, CSI, CALIBRATE, PRESENCE, ...)
• 26 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

References

• ESP-IDF Docs
• ESP-CSI GitHub
• IEEE OUI Database
• Bluetooth Company Identifiers