Merge branch 'add_esp_crab' into 'master'

add_esp-crab

See merge request esp-components/esp-csi-ext!62

Author: Ning Yu Xiang

components/esp-radar/idf_component.yml

@@ -1,11 +1,12 @@
-version: "0.2.0"
+version: "0.2.1"
 description: This package provides algorithmic functionality for ESP-CSI human movement and presence detection for easy integration into products.
 url: https://github.com/espressif/esp-csi/tree/master/esp-radar
 issues: https://github.com/espressif/esp-csi/issues
 targets:
   - esp32
   - esp32s3
   - esp32c3
+  - esp32c5
 dependencies:
   idf: ">=4.4.1"
   cmake_utilities: "0.*"

components/esp-radar/include/esp_radar.h

@@ -26,7 +26,7 @@ extern "C"
 {
 #endif
 
-#if CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3
+#if CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32C5 || CONFIG_IDF_TARGET_ESP32C6
 #define WIFI_CSI_PHY_GAIN_ENABLE          1
 #endif
 
@@ -140,7 +140,7 @@ typedef struct {
         .shift             = 4, \
     } \
 }
-  
+
 /**
   * @brief Set Wi-Fi radar configuration
   *
@@ -229,22 +229,80 @@ esp_err_t esp_radar_train_stop(float *wander_threshold, float *jitter_threshold)
 
 #if WIFI_CSI_PHY_GAIN_ENABLE
 /**
- * @brief 
+ * @brief Retrieve the gain baseline of the receive gain
  * 
  * @param agc_gain 
  * @param fft_gain 
  * @return esp_err_t 
  */
-esp_err_t esp_radar_get_rx_gain(uint8_t* agc_gain, int8_t *fft_gain);
+esp_err_t esp_radar_get_rx_gain_baseline(uint8_t* agc_gain, int8_t *fft_gain);
+
 
 /**
- * @brief 
+ * @brief Force setting the receive gain, but it may lead to packet loss.
+ * 
+ * @param agc_gain 
+ * @param fft_gain 
+ * @return esp_err_t 
+ */
+esp_err_t esp_radar_set_rx_force_gain(uint8_t agc_gain, int8_t fft_gain);
+
+/**
+ * @brief To calculate the gain baseline, record the receive gain.
  * 
  * @param agc_gain 
  * @param fft_gain 
  * @return esp_err_t 
  */
-esp_err_t esp_radar_set_rx_gain(uint8_t agc_gain, int8_t fft_gain);
+esp_err_t esp_radar_record_rx_gain(uint8_t agc_gain, int8_t fft_gain);
+
+/**
+  * @brief  Reset rx gain baseline
+  * @return esp_err_t
+  */
+void esp_radar_reset_rx_gain_baseline(void);
+
+/**
+  * @brief  This function compensates the input data based on the provided AGC gain and FFT gain.
+  *         It adjusts the data by applying compensation calculated from the AGC gain and FFT gain values.
+  *
+  * @param data            Pointer to the data to be compensated.
+  * @param size            Size of the data array.
+  * @param compensate_gain Pointer to store the computed compensation gain.
+  * @param agc_gain        AGC gain value used for compensation.
+  * @param fft_gain        FFT gain value used for compensation.
+  *
+  * @return
+  *    - ESP_OK: Compensation successfully applied.
+  *    - ESP_ERR_INVALID_STATE: Invalid state, compensation cannot be applied.
+  */
+esp_err_t esp_radar_compensate_rx_gain(int8_t *data, uint16_t size, float *compensate_gain, uint8_t agc_gain, int8_t fft_gain);
+
+/**
+  * @brief  Get the gain compensation value based on the provided AGC gain and FFT gain.
+  *
+  * @param compensate_gain Pointer to store the calculated gain compensation value.
+  * @param agc_gain Automatic Gain Control (AGC) gain value used for compensation.
+  * @param fft_gain Fast Fourier Transform (FFT) gain value used for compensation.
+  *
+  * @return
+  *    - ESP_OK: Compensation successfully applied.
+  *    - ESP_ERR_INVALID_STATE: Invalid state, compensation cannot be applied.
+  */
+esp_err_t esp_radar_get_gain_compensation(float *compensate_gain, uint8_t agc_gain, int8_t fft_gain);
+
+/**
+  * @brief  Retrieve the RX gain values from CSI packet information.
+  * 
+  * @param info      Pointer to the wifi_csi_info_t structure.
+  * @param agc_gain Pointer to store the AGC gain value.
+  * @param fft_gain Pointer to store the FFT gain value.
+  *
+  * @return esp_err_t Returns ESP_OK on success, or ESP_ERR_INVALID_ARG if input parameters are invalid.
+  */
+
+esp_err_t esp_radar_get_rx_gain(wifi_csi_info_t *info, uint8_t* agc_gain, int8_t* fft_gain);
+
 #endif
 
 #ifdef __cplusplus

components/esp-radar/lib/esp32c5/libesp-radar.a

@@ -0,0 +1,12 @@
+# Example Projects
+[[中文]](./README_cn.md)  
+This directory contains multiple example projects for esp-csi. These examples are intended to demonstrate various features of esp-csi and provide code that can be copied and adapted for your own projects.
+
+- `get-started/csi_recv`: A basic CSI data reception example showing how to obtain CSI information via a Wi-Fi receiver.
+- `get-started/csi_send`: A basic CSI transmission example designed to work with `csi_recv`, sending Wi-Fi packets for the receiver to extract CSI.
+- `get-started/csi_recv_router`: Receives CSI in router communication mode by pinging a router and parsing the CSI from its reply packets.
+- `esp-radar/connect_rainmaker`: Connects CSI data to Espressif's Rainmaker cloud platform for remote visualization or control.
+- `esp-radar/console_test`: A console-based testing example for debugging and evaluating CSI data and algorithm performance.
+- `esp-crab/master_recv`: The master receiver for the esp-crab hardware platform; responsible for acquiring and parsing Wi-Fi CIR/CSI data.
+- `esp-crab/slave_recv`: The slave receiver on the esp-crab platform, assisting the master receiver with multi-channel data collection.
+- `esp-crab/slave_send`: The transmitter on the esp-crab platform, responsible for sending packets periodically for CSI extraction by other nodes.

examples/README.md

@@ -0,0 +1,12 @@
+# 示例程序
+[[English]](./README.md)  
+本目录包含多个 esp-csi 示例项目。这些示例旨在演示  esp-csi 的部分功能，并提供可以复制和修改以用于自己项目的代码。
+
+- `get-started/csi_recv`：基本的 CSI 数据接收示例，展示如何通过 Wi-Fi 接收端获取 CSI 信息。
+- `get-started/csi_send`：基本的 CSI 发送端示例，用于配合 `csi_recv` 发送 Wi-Fi 包以供接收侧获取 CSI。
+- `get-started/csi_recv_router`：在路由器通信模式下接收 CSI，通过 ping 路由器并解析其应答包中的 CSI 信息。
+- `esp-radar/connect_rainmaker`：将 CSI 数据与 Espressif 的云平台 Rainmaker 连接，用于远程展示或控制。
+- `esp-radar/console_test`：用于控制台调试测试 CSI 数据和算法效果的示例。
+- `esp-crab/master_recv`：esp-crab 硬件平台上的主接收端，支持获取并解析 Wi-Fi CIR/CSI 数据。
+- `esp-crab/slave_recv`：esp-crab 平台的从接收端，辅助主接收端进行多通道数据收集。
+- `esp-crab/slave_send`：esp-crab 平台的发送端，负责定时发送数据包供其他节点进行接收和 CSI 提取。

examples/README_cn.md

@@ -0,0 +1,128 @@
+# Co-Crystal Oscillator CSI Reception Example
+
+* [中文版](./README_CN.md)
+
+This example provides a radio frequency phase synchronization solution for Wi-Fi CSI, including three sub-projects: `MASTER_RECV` (master receiver), `SLAVE_RECV` (slave receiver), and `SLAVE_SEND` (slave sender).  
+The solution includes two working modes:  
+1. Self-transmit-and-receive mode  
+2. Single-transmit-and-dual-receive mode
+
+## Feature Introduction
+
+### 1. Self-Transmit-and-Receive Mode
+
+In this mode, two ESP32-C5 chips are used to transmit and receive signals respectively. By analyzing the phase information in the received Wi-Fi CSI signals, disturbances in the signal path can be sensed with millimeter-level accuracy.  
+By installing copper sheets to control the RF signal transmission path, the sensing range can also be adjusted, thus supporting high-precision short-range Wi-Fi sensing.  
+This enables finer Wi-Fi signal sensing, suitable for precise applications in close-range and complex environments.
+
+![Self-Transmission and Reception Amplitude](<doc/img/Self-Transmission and Reception Amplitude.gif>)  
+![Self-Transmission and Reception Phase](<doc/img/Self-Transmission and Reception Phase.gif>)
+
+#### 1.1 MASTER_RECV (Master Receiver)
+
+Flash the `MASTER_RECV` firmware to the **Master** chip of the `esp-crab` device. Its functions include:
+
+* Receiving Wi-Fi packets from the `SLAVE_SEND` and extracting **CIR (Channel Impulse Response)** data.
+* Calculating the **amplitude and phase** of Wi-Fi CSI from the CIR and displaying the results.
+
+#### 1.2 SLAVE_SEND (Slave Sender)
+
+Flash the `SLAVE_SEND` firmware to the **Slave** chip of the `esp-crab` device. Its function:
+
+* Transmitting specific Wi-Fi packets.
+
+### 2. Single-Transmit-and-Dual-Receive Mode
+
+In this mode, one ESP32-C5 chip is responsible for signal transmission, while the two ESP32-C5 chips on the `esp-crab` device receive signals.  
+By spatially distributing the sender and receivers, Wi-Fi sensing can be realized over a **larger area**.  
+The **co-crystal oscillator Wi-Fi CSI data** acquired by the `esp-crab` satisfies the performance requirements of cutting-edge Wi-Fi sensing research, and can be directly integrated with advanced algorithms, further improving the **accuracy and application value** of the sensing system.  
+This mode offers strong technical support for **wide-area and complex environment wireless sensing and positioning**.
+
+![Single-Transmission and Dual-Reception Phase](<doc/img/Single-Transmission and Dual-Reception Phase.gif>)
+
+#### 2.1 MASTER_RECV (Master Receiver)
+
+Flash the `MASTER_RECV` firmware to the **Master** chip of the `esp-crab` device. Its functions include:
+
+* Receiving Wi-Fi packets from `SLAVE_SEND` via antenna and extracting **CIR data**.
+* Receiving CIR data from the `SLAVE_RECV` chip (collected via its antenna).
+* Calculating the **amplitude and phase difference** of Wi-Fi CSI and displaying the result.
+
+#### 2.2 SLAVE_RECV (Slave Receiver)
+
+Flash the `SLAVE_RECV` firmware to the **Slave** chip of the `esp-crab` device. It supports two modes:
+
+* Receiving Wi-Fi packets from `SLAVE_SEND` and extracting **CIR data**.
+* Transmitting the CIR data to `MASTER_RECV`.
+
+#### 2.3 SLAVE_SEND (Slave Sender)
+
+Flash the `SLAVE_SEND` firmware to an extra **ESP32-C5 chip** (e.g., `ESP32-C5-DevkitC-1`). Its function:
+
+* Transmitting specific Wi-Fi packets.
+
+## Required Hardware
+
+### `esp-crab` Device
+
+#### PCB Overview
+
+The RF phase synchronization solution must run on the `esp-crab` device. The images below show the front and back of the PCB:
+
+| No. | Function                          |
+|-----|-----------------------------------|
+| 1   | Master external antenna           |
+| 2   | Master onboard antenna            |
+| 3   | Slave external antenna            |
+| 4   | Slave onboard antenna             |
+| 5   | Master BOOT button                |
+| 6   | Master ADC button                 |
+| 7   | Slave BOOT button                 |
+| 8   | Master 2.4G antenna switch resistor |
+| 9   | Master 5G antenna switch resistor |
+| 10  | Slave 5G antenna switch resistor  |
+| 11  | Slave 2.4G antenna switch resistor |
+| 12  | RST button                        |
+
+![esp_crab_pcb_front](doc/img/esp_crab_pcb_front.png)  
+![esp_crab_pcb_back](doc/img/esp_crab_pcb_back.jpg)
+
+See [PCB V1.1](doc/PCB_ESP_CRAB_ESP32C5_V1_1.pdf) and [SCH V1.1](doc/SCH_ESP_CRAB_ESP32C5_V1_1.pdf) for the PCB schematic and design.
+
+#### Device Form Factor
+
+The `esp-crab` device has two casing styles based on mode:
+
+* Spaceship case for Self-transmit-and-receive mode  
+  ![Alt text](doc/img/shape_style.png)
+* Router-style case for Single-transmit-and-dual-receive mode  
+  ![router_shape](doc/img/router_style.png)
+
+### `ESP32-C5-DevkitC-1` Development Board
+
+The Single-transmit-and-dual-receive mode requires an `ESP32-C5-DevkitC-1` board as the Wi-Fi sender.
+
+## How to Use the Example
+
+### 1. Self-Transmit-and-Receive Mode
+
+Power the `esp-crab` via Type-C and it will begin operation. It will display CSI amplitude and phase:
+
+* **Amplitude**: Two curves representing CIR amplitude for -Nsr~0 and 0~Nsr.
+* **Phase**: A standard sine curve. The intersection with the red center line represents the CIR phase for 0~Nsr.
+
+At the same time, `esp-crab` will print received CSI data to the serial port in the following format:  
+`type,id,mac,rssi,rate,noise_floor,fft_gain,agc_gain,channel,local_timestamp,sig_len,rx_state,len,first_word,data`
+
+Example:
+
+``` text
+CSI_DATA,3537,1a:00:00:00:00:00,-17,11,159,22,5,8,859517,47,0,234,0,"[14,9,13,...,-11]"
+```
+
+> **Note:** Upon power-up, the device collects the first 100 Wi-Fi packets to determine the RF reception gain.
+
+### 2. Single-Transmit-and-Dual-Receive Mode
+
+In this mode, both the `esp-crab` and the `ESP32-C5-DevkitC-1` need to be powered and placed at a certain distance from each other.  
+The `esp-crab` will then display the amplitude and phase information of the CSI, and simultaneously print the received `CSI` data to the serial port, as described earlier.

examples/esp-crab/README.md

@@ -0,0 +1,117 @@
+# 共晶振CSI接收示例
+
+* [English Version](./README.md)
+
+此示例提供了一种 Wifi-CSI 的射频相位同步解决方案，包含三个子项目：MASTER_RECV（主接收端）、SLAVE_RECV（从接收端）、SLAVE_SEND（从发送端）。
+该方案包含两种工作模式：1、自发自收模式；2、单发双收模式
+
+## 功能介绍
+
+### 1. 自发自收模式
+
+在该模式下，两片 ESP32-C5 芯片分别发送和接收信号，通过计算接收 Wi-Fi CSI 信号中的相位信息，可以毫米级地感知射频信号路径中的扰动。同时，通过安装铜片控制射频信号的传输路径，也可以调节感知范围，从而为高精度的近距离 Wi-Fi 感知提供技术支持。这种模式使得 Wi-Fi 信号感知更加精细，适用于近距离和复杂环境中的精确感知应用。
+
+![Self-Transmission and Reception Amplitude](<doc/img/Self-Transmission and Reception Amplitude.gif>)
+![Self-Transmission and Reception Phase](<doc/img/Self-Transmission and Reception Phase.gif>)
+
+#### 1.1 MASTER_RECV（主接收端）
+
+将 `MASTER_RECV` 固件烧录至 `esp-crab` 设备的 **Master** 芯片，其功能包括：
+
+* 接收来自 `SLAVE_SEND` 端的 WiFi 数据包，并提取数据中的 **CIR (Channel Impulse Response)** 信息。
+* 基于接收到的 CIR 信息，计算 Wifi-CSI 的 **幅度和相位**，并将结果显示。
+
+#### 1.2 SLAVE_SEND（从发送端）
+
+将 `SLAVE_SEND` 固件烧录至 `esp-crab` 设备的 **Slave** 芯片，其功能包括：
+
+* 发送特定的wifi数据包。
+
+### 2. 单发双收模式
+
+此模式下，一片 ESP32-C5 芯片负责发送信号，而 `esp-crab` 的两片 ESP32-C5 芯片则负责接收信号。通过分散部署发送端和接收端，可以在 **大范围空间** 内实现 Wi-Fi 感知。`esp-crab` 获取的 **共晶振 Wi-Fi CSI 信息** 能够满足前沿研究中的 Wi-Fi 感知性能需求，并且可以直接对接成熟的高级算法，进一步提升无线感知系统的 **精度和应用价值**。该模式为 **大范围、复杂环境下的无线感知和定位** 提供了强大的技术支撑。
+
+![Single-Transmission and Dual-Reception Phase](<doc/img/Single-Transmission and Dual-Reception Phase.gif>)  
+
+#### 2.1 MASTER_RECV（主接收端）
+
+将 `MASTER_RECV` 固件烧录至 `esp-crab` 设备的 **Master** 芯片，其功能包括：
+
+* 通过天线接收来自 `SLAVE_SEND` 的 Wi-Fi 数据包，并提取 **CIR 信息**。
+* 同时接收来自 `SLAVE_RECV` 的 CIR 信息（该信息由从接收端的天线收集）。
+* 计算 Wi-Fi CSI 的 **幅度和相位差值**，并将结果显示。
+
+#### 2.2 SLAVE_RECV（从接收端）
+
+将 `SLAVE_RECV` 固件烧录至 `esp-crab` 设备的 **Slave** 芯片，支持以下两种模式：
+
+* 通过天线接收来自 `SLAVE_SEND` 的 Wi-Fi 数据包，并提取 **CIR 信息**。
+* 将接收到的 CIR 信息发送到 `MASTER_RECV`。
+
+#### 2.3 SLAVE_SEND（从发送端）
+
+将 `SLAVE_SEND` 固件烧录至额外的 **ESP32-C5 芯片**（例如 `ESP32-C5-DevkitC-1`），其功能包括：
+
+* 发送特定的 Wi-Fi 数据包。
+
+## 所需硬件
+
+### `esp-crab` 设备
+
+#### PCB介绍  
+
+射频相位同步解决方案需要运行在 `esp-crab` 设备上，下面的图片显示了PCB的正面和背面。
+
+| 序号 | 功能                     |
+|------|--------------------------|
+| 1    | Master 外接天线          |
+| 2    | Master 板载天线          |
+| 3    | Slave 外接天线           |
+| 4    | Slave 板载天线           |
+| 5    | Master BOOT 按键         |
+| 6    | Master ADC 按键          |
+| 7    | Slave BOOT 按键          |
+| 8    | Master 2.4G天线切换电阻  |
+| 9    | Master 5G天线切换电阻    |
+| 10   | Slave 5G天线切换电阻     |
+| 11   | Slave 2.4G天线切换电阻   |
+| 12   | RST 按键                 |
+
+![esp_crab_pcb_front](doc/img/esp_crab_pcb_front.png)
+![esp_crab_pcb_back](doc/img/esp_crab_pcb_back.jpg)
+
+参考 [PCB V1.1](doc/PCB_ESP_CRAB_ESP32C5_V1_1.pdf) 和 [SCH V1.1](doc/SCH_ESP_CRAB_ESP32C5_V1_1.pdf) 查看PCB的原理图和PCB。
+
+#### 形态介绍
+
+`esp-crab` 设备根据功能的不同，具有两种外壳形式，
+
+* 自发自收模式的飞船外形
+![Alt text](doc/img/shape_style.png)
+* 单发双收模式的飞船外形
+![router_shape](doc/img/router_style.png)
+
+### `ESP32-C5-DevkitC-1`开发板
+
+单发双收模式需要一个`ESP32-C5-DevkitC-1`开发板作为wifi发送端。
+
+## 如何使用样例
+
+### 1. 自发自收模式
+
+自发自收模式只要为 `esp-crab` 通过 Type-c 供电，就可以开始工作，`esp-crab` 即会显示CIS的幅度和相位信息。
+
+* 幅度信息：两条曲线分别为 -Nsr~0 和 0~Nsr 对应CIR的幅度信息。
+* 相位信息：曲线为标准正弦曲线，曲线与屏幕中心红线的交点为 0~Nsr 对应CIR的相位信息。
+
+同时`esp-crab`会在串口打印接收到的 `CSI` 数据，按 `type,id,mac,rssi,rate,noise_floor,fft_gain,agc_gain,channel,local_timestamp,sig_len,rx_state,len,first_word,data` 顺序打印如下所示的数据。
+
+```text
+CSI_DATA,3537,1a:00:00:00:00:00,-17,11,159,22,5,8,859517,47,0,234,0,"[14,9,13,10,13,11,13,12,17,13,16,14,16,16,16,16,15,18,17,17,17,21,15,20,16,22,17,23,15,25,16,23,17,21,13,25,15,23,14,21,17,24,16,22,16,21,19,20,18,21,17,18,18,20,17,20,17,21,18,19,18,18,20,19,19,15,19,17,21,16,21,16,21,15,22,13,24,14,24,11,23,9,24,9,25,9,25,7,25,9,26,7,26,6,24,5,26,6,26,4,26,3,28,2,28,2,29,2,30,-1,28,-1,24,-3,0,0,0,0,0,0,-6,-28,-7,-28,-5,-28,-7,-28,-6,-28,-9,-26,-9,-26,-10,-27,-12,-27,-10,-24,-10,-23,-11,-25,-13,-24,-16,-22,-17,-25,-16,-22,-20,-21,-19,-20,-18,-23,-17,-19,-18,-16,-21,-19,-19,-17,-19,-17,-23,-18,-21,-17,-22,-13,-22,-13,-23,-14,-24,-14,-23,-12,-24,-14,-23,-13,-25,-12,-24,-11,-28,-12,-24,-11,-25,-10,-27,-10,-25,-12,-26,-10,-26,-10,-26,-12,-29,-11,-27,-12,-25,-11,-23,-13,-22,-12,-20,-14,-21,-13,-20,-13,-18,-11,-14,-13,-16,-11,-13,-11,-12,-10,-11,-11]"
+```
+
+> 注：上电设备会采集前一百个wifi包来确定wifi射频接收增益。
+
+### 2. 单发双收模式
+
+单发双收模式要为 `esp-crab` 和 `ESP32-C5-DevkitC-1` 供电，并布置在有一定距离的空间内，`esp-crab` 即会显示CIS的幅度和相位信息。同时`esp-crab`会在串口打印接收到如前文所示的 `CSI` 数据。