chore: update vendor submodules to latest main

docs: update user guide with v0.4.1 firmware release and CSI troubleshooting
- Add v0.4.1 to firmware release table as recommended stable release - Update flash command with correct partition offsets (8MB, OTA) - Add "CSI not enabled" troubleshooting entry - Add warning about pre-v0.4.1 firmware CSI bug Co-Authored-By: claude-flow <ruv@ruv.net>
2026-06-27 13:13:21 +00:00 · 2026-03-13 00:36:02 +00:00 · 2026-03-12 13:49:20 -04:00 · 2026-03-12 13:49:20 -04:00 · 2026-03-12 13:49:20 -04:00 · 2026-03-10 12:16:06 -04:00
8 changed files with 168 additions and 21 deletions
@@ -1043,14 +1043,16 @@ Download a pre-built binary — no build toolchain needed:

 | Release | What's included | Tag |
 |---------|-----------------|-----|
-| [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Stable — raw CSI streaming, multi-node TDM, channel hopping | `v0.2.0-esp32` |
+| [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | **Stable** — CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` |
 | [v0.3.0-alpha](https://github.com/ruvnet/RuView/releases/tag/v0.3.0-alpha-esp32) | Alpha — adds on-device edge intelligence and WASM modules ([ADR-039](docs/adr/ADR-039-esp32-edge-intelligence.md), [ADR-040](docs/adr/ADR-040-wasm-programmable-sensing.md)) | `v0.3.0-alpha-esp32` |
+| [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Raw CSI streaming, multi-node TDM, channel hopping | `v0.2.0-esp32` |

 ```bash
 # 1. Flash the firmware to your ESP32-S3
 python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
-  write_flash --flash_mode dio --flash_size 8MB \
-  0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 esp32-csi-node.bin
+  write_flash --flash-mode dio --flash-size 8MB --flash-freq 80m \
+  0x0 bootloader.bin 0x8000 partition-table.bin \
+  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin

 # 2. Set WiFi credentials and server address (stored in flash, survives reboots)
 python firmware/esp32-csi-node/provision.py --port COM7 \
@@ -0,0 +1,82 @@
+# ADR-057: Firmware CSI Build Guard and sdkconfig.defaults
+
+| Field       | Value                                       |
+|-------------|---------------------------------------------|
+| **Status**  | Accepted                                    |
+| **Date**    | 2026-03-12                                  |
+| **Authors** | ruv                                         |
+| **Issues**  | #223, #238, #234, #210, #190                |
+
+## Context
+
+Multiple GitHub issues (#223, #238, #234, #210, #190) report firmware problems
+that fall into two categories:
+
+1. **CSI not enabled at runtime** — The committed `sdkconfig` had
+   `# CONFIG_ESP_WIFI_CSI_ENABLED is not set` (line 1135), meaning users who
+   built from source or used pre-built binaries got the runtime error:
+   `E (6700) wifi:CSI not enabled in menuconfig!`
+
+   Root cause: `sdkconfig.defaults.template` existed with the correct setting
+   (`CONFIG_ESP_WIFI_CSI_ENABLED=y`) but ESP-IDF only reads
+   `sdkconfig.defaults` — not `.template` suffixed files. No `sdkconfig.defaults`
+   file was committed.
+
+2. **Unsupported ESP32 variants** — Users attempting to use original ESP32
+   (D0WD) and ESP32-C3 boards. The firmware targets ESP32-S3 only
+   (`CONFIG_IDF_TARGET="esp32s3"`, Xtensa architecture) and this was not
+   surfaced clearly enough in documentation or build errors.
+
+## Decision
+
+### Fix 1: Commit `sdkconfig.defaults` (not just template)
+
+Copy `sdkconfig.defaults.template` → `sdkconfig.defaults` so that ESP-IDF
+applies the correct defaults (including `CONFIG_ESP_WIFI_CSI_ENABLED=y`)
+automatically when `sdkconfig` is regenerated.
+
+### Fix 2: `#error` compile-time guard in `csi_collector.c`
+
+Add a preprocessor guard:
+
+```c
+#ifndef CONFIG_ESP_WIFI_CSI_ENABLED
+#error "CONFIG_ESP_WIFI_CSI_ENABLED must be set in sdkconfig."
+#endif
+```
+
+This turns a confusing runtime crash into a clear compile-time error with
+instructions on how to fix it.
+
+### Fix 3: Fix committed `sdkconfig`
+
+Change line 1135 from `# CONFIG_ESP_WIFI_CSI_ENABLED is not set` to
+`CONFIG_ESP_WIFI_CSI_ENABLED=y`.
+
+## Consequences
+
+- **Positive**: New builds will always have CSI enabled. Users building from
+  source will get a clear compile error if CSI is somehow disabled.
+- **Positive**: Pre-built release binaries will include CSI support.
+- **Neutral**: Original ESP32 and ESP32-C3 remain unsupported. This is by
+  design — only ESP32-S3 has the CSI API surface we depend on. Future ADRs
+  may address multi-target support if demand warrants it.
+- **Negative**: None identified.
+
+## Hardware Support Matrix
+
+| Variant      | CSI Support | Firmware Target | Status        |
+|--------------|-------------|-----------------|---------------|
+| ESP32-S3     | Yes         | Yes             | Supported     |
+| ESP32 (orig) | Partial     | No              | Unsupported   |
+| ESP32-C3     | Yes (IDF 5.1+) | No           | Unsupported   |
+| ESP32-C6     | Yes         | No              | Unsupported   |
+
+## Notes
+
+- ESP32-C3 and C6 use RISC-V architecture; a separate build target
+  (`idf.py set-target esp32c3`) would be needed.
+- Original ESP32 has limited CSI (no STBC HT-LTF2, fewer subcarriers).
+- Users on unsupported hardware can still write custom firmware using the
+  ADR-018 binary frame format (magic `0xC5110001`) for interop with the
+  Rust aggregator.
@@ -78,6 +78,17 @@ docker pull ruvnet/wifi-densepose:latest

 Multi-architecture image (amd64 + arm64). Works on Intel/AMD and Apple Silicon Macs. Contains the Rust sensing server, Three.js UI, and all signal processing.

+**Data source selection:** Use the `CSI_SOURCE` environment variable to select the sensing mode:
+
+| Value | Description |
+|-------|-------------|
+| `auto` | (default) Probe for ESP32 on UDP 5005, fall back to simulation |
+| `esp32` | Receive real CSI frames from ESP32 devices over UDP |
+| `simulated` | Generate synthetic CSI frames (no hardware required) |
+| `wifi` | Host Wi-Fi RSSI (not available inside containers) |
+
+Example: `docker run -e CSI_SOURCE=esp32 -p 3000:3000 -p 5005:5005/udp ruvnet/wifi-densepose:latest`
+
 ### From Source (Rust)

 ```bash
@@ -267,8 +278,8 @@ Real Channel State Information at 20 Hz with 56-192 subcarriers. Required for po
 # From source
 ./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

-# Docker
-docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest --source esp32
+# Docker (use CSI_SOURCE environment variable)
+docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest
 ```

 The ESP32 nodes stream binary CSI frames over UDP to port 5005. See [Hardware Setup](#esp32-s3-mesh) for flashing instructions.
@@ -679,9 +690,11 @@ Download the dataset files and place them in a `data/` directory.
 ./target/release/sensing-server --train --dataset data/ --dataset-type mmfi --epochs 100 --save-rvf model.rvf

 # Via Docker (mount your data directory)
+# Note: Training mode requires overriding the default entrypoint
 docker run --rm \
  -v $(pwd)/data:/data \
  -v $(pwd)/output:/output \
+  --entrypoint /app/sensing-server \
  ruvnet/wifi-densepose:latest \
  --train --dataset /data --epochs 100 --export-rvf /output/model.rvf
 ```
@@ -797,14 +810,18 @@ Pre-built binaries are available at [Releases](https://github.com/ruvnet/RuView/

 | Release | What It Includes | Tag |
 |---------|-----------------|-----|
-| [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Stable — raw CSI streaming, TDM, channel hopping, QUIC mesh | `v0.2.0-esp32` |
+| [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) | **Stable** — CSI build fix, compile guard, AMOLED display, edge intelligence ([ADR-057](../docs/adr/ADR-057-firmware-csi-build-guard.md)) | `v0.4.1-esp32` |
 | [v0.3.0-alpha](https://github.com/ruvnet/RuView/releases/tag/v0.3.0-alpha-esp32) | Alpha — adds on-device edge intelligence (ADR-039) | `v0.3.0-alpha-esp32` |
+| [v0.2.0](https://github.com/ruvnet/RuView/releases/tag/v0.2.0-esp32) | Raw CSI streaming, TDM, channel hopping, QUIC mesh | `v0.2.0-esp32` |
+
+> **Important:** Firmware versions prior to v0.4.1 had CSI **disabled** in the build config, causing a runtime error (`E wifi:CSI not enabled in menuconfig!`). Always use v0.4.1 or later.

 ```bash
 # Flash an ESP32-S3 (requires esptool: pip install esptool)
 python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
-  write-flash --flash-mode dio --flash-size 4MB \
-  0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 esp32-csi-node.bin
+  write-flash --flash-mode dio --flash-size 8MB --flash-freq 80m \
+  0x0 bootloader.bin 0x8000 partition-table.bin \
+  0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin
 ```

 **Provisioning:**
@@ -885,8 +902,8 @@ Binary size: 777 KB (24% free in the 1 MB app partition).
 # From source
 ./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

-# Docker
-docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp ruvnet/wifi-densepose:latest --source esp32
+# Docker (use CSI_SOURCE environment variable)
+docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest
 ```

 See [ADR-018](../docs/adr/ADR-018-esp32-dev-implementation.md), [ADR-029](../docs/adr/ADR-029-ruvsense-multistatic-sensing-mode.md), and [Tutorial #34](https://github.com/ruvnet/RuView/issues/34).
@@ -953,12 +970,17 @@ Add the WebSocket port mapping:
 docker run -p 3000:3000 -p 3001:3001 ruvnet/wifi-densepose:latest
 ```

+### ESP32: "CSI not enabled in menuconfig"
+
+Firmware versions prior to v0.4.1 had `CONFIG_ESP_WIFI_CSI_ENABLED` disabled in the build config. Upgrade to [v0.4.1](https://github.com/ruvnet/RuView/releases/tag/v0.4.1-esp32) or later. If building from source, ensure `sdkconfig.defaults` exists (not just `sdkconfig.defaults.template`). See [ADR-057](../docs/adr/ADR-057-firmware-csi-build-guard.md).
+
 ### ESP32: No data arriving

-1. Verify the ESP32 is connected to the same WiFi network
-2. Check the target IP matches the sensing server machine: `python firmware/esp32-csi-node/provision.py --port COM7 --target-ip <YOUR_IP>`
-3. Verify UDP port 5005 is not blocked by firewall
-4. Test with: `nc -lu 5005` (Linux) or similar UDP listener
+1. Verify firmware is v0.4.1+ (older versions had CSI disabled — see above)
+2. Verify the ESP32 is connected to the same WiFi network
+3. Check the target IP matches the sensing server machine: `python firmware/esp32-csi-node/provision.py --port COM7 --target-ip <YOUR_IP>`
+4. Verify UDP port 5005 is not blocked by firewall
+5. Test with: `nc -lu 5005` (Linux) or similar UDP listener

 ### Build: Rust compilation errors

@@ -21,6 +21,16 @@
 #include "esp_timer.h"
 #include "sdkconfig.h"

+/* ADR-057: Build-time guard — fail early if CSI is not enabled in sdkconfig.
+ * Without this, the firmware compiles but crashes at runtime with:
+ *   "E (xxxx) wifi:CSI not enabled in menuconfig!"
+ * which is confusing for users flashing pre-built binaries. */
+#ifndef CONFIG_ESP_WIFI_CSI_ENABLED
+#error "CONFIG_ESP_WIFI_CSI_ENABLED must be set in sdkconfig. " \
+       "Run: idf.py menuconfig -> Component config -> Wi-Fi -> Enable WiFi CSI, " \
+       "or copy sdkconfig.defaults.template to sdkconfig.defaults before building."
+#endif
+
 static const char *TAG = "csi_collector";

 static uint32_t s_sequence = 0;
@@ -0,0 +1,33 @@
+# ESP32-S3 CSI Node — Default SDK Configuration
+# This file is applied automatically by idf.py when no sdkconfig exists.
+
+# Target: ESP32-S3
+CONFIG_IDF_TARGET="esp32s3"
+
+# Use custom partition table (8MB flash with OTA — ADR-045)
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_display.csv"
+
+# Flash configuration: 8MB (Quad SPI)
+CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y
+CONFIG_ESPTOOLPY_FLASHSIZE="8MB"
+
+# Compiler optimization: optimize for size to reduce binary
+CONFIG_COMPILER_OPTIMIZATION_SIZE=y
+
+# Enable CSI (Channel State Information) in WiFi driver
+CONFIG_ESP_WIFI_CSI_ENABLED=y
+
+# NVS encryption disabled by default (requires eFuse provisioning).
+# Enable only after burning HMAC key to eFuse block.
+# CONFIG_NVS_ENCRYPTION is not set
+
+# Disable unused features to reduce binary size
+CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y
+
+# LWIP: enable extended socket options for UDP multicast
+CONFIG_LWIP_SO_RCVBUF=y
+
+# FreeRTOS: increase task stack for CSI processing
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
@@ -18,8 +18,9 @@ CONFIG_COMPILER_OPTIMIZATION_SIZE=y
 # Enable CSI (Channel State Information) in WiFi driver
 CONFIG_ESP_WIFI_CSI_ENABLED=y

-# Enable NVS encryption for secure credential storage
-CONFIG_NVS_ENCRYPTION=y
+# NVS encryption disabled by default (requires eFuse provisioning).
+# Enable only after burning HMAC key to eFuse block.
+# CONFIG_NVS_ENCRYPTION is not set

 # Disable unused features to reduce binary size
 CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y
@@ -30,9 +30,6 @@
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
-    ],
-    "resources": {
-      "../../target/release/sensing-server": "bin/sensing-server"
-    }
+    ]
  }
 }
Author	SHA1	Message	Date
github-actions[bot]	6891a72053	chore: update vendor submodules to latest main	2026-03-13 00:36:02 +00:00
ruv	6e03a47867	docs: update user guide with v0.4.1 firmware release and CSI troubleshooting - Add v0.4.1 to firmware release table as recommended stable release - Update flash command with correct partition offsets (8MB, OTA) - Add "CSI not enabled" troubleshooting entry - Add warning about pre-v0.4.1 firmware CSI bug Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 13:49:20 -04:00
ruv	9d1140de2d	docs: update README firmware release table with v0.4.1 Add v0.4.1-esp32 as the recommended stable release and update the flash command to match the current partition layout. Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 13:49:20 -04:00
ruv	952f27a1ce	fix(firmware): enable CSI in sdkconfig and add build guard (ADR-057) The committed sdkconfig had CONFIG_ESP_WIFI_CSI_ENABLED disabled, causing all builds to crash at runtime with "CSI not enabled in menuconfig". Root cause: sdkconfig.defaults.template existed but ESP-IDF only reads sdkconfig.defaults (no .template suffix). Fixes: - Add sdkconfig.defaults with CONFIG_ESP_WIFI_CSI_ENABLED=y - Add #error compile guard in csi_collector.c to prevent recurrence - Fix NVS encryption default (requires eFuse, breaks clean builds) Verified: Docker build + flash to ESP32-S3 + CSI callbacks confirmed. Closes #241 Relates to #223, #238, #234, #210, #190 Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 13:49:20 -04:00
Reuven	f7d043d727	docs: fix Docker commands to use CSI_SOURCE environment variable The Docker image uses CSI_SOURCE env var to select the data source, not command-line arguments appended after the image name. Fixed: - ESP32 mode examples now use -e CSI_SOURCE=esp32 - Training mode example now uses --entrypoint override - Added CSI_SOURCE value table in Docker section Fixes #226 Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-10 12:16:06 -04:00
Reuven	ff91d4e8cf	fix(desktop): remove bundled sensing-server resource for CI build The sensing-server binary was referenced in tauri.conf.json but doesn't exist in CI environment. Removed the resources section to fix the build. Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-10 10:56:31 -04:00