Tracking System

The tracking system predicts beacon locations based on RSSI data from adv4 messages. It is implemented in server/src/tracking.ts with algorithm implementations in server/src/algs/.

Overview

When tracking is active, the system:

1. Receives adv4 RSSI data from MQTT (beacon signal strength at each gateway)
2. Maintains in-memory caches of zones, gateways, and maps
3. Runs a prediction algorithm to determine which zone a beacon is in
4. Publishes updates to WebSocket subscribers
5. Logs tracking intervals to protobuf files

Algorithms

Three tracking algorithms are available:

Zone Voting (tracking_alg_zone_voting)

The simplest algorithm. Each gateway "votes" for the zone it belongs to, weighted by the beacon's signal strength at that gateway. The zone with the most votes wins.

Trilateration (tracking_alg_trilateration)

Uses RSSI values from multiple gateways to estimate the beacon's 2D position via trilateration, then maps the position to the nearest zone.

Brutus (tracking_alg_brutus)

An enhanced algorithm that combines signal strength analysis with zone graph connectivity. Uses smoothing and history to reduce zone prediction jitter.

Control API

Endpoint	Method	Description
/api/v1/tracking/start/:alg	POST	Start tracking with a named algorithm
/api/v1/tracking/stop	POST	Stop tracking
/api/v1/tracking/status	GET	Current tracking state and algorithm
/api/v1/tracking/algorithms	GET	List available algorithms
/api/v1/tracking/:id	GET	Get tracking data for a beacon (:id = asset_uid)

WebSocket Updates

The tracking system pushes updates to three types of WebSocket subscribers:

• track-{asset_uid}: Position update for a specific asset
• track-debug-{asset_uid}: Debug data including RSSI values, gateway distances, and algorithm internals
• overview-{map_id}: All beacon positions on a specific map

Subscribe messages send data.mac as asset_uid (field name kept for schema stability).

Tracking Logs

Tracking intervals (beacon enters/exits a zone) are logged to protobuf files under the logs/ directory. These can be queried via the /api/v1/beacon/:id/intervals endpoint.

In-Memory Caches

The tracking module maintains caches loaded from the database:

Cache	Contents	Purpose
Zones	All zones with coordinates	Zone lookup for predictions
Gateways	Gateways with map/zone assignments	Map RSSI to gateways
Maps	Map metadata	Zone-to-map mapping
RSSI	Recent RSSI readings per beacon	Algorithm input data

The cache is loaded at startup via tracking_load_cache() and refreshed when maps, zones, or gateways are modified.