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

feat: Add HELP, CONFIG, FACTORY commands; sync project docs

Browse Source 
Firmware: HELP lists all 27 commands with syntax, CONFIG dumps
running config as key=value, FACTORY erases NVS and reboots.

Docs: update PROJECT, ROADMAP, TASKS, TODO to reflect v1.10
completion, v1.11 unreleased work, and esp32-web v0.1.5 state.
Remove stale v2.0 Flask phase-by-phase plan (now tracked in
~/git/esp32-web/). Clean deferred items from completed milestones.
This commit is contained in:
user
2026-02-14 14:26:01 +01:00
parent aea0a06a5f
commit 468a97713c
5 changed files with 212 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
PROJECT.md
View File

@@ -18,17 +18,30 @@ Firmware and tooling for ESP32 CSI (Channel State Information) sensors used for
|-----------|----------|-------------| |-----------|----------|-------------|
| Firmware | `get-started/csi_recv_router/` | ESP32 sensor firmware (C, ESP-IDF) | | Firmware | `get-started/csi_recv_router/` | ESP32 sensor firmware (C, ESP-IDF) |
| CLI Tools | `~/git/esp-tools/` | `esp-ctl`, `esp-fleet`, `esp-ota` | | CLI Tools | `~/git/esp-tools/` | `esp-ctl`, `esp-fleet`, `esp-ota` |
| Flask API | `~/git/esp32-web/` | REST API backend (Python, Flask) | | Flask API | `~/git/esp32-web/` | REST API backend (v0.1.5, Python, Flask) |
## Current State (v1.9) ## Current State
### Firmware: v1.10.3 (+ unreleased v1.11 changes)
- 3x ESP32-DevKitC V1 deployed with custom firmware - 3x ESP32-DevKitC V1 deployed with custom firmware
- 27 UDP commands (HELP, CONFIG, FACTORY, STATUS, CSI, CALIBRATE, PRESENCE, ...)
- 26 NVS-persisted configuration keys
- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT - UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
- Remote management via UDP commands (port 5501) - Remote management via UDP commands (port 5501)
- OTA firmware updates (HTTP/HTTPS) - OTA firmware updates (HTTP/HTTPS) with rollback
- Presence detection via CSI baseline calibration - Presence detection via CSI baseline calibration
- Multi-channel scanning for broader WiFi coverage - Multi-channel scanning for broader WiFi coverage
- BLE fingerprinting (company_id, tx_power, flags) - BLE fingerprinting (company_id, tx_power, flags)
- LED quiet mode (default off, solid on motion/presence)
### Web Backend: v0.1.5
- Flask + SQLAlchemy + SQLite (WAL mode)
- UDP collector (all 5 sensor streams)
- REST API: sensors, devices, alerts, probes, events, stats, export, zones
- Intelligence dashboard: vendor treemap, SSID graph, fingerprint clusters, presence timeline
- 3D floorplan, OpenAPI/Swagger, 77 tests passing
## Hardware ## Hardware
@@ -71,23 +84,34 @@ Firmware and tooling for ESP32 CSI (Channel State Information) sensors used for
| Path | Description | | Path | Description |
|------|-------------| |------|-------------|
| `~/git/esp32-hacking/` | This project (firmware sources, docs) | | `~/git/esp32-hacking/` | This project (firmware sources, docs) |
| `~/git/esp32-web/` | Flask API backend (planned) | | `~/git/esp32-web/` | Flask API backend (v0.1.5) |
| `~/git/esp-tools/` | CLI tools (esp-ctl, esp-fleet, esp-ota) | | `~/git/esp-tools/` | CLI tools (esp-ctl, esp-fleet, esp-ota) |
| `~/esp/esp-idf/` | ESP-IDF toolchain | | `~/esp/esp-idf/` | ESP-IDF toolchain |
## API Endpoints (Planned) ## API Endpoints
Base URL: `http://<host>:5500/api/v1` Base URL: `http://<host>:5500/api/v1`
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| GET | `/sensors` | List sensors with status | | GET | `/sensors` | List sensors with status |
| GET | `/sensors/<id>` | Sensor detail |
| GET | `/sensors/<id>/config` | Sensor configuration |
| PUT | `/sensors/<id>/config` | Update sensor config |
| POST | `/sensors/<id>/command` | Send UDP command |
| POST | `/sensors/<id>/ota` | Trigger OTA update |
| POST | `/sensors/<id>/calibrate` | Trigger calibration |
| GET | `/devices` | List discovered devices | | GET | `/devices` | List discovered devices |
| GET | `/devices/<id>` | Device detail |
| GET | `/alerts` | Alert feed with filters | | GET | `/alerts` | Alert feed with filters |
| GET | `/probes` | Probe requests | | GET | `/probes` | Probe requests |
| GET | `/events` | Sensor events | | GET | `/events` | Sensor events |
| POST | `/sensors/<id>/command` | Send command to sensor |
| GET | `/stats` | Aggregate statistics | | GET | `/stats` | Aggregate statistics |
| GET | `/zones` | List zones |
| POST | `/zones` | Create zone |
| PUT | `/zones/<id>` | Update zone |
| GET | `/export/devices.csv` | Export devices |
| GET | `/intelligence/*` | Vendor treemap, SSID graph, fingerprints, presence |
## References ## References

81
ROADMAP.md
View File

@@ -98,10 +98,6 @@ Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — bre
- [x] Zone tracking with EMA RSSI (`esp-ctl osint zones`, `device_zones` table) - [x] Zone tracking with EMA RSSI (`esp-ctl osint zones`, `device_zones` table)
- [x] Per-sensor breakdown in MAC profile (`esp-ctl osint mac`) - [x] Per-sensor breakdown in MAC profile (`esp-ctl osint mac`)
- [x] POWERTEST command (7-phase power profiling with EVENT markers) - [x] POWERTEST command (7-phase power profiling with EVENT markers)
- [ ] Test OTA rollback (flash bad firmware, verify auto-revert)
- [ ] Create HA webhook automations for deauth_flood / unknown_probe
- [ ] Document esp-crab dual-antenna capabilities
- [ ] Document esp-radar console features
## v1.5 - Event Handling & NVS Persistence [DONE] ## v1.5 - Event Handling & NVS Persistence [DONE]
- [x] EVENT packet parsing in watch daemon (motion, wifi_reconnect, powertest) - [x] EVENT packet parsing in watch daemon (motion, wifi_reconnect, powertest)
@@ -116,9 +112,6 @@ Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — bre
- [x] POWERSAVE command (WiFi modem sleep toggle, NVS persisted, default off) - [x] POWERSAVE command (WiFi modem sleep toggle, NVS persisted, default off)
- [x] POWERTEST save/restore of powersave state - [x] POWERTEST save/restore of powersave state
- [x] sdkconfig: CONFIG_PM_ENABLE, CONFIG_FREERTOS_USE_TICKLESS_IDLE - [x] sdkconfig: CONFIG_PM_ENABLE, CONFIG_FREERTOS_USE_TICKLESS_IDLE
- [ ] Power consumption measurements using POWERTEST + external meter
- [ ] Deep sleep mode with wake-on-CSI-motion
- [ ] Battery-optimized duty cycling
## v1.7 - Baseline Calibration & Presence Detection [DONE] ## v1.7 - Baseline Calibration & Presence Detection [DONE]
- [x] CALIBRATE command (capture N seconds of CSI with room empty, average per-subcarrier amplitudes, store in NVS) - [x] CALIBRATE command (capture N seconds of CSI with room empty, average per-subcarrier amplitudes, store in NVS)
@@ -130,7 +123,6 @@ Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — bre
- [x] Calibration done event (`EVENT,<hostname>,calibrate=done packets=<n> nsub=<n>`) - [x] Calibration done event (`EVENT,<hostname>,calibrate=done packets=<n> nsub=<n>`)
- [x] presence= and pr_score= fields in STATUS reply - [x] presence= and pr_score= fields in STATUS reply
- [x] NVS persistence for baseline (bl_amps blob, bl_nsub) and presence config - [x] NVS persistence for baseline (bl_amps blob, bl_nsub) and presence config
- [ ] Tune presence threshold per room with real-world testing
## v1.8 - HTTPS OTA Support [DONE] ## v1.8 - HTTPS OTA Support [DONE]
- [x] Support HTTPS URLs for OTA updates (esp_https_ota) - [x] Support HTTPS URLs for OTA updates (esp_https_ota)
@@ -144,62 +136,33 @@ Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — bre
- [x] BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA - [x] BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA
- [x] Historical presence sessions support - [x] Historical presence sessions support
## v2.0 - Flask API Backend (Purple Team) ## v1.10 - LED Quiet Mode & CI Hardening [DONE]
- [x] LED quiet mode (off normally, solid on motion/presence, blinks on OTA)
- [x] Default LED to quiet mode
- [x] Build metadata in STATUS (date, time, IDF version, chip info)
- [x] CI security checks (secrets scan, config validation, size check)
- [x] Size optimization (`-Os`, saves ~75KB vs -O2)
- [x] CSI ON/OFF toggle command (NVS persisted)
REST API backend for OPSEC/OSINT/Purple team operations using ESP32 sensor fleet. ## v1.11 - Diagnostics & Usability (unreleased)
API-first design; frontend dashboard deferred to v2.1+. - [x] HELP command (lists all commands with syntax)
- [x] CONFIG command (dump all running config key=value)
- [x] FACTORY command (erase NVS config + reboot)
- [ ] Tag and OTA deploy to fleet
- **HTTP API:** TCP 5500 ## v1.12 - Firmware Polish
- **UDP Collector:** UDP 5500 (sensor data) - [ ] PING command (echo reply for connectivity tests)
- **Sensor Commands:** UDP 5501 (outbound) - [ ] LOG command (runtime log level control)
- [ ] Multi-target (send data to 2+ UDP destinations)
- [ ] Temp/heap alert thresholds (EVENT on overheat or low memory)
- [ ] OTA rollback validation test
### Phase 1: Project Setup ## Web Backend (`~/git/esp32-web/`)
- [ ] 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 Tracked in its own repository. See `~/git/esp32-web/ROADMAP.md`.
- [ ] 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 Current: v0.1.5 (zones, intelligence dashboard, fleet management, 77 tests).
- [ ] `GET /api/v1/sensors` — list sensors with status, uptime, last_seen Next: v0.1.6 (auth, rate limiting, production deployment).
- [ ] `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) ## v3.0 - Hardware Upgrade (ESP32-S3/C6)

66
TASKS.md
View File

@@ -1,50 +1,53 @@
# ESP32 Hacking Tasks # ESP32 Hacking Tasks
**Last Updated:** 2026-02-05 **Last Updated:** 2026-02-14
## Current Sprint: v2.0 — Flask API Backend ## Firmware: Unreleased (v1.11 candidates)
### P0 - Critical (Phase 1: Project Setup) - [x] CSI ON/OFF command to toggle CSI collection
- [ ] Create project scaffold `~/git/esp32-web/` - [x] HELP command (lists all 23 commands with syntax)
- [ ] Flask app factory pattern with Blueprints - [x] FACTORY command (erase NVS config + reboot)
- [ ] HTTP API on TCP 5500, UDP collector on UDP 5500 - [x] CONFIG command (dump all running config key=value)
- [ ] SQLAlchemy models: Sensor, Device, Sighting, Alert, Event, Probe - [ ] Tag and OTA deploy to fleet
- [ ] Containerfile for podman
- [ ] Makefile (build, run, dev, stop, logs)
- [ ] Basic pytest setup
### P1 - High (Phase 2: UDP Collector) ## Web Backend (`~/git/esp32-web/`)
- [ ] 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) Tracked separately in `~/git/esp32-web/TASKS.md`. Currently at v0.1.5.
- [ ] `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) ## Firmware Backlog
- [ ] 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) ### P1 - High
- [ ] Test OTA rollback (flash bad firmware, verify auto-revert)
### P2 - Normal
- [ ] Tune presence threshold per room with real-world testing - [ ] Tune presence threshold per room with real-world testing
- [ ] Power consumption measurements using POWERTEST + external meter - [ ] Power consumption measurements using POWERTEST + external meter
- [ ] Test OTA rollback (flash bad firmware, verify auto-revert) - [ ] PING command (echo reply for connectivity tests)
- [ ] LOG command (runtime `esp_log_level_set()`)
- [ ] Multi-target (send UDP to 2+ destinations)
### P3 - Low ### P3 - Low
- [ ] Deep sleep mode with wake-on-CSI-motion - [ ] Deep sleep mode with wake-on-CSI-motion
- [ ] Battery-optimized duty cycling - [ ] Battery-optimized duty cycling
- [ ] Temp/heap alert thresholds (EVENT on overheat or low memory)
- [ ] RSSI RESET command (reset min/max counters)
- [ ] AP+STA config portal (captive portal for initial setup)
### Documentation
- [ ] Document esp-crab dual-antenna capabilities - [ ] Document esp-crab dual-antenna capabilities
- [ ] Document esp-radar console features - [ ] Document esp-radar console features
- [ ] Pin mapping for ESP32-DevKitC V1 - [ ] Pin mapping for ESP32-DevKitC V1
## Completed: v1.10 - LED Quiet Mode & CI Hardening
- [x] LED quiet mode (off normally, solid on motion/presence, blinks on OTA)
- [x] Default LED to quiet mode
- [x] Build metadata in STATUS reply
- [x] CI security checks (secrets scan, config validation)
- [x] Firmware size check and version tag validation
- [x] Size optimization (`-Os`, saves ~75KB)
- [x] CSI ON/OFF toggle command
## Completed: v1.9 - Multi-Channel Scanning & BLE Fingerprinting ## Completed: v1.9 - Multi-Channel Scanning & BLE Fingerprinting
- [x] CHANSCAN command (ON/OFF/NOW/INTERVAL) - [x] CHANSCAN command (ON/OFF/NOW/INTERVAL)
@@ -212,10 +215,11 @@
## Notes ## Notes
- Adaptive threshold varies by environment; 0.001-0.01 is a good starting range - Adaptive threshold varies by environment; 0.001-0.01 is a good starting range
- 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` - NVS keys (26 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`, `led_quiet`, `csi_enabled`
- UDP commands (23 total): STATUS, CONFIG, RATE, POWER, TARGET, HOSTNAME, CSI, CSIMODE, ADAPTIVE, THRESHOLD, BLE, SCANRATE, PROBERATE, CALIBRATE, PRESENCE, CHANSCAN, LED, POWERSAVE, AUTH, FLOODTHRESH, OTA, POWERTEST, PROFILE, IDENTIFY, REBOOT, FACTORY, HELP
- EVENT packets include sensor hostname: `EVENT,<hostname>,motion=... rate=... wander=...` - 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>` - 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=` - 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=`, `csi_mode=`, `hybrid_n=`, `auth=`, `flood_thresh=`, `powersave=`, `presence=`, `pr_score=`, `chanscan=`, `led=`, `nvs_used=`, `nvs_free=`, `nvs_total=`, `part_size=`, `built=`, `idf=`, `chip=`
- PROBE_DATA format: `PROBE_DATA,<hostname>,<mac>,<rssi>,<ssid>` - PROBE_DATA format: `PROBE_DATA,<hostname>,<mac>,<rssi>,<ssid>`
- Probe requests deduped per MAC (default 10s cooldown, tunable via PROBERATE) - Probe requests deduped per MAC (default 10s cooldown, tunable via PROBERATE)
- mDNS service: `_esp-csi._udp` on data port (for sensor discovery) - mDNS service: `_esp-csi._udp` on data port (for sensor discovery)

79
TODO.md
View File

@@ -1,72 +1,38 @@
# ESP32 Hacking TODO # 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 ## Firmware
### Commands
- [ ] PING command (echo reply for connectivity tests)
- [ ] LOG command (runtime `esp_log_level_set()` control)
- [ ] RSSI RESET command (reset min/max counters)
### Features
- [ ] Multi-target (send UDP data to 2+ destinations simultaneously)
- [ ] Temp/heap alert thresholds (emit EVENT on overheat or low memory)
- [ ] Deep sleep mode with wake-on-CSI-motion - [ ] Deep sleep mode with wake-on-CSI-motion
- [ ] Battery-optimized duty cycling - [ ] Battery-optimized duty cycling
- [ ] AP+STA config portal (captive portal for initial setup) - [ ] AP+STA config portal (captive portal for initial setup)
### Testing
- [ ] OTA rollback validation (flash bad firmware, verify auto-revert)
- [ ] Tune presence threshold per room with real-world testing
- [ ] Power consumption measurements (per-mode: idle, CSI, BLE, probe)
- [ ] Benchmark: CSI callback latency
- [ ] Benchmark: UDP throughput at different rates
### Documentation
- [ ] Document esp-crab dual-antenna capabilities
- [ ] Document esp-radar console features
- [ ] Pin mapping for ESP32-DevKitC V1
- [ ] Compare CSI quality: passive (router) vs active (ESP-NOW)
- [ ] Multi-sensor deployment guide (placement, zones, triangulation)
## Tools (esp-ctl) ## Tools (esp-ctl)
- [ ] Migrate OSINT database to Flask API (esp-ctl becomes thin client) - [ ] Migrate OSINT database to Flask API (esp-ctl becomes thin client)
- [ ] `esp-ctl api` subcommand (query Flask API) - [ ] `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 ## Ideas
- ESP-NOW mesh for direct ESP32-to-ESP32 CSI - ESP-NOW mesh for direct ESP32-to-ESP32 CSI
@@ -76,4 +42,3 @@
- Grafana dashboards for long-term analytics - Grafana dashboards for long-term analytics
- ML-based device classification (phone vs laptop vs IoT) - ML-based device classification (phone vs laptop vs IoT)
- Webhook callbacks for alerts (Slack, Discord, ntfy) - Webhook callbacks for alerts (Slack, Discord, ntfy)
- Rate limiting and API authentication (JWT)

103
get-started/csi_recv_router/main/app_main.c
View File

@@ -2157,6 +2157,109 @@ static int cmd_handle(const char *cmd, char *reply, size_t reply_size)
return strlen(reply); return strlen(reply);
} }
/* HELP */
if (strcmp(cmd, "HELP") == 0) {
int pos = 0;
pos += snprintf(reply + pos, reply_size - pos,
"OK HELP\n"
"STATUS — sensor status\n"
"CONFIG — dump all NVS settings\n"
"RATE <10-100> — set CSI ping rate (Hz)\n"
"POWER <2-20> — set TX power (dBm)\n"
"TARGET <ip> [port] — set data destination\n"
"HOSTNAME [name] — get/set hostname\n"
"CSI [ON|OFF] — toggle CSI collection\n"
"CSIMODE [RAW|COMPACT|HYBRID N] — CSI output mode\n"
"ADAPTIVE [ON|OFF] — adaptive sampling\n"
"THRESHOLD <0-1> — motion threshold\n"
"BLE [ON|OFF] — BLE scanning\n"
"SCANRATE <5-300> — BLE scan interval (s)\n"
"PROBERATE <1-300> — probe dedup cooldown (s)\n"
"CALIBRATE [STATUS|CLEAR|N] — baseline calibration\n"
"PRESENCE [ON|OFF|THRESHOLD] — presence detection\n"
"CHANSCAN [ON|OFF|NOW|INTERVAL] — channel scanning\n"
"LED [QUIET|AUTO] — LED mode\n"
"POWERSAVE [ON|OFF] — WiFi modem sleep\n"
"AUTH [secret|OFF] — HMAC authentication\n"
"FLOODTHRESH <n> [win] — deauth flood threshold\n"
"OTA <url> — firmware update\n"
"POWERTEST [dwell] — power profiling\n"
"PROFILE — heap/stack/CPU stats\n"
"IDENTIFY — LED solid 5s\n"
"REBOOT — restart sensor\n"
"FACTORY — erase config, reboot\n"
"HELP — this message");
return pos;
}
/* FACTORY — erase all NVS config and reboot */
if (strcmp(cmd, "FACTORY") == 0) {
snprintf(reply, reply_size, "OK FACTORY erasing config and rebooting");
/* Send reply before erasing */
nvs_handle_t fh;
if (nvs_open("csi_config", NVS_READWRITE, &fh) == ESP_OK) {
nvs_erase_all(fh);
nvs_commit(fh);
nvs_close(fh);
}
xTaskCreate(reboot_after_delay, "reboot", 1024, NULL, 1, NULL);
return strlen(reply);
}
/* CONFIG — dump all NVS settings */
if (strcmp(cmd, "CONFIG") == 0) {
const char *csi_mode_str = (s_csi_mode == CSI_MODE_COMPACT) ? "compact" :
(s_csi_mode == CSI_MODE_HYBRID) ? "hybrid" : "raw";
int pos = 0;
pos += snprintf(reply + pos, reply_size - pos,
"OK CONFIG\n"
"hostname=%s\n"
"send_rate=%d\n"
"tx_power=%d\n"
"target=%s:%d\n"
"csi=%s\n"
"csi_mode=%s\n"
"hybrid_n=%d\n"
"adaptive=%s\n"
"threshold=%.6f\n"
"ble=%s\n"
"scan_rate=%ds\n"
"probe_rate=%ds\n"
"presence=%s\n"
"pr_thresh=%.4f\n"
"baseline_nsub=%d\n"
"chanscan=%s\n"
"chanscan_int=%ds\n"
"led=%s\n"
"powersave=%s\n"
"auth=%s\n"
"flood_thresh=%d/%ds\n"
"boots=%lu",
s_hostname,
s_send_frequency,
(int)s_tx_power_dbm,
s_target_ip, s_target_port,
s_csi_enabled ? "on" : "off",
csi_mode_str,
s_hybrid_interval,
s_adaptive ? "on" : "off",
s_motion_threshold,
s_ble_enabled ? "on" : "off",
(int)(s_ble_scan_interval_us / 1000000LL),
(int)(s_probe_dedup_us / 1000000LL),
s_presence_enabled ? "on" : "off",
s_pr_threshold,
s_baseline_nsub,
s_chanscan_enabled ? "on" : "off",
s_chanscan_interval_s,
s_led_quiet ? "quiet" : "auto",
s_powersave ? "on" : "off",
s_auth_secret[0] ? "on" : "off",
s_flood_thresh, s_flood_window_s,
(unsigned long)s_boot_count);
return pos;
}
snprintf(reply, reply_size, "ERR UNKNOWN"); snprintf(reply, reply_size, "ERR UNKNOWN");
return strlen(reply); return strlen(reply);
} }