ESP32 Firmware & Provisioning
Relevant source files
The following files were used as context for generating this wiki page:
ESP32 Firmware and Provisioning enables hardware nodes to capture WiFi Channel State Information (CSI) and transmit it to a central sensing server. This system manages the lifecycle of physical sensing nodes, including building target-specific binaries, flashing devices over serial connections, and configuring runtime parameters via Non-Volatile Storage (NVS).
The firmware supports high-performance edge processing on ESP32-S3 and ESP32-C6 targets. It includes an automated provisioning script to set WiFi credentials, target sink addresses, and sensing thresholds without requiring code modifications.
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md, firmware/esp32-csi-node/README.md
Firmware Architecture
The firmware uses ESP-IDF v5.4 to implement a DSP pipeline for radio sensing. It configures the WiFi stack in a high-current, continuous radio mode (WIFI_PS_NONE) to ensure stable CSI collection. The system supports multiple hardware variants through specific sdkconfig templates.
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:16-24, firmware/esp32-csi-node/RUNBOOK.md:86-90
Supported Hardware Targets
| Device | Flash Requirement | Primary Role |
|---|---|---|
| ESP32-S3 (8MB) | 8 MB | Default WiFi CSI sensing node |
| ESP32-S3 SuperMini | 4 MB | Compact node (uses sdkconfig.defaults.4mb) |
| ESP32-C6 | 16 MB | Research target with mmWave fusion support |
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:12-18, firmware/esp32-csi-node/RUNBOOK.md:27-28
Firmware Build Flow
The build process utilizes Docker or a specific Python-subprocess environment to bypass path conversion issues in MSYS2/Git Bash environments.
The diagram shows the transition from configuration selection to the generation of required flash binaries.
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:26-35, firmware/esp32-csi-node/RUNBOOK.md:8-16
Device Provisioning
Provisioning occurs over a serial connection (UART) using the provision.py tool. This script writes configuration data directly to the csi_cfg NVS namespace on the device.
Critical NVS Behavior
Flashing new configuration replaces the entire csi_cfg namespace. Any keys not specified during a provision.py execution are erased. You must pass the full set of required flags to maintain device functionality.
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:65-68, plugins/ruview/skills/ruview-configure/SKILL.md:39-42
Configuration Parameters
| Flag | Default Value | Description |
|---|---|---|
--ssid | - | Target WiFi network name |
--password | - | WiFi password (stored in NVS) |
--target-ip | - | IP address of the RuView UDP sink |
--target-port | 5005 | Port of the RuView UDP sink |
--node-id | 1 | Unique identifier for the node (0-255) |
--fall-thresh | 15000 | Fall detection threshold (~15.0 rad/s²) |
--edge-tier | 2 | Processing level (0=off, 1=stats, 2=vitals) |
Sources: plugins/ruview/skills/ruview-configure/SKILL.md:22-38, plugins/ruview/skills/ruview-hardware-setup/SKILL.md:60-64
Flashing Procedure
Flashing requires specific memory offsets to match the partition table. For 8MB S3 builds, the app partition starts at 0x20000.
Flash Commands
Using esptool, you must write multiple binaries to their respective offsets:
python -m esptool --chip esp32s3 --port COM8 --baud 460800 \
write_flash 0x0 firmware/esp32-csi-node/build/bootloader/bootloader.bin \
0x8000 firmware/esp32-csi-node/build/partition_table/partition-table.bin \
0xf000 firmware/esp32-csi-node/build/ota_data_initial.bin \
0x20000 firmware/esp32-csi-node/build/esp32-csi-node.bin
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:52-57, harness/ruview/skills/provision-node.md:20-24
Provisioning Sequence
This diagram illustrates the communication flow during the provisioning phase and the subsequent start of sensing operations.
Sources: plugins/ruview/skills/ruview-hardware-setup/SKILL.md:60-70, firmware/esp32-csi-node/main/main.c:420-435
Operations and Monitoring
Once provisioned, nodes transmit CSI frames and edge-processed vitals via UDP. Monitoring is performed through the serial console or by observing the UDP sink.
Monitoring Verification
You can verify operation by observing specific serial log markers:
CSI cb #...: Indicates active Channel State Information callbacks.CSI filter upgraded to MGMT+DATA: Confirms the radio is capturing both management and data frames for higher resolution.
Sources: harness/ruview/skills/provision-node.md:36-40, firmware/esp32-csi-node/main/main.c:440-445
Over-the-Air (OTA) Updates
The firmware supports OTA updates for the app partition. However, OTA cannot modify the bootloader or the partition table; these changes require a physical USB connection.
Sources: firmware/esp32-csi-node/RUNBOOK.md:80-92
Summary
ESP32 Firmware & Provisioning provides the low-level foundation for the RuView sensing grid. It transforms standard ESP32-S3 and C6 hardware into specialized RF sensors. By combining high-speed CSI capture with a streamlined NVS-based configuration system, it allows for scalable deployments of through-wall human sensing nodes without requiring individual source code changes for each device environment.