Skip to content

docs: troubleshooting guide for ESP32 CSI deployments#377

Open
schwarztim wants to merge 1 commit intoruvnet:mainfrom
schwarztim:docs/troubleshooting-guide
Open

docs: troubleshooting guide for ESP32 CSI deployments#377
schwarztim wants to merge 1 commit intoruvnet:mainfrom
schwarztim:docs/troubleshooting-guide

Conversation

@schwarztim
Copy link
Copy Markdown

Adds docs/TROUBLESHOOTING.md covering 8 common issues encountered during multi-node ESP32-S3 WiFi CSI deployments:

  1. Node not appearing — limping state after USB flash, watchdog recovery
  2. Person count stuck at 1 — ADR-044 root causes and fixes
  3. Vitals jitter — last-write-wins from multiple nodes, best-node selection
  4. Signal quality placeholder — was hardcoded, now uses adaptive p95
  5. Dashboard freezing — WebSocket disconnect loop (see PR fix(websocket): handle broadcast Lagged error + ping keepalive #376)
  6. OTA crash at 59% — BLE/OTA Core 1 conflict
  7. SSH LAN hang — Tailscale workaround
  8. USB-C port selection — left port for UART bridge

Helps users hitting #268, #375, #366.

Covers 8 known issues encountered during multi-node ESP32-S3 deployments:
1. Node not appearing (limping state after USB flash)
2. Person count stuck at 1 (ADR-044)
3. Heart rate/breathing rate jitter (last-write-wins from multiple nodes)
4. Signal quality placeholder
5. Dashboard freezing (WS disconnect loop)
6. OTA crash at 59% (BLE vs OTA conflict)
7. SSH LAN hang (Tailscale workaround)
8. USB-C port selection

Helps with ruvnet#268 (no nodes found), ruvnet#375 (node_id), ruvnet#366 (build errors).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant