docs: Add v2.0 Flask API backend roadmap

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

View File

@@ -2,15 +2,41 @@
**Last Updated:** 2026-02-05
## Current Sprint: v1.7+ — Presence Tuning & Integration
## Current Sprint: v2.0 — Flask API Backend
### P2 - Normal
### P0 - Critical (Phase 1: Project Setup)
- [ ] Create project scaffold `~/git/esp32-web/`
- [ ] Flask app factory pattern with Blueprints
- [ ] HTTP API on TCP 5500, UDP collector on UDP 5500
- [ ] SQLAlchemy models: Sensor, Device, Sighting, Alert, Event, Probe
- [ ] Containerfile for podman
- [ ] Makefile (build, run, dev, stop, logs)
- [ ] Basic pytest setup
### P1 - High (Phase 2: UDP Collector)
- [ ] UDP listener thread (parse CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT)
- [ ] Store parsed data to SQLite/PostgreSQL
- [ ] Sensor heartbeat tracking (mark online/offline)
- [ ] Integrate collector with Flask app lifecycle
### P1 - High (Phase 3: Core API)
- [ ] `GET /api/v1/sensors` — list sensors
- [ ] `GET /api/v1/devices` — list devices (BLE + WiFi MACs)
- [ ] `GET /api/v1/alerts` — alert feed with pagination
- [ ] `GET /api/v1/probes` — probe requests
- [ ] `GET /api/v1/events` — sensor events
- [ ] `POST /api/v1/sensors/<id>/command` — send command to sensor
### P2 - Normal (Phase 4: OSINT)
- [ ] MAC vendor lookup (OUI database)
- [ ] BLE company_id mapping
- [ ] `GET /api/v1/stats` — aggregate statistics
- [ ] Export endpoints (CSV, JSON)
### P2 - Normal (Backlog from v1.x)
- [ ] Tune presence threshold per room with real-world testing
- [x] Pi-side presence event handling in watch daemon
- [x] Firmware security audit (cppcheck + manual review — no issues found)
- [ ] Power consumption measurements using POWERTEST + external meter
- [ ] Test OTA rollback (flash bad firmware, verify auto-revert)
- [ ] Create HA webhook automations for deauth_flood / unknown_probe
### P3 - Low
- [ ] Deep sleep mode with wake-on-CSI-motion
@@ -19,6 +45,20 @@
- [ ] Document esp-radar console features
- [ ] Pin mapping for ESP32-DevKitC V1
## Completed: v1.9 - Multi-Channel Scanning & BLE Fingerprinting
- [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
## Completed: v1.8 - HTTPS OTA Support
- [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
## Completed: v1.7 - Baseline Calibration & Presence Detection
- [x] CALIBRATE command (capture N seconds of CSI, average per-subcarrier amplitudes)
@@ -172,7 +212,7 @@
## Notes
- Adaptive threshold varies by environment; 0.001-0.01 is a good starting range
- NVS keys: `send_rate`, `tx_power`, `adaptive`, `threshold`, `ble_scan`, `target_ip`, `target_port`, `hostname`, `boot_count`, `csi_mode`, `hybrid_n`, `auth_secret`, `flood_thresh`, `flood_window`, `scan_rate`, `probe_rate`, `powersave`, `presence`, `pr_thresh`, `bl_nsub`, `bl_amps`
- NVS keys (24 total): `send_rate`, `tx_power`, `adaptive`, `threshold`, `ble_scan`, `target_ip`, `target_port`, `hostname`, `boot_count`, `csi_mode`, `hybrid_n`, `auth_secret`, `flood_thresh`, `flood_window`, `scan_rate`, `probe_rate`, `powersave`, `presence`, `pr_thresh`, `bl_nsub`, `bl_amps`, `chanscan`, `chanscan_int`
- EVENT packets include sensor hostname: `EVENT,<hostname>,motion=... rate=... wander=...`
- ALERT_DATA format: `ALERT_DATA,<hostname>,<deauth|disassoc>,<sender_mac>,<target_mac>,<rssi>` or `ALERT_DATA,<hostname>,deauth_flood,<count>,<window_s>`
- STATUS fields: `uptime=`, `uptime_s=`, `heap=`, `rssi=`, `channel=`, `tx_power=`, `rate=`, `csi_rate=`, `hostname=`, `version=`, `adaptive=`, `motion=`, `ble=`, `target=`, `temp=`, `csi_count=`, `boots=`, `rssi_min=`, `rssi_max=`, `csi_mode=`, `hybrid_n=`, `auth=`, `flood_thresh=`, `powersave=`, `presence=`, `pr_score=`