chore: update vendor submodules to latest main

docs: ADR-061 QEMU ESP32-S3 firmware testing platform (9 layers)
Comprehensive QEMU emulation strategy for ESP32-S3 CSI node firmware: - Layer 1: Mock CSI generator with 10 test scenarios - Layer 2: QEMU runner + CI workflow with NVS matrix - Layer 3: Multi-node mesh simulation (TAP networking) - Layer 4: GDB remote debugging (zero-cost, no JTAG) - Layer 5: Code coverage (gcov/lcov) - Layer 6: Fuzz testing (libFuzzer for CSI parser, NVS, WASM) - Layer 7: NVS provisioning matrix (14 configs) - Layer 8: Snapshot & replay (<100ms restore) - Layer 9: Chaos testing (9 fault injection scenarios) Co-Authored-By: claude-flow <ruv@ruv.net>
2026-07-26 18:01:48 +00:00 · 2026-03-13 18:16:16 +00:00 · 2026-03-13 09:02:09 -04:00 · 2026-03-13 08:27:08 -04:00 · 2026-03-12 21:55:09 -04:00 · 2026-03-12 21:47:31 -04:00
12 changed files with 1056 additions and 22 deletions
@@ -87,7 +87,7 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest
  </a>
  <br>
  <em>Real-time pose skeleton from WiFi CSI signals — no cameras, no wearables</em>
-  <br>
+  <br><br>
  <a href="https://ruvnet.github.io/RuView/"><strong>▶ Live Observatory Demo</strong></a>
  &nbsp;|&nbsp;
  <a href="https://ruvnet.github.io/RuView/pose-fusion.html"><strong>▶ Dual-Modal Pose Fusion Demo</strong></a>
@@ -0,0 +1,59 @@
+# ADR-060: Provision Channel Override and MAC Address Filtering
+
+- **Status:** Accepted
+- **Date:** 2026-03-12
+- **Issues:** [#247](https://github.com/ruvnet/RuView/issues/247), [#229](https://github.com/ruvnet/RuView/issues/229)
+
+## Context
+
+Two related provisioning gaps were reported by users:
+
+1. **Channel mismatch (Issue #247):** The CSI collector initializes on the
+   Kconfig default channel (typically 6), even when the ESP32 connects to an AP
+   on a different channel (e.g. 11). On managed networks where the user cannot
+   change the router channel, this makes nodes undiscoverable. The
+   `provision.py` script has no `--channel` argument.
+
+2. **Missing MAC filter (Issue #229):** The v0.2.0 release notes documented a
+   `--filter-mac` argument for `provision.py`, but it was never implemented.
+   The firmware's CSI callback accepts frames from all sources, causing signal
+   mixing in multi-AP environments.
+
+## Decision
+
+### Channel configuration
+
+- Add `--channel` argument to `provision.py` that writes a `csi_channel` key
+  (u8) to NVS.
+- In `nvs_config.c`, read the `csi_channel` key and override
+  `channel_list[0]` when present.
+- In `csi_collector_init()`, after WiFi connects, auto-detect the AP channel
+  via `esp_wifi_sta_get_ap_info()` and use it as the default CSI channel when
+  no NVS override is set. This ensures the CSI collector always matches the
+  connected AP's channel without requiring manual provisioning.
+
+### MAC address filtering
+
+- Add `--filter-mac` argument to `provision.py` that writes a `filter_mac`
+  key (6-byte blob) to NVS.
+- In `nvs_config.h`, add a `filter_mac[6]` field and `filter_mac_set` flag.
+- In `nvs_config.c`, read the `filter_mac` blob from NVS.
+- In the CSI callback (`wifi_csi_callback`), if `filter_mac_set` is true,
+  compare the source MAC from the received frame against the configured MAC
+  and drop non-matching frames.
+
+### Provisioning flow
+
+```
+python provision.py --port COM7 --channel 11
+python provision.py --port COM7 --filter-mac "AA:BB:CC:DD:EE:FF"
+python provision.py --port COM7 --channel 11 --filter-mac "AA:BB:CC:DD:EE:FF"
+```
+
+## Consequences
+
+- Users on managed networks can force the CSI channel to match their AP
+- Multi-AP environments can filter CSI to a single source
+- Auto-channel detection eliminates the most common misconfiguration
+- Backward compatible: existing provisioned nodes without these keys behave
+  as before (use Kconfig default channel, accept all MACs)
@@ -0,0 +1,864 @@
+# ADR-061: QEMU ESP32-S3 Emulation for Firmware Testing & Development
+
+| Field       | Value                                          |
+|-------------|------------------------------------------------|
+| **Status**  | Proposed                                       |
+| **Date**    | 2026-03-13                                     |
+| **Authors** | RuView Team                                    |
+| **Relates** | ADR-018 (binary frame), ADR-039 (edge intel), ADR-040 (WASM), ADR-057 (build guard), ADR-060 (channel/MAC filter) |
+
+## Context
+
+The ESP32-S3 CSI node firmware (`firmware/esp32-csi-node/`) has grown to 16 source files spanning:
+
+| Module | File | Testable in QEMU? |
+|--------|------|--------------------|
+| NVS config load | `nvs_config.c` | Yes — NVS partition in flash image |
+| Edge processing (DSP) | `edge_processing.c` | Yes — all math, no HW dependency |
+| ADR-018 frame serialization | `csi_collector.c:csi_serialize_frame()` | Yes — pure buffer ops |
+| UDP stream sender | `stream_sender.c` | Yes — QEMU has lwIP via SLIRP |
+| WASM runtime | `wasm_runtime.c` | Yes — CPU only |
+| OTA update | `ota_update.c` | Partial — needs HTTP mock |
+| Power management | `power_mgmt.c` | Partial — no real light-sleep |
+| Display (OLED) | `display_*.c` | No — I2C hardware |
+| WiFi CSI callback | `csi_collector.c:wifi_csi_callback()` | **No** — requires RF PHY |
+| Channel hopping | `csi_collector.c:hop_timer_cb()` | **No** — requires `esp_wifi_set_channel()` |
+
+Currently, **every code change requires flashing to physical hardware** on COM7. This creates a bottleneck:
+- Build + flash cycle: ~20 seconds
+- Serial monitor: manual inspection
+- No automated CI (no ESP32-S3 in GitHub Actions runners)
+- Contributors without hardware cannot test firmware changes
+
+Espressif maintains an official QEMU fork (`github.com/espressif/qemu`) with ESP32-S3 machine support, including dual-core Xtensa LX7, flash mapping, UART, GPIO, timers, and FreeRTOS.
+
+## Decision
+
+Introduce a **comprehensive QEMU testing platform** for the ESP32-S3 CSI node firmware with nine capability layers:
+
+1. **Mock CSI generator** — compile-time synthetic CSI frame injection
+2. **QEMU runner** — automated build, run, and validation
+3. **Multi-node mesh simulation** — TDM and aggregation testing across QEMU instances
+4. **GDB remote debugging** — zero-cost breakpoint debugging without JTAG
+5. **Code coverage** — gcov/lcov integration for path analysis
+6. **Fuzz testing** — malformed input resilience for CSI parser, NVS, WASM
+7. **NVS provisioning matrix** — exhaustive config combination testing
+8. **Snapshot & replay** — sub-100ms state restore for fast iteration
+9. **Chaos testing** — fault injection for resilience validation
+
+---
+
+## Layer 1: Mock CSI Generator
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  ESP32-S3 Firmware                    │
+│                                                       │
+│  ┌─────────────┐    ┌──────────────────────────────┐ │
+│  │  Real WiFi   │    │  Mock CSI Generator          │ │
+│  │  CSI Callback │ OR │  (timer → synthetic frames)  │ │
+│  │  (HW only)   │    │  (QEMU + unit tests)         │ │
+│  └──────┬───────┘    └──────────┬───────────────────┘ │
+│         │                       │                     │
+│         └───────────┬───────────┘                     │
+│                     ▼                                 │
+│  ┌──────────────────────────────────────────────────┐ │
+│  │  edge_enqueue_csi() → SPSC ring → DSP Core 1    │ │
+│  │  ├── Biquad bandpass (breathing / heart rate)    │ │
+│  │  ├── Phase unwrapping + Welford stats            │ │
+│  │  ├── Top-K subcarrier selection                  │ │
+│  │  ├── Presence detection (adaptive threshold)     │ │
+│  │  ├── Fall detection (phase acceleration)         │ │
+│  │  └── Multi-person vitals clustering              │ │
+│  └──────────────────┬───────────────────────────────┘ │
+│                     ▼                                 │
+│  ┌──────────────────────────────────────────────────┐ │
+│  │  csi_serialize_frame() → ADR-018 binary format   │ │
+│  │  stream_sender_send() → UDP to aggregator        │ │
+│  │  edge vitals packet   → 0xC5110002 (32 bytes)    │ │
+│  └──────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+### Mock CSI Generator Design
+
+When `CONFIG_CSI_MOCK_ENABLED=y` (Kconfig option), the build replaces `esp_wifi_set_csi_config()` / `esp_wifi_set_csi_rx_cb()` with a periodic timer that injects synthetic CSI frames:
+
+```c
+// mock_csi.c — synthetic CSI frame generator
+
+#define MOCK_CSI_INTERVAL_MS   50   // 20 Hz (matches real CSI rate)
+#define MOCK_N_SUBCARRIERS     52   // HT20 mode
+#define MOCK_IQ_LEN            (MOCK_N_SUBCARRIERS * 2)  // I + Q bytes
+
+typedef struct {
+    uint8_t  scenario;        // 0=empty, 1=person_static, 2=person_walking, 3=fall
+    uint32_t frame_count;
+    float    person_x;        // Simulated position [0..1]
+    float    person_speed;    // Movement speed per frame
+    uint8_t  breathing_phase; // Simulated breathing cycle
+} mock_state_t;
+
+// Generates realistic CSI I/Q data:
+// - Empty room: Gaussian noise + stable phase (low variance)
+// - Static person: Phase shift proportional to distance, breathing modulation
+// - Walking person: Progressive phase drift + Doppler-like amplitude change
+// - Fall event: Sudden phase acceleration spike
+void mock_generate_csi_frame(mock_state_t *state, wifi_csi_info_t *out_info);
+```
+
+### Signal Model
+
+The synthetic CSI generator models subcarrier amplitude and phase as:
+
+```
+A_k(t) = A_base + A_person * exp(-d_k²/σ²) + noise
+φ_k(t) = φ_base + (2π * d / λ) + breathing_mod(t) + noise
+
+where:
+  k         = subcarrier index
+  d_k       = simulated distance effect on subcarrier k
+  A_person  = amplitude perturbation from human body (scenario-dependent)
+  d         = simulated person-to-antenna distance
+  λ         = wavelength at subcarrier frequency
+  breathing_mod(t) = sin(2π * f_breath * t) * amplitude_breath
+  noise     = Gaussian, σ tuned to match real ESP32-S3 CSI noise floor (~-90 dBm)
+```
+
+This model exercises:
+- Presence detection (amplitude variance exceeds threshold)
+- Breathing rate extraction (periodic phase modulation at 0.1-0.5 Hz)
+- Fall detection (sudden phase acceleration exceeding `fall_thresh`)
+- Multi-person separation (distinct subcarrier groups with different breathing frequencies)
+
+### Scenarios
+
+| ID | Scenario | Duration | Expected Output |
+|----|----------|----------|-----------------|
+| 0 | Empty room | 10s | `presence=0`, `motion_energy < thresh` |
+| 1 | Static person | 10s | `presence=1`, `breathing_rate ∈ [10,25]`, `fall=0` |
+| 2 | Walking person | 10s | `presence=1`, `motion_energy > 0.5`, `fall=0` |
+| 3 | Fall event | 5s | `fall=1` flag set, `motion_energy` spike |
+| 4 | Multi-person | 15s | `n_persons=2`, independent breathing rates |
+| 5 | Channel sweep | 5s | Frames on channels 1, 6, 11 in sequence |
+| 6 | MAC filter test | 5s | Frames with wrong MAC are dropped (counter check) |
+| 7 | Ring buffer overflow | 3s | 1000 frames in 100ms burst, graceful drop |
+| 8 | Boundary RSSI | 5s | RSSI sweeps -127 to 0, no crash |
+| 9 | Zero-length frame | 2s | `iq_len=0` frames, serialize returns 0 |
+
+---
+
+## Layer 2: QEMU Runner & CI
+
+### QEMU Runner Script
+
+```bash
+#!/bin/bash
+# scripts/qemu-esp32s3-test.sh
+
+set -euo pipefail
+
+FIRMWARE_DIR="firmware/esp32-csi-node"
+BUILD_DIR="$FIRMWARE_DIR/build"
+QEMU_BIN="${QEMU_PATH:-qemu-system-xtensa}"
+FLASH_IMAGE="$BUILD_DIR/qemu_flash.bin"
+LOG_FILE="$BUILD_DIR/qemu_output.log"
+TIMEOUT_SEC="${QEMU_TIMEOUT:-60}"
+
+echo "=== QEMU ESP32-S3 Firmware Test ==="
+
+# 1. Build with mock CSI enabled
+echo "[1/4] Building firmware (mock CSI mode)..."
+idf.py -C "$FIRMWARE_DIR" \
+  -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.qemu" \
+  build
+
+# 2. Merge binaries into single flash image
+echo "[2/4] Creating merged flash image..."
+esptool.py --chip esp32s3 merge_bin -o "$FLASH_IMAGE" \
+  --flash_mode dio --flash_freq 80m --flash_size 8MB \
+  0x0     "$BUILD_DIR/bootloader/bootloader.bin" \
+  0x8000  "$BUILD_DIR/partition_table/partition-table.bin" \
+  0xf000  "$BUILD_DIR/ota_data_initial.bin" \
+  0x20000 "$BUILD_DIR/esp32-csi-node.bin"
+
+# 3. Optionally inject pre-provisioned NVS partition
+if [ -f "$BUILD_DIR/nvs_test.bin" ]; then
+  echo "[2b] Injecting pre-provisioned NVS partition..."
+  dd if="$BUILD_DIR/nvs_test.bin" of="$FLASH_IMAGE" \
+    bs=1 seek=$((0x9000)) conv=notrunc
+fi
+
+# 4. Run in QEMU with timeout, capture UART output
+echo "[3/4] Running QEMU (timeout: ${TIMEOUT_SEC}s)..."
+timeout "$TIMEOUT_SEC" "$QEMU_BIN" \
+  -machine esp32s3 \
+  -nographic \
+  -drive file="$FLASH_IMAGE",if=mtd,format=raw \
+  -serial mon:stdio \
+  -no-reboot \
+  2>&1 | tee "$LOG_FILE" || true
+
+# 5. Validate expected output
+echo "[4/4] Validating output..."
+python3 scripts/validate_qemu_output.py "$LOG_FILE"
+```
+
+### QEMU sdkconfig overlay (`sdkconfig.qemu`)
+
+```
+# Enable mock CSI generator (disables real WiFi CSI)
+CONFIG_CSI_MOCK_ENABLED=y
+
+# Skip WiFi STA connection (no AP in QEMU)
+CONFIG_CSI_MOCK_SKIP_WIFI_CONNECT=y
+
+# Run all scenarios sequentially
+CONFIG_CSI_MOCK_SCENARIO=255
+
+# Use loopback for UDP (QEMU SLIRP provides 10.0.2.x network)
+CONFIG_CSI_TARGET_IP="10.0.2.2"
+
+# Shorter test durations
+CONFIG_CSI_MOCK_SCENARIO_DURATION_MS=5000
+
+# Enable verbose logging for validation
+CONFIG_LOG_DEFAULT_LEVEL_INFO=y
+CONFIG_CSI_MOCK_LOG_FRAMES=y
+```
+
+### Output Validation Script
+
+`scripts/validate_qemu_output.py` parses the UART log and checks:
+
+| Check | Pass Criteria | Severity |
+|-------|---------------|----------|
+| Boot | `app_main()` called, no panic/assert | FATAL |
+| NVS load | `nvs_config:` log line present | FATAL |
+| Mock CSI init | `mock_csi: Starting mock CSI generator` | FATAL |
+| Frame generation | `mock_csi: Generated N frames` where N > 0 | ERROR |
+| Edge pipeline | `edge_processing: DSP task started on Core 1` | ERROR |
+| Vitals output | At least one `vitals:` log line with valid BPM | ERROR |
+| Presence detection | `presence=1` appears during person scenarios | WARN |
+| Fall detection | `fall=1` appears during fall scenario | WARN |
+| MAC filter | `csi_collector: MAC filter dropped N frames` where N > 0 | WARN |
+| ADR-018 serialize | `csi_collector: Serialized N frames` where N > 0 | ERROR |
+| No crash | No `Guru Meditation Error`, no `assert failed`, no `abort()` | FATAL |
+| Clean exit | Firmware reaches end of scenario sequence | ERROR |
+| Heap OK | No `HEAP_ERROR` or `out of memory` | FATAL |
+| Stack OK | No `Stack overflow` detected | FATAL |
+
+Exit codes: `0` = all pass, `1` = WARN only, `2` = ERROR, `3` = FATAL
+
+### CI Workflow
+
+```yaml
+# .github/workflows/firmware-qemu.yml
+name: Firmware QEMU Tests
+on:
+  push:
+    paths: ['firmware/**']
+  pull_request:
+    paths: ['firmware/**']
+
+jobs:
+  qemu-test:
+    runs-on: ubuntu-latest
+    container:
+      image: espressif/idf:v5.4
+    strategy:
+      matrix:
+        scenario: [default, nvs-full, nvs-edge-tier0, nvs-tdm-3node]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Espressif QEMU
+        run: |
+          apt-get update && apt-get install -y libslirp-dev libglib2.0-dev ninja-build
+          git clone --depth 1 https://github.com/espressif/qemu.git /tmp/qemu
+          cd /tmp/qemu
+          ./configure --target-list=xtensa-softmmu --enable-slirp
+          make -j$(nproc)
+          cp build/qemu-system-xtensa /usr/local/bin/
+        env:
+          QEMU_PATH: /usr/local/bin/qemu-system-xtensa
+
+      - name: Prepare NVS for scenario
+        run: |
+          case "${{ matrix.scenario }}" in
+            nvs-full)
+              python firmware/esp32-csi-node/provision.py --dry-run \
+                --port dummy --ssid "TestWiFi" --password "test1234" \
+                --target-ip "10.0.2.2" --target-port 5005 \
+                --channel 6 --filter-mac AA:BB:CC:DD:EE:FF \
+                --node-id 1 --edge-tier 2
+              cp nvs_provision.bin firmware/esp32-csi-node/build/nvs_test.bin
+              ;;
+            nvs-edge-tier0)
+              python firmware/esp32-csi-node/provision.py --dry-run \
+                --port dummy --edge-tier 0 --node-id 5
+              cp nvs_provision.bin firmware/esp32-csi-node/build/nvs_test.bin
+              ;;
+            nvs-tdm-3node)
+              python firmware/esp32-csi-node/provision.py --dry-run \
+                --port dummy --tdm-slot 1 --tdm-total 3 --node-id 1
+              cp nvs_provision.bin firmware/esp32-csi-node/build/nvs_test.bin
+              ;;
+          esac
+
+      - name: Build firmware (mock CSI mode)
+        run: |
+          cd firmware/esp32-csi-node
+          idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.qemu" set-target esp32s3
+          idf.py build
+
+      - name: Run QEMU tests
+        run: bash scripts/qemu-esp32s3-test.sh
+        env:
+          QEMU_PATH: /usr/local/bin/qemu-system-xtensa
+          QEMU_TIMEOUT: 90
+
+      - name: Upload QEMU log
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: qemu-output-${{ matrix.scenario }}
+          path: firmware/esp32-csi-node/build/qemu_output.log
+```
+
+---
+
+## Layer 3: Multi-Node Mesh Simulation
+
+Run multiple QEMU instances with TAP networking to test TDM slot coordination and multi-node aggregation.
+
+### Architecture
+
+```
+┌──────────┐   ┌──────────┐   ┌──────────┐
+│ QEMU #0  │   │ QEMU #1  │   │ QEMU #2  │
+│ slot=0   │   │ slot=1   │   │ slot=2   │
+│ node_id=0│   │ node_id=1│   │ node_id=2│
+└────┬─────┘   └────┬─────┘   └────┬─────┘
+     │              │              │
+     └──────────┬───┴──────────────┘
+                ▼
+        ┌───────────────┐
+        │ TAP bridge    │
+        │ (10.0.0.0/24) │
+        └───────┬───────┘
+                ▼
+        ┌───────────────┐
+        │ Rust aggregator│
+        │ (UDP :5005)   │
+        └───────────────┘
+```
+
+### Multi-Node Runner
+
+```bash
+#!/bin/bash
+# scripts/qemu-mesh-test.sh — run 3 QEMU nodes + Rust aggregator
+
+set -euo pipefail
+
+N_NODES=${1:-3}
+AGGREGATOR_PORT=5005
+BRIDGE="qemu-br0"
+
+# Create bridge
+ip link add "$BRIDGE" type bridge
+ip addr add 10.0.0.1/24 dev "$BRIDGE"
+ip link set "$BRIDGE" up
+
+# Build flash images with per-node NVS
+for i in $(seq 0 $((N_NODES - 1))); do
+  python firmware/esp32-csi-node/provision.py --dry-run \
+    --port dummy --node-id "$i" --tdm-slot "$i" --tdm-total "$N_NODES" \
+    --target-ip 10.0.0.1 --target-port "$AGGREGATOR_PORT"
+  cp nvs_provision.bin "build/nvs_node${i}.bin"
+
+  # Inject NVS into per-node flash image
+  cp build/qemu_flash.bin "build/qemu_flash_node${i}.bin"
+  dd if="build/nvs_node${i}.bin" of="build/qemu_flash_node${i}.bin" \
+    bs=1 seek=$((0x9000)) conv=notrunc
+done
+
+# Start Rust aggregator in background
+cargo run -p wifi-densepose-hardware --bin aggregator -- \
+  --listen 0.0.0.0:${AGGREGATOR_PORT} \
+  --expect-nodes "$N_NODES" \
+  --output build/mesh_test_results.json &
+AGGREGATOR_PID=$!
+
+# Launch QEMU nodes
+for i in $(seq 0 $((N_NODES - 1))); do
+  TAP="tap${i}"
+  ip tuntap add "$TAP" mode tap
+  ip link set "$TAP" master "$BRIDGE"
+  ip link set "$TAP" up
+
+  qemu-system-xtensa \
+    -machine esp32s3 \
+    -nographic \
+    -drive file="build/qemu_flash_node${i}.bin",if=mtd,format=raw \
+    -serial file:"build/qemu_node${i}.log" \
+    -nic tap,ifname="$TAP",script=no,downscript=no \
+    -no-reboot &
+  echo "Started QEMU node $i (PID: $!)"
+done
+
+# Wait for test duration
+sleep 30
+
+# Validate results
+kill $AGGREGATOR_PID 2>/dev/null || true
+python3 scripts/validate_mesh_test.py build/mesh_test_results.json --nodes "$N_NODES"
+```
+
+### Mesh Validation Checks
+
+| Check | Pass Criteria |
+|-------|---------------|
+| All nodes booted | N distinct `node_id` values in received frames |
+| TDM ordering | Slot 0 frames arrive before slot 1 within each TDM cycle |
+| No slot collision | No two frames from different nodes with overlapping timestamps within TDM window |
+| Frame count balance | Each node contributes ±10% of total frames |
+| ADR-018 compliance | All frames have valid magic `0xC5110001` and correct node IDs |
+| Vitals per node | Each node produces independent vitals packets |
+
+---
+
+## Layer 4: GDB Remote Debugging
+
+QEMU provides a built-in GDB stub for zero-cost debugging without JTAG hardware.
+
+### Usage
+
+```bash
+# Launch QEMU with GDB stub (paused at boot)
+qemu-system-xtensa \
+  -machine esp32s3 \
+  -nographic \
+  -drive file=build/qemu_flash.bin,if=mtd,format=raw \
+  -serial mon:stdio \
+  -s -S   # -s = GDB on :1234, -S = pause at start
+
+# In another terminal: attach GDB
+xtensa-esp-elf-gdb build/esp32-csi-node.elf \
+  -ex "target remote :1234" \
+  -ex "b edge_processing.c:dsp_task" \
+  -ex "b csi_collector.c:wifi_csi_callback" \
+  -ex "b mock_csi.c:mock_generate_csi_frame" \
+  -ex "watch g_nvs_config.csi_channel" \
+  -ex "continue"
+```
+
+### Key Breakpoint Locations
+
+| Breakpoint | Purpose |
+|-----------|---------|
+| `edge_processing.c:dsp_task` | DSP consumer loop entry |
+| `edge_processing.c:presence_detect` | Threshold comparison |
+| `edge_processing.c:fall_detect` | Phase acceleration check |
+| `csi_collector.c:wifi_csi_callback` | Frame ingestion (or mock injection point) |
+| `csi_collector.c:csi_serialize_frame` | ADR-018 serialization |
+| `nvs_config.c:nvs_config_load` | NVS parse logic |
+| `wasm_runtime.c:wasm_on_csi` | WASM module dispatch |
+| `mock_csi.c:mock_generate_csi_frame` | Synthetic frame generation |
+
+### VS Code Integration
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [{
+    "name": "QEMU ESP32-S3 Debug",
+    "type": "cppdbg",
+    "request": "launch",
+    "program": "${workspaceFolder}/firmware/esp32-csi-node/build/esp32-csi-node.elf",
+    "miDebuggerPath": "xtensa-esp-elf-gdb",
+    "miDebuggerServerAddress": "localhost:1234",
+    "setupCommands": [
+      { "text": "set remote hardware-breakpoint-limit 2" },
+      { "text": "set remote hardware-watchpoint-limit 2" }
+    ]
+  }]
+}
+```
+
+---
+
+## Layer 5: Code Coverage (gcov/lcov)
+
+### Build with Coverage
+
+```
+# sdkconfig.coverage (overlay)
+CONFIG_COMPILER_OPTIMIZATION_NONE=y
+CONFIG_GCOV_ENABLE=y
+CONFIG_APPTRACE_GCOV_ENABLE=y
+```
+
+### Coverage Collection
+
+```bash
+# After QEMU run, extract gcov data from flash dump
+esptool.py --chip esp32s3 read_flash 0x300000 0x100000 gcov_data.bin
+
+# Or use ESP-IDF's app_trace + gcov integration:
+# QEMU + GDB → "monitor gcov dump" → .gcda files
+
+# Generate HTML report
+lcov --capture --directory build --output-file coverage.info
+lcov --remove coverage.info '*/esp-idf/*' '*/test/*' --output-file coverage_filtered.info
+genhtml coverage_filtered.info --output-directory build/coverage_report
+```
+
+### Coverage Targets
+
+| Module | Target | Critical Paths |
+|--------|--------|---------------|
+| `edge_processing.c` | ≥80% | `dsp_task`, `biquad_filter`, `fall_detect`, `multi_person_cluster` |
+| `csi_collector.c` | ≥90% | `csi_serialize_frame`, `wifi_csi_callback`, MAC filter branch |
+| `nvs_config.c` | ≥95% | Every NVS key read path, default fallback paths |
+| `mock_csi.c` | ≥95% | All scenarios, all signal model branches |
+| `stream_sender.c` | ≥80% | Init, send, error paths |
+| `wasm_runtime.c` | ≥70% | Module load, dispatch, signature verify |
+
+---
+
+## Layer 6: Fuzz Testing
+
+### Fuzz Targets
+
+| Target | Input | Mutation Strategy | Looking For |
+|--------|-------|-------------------|-------------|
+| `csi_serialize_frame()` | Random `wifi_csi_info_t` | Extreme `len` (0, 65535), NULL `buf`, negative RSSI, channel 255 | Buffer overflow, NULL deref |
+| `nvs_config_load()` | Crafted NVS partition binary | Truncated strings, out-of-range u8/u16, missing keys, corrupt headers | Kconfig fallback, no crash |
+| `edge_enqueue_csi()` | Rapid-fire 10,000 frames | Vary `iq_len` (0 to `EDGE_MAX_IQ_BYTES+1`), randomize RSSI | Ring overflow, no data corruption |
+| `rvf_parser.c` | Malformed RVF network packets | Bad magic, truncated headers, oversized payloads | Parse rejection, no crash |
+| `wasm_upload.c` | Corrupt WASM blobs | Invalid magic, oversized modules, bad Ed25519 signatures, truncated | Rejection without crash, no code execution |
+| `csi_serialize_frame()` + `edge_enqueue_csi()` | Chained: generate → serialize → enqueue | End-to-end with random data | Pipeline integrity |
+
+### Implementation Approach
+
+```c
+// test/fuzz_csi_serialize.c — runs on host (not ESP32)
+// Compiled with: clang -fsanitize=fuzzer,address
+
+#include "csi_collector.h"
+
+int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
+    if (size < sizeof(wifi_csi_info_t)) return 0;
+
+    wifi_csi_info_t info;
+    memcpy(&info, data, sizeof(info));
+
+    // Point buf at remaining fuzz data
+    size_t remaining = size - sizeof(info);
+    uint8_t iq_buf[2048];
+    if (remaining > sizeof(iq_buf)) remaining = sizeof(iq_buf);
+    memcpy(iq_buf, data + sizeof(info), remaining);
+    info.buf = iq_buf;
+    info.len = (int)remaining;
+
+    uint8_t out[4096];
+    csi_serialize_frame(&info, out, sizeof(out));
+    return 0;
+}
+```
+
+### Fuzz CI Job
+
+```yaml
+  fuzz-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build fuzz targets
+        run: |
+          cd firmware/esp32-csi-node/test
+          clang -fsanitize=fuzzer,address -I../main \
+            fuzz_csi_serialize.c ../main/csi_collector.c \
+            -o fuzz_serialize
+      - name: Run fuzz (5 min per target)
+        run: |
+          cd firmware/esp32-csi-node/test
+          timeout 300 ./fuzz_serialize corpus/ || true
+      - name: Upload crashes
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-crashes
+          path: firmware/esp32-csi-node/test/crash-*
+```
+
+---
+
+## Layer 7: NVS Provisioning Matrix
+
+### Config Combinations
+
+| Config | NVS Values | Validates |
+|--------|-----------|-----------|
+| `default` | (empty NVS) | Kconfig fallback paths |
+| `wifi-only` | ssid, password | Basic provisioning |
+| `full-adr060` | channel=6, filter_mac=AA:BB:CC:DD:EE:FF | Channel override + MAC filter |
+| `edge-tier0` | edge_tier=0 | Raw CSI passthrough (no DSP) |
+| `edge-tier1` | edge_tier=1, pres_thresh=100, fall_thresh=2000 | Stats-only mode |
+| `edge-tier2-custom` | edge_tier=2, vital_win=128, vital_int=500, subk_count=16 | Full vitals with custom params |
+| `tdm-3node` | tdm_slot=1, tdm_nodes=3, node_id=1 | TDM mesh timing |
+| `wasm-signed` | wasm_max=4, wasm_verify=1, wasm_pubkey=<32 bytes> | WASM with Ed25519 verification |
+| `wasm-unsigned` | wasm_max=2, wasm_verify=0 | WASM without signature check |
+| `5ghz-channel` | channel=36, filter_mac=... | 5 GHz CSI collection |
+| `boundary-max` | target_port=65535, node_id=255, top_k=32, vital_win=256 | Max-range values |
+| `boundary-min` | target_port=1, node_id=0, top_k=1, vital_win=32 | Min-range values |
+| `power-save` | power_duty=10, edge_tier=0 | Low-power mode |
+| `corrupt-nvs` | (manually crafted partial/corrupt partition) | Graceful fallback to defaults |
+
+### Automated Matrix Generation
+
+```python
+# scripts/generate_nvs_matrix.py
+# Generates all 14 NVS partition binaries for CI matrix
+
+CONFIGS = [
+    {"name": "default", "args": []},
+    {"name": "wifi-only", "args": ["--ssid", "Test", "--password", "test1234"]},
+    {"name": "full-adr060", "args": ["--channel", "6", "--filter-mac", "AA:BB:CC:DD:EE:FF",
+                                      "--ssid", "Test", "--password", "test"]},
+    {"name": "edge-tier0", "args": ["--edge-tier", "0"]},
+    # ... all 14 configs
+]
+```
+
+---
+
+## Layer 8: Snapshot & Replay
+
+### QEMU Snapshot Commands
+
+```bash
+# Save snapshot after boot + NVS load (skip 3s boot time)
+(qemu) savevm post_boot
+
+# Save after WiFi connect + first CSI frame
+(qemu) savevm post_connect
+
+# Save after edge pipeline calibration complete (~60s)
+(qemu) savevm post_calibration
+
+# Restore any snapshot (< 100ms)
+(qemu) loadvm post_connect
+```
+
+### Automated Snapshot Pipeline
+
+```bash
+# scripts/qemu-snapshot-test.sh
+
+# Phase 1: Create base snapshots (one-time, cached in CI)
+qemu-system-xtensa ... -monitor unix:qemu.sock,server,nowait &
+sleep 5
+echo "savevm post_boot" | socat - UNIX-CONNECT:qemu.sock
+sleep 10
+echo "savevm post_first_frame" | socat - UNIX-CONNECT:qemu.sock
+
+# Phase 2: Run quick tests from snapshots (< 1s each)
+for test in test_presence test_fall test_multi_person; do
+  echo "loadvm post_first_frame" | socat - UNIX-CONNECT:qemu.sock
+  echo "cont" | socat - UNIX-CONNECT:qemu.sock
+  sleep 2  # Run test scenario
+  # Validate output
+done
+```
+
+### Performance Impact
+
+| Operation | Without Snapshots | With Snapshots |
+|-----------|-------------------|----------------|
+| Full boot + NVS + WiFi mock | ~5 seconds | ~5 seconds (first run) |
+| Run single scenario | ~5s boot + ~5s test = 10s | ~0.1s restore + ~5s test = 5.1s |
+| Run all 10 scenarios | ~100 seconds | ~51 seconds (49% faster) |
+| Run 14 NVS configs × 10 scenarios | ~23 minutes | ~12 minutes (48% faster) |
+
+---
+
+## Layer 9: Chaos Testing
+
+### Fault Injection Table
+
+| Fault | Injection Method | Expected Behavior | Severity |
+|-------|-----------------|-------------------|----------|
+| WiFi disconnect | Timer kills mock WiFi connection after N frames | Reconnect attempt, CSI pauses and resumes | HIGH |
+| Ring buffer overflow | Burst 1000 frames in 100ms | Frame drop counter increments, no crash, no data corruption | HIGH |
+| NVS corruption | Flash image with partial-write NVS partition | Falls back to Kconfig defaults, logs warning | MEDIUM |
+| Stack overflow | Deep recursion in WASM module callback | Watchdog fires, task restarts, no hang | HIGH |
+| Heap exhaustion | `malloc` returns NULL after N allocations | Graceful degradation, logs OOM, continues operation | HIGH |
+| Timer starvation | Block DSP task for 500ms | Frames dropped from ring, no deadlock, recovers | MEDIUM |
+| UDP send failure | SLIRP network down | `stream_sender_send` returns -1, error counter increments | LOW |
+| Corrupt CSI frame | Inject frame with invalid magic in I/Q data | Edge pipeline rejects, increments error counter | LOW |
+| NVS write during read | Concurrent NVS open for write while config loads | No corruption, NVS handle isolation | MEDIUM |
+
+### Chaos Runner
+
+```bash
+# scripts/qemu-chaos-test.sh
+
+# Run with fault injection enabled
+qemu-system-xtensa ... \
+  -monitor unix:qemu.sock,server,nowait &
+
+# Inject faults via GDB or monitor commands
+for fault in wifi_kill heap_exhaust ring_flood; do
+  echo "[CHAOS] Injecting: $fault"
+  python3 scripts/inject_fault.py --socket qemu.sock --fault "$fault"
+  sleep 5
+  python3 scripts/check_health.py --log "$LOG_FILE" --after-fault "$fault"
+done
+```
+
+---
+
+## Implementation Plan
+
+| Phase | Layer | Deliverables | Effort | Priority |
+|-------|-------|-------------|--------|----------|
+| **P1** | L1 + L2 | `mock_csi.c`, `mock_csi.h`, `Kconfig.projbuild`, `sdkconfig.qemu`, `qemu-esp32s3-test.sh`, `validate_qemu_output.py`, `firmware-qemu.yml` | 2 days | Critical |
+| **P2** | L4 + L5 | GDB launch config, `sdkconfig.coverage`, lcov integration, coverage CI job | 1 day | High |
+| **P3** | L7 | `generate_nvs_matrix.py`, 14 NVS configs, CI matrix expansion | 1 day | High |
+| **P4** | L6 | `fuzz_csi_serialize.c`, `fuzz_nvs_config.c`, `fuzz_edge_enqueue.c`, fuzz CI job | 2 days | High |
+| **P5** | L3 | `qemu-mesh-test.sh`, TAP bridge setup, `validate_mesh_test.py`, Rust aggregator integration | 3 days | High |
+| **P6** | L8 | Snapshot pipeline, cached base images in CI | 0.5 day | Medium |
+| **P7** | L9 | `inject_fault.py`, `check_health.py`, `qemu-chaos-test.sh`, 9 fault scenarios | 2 days | Medium |
+| **P8** | Performance | Instruction counting, DSP cycle profiling, optimization report | 1 day | Low |
+
+**Total**: ~12.5 days across 8 phases
+
+---
+
+## File Layout
+
+```
+firmware/esp32-csi-node/
+├── main/
+│   ├── mock_csi.c              # NEW — synthetic CSI frame generator
+│   ├── mock_csi.h              # NEW — mock API + scenario definitions
+│   ├── Kconfig.projbuild       # MODIFIED — CONFIG_CSI_MOCK_* options
+│   ├── CMakeLists.txt          # MODIFIED — conditional mock_csi.c inclusion
+│   └── ... (existing files unchanged)
+├── test/
+│   ├── fuzz_csi_serialize.c    # NEW — libFuzzer target for serialization
+│   ├── fuzz_nvs_config.c       # NEW — libFuzzer target for NVS parsing
+│   ├── fuzz_edge_enqueue.c     # NEW — libFuzzer target for ring buffer
+│   └── corpus/                 # NEW — seed inputs for fuzz targets
+├── sdkconfig.qemu             # NEW — QEMU-specific sdkconfig overlay
+├── sdkconfig.coverage         # NEW — gcov-enabled sdkconfig overlay
+└── ...
+
+scripts/
+├── qemu-esp32s3-test.sh       # NEW — single-node QEMU runner
+├── qemu-mesh-test.sh          # NEW — multi-node mesh runner
+├── qemu-chaos-test.sh         # NEW — chaos/fault injection runner
+├── validate_qemu_output.py    # NEW — UART log validation
+├── validate_mesh_test.py      # NEW — mesh test validation
+├── generate_nvs_matrix.py     # NEW — NVS config matrix generator
+├── inject_fault.py            # NEW — QEMU fault injection
+└── check_health.py            # NEW — post-fault health checker
+
+.vscode/
+└── launch.json                # MODIFIED — add QEMU GDB debug config
+
+.github/workflows/
+└── firmware-qemu.yml          # NEW — CI workflow with matrix
+```
+
+---
+
+## Consequences
+
+### Benefits
+
+1. **No hardware required** — contributors validate firmware changes with QEMU alone
+2. **Automated CI** — every PR touching `firmware/` runs 14 NVS configs × 10 scenarios in parallel
+3. **10× faster iteration** — snapshot restore in <100ms vs 20s flash cycle
+4. **Security hardening** — fuzz testing catches buffer overflows, NULL derefs, and parser bugs before they reach hardware
+5. **Mesh validation** — multi-node TDM tested without 3 physical ESP32s
+6. **Coverage visibility** — lcov reports show untested edge processing paths
+7. **Resilience proof** — chaos tests verify firmware recovers from WiFi drops, OOM, and ring overflow
+8. **GDB debugging** — set breakpoints on DSP pipeline without JTAG adapter
+9. **Regression detection** — boot failures, NVS parsing errors, and FreeRTOS deadlocks caught in CI
+
+### Limitations
+
+1. **No real WiFi/CSI** — QEMU cannot emulate the ESP32-S3 WiFi radio or CSI extraction hardware
+2. **Synthetic CSI fidelity** — mock frames approximate real CSI patterns but don't capture real-world multipath, interference, or antenna characteristics
+3. **Timing differences** — QEMU timing is not cycle-accurate; FreeRTOS tick rates may differ from hardware
+4. **No peripheral testing** — I2C display, real GPIO, and light-sleep power management cannot be tested
+5. **QEMU build requirement** — Espressif's QEMU fork must be built from source (not in Ubuntu packages)
+6. **Coverage overhead** — gcov-enabled builds are ~2× slower in QEMU
+
+### What QEMU Testing Covers vs Requires Hardware
+
+| Test Domain | QEMU | Hardware |
+|-------------|------|----------|
+| Boot + NVS config (14 configs) | Full | Full |
+| Edge DSP pipeline (biquad, Welford, top-K) | Full | Full |
+| ADR-018 frame serialization | Full | Full |
+| Vitals packet generation (0xC5110002) | Full | Full |
+| WASM module loading + execution | Full | Full |
+| Multi-node TDM mesh (3+ nodes) | Full (TAP) | Full |
+| Fuzz testing (CSI parser, NVS) | Full | N/A |
+| Code coverage analysis | Full | Partial |
+| GDB breakpoint debugging | Full | Full (JTAG) |
+| Chaos/fault injection | Full | Manual |
+| OTA update flow | Partial (HTTP mock) | Full |
+| Real WiFi connection | No | Full |
+| Real CSI data quality | No | Full |
+| Channel hopping on RF | No | Full |
+| MAC filter on real frames | No | Full |
+| Power management (light-sleep) | No | Full |
+| Display rendering (OLED) | No | Full |
+| UDP over real network | No | Full |
+
+---
+
+## Alternatives Considered
+
+### 1. Host-native unit tests (no QEMU)
+Extract pure C functions (`csi_serialize_frame`, edge DSP math) and compile/test on host with CMock/Unity. Simpler but doesn't test FreeRTOS integration, NVS, or boot sequence.
+
+**Verdict**: Complementary — do both. Host unit tests for math, QEMU for integration. Fuzz targets (Layer 6) already use host-native compilation.
+
+### 2. Hardware-in-the-loop CI (real ESP32 on runner)
+Use a self-hosted GitHub Actions runner with a physical ESP32-S3 attached.
+
+**Verdict**: Valuable but expensive and fragile. QEMU covers ~85% of test cases (up from 70% with all 9 layers). Add HIL later for real CSI validation only.
+
+### 3. Docker-based ESP-IDF build only (no runtime test)
+Just verify the firmware compiles in CI without running it.
+
+**Verdict**: Already possible but insufficient — compilation doesn't catch runtime bugs (stack overflow, NVS parsing errors, FreeRTOS deadlocks).
+
+### 4. Renode emulator
+Alternative to QEMU with better peripheral modeling for some platforms.
+
+**Verdict**: Renode has ESP32 support but ESP32-S3 support is less mature than Espressif's own QEMU fork. Revisit if Renode adds full S3 support.
+
+---
+
+## References
+
+- [Espressif QEMU fork](https://github.com/espressif/qemu) — official ESP32/S3/C3/H2 support
+- [ESP-IDF QEMU guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/tools/qemu.html)
+- [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) — LLVM-based coverage-guided fuzzing
+- [lcov](https://github.com/linux-test-project/lcov) — Linux test coverage visualization
+- ADR-018: Binary CSI frame format (magic `0xC5110001`)
+- ADR-039: Edge intelligence pipeline (biquad, vitals, fall detection)
+- ADR-040: WASM programmable sensing runtime
+- ADR-057: Build-time CSI guard (`CONFIG_ESP_WIFI_CSI_ENABLED`)
+- ADR-060: Channel override and MAC address filter
@@ -12,6 +12,7 @@
 */

 #include "csi_collector.h"
+#include "nvs_config.h"
 #include "stream_sender.h"
 #include "edge_processing.h"

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

+/* ADR-060: Access the global NVS config for MAC filter and channel override. */
+extern nvs_config_t g_nvs_config;
+
 /* 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!"
@@ -151,6 +155,14 @@ size_t csi_serialize_frame(const wifi_csi_info_t *info, uint8_t *buf, size_t buf
 static void wifi_csi_callback(void *ctx, wifi_csi_info_t *info)
 {
    (void)ctx;
+
+    /* ADR-060: MAC address filtering — drop frames from non-matching sources. */
+    if (g_nvs_config.filter_mac_set) {
+        if (memcmp(info->mac, g_nvs_config.filter_mac, 6) != 0) {
+            return;  /* Source MAC doesn't match filter — skip frame. */
+        }
+    }
+
    s_cb_count++;

    if (s_cb_count <= 3 || (s_cb_count % 100) == 0) {
@@ -203,6 +215,29 @@ static void wifi_promiscuous_cb(void *buf, wifi_promiscuous_pkt_type_t type)

 void csi_collector_init(void)
 {
+    /* ADR-060: Determine the CSI channel.
+     * Priority: 1) NVS override (--channel), 2) connected AP channel, 3) Kconfig default. */
+    uint8_t csi_channel = (uint8_t)CONFIG_CSI_WIFI_CHANNEL;
+
+    if (g_nvs_config.csi_channel > 0) {
+        /* Explicit NVS override via provision.py --channel */
+        csi_channel = g_nvs_config.csi_channel;
+        ESP_LOGI(TAG, "Using NVS channel override: %u", (unsigned)csi_channel);
+    } else {
+        /* Auto-detect from connected AP */
+        wifi_ap_record_t ap_info;
+        if (esp_wifi_sta_get_ap_info(&ap_info) == ESP_OK && ap_info.primary > 0) {
+            csi_channel = ap_info.primary;
+            ESP_LOGI(TAG, "Auto-detected AP channel: %u", (unsigned)csi_channel);
+        } else {
+            ESP_LOGW(TAG, "Could not detect AP channel, using Kconfig default: %u",
+                     (unsigned)csi_channel);
+        }
+    }
+
+    /* Update the hop table's first channel to match. */
+    s_hop_channels[0] = csi_channel;
+
    /* Enable promiscuous mode — required for reliable CSI callbacks.
     * Without this, CSI only fires on frames destined to this station,
     * which may be very infrequent on a quiet network. */
@@ -230,8 +265,15 @@ void csi_collector_init(void)
    ESP_ERROR_CHECK(esp_wifi_set_csi_rx_cb(wifi_csi_callback, NULL));
    ESP_ERROR_CHECK(esp_wifi_set_csi(true));

-    ESP_LOGI(TAG, "CSI collection initialized (node_id=%d, channel=%d)",
-             CONFIG_CSI_NODE_ID, CONFIG_CSI_WIFI_CHANNEL);
+    if (g_nvs_config.filter_mac_set) {
+        ESP_LOGI(TAG, "MAC filter active: %02x:%02x:%02x:%02x:%02x:%02x",
+                 g_nvs_config.filter_mac[0], g_nvs_config.filter_mac[1],
+                 g_nvs_config.filter_mac[2], g_nvs_config.filter_mac[3],
+                 g_nvs_config.filter_mac[4], g_nvs_config.filter_mac[5]);
+    }
+
+    ESP_LOGI(TAG, "CSI collection initialized (node_id=%d, channel=%u)",
+             CONFIG_CSI_NODE_ID, (unsigned)csi_channel);
 }

 /* ---- ADR-029: Channel hopping ---- */
@@ -91,6 +91,11 @@ void nvs_config_load(nvs_config_t *cfg)
    cfg->wasm_verify = 0;  /* Kconfig disabled signature verification. */
 #endif

+    /* ADR-060: Channel override and MAC filter defaults. */
+    cfg->csi_channel = 0;  /* 0 = auto-detect from connected AP. */
+    cfg->filter_mac_set = 0;
+    memset(cfg->filter_mac, 0, 6);
+
    /* Try to override from NVS */
    nvs_handle_t handle;
    esp_err_t err = nvs_open("csi_cfg", NVS_READONLY, &handle);
@@ -277,6 +282,26 @@ void nvs_config_load(nvs_config_t *cfg)
        ESP_LOGW(TAG, "wasm_verify=1 but no wasm_pubkey in NVS — uploads will be rejected");
    }

+    /* ADR-060: CSI channel override. */
+    uint8_t csi_ch_val;
+    if (nvs_get_u8(handle, "csi_channel", &csi_ch_val) == ESP_OK) {
+        if ((csi_ch_val >= 1 && csi_ch_val <= 14) || (csi_ch_val >= 36 && csi_ch_val <= 177)) {
+            cfg->csi_channel = csi_ch_val;
+            ESP_LOGI(TAG, "NVS override: csi_channel=%u", (unsigned)cfg->csi_channel);
+        } else {
+            ESP_LOGW(TAG, "NVS csi_channel=%u invalid, ignored", (unsigned)csi_ch_val);
+        }
+    }
+
+    /* ADR-060: MAC address filter (6-byte blob). */
+    size_t mac_len = 6;
+    if (nvs_get_blob(handle, "filter_mac", cfg->filter_mac, &mac_len) == ESP_OK && mac_len == 6) {
+        cfg->filter_mac_set = 1;
+        ESP_LOGI(TAG, "NVS override: filter_mac=%02x:%02x:%02x:%02x:%02x:%02x",
+                 cfg->filter_mac[0], cfg->filter_mac[1], cfg->filter_mac[2],
+                 cfg->filter_mac[3], cfg->filter_mac[4], cfg->filter_mac[5]);
+    }
+
    /* Validate tdm_slot_index < tdm_node_count */
    if (cfg->tdm_slot_index >= cfg->tdm_node_count) {
        ESP_LOGW(TAG, "tdm_slot_index=%u >= tdm_node_count=%u, clamping to 0",
@@ -50,6 +50,11 @@ typedef struct {
    uint8_t  wasm_verify;                    /**< Require Ed25519 signature for uploads. */
    uint8_t  wasm_pubkey[32];               /**< Ed25519 public key for WASM signature. */
    uint8_t  wasm_pubkey_valid;             /**< 1 if pubkey was loaded from NVS. */
+
+    /* ADR-060: Channel override and MAC address filtering */
+    uint8_t  csi_channel;                    /**< Explicit CSI channel override (0 = auto-detect). */
+    uint8_t  filter_mac[6];                  /**< MAC address to filter CSI frames. */
+    uint8_t  filter_mac_set;                 /**< 1 if filter_mac was loaded from NVS. */
 } nvs_config_t;

 /**
@@ -64,6 +64,13 @@ def build_nvs_csv(args):
        writer.writerow(["vital_int", "data", "u16", str(args.vital_int)])
    if args.subk_count is not None:
        writer.writerow(["subk_count", "data", "u8", str(args.subk_count)])
+    # ADR-060: Channel override and MAC filter
+    if args.channel is not None:
+        writer.writerow(["csi_channel", "data", "u8", str(args.channel)])
+    if args.filter_mac is not None:
+        mac_bytes = bytes(int(b, 16) for b in args.filter_mac.split(":"))
+        # NVS blob: write as hex-encoded string for CSV compatibility
+        writer.writerow(["filter_mac", "data", "hex2bin", mac_bytes.hex()])
    return buf.getvalue()


@@ -165,6 +172,10 @@ def main():
    parser.add_argument("--vital-win", type=int, help="Phase history window in frames (default: 300)")
    parser.add_argument("--vital-int", type=int, help="Vitals packet interval in ms (default: 1000)")
    parser.add_argument("--subk-count", type=int, help="Top-K subcarrier count (default: 32)")
+    # ADR-060: Channel override and MAC filter
+    parser.add_argument("--channel", type=int, help="CSI channel (1-14 for 2.4GHz, 36-177 for 5GHz). "
+                        "Overrides auto-detection from connected AP.")
+    parser.add_argument("--filter-mac", type=str, help="MAC address to filter CSI frames (AA:BB:CC:DD:EE:FF)")
    parser.add_argument("--dry-run", action="store_true", help="Generate NVS binary but don't flash")

    args = parser.parse_args()
@@ -176,6 +187,7 @@ def main():
        args.edge_tier is not None, args.pres_thresh is not None,
        args.fall_thresh is not None, args.vital_win is not None,
        args.vital_int is not None, args.subk_count is not None,
+        args.channel is not None, args.filter_mac is not None,
    ])
    if not has_value:
        parser.error("At least one config value must be specified")
@@ -186,6 +198,22 @@ def main():
    if args.tdm_slot is not None and args.tdm_slot >= args.tdm_total:
        parser.error(f"--tdm-slot ({args.tdm_slot}) must be less than --tdm-total ({args.tdm_total})")

+    # ADR-060: Validate channel and MAC filter
+    if args.channel is not None:
+        if not ((1 <= args.channel <= 14) or (36 <= args.channel <= 177)):
+            parser.error(f"--channel must be 1-14 (2.4GHz) or 36-177 (5GHz), got {args.channel}")
+    if args.filter_mac is not None:
+        parts = args.filter_mac.split(":")
+        if len(parts) != 6:
+            parser.error(f"--filter-mac must be in AA:BB:CC:DD:EE:FF format, got '{args.filter_mac}'")
+        try:
+            for p in parts:
+                val = int(p, 16)
+                if val < 0 or val > 255:
+                    raise ValueError
+        except ValueError:
+            parser.error(f"--filter-mac contains invalid hex bytes: '{args.filter_mac}'")
+
    print("Building NVS configuration:")
    if args.ssid:
        print(f"  WiFi SSID:     {args.ssid}")
@@ -212,6 +240,10 @@ def main():
        print(f"  Vital Interval:{args.vital_int} ms")
    if args.subk_count is not None:
        print(f"  Top-K Subcarr: {args.subk_count}")
+    if args.channel is not None:
+        print(f"  CSI Channel:   {args.channel}")
+    if args.filter_mac is not None:
+        print(f"  Filter MAC:    {args.filter_mac}")

    csv_content = build_nvs_csv(args)

@@ -3,15 +3,15 @@
 <head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>WiFi-DensePose — Dual-Modal Pose Estimation</title>
-  <link rel="stylesheet" href="pose-fusion/css/style.css?v=12">
+  <title>RuView — Dual-Modal Pose Estimation</title>
+  <link rel="stylesheet" href="pose-fusion/css/style.css?v=13">
 </head>
 <body>

  <!-- Header -->
  <header class="header">
    <div class="header-left">
-      <div class="logo"><span class="pi">&pi;</span> DensePose</div>
+      <div class="logo"><span class="pi">&pi;</span> RuView</div>
      <div class="header-title">Dual-Modal Pose Estimation — Live Video + WiFi CSI Fusion</div>
    </div>
    <div class="header-right">
@@ -184,11 +184,11 @@
    <!-- Bottom Bar -->
    <div class="bottom-bar">
      <div>
-        WiFi-DensePose &middot; Dual-Modal Pose Estimation &middot;
+        RuView &middot; Dual-Modal Pose Estimation &middot;
        Architecture: Conv2D &rarr; RuVector 6-Stage Attention (Flash+MHA+Hyperbolic+Linear+MoE+L/G) &rarr; Fusion &rarr; 26-Keypoint Pose
      </div>
      <div>
-        <a href="https://github.com/ruvnet/wifi-densepose">GitHub</a> &middot;
+        <a href="https://github.com/ruvnet/RuView">GitHub</a> &middot;
        CNN: <span id="cnn-backend">ruvector-cnn (loading…)</span> &middot;
        <a href="observatory.html">Observatory</a>
      </div>
@@ -196,6 +196,6 @@

  </div><!-- /main-grid -->

-  <script type="module" src="pose-fusion/js/main.js?v=12"></script>
+  <script type="module" src="pose-fusion/js/main.js?v=13"></script>
 </body>
 </html>
@@ -1,4 +1,4 @@
-/* WiFi-DensePose — Dual-Modal Pose Fusion Demo
+/* RuView — Dual-Modal Pose Fusion Demo
   Dark theme matching Observatory */

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&family=JetBrains+Mono:wght@400;600&display=swap');
@@ -193,6 +193,7 @@ body {
  color: var(--text-secondary);
  padding: 24px;
  z-index: 6;
+  background: radial-gradient(ellipse at center, rgba(0,210,120,0.08) 0%, rgba(8,12,20,0.95) 70%);
 }

 .camera-prompt button {
@@ -267,6 +267,12 @@ export class CsiSimulator {
      return;
    }

+    // Handle Blob data (convert to ArrayBuffer and re-process)
+    if (data instanceof Blob) {
+      data.arrayBuffer().then(ab => this._handleLiveFrame(ab)).catch(() => {});
+      return;
+    }
+
    // Handle binary ArrayBuffer frames (ADR-018 format)
    if (!(data instanceof ArrayBuffer)) return;
    const view = new DataView(data);
@@ -1,15 +1,15 @@
 /**
- * WiFi-DensePose — Dual-Modal Pose Estimation Demo
+ * RuView — Dual-Modal Pose Estimation Demo
 *
 * Main orchestration: video capture → CNN embedding → CSI processing → fusion → rendering
 */

-import { VideoCapture } from './video-capture.js?v=11';
-import { CsiSimulator } from './csi-simulator.js?v=11';
-import { CnnEmbedder } from './cnn-embedder.js?v=11';
-import { FusionEngine } from './fusion-engine.js?v=11';
-import { PoseDecoder } from './pose-decoder.js?v=11';
-import { CanvasRenderer } from './canvas-renderer.js?v=11';
+import { VideoCapture } from './video-capture.js?v=13';
+import { CsiSimulator } from './csi-simulator.js?v=13';
+import { CnnEmbedder } from './cnn-embedder.js?v=13';
+import { FusionEngine } from './fusion-engine.js?v=13';
+import { PoseDecoder } from './pose-decoder.js?v=13';
+import { CanvasRenderer } from './canvas-renderer.js?v=13';

 // === State ===
 let mode = 'dual';  // 'dual' | 'video' | 'csi'
@@ -344,10 +344,10 @@ function mainLoop(timestamp) {
  const rvEnergyEl = document.getElementById('rv-energy');
  const rvRefineEl = document.getElementById('rv-refine');
  const rvImpactEl = document.getElementById('rv-impact');
-  if (rvEnergyEl) rvEnergyEl.textContent = rvStats.energy.toFixed(2);
-  if (rvRefineEl) rvRefineEl.textContent = (rvStats.refinementMag * 1000).toFixed(1) + 'px';
+  if (rvEnergyEl) rvEnergyEl.textContent = (rvStats.energy || 0).toFixed(2);
+  if (rvRefineEl) rvRefineEl.textContent = ((rvStats.refinementMag || 0) * 1000).toFixed(1) + 'px';
  if (rvImpactEl) {
-    const impact = Math.min(100, rvStats.refinementMag * 5000);
+    const impact = Math.min(100, (rvStats.refinementMag || 0) * 5000);
    rvImpactEl.textContent = impact.toFixed(0) + '%';
  }
  // Pulse the pipeline stages when active
@@ -361,7 +361,7 @@ function mainLoop(timestamp) {
  // One-time diagnostic
  if (!_diagDone) {
    _diagDone = true;
-    console.log(`[PoseFusion] frame 1 OK — mode=${mode}, csi.bufLen=${csiSimulator.amplitudeBuffer.length}, embPts=${embPoints.fused.length}, rssi=${csiSimulator.rssiDbm.toFixed(1)}`);
+    console.log(`[PoseFusion] frame 1 OK — mode=${mode}, csi.bufLen=${csiSimulator.amplitudeBuffer.length}, embPts=${embPoints?.fused?.length ?? 0}, rssi=${(csiSimulator.rssiDbm ?? -99).toFixed(1)}`);
  }

  } catch (err) {
Author	SHA1	Message	Date
github-actions[bot]	8380046a8a	chore: update vendor submodules to latest main	2026-03-13 18:16:16 +00:00
ruv	a467dfed9f	docs: ADR-061 QEMU ESP32-S3 firmware testing platform (9 layers) Comprehensive QEMU emulation strategy for ESP32-S3 CSI node firmware: - Layer 1: Mock CSI generator with 10 test scenarios - Layer 2: QEMU runner + CI workflow with NVS matrix - Layer 3: Multi-node mesh simulation (TAP networking) - Layer 4: GDB remote debugging (zero-cost, no JTAG) - Layer 5: Code coverage (gcov/lcov) - Layer 6: Fuzz testing (libFuzzer for CSI parser, NVS, WASM) - Layer 7: NVS provisioning matrix (14 configs) - Layer 8: Snapshot & replay (<100ms restore) - Layer 9: Chaos testing (9 fault injection scenarios) Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-13 09:02:09 -04:00
rUv	d793c1f49f	feat(firmware): --channel and --filter-mac provisioning (ADR-060) - provision.py: add --channel (CSI channel override) and --filter-mac (AA:BB:CC:DD:EE:FF format) arguments with validation - nvs_config: add csi_channel, filter_mac[6], filter_mac_set fields; read from NVS on boot - csi_collector: auto-detect AP channel when no NVS override is set; filter CSI frames by source MAC when filter_mac is configured - ADR-060 documents the design and rationale Fixes #247, fixes #229	2026-03-13 08:27:08 -04:00
ruv	3457610c9f	brand: rename DensePose to RuView in pose-fusion UI Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:55:09 -04:00
ruv	e9d5ea3ad3	style: add spacing between tagline and demo links in README Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:47:31 -04:00
ruv	9cefb32815	fix(demo): add radial gradient background to camera prompt overlay Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:38:17 -04:00
ruv	a7c74e0c57	fix(demo): guard RuVector pipeline stats against undefined values Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:32:02 -04:00
ruv	98a2b0462c	fix(demo): bump import cache busters to v=13 to prevent stale modules Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:25:46 -04:00
ruv	e5e3d42ca2	fix(demo): guard toFixed on undefined rssiDbm and handle Blob WebSocket data - Add null-safe optional chaining for embPoints and rssiDbm in diagnostic log - Handle Blob data in _handleLiveFrame (convert to ArrayBuffer before processing) - Bump cache busters to v=13 Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 21:16:29 -04:00
rUv	7c1351fd5d	feat(demo): wire all 6 RuVector WASM attention mechanisms into pose fusion * feat: dual-modal WASM browser pose estimation demo (ADR-058) Live webcam video + WiFi CSI fusion for real-time pose estimation. Two parallel CNN pipelines (ruvector-cnn-wasm) with attention-weighted fusion and dynamic confidence gating. Three modes: Dual, Video-only, CSI-only. Includes pre-built WASM package (~52KB) for browser deployment. - ADR-058: Dual-modal architecture design - ui/pose-fusion.html: Main demo page with dark theme UI - 7 JS modules: video-capture, csi-simulator, cnn-embedder, fusion-engine, pose-decoder, canvas-renderer, main orchestrator - Pre-built ruvector-cnn-wasm WASM package for browser - CSI heatmap, embedding space visualization, latency metrics - WebSocket support for live ESP32 CSI data - Navigation link added to main dashboard Co-Authored-By: claude-flow <ruv@ruv.net> * fix: motion-responsive skeleton + through-wall CSI tracking - Pose decoder now uses per-cell motion grid to track actual arm/head positions — raising arms moves the skeleton's arms, head follows lateral movement - Motion grid (10x8 cells) tracks intensity per body zone: head, left/right arm upper/mid, legs - Through-wall mode: when person exits frame, CSI maintains presence with slow decay (~10s) and skeleton drifts in exit direction - CSI simulator persists sensing after video loss, ghost pose renders with decreasing confidence - Reduced temporal smoothing (0.45) for faster response to movement Co-Authored-By: claude-flow <ruv@ruv.net> * fix: video fills available space + correct WASM path resolution - Remove fixed aspect-ratio and max-height from video panel so it fills the available viewport space without scrolling - Grid uses 1fr row for content area, overflow:hidden on main grid - Fix WASM path: resolve relative to JS module file using import.meta.url instead of hardcoded ./pkg/ which resolved incorrectly on gh-pages - Responsive: mobile still gets aspect-ratio constraint Co-Authored-By: claude-flow <ruv@ruv.net> * feat: live ESP32 CSI pipeline + auto-connect WebSocket - Add auto-connect to local sensing server WebSocket (ws://localhost:8765) - Demo shows "Live ESP32" when connected to real CSI data - Add build_firmware.ps1 for native Windows ESP-IDF builds (no Docker) - Add read_serial.ps1 for ESP32 serial monitor Pipeline: ESP32 → UDP:5005 → sensing-server → WS:8765 → browser demo Co-Authored-By: claude-flow <ruv@ruv.net> * docs: add ADR-059 live ESP32 CSI pipeline + update README with demo links - ADR-059: Documents end-to-end ESP32 → sensing server → browser pipeline - README: Add dual-modal pose fusion demo link, update ADR count to 49 - References issue #245 Co-Authored-By: claude-flow <ruv@ruv.net> * feat: RSSI visualization, RuVector attention WASM, cache-bust fixes - Add animated RSSI Signal Strength panel with sparkline history - Fix RuVector WasmMultiHeadAttention retptr calling convention - Wire up RuVector Multi-Head + Flash Attention in CNN embedder - Add ambient temporal drift to CSI simulator for visible heatmap animation - Fix embedding space projection (sparse projection replaces cancelling sum) - Add auto-scaling to embedding space renderer - Add cache busters (?v=4) to all ES module imports to prevent stale caches - Add diagnostic logging for module version verification - Add RSSI tracking with quality labels and color-coded dBm display - Includes ruvector-attention-wasm v2.0.5 browser ESM wrapper Co-Authored-By: claude-flow <ruv@ruv.net> * feat: 26-keypoint dexterous pose + full RuVector attention pipeline Pose Decoder (17 → 26 keypoints): - Add finger approximations: thumb, index, pinky per hand (6 new) - Add toe tips: left/right foot index (2 new) - Add neck keypoint (1 new) - Hand openness driven by arm motion intensity - Finger positions computed from wrist-elbow axis angles CNN Embedder (full RuVector WASM pipeline): - Stage 1: Multi-Head Attention (global spatial reasoning) - Stage 2: Hyperbolic Attention (hierarchical body-part tree) - Stage 3: MoE Attention (3 experts: upper/lower/extremities, top-2) - Blended 40/30/30 weighting → final embedding projection Canvas Renderer: - Magenta finger joints with distinct glow - Cyan toe tips - White neck keypoint - Thinner limb lines for hand/foot connections - Joint count shown in overlay label CSI Simulator: - Skip synthetic person state when live ESP32 connected - Only simulate CSI data in demo mode (was already correct) Embedding Space: - Fixed projection: sparse 8-dim projection replaces cancelling sum - Auto-scaling normalizes point spread to fill canvas Cache busters bumped to v=5 on all imports. Co-Authored-By: claude-flow <ruv@ruv.net> * fix: centroid-based pose tracking for responsive limb movement Rewrites pose decoder from intensity-based to position-based tracking: - Arms now track toward motion centroid in each body zone - Elbow/wrist positions computed along shoulder→centroid vector - Legs track toward lower-body zone centroids - Smoothing reduced from 0.45 to 0.25 for responsiveness - Zone centroids blend 30% old / 70% new each frame 6 body zones with overlapping coverage: - Head (top 20%, center cols) - Left/Right Arm (rows 10-60%, outer cols) - Torso (rows 15-55%, center cols) - Left/Right Leg (rows 50-100%, half cols each) Hand openness now driven by arm spread distance + raise amount. Cache busters v=6. Co-Authored-By: claude-flow <ruv@ruv.net> * fix: remove duplicate lAnkleX/rAnkleX declarations in pose-decoder Stale code block from old intensity-based tracking was left behind, re-declaring variables already defined by centroid-based tracking. Co-Authored-By: claude-flow <ruv@ruv.net> * feat(demo): wire all 6 RuVector WASM attention mechanisms into pose fusion - Add WasmLinearAttention and WasmLocalGlobalAttention to browser ESM wrapper - Add 6 WASM utility functions (batch_normalize, pairwise_distances, etc.) - Extend CnnEmbedder to 6-stage pipeline: Flash → MHA → Hyperbolic → Linear → MoE → L+G - Use log-energy softmax blending across all 6 stages - Wire WASM cosine_similarity and normalize into FusionEngine - Add RuVector pipeline stats panel to UI (energy, refinement, pose impact) - Compute embedding-to-joint mapping stats without modifying joint positions - Center camera prompt with flexbox layout - Add cache busters v=12 Co-Authored-By: claude-flow <ruv@ruv.net>	2026-03-12 20:59:57 -04:00