[Task]PC上CSI数据处理工具

[Lixeer]

💡 背景 / 动机 (Context / Motivation)

现阶段已经完成了在esp32c6对WIFI CSI 原生数据的高频采集和传输，但是采集数据毫无规律，直接可视化也无法区分出数据意义(输出大致如下)

len:256 index:<表示数据包索引> data:[0,0,0,0,0,0,0,0,0,0,0,0,26,7,26,9,27,10,28,11,29,12,29,13,28,14,29,15,31,14,32,15,32,16,32,15,36,13,34,15,34,16,33,14,36,15,36,14,36,14,39,16,42,13,35,14,38,10,37,11,37,12,38,8,37,8,36,6,39,5,37,3,38,1,39,1,37,0,36,-1,37,-3,37,-7,36,-7,37,-10,37,-10,36,-14,35,-13,34,-17,34,-17,34,-21,33,-18,33,-23,33,-22,33,-25,32,-23,26,-25,31,-27,43,-33,32,-25,24,-29,28,-35,26,-29,32,-33,0,0,0,0,0,0,-31,-29,-31,-26,-32,-25,-28,-23,-32,-23,-31,-22,-29,-21,-30,-18,-28,-18,-26,-16,-27,-14,-26,-12,-27,-12,-26,-12,-26,-11,-25,-9,-27,-10,-24,-7,-24,-7,-24,-4,-22,-4,-24,-3,-22,-5,-21,-3,-21,-3,-20,-1,-20,-4,-19,-2,-19,-2,-18,1,-15,-1,-16,-2,-15,-2,-14,-2,-14,-2,-12,-1,-12,-4,-9,-2,-9,-3,-6,-1,-5,0,-5,-1,-5,0,-3,0,-1,0,-1,0,0,1,-1,1,1,0,0,1,1,2,1,1,2,2,2,2,1,2,2,4,2,3,0,0,0,0,0,0,0,0,0,0]

我们迫切需要一个工具用来处理这些数据

📝 目标 (Objective)

了解数据意义，对数据进行实时预处理且可视化，并且为后续数据标注留出可能性(例如人的剧烈运动可能引起波形的变化，但是在这堆数据中我们并不能知道哪个时间段是变化的)。

📕 任务指南

查看乐鑫源代码注释

typedef struct wifi_csi_info_t {
    wifi_pkt_rx_ctrl_t rx_ctrl;/**< received packet radio metadata header of the CSI data */
    uint8_t mac[6];            /**< source MAC address of the CSI data */
    uint8_t dmac[6];           /**< destination MAC address of the CSI data */
    bool first_word_invalid;   /**< first four bytes of the CSI data is invalid or not, true indicates the first four bytes is invalid due to hardware limitation */
    int8_t *buf;               /**< valid buffer of CSI data */
    uint16_t len;              /**< valid length of CSI data */
    uint8_t *hdr;              /**< header of the wifi packet */
    uint8_t *payload;          /**< payload of the wifi packet */
    uint16_t payload_len;      /**< payload len of the wifi packet */
    uint16_t rx_seq;           /**< rx sequence number of the wifi packet */
} wifi_csi_info_t;

buf是csi的原生数据，并且通过官方的文档

• 元数据字段：包括 type, id, mac, ... first_word等。
• CSI 数据：由最后一项 data 数组存储，用 [...] 框起。包含每个子载波的信道状态信息。
• 具体结构可参考 ESP-WIFI-CSI Guide 的 Long Training Field (LTF) 部分。对于每一个子载波，先储存虚数部分，再储存实数部分（即：[子载波1的虚部，子载波1的实部，子载波2的虚部，子载波2的实部，子载波3的虚部，子载波3的实部，...]）。
  LTF的顺序为：LLTF、HT-LTF、STBC-HT-LTF。根据通道和分组信息，可能不会出现所有3个LTF。
  he order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. Depending on the channel and grouping information, not all 3 LTFs may appear.
  大致得知数据意义

在仓库根目录tool/下有可视化工具的基本代码和管理文件，你需要在这下面完成你的任务设计
这个工具采用uv管理器进行管理(什么是uv uv 一个高性能python项目管理器)
你需要将他运行起来，并且以这个为参考继续开发

📋 待办列表 (To-Do List)

• 编译并烧录固件到esp32c6上，或者直接在action中选择tag为c6 的bin文件进行烧录
• 成功运行/tools/main.py 并且与开发板建立连接采集到数据
• 完成滤波算法
• 实时数据可视化可以响应人体动作

🎯 完成定义 (验收标准 / Definition of Done)

• 完成待办列表
• 代码经过运行测试且经过不少于一个review
• 必要的文档

🔗 相关 Issue / PR

无

[Lixeer]

esp-radar，结合乐鑫官方的分析工具, 这个组件具有信号处理，抖动，漂移计算。但是其依赖的esp_radar_motion_dec并没有开源。 我们需要根据文档对其进行黑盒逆向，大概复现他的实现，可以根据esp_radar_motion_dec给出的例程

/*
 * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <math.h>
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_radar_motion_dec.h"

static const char *TAG = "motion_dec_test";

#define TEST_COLS 64
#define TEST_ROW_0 10
#define TEST_ROW_1 10
#define TEST_WINDOW_SIZE 5

/**
 * @brief Test esp_radar_motion_dec_compute function
 */
static void test_motion_dec_compute(void)
{
    ESP_LOGI(TAG, "========== Test esp_radar_motion_dec_compute ==========");

    // Use dynamic allocation to avoid stack overflow
    float (*data_0)[TEST_COLS] = (float (*)[TEST_COLS])malloc(TEST_ROW_0 * TEST_COLS * sizeof(float));
    float (*data_1)[TEST_COLS] = (float (*)[TEST_COLS])malloc(TEST_ROW_1 * TEST_COLS * sizeof(float));
    float *output = (float *)malloc(TEST_COLS * sizeof(float));

    if (!data_0 || !data_1 || !output) {
        ESP_LOGE(TAG, "Failed to allocate memory for test data");
        if (data_0) {
            free(data_0);
        }
        if (data_1) {
            free(data_1);
        }
        if (output) {
            free(output);
        }
        return;
    }

    // Initialize test data - first segment: simple incremental pattern
    for (int i = 0; i < TEST_ROW_0; i++) {
        for (int j = 0; j < TEST_COLS; j++) {
            data_0[i][j] = (float)(i * TEST_COLS + j) * 0.1f;
        }
    }

    // Initialize test data - second segment: slightly different pattern
    for (int i = 0; i < TEST_ROW_1; i++) {
        for (int j = 0; j < TEST_COLS; j++) {
            data_1[i][j] = (float)((i + TEST_ROW_0) * TEST_COLS + j) * 0.1f + 0.5f;
        }
    }

    // Call the function
    esp_err_t ret = esp_radar_motion_dec_compute(TEST_COLS,
                                                 TEST_ROW_0, data_0,
                                                 TEST_ROW_1, data_1,
                                                 output);

    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "esp_radar_motion_dec_compute: SUCCESS");
        ESP_LOGI(TAG, "Output sample (first 5 values): %.4f, %.4f, %.4f, %.4f, %.4f",
                 output[0], output[1], output[2], output[3], output[4]);
    } else {
        ESP_LOGE(TAG, "esp_radar_motion_dec_compute: FAILED (ret=%d)", ret);
    }

    // Free memory
    free(data_0);
    free(data_1);
    free(output);
}

/**
 * @brief Test esp_radar_motion_dec_wander_compute function
 */
static void test_wander_compute(void)
{
    ESP_LOGI(TAG, "========== Test esp_radar_motion_dec_wander_compute ==========");

    // Create test vectors
    float vector_a[TEST_COLS];
    float vector_b[TEST_COLS];
    float vector_c[TEST_COLS];

    // Initialize vector A: sine wave pattern
    for (int i = 0; i < TEST_COLS; i++) {
        vector_a[i] = (float)sin(2.0 * M_PI * i / TEST_COLS);
    }

    // Initialize vector B: similar to A (slightly offset)
    for (int i = 0; i < TEST_COLS; i++) {
        vector_b[i] = (float)sin(2.0 * M_PI * i / TEST_COLS + 0.1);
    }

    // Initialize vector C: completely different from A (random values)
    for (int i = 0; i < TEST_COLS; i++) {
        vector_c[i] = (float)(rand() % 100) / 10.0f;
    }

    // Test similar vectors
    float wander_ab = esp_radar_motion_dec_wander_compute(vector_a, vector_b, TEST_COLS);
    ESP_LOGI(TAG, "Wander (similar vectors): %.4f (smaller is more similar)", wander_ab);

    // Test dissimilar vectors
    float wander_ac = esp_radar_motion_dec_wander_compute(vector_a, vector_c, TEST_COLS);
    ESP_LOGI(TAG, "Wander (different vectors): %.4f (smaller is more similar)", wander_ac);

    if (wander_ab < wander_ac) {
        ESP_LOGI(TAG, "Result: Similar vectors have smaller wander value - CORRECT");
    } else {
        ESP_LOGW(TAG, "Result: Unexpected - similar vectors have larger wander value");
    }
}

/**
 * @brief Test esp_radar_motion_dec_compute_jitter function
 */
static void test_jitter_compute(void)
{
    ESP_LOGI(TAG, "========== Test esp_radar_motion_dec_compute_jitter ==========");

    // Create history data buffer
    float *history[TEST_WINDOW_SIZE];
    for (int i = 0; i < TEST_WINDOW_SIZE; i++) {
        history[i] = (float *)malloc(TEST_COLS * sizeof(float));
        if (!history[i]) {
            ESP_LOGE(TAG, "Failed to allocate history buffer %d", i);
            return;
        }
    }

    // Create current data
    float current[TEST_COLS];

    // Initialize history data: stable pattern
    for (int i = 0; i < TEST_WINDOW_SIZE; i++) {
        for (int j = 0; j < TEST_COLS; j++) {
            history[i][j] = (float)sin(2.0 * M_PI * j / TEST_COLS) + i * 0.01f;
        }
    }

    // Test 1: current data similar to history data (stable case)
    for (int j = 0; j < TEST_COLS; j++) {
        current[j] = (float)sin(2.0 * M_PI * j / TEST_COLS) + (TEST_WINDOW_SIZE - 1) * 0.01f;
    }

    float jitter_stable = esp_radar_motion_dec_compute_jitter(current, history, TEST_COLS,
                                                              TEST_WINDOW_SIZE, TEST_WINDOW_SIZE);
    ESP_LOGI(TAG, "Jitter (stable case): %.4f (smaller is more stable)", jitter_stable);

    // Test 2: current data differs significantly from history data (motion case)
    for (int j = 0; j < TEST_COLS; j++) {
        current[j] = (float)(rand() % 100) / 10.0f;
    }

    float jitter_motion = esp_radar_motion_dec_compute_jitter(current, history, TEST_COLS,
                                                              TEST_WINDOW_SIZE, TEST_WINDOW_SIZE);
    ESP_LOGI(TAG, "Jitter (motion case): %.4f (smaller is more stable)", jitter_motion);

    // Test 3: insufficient data case
    float jitter_insufficient = esp_radar_motion_dec_compute_jitter(current, history, TEST_COLS,
                                                                    TEST_WINDOW_SIZE, 2);
    ESP_LOGI(TAG, "Jitter (insufficient data): %.4f (should be 0.0)", jitter_insufficient);

    // Free memory
    for (int i = 0; i < TEST_WINDOW_SIZE; i++) {
        free(history[i]);
    }
}

void app_main()
{
    ESP_LOGI(TAG, "ESP Radar Motion Detection Test Application");
    ESP_LOGI(TAG, "===========================================");

    vTaskDelay(pdMS_TO_TICKS(1000));

    // Run all tests
    test_motion_dec_compute();
    vTaskDelay(pdMS_TO_TICKS(500));

    test_wander_compute();
    vTaskDelay(pdMS_TO_TICKS(500));

    test_jitter_compute();
    vTaskDelay(pdMS_TO_TICKS(500));

    ESP_LOGI(TAG, "===========================================");
    ESP_LOGI(TAG, "All tests completed!");
}

逆向出以下三个函数的大致代码

/**
 * @brief Compute motion detection result
 *
 * @param cols Number of subcarriers (columns)
 * @param row_0 Number of rows in the first data segment
 * @param data_0 First data segment [row_0][cols]
 * @param row_1 Number of rows in the second data segment
 * @param data_1 Second data segment [row_1][cols]
 * @param output Output result [cols]
 * @return esp_err_t ESP_OK on success
 */
esp_err_t esp_radar_motion_dec_compute(uint32_t cols,
                                       uint32_t row_0, const float data_0[row_0][cols],
                                       uint32_t row_1, const float data_1[row_1][cols],
                                       float output[cols]);

/**
 * @brief Compute waveform wander
 *
 * @param a Vector A
 * @param b Vector B
 * @param len Vector length
 * @return float Waveform wander value [0.0, 1.0], smaller value indicates more similarity (more stable)
 */
float esp_radar_motion_dec_wander_compute(const float *a, const float *b, size_t len);

/**
 * @brief Compute waveform jitter
 *
 * @param current Current result [cols]
 * @param history History data buffer [window_size][cols]
 * @param cols Number of subcarriers
 * @param window_size Window size
 * @param buff_num Current buffer count (used to index history data)
 * @return float Computed jitter value [0.0, 1.0], smaller value indicates more stability, returns 0.0 if data is insufficient
 */
float esp_radar_motion_dec_compute_jitter(float *current,
                                          float **history,
                                          uint16_t cols,
                                          uint8_t window_size,
                                          uint32_t buff_num);

[Lixeer]

esp_radar_motion_dec_wander_compute 黑盒逆向结果

/**
 * @brief  计算两个向量余弦值相似度
 * 
 * @param[in]  a  第一个向量
 * @param[in]  b  第二个向量
 * 
 * @return 返回[0.0,1.0] 越大相似度越大
 
**/


float esp_radar_motion_dec_wander_compute(float a[], float b[], int len) {
    float dot = 0, norm_a = 0, norm_b = 0;
    
    for (int i = 0; i < len; i++) {
        dot += a[i] * b[i];
        norm_a += a[i] * a[i];
        norm_b += b[i] * b[i];
    }
    
    // 防止除零
    if (norm_a == 0 || norm_b == 0) return 1.0f;
    
    float norm_product = sqrtf(norm_a) * sqrtf(norm_b);
    float cos_sim = dot / norm_product;
    
    // 限制余弦相似度在 [-1, 1] 范围内（防止浮点误差）
    if (cos_sim > 1.0f) cos_sim = 1.0f;
    if (cos_sim < -1.0f) cos_sim = -1.0f;
    
    float result = 1.0f - cos_sim;
    
    // result 范围理论上在 [0, 2]，限制到 [0, 1]
    if (result > 1.0f) return 1.0f;
    return result;
}

esp_radar_motion_dec_compute_jitter大致实现（猜测）

float esp_radar_motion_dec_compute_jitter(float *current, float **history,
                                              uint16_t cols, uint8_t window_size,
                                              uint32_t buff_num) {
    if (buff_num < window_size) return 0.0f;
    
    float total_error = 0.0f;
    
    for (int j = 0; j < cols; j++) {
        // 使用最后两个点的线性预测
        float predicted;
        if (window_size >= 2) {
            float prev1 = history[window_size-1][j];
            float prev2 = history[window_size-2][j];
            predicted = prev1 + (prev1 - prev2); // 线性外推
        } else {
            predicted = history[0][j];
        }
        
        float error = fabsf(current[j] - predicted);
        
        // 关键：只有误差超过阈值才计数（模拟对随机波动的敏感）
        float threshold = 0.1f;
        if (error > threshold) {
            total_error += (error - threshold) / (1.0f - threshold);
        }
    }
    
    float jitter = total_error / cols;
    return jitter > 1.0f ? 1.0f : jitter;
}