WebSockets

WebSocket connections are handled by server/src/routes/ws.ts. Clients connect to the WebSocket endpoint and subscribe to specific data streams by sending typed messages.

Connection

The WebSocket endpoint is available at the same port as the HTTP server, typically ws://localhost:8088/ws.

Subscription Types

Clients subscribe to data by sending a JSON message with a type field. The server validates the message with Valibot schemas and subscribes the client to the appropriate topic.

track

Subscribe to real-time tracking updates for a specific beacon.

{ "type": "track", "mac": "BC5729AABBCC" }

Subscribes to topic: track-{mac}

Receives tracking position updates as the beacon moves between zones.

debug

Subscribe to debug-level tracking data for a beacon (includes RSSI, algorithm internals).

{ "type": "debug", "mac": "BC5729AABBCC" }

Subscribes to topic: track-debug-{mac}

overview

Subscribe to map overview updates showing all beacon positions on a map.

{ "type": "overview", "map_id": 1 }

Subscribes to topic: overview-{map_id}

events

Subscribe to the global event stream (panic buttons, SOS alerts, etc.).

{ "type": "events" }

Subscribes to topic: events

test_beacon

Send a simulated beacon message for testing. This is forwarded to the events system and processed as if it came from MQTT.

{ "type": "test_beacon", "data": { ... } }

Subscribes to topic: test-beacon

Server-Sent Messages

The server pushes messages to subscribed clients using server.publish(topic, data). Message types include:

• track_update: Position update for a tracked beacon
• overview_update: Updated positions for all beacons on a map
• track_debug: Debug data with RSSI values and algorithm details
• event: New event (panic, SOS, etc.)

Validation

All incoming WebSocket messages are validated using Valibot schemas:

• HttpWsMessageTrackSchema for track/debug subscriptions
• HttpWsMessageOverviewSchema for overview subscriptions
• HttpWsMessageBeaconTestSchema for test beacon messages