Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 92a5182

Browse files
ruvnetruvnet
committed
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 <[email protected]>
1 parent 885627b commit 92a5182

22 files changed

Lines changed: 1790 additions & 173 deletions

File tree

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
# ESP32 firmware build artifacts and local config (contains WiFi credentials)
2+
firmware/esp32-csi-node/build/
3+
firmware/esp32-csi-node/sdkconfig
4+
firmware/esp32-csi-node/sdkconfig.defaults
5+
firmware/esp32-csi-node/sdkconfig.old
6+
17
# Byte-compiled / optimized / DLL files
28
__pycache__/
39
*.py[cod]

‎README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,44 @@ A cutting-edge WiFi-based human pose estimation system that leverages Channel St
3434
- **WebSocket Streaming**: Real-time pose data streaming for live applications
3535
- **100% Test Coverage**: Thoroughly tested with comprehensive test suite
3636

37+
## ESP32-S3 Hardware Pipeline (ADR-018)
38+
39+
End-to-end WiFi CSI capture verified on real hardware:
40+
41+
```
42+
ESP32-S3 (STA + promiscuous) UDP/5005 Rust aggregator
43+
┌─────────────────────────┐ ──────────> ┌──────────────────┐
44+
│ WiFi CSI callback 20 Hz │ ADR-018 │ Esp32CsiParser │
45+
│ ADR-018 binary frames │ binary │ CsiFrame output │
46+
│ stream_sender (UDP) │ │ presence detect │
47+
└─────────────────────────┘ └──────────────────┘
48+
```
49+
50+
| Metric | Measured |
51+
|--------|----------|
52+
| Frame rate | ~20 Hz sustained |
53+
| Subcarriers | 64 / 128 / 192 (LLTF, HT, HT40) |
54+
| Latency | < 1ms (UDP loopback) |
55+
| Presence detection | Motion score 10/10 at 3m |
56+
57+
**Quick start:**
58+
59+
```bash
60+
# 1. Build firmware (Docker)
61+
cd firmware/esp32-csi-node
62+
docker run --rm -v "$(pwd):/project" -w /project espressif/idf:v5.2 \
63+
bash -c "idf.py set-target esp32s3 && idf.py build"
64+
65+
# 2. Flash to ESP32-S3
66+
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
67+
write-flash @build/flash_args
68+
69+
# 3. Run aggregator
70+
cargo run -p wifi-densepose-hardware --bin aggregator -- --bind 0.0.0.0:5005
71+
```
72+
73+
See [`firmware/esp32-csi-node/README.md`](firmware/esp32-csi-node/README.md) for detailed setup.
74+
3775
## 🦀 Rust Implementation (v2)
3876

3977
A high-performance Rust port is available in `/rust-port/wifi-densepose-rs/`:

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# ESP32 CSI Node Firmware (ADR-018)
2+
# Requires ESP-IDF v5.2+
3+
cmake_minimum_required(VERSION 3.16)
4+
5+
set(EXTRA_COMPONENT_DIRS "")
6+
7+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
8+
project(esp32-csi-node)

‎firmware/esp32-csi-node/README.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# ESP32-S3 CSI Node Firmware (ADR-018)
2+
3+
Firmware for ESP32-S3 that collects WiFi Channel State Information (CSI)
4+
and streams it as ADR-018 binary frames over UDP to the aggregator.
5+
6+
Verified working with ESP32-S3-DevKitC-1 (CP2102, MAC 3C:0F:02:EC:C2:28)
7+
streaming ~20 Hz CSI to the Rust aggregator binary.
8+
9+
## Prerequisites
10+
11+
| Component | Version | Purpose |
12+
|-----------|---------|---------|
13+
| Docker Desktop | 28.x+ | Cross-compile ESP-IDF firmware |
14+
| esptool | 5.x+ | Flash firmware to ESP32 |
15+
| ESP32-S3 board | - | Hardware (DevKitC-1 or similar) |
16+
| USB-UART driver | CP210x | Silicon Labs driver for serial |
17+
18+
## Quick Start
19+
20+
### Step 1: Configure WiFi credentials
21+
22+
Create `sdkconfig.defaults` in this directory (it is gitignored):
23+
24+
```
25+
CONFIG_IDF_TARGET="esp32s3"
26+
CONFIG_ESP_WIFI_CSI_ENABLED=y
27+
CONFIG_CSI_NODE_ID=1
28+
CONFIG_CSI_WIFI_SSID="YOUR_WIFI_SSID"
29+
CONFIG_CSI_WIFI_PASSWORD="YOUR_WIFI_PASSWORD"
30+
CONFIG_CSI_TARGET_IP="192.168.1.20"
31+
CONFIG_CSI_TARGET_PORT=5005
32+
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
33+
```
34+
35+
Replace `YOUR_WIFI_SSID`, `YOUR_WIFI_PASSWORD`, and `CONFIG_CSI_TARGET_IP`
36+
with your actual values. The target IP is the machine running the aggregator.
37+
38+
### Step 2: Build with Docker
39+
40+
```bash
41+
cd firmware/esp32-csi-node
42+
43+
# On Linux/macOS:
44+
docker run --rm -v "$(pwd):/project" -w /project \
45+
espressif/idf:v5.2 bash -c "idf.py set-target esp32s3 && idf.py build"
46+
47+
# On Windows (Git Bash — MSYS path fix required):
48+
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd -W)://project" -w //project \
49+
espressif/idf:v5.2 bash -c "idf.py set-target esp32s3 && idf.py build"
50+
```
51+
52+
Build output: `build/bootloader.bin`, `build/partition_table/partition-table.bin`,
53+
`build/esp32-csi-node.bin`.
54+
55+
### Step 3: Flash to ESP32-S3
56+
57+
Find your serial port (`COM7` on Windows, `/dev/ttyUSB0` on Linux):
58+
59+
```bash
60+
cd firmware/esp32-csi-node/build
61+
62+
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
63+
--before default-reset --after hard-reset \
64+
write-flash --flash-mode dio --flash-freq 80m --flash-size 4MB \
65+
0x0 bootloader/bootloader.bin \
66+
0x8000 partition_table/partition-table.bin \
67+
0x10000 esp32-csi-node.bin
68+
```
69+
70+
### Step 4: Run the aggregator
71+
72+
```bash
73+
cargo run -p wifi-densepose-hardware --bin aggregator -- --bind 0.0.0.0:5005 --verbose
74+
```
75+
76+
Expected output:
77+
```
78+
Listening on 0.0.0.0:5005...
79+
[148 bytes from 192.168.1.71:60764]
80+
[node:1 seq:0] sc=64 rssi=-49 amp=9.5
81+
[276 bytes from 192.168.1.71:60764]
82+
[node:1 seq:1] sc=128 rssi=-64 amp=16.0
83+
```
84+
85+
### Step 5: Verify presence detection
86+
87+
If you see frames streaming (~20/sec), the system is working. Walk near the
88+
ESP32 and observe amplitude variance changes in the CSI data.
89+
90+
## Configuration Reference
91+
92+
Edit via `idf.py menuconfig` or `sdkconfig.defaults`:
93+
94+
| Setting | Default | Description |
95+
|---------|---------|-------------|
96+
| `CSI_NODE_ID` | 1 | Unique node identifier (0-255) |
97+
| `CSI_TARGET_IP` | 192.168.1.100 | Aggregator host IP |
98+
| `CSI_TARGET_PORT` | 5005 | Aggregator UDP port |
99+
| `CSI_WIFI_SSID` | wifi-densepose | WiFi network SSID |
100+
| `CSI_WIFI_PASSWORD` | (empty) | WiFi password |
101+
| `CSI_WIFI_CHANNEL` | 6 | WiFi channel to monitor |
102+
103+
## Firewall Note
104+
105+
On Windows, you may need to allow inbound UDP on port 5005:
106+
107+
```
108+
netsh advfirewall firewall add rule name="ESP32 CSI" dir=in action=allow protocol=UDP localport=5005
109+
```
110+
111+
## Architecture
112+
113+
```
114+
ESP32-S3 Host Machine
115+
+-------------------+ +-------------------+
116+
| WiFi CSI callback | UDP/5005 | aggregator binary |
117+
| (promiscuous mode)| ──────────> | (Rust, clap CLI) |
118+
| ADR-018 serialize | ADR-018 | Esp32CsiParser |
119+
| stream_sender.c | binary frames | CsiFrame output |
120+
+-------------------+ +-------------------+
121+
```
122+
123+
## Binary Frame Format (ADR-018)
124+
125+
```
126+
Offset Size Field
127+
0 4 Magic: 0xC5110001
128+
4 1 Node ID
129+
5 1 Number of antennas
130+
6 2 Number of subcarriers (LE u16)
131+
8 4 Frequency MHz (LE u32)
132+
12 4 Sequence number (LE u32)
133+
16 1 RSSI (i8)
134+
17 1 Noise floor (i8)
135+
18 2 Reserved
136+
20 N*2 I/Q pairs (n_antennas * n_subcarriers * 2 bytes)
137+
```
138+
139+
## Troubleshooting
140+
141+
| Symptom | Cause | Fix |
142+
|---------|-------|-----|
143+
| No serial output | Wrong baud rate | Use 115200 |
144+
| WiFi won't connect | Wrong SSID/password | Check sdkconfig.defaults |
145+
| No UDP frames | Firewall blocking | Add UDP 5005 inbound rule |
146+
| CSI callback not firing | Promiscuous mode off | Verify `esp_wifi_set_promiscuous(true)` in csi_collector.c |
147+
| Parse errors in aggregator | Firmware/parser mismatch | Rebuild both from same source |

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
idf_component_register(
2+
SRCS "main.c" "csi_collector.c" "stream_sender.c"
3+
INCLUDE_DIRS "."
4+
)

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
menu "CSI Node Configuration"
2+
3+
config CSI_NODE_ID
4+
int "Node ID (0-255)"
5+
default 1
6+
range 0 255
7+
help
8+
Unique identifier for this ESP32 CSI node.
9+
10+
config CSI_TARGET_IP
11+
string "Aggregator IP address"
12+
default "192.168.1.100"
13+
help
14+
IP address of the UDP aggregator host.
15+
16+
config CSI_TARGET_PORT
17+
int "Aggregator UDP port"
18+
default 5005
19+
range 1024 65535
20+
help
21+
UDP port the aggregator listens on.
22+
23+
config CSI_WIFI_SSID
24+
string "WiFi SSID"
25+
default "wifi-densepose"
26+
help
27+
SSID of the WiFi network to connect to.
28+
29+
config CSI_WIFI_PASSWORD
30+
string "WiFi Password"
31+
default ""
32+
help
33+
Password for the WiFi network. Leave empty for open networks.
34+
35+
config CSI_WIFI_CHANNEL
36+
int "WiFi Channel (1-13)"
37+
default 6
38+
range 1 13
39+
help
40+
WiFi channel to listen on for CSI data.
41+
42+
endmenu

0 commit comments

Comments
 (0)