Getting Started: Common setup issues and solutions

[ruvnet]

Having trouble getting WiFi DensePose running? This thread covers the most common setup issues.

Quick Start

# Clone and run with Docker
git clone https://github.com/ruvnet/wifi-densepose.git
cd wifi-densepose
docker compose up

Then open http://localhost:3000 in your browser.

Common Issues

"RuntimeError: Cannot read /proc/net/wireless"

You're running on a system without a Linux wireless subsystem (Docker on Mac/Windows, WSL2, headless server). The server will automatically fall back to simulated data. For real sensing, connect ESP32 nodes via UDP port 5005. See issue #148 and ADR-049.

ESP32 not detected

• Ensure your ESP32 is flashed with the CSI firmware (see firmware/ directory)
• Check that UDP port 5005 is reachable from the server
• Verify TDM slot configuration: --tdm-slot 0 --tdm-total N

Visualization is jittery / skeletons jumping

This means you need calibration. See the Calibration Guide.

Docker issues

• Make sure Docker Desktop is running
• On Windows/macOS, ESP32 UDP traffic needs port forwarding into the container
• The server runs on simulated data by default in Docker (this is normal)

Reporting Issues

When opening a bug report, please include:

1. OS (Windows/macOS/Linux + version)
2. How you're running it (Docker, native Python, etc.)
3. Hardware (which ESP32 variant, how many)
4. Full error output (logs or screenshots)
5. Steps to reproduce