Spaces:

secutorpro
/

dispatch-console

Paused

App Files Files Community

secutorpro commited on Sep 18

Commit

6cb1a1b

verified ·

1 Parent(s): cd25c51

README: overview, quickstart, protocol, limitations

Browse files

Files changed (1) hide show

README.md +63 -71

README.md CHANGED Viewed

@@ -1,97 +1,89 @@
 ---
 title: Dispatch Console
 emoji: 🗺️
 sdk: docker
 app_port: 8080
 pinned: false
 ---
-# Dispatch Console (PoC-style, self-hosted)
-A production-ready, self-hosted alternative to hosted PoC dispatch consoles:
-live member map, GPS tracking, SOS alert workflow, push-to-talk intercom with
-server-enforced floor control, and member/talkgroup management.
-## Stack
-- **Backend** — Node.js, Express (REST API), `ws` (WebSocket: GPS, SOS, PTT signaling, audio relay), SQLite (`better-sqlite3`), JWT auth
-- **Frontend** — React 18 + Vite, Leaflet (OpenStreetMap), AudioWorklet capture / WebAudio playback
-- **Deploy** — Docker / docker-compose; also runnable directly and on HF Spaces (this repo)
-## Quickstart (local, no Docker)
-```bash
-# 1. backend
-cd server
-npm install
-npm start                     # listens on :8080
-# 2. frontend (dev server with proxy)
-cd ../web
-npm install
-npm run dev                   # http://localhost:5173
-# 3. simulated fleet (separate terminal)
-cd ../server
-npm run sim                   # 5 units: GPS every 5 s, SOS at 25 s, PTT turns
 ```
-Default dispatcher: **admin / admin** (override with `ADMIN_PASSWORD` on first run; change it after first login).
 ## Quickstart (Docker)
 ```bash
-docker compose up --build -d  # http://localhost:8080
 ```
-Data (SQLite + JWT secret) persists in `./data`.
-## Architecture
 ```
-web (React+Vite)  ──HTTP /api/*──>  Express  ──>  SQLite (better-sqlite3)
-       |                                |
-       +--WebSocket /ws (JSON + PCM) --> Hub (realtime.js)
-                                          |- GPS ingestion -> members + gps_pings
-                                          |- SOS alerts -> broadcast + REST ack/resolve
-                                          +- PTT floor control + 16 kHz PCM audio relay
 ```
-Devices (radios/phones) connect as WebSocket **device** clients
-(`{type:"auth", token, memberId}`); dispatch consoles connect as plain
-authenticated clients and see everything. Binary WebSocket frames carry audio:
-`[1 byte type=0x01][4 bytes groupId BE][4 bytes memberId BE][16 kHz mono Int16 LE PCM]`.
-Only the current floor holder may transmit; the server enforces one speaker per
-talkgroup and relays frames to everyone subscribed to that group.
-## REST API (JWT Bearer)
-| Method | Path | Purpose |
-|---|---|---|
-| POST | `/api/login` | get token |
-| GET | `/api/me` | current user |
-| GET/POST | `/api/groups` | talkgroups |
-| GET/POST | `/api/members` | list / create members |
-| PUT/DELETE | `/api/members/:id` | edit / delete |
-| GET | `/api/members/:id/trail` | GPS history |
-| GET | `/api/sos` | alert list (`?state=open`) |
-| POST | `/api/sos/:id/ack` / `/api/sos/:id/resolve` | SOS workflow |
-| GET | `/api/calls` | call log |
-## Limitations (v1, honest)
-- Audio is relayed 16 kHz PCM over WebSocket — fine for small fleets; move to
-  Opus + a media server (LiveKit/Janus) for scale and better quality.
-- Devices authenticate with any valid dispatcher token + memberId; per-device
-  credentials are the first thing to add before real deployment.
-- Single-node, single SQLite file; no clustering.
-- The fleet simulator needs a real browser (or device client) to produce audio;
-  it exercises GPS, SOS and floor events only.
-## Files
-- `server/src/realtime.js` — WebSocket hub: auth, GPS, SOS, PTT floor, audio relay
-- `server/src/routes.js` — REST CRUD + SOS workflow
-- `server/simulator.js` — simulated fleet for testing
-- `web/src/App.jsx` — state + realtime wiring
-- `web/src/audio.js` — AudioWorklet capture / playback / SOS alarm

 ---
 title: Dispatch Console
 emoji: 🗺️
+colorFrom: blue
+colorTo: green
 sdk: docker
 app_port: 8080
 pinned: false
 ---
+# Dispatch Console
+A self-hostable PoC-style fleet dispatch console — in the spirit of platforms like Global-PTT's dispatch: a live map of members, SOS alert handling, group push-to-talk, and member/talkgroup management. One process, one SQLite file, no external services.
+## Features
+- **Live map + GPS** — Leaflet/OpenStreetMap map, member markers colored by talkgroup, online/offline styling, SOS pulse, popup with battery and coordinates; devices push positions over WebSocket, every ping is stored for trails (`GET /api/members/:id/trail`)
+- **SOS alerts** — devices raise SOS, console shows a queue with Ack → Resolve flow and an audio alarm; state is broadcast to all consoles instantly
+- **Intercom / PTT** — talkgroups with floor control (one speaker per group); dispatcher holds a button to talk, mic is captured at 16 kHz via AudioWorklet and relayed as PCM over the same WebSocket; floor indicator shows who is talking; call log recorded
+- **Member management** — add/edit/remove members, assign talkgroups, see status/battery/last-seen; talkgroup list with colors
+## Architecture
+```
+browser / devices
+   │  HTTPS (REST: members, groups, SOS, trails)
+   │  WSS   /ws (GPS, SOS, PTT control, PCM audio frames)
+   ▼
+Node + Express ── better-sqlite3 (dispatch.db)
+   └─ ws Hub: auth, floor control per talkgroup, audio relay
+React + Vite + Leaflet frontend (served statically by the same process)
 ```
+Binary audio frame on the WebSocket:
+`[1B type=0x01][4B groupId BE][4B memberId BE][Int16LE PCM @ 16 kHz]`
+Only the current floor holder of a talkgroup may transmit; the server drops audio from anyone else.
 ## Quickstart (Docker)
 ```bash
+docker compose up --build
+# open http://localhost:8080 — log in with admin / admin (change it)
 ```
+## Quickstart (dev)
+```bash
+cd server  && npm install && npm run dev        # API + WS on :8080
+cd web     && npm install && npm run dev        # Vite on :5173, proxied to :8080
+```
+## Simulated fleet
+With the server running, drive a fake fleet so you can see the console come alive:
+```bash
+cd server && npm run sim
+# 5 units driving around Paris, one SOS after ~25 s, rotating PTT floor requests
 ```
+## Device integration
+A device (or backend integration) authenticates with a dispatcher JWT and identifies as a member:
+```json
+{"type": "auth", "token": "<jwt>", "memberId": 12}
 ```
+Then, per message: `{"type":"gps","lat":48.85,"lng":2.35,"speed":34,"battery":80}`,
+`{"type":"sos"}`, `{"type":"ptt_start"}`, `{"type":"ptt_stop"}`,
+and raw binary frames for audio (format above).
+## Configuration
+| Env | Meaning |
+| --- | --- |
+| `PORT` | HTTP/WS port (default 8080) |
+| `DATA_DIR` | where `dispatch.db` and the JWT secret live (default `server/data`) |
+| `JWT_SECRET` | signing secret; generated and persisted on first run if unset |
+| `ADMIN_PASSWORD` | password for the first-run `admin` dispatcher |
+## Limitations & next steps
+- **Device auth is trusted-by-JWT**: any valid token can claim any `memberId`. Production needs per-device credentials and revocation.
+- **Audio is uncompressed 16 kHz PCM relayed over WebSocket** — fine for small fleets on good links; swap in Opus + an SFU (LiveKit, mediasoup) for larger ones and lossy networks.
+- Single-node SQLite; horizontal scale would need Postgres and a Redis pub/sub fan-out.
+- Map tiles come from public OpenStreetMap servers — self-host tiles for production privacy.
+- No TLS in the container — terminate TLS at your reverse proxy (devices require WSS/HTTPS for mic access anyway).
+- On HF Spaces, storage is ephemeral: the SQLite file resets on rebuild (fine for demos; use a mounted volume or external DB for real data).