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.

PROJECT.md

@@ -1,47 +1,97 @@
 # ESP32 Hacking Project
 
 ## Overview
-Firmware customization and experimentation for ESP32 CSI (Channel State Information) sensors used in the [wifi-sensing](~/git/wifi-sensing/) project.
+
+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
-- Document current firmware and configuration
-- Add remote management commands (reboot, identify, status)
-- Implement OTA firmware updates
-- Explore BLE scanning for complementary presence detection
-- Optimize CSI data pipeline (adaptive rate, on-device processing)
 
-## Current State
-- 3x ESP32-DevKitC V1 deployed with stock `csi_recv_router` firmware
-- Firmware sends raw CSI data via UDP at ~100 pkt/s per device
-- No remote management capability (must physically access USB)
+- 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 (Python, Flask) |
+
+## Current State (v1.9)
+
+- 3x ESP32-DevKitC V1 deployed with custom firmware
+- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
+- Remote management via UDP commands (port 5501)
+- OTA firmware updates (HTTP/HTTPS)
+- Presence detection via CSI baseline calibration
+- Multi-channel scanning for broader WiFi coverage
+- BLE fingerprinting (company_id, tx_power, flags)
 
 ## 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 | Development framework (`~/esp/esp-idf/`) |
-| esp-csi | latest | CSI extraction library |
-| FreeRTOS | (bundled) | RTOS kernel |
+| 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/wifi-sensing/` | Server application (receives CSI data) |
+| `~/git/esp32-web/` | Flask API backend (planned) |
+| `~/git/esp-tools/` | CLI tools (esp-ctl, esp-fleet, esp-ota) |
 | `~/esp/esp-idf/` | ESP-IDF toolchain |
-| `~/esp/esp-csi/` | Original esp-csi repo (build from here) |
 
-## Dependencies
-- ESP-IDF toolchain (`~/esp/esp-idf/`)
-- USB cable for initial flash (OTA planned)
+## API Endpoints (Planned)
+
+Base URL: `http://<host>:5500/api/v1`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/sensors` | List sensors with status |
+| GET | `/devices` | List discovered devices |
+| GET | `/alerts` | Alert feed with filters |
+| GET | `/probes` | Probe requests |
+| GET | `/events` | Sensor events |
+| POST | `/sensors/<id>/command` | Send command to sensor |
+| GET | `/stats` | Aggregate statistics |
 
 ## References
+
 - [ESP-IDF Docs](https://docs.espressif.com/projects/esp-idf/en/latest/)
 - [ESP-CSI GitHub](https://github.com/espressif/esp-csi)
-- [ESP32 WiFi CSI API](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html)
+- [IEEE OUI Database](https://standards-oui.ieee.org/)
+- [Bluetooth Company Identifiers](https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/)