fix(docker): UDP relay for multi-source ESP32 on Docker Desktop Windows

[ruvnet]

Summary

• Adds scripts/udp-relay.py — a stdlib-only host-side UDP relay that collapses multi-source ESP32 datagrams onto a single loopback source so Docker Desktop on Windows forwards every packet (root cause of Docker Desktop drops UDP from multiple ESP32 sources #374 / Live UI connects, packets flow, but pose does not move correctly with 6 ESP32-S3 nodes on Windows #386).
• Updates docker/docker-compose.yml with an inline comment pointing Windows users at the relay + 5006:5005/udp mapping. Linux/macOS hosts are unaffected.
• Adds three new entries to docs/TROUBLESHOOTING.md: §9 Docker Desktop Windows UDP (Docker Desktop drops UDP from multiple ESP32 sources #374, Live UI connects, packets flow, but pose does not move correctly with 6 ESP32-S3 nodes on Windows #386), §10 sensing-server /ui 404 (Unable to access visualization page via browser #188), §11 --edge-tier 1/2 boot loop (boot loop #438).

Why a relay and not a docs-only fix

Docker Desktop on Windows runs the engine inside a WSL2/Hyper-V VM. Inbound UDP from multiple source IPs is demultiplexed onto a single virtual socket — the first source "wins" and subsequent unique sources are silently dropped at the VM boundary. Neither host.docker.internal nor --network host resolves this (host networking is not available on the Linux engine on Windows). The relay is the only end-user-runnable fix until Docker Desktop ships per-source UDP forwarding (docker/for-win#1144).

PR #413 by @txhno proposed a docs-only writeup of the same workaround but was conflicting and didn't ship the actual relay tool. This PR supersedes it; happy to credit and close #413 once merged.

Validation

Multi-source relay test on Windows host (this branch):

$ python scripts/udp-relay.py --listen-port 25005 --forward-port 25006 --verbose
udp-relay: listening on 0.0.0.0:25005 -> forwarding to 127.0.0.1:25006

# Send from three distinct ephemeral ports (40001, 40002, 40003)
# Receiver on 25006 sees:
received=6 packets
  from ('127.0.0.1', 54134) -> b'pkt-A-from-40001'
  from ('127.0.0.1', 54134) -> b'pkt-B-from-40001'
  from ('127.0.0.1', 54134) -> b'pkt-A-from-40002'
  from ('127.0.0.1', 54134) -> b'pkt-B-from-40002'
  from ('127.0.0.1', 54134) -> b'pkt-A-from-40003'
  from ('127.0.0.1', 54134) -> b'pkt-B-from-40003'
PASS

All 6 packets from 3 distinct source ports arrive at the receiver, all from the relay's single ephemeral socket — exactly the shape Docker Desktop forwards without dropping.

Test plan

• Reviewer with a Windows + Docker Desktop host: edit docker/docker-compose.yml to map 5006:5005/udp, run python scripts/udp-relay.py, point ≥2 ESP32-S3 nodes at the host on port 5005, confirm /api/v1/sensing/latest returns frames from every node.
• Linux/macOS reviewer: confirm the unchanged default 5005:5005/udp mapping still works without the relay.
• Docs render check: §9–§11 of docs/TROUBLESHOOTING.md look right on github.com.

Closes

• Closes Docker Desktop drops UDP from multiple ESP32 sources #374 (Docker Desktop drops UDP from multiple ESP32 sources)
• Closes Live UI connects, packets flow, but pose does not move correctly with 6 ESP32-S3 nodes on Windows #386 (Live UI connects, packets flow, but pose does not move correctly with 6 nodes on Windows — duplicate root cause)

Refs

• Unable to access visualization page via browser #188 (visualization 404) — workaround documented; future code-side fix tracked there
• boot loop #438 (boot loop on --edge-tier 1/2) — workaround documented; resolved by upgrading to v0.4.3.1-esp32+
• Known Issues & Setup Troubleshooting Guide #301 (Known Issues guide) — three new entries land directly in docs/TROUBLESHOOTING.md
• docs: clarify Windows Docker Desktop UDP troubleshooting #413 (@txhno's docs-only attempt) — superseded; can close when this lands

🤖 Generated with claude-flow