feat(adr-018): ESP32-S3 firmware, Rust aggregator, and live CSI pipeline

Complete end-to-end WiFi CSI capture pipeline verified on real hardware:

- ESP32-S3 firmware: WiFi STA + promiscuous mode CSI collection,
  ADR-018 binary serialization, UDP streaming at ~20 Hz
- Rust aggregator CLI binary (clap): receives UDP frames, parses with
  Esp32CsiParser, prints per-frame summary (node, seq, rssi, amp)
- UDP aggregator module with per-node sequence tracking and drop detection
- CsiFrame bridge to detection pipeline (amplitude/phase/SNR conversion)
- Python ESP32 binary parser with UDP reader
- Presence detection confirmed: motion score 10/10 from live CSI variance

Hardware verified: ESP32-S3-DevKitC-1 (CP2102, MAC 3C:0F:02:EC:C2:28),
Docker ESP-IDF v5.2 build, esptool 5.1.0 flash, 20 Rust + 6 Python tests pass.

Co-Authored-By: claude-flow <ruv@ruv.net>

firmware/esp32-csi-node/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(
+    SRCS "main.c" "csi_collector.c" "stream_sender.c"
+    INCLUDE_DIRS "."
+)

firmware/esp32-csi-node/main/Kconfig.projbuild

@@ -0,0 +1,42 @@
+menu "CSI Node Configuration"
+
+    config CSI_NODE_ID
+        int "Node ID (0-255)"
+        default 1
+        range 0 255
+        help
+            Unique identifier for this ESP32 CSI node.
+
+    config CSI_TARGET_IP
+        string "Aggregator IP address"
+        default "192.168.1.100"
+        help
+            IP address of the UDP aggregator host.
+
+    config CSI_TARGET_PORT
+        int "Aggregator UDP port"
+        default 5005
+        range 1024 65535
+        help
+            UDP port the aggregator listens on.
+
+    config CSI_WIFI_SSID
+        string "WiFi SSID"
+        default "wifi-densepose"
+        help
+            SSID of the WiFi network to connect to.
+
+    config CSI_WIFI_PASSWORD
+        string "WiFi Password"
+        default ""
+        help
+            Password for the WiFi network. Leave empty for open networks.
+
+    config CSI_WIFI_CHANNEL
+        int "WiFi Channel (1-13)"
+        default 6
+        range 1 13
+        help
+            WiFi channel to listen on for CSI data.
+
+endmenu

firmware/esp32-csi-node/main/csi_collector.c

@@ -0,0 +1,176 @@
+/**
+ * @file csi_collector.c
+ * @brief CSI data collection and ADR-018 binary frame serialization.
+ *
+ * Registers the ESP-IDF WiFi CSI callback and serializes incoming CSI data
+ * into the ADR-018 binary frame format for UDP transmission.
+ */
+
+#include "csi_collector.h"
+#include "stream_sender.h"
+
+#include <string.h>
+#include "esp_log.h"
+#include "esp_wifi.h"
+#include "sdkconfig.h"
+
+static const char *TAG = "csi_collector";
+
+static uint32_t s_sequence = 0;
+static uint32_t s_cb_count = 0;
+static uint32_t s_send_ok = 0;
+static uint32_t s_send_fail = 0;
+
+/**
+ * Serialize CSI data into ADR-018 binary frame format.
+ *
+ * Layout:
+ *   [0..3]   Magic: 0xC5110001 (LE)
+ *   [4]      Node ID
+ *   [5]      Number of antennas (rx_ctrl.rx_ant + 1 if available, else 1)
+ *   [6..7]   Number of subcarriers (LE u16) = len / (2 * n_antennas)
+ *   [8..11]  Frequency MHz (LE u32) — derived from channel
+ *   [12..15] Sequence number (LE u32)
+ *   [16]     RSSI (i8)
+ *   [17]     Noise floor (i8)
+ *   [18..19] Reserved
+ *   [20..]   I/Q data (raw bytes from ESP-IDF callback)
+ */
+size_t csi_serialize_frame(const wifi_csi_info_t *info, uint8_t *buf, size_t buf_len)
+{
+    if (info == NULL || buf == NULL || info->buf == NULL) {
+        return 0;
+    }
+
+    uint8_t n_antennas = 1;  /* ESP32-S3 typically reports 1 antenna for CSI */
+    uint16_t iq_len = (uint16_t)info->len;
+    uint16_t n_subcarriers = iq_len / (2 * n_antennas);
+
+    size_t frame_size = CSI_HEADER_SIZE + iq_len;
+    if (frame_size > buf_len) {
+        ESP_LOGW(TAG, "Buffer too small: need %u, have %u", (unsigned)frame_size, (unsigned)buf_len);
+        return 0;
+    }
+
+    /* Derive frequency from channel number */
+    uint8_t channel = info->rx_ctrl.channel;
+    uint32_t freq_mhz;
+    if (channel >= 1 && channel <= 13) {
+        freq_mhz = 2412 + (channel - 1) * 5;
+    } else if (channel == 14) {
+        freq_mhz = 2484;
+    } else if (channel >= 36 && channel <= 177) {
+        freq_mhz = 5000 + channel * 5;
+    } else {
+        freq_mhz = 0;
+    }
+
+    /* Magic (LE) */
+    uint32_t magic = CSI_MAGIC;
+    memcpy(&buf[0], &magic, 4);
+
+    /* Node ID */
+    buf[4] = (uint8_t)CONFIG_CSI_NODE_ID;
+
+    /* Number of antennas */
+    buf[5] = n_antennas;
+
+    /* Number of subcarriers (LE u16) */
+    memcpy(&buf[6], &n_subcarriers, 2);
+
+    /* Frequency MHz (LE u32) */
+    memcpy(&buf[8], &freq_mhz, 4);
+
+    /* Sequence number (LE u32) */
+    uint32_t seq = s_sequence++;
+    memcpy(&buf[12], &seq, 4);
+
+    /* RSSI (i8) */
+    buf[16] = (uint8_t)(int8_t)info->rx_ctrl.rssi;
+
+    /* Noise floor (i8) */
+    buf[17] = (uint8_t)(int8_t)info->rx_ctrl.noise_floor;
+
+    /* Reserved */
+    buf[18] = 0;
+    buf[19] = 0;
+
+    /* I/Q data */
+    memcpy(&buf[CSI_HEADER_SIZE], info->buf, iq_len);
+
+    return frame_size;
+}
+
+/**
+ * WiFi CSI callback — invoked by ESP-IDF when CSI data is available.
+ */
+static void wifi_csi_callback(void *ctx, wifi_csi_info_t *info)
+{
+    (void)ctx;
+    s_cb_count++;
+
+    if (s_cb_count <= 3 || (s_cb_count % 100) == 0) {
+        ESP_LOGI(TAG, "CSI cb #%lu: len=%d rssi=%d ch=%d",
+                 (unsigned long)s_cb_count, info->len,
+                 info->rx_ctrl.rssi, info->rx_ctrl.channel);
+    }
+
+    uint8_t frame_buf[CSI_MAX_FRAME_SIZE];
+    size_t frame_len = csi_serialize_frame(info, frame_buf, sizeof(frame_buf));
+
+    if (frame_len > 0) {
+        int ret = stream_sender_send(frame_buf, frame_len);
+        if (ret > 0) {
+            s_send_ok++;
+        } else {
+            s_send_fail++;
+            if (s_send_fail <= 5) {
+                ESP_LOGW(TAG, "sendto failed (fail #%lu)", (unsigned long)s_send_fail);
+            }
+        }
+    }
+}
+
+/**
+ * Promiscuous mode callback — required for CSI to fire on all received frames.
+ * We don't need the packet content, just the CSI triggered by reception.
+ */
+static void wifi_promiscuous_cb(void *buf, wifi_promiscuous_pkt_type_t type)
+{
+    /* No-op: CSI callback is registered separately and fires in parallel. */
+    (void)buf;
+    (void)type;
+}
+
+void csi_collector_init(void)
+{
+    /* 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. */
+    ESP_ERROR_CHECK(esp_wifi_set_promiscuous(true));
+    ESP_ERROR_CHECK(esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb));
+
+    wifi_promiscuous_filter_t filt = {
+        .filter_mask = WIFI_PROMIS_FILTER_MASK_MGMT | WIFI_PROMIS_FILTER_MASK_DATA,
+    };
+    ESP_ERROR_CHECK(esp_wifi_set_promiscuous_filter(&filt));
+
+    ESP_LOGI(TAG, "Promiscuous mode enabled for CSI capture");
+
+    wifi_csi_config_t csi_config = {
+        .lltf_en = true,
+        .htltf_en = true,
+        .stbc_htltf2_en = true,
+        .ltf_merge_en = true,
+        .channel_filter_en = false,
+        .manu_scale = false,
+        .shift = false,
+    };
+
+    ESP_ERROR_CHECK(esp_wifi_set_csi_config(&csi_config));
+    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);
+}

firmware/esp32-csi-node/main/csi_collector.h

@@ -0,0 +1,38 @@
+/**
+ * @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_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)
+
+/**
+ * Initialize CSI collection.
+ * Registers the WiFi CSI callback.
+ */
+void csi_collector_init(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);
+
+#endif /* CSI_COLLECTOR_H */

firmware/esp32-csi-node/main/main.c

@@ -0,0 +1,137 @@
+/**
+ * @file main.c
+ * @brief ESP32-S3 CSI Node — ADR-018 compliant firmware.
+ *
+ * Initializes NVS, WiFi STA mode, CSI collection, and UDP streaming.
+ * CSI frames are serialized in ADR-018 binary format and sent to the
+ * aggregator over UDP.
+ */
+
+#include <string.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/event_groups.h"
+#include "esp_system.h"
+#include "esp_wifi.h"
+#include "esp_event.h"
+#include "esp_log.h"
+#include "nvs_flash.h"
+#include "sdkconfig.h"
+
+#include "csi_collector.h"
+#include "stream_sender.h"
+
+static const char *TAG = "main";
+
+/* Event group bits */
+#define WIFI_CONNECTED_BIT BIT0
+#define WIFI_FAIL_BIT      BIT1
+
+static EventGroupHandle_t s_wifi_event_group;
+static int s_retry_num = 0;
+#define MAX_RETRY 10
+
+static void event_handler(void *arg, esp_event_base_t event_base,
+                          int32_t event_id, void *event_data)
+{
+    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
+        esp_wifi_connect();
+    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
+        if (s_retry_num < MAX_RETRY) {
+            esp_wifi_connect();
+            s_retry_num++;
+            ESP_LOGI(TAG, "Retrying WiFi connection (%d/%d)", s_retry_num, MAX_RETRY);
+        } else {
+            xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT);
+        }
+    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
+        ip_event_got_ip_t *event = (ip_event_got_ip_t *)event_data;
+        ESP_LOGI(TAG, "Got IP: " IPSTR, IP2STR(&event->ip_info.ip));
+        s_retry_num = 0;
+        xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT);
+    }
+}
+
+static void wifi_init_sta(void)
+{
+    s_wifi_event_group = xEventGroupCreate();
+
+    ESP_ERROR_CHECK(esp_netif_init());
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    esp_netif_create_default_wifi_sta();
+
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_init(&cfg));
+
+    esp_event_handler_instance_t instance_any_id;
+    esp_event_handler_instance_t instance_got_ip;
+    ESP_ERROR_CHECK(esp_event_handler_instance_register(
+        WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler, NULL, &instance_any_id));
+    ESP_ERROR_CHECK(esp_event_handler_instance_register(
+        IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler, NULL, &instance_got_ip));
+
+    wifi_config_t wifi_config = {
+        .sta = {
+            .ssid = CONFIG_CSI_WIFI_SSID,
+#ifdef CONFIG_CSI_WIFI_PASSWORD
+            .password = CONFIG_CSI_WIFI_PASSWORD,
+#endif
+            .threshold.authmode = WIFI_AUTH_WPA2_PSK,
+        },
+    };
+
+    /* If password is empty, use open auth */
+    if (strlen((char *)wifi_config.sta.password) == 0) {
+        wifi_config.sta.threshold.authmode = WIFI_AUTH_OPEN;
+    }
+
+    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
+    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
+    ESP_ERROR_CHECK(esp_wifi_start());
+
+    ESP_LOGI(TAG, "WiFi STA initialized, connecting to SSID: %s", CONFIG_CSI_WIFI_SSID);
+
+    /* Wait for connection */
+    EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group,
+        WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
+        pdFALSE, pdFALSE, portMAX_DELAY);
+
+    if (bits & WIFI_CONNECTED_BIT) {
+        ESP_LOGI(TAG, "Connected to WiFi");
+    } else if (bits & WIFI_FAIL_BIT) {
+        ESP_LOGE(TAG, "Failed to connect to WiFi after %d retries", MAX_RETRY);
+    }
+}
+
+void app_main(void)
+{
+    ESP_LOGI(TAG, "ESP32-S3 CSI Node (ADR-018) — Node ID: %d", CONFIG_CSI_NODE_ID);
+
+    /* Initialize NVS */
+    esp_err_t ret = nvs_flash_init();
+    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        ret = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(ret);
+
+    /* Initialize WiFi STA */
+    wifi_init_sta();
+
+    /* Initialize UDP sender */
+    if (stream_sender_init() != 0) {
+        ESP_LOGE(TAG, "Failed to initialize UDP sender");
+        return;
+    }
+
+    /* Initialize CSI collection */
+    csi_collector_init();
+
+    ESP_LOGI(TAG, "CSI streaming active → %s:%d",
+             CONFIG_CSI_TARGET_IP, CONFIG_CSI_TARGET_PORT);
+
+    /* Main loop — keep alive */
+    while (1) {
+        vTaskDelay(pdMS_TO_TICKS(10000));
+    }
+}

firmware/esp32-csi-node/main/stream_sender.c

@@ -0,0 +1,67 @@
+/**
+ * @file stream_sender.c
+ * @brief UDP stream sender for CSI frames.
+ *
+ * Opens a UDP socket and sends serialized ADR-018 frames to the aggregator.
+ */
+
+#include "stream_sender.h"
+
+#include <string.h>
+#include "esp_log.h"
+#include "lwip/sockets.h"
+#include "lwip/netdb.h"
+#include "sdkconfig.h"
+
+static const char *TAG = "stream_sender";
+
+static int s_sock = -1;
+static struct sockaddr_in s_dest_addr;
+
+int stream_sender_init(void)
+{
+    s_sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
+    if (s_sock < 0) {
+        ESP_LOGE(TAG, "Failed to create socket: errno %d", errno);
+        return -1;
+    }
+
+    memset(&s_dest_addr, 0, sizeof(s_dest_addr));
+    s_dest_addr.sin_family = AF_INET;
+    s_dest_addr.sin_port = htons(CONFIG_CSI_TARGET_PORT);
+
+    if (inet_pton(AF_INET, CONFIG_CSI_TARGET_IP, &s_dest_addr.sin_addr) <= 0) {
+        ESP_LOGE(TAG, "Invalid target IP: %s", CONFIG_CSI_TARGET_IP);
+        close(s_sock);
+        s_sock = -1;
+        return -1;
+    }
+
+    ESP_LOGI(TAG, "UDP sender initialized: %s:%d", CONFIG_CSI_TARGET_IP, CONFIG_CSI_TARGET_PORT);
+    return 0;
+}
+
+int stream_sender_send(const uint8_t *data, size_t len)
+{
+    if (s_sock < 0) {
+        return -1;
+    }
+
+    int sent = sendto(s_sock, data, len, 0,
+                      (struct sockaddr *)&s_dest_addr, sizeof(s_dest_addr));
+    if (sent < 0) {
+        ESP_LOGW(TAG, "sendto failed: errno %d", errno);
+        return -1;
+    }
+
+    return sent;
+}
+
+void stream_sender_deinit(void)
+{
+    if (s_sock >= 0) {
+        close(s_sock);
+        s_sock = -1;
+        ESP_LOGI(TAG, "UDP sender closed");
+    }
+}

firmware/esp32-csi-node/main/stream_sender.h

@@ -0,0 +1,34 @@
+/**
+ * @file stream_sender.h
+ * @brief UDP stream sender for CSI frames.
+ */
+
+#ifndef STREAM_SENDER_H
+#define STREAM_SENDER_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+/**
+ * Initialize the UDP sender.
+ * Creates a UDP socket targeting the configured aggregator.
+ *
+ * @return 0 on success, -1 on error.
+ */
+int stream_sender_init(void);
+
+/**
+ * Send a serialized CSI frame over UDP.
+ *
+ * @param data Frame data buffer.
+ * @param len  Length of data to send.
+ * @return Number of bytes sent, or -1 on error.
+ */
+int stream_sender_send(const uint8_t *data, size_t len);
+
+/**
+ * Close the UDP sender socket.
+ */
+void stream_sender_deinit(void);
+
+#endif /* STREAM_SENDER_H */