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
This commit is contained in:
rUv
2026-03-13 08:27:08 -04:00
committed by GitHub
parent 3457610c9f
commit d793c1f49f
5 changed files with 165 additions and 2 deletions
@@ -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)