username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
c76c1ee61b07a40477295b5d1b935649003eaa71
esp32-hacking/ROADMAP.md
user c76c1ee61b
Some checks failed
Lint & Build / Security Flaw Analysis (push) Successful in 15s
Details
Lint & Build / Secret Scanning (push) Successful in 5s
Details
Lint & Build / C/C++ Static Analysis (push) Failing after 34s
Details
Lint & Build / Build Firmware (push) Has been skipped
Details
feat: OTA TLS cert verification + CI release pipeline 
Wire ESP-IDF's built-in 150-CA root bundle to the OTA HTTP client
so HTTPS OTA verifies server certificates. Pin bundle config in
sdkconfig.defaults. Replace dead artifact-copy step with Gitea
release creation on tag push. Bump CI container to IDF v5.5.
2026-02-14 22:38:41 +01:00

11 KiB
Raw Blame History

ESP32 Hacking Roadmap

v0.1 - Documentation & Setup [DONE]

  • Copy firmware sources from esp-csi
  • Document current firmware behavior
  • Document CSI data format
  • Document build & flash process
  • List firmware modification ideas with priorities
  • Verify build from repo (ESP-IDF v5.5.2, aarch64)

v0.2 - Remote Management [DONE]

  • Add UDP command listener on ESP32 (port 5501)
  • Implement REBOOT command
  • Implement IDENTIFY command (LED solid 5s)
  • Implement STATUS command (uptime, heap, RSSI, tx_power, rate, version)
  • Implement RATE command (change ping Hz, NVS persist)
  • Implement POWER command (TX power dBm, NVS persist)
  • Add LED status indicator (off/slow blink/fast blink/solid)
  • NVS persistence for rate and tx_power settings
  • Pi-side esp-cmd and esp-fleet CLI tools
  • mDNS hostname, watchdog, human-readable uptime
  • Build and flash to device
  • Update CHEATSHEET.md with new commands

v0.3 - OTA Updates [DONE]

  • Dual OTA partition table (ota_0 + ota_1, 1920 KB each)
  • 4MB flash config, custom partitions in sdkconfig.defaults
  • OTA command handler + ota_task in firmware
  • LED_OTA double-blink pattern during download
  • Bootloader rollback on failed update (30s watchdog)
  • Version field in STATUS reply
  • Pi-side esp-ota tool (HTTP server + OTA orchestration)
  • esp-fleet ota subcommand (sequential fleet update)
  • USB-flash first device (partition table change)
  • End-to-end OTA test

v0.4 - Adaptive Sampling [DONE]

  • On-device CSI wander calculation (coefficient of variation)
  • Reduce to 10 pkt/s when idle (3s holdoff)
  • Increase to 100 pkt/s on motion detection
  • Rate change EVENT notification to Pi via UDP
  • ADAPTIVE ON/OFF command (NVS persisted)
  • THRESHOLD command for tuning sensitivity (NVS persisted)
  • RATE command disables adaptive mode
  • adaptive/motion fields in STATUS reply

v0.5 - BLE Scanning [DONE]

  • Enable Bluetooth alongside WiFi (NimBLE, BLE ON/OFF command)
  • Periodic BLE advertisement scanning
  • Report device MAC, RSSI, name via UDP (BLE_DATA,<mac>,<rssi>,<type>,<name>)
  • Pi-side BLE device tracking (esp-ctl ble --track, dedup, summary table)

v1.0 - Production Firmware [DONE]

  • mDNS auto-discovery
  • Watchdog + auto-recovery
  • Configuration via UDP (TARGET <ip> [port], NVS persisted)
  • Comprehensive error handling (watchdog, WiFi reconnect via example_connect)
  • esp-ctl unified CLI tool (cmd, status, listen, serial, ble, target, profile)
  • PROFILE command (heap, stack watermarks, CPU runtime stats)

v1.1 - Passive Sensing & Multi-Sensor [DONE]

  • Sensor ID in data packets (hostname prefix on CSI_DATA, BLE_DATA, EVENT)
  • WiFi probe request capture (PROBE_DATA,<sensor>,<mac>,<rssi>,<ssid>, 10s dedup)
  • Deauth/disassoc frame detection (ALERT_DATA,<sensor>,<type>,<sender>,<target>,<rssi>)
  • BLE alerting (esp-ctl ble --known, alert on unknown MACs)
  • BLE dwell time tracking (esp-ctl ble --track dwell column)
  • Timestamped event logging (esp-ctl listen --timestamp)
  • Runtime HOSTNAME command (NVS persisted, mDNS updated)
  • mDNS service advertisement (_esp-csi._udp) + discovery (esp-ctl discover)
  • SCANRATE / PROBERATE tuning commands (NVS persisted)
  • Chip temperature reporting in STATUS (temp= field)
  • Channel, boot count, RSSI min/max, actual CSI rate in STATUS
  • FreeRTOS CPU runtime stats in PROFILE

Note: Promiscuous mode (probe/deauth capture) disabled on original ESP32 — breaks CSI callback. Works on ESP32-C6+.

v1.2 - On-Device CSI Processing [DONE]

  • On-device feature extraction (amp_rms, amp_std, amp_max, amp_max_idx, energy)
  • CSIMODE command: RAW, COMPACT, HYBRID N (NVS persisted)
  • Compact payload format (F:rms,std,max,idx,energy — ~80% bandwidth reduction)
  • Hybrid mode: compact every packet, raw every Nth
  • Adaptive sampling reuses extracted energy (no duplicate computation)

v1.3 - Security & OSINT [DONE]

  • HMAC-SHA256 command authentication (firmware + esp-ctl/esp-cmd/esp-fleet/esp-ota)
  • AUTH command (set/query/disable secret, NVS persisted)
  • Deauth flood detection (ring buffer, aggregate ALERT_DATA)
  • FLOODTHRESH command (count + window, NVS persisted)
  • MAC OUI vendor lookup (esp-ctl oui, IEEE CSV database)
  • OSINT SQLite database (probe_ssids, device_sightings tables)
  • Watch daemon (esp-ctl watch — listen + enrich + store)
  • OSINT query CLI (esp-ctl osint probes/devices/mac/stats)
  • Home Assistant webhook integration (deauth_flood, unknown_probe, unknown_ble)
  • Parallel OTA fleet updates (esp-fleet ota --parallel)

v1.4 - Multi-Sensor & Validation [DONE]

  • Multi-sensor BLE correlation in esp-ctl (zone tracking by source sensor)
  • Zone tracking with EMA RSSI (esp-ctl osint zones, device_zones table)
  • Per-sensor breakdown in MAC profile (esp-ctl osint mac)
  • POWERTEST command (7-phase power profiling with EVENT markers)

v1.5 - Event Handling & NVS Persistence [DONE]

  • EVENT packet parsing in watch daemon (motion, wifi_reconnect, powertest)
  • Sensor heartbeat tracking (offline/online detection, configurable timeout)
  • sensor_events table with indexed queries (esp-ctl osint events)
  • HA webhooks for sensor_offline, sensor_online, motion_change
  • NVS persistence for SCANRATE and PROBERATE commands
  • Sensor events count in esp-ctl osint stats

v1.6 - Power Management [DONE]

  • ESP-IDF power management framework (DFS 240/80 MHz + light sleep)
  • POWERSAVE command (WiFi modem sleep toggle, NVS persisted, default off)
  • POWERTEST save/restore of powersave state
  • sdkconfig: CONFIG_PM_ENABLE, CONFIG_FREERTOS_USE_TICKLESS_IDLE

v1.7 - Baseline Calibration & Presence Detection [DONE]

  • CALIBRATE command (capture N seconds of CSI with room empty, average per-subcarrier amplitudes, store in NVS)
  • CALIBRATE STATUS / CALIBRATE CLEAR subcommands
  • Presence scoring (normalized Euclidean distance of live CSI vs baseline, rolling window)
  • PRESENCE ON/OFF command (NVS persisted, requires valid baseline)
  • PRESENCE THRESHOLD command (tunable 0.001-1.0, NVS persisted)
  • Presence events (EVENT,<hostname>,presence=<0|1> score=<float>) with 10s holdoff
  • Calibration done event (EVENT,<hostname>,calibrate=done packets=<n> nsub=<n>)
  • presence= and pr_score= fields in STATUS reply
  • NVS persistence for baseline (bl_amps blob, bl_nsub) and presence config

v1.8 - HTTPS OTA Support [DONE]

  • Support HTTPS URLs for OTA updates (esp_https_ota)
  • CI: Upload firmware to Gitea releases for OTA
  • CI: Simplify deploy script to pure POSIX sh

v1.9 - Multi-Channel Scanning & BLE Fingerprinting [DONE]

  • CHANSCAN command (ON/OFF/NOW/INTERVAL)
  • Channel hopping (1-13) with 100ms dwell, pause CSI during scan
  • chanscan= field in STATUS, chanscan_int NVS persistence
  • BLE fingerprinting: company_id, tx_power, adv_flags in BLE_DATA
  • Historical presence sessions support

v1.10 - LED Quiet Mode & CI Hardening [DONE]

  • LED quiet mode (off normally, solid on motion/presence, blinks on OTA)
  • Default LED to quiet mode
  • Build metadata in STATUS (date, time, IDF version, chip info)
  • CI security checks (secrets scan, config validation, size check)
  • Size optimization (-Os, saves ~75KB vs -O2)
  • CSI ON/OFF toggle command (NVS persisted)

v1.11 - Diagnostics & Usability [DONE]

  • HELP command (lists all commands with syntax)
  • CONFIG command (dump all running config key=value)
  • FACTORY command (erase NVS config + reboot)
  • PING command (echo reply for connectivity tests)
  • LOG command (runtime log level control)
  • RSSI RESET command (reset min/max counters)
  • OTA rollback validation (crasher firmware + bootloader rollback confirmed)
  • Tagged v1.11.0 and OTA deployed to all 3 sensors

v1.12 - Security Hardening & Monitoring (unreleased)

  • ALERT command (temp/heap thresholds, EVENT emission, 60s holdoff, NVS persisted)
  • Auth whitelist (read-only queries only without HMAC)
  • AUTH OFF disabled remotely (serial/FACTORY only)
  • STATUS split (minimal unauthed vs full authed)
  • Rate limiter (50ms throttle, 20 cmd/s)
  • NVS write throttle (20 writes per 10s)
  • CSI buffer bounds checking (UDP_REM macro)
  • PMF required (CONFIG_ESP_WIFI_PMF_REQUIRED=y)
  • mDNS stripped to hostname-only (no service advertisement)
  • Serial console AUTH management
  • Auto-generated auth secret on first boot
  • Pentest completed: 50+ tests, all network-facing tests PASS
  • Enable stack canaries (CONFIG_COMPILER_STACK_CHECK_MODE_NORM)
  • Enable heap poisoning (CONFIG_HEAP_POISONING_LIGHT)
  • Enable WDT panic (CONFIG_ESP_TASK_WDT_PANIC)
  • Remove unused #include "esp_now.h" (CVE-2025-52471 mitigation)
  • Remove hardcoded default IP from Kconfig (use TARGET command)
  • OTA TLS certificate verification (ESP-IDF 150-CA bundle, crt_bundle_attach)
  • Multi-target (send data to 2+ UDP destinations)

Web Backend (~/git/esp32-web/)

Tracked in its own repository. See ~/git/esp32-web/ROADMAP.md.

Current: v0.1.5 (zones, intelligence dashboard, fleet management, 77 tests). Next: v0.1.6 (auth, rate limiting, production deployment).

v3.0 - Hardware Upgrade (ESP32-S3/C6)

Requires replacing current ESP32 (original) DevKitC V1 boards with ESP32-S3 or ESP32-C6 modules. The original ESP32 lacks FTM and has CSI/promiscuous mode conflicts.

  • Select target chip (ESP32-S3 for dual-core + BLE 5, or C6 for WiFi 6 + 802.15.4)
  • Port firmware to new target (idf.py set-target, adjust #if CONFIG_IDF_TARGET_*)
  • WiFi FTM / 802.11mc support (Fine Timing Measurement, ~1-2m accuracy)
    • FTM initiator + responder mode on each sensor
    • Inter-sensor ranging (3 pairs from 3 sensors)
    • Auto-calibrate sensor positions for 3D floor plan
  • Enable promiscuous mode alongside CSI (works on S2/S3/C3/C6)
  • Validate CSI quality on new chip (subcarrier count differs)
  • Update parsers for chip-specific CSI format

Future

  • AP+STA config portal (WIFI_MODE_APSTA, captive portal for initial setup)
  • ESP-NOW mesh (ESP32-to-ESP32 CSI)
  • External sensor support (PIR, temp/humidity via GPIO)
  • Pin mapping for ESP32-DevKitC V1
  • Compare CSI quality: passive (router) vs active (ESP-NOW)
  • Multi-sensor deployment guide (placement, zones, triangulation)
  • Home Assistant integration (MQTT discovery, entity creation)
  • Grafana dashboards for long-term analytics
  • ML-based device classification (phone vs laptop vs IoT)
  • RSSI triangulation with 3+ sensors (approximate device location)
Reference in New Issue View Git Blame Copy Permalink