# ESP32 Hacking TODO

## Flask API (`~/git/esp32-web/`)

### Architecture
- [ ] App factory pattern (`create_app()`)
- [ ] Blueprints: `api`, `collector`
- [ ] SQLAlchemy with migrations (Flask-Migrate)
- [ ] Background UDP collector (threading or Celery)
- [ ] Config from environment variables
- [ ] Port 5500: HTTP API (TCP) + UDP collector (UDP) on same port number

### Database Schema
- [ ] `sensors` — id, hostname, ip, last_seen, status, config_json
- [ ] `devices` — mac, type (ble/wifi), vendor, first_seen, last_seen
- [ ] `sightings` — device_id, sensor_id, rssi, timestamp
- [ ] `alerts` — sensor_id, type, source_mac, target_mac, rssi, timestamp
- [ ] `probes` — device_id, sensor_id, ssid, rssi, channel, timestamp
- [ ] `events` — sensor_id, event_type, payload_json, timestamp

### API Endpoints
- [ ] Sensors: list, detail, status, command, config, history
- [ ] Devices: list, detail, profile, sightings
- [ ] Alerts: list with filters (type, sensor, time range)
- [ ] Probes: list, group by SSID, group by MAC
- [ ] Events: list with filters
- [ ] Stats: counts, activity graphs data
- [ ] Export: CSV, JSON for devices/alerts/probes

### UDP Collector
- [ ] Parse CSI_DATA (hostname, count, mac, rssi, features)
- [ ] Parse BLE_DATA (hostname, mac, rssi, type, name, company_id, tx_power, flags)
- [ ] Parse PROBE_DATA (hostname, mac, rssi, ssid, channel)
- [ ] Parse ALERT_DATA (hostname, type, source, target, rssi OR flood count)
- [ ] Parse EVENT (hostname, key=value pairs)
- [ ] Heartbeat timeout detection (mark sensor offline)

### OSINT
- [ ] IEEE OUI database (download + parse)
- [ ] BLE company ID database (Bluetooth SIG)
- [ ] Device fingerprinting by BLE advertisement patterns
- [ ] Probe request SSID profiling (home networks, corporate, etc.)

## Firmware

- [ ] Deep sleep mode with wake-on-CSI-motion
- [ ] Battery-optimized duty cycling
- [ ] AP+STA config portal (captive portal for initial setup)

## Tools (esp-ctl)

- [ ] Migrate OSINT database to Flask API (esp-ctl becomes thin client)
- [ ] `esp-ctl api` subcommand (query Flask API)

## Testing

- [ ] Benchmark: CSI callback latency
- [ ] Benchmark: UDP throughput at different rates
- [ ] Power consumption measurements (per-mode: idle, CSI, BLE, probe)
- [ ] API load testing (concurrent requests)

## Documentation

- [ ] Flask API: OpenAPI/Swagger spec
- [ ] Deployment guide (podman, systemd)
- [ ] Pin mapping for ESP32-DevKitC V1
- [ ] Compare CSI quality: passive (router) vs active (ESP-NOW)
- [ ] Multi-sensor deployment guide (placement, zones, triangulation)

## Ideas

- ESP-NOW mesh for direct ESP32-to-ESP32 CSI
- External PIR sensor for CSI ground truth validation
- RSSI triangulation with 3+ sensors (approximate device location)
- Home Assistant MQTT discovery integration
- Grafana dashboards for long-term analytics
- ML-based device classification (phone vs laptop vs IoT)
- Webhook callbacks for alerts (Slack, Discord, ntfy)
- Rate limiting and API authentication (JWT)