Add WebSocket relay with token & UI

Introduce a downlink-only WebSocket relay feature and status UI controls. Changes include:

- README: document new relay-related env vars and Cloudflare Tunnel usage for exposing wss://.
- deploy/.env.macbook: add placeholder RELAY_TOKEN and cloudflared config paths.
- docker-compose.macbook-base.yml: expose port 9089, enable relay envs, and add a cloudflared service to publish the relay via a tunnel.
- src/ws_relay.py: make the relay read a live token (from /app/relay_token or env), require tokens per LAN policy, and apply the live token to auth checks.
- src/status_server.py: add /relay-info GET and /relay-token POST endpoints; persist token to /app/relay_token so UI changes take effect immediately.
- status/index.html: add relay card to status UI (port, token input, copy/save), replace the old packet-rate / seq-tape visuals with a 60s health mosaic, and wire UI to new endpoints (load/save token).
- src/data.py: adjust status_map pruning range and status_buffer slice to cover the larger window used by the UI mosaic.

These changes enable remote viewers to connect to a base-station WebSocket (port 9089) with an optional token, and document a recommended secure exposure path via Cloudflare Tunnel. UI changes allow operators to view and update the token without restarting services.

Author: haoruizhou

universal-telemetry-software/README.md

@@ -202,6 +202,11 @@ Images are built for both `linux/amd64` and `linux/arm64` (Raspberry Pi).
 | `ENABLE_VIDEO` | `false` | Enable video streaming (car: push RTSP; base: unused) |
 | `ENABLE_AUDIO` | `false` | Enable audio streaming |
 | `ENABLE_TIMESCALE_LOGGING` | `false` | Log telemetry to server TimescaleDB (direct write) |
+| `ENABLE_WS_RELAY` | `false` | Enable downlink-only WebSocket relay for remote viewers |
+| `RELAY_TOKEN` | unset | Optional passcode for relay connections (`?token=...`) |
+| `RELAY_LISTEN_PORT` | `9089` | Local port for the relay WebSocket server |
+| `RELAY_UPSTREAM_WS` | `ws://127.0.0.1:9080` | Upstream base-station WebSocket consumed by the relay |
+| `RELAY_REQUIRE_TOKEN_ON_LAN` | `false` | Require token for LAN clients too, not just loopback/public clients |
 | `RTSP_PORT` | `8554` | Port on base station where MediaMTX accepts RTSP push |
 | `VIDEO_STREAM_NAME` | `car-camera` | RTSP/WebRTC stream path name |
 | `VIDEO_WIDTH` | `848` | Capture width (overridden by quality preset) |
@@ -219,6 +224,7 @@ Images are built for both `linux/amd64` and `linux/arm64` (Raspberry Pi).
 | 6379 | TCP | Redis (internal) |
 | 8080 | HTTP | Status monitoring page |
 | 9080 | WebSocket | PECAN dashboard feed |
+| 9089 | WebSocket | Downlink-only relay for remote viewers |
 | 3000 | HTTP | PECAN dashboard UI |
 | 8081 | HTTP | Video quality control (car only, when ENABLE_VIDEO=true) |
 | 8554 | TCP | RTSP — car pushes H.264 to MediaMTX on base |
@@ -283,6 +289,80 @@ v4l2-ctl --device /dev/video0 --set-ctrl focus_absolute=40
 
 ---
 
+## Remote Viewing via WebSocket Relay
+
+The base station can publish the live telemetry WebSocket through a downlink-only relay on port `9089`. The relay connects upstream to the normal local WebSocket (`9080`) and rebroadcasts frames to viewers; downstream messages are not forwarded back to the car or base station.
+
+### Enable the relay
+
+For the MacBook base stack this is already enabled in `deploy/docker-compose.macbook-base.yml`:
+
+```yaml
+ENABLE_WS_RELAY=true
+RELAY_UPSTREAM_WS=ws://127.0.0.1:9080
+RELAY_LISTEN_PORT=9089
+RELAY_TOKEN=<optional passcode>
+```
+
+You can set or change the token from the status page at `http://localhost:8080`. Tokens saved from the UI take effect for new relay connections immediately.
+
+Local viewers can connect to:
+
+```text
+ws://<base-station-ip>:9089?token=<token>
+```
+
+### Forward with Cloudflare Tunnel
+
+Cloudflare Tunnel is the recommended way to expose the relay as secure `wss://` without opening inbound firewall ports.
+
+Install and log in:
+
+```bash
+brew install cloudflared
+cloudflared tunnel login
+```
+
+Create a tunnel:
+
+```bash
+cloudflared tunnel create daq-ws-relay
+```
+
+Create `~/.cloudflared/config.yml`:
+
+```yaml
+tunnel: <tunnel-id-or-name>
+credentials-file: /Users/<you>/.cloudflared/<tunnel-id>.json
+
+ingress:
+  - hostname: daq-relay.example.com
+    service: http://localhost:9089
+  - service: http_status:404
+```
+
+Route DNS:
+
+```bash
+cloudflared tunnel route dns daq-ws-relay daq-relay.example.com
+```
+
+Run the tunnel while the base station stack is up:
+
+```bash
+cloudflared tunnel run daq-ws-relay
+```
+
+Remote viewers connect with:
+
+```text
+wss://daq-relay.example.com?token=<token>
+```
+
+This same relay can be published by any reverse tunnel provider; Cloudflare is only the documented default.
+
+---
+
 ## Redis Channels
 
 ### `can_messages`

universal-telemetry-software/deploy/.env.macbook

@@ -1,7 +1,11 @@
-# MacBook base station env
+# MacBook base station env template
 # Usage: docker compose -f deploy/docker-compose.macbook-base.yml --env-file deploy/.env.macbook up -d
+# Put real team credentials/paths in a private env file and pass that with --env-file.
 
 REMOTE_IP=10.71.1.10
 TIMESCALE_TABLE=WFR26test
 DBC_HOST_PATH=./example.dbc
 GRAFANA_ADMIN_PASSWORD=admin
+RELAY_TOKEN=
+CLOUDFLARED_CONFIG=./cloudflared/config.yml
+CLOUDFLARED_CREDENTIALS=./cloudflared/credentials.json

universal-telemetry-software/deploy/docker-compose.macbook-base.yml

@@ -20,6 +20,7 @@ services:
     restart: unless-stopped
     ports:
       - "9080:9080"   # WebSocket (Pecan connects here)
+      - "9089:9089"   # WS relay (external access via Cloudflare tunnel)
       - "8080:8080"   # Status page
       - "5005:5005/udp"
       - "5006:5006/tcp"
@@ -39,6 +40,10 @@ services:
       - POSTGRES_DSN=postgresql://wfr:wfr_password@timescaledb:5432/wfr
       - TIMESCALE_TABLE=${TIMESCALE_TABLE:-WFR26test}_base
       - DBC_FILE_PATH=/app/active.dbc
+      - ENABLE_WS_RELAY=true
+      - RELAY_TOKEN=${RELAY_TOKEN:-}
+      - RELAY_REQUIRE_TOKEN_ON_LAN=true
+      - RELAY_UPSTREAM_WS=ws://127.0.0.1:9080
     volumes:
       - ${DBC_HOST_PATH:-./example.dbc}:/app/active.dbc:ro
       - raw_can_data:/app/raw_can_logs
@@ -75,6 +80,19 @@ services:
     networks:
       - datalink
 
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    container_name: daq-cloudflared
+    restart: unless-stopped
+    command: tunnel --config /etc/cloudflared/config.yml run daq-ws-relay
+    volumes:
+      - ${CLOUDFLARED_CONFIG:-./cloudflared/config.yml}:/etc/cloudflared/config.yml:ro
+      - ${CLOUDFLARED_CREDENTIALS:-./cloudflared/credentials.json}:/etc/cloudflared/credentials.json:ro
+    depends_on:
+      - telemetry
+    networks:
+      - datalink
+
   mediamtx:
     image: bluenviron/mediamtx:latest
     container_name: daq-mediamtx

universal-telemetry-software/src/data.py

@@ -485,7 +485,7 @@ async def udp_receiver():
                     self.latest_seq = seq
                     # Prune status map to last 3000 sequences
                     if len(self.status_map) > 3000:
-                        min_seq = self.latest_seq - 2000
+                        min_seq = self.latest_seq - 2999
                         self.status_map = {s: v for s, v in self.status_map.items() if s >= min_seq}
                 elif seq in self.status_map and self.status_map[seq] == 0:
                     self.status_map[seq] = 1 # Out-of-order UDP arrival
@@ -641,7 +641,7 @@ async def stats_publisher():
                     "base_clock_bad": self._base_clock_bad,
                     "last_udp_time": self.last_udp_time,
                     "car_alive": (time.time() - self.last_udp_time) < 5 if self.last_udp_time else False,
-                    "status_buffer": [self.status_map.get(s, 0) for s in range(max(0, self.latest_seq - 1000), self.latest_seq + 1)] if self.latest_seq != -1 else [],
+                    "status_buffer": [self.status_map.get(s, 0) for s in range(max(0, self.latest_seq - 2999), self.latest_seq + 1)] if self.latest_seq != -1 else [],
                     "own_git_hash": self._own_git_hash,
                     "car_git_hash": self._car_git_hash,
                     "remote_ip": os.getenv("REMOTE_IP", "unknown"),

universal-telemetry-software/src/status_server.py

@@ -19,6 +19,16 @@
 logger = logging.getLogger("StatusServer")
 
 PORT = int(os.getenv("STATUS_PORT", 8080))
+TOKEN_FILE = "/app/relay_token"
+
+
+def _read_relay_token() -> str:
+    try:
+        with open(TOKEN_FILE) as f:
+            return f.read().strip()
+    except FileNotFoundError:
+        pass
+    return os.getenv("RELAY_TOKEN", "")
 DIRECTORY = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + "/status"
 # SET_TIME_ENABLED must be explicitly set to "true" to allow the /set-time endpoint.
 # This prevents unauthenticated callers from modifying the host clock.
@@ -40,6 +50,14 @@ def end_headers(self):
     def log_message(self, format, *args):
         logger.info("%s - - [%s] %s" % (self.address_string(), self.log_date_time_string(), format % args))
 
+    def do_GET(self):
+        if self.path == '/relay-info':
+            token = _read_relay_token()
+            port = int(os.getenv("RELAY_LISTEN_PORT", "9089"))
+            self._json_response(200, {"token": token, "port": port, "enabled": True})
+            return
+        super().do_GET()
+
     def do_OPTIONS(self):
         self.send_response(200)
         self.send_header('Access-Control-Allow-Origin', '*')
@@ -48,6 +66,9 @@ def do_OPTIONS(self):
         self.end_headers()
 
     def do_POST(self):
+        if self.path == '/relay-token':
+            self._handle_relay_token()
+            return
         if self.path == '/set-time':
             if not SET_TIME_ENABLED:
                 self._json_response(403, {"error": "set-time is disabled (set SET_TIME_ENABLED=true)"})
@@ -85,6 +106,19 @@ def _handle_set_time(self):
             logger.error(f"/set-time error: {e}")
             self._json_response(500, {"error": str(e)})
 
+    def _handle_relay_token(self):
+        try:
+            length = int(self.headers.get('Content-Length', 0))
+            body = json.loads(self.rfile.read(length))
+            token = body.get('token', '').strip()
+            with open(TOKEN_FILE, 'w') as f:
+                f.write(token)
+            logger.info("Relay token updated via UI")
+            self._json_response(200, {"ok": True, "token": token})
+        except Exception as e:
+            logger.error(f"/relay-token error: {e}")
+            self._json_response(500, {"error": str(e)})
+
     def _json_response(self, code: int, payload: dict):
         body = json.dumps(payload).encode()
         self.send_response(code)

universal-telemetry-software/src/ws_relay.py

@@ -39,12 +39,24 @@ def _env_bool(name: str, default: str = "false") -> bool:
     return os.getenv(name, default).lower() == "true"
 
 
+TOKEN_FILE = "/app/relay_token"
+
+
+def _get_live_token() -> str | None:
+    try:
+        with open(TOKEN_FILE) as f:
+            val = f.read().strip()
+            return val or None
+    except FileNotFoundError:
+        pass
+    return os.getenv("RELAY_TOKEN") or None
+
+
 def _config() -> dict:
     return {
         "upstream": os.getenv("RELAY_UPSTREAM_WS", "ws://127.0.0.1:9080"),
         "listen_host": os.getenv("RELAY_LISTEN_HOST", "0.0.0.0"),
         "listen_port": int(os.getenv("RELAY_LISTEN_PORT", "9089")),
-        "token": os.getenv("RELAY_TOKEN") or None,
         "require_token_on_lan": _env_bool("RELAY_REQUIRE_TOKEN_ON_LAN", "false"),
         "reconnect_min": float(os.getenv("RELAY_UPSTREAM_RECONNECT_MIN", "1")),
         "reconnect_max": float(os.getenv("RELAY_UPSTREAM_RECONNECT_MAX", "30")),
@@ -98,11 +110,10 @@ def _reject_401() -> Response:
     return Response(401, "Unauthorized", Headers(), b"missing or invalid token\n")
 
 
-def _make_process_request(relay_token: str | None, require_on_lan: bool):
+def _make_process_request(get_token, require_on_lan: bool):
     async def process_request(connection: ServerConnection, request) -> Response | None:
-        host = ""
-        if connection.remote_address:
-            host = connection.remote_address[0]
+        host = connection.remote_address[0] if connection.remote_address else ""
+        relay_token = get_token()
         if not token_required_for_peer(host, relay_token, require_on_lan):
             return None
         provided = _token_from_request_path(request.path)
@@ -119,7 +130,6 @@ async def run_ws_relay(heartbeat_event=None) -> None:
     upstream_uri = cfg["upstream"]
     host = cfg["listen_host"]
     port = cfg["listen_port"]
-    relay_token = cfg["token"]
     require_on_lan = cfg["require_token_on_lan"]
     backoff_min = cfg["reconnect_min"]
     backoff_max = cfg["reconnect_max"]
@@ -129,7 +139,7 @@ async def run_ws_relay(heartbeat_event=None) -> None:
     utils.register_shutdown_signals(loop, shutdown_event, "WS relay")
 
     connected_clients: set = set()
-    process_request = _make_process_request(relay_token, require_on_lan)
+    process_request = _make_process_request(_get_live_token, require_on_lan)
 
     async def downstream_handler(connection: ServerConnection) -> None:
         peer = connection.remote_address
@@ -203,7 +213,7 @@ async def upstream_loop() -> None:
         host,
         port,
         upstream_uri,
-        "set" if relay_token else "off",
+        "set" if _get_live_token() else "off",
         require_on_lan,
     )