MQTT Integration

The server connects to an MQTT broker to receive real-time beacon and gateway data. MQTT handling is split between lib/src/mqtt.ts (client connection) and server/src/mqtt.ts (message dispatching).

Message Types

Beacon Messages

Beacons broadcast three types of advertisement packets:

Type	Schema	Data	Purpose
adv1	MqttButtonAdv1Schema	Battery, temperature, humidity, button state	Sensor data and panic button events
adv4	MqttButtonAdv4Schema	RSSI, gateway MAC	Signal strength for location tracking
adv8	MqttButtonAdv8Schema	Extended sensor data	Additional sensor readings

Beacons are identified by MAC address with prefixes BC5729 or BBCBBC.

Gateway Messages

Type	Schema	Data	Purpose
alive	MqttGatewayAliveSchema	IP, uptime, firmware	Gateway health monitoring
advData	MqttGatewayAdvDataSchema	Beacon advertisements	Forwarded beacon data

Direct Sensor Messages

Legacy (non-BLE) MQTT-enabled sensors publish directly to the broker, without a gateway:

Type	Schema	Data	Purpose
sData	MqttSensorDataSchema	Temperature, humidity	Environmental readings from legacy sensors

These messages carry no RSSI, so the devices are discovered and fed into sensor storage/alerting but never participate in RTLS tracking. See the Legacy Sensor MQTT Spec for the full device-facing specification.

Message Flow

MQTT Broker
    │
    ▼
lib/src/mqtt.ts
    │  mqtt_start() → subscribes to all topics (#)
    │  Parses gateway messages (MqttGatewayMessageSchema)
    │  Extracts beacon adv1/adv4/adv8 and gateway alive
    │
    ▼
server/src/mqtt.ts
    │  mqtt_message_process(source, type, message)
    │
    ├── bridge_process_mqtt_message()  [if bridge enabled]
    │   → Forwards to Zabbix
    │
    ├── devices_mqtt_process()
    │   → Updates in-memory device caches (used immediately by Import Gateways / Import Beacons, alongside periodic sync to `device_gateways` / `device_beacons`)
    │
    └── events_process_mqtt_message()
        ├── Panic/SOS handling
        ├── Sensor data storage
        └── tracking_process_mqtt_message()
            → RSSI data for zone prediction

Configuration

MQTT connection is configured in config/main.config.json (legacy fallback: root main.config.json):

Key	Description
server_mqtt_url	Broker URL (e.g. mqtt://localhost:1883)
server_mqtt_user	Broker username
server_mqtt_pass	Broker password

Status

The MQTT connection status can be checked via:

• HTTP endpoint: GET /api/v1/status/mqtt (cached snapshot wrapper; the dashboard uses GET /api/v1/status/dashboard)
• Function: mqtt_status_get() returns connection state