OTA Updates & Fleet Management
Relevant source files
The following files were used as context for generating this wiki page:
OTA (Over-the-Air) updates and fleet management allow the remote deployment of firmware images and configuration changes to ESP32-based sensing nodes. This system ensures that nodes stay current with the latest signal processing modules without requiring physical serial connections for every update. The scope includes firmware partition management, rollback safety mechanisms, and runtime configuration overrides. Sources: harness/ruview/src/guidance.js, firmware/esp32-csi-node/RUNBOOK.md:2.
Firmware OTA Architecture
RuView sensing nodes utilize the standard ESP-IDF dual-slot OTA mechanism. The flash memory contains two application partitions (ota_0 and ota_1), allowing one slot to run the current production firmware while the other receives an update. Sources: firmware/esp32-csi-node/RUNBOOK.md:65-72.
Memory Partition Layout
The system uses a 16MB flash configuration with specific offsets for bootloader and application data.
| Region | Offset | Reachable by OTA? |
|---|---|---|
| Bootloader | 0x0 | No (USB Only) |
| Partition Table | 0x8000 | No (USB Only) |
| otadata | 0xF000 | Rewritten by OTA |
| ota_0 | 0x20000 | Yes (4 MB) |
| ota_1 | 0x420000 | Yes (4 MB) |
| nvs | 0x9000 | Never (Provisioning survives) |
Sources: firmware/esp32-csi-node/RUNBOOK.md:65-75.
OTA Update Flow
The desktop CLI or sensing server initiates an update by pushing a binary to the node's OTA endpoint. The node writes the incoming stream to the inactive partition and updates the otadata register to point to the new slot upon the next boot. Sources: firmware/esp32-csi-node/RUNBOOK.md:78-83.
This diagram shows the sequence for transferring and applying a remote firmware update to an inactive flash slot. Sources: v2/crates/wifi-densepose-desktop/src/commands/ota.rs, firmware/esp32-csi-node/RUNBOOK.md:78-83.
Safety and Recovery Mechanisms
Bootloader Rollback
The system enables CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE=y. This capability allows the node to revert to the previous working firmware slot if the new image fails to initialize properly or cannot establish a network link. Sources: firmware/esp32-csi-node/RUNBOOK.md:16-24.
- Self-Verification: The application must call
ota_rollback_boot_check()upon a successful boot to confirm the new image is functional. Sources: firmware/esp32-csi-node/RUNBOOK.md:22. - USB Recovery: Changes to the bootloader or partition table itself are not reachable via OTA and require a physical USB connection for updates. Sources: firmware/esp32-csi-node/RUNBOOK.md:73-75.
Trial Configuration
Critical connectivity settings (SSID, WiFi Password, Channel) use a trial application pattern. The node reboots with the new settings but reverts to the banked "known-good" values if it fails to associate with the network. Sources: firmware/esp32-csi-node/RUNBOOK.md:106-112.
Fleet Configuration Management
Fleet management involves tuning parameters via the csi_cfg NVS namespace without requiring a full firmware re-flash. The config_push.py tool facilitates these updates over the network. Sources: plugins/ruview/agents/ruview-config-engineer.md:13, firmware/esp32-csi-node/RUNBOOK.md:102-105.
Remote Config Keys
| Key | Default | Impact |
|---|---|---|
led_brightness | 10 | Visual feedback |
vital_interval_ms | 1000 | Sensing frequency |
swarm_heartbeat_sec | 30 | Mesh health timing |
csi_channel | Trial-based | RF link configuration |
Sources: firmware/esp32-csi-node/RUNBOOK.md:105-115.
Fleet Monitoring and Health
Nodes report telemetry to the sensing server to enable fleet-wide health monitoring. The system status API tracks performance metrics and hardware state. Sources: plans/phase1-specification/api-spec.md:2.2.1.
Health Metrics
Monitoring data is accessible via GET /api/v1/mesh and includes:
- min_heap_kib: Minimum heap available since boot (watermark). Sources: firmware/esp32-csi-node/RUNBOOK.md:121-125.
- die_c: Internal thermal sensor reading. Sources: firmware/esp32-csi-node/RUNBOOK.md:139-142.
- TX-path counters:
send_fail,rate_skip, andearly_dropto identify network starvation. Sources: firmware/esp32-csi-node/RUNBOOK.md:119.
The flow shows how telemetry travels from individual nodes to a central server for monitoring and subsequent remote configuration. Sources: firmware/esp32-csi-node/RUNBOOK.md:118-125, plans/phase1-specification/api-spec.md:2.2.1.
Summary
OTA updates and fleet management provide a robust framework for maintaining a distributed sensing network. By utilizing dual-partition slots and bootloader rollback enables, RuView prevents nodes from becoming unreachable due to bad updates. Remote configuration via NVS allows for fine-tuning RF parameters and sensing intervals across the fleet without physical hardware access. Sources: firmware/esp32-csi-node/RUNBOOK.md, plugins/ruview/agents/ruview-config-engineer.md.