Skip to content

docs: fix ESP32 Docker command and add WSL2/dual-USB-C notes #492

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
SiamRahman29 wants to merge 1 commit into from
+13 −2
Closed

docs: fix ESP32 Docker command and add WSL2/dual-USB-C notes #492

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ Real Channel State Information at 20 Hz with 56-192 subcarriers. Required for po
# From source
./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

# Docker (use CSI_SOURCE environment variable)
# Docker (pre-built image uses CSI_SOURCE env var, not a CLI flag)
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest
```

Expand Down Expand Up @@ -1014,6 +1014,8 @@ Pre-built binaries are available at [Releases](https://github.com/ruvnet/RuView/

> **Important:** Always use **v0.4.3.1 or later**. Earlier versions have false fall detection alerts (v0.4.2 and below) and CSI disabled in the build config (pre-v0.4.1).

> **Note:** If your board has two USB-C ports, use the **UART port** (not the OTG port) for flashing and serial monitoring. Using the wrong port results in `No serial data received`.

```bash
# Flash an ESP32-S3 with 8MB flash (most boards)
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
Expand Down Expand Up @@ -1105,11 +1107,13 @@ Binary size: 990 KB (8MB flash, 52% free) or 773 KB (4MB flash). v0.5.0 adds mmW

**Start the aggregator:**

> **WSL2 users:** WSL2's default NAT networking does not receive UDP packets sent to the Windows host IP. Enable mirrored networking so WSL shares the host network stack: add `networkingMode=mirrored` under `[wsl2]` in `%USERPROFILE%\.wslconfig`, then run `wsl --shutdown` and reopen WSL. Requires Windows 11 22H2+.

```bash
# From source
./target/release/sensing-server --source esp32 --udp-port 5005 --http-port 3000 --ws-port 3001

# Docker (use CSI_SOURCE environment variable)
# Docker (pre-built image uses CSI_SOURCE env var, not a CLI flag)
docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest
```

Expand Down Expand Up @@ -1691,6 +1695,7 @@ Firmware versions prior to v0.4.1 had `CONFIG_ESP_WIFI_CSI_ENABLED` disabled in
3. Check the target IP matches the sensing server machine: `python firmware/esp32-csi-node/provision.py --port COM7 --target-ip <YOUR_IP>`
4. Verify UDP port 5005 is not blocked by firewall
5. Test with: `nc -lu 5005` (Linux) or similar UDP listener
6. **WSL2:** UDP to the Windows host IP does not reach WSL by default. Enable mirrored networking (see [ESP32-S3 Mesh](#esp32-s3-mesh) setup notes above).

### Build: Rust compilation errors

Expand Down
6 changes: 6 additions & 0 deletions firmware/esp32-csi-node/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ MSYS_NO_PATHCONV=1 docker run --rm \

### 2. Flash

Find your serial port (`COM7` on Windows, `/dev/ttyACM0` on Linux/WSL):

> **Dual USB-C boards:** Use the **UART port**, not the OTG port. Using the wrong port results in `No serial data received` during flashing.

```bash
python -m esptool --chip esp32s3 --port COM7 --baud 460800 \
write_flash --flash_mode dio --flash_size 8MB \
Expand All @@ -47,6 +51,8 @@ python -m esptool --chip esp32s3 --port COM7 --baud 460800 \

### 3. Provision WiFi credentials (no reflash needed)

> **WSL2 users:** WSL2's NAT networking does not receive UDP packets sent to the Windows host IP. Enable mirrored networking first: add `networkingMode=mirrored` under `[wsl2]` in `%USERPROFILE%\.wslconfig`, run `wsl --shutdown`, then reopen WSL. Requires Windows 11 22H2+.

```bash
python scripts/provision.py --port COM7 \
--ssid "YourSSID" --password "YourPass" --target-ip 192.168.1.20
Expand Down