username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
1377abe24847fe87fccba1bb2b6c3354e9b85430
esp32-hacking/TODO.md
user f87ddec742 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.
2026-02-05 20:41:24 +01:00

2.9 KiB
Raw Blame History

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)
Reference in New Issue View Git Blame Copy Permalink