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

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
    │
    └── 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 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 /status/mqtt
• Function: mqtt_status_get() returns connection state