docs: Complete v0.1 documentation sprint
- Add build & flash workflow (docs/INSTALL.md) - Add CSI config reference and firmware comparison (docs/USAGE.md) - Add quick reference cheatsheet (docs/CHEATSHEET.md) - Add dependencies.lock to .gitignore (env-specific) - Update TASKS.md with completed items and build notes - Verified firmware builds on ESP-IDF v6.1.0 / aarch64
This commit is contained in:
user
200
docs/USAGE.md
Normal file
200
docs/USAGE.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Usage Guide
|
||||
|
||||
## Firmware Variants
|
||||
|
||||
This repo contains three firmware approaches for CSI data collection:
|
||||
|
||||
| Firmware | Directory | Output | Use Case |
|
||||
|----------|-----------|--------|----------|
|
||||
| **csi_recv_router** | `get-started/csi_recv_router/` | UDP to Pi | **Production** - deployed on 3 sensors |
|
||||
| **csi_recv** | `get-started/csi_recv/` | Serial console | Development/debugging |
|
||||
| **csi_send** | `get-started/csi_send/` | N/A (transmit only) | Paired with csi_recv |
|
||||
|
||||
## csi_recv_router (Deployed Firmware)
|
||||
|
||||
### How It Works
|
||||
|
||||
1. ESP32 connects to WiFi router as a station
|
||||
2. Pings the gateway at 100 Hz (10ms interval)
|
||||
3. Each ping response triggers a CSI callback
|
||||
4. CSI data is formatted as CSV and sent via UDP
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
Router ←── ping ──→ ESP32 ──── UDP ──→ Pi (192.168.129.11:5500)
|
||||
(100 Hz) (CSI_DATA)
|
||||
```
|
||||
|
||||
### CSI Data Format (ESP32)
|
||||
|
||||
```
|
||||
CSI_DATA,<seq>,<mac>,<rssi>,<rate>,<sig_mode>,<mcs>,<cwb>,<smoothing>,
|
||||
<not_sounding>,<aggregation>,<stbc>,<fec_coding>,<sgi>,<noise_floor>,
|
||||
<ampdu_cnt>,<channel>,<secondary_channel>,<timestamp>,<ant>,<sig_len>,
|
||||
<rx_state>,<len>,<first_word_invalid>,"[csi_values]"
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| seq | int | Packet sequence number (increments from 0) |
|
||||
| mac | MAC | Gateway MAC address |
|
||||
| rssi | int8 | Received signal strength (dBm) |
|
||||
| rate | uint8 | PHY rate |
|
||||
| sig_mode | uint8 | 0=non-HT, 1=HT, 3=VHT |
|
||||
| mcs | uint8 | Modulation and coding scheme |
|
||||
| cwb | uint8 | Channel bandwidth (0=20MHz, 1=40MHz) |
|
||||
| smoothing | uint8 | Channel estimate smoothing |
|
||||
| not_sounding | uint8 | Not sounding frame |
|
||||
| aggregation | uint8 | AMPDU aggregation |
|
||||
| stbc | uint8 | Space-time block coding |
|
||||
| fec_coding | uint8 | FEC coding (0=BCC, 1=LDPC) |
|
||||
| sgi | uint8 | Short guard interval |
|
||||
| noise_floor | int8 | Noise floor (dBm) |
|
||||
| ampdu_cnt | uint8 | AMPDU sub-frame count |
|
||||
| channel | uint8 | Primary channel number |
|
||||
| secondary_channel | uint8 | Secondary channel offset |
|
||||
| timestamp | uint32 | Local timestamp (microseconds) |
|
||||
| ant | uint8 | Antenna number |
|
||||
| sig_len | uint16 | Signal length |
|
||||
| rx_state | uint32 | RX state (0 = valid) |
|
||||
| len | int | CSI data length (bytes) |
|
||||
| first_word_invalid | bool | First 4 bytes invalid flag |
|
||||
| csi_values | int8[] | Raw CSI I/Q values (interleaved) |
|
||||
|
||||
### CSI Values Interpretation
|
||||
|
||||
The `csi_values` array contains interleaved I/Q pairs per subcarrier:
|
||||
|
||||
```
|
||||
[I0, Q0, I1, Q1, I2, Q2, ...]
|
||||
```
|
||||
|
||||
- Each pair represents one OFDM subcarrier
|
||||
- Amplitude: `sqrt(I^2 + Q^2)`
|
||||
- Phase: `atan2(Q, I)`
|
||||
- Typical length: 128 bytes (64 subcarriers x 2 values) for HT20
|
||||
|
||||
## csi_recv vs csi_recv_router Comparison
|
||||
|
||||
| Aspect | csi_recv | csi_recv_router |
|
||||
|--------|----------|-----------------|
|
||||
| **WiFi mode** | STA, no AP connection | STA, connects to router |
|
||||
| **CSI source** | ESP-NOW packets from csi_send | Ping responses from gateway |
|
||||
| **Output** | Serial (`ets_printf`) | UDP socket |
|
||||
| **Requires** | Paired csi_send device | WiFi router only |
|
||||
| **Promiscuous mode** | Yes | No |
|
||||
| **MAC filtering** | Fixed `1a:00:00:00:00:00` | Gateway BSSID |
|
||||
| **WiFi credentials** | Not needed | Required (menuconfig) |
|
||||
| **CSI config (ESP32)** | All LTF types enabled | LLTF only (router compat) |
|
||||
| **Gain compensation** | Logged to serial | Applied to UDP data |
|
||||
| **Sequence counter** | From ESP-NOW payload (`rx_id`) | Local counter (`s_count`) |
|
||||
| **Network** | Standalone (no router needed) | Depends on router |
|
||||
| **Deployment** | Lab/testing | Production |
|
||||
|
||||
### Key Differences in CSI Config (ESP32 target)
|
||||
|
||||
| Setting | csi_recv | csi_recv_router |
|
||||
|---------|----------|-----------------|
|
||||
| `lltf_en` | true | true |
|
||||
| `htltf_en` | **true** | **false** |
|
||||
| `stbc_htltf2_en` | **true** | **false** |
|
||||
| `manu_scale` | **false** | **true** |
|
||||
| `shift` | **false** | **true** |
|
||||
|
||||
The router firmware uses only LLTF for broader router compatibility. The ESP-NOW firmware enables all LTF types since it controls both endpoints.
|
||||
|
||||
## CSI Configuration Reference
|
||||
|
||||
### sdkconfig.defaults
|
||||
|
||||
#### WiFi Settings
|
||||
|
||||
| Config | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `CONFIG_ESP32_WIFI_CSI_ENABLED` | `y` | **Required.** Enables CSI extraction from received frames |
|
||||
| `CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED` | (empty) | Disables TX aggregation. Aggregated frames combine CSI, reducing quality |
|
||||
| `CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED` | (empty) | Disables RX aggregation (csi_recv_router only) |
|
||||
| `CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM` | `128` | Number of dynamic RX buffers. Higher = fewer drops at high CSI rates. Default is 32 |
|
||||
| `CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM` | `32` | Number of dynamic TX buffers |
|
||||
|
||||
#### Performance Settings
|
||||
|
||||
| Config | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` | `240` | Max CPU clock. Ensures CSI callback and UDP send complete within 10ms |
|
||||
| `CONFIG_COMPILER_OPTIMIZATION_PERF` | `y` | `-O2` optimization. Faster CSI processing |
|
||||
| `CONFIG_FREERTOS_HZ` | `1000` | 1ms tick resolution. Required for 100 Hz ping timer accuracy |
|
||||
|
||||
#### System Settings
|
||||
|
||||
| Config | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `CONFIG_ESP_TASK_WDT_TIMEOUT_S` | `30` | Watchdog timeout. Extended from default 5s to avoid false resets during WiFi reconnect |
|
||||
| `CONFIG_ESP_CONSOLE_UART_BAUDRATE` | `921600` | Fast serial for debug output |
|
||||
| `CONFIG_ESPTOOLPY_MONITOR_BAUD` | `921600` | Monitor baud rate (must match console) |
|
||||
|
||||
### Kconfig.projbuild (Custom Settings)
|
||||
|
||||
| Config | Default | Range | Description |
|
||||
|--------|---------|-------|-------------|
|
||||
| `CONFIG_CSI_UDP_TARGET_IP` | `192.168.129.11` | Any IPv4 | Destination IP for UDP CSI packets |
|
||||
| `CONFIG_CSI_UDP_TARGET_PORT` | `5500` | 1024-65535 | Destination UDP port |
|
||||
|
||||
### wifi_csi_config_t (Code-Level Settings)
|
||||
|
||||
#### ESP32 (Xtensa)
|
||||
|
||||
| Field | csi_recv_router | Description |
|
||||
|-------|----------------|-------------|
|
||||
| `lltf_en` | `true` | Enable Legacy Long Training Field. Most compatible with routers |
|
||||
| `htltf_en` | `false` | HT-LTF. Only in HT (802.11n) frames. Disabled for router compat |
|
||||
| `stbc_htltf2_en` | `false` | STBC HT-LTF2. Only with STBC encoding |
|
||||
| `ltf_merge_en` | `true` | Merge multiple LTF into one CSI report |
|
||||
| `channel_filter_en` | `true` | Apply channel estimation filter |
|
||||
| `manu_scale` | `true` | Manual amplitude scaling |
|
||||
| `shift` | `true` | Bit shift for value range |
|
||||
|
||||
### Compile-Time Defines (app_main.c)
|
||||
|
||||
| Define | Value | Description |
|
||||
|--------|-------|-------------|
|
||||
| `CONFIG_SEND_FREQUENCY` | `100` | Ping rate in Hz (10ms interval) |
|
||||
| `CONFIG_FORCE_GAIN` | `0` | Force AGC/FFT gain to baseline (disabled) |
|
||||
| `CONFIG_GAIN_CONTROL` | `1` (auto) | Enable gain compensation (ESP32-S3, C3, C5, C6, C61) |
|
||||
|
||||
## Receiving CSI Data on the Pi
|
||||
|
||||
Listen on UDP port 5500:
|
||||
|
||||
```bash
|
||||
# Quick test
|
||||
nc -lu 5500
|
||||
|
||||
# Save to file
|
||||
nc -lu 5500 > csi_capture.csv
|
||||
|
||||
# With socat (more reliable)
|
||||
socat UDP-RECV:5500 STDOUT
|
||||
```
|
||||
|
||||
## Python Visualization Tools
|
||||
|
||||
### get-started/tools/
|
||||
|
||||
```bash
|
||||
pip install -r get-started/tools/requirements.txt
|
||||
python get-started/tools/csi_data_read_parse.py
|
||||
```
|
||||
|
||||
Requires serial connection (not UDP). Use for development with `csi_recv` firmware.
|
||||
|
||||
### esp-radar/console_test/tools/
|
||||
|
||||
```bash
|
||||
pip install -r esp-radar/console_test/tools/requirements.txt
|
||||
python esp-radar/console_test/tools/esp_csi_tool.py
|
||||
python esp-radar/console_test/tools/esp_csi_tool_gui.py
|
||||
```
|
||||
|
||||
CLI and GUI tools for CSI analysis with presence detection algorithms.
|
||||
Reference in New Issue
Block a user