username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: Add v2.0 Flask API backend roadmap

Browse Source 
Plan for REST API backend (purple team/OPSEC/OSINT):
- Phase 1: Project scaffold, SQLAlchemy models, podman
- Phase 2: UDP collector for sensor data streams
- Phase 3: Core API endpoints (sensors, devices, alerts, probes, events)
- Phase 4: OSINT features (OUI lookup, BLE company ID mapping)
- Phase 5: Fleet management API

Port allocation:
- TCP 5500: HTTP REST API
- UDP 5500: Sensor data collector
- UDP 5501: Sensor commands (outbound)

Also documents completed v1.8 (HTTPS OTA) and v1.9 (multi-channel
scanning, BLE fingerprinting) milestones.
This commit is contained in:
user
2026-02-05 20:41:24 +01:00
parent d58b6dd814
commit f87ddec742
4 changed files with 247 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
ROADMAP.md
View File

@@ -131,9 +131,77 @@ Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — bre
- [x] presence= and pr_score= fields in STATUS reply
- [x] NVS persistence for baseline (bl_amps blob, bl_nsub) and presence config
- [ ] Tune presence threshold per room with real-world testing
- [ ] Pi-side presence event handling in watch daemon
## v2.0 - Hardware Upgrade (ESP32-S3/C6)
## v1.8 - HTTPS OTA Support [DONE]
- [x] Support HTTPS URLs for OTA updates (esp_https_ota)
- [x] CI: Upload firmware to Gitea releases for OTA
- [x] CI: Simplify deploy script to pure POSIX sh
## v1.9 - Multi-Channel Scanning & BLE Fingerprinting [DONE]
- [x] CHANSCAN command (ON/OFF/NOW/INTERVAL)
- [x] Channel hopping (1-13) with 100ms dwell, pause CSI during scan
- [x] chanscan= field in STATUS, chanscan_int NVS persistence
- [x] BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA
- [x] Historical presence sessions support
## v2.0 - Flask API Backend (Purple Team)
REST API backend for OPSEC/OSINT/Purple team operations using ESP32 sensor fleet.
API-first design; frontend dashboard deferred to v2.1+.
- **HTTP API:** TCP 5500
- **UDP Collector:** UDP 5500 (sensor data)
- **Sensor Commands:** UDP 5501 (outbound)
### Phase 1: Project Setup
- [ ] Project scaffold (`~/git/esp32-web/`) with Flask + SQLAlchemy + Blueprints
- [ ] Database schema: sensors, devices, sightings, alerts, events, probes
- [ ] Containerfile for podman deployment
- [ ] Makefile (build, run, dev, stop, logs)
- [ ] pytest setup with fixtures
### Phase 2: UDP Collector
- [ ] Async UDP listener daemon (threading or asyncio)
- [ ] Parse all sensor streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
- [ ] Store to database with timestamps
- [ ] Sensor heartbeat tracking (online/offline status)
- [ ] Run as background thread alongside Flask
### Phase 3: Core API Endpoints
- [ ] `GET /api/v1/sensors` — list sensors with status, uptime, last_seen
- [ ] `GET /api/v1/sensors/<id>/status` — detailed sensor info
- [ ] `POST /api/v1/sensors/<id>/command` — send UDP command (proxy)
- [ ] `GET /api/v1/devices` — list all discovered devices (BLE + WiFi)
- [ ] `GET /api/v1/devices/<mac>` — device profile (sightings, zones, vendor)
- [ ] `GET /api/v1/alerts` — alert feed with pagination + filters
- [ ] `GET /api/v1/probes` — probe requests with SSID enumeration
- [ ] `GET /api/v1/events` — sensor events (motion, presence, calibration)
### Phase 4: OSINT Features
- [ ] MAC vendor lookup (IEEE OUI database)
- [ ] BLE company_id to manufacturer mapping
- [ ] `GET /api/v1/devices/<mac>/profile` — enriched device intel
- [ ] `GET /api/v1/stats` — aggregate statistics (device counts, alert counts)
- [ ] Export endpoints: `GET /api/v1/export/devices.csv`, `.json`
### Phase 5: Fleet Management API
- [ ] `GET /api/v1/sensors/<id>/config` — current sensor configuration
- [ ] `PUT /api/v1/sensors/<id>/config` — update sensor settings
- [ ] `POST /api/v1/sensors/<id>/ota` — trigger OTA update
- [ ] `POST /api/v1/sensors/<id>/calibrate` — trigger baseline calibration
- [ ] `GET /api/v1/sensors/<id>/history` — historical metrics
## v2.1 - Web Dashboard (Future)
Frontend dashboard using htmx + Pico CSS, built on top of v2.0 API.
- [ ] Live sensor status dashboard
- [ ] Device inventory table with search/filter
- [ ] Alert timeline with severity badges
- [ ] Presence heatmap per zone
- [ ] Sensor fleet management UI
## v3.0 - Hardware Upgrade (ESP32-S3/C6)
Requires replacing current ESP32 (original) DevKitC V1 boards with ESP32-S3
or ESP32-C6 modules. The original ESP32 lacks FTM and has CSI/promiscuous
@@ -152,10 +220,11 @@ mode conflicts.
## Future
- AP+STA config portal (WIFI_MODE_APSTA, captive portal for initial setup)
- ESP-NOW mesh (ESP32-to-ESP32 CSI)
- Multi-channel scanning (hop across WiFi channels)
- BLE device fingerprinting (identify phone models by advertisement patterns)
- Historical presence logging (who was here, when, how long)
- External sensor support (PIR, temp/humidity via GPIO)
- Pin mapping for ESP32-DevKitC V1
- Compare CSI quality: passive (router) vs active (ESP-NOW)
- Multi-sensor deployment guide (placement, zones, triangulation)
- Home Assistant integration (MQTT discovery, entity creation)
- Grafana dashboards for long-term analytics
- ML-based device classification (phone vs laptop vs IoT)
- RSSI triangulation with 3+ sensors (approximate device location)