depz-sensor-viewer

A local, standalone launcher for the DEPZ sensor web viewer. It runs a tiny localhost web server that serves the viewer SPA and talks to your DEPZ sensors over pyserial — so the UI never touches the browser WebSerial API.

Why

The hosted viewer uses the browser's WebSerial API, which means:

• a port-picker prompt every time you connect,
• Chrome-only support, and
• failures under some enterprise / managed-Chrome policies that disable WebSerial entirely.

This launcher sidesteps all of that. The Python process opens the serial port locally with pyserial and pipes raw bytes to the SPA over a WebSocket. No prompt, no WebSerial, works in any browser pointed at localhost.

Install & run

pipx install depz-sensor-viewer
depz-sensor-viewer

This starts the server on http://127.0.0.1:8765 (or a random free port if 8765 is taken) and opens your browser. Options:

depz-sensor-viewer --port 9000       # pick a port (0 = random free)
depz-sensor-viewer --host 127.0.0.1  # bind address (localhost by default)
depz-sensor-viewer --no-browser      # just start the server
depz-sensor-viewer --keep-alive      # don't stop the server when the viewer window closes

Press Ctrl-C to stop.

Linux: serial permissions

On Linux, opening /dev/ttyACM* requires membership in the dialout group. If devices don't open, add yourself and re-login:

sudo usermod -aG dialout $USER
# then log out and back in (or: newgrp dialout)

The viewer diagnoses this for you at GET /api/permissions and shows the fix in the UI.

HTTP / WebSocket contract

The bundled SPA detects standalone mode and drives devices through this fixed interface (served by depz_sensor_viewer.server):

Recordings live on disk like the camera viewer's: <repo>/recordings/ in a dev checkout, else <Documents>/DEPZ/recordings/ (--recordings-dir overrides). In standalone mode the SPA's Record button saves there and the Player button lists the directory inline; the hosted (WebSerial) viewer keeps standard browser downloads and the file picker.

/api/devices enumerates only ports whose USB identity is a known DEPZ device (via the SDK's USB table); it does not open the ports. baud defaults to 115200 and is nominal for the CDC-ACM devices.

/ws/serial framing:

• client → server binary frame → serial.write(bytes)
• server → client binary frame ← bytes read from the serial port
• text frames carry JSON control/status:
  • server: {"opened": true, "path": ..., "baud": ...} right after open
  • server: {"error": "...", "code": "...", "fix": {...}} on failure (permission errors include the per-OS fix)
  • client: {"cmd": "set_baud", "baud": <int>} (optional)

The port is closed when the WebSocket closes.

Building the bundled SPA

The wheel ships the built SPA under depz_sensor_viewer/_static/. To (re)build it from the repo's TypeScript viewer:

python packages/depz-sensor-viewer/scripts/bundle_spa.py

This runs bun run build:spa at the repo root and copies dist-spa/client/** into _static/, materialising index.html from the prerendered SPA shell. Pass --skip-build to copy an existing dist-spa/client/ without rebuilding. Until you run it, / serves a plaintext placeholder that points here — the API endpoints above are live regardless.

The SPA build (vite.config.spa.ts) is deliberately not the default bun run build: that one targets Cloudflare and emits an SSR worker (dist/server/server.js + dist/client/) with no index.html, which the plain-file launcher cannot serve. The SSR dist/ build is left untouched, so the Cloudflare deploy keeps working.

License

MIT