Firmware and hardware targets
Overview
This area covers the embedded targets and hardware-facing support path for RuView/WiFi DensePose. The production firmware is firmware/esp32-csi-node: an ESP-IDF project whose app_main() in firmware/…/main.c initializes NVS, loads runtime configuration, starts USB serial onboarding, connects WiFi, opens the UDP sender, enables CSI collection, starts edge DSP, exposes OTA/config HTTP endpoints on port 8032, and then supervises the node while it streams sensing data. The project version comes from firmware/…/version.txt through firmware/…/CMakeLists.txt, so release binaries and esp_app_get_description()->version share the same source.
Build variants are selected by ESP-IDF defaults files and partition CSVs under firmware/esp32-csi-node. sdkconfig.defaults is the ESP32-S3 8 MB display-capable baseline using partitions_display.csv; sdkconfig.defaults.4mb switches S3 to the headless 4 MB OTA layout in partitions_4mb.csv; sdkconfig.defaults.esp32c6 layers the C6 research profile with native USB serial/JTAG onboarding, 4 MB layout, Wi-Fi 6/HE tagging, 8 Hz edge DSP, no display/WASM, and ESP-NOW sync instead of the disabled 802.15.4 time-sync path; sdkconfig.defaults.esp32c5 is an experimental C5 baseline requiring ESP-IDF >= 5.5.2, UART console, 240 MHz CPU, 8 Hz edge DSP, and opt-in LED wiring. firmware/…/CMakeLists.txt registers the firmware modules and adjusts dependencies for target and IDF version, including C6-only IEEE 802.15.4/LP-core dependencies, IDF 6 component splits, optional mock CSI, display, WASM, and mDNS.
Runtime configuration is split between Kconfig defaults and the csi_cfg NVS namespace. firmware/…/nvs_config.c reads WiFi credentials, UDP target, node ID, channel hopping, edge DSP thresholds, WASM verification, CSI channel/MAC filter, swarm settings, and LED mode into g_nvs_config. firmware/…/provision.py builds and flashes the NVS partition at offset 0x9000, merging host-side per-board state keyed by chip MAC so partial reprovisioning does not wipe earlier values; it can also write security/ota_psk but deliberately does not cache the OTA key. firmware/…/config_push.py writes the same class of settings over the authenticated /config endpoint. The firmware-side handler in firmware/…/config_api.c validates the full request before writing, banks prior values in cfg_trial, and reboots into a trial for association-affecting changes so a bad SSID/password/channel reverts automatically.
CSI transport starts in firmware/…/csi_collector.c. It registers the ESP-IDF CSI callback, defensively copies the node ID and MAC filter before WiFi init can clobber g_nvs_config, configures promiscuous capture and CSI acquisition differently for HE-capable C5/C6 versus S3, and serializes raw frames into ADR-018: magic 0xC5110001, node ID, antenna count, subcarrier count, frequency, sequence, RSSI/noise, optional PPDU/flag bytes, then sanitized I/Q bytes. The callback rate-gates processing to approximately 50 Hz to avoid WiFi/flash-cache and lwIP pressure; if mesh time is valid it aligns the gate to ESP-NOW epoch buckets so multiple nodes accept frames from the same windows. It streams raw CSI through firmware/…/stream_sender.c, which sends UDP to the configured aggregator and backs off on ENOMEM, while priority packets bypass the CSI backoff for low-rate control/sync traffic. The same callback emits ADR-110 sync packets with magic 0xC511A110 and enqueues a separate uniform cadence into edge DSP.
Edge telemetry is produced in firmware/…/edge_processing.c. The DSP task consumes sanitized I/Q from a lock-free ring, tracks subcarrier phase variance, chooses top-K subcarriers, estimates breathing and heart rate, computes motion/presence/fall, debounces multi-person counts, and sends derived packets over the same UDP socket. Standard vitals use magic 0xC5110002; when firmware/…/mmwave_sensor.c detects a supported mmWave sensor, edge processing emits fused vitals instead. The feature-vector path emits a compact vector alongside vitals, and Tier 2 dispatches frame data into the WASM runtime if enabled. firmware/…/swarm_bridge.c is optional: when seed_url is configured in NVS, it POSTs registration, heartbeat, and presence-gated happiness vectors to a Cognitum Seed ingest endpoint at /api/v1/store/ingest.
OTA and control live on the firmware HTTP server in firmware/…/ota_update.c. GET /ota/status reports version, build date/time, running and next partitions, OTA state, and max update slot size. POST /ota accepts an application image only when security/ota_psk is provisioned and the request carries Authorization: Bearer <psk>; unprovisioned devices fail closed. The same server registers /config and /link/reassoc from firmware/…/config_api.c, and the WASM upload endpoints when firmware/…/wasm_upload.c is active. firmware/…/ota_health.c is started before network waits in main.c so an OTA image in PENDING_VERIFY must prove WiFi association and CSI send progress before it is confirmed.
Serial onboarding is a physical-USB escape hatch. firmware/…/serial_onboarding.c starts before WiFi so a node with bad credentials can still be configured. It accepts RUVIEW_HELLO_V1 <nonce>, replies with RUVIEW_HELLO_OK_V1 including chip, firmware version, current target, configured flag, and device digest, then accepts one nonce-bound RUVIEW_CONFIG_V1 line and writes SSID/password unless KEEP is requested. The parser in firmware/…/serial_onboarding_protocol.c enforces private IPv4 targets, node IDs 1-255, base64 printable credentials, and a 60-second nonce window.
firmware/esp32-hello-world is a separate ESP-IDF probe application, not the sensing firmware. Its firmware/…/main.c prints chip, flash, partition, WiFi/CSI, BLE/802.15.4, GPIO/peripheral, heap, temperature, and FreeRTOS capability information without joining WiFi. firmware/esp32-hello-world/sdkconfig.defaults defaults to ESP32-C6 with CSI enabled and a larger main stack, making it a board qualification/capability dump before choosing a sensing-node build.
OpenWrt router CSI support lives in firmware/openwrt-wn586x3. This directory contains patches, not an image: firmware/…/README.md documents WL-WN586X3 Rev A patches against OpenWrt 24.10.8 / mt76, board support, and mt76-vendor/CSIdump fixes. It emits MediaTek CSI for the host-side wifi-densepose-mtk-bridge, with provenance marked mediatek:physical-unvalidated until calibration, sequence, timestamp, and repeatability gates pass. The README explicitly prefers the mt76-vendor dump csi JSON path when chain layout matters because it preserves RSSI, SNR, transmit address, bandwidth, PPDU mode, and per-chain indices that the CSIdump UDP datagram lacks.
PrivShield is a separate hardware/firmware research tree under firmware/privshield. The portable core in firmware/…/veil_shield.c and .h implements a deterministic SplitMix64 schedule and keyed Givens rotations over an in-memory float vector; it preserves L2 energy and can invert with the same key. Provider adapters are build-only scaffolds: firmware/…/veil_shieldd.c drives only the commodity Linux/mac80211 knobs that userspace can reach and marks the true per-packet keyed rotation as blob-blocked; firmware/…/veil_openwifi.c is the openwifi FPGA shim that would program future veil_rot/veil_unrot AXI-Lite blocks; firmware/…/veil_patch.c is a Nexmon-style Broadcom hook skeleton with placeholder addresses. The ESP32 PrivShield components (firmware/…/veil_sensing_detector.c and firmware/…/veil_ris_controller.c) deliberately do not claim ESP32 can shape its own beamforming feedback: the detector is a CSI cadence trigger stub, and the RIS controller only generates keyed bitmaps for passive external surface control.
Firmware-adjacent validation and release tooling is under scripts/. scripts/firmware-release-guard.sh regenerates the expected partition table from the variant CSV and compares it to a build output so stale sdkconfig cannot ship a mislabeled 4 MB/8 MB image. scripts/generate_nvs_matrix.py emits NVS binaries for QEMU and boundary tests. scripts/qemu-esp32s3-test.sh, scripts/qemu-mesh-test.sh, scripts/qemu_swarm.py, scripts/qemu-snapshot-test.sh, scripts/qemu-chaos-test.sh, and scripts/validate_qemu_output.py build mock-CSI firmware, merge flash images, inject NVS at 0x9000, run Espressif QEMU with optional networking/topologies/faults/snapshots, and validate UART logs for boot, mock CSI, edge, vitals, ADR-018 streaming, crash, heap, stack, and ADR-081 markers. scripts/esp32_jsonl_to_rvcsi.py converts ESP32 JSONL captures into .rvcsi JSONL by deriving amplitude/phase from int8 I/Q and applying rvcsi-style quality scoring. scripts/validate-esp32-mqtt.sh is a real-hardware ESP32→sensing-server→MQTT/Home Assistant discovery harness, and scripts/esp32_wasm_test.py uploads generated WASM modules to a node’s HTTP server to exercise the firmware WASM import surface.
The Docker files are the host ingest side for live firmware. docker/Dockerfile.rust builds the Rust sensing-server with MQTT by default, copies UI assets, exposes REST/WebSocket, UDP 5005, MQTT, and Homecore ports, and defaults CSI_SOURCE=auto; docker/docker-entrypoint.sh starts the sensing server and, when ESP32 UDP ingest is expected from outside the container, only binds UDP to 0.0.0.0 if an ADR-296 source guard is configured via RUVIEW_UDP_ALLOW or RUVIEW_UDP_INSECURE_LAN. docker/docker-compose.yml publishes UDP 5005:5005/udp for ESP32 nodes and documents Docker Desktop source-address rewriting, while keeping TCP APIs loopback by default and requiring API auth unless the operator opts into an unauthenticated posture. The Python image in docker/Dockerfile.python is the legacy archive/v1 WebSocket pipeline, not the ESP32 CSI aggregator path.
Coupling
- If the ADR-018 wire format changes in firmware/…/csi_collector.c or the derived packet structs in firmware/…/edge_processing.h, update every host parser and transcoder that assumes magic values and byte layouts, including scripts/esp32_jsonl_to_rvcsi.py and the UDP ingest path behind
docker/Dockerfile.rust. The firmware uses raw UDP frames without schema negotiation, so parsers will not fail loudly on a reserved-byte or magic-number drift. - If any NVS key or range changes in firmware/…/nvs_config.c, firmware/…/config_rules.c, or firmware/…/nvs_config.h, update all writers: firmware/…/provision.py, firmware/…/config_push.py, and scripts/generate_nvs_matrix.py. These paths write the same namespace from USB, HTTP, and QEMU; a new key that is only added to one writer creates divergent device state.
- If a partition CSV or flash-size default changes under
firmware/esp32-csi-node, update scripts/firmware-release-guard.sh and QEMU merge offsets in scripts/qemu-esp32s3-test.sh / scripts/qemu-mesh-test.sh. OTA, NVS provisioning, and release packaging all assume NVS at0x9000, OTA data at0xf000, and app offset0x20000for the current layouts. - If the HTTP control port or OTA auth model changes in firmware/…/ota_update.c, update firmware/…/config_push.py and scripts/esp32_wasm_test.py.
/config,/link/reassoc,/ota, and WASM upload endpoints share the same server and bearer-token cache, so a security change in one handler affects all remote control paths. - If
CONFIG_CSI_MOCK_ENABLED, mock scenarios, or QEMU log phrases change in firmware/…/mock_csi.c,firmware/esp32-csi-node/main/Kconfig.projbuild, or firmware/…/main.c, update scripts/qemu-esp32s3-test.sh, scripts/qemu_swarm.py, and scripts/validate_qemu_output.py. The QEMU harnesses validate behavior by UART markers rather than an RPC contract. - If ESP32 UDP ingest is moved from port
5005or needs a different bind/source-guard posture, updatedocker/Dockerfile.rust, docker/docker-compose.yml, docker/docker-entrypoint.sh, and provisioning defaults infirmware/esp32-csi-node/main/Kconfig.projbuild/ firmware/…/provision.py. Nodes stream blindly totarget_ip:target_port; the container entrypoint may otherwise keep the UDP socket on loopback and silently receive nothing from LAN nodes. - If PrivShield’s portable rotation schedule changes in firmware/…/veil_shield.c, update the duplicated schedule serializers in firmware/…/veil_openwifi.c, firmware/…/veil_shieldd.c, and firmware/…/veil_ris_controller.c. The adapters rely on byte-identical SplitMix64 draw order with the core; drift breaks inversion/keyed reproducibility.
Risks
- firmware/…/csi_collector.c, firmware/…/stream_sender.c, and
firmware/esp32-csi-node/main/Kconfig.projbuildare fragile around callback rate and UDP buffer pressure. The code documents prior WiFi ISR/cache crashes above ~50 Hz and lwIPENOMEMcascades; raisingCONFIG_CSI_SELF_PING_HZ, removing the callback gate, or bypassingstream_senderbackoff can turn CSI traffic into crashes or near-total frame loss. - firmware/…/main.c and firmware/…/csi_collector.c carry defensive ordering for
g_nvs_config: main.c capturesnode_idimmediately afternvs_config_load()because comments cite confirmed WiFi-driver clobbering of the struct. Movingwifi_init_sta()earlier or making callback paths readg_nvs_configdirectly can corrupt node identity, MAC filtering, and stream attribution. - firmware/…/ota_update.c and firmware/…/config_api.c intentionally fail closed on missing OTA PSK and bank configuration before writes. Relaxing auth or combining validate/write passes reintroduces the documented bug class where unauthenticated LAN hosts can push firmware or rejected config requests can still half-apply WiFi settings and orphan a node.
firmware/esp32-csi-node/sdkconfig.defaults.esp32c6, firmware/…/c6_timesync.c, and firmware/…/c6_sync_espnow.c encode a measured workaround: C6 802.15.4 RX is disabled because the path delivered no frames in tested IDF 5.4 configurations. Re-enabling 802.15.4 time-sync without validating RX can steal airtime from CSI while falsely implying mesh sync support.firmware/esp32-csi-node/sdkconfig.defaults.devkitcand firmware/…/main.c couple display probing to CSI filter selection. A false-positive display probe keeps capture at MGMT-only and can collapse CSI yield to 0 pps on display-less boards; display-overlay changes should be checked against raw CSI callback yield, not just UI boot logs.firmware/privshield/**is explicitlySYNTHETIC / L0except the portable core host tests. Treating firmware/…/MEASUREMENT.md, firmware/…/veil_patch.c, or ESP32 PrivShield stubs as hardware evidence would create false defense claims; the docs require captured real-silicon logs before anyMEASUREDprivacy-shield result.