dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity

feat: ADR-029/031 TDM sensing protocol, channel hopping, and NVS config

Browse Source 
Implement the hardware and firmware portions of RuvSense (ADR-029) and
RuView (ADR-031) for multistatic WiFi sensing:

Rust (wifi-densepose-hardware):
- TdmSchedule: uniform slot assignments with configurable cycle period,
  guard intervals, and processing window (default 4-node 20 Hz)
- TdmCoordinator: manages sensing cycles, tracks per-slot completion,
  cumulative clock drift compensation (±10 ppm over 50 ms = 0.5 us)
- SyncBeacon: 16-byte wire format for cycle synchronization with
  drift correction offsets
- TdmSlotCompleted event for aggregator notification
- 18 unit tests + 4 doctests, all passing

Firmware (C, ESP32):
- Channel-hop table in csi_collector.c (s_hop_channels, configurable
  via csi_collector_set_hop_table)
- Timer-driven channel hopping via esp_timer at dwell intervals
- NDP frame injection stub via esp_wifi_80211_tx()
- Backward-compatible: hop_count=1 disables hopping entirely
- NVS config extension: hop_count, chan_list, dwell_ms, tdm_slot,
  tdm_node_count with bounds validation and Kconfig fallback defaults

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-03-01 21:33:48 -05:00
parent b4f1e55546
commit 303871275b
7 changed files with 1124 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
firmware/esp32-csi-node/main/csi_collector.c
View File

@@ -4,6 +4,11 @@
*
* Registers the ESP-IDF WiFi CSI callback and serializes incoming CSI data
* into the ADR-018 binary frame format for UDP transmission.
*
* ADR-029 extensions:
* - Channel-hop table for multi-band sensing (channels 1/6/11 by default)
* - Timer-driven channel hopping at configurable dwell intervals
* - NDP frame injection stub for sensing-first TX
*/
#include "csi_collector.h"
@@ -12,6 +17,7 @@
#include <string.h>
#include "esp_log.h"
#include "esp_wifi.h"
#include "esp_timer.h"
#include "sdkconfig.h"
static const char *TAG = "csi_collector";
@@ -21,6 +27,23 @@ static uint32_t s_cb_count = 0;
static uint32_t s_send_ok = 0;
static uint32_t s_send_fail = 0;
/* ---- ADR-029: Channel-hop state ---- */
/** Channel hop table (populated from NVS at boot or via set_hop_table). */
static uint8_t s_hop_channels[CSI_HOP_CHANNELS_MAX] = {1, 6, 11, 36, 40, 44};
/** Number of active channels in the hop table. 1 = single-channel (no hop). */
static uint8_t s_hop_count = 1;
/** Dwell time per channel in milliseconds. */
static uint32_t s_dwell_ms = 50;
/** Current index into s_hop_channels. */
static uint8_t s_hop_index = 0;
/** Handle for the periodic hop timer. NULL when timer is not running. */
static esp_timer_handle_t s_hop_timer = NULL;
/**
* Serialize CSI data into ADR-018 binary frame format.
*
@@ -174,3 +197,146 @@ void csi_collector_init(void)
ESP_LOGI(TAG, "CSI collection initialized (node_id=%d, channel=%d)",
CONFIG_CSI_NODE_ID, CONFIG_CSI_WIFI_CHANNEL);
}
/* ---- ADR-029: Channel hopping ---- */
void csi_collector_set_hop_table(const uint8_t *channels, uint8_t hop_count, uint32_t dwell_ms)
{
if (channels == NULL) {
ESP_LOGW(TAG, "csi_collector_set_hop_table: channels is NULL");
return;
}
if (hop_count == 0 || hop_count > CSI_HOP_CHANNELS_MAX) {
ESP_LOGW(TAG, "csi_collector_set_hop_table: invalid hop_count=%u (max=%u)",
(unsigned)hop_count, (unsigned)CSI_HOP_CHANNELS_MAX);
return;
}
if (dwell_ms < 10) {
ESP_LOGW(TAG, "csi_collector_set_hop_table: dwell_ms=%lu too small, clamping to 10",
(unsigned long)dwell_ms);
dwell_ms = 10;
}
memcpy(s_hop_channels, channels, hop_count);
s_hop_count = hop_count;
s_dwell_ms = dwell_ms;
s_hop_index = 0;
ESP_LOGI(TAG, "Hop table set: %u channels, dwell=%lu ms", (unsigned)hop_count,
(unsigned long)dwell_ms);
for (uint8_t i = 0; i < hop_count; i++) {
ESP_LOGI(TAG, " hop[%u] = channel %u", (unsigned)i, (unsigned)channels[i]);
}
}
void csi_hop_next_channel(void)
{
if (s_hop_count <= 1) {
/* Single-channel mode: no-op for backward compatibility. */
return;
}
s_hop_index = (s_hop_index + 1) % s_hop_count;
uint8_t channel = s_hop_channels[s_hop_index];
/*
* esp_wifi_set_channel() changes the primary channel.
* The second parameter is the secondary channel offset for HT40;
* we use HT20 (no secondary) for sensing.
*/
esp_err_t err = esp_wifi_set_channel(channel, WIFI_SECOND_CHAN_NONE);
if (err != ESP_OK) {
ESP_LOGW(TAG, "Channel hop to %u failed: %s", (unsigned)channel, esp_err_to_name(err));
} else if ((s_cb_count % 200) == 0) {
/* Periodic log to confirm hopping is working (not every hop). */
ESP_LOGI(TAG, "Hopped to channel %u (index %u/%u)",
(unsigned)channel, (unsigned)s_hop_index, (unsigned)s_hop_count);
}
}
/**
* Timer callback for channel hopping.
* Called every s_dwell_ms milliseconds from the esp_timer context.
*/
static void hop_timer_cb(void *arg)
{
(void)arg;
csi_hop_next_channel();
}
void csi_collector_start_hop_timer(void)
{
if (s_hop_count <= 1) {
ESP_LOGI(TAG, "Single-channel mode: hop timer not started");
return;
}
if (s_hop_timer != NULL) {
ESP_LOGW(TAG, "Hop timer already running");
return;
}
esp_timer_create_args_t timer_args = {
.callback = hop_timer_cb,
.arg = NULL,
.name = "csi_hop",
};
esp_err_t err = esp_timer_create(&timer_args, &s_hop_timer);
if (err != ESP_OK) {
ESP_LOGE(TAG, "Failed to create hop timer: %s", esp_err_to_name(err));
return;
}
uint64_t period_us = (uint64_t)s_dwell_ms * 1000;
err = esp_timer_start_periodic(s_hop_timer, period_us);
if (err != ESP_OK) {
ESP_LOGE(TAG, "Failed to start hop timer: %s", esp_err_to_name(err));
esp_timer_delete(s_hop_timer);
s_hop_timer = NULL;
return;
}
ESP_LOGI(TAG, "Hop timer started: period=%lu ms, channels=%u",
(unsigned long)s_dwell_ms, (unsigned)s_hop_count);
}
/* ---- ADR-029: NDP frame injection stub ---- */
esp_err_t csi_inject_ndp_frame(void)
{
/*
* TODO: Construct a proper 802.11 Null Data Packet frame.
*
* A real NDP is preamble-only (~24 us airtime, no payload) and is the
* sensing-first TX mechanism described in ADR-029. For now we send a
* minimal null-data frame as a placeholder so the API is wired up.
*
* Frame structure (IEEE 802.11 Null Data):
* FC (2) | Duration (2) | Addr1 (6) | Addr2 (6) | Addr3 (6) | SeqCtl (2)
* = 24 bytes total, no body, no FCS (hardware appends FCS).
*/
uint8_t ndp_frame[24];
memset(ndp_frame, 0, sizeof(ndp_frame));
/* Frame Control: Type=Data (0x02), Subtype=Null (0x04) -> 0x0048 */
ndp_frame[0] = 0x48;
ndp_frame[1] = 0x00;
/* Duration: 0 (let hardware fill) */
/* Addr1 (destination): broadcast */
memset(&ndp_frame[4], 0xFF, 6);
/* Addr2 (source): will be overwritten by hardware with own MAC */
/* Addr3 (BSSID): broadcast */
memset(&ndp_frame[16], 0xFF, 6);
esp_err_t err = esp_wifi_80211_tx(WIFI_IF_STA, ndp_frame, sizeof(ndp_frame), false);
if (err != ESP_OK) {
ESP_LOGW(TAG, "NDP inject failed: %s", esp_err_to_name(err));
}
return err;
}

46
firmware/esp32-csi-node/main/csi_collector.h
View File

@@ -19,6 +19,9 @@
/** 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.
@@ -35,4 +38,47 @@ void csi_collector_init(void);
*/
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 */

75
firmware/esp32-csi-node/main/nvs_config.c
View File

@@ -18,6 +18,11 @@ static const char *TAG = "nvs_config";
void nvs_config_load(nvs_config_t *cfg)
{
if (cfg == NULL) {
ESP_LOGE(TAG, "nvs_config_load: cfg is NULL");
return;
}
/* Start with Kconfig compiled defaults */
strncpy(cfg->wifi_ssid, CONFIG_CSI_WIFI_SSID, NVS_CFG_SSID_MAX - 1);
cfg->wifi_ssid[NVS_CFG_SSID_MAX - 1] = '\0';
@@ -35,6 +40,17 @@ void nvs_config_load(nvs_config_t *cfg)
cfg->target_port = (uint16_t)CONFIG_CSI_TARGET_PORT;
cfg->node_id = (uint8_t)CONFIG_CSI_NODE_ID;
/* ADR-029: Defaults for channel hopping and TDM.
* hop_count=1 means single-channel (backward-compatible). */
cfg->channel_hop_count = 1;
cfg->channel_list[0] = (uint8_t)CONFIG_CSI_WIFI_CHANNEL;
for (uint8_t i = 1; i < NVS_CFG_HOP_MAX; i++) {
cfg->channel_list[i] = 0;
}
cfg->dwell_ms = 50;
cfg->tdm_slot_index = 0;
cfg->tdm_node_count = 1;
/* Try to override from NVS */
nvs_handle_t handle;
esp_err_t err = nvs_open("csi_cfg", NVS_READONLY, &handle);
@@ -84,5 +100,64 @@ void nvs_config_load(nvs_config_t *cfg)
ESP_LOGI(TAG, "NVS override: node_id=%u", cfg->node_id);
}
/* ADR-029: Channel hop count */
uint8_t hop_count_val;
if (nvs_get_u8(handle, "hop_count", &hop_count_val) == ESP_OK) {
if (hop_count_val >= 1 && hop_count_val <= NVS_CFG_HOP_MAX) {
cfg->channel_hop_count = hop_count_val;
ESP_LOGI(TAG, "NVS override: hop_count=%u", (unsigned)cfg->channel_hop_count);
} else {
ESP_LOGW(TAG, "NVS hop_count=%u out of range [1..%u], ignored",
(unsigned)hop_count_val, (unsigned)NVS_CFG_HOP_MAX);
}
}
/* ADR-029: Channel list (stored as a blob of up to NVS_CFG_HOP_MAX bytes) */
len = NVS_CFG_HOP_MAX;
uint8_t ch_blob[NVS_CFG_HOP_MAX];
if (nvs_get_blob(handle, "chan_list", ch_blob, &len) == ESP_OK && len > 0) {
uint8_t count = (len < cfg->channel_hop_count) ? (uint8_t)len : cfg->channel_hop_count;
for (uint8_t i = 0; i < count; i++) {
cfg->channel_list[i] = ch_blob[i];
}
ESP_LOGI(TAG, "NVS override: chan_list loaded (%u channels)", (unsigned)count);
}
/* ADR-029: Dwell time */
uint32_t dwell_val;
if (nvs_get_u32(handle, "dwell_ms", &dwell_val) == ESP_OK) {
if (dwell_val >= 10) {
cfg->dwell_ms = dwell_val;
ESP_LOGI(TAG, "NVS override: dwell_ms=%lu", (unsigned long)cfg->dwell_ms);
} else {
ESP_LOGW(TAG, "NVS dwell_ms=%lu too small, ignored", (unsigned long)dwell_val);
}
}
/* ADR-029/031: TDM slot index */
uint8_t slot_val;
if (nvs_get_u8(handle, "tdm_slot", &slot_val) == ESP_OK) {
cfg->tdm_slot_index = slot_val;
ESP_LOGI(TAG, "NVS override: tdm_slot_index=%u", (unsigned)cfg->tdm_slot_index);
}
/* ADR-029/031: TDM node count */
uint8_t tdm_nodes_val;
if (nvs_get_u8(handle, "tdm_nodes", &tdm_nodes_val) == ESP_OK) {
if (tdm_nodes_val >= 1) {
cfg->tdm_node_count = tdm_nodes_val;
ESP_LOGI(TAG, "NVS override: tdm_node_count=%u", (unsigned)cfg->tdm_node_count);
} else {
ESP_LOGW(TAG, "NVS tdm_nodes=%u invalid, ignored", (unsigned)tdm_nodes_val);
}
}
/* 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",
(unsigned)cfg->tdm_slot_index, (unsigned)cfg->tdm_node_count);
cfg->tdm_slot_index = 0;
}
nvs_close(handle);
}

10
firmware/esp32-csi-node/main/nvs_config.h
View File

@@ -18,6 +18,9 @@
#define NVS_CFG_PASS_MAX 65
#define NVS_CFG_IP_MAX 16
/** Maximum channels in the hop list (must match CSI_HOP_CHANNELS_MAX). */
#define NVS_CFG_HOP_MAX 6
/** Runtime configuration loaded from NVS or Kconfig defaults. */
typedef struct {
char wifi_ssid[NVS_CFG_SSID_MAX];
@@ -25,6 +28,13 @@ typedef struct {
char target_ip[NVS_CFG_IP_MAX];
uint16_t target_port;
uint8_t node_id;
/* ADR-029: Channel hopping and TDM configuration */
uint8_t channel_hop_count; /**< Number of channels to hop (1 = no hop). */
uint8_t channel_list[NVS_CFG_HOP_MAX]; /**< Channel numbers for hopping. */
uint32_t dwell_ms; /**< Dwell time per channel in ms. */
uint8_t tdm_slot_index; /**< This node's TDM slot index (0-based). */
uint8_t tdm_node_count; /**< Total nodes in the TDM schedule. */
} nvs_config_t;
/**