mirror of
https://github.com/ruvnet/RuView
synced 2026-07-26 18:01:48 +00:00
ruv
425f0e6aac
Users on multi-node ESP32 deployments have been reporting for months
that their provisioned `node_id` reverts to the Kconfig default of `1`
in UDP frames and the `csi_collector` init log, despite boot showing:
nvs_config: NVS override: node_id=4
main: ESP32-S3 CSI Node (ADR-018) - Node ID: 4
csi_collector: CSI collection initialized (node_id=1, channel=11)
See #232, #375, #385, #386, #390. The root memory-corruption path for
the `g_nvs_config.node_id` byte has not been definitively isolated
(does not reproduce on my attached ESP32-S3 running current source
and the v0.6.0 release binary), but the UDP frame header can be made
tamper-proof regardless:
1. `csi_collector_init()` now captures `g_nvs_config.node_id` into a
module-local `static uint8_t s_node_id` at init time.
2. `csi_serialize_frame()` reads `buf[4]` from `s_node_id`, not from
the global - so any later corruption of `g_nvs_config` cannot
affect outgoing CSI frames.
3. All other consumers (`edge_processing.c` x3, `wasm_runtime.c`,
`display_ui.c`, `main.c swarm_bridge_init`) now go through a new
`csi_collector_get_node_id()` accessor instead of reading the
global directly.
4. A canary at end-of-init logs `WARN` if `g_nvs_config.node_id`
already diverges from the captured value - this will pinpoint
the corruption path if it happens on a user's device.
Hardware validation on attached ESP32-S3 (COM8):
- NVS loads node_id=2
- Boot log: `main: ... Node ID: 2`
- NEW log: `csi_collector: Captured node_id=2 at init (defensive
copy for #232/#375/#385/#390)`
- Init log: `csi_collector: CSI collection initialized (node_id=2)`
- UDP frame byte[4] = 2 (verified via socket sniffer, 15/15 packets)
This is defense in depth - it shields the UDP frame from whatever
upstream bug is clobbering the struct. When a user hits the original
bug, the canary WARN will help isolate the root cause.
Refs #232 #375 #385 #386 #390
Co-Authored-By: claude-flow <ruv@ruv.net>
98 lines
3.1 KiB
C
98 lines
3.1 KiB
C
/**
|
|
* @file csi_collector.h
|
|
* @brief CSI data collection and ADR-018 binary frame serialization.
|
|
*/
|
|
|
|
#ifndef CSI_COLLECTOR_H
|
|
#define CSI_COLLECTOR_H
|
|
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
#include "esp_err.h"
|
|
#include "esp_wifi_types.h"
|
|
|
|
/** ADR-018 magic number. */
|
|
#define CSI_MAGIC 0xC5110001
|
|
|
|
/** ADR-018 header size in bytes. */
|
|
#define CSI_HEADER_SIZE 20
|
|
|
|
/** Maximum frame buffer size (header + 4 antennas * 256 subcarriers * 2 bytes). */
|
|
#define CSI_MAX_FRAME_SIZE (CSI_HEADER_SIZE + 4 * 256 * 2)
|
|
|
|
/** Maximum number of channels in the hop table (ADR-029). */
|
|
#define CSI_HOP_CHANNELS_MAX 6
|
|
|
|
/**
|
|
* Initialize CSI collection.
|
|
* Registers the WiFi CSI callback.
|
|
*/
|
|
void csi_collector_init(void);
|
|
|
|
/**
|
|
* Get the runtime node_id captured at csi_collector_init().
|
|
*
|
|
* This is a defensive copy of g_nvs_config.node_id taken at init time. Other
|
|
* modules (edge_processing, wasm_runtime, display_ui) should prefer this
|
|
* accessor over reading g_nvs_config.node_id directly, because the global
|
|
* struct can be clobbered by memory corruption (see #232, #375, #385, #390).
|
|
*
|
|
* @return Node ID (0-255) as loaded from NVS or Kconfig default at boot.
|
|
*/
|
|
uint8_t csi_collector_get_node_id(void);
|
|
|
|
/**
|
|
* Serialize CSI data into ADR-018 binary frame format.
|
|
*
|
|
* @param info WiFi CSI info from the ESP-IDF callback.
|
|
* @param buf Output buffer (must be at least CSI_MAX_FRAME_SIZE bytes).
|
|
* @param buf_len Size of the output buffer.
|
|
* @return Number of bytes written, or 0 on error.
|
|
*/
|
|
size_t csi_serialize_frame(const wifi_csi_info_t *info, uint8_t *buf, size_t buf_len);
|
|
|
|
/**
|
|
* Configure the channel-hop table for multi-band sensing (ADR-029).
|
|
*
|
|
* When hop_count == 1 the collector stays on the single configured channel
|
|
* (backward-compatible with the original single-channel mode).
|
|
*
|
|
* @param channels Array of WiFi channel numbers (1-14 for 2.4 GHz, 36-177 for 5 GHz).
|
|
* @param hop_count Number of entries in the channels array (1..CSI_HOP_CHANNELS_MAX).
|
|
* @param dwell_ms Dwell time per channel in milliseconds (>= 10).
|
|
*/
|
|
void csi_collector_set_hop_table(const uint8_t *channels, uint8_t hop_count, uint32_t dwell_ms);
|
|
|
|
/**
|
|
* Advance to the next channel in the hop table.
|
|
*
|
|
* Called by the hop timer callback. If hop_count <= 1 this is a no-op.
|
|
* Calls esp_wifi_set_channel() internally.
|
|
*/
|
|
void csi_hop_next_channel(void);
|
|
|
|
/**
|
|
* Start the channel-hop timer.
|
|
*
|
|
* Creates an esp_timer periodic callback that fires every dwell_ms
|
|
* milliseconds, calling csi_hop_next_channel(). If hop_count <= 1
|
|
* the timer is not started (single-channel backward-compatible mode).
|
|
*/
|
|
void csi_collector_start_hop_timer(void);
|
|
|
|
/**
|
|
* Inject an NDP (Null Data Packet) frame for sensing.
|
|
*
|
|
* Uses esp_wifi_80211_tx() to send a preamble-only frame (~24 us airtime)
|
|
* that triggers CSI measurement at all receivers. This is the "sensing-first"
|
|
* TX mechanism described in ADR-029.
|
|
*
|
|
* @return ESP_OK on success, or an error code.
|
|
*
|
|
* @note TODO: Full NDP frame construction. Currently sends a minimal
|
|
* null-data frame as a placeholder.
|
|
*/
|
|
esp_err_t csi_inject_ndp_frame(void);
|
|
|
|
#endif /* CSI_COLLECTOR_H */
|