Known Issues & Setup Troubleshooting Guide

[ruvnet]

This issue collects the most common setup problems and their solutions. Check here before opening a new issue.

---

Quick Checks

Symptom	Likely Cause	Fix
UI shows same skeleton regardless of people	You're in simulation mode	Check curl http://localhost:3000/health — if "source":"simulated", see Simulation vs Live below
Server says "No hardware detected"	ESP32 not sending UDP to your computer	Check --target-ip, firewall, WiFi connection (see No Data Arriving)
Only 1 node detected despite multiple ESP32s	Node IDs not persisted	Flash v0.5.0-esp32, re-provision each node separately
"Always 2 persons" when only 1 present	Multipath ghosting	Use 3+ nodes, update to latest server (PR #295 hysteresis fix)
Skeletons shaking / jittery	No trained model + count instability	PR #295 hysteresis fix + record calibration data
Watchdog crash CPU 1: edge_dsp	Firmware DSP task not yielding	Flash v0.4.3-esp32 or later
Training endpoint returns instantly	No recorded data to train on	Record labeled data first (see Training below)
Fall detected! flooding logs	Threshold too low in old firmware	Flash v0.4.3+ (threshold raised from 2.0 to 15.0)

---

Simulation vs Live Mode

How to tell which mode you're in:

curl http://localhost:3000/health

• "source":"simulated" → You're seeing synthetic data. The UI will not respond to real room conditions.
• "source":"esp32" → You're receiving real CSI data from hardware.

To switch to live mode:

1. Flash ESP32-S3 with v0.5.0-esp32 firmware
2. Provision with your computer's real LAN IP (not 0.0.0.0):

   # Find your IP: ifconfig (macOS) / ipconfig (Windows) / hostname -I (Linux)
   python firmware/esp32-csi-node/provision.py --port YOUR_PORT \
     --ssid "YourWiFi" --password "YourPassword" --target-ip YOUR_COMPUTER_IP

3. Start server with --source esp32 or -e CSI_SOURCE=esp32 (Docker)
4. Verify: curl http://localhost:3000/health should show "source":"esp32"

---

No Data Arriving (ESP32 → Server)

Diagnostic steps:

# 1. Check ESP32 serial output
python -m serial.tools.miniterm YOUR_PORT 115200
# Look for: "Got IP: 192.168.x.x" and "CSI cb #N" messages

# 2. Check if UDP packets reach your computer
# macOS/Linux:
sudo tcpdump -i any udp port 5005 -c 5
# Windows (PowerShell as Admin):
netstat -an | findstr "5005"

# 3. If no packets → re-provision with correct target IP
# 4. If packets arrive but server says "no hardware" → check firewall

Firewall rules (UDP 5005 must be open inbound):

• macOS: System Preferences → Security → Firewall → allow sensing-server
• Windows: Windows Defender Firewall → allow UDP 5005 inbound
• Linux: sudo ufw allow 5005/udp

---

Multi-Node Setup

Each node must be provisioned one at a time with unique IDs:

# Node 0
python provision.py --port COM7 --ssid "WiFi" --password "pass" \
  --target-ip 192.168.1.20 --node-id 0 --tdm-slot 0 --tdm-total 3

# Unplug, plug next ESP32
# Node 1
python provision.py --port COM7 --ssid "WiFi" --password "pass" \
  --target-ip 192.168.1.20 --node-id 1 --tdm-slot 1 --tdm-total 3

# Node 2
python provision.py --port COM7 --ssid "WiFi" --password "pass" \
  --target-ip 192.168.1.20 --node-id 2 --tdm-slot 2 --tdm-total 3

Important: --node-id 0,1,2 (comma-separated) does NOT work. Each node must be provisioned individually.

---

Training the Adaptive Classifier

The training endpoint returns instantly if no data has been recorded:

# Record ~60s of empty room
curl -X POST "http://localhost:3000/api/v1/record/start?label=empty"
# wait 60s
curl -X POST "http://localhost:3000/api/v1/record/stop"

# Record ~60s with 1 person
curl -X POST "http://localhost:3000/api/v1/record/start?label=1person"
# wait 60s
curl -X POST "http://localhost:3000/api/v1/record/stop"

# Now train
curl -X POST "http://localhost:3000/api/v1/adaptive/train"

---

What WiFi CSI Can and Cannot Do

Works today (no ML model needed): Presence detection, motion classification, person count (1-3), breathing rate, basic heart rate, fall detection.

Requires a trained model: Full skeleton/pose estimation, multi-person pose tracking, cross-room transfer.

The 3D skeleton shown in the UI without a model is driven by signal heuristics — it demonstrates the pipeline is working but is not a true pose reconstruction.

---

Useful Links

• User Guide — Full setup walkthrough
• Releases — Pre-built firmware binaries
• Tutorial #34 — End-to-end ESP32-S3 CSI pipeline setup
• Node Placement Guide — Where to position your ESP32s

---

Related Issues

• fix(sensing-server): person count hysteresis to stop flickering #295 — Person count hysteresis fix
• fix(sensing-server): detect ESP32 offline after 5s timeout #300 — ESP32 offline detection (5s timeout)
• Detection Fail #282 — Multi-node detection improvements
• Help Ruvnet! Detection Window showing the same thing regardless of position and people in room. #249 — UI showing same output regardless of position
• Only one can be detected #276 — Single node detection with multiple devices

[lepotatoclaw]

Incredible project! Using WiFi CSI for pose estimation without any camera is such a clever approach. The privacy-preserving aspect alone makes this revolutionary - no video, no biometrics, just RF signals. The troubleshooting guide is super helpful too! 🔥