Direkt zum Hauptinhalt

MQTT Broker Service

MQTT ProtocolBroker Specification for LX2-PagersService

Der

Achtung,DEXA Entwurfsstadium!

Pager
Broker

Connection Details

  • Server: pager.dexa.gmbh
  • Port: 443 (HTTPS/WebSocket)
  • WebSocket URL: wss://pager.dexa.gmbh/mqtt
  • Protocol:unterstützt MQTT overals WebSocketKommunikationsprotokoll (Secure)
    • für
  • Authentication:LX7-Pager. CurrentlyMQTT disabledbietet (anonymous),gegenüber willTCP beeine enabledzuverlässigere later
    • Verbindung
mit automatischer Wiederverbindung und ist besonders für mobile Geräte mit wechselnder Netzwerkverbindung geeignet.

Topic StructureVerbindungsdaten

Inbound Topics (Pager → Server)

Topic PatternParameter DescriptionQoSWert
Brokerp/u/<uid>/regmqtt.pager.dexa.gmbh
Pager registration on startupPort 8883 (TLS)
ProtokollMQTT 3.1.1
p/u/<uid>/kaAuthentifizierung Keep-aliveClient-Zertifikat /oder Heartbeat0
p/u/<uid>/statusStatus updates (battery, GPS, signal)1
p/u/<uid>/ack/<alarm_id>Alarm acknowledgment1
p/u/<uid>/lwtLast Will & Testament (offline)1Username/Password

Outbound

Topic-Struktur

Alle Topics folgen dem Schema:

p/u//...

  • p = Pager
  • u = Unique ID
  • <UID> = 14-stellige Seriennummer des Pagers

Topics

Alarm senden (Server → Pager)

Topic PatternDescriptionQoS
p/u/<uid>/r/<ric>Alarm messages for specific RIC1

Variables:

  • <uid>: Pager unique ID (14 digits, e.g., 24702004551000)
  • <ric>: RIC code (e.g., 1379996A)
  • <alarm_id>: Alarm ID from database

Message Formats

All messages use JSON format.

1. Registration Message

Topic: p/u/24702004551000/reg<UID>/r/<RIC>

Payload:

{
  "type"msg": "reg",
  <Alarmtext>"uid": "24702004551000",
  "rics": ["1379996A", "1379997B"],
  "ts": 1700123456
}
Beispiel:

Fields:

  • type: Always "reg"
  • uid: Pager unique ID (14 digits)
  • rics: Array of RIC codes this pager subscribes to (optional)
  • ts: Unix timestamp (seconds since epoch)

What happens:

  • Pager is automatically switched from TCP to MQTT in database
  • last_seen_mqtt is updated
  • connection_type is set to 'mqtt'
  • active is set to TRUE
  • RICs are stored in database

2. Keep-Alive / Heartbeat

Topic: p/u/24702004551000/ka

Payload:

{
  "type": "ka",
  "uid": "24702004551000",
  "bat": 78,
  "sig": -68,
  "ts": 1700124000
}

Fields:

  • type: Always "ka"
  • uid: Pager unique ID
  • bat: Battery percentage (0-100, optional)
  • sig: Signal strength in dBm (e.g., -68, optional)
  • ts: Unix timestamp

What happens:

  • last_seen_mqtt is updated
  • Battery and signal are stored if provided
  • Pager remains active

3. Status Update

Topic: p/u/24702004551000/status

Payload:

{
  "type": "status",
  "uid": "24702004551000",
  "bat": 78,
  "v": 3.85,
  "lat": 51.5074,
  "lon": -0.1278,
  "sig": -68,
  "ts": 1700124001
}

Fields:

  • type: Always "status"
  • uid: Pager unique ID
  • bat: Battery percentage (0-100, optional)
  • v: Battery voltage in Volts (e.g., 3.85, optional)
  • lat: GPS latitude (decimal degrees, optional)
  • lon: GPS longitude (decimal degrees, optional)
  • sig: Signal strength in dBm (optional)
  • ts: Unix timestamp

When to send: Periodically (e.g., every 5-10 minutes) or on significant changes

What happens:

  • All provided fields are stored in database
  • last_seen_mqtt is updated
  • GUI displays updated values

4. Alarm Acknowledgment

Topic: p/u/24702004551000/ack/12345

Payload:

{
  "type": "ack",
  "uid": "24702004551000",
  "aid": 12345,
  "ric": "1379996A",
  "ts": 1700124002
}

Fields:

  • type: Always "ack"
  • uid: Pager unique ID
  • aid: Alarm ID (from tcp_outbound.id in database)
  • ric: RIC code (optional)
  • ts: Unix timestamp

When to send: When user acknowledges/views an alarm on the pager

What happens:

  • Alarm is marked as acknowledged in tcp_outbound table
  • success and sent_ok are set to TRUE

5. Last Will & Testament (LWT)

Topic: p/u/24702004551000/lwt

Payload:

{
  "type": "lwt",
  "uid": "24702004551000",
  "ts": 1700124003
}

Fields:

  • type: Always "lwt"
  • uid: Pager unique ID
  • ts: Unix timestamp

How to configure: Set this as MQTT Last Will message when connecting. The broker will automatically publish it if connection is lost unexpectedly.

What happens:

  • Pager is marked as active=FALSE in database
  • Shows as "Offline" in GUI

Receiving Alarms

Subscription

After registration, subscribe to your alarm topics:

p/u/24702004551000/r/+        # All RICs for this pager   p/u/24702004551000/r/1379996A
#Payload: Specific{"msg":"Feuer in Musterstadt, Hauptstraße 15"}

Der RIC onlywird
aus

Alarmdem Format

Topic

Alarmsextrahiert. areDer sentPager asempfängt binarydie dataNachricht (Latin-1nur, encoded)wenn der RIC in theseiner sameKonfiguration formathinterlegt asist. TCP:

--- 
KeepAlive und Antworten (Pager → Server)

Topic: p/u/<STXUID>24702004551000#09#1379996A#TESTEINSATZ/ka

Alle Pager-Nachrichten (KeepAlive, Alarm-Antworten, Notrufe) werden über dieses Topic gesendet. Die UID wird aus dem Topic extrahiert,
nicht aus dem Payload.

Type-Codes

| Type | Beschreibung    | Zusätzliche Felder |
|------|-----------------|--------------------|
| 10   | KeepAlive       | bat, gps           |
| 02   | Empfangen (ACK) | -                  Dies|
ist| ein80   Test<ETX>|
KOMME

Format breakdown:

  • <STX>: Start of text (0x02)
  • 24702004551000: Pager UID
  • #09#: Command code (09 = alarm)
  • 1379996A: RIC code
  • TESTEINSATZ| - Dies| ist| ein82 Test:| AlarmKOMME text
    • SPÄTER
  • <ETX>:| End- of| text| 84 | KOMME NICHT | - | | 08 | NOTRUF | gps | | 0A | MANDOWN | gps | | 0C | Tearoff | - | Payload-Felder | Feld | Typ | Beschreibung | |------|--------|---------------------------------------------------| | type | string | Type-Code (0x03)
    • siehe
Tabelle)

Connection| Flow

|

Initialbat Connection

|
    string
  1. Pager| connectsBatteriespannung, toz.B. wss://pager.dexa.gmbh/mqtt
    2. "4,24V+"
  2. Sends| registration| messagegps to| p/u/<uid>/reg
    3. string
  3. Server| automaticallyGPS-Position, switchesz.B. pager"130946 to52N13.007 MQTT009E33.7736" mode
    4. |
  4. Pager| subscribesfirm to| p/u/<uid>/r/+
    5. string
  5. Pager| starts sending keep-alive messages every 60s

Reconnection

If connection is lost:

  1. Pager reconnects to broker
  2. Sends registration message again
  3. Re-subscribes to alarm topics
  4. Continues normal operation

Battery Optimization

To maximize battery life:

  • Keep-AliveFirmware-Version (QoSnur 0):bei CanPowerOn) be| lost| withoutlte issues,| savesstring retransmission| overhead
  • Heartbeat interval: 60 secondsLTE/SIM-Info (cannur bebei adjustedPowerOn) based| onBeispiele needs)
    • KeepAlive:
  • Status updates: Only when values change significantly or every 5-10 minutes
  • QoS 1 for critical messages: Registration, Status, ACK to ensure delivery
  • MQTT Keep-Alive: 30 minutes (server configured)

Testing with mosquitto_pub

Send Registration

mosquitto_pub -h 127.0.0.1 -p 1883 -t "p/u/24702004551000/reg" \
  -m '{"type":"reg"10","uid"bat":"24702004551000"4,24V+","rics"gps":["1379996A"],"ts"130946 52N13.007 009E33.7736"}

PowerOn (mit Firmware-Info):1700123456}'

Send Keep-Alive

mosquitto_pub -h 127.0.0.1 -p 1883 -t "p/u/24702004551000/ka" \
  -m '{"type":"ka","uid":"24702004551000"10","bat":78,"sig"4,18V+","firm":-68,"ts"F2470101P60A0P51EF56","lte":1700124000}'"860873040845702"}
Alarm

Sendempfangen Status

(ACK): 
mosquitto_pub -h 127.0.0.1 -p 1883 -t "p/u/24702004551000/status" \
  -m '{"type":"status"02"}

Rückmeldung KOMME:
{"type":"80"}

NOTRUF:
{"type":"08","uid"gps":"24702004551000"130946 52N13.007 009E33.7736"}

MANDOWN:
{"type":"0A","bat"gps":78,"v"130946 52N13.007 009E33.7736"}

Hinweis: Alarm-Antworten (02, 80, 82, 84) enthalten keinen RIC. Die Antwort bezieht sich immer auf den zuletzt empfangenen Alarm des 
Pagers.

---
Last Will Testament (Broker → Server)

Topic: p/u/<UID>/lwt

Payload:
{"type":"lwt"}

Diese Nachricht wird vom MQTT-Broker automatisch gesendet, wenn die Verbindung zum Pager unerwartet abbricht (z.B. Funkloch, Akku leer).
Der Server markiert den Pager daraufhin als offline.

---
GPS-Format

Das GPS-Feld verwendet folgendes Format:

HHMMSS DDN/SMM.MMMM DDDE/WMM.MMMM

| Teil    | Beschreibung             | Beispiel              |
|---------|--------------------------|-----------------------|
| HHMMSS  | UTC-Zeit                 | 130946 = 13:09:46 UTC |
| DDN/S   | Breitengrad (Grad) + N/S | 52N = 52° Nord        |
| MM.MMMM | Breitengrad (Minuten)    | 13.007                |
| DDDE/W  | Längengrad (Grad) + E/W  | 009E = 9° Ost         |
| MM.MMMM | Längengrad (Minuten)     | 33.7736               |

Beispiel: 130946 52N13.007 009E33.7736
- Zeit: 13:09:46 UTC
- Position: 52° 13.007' N, 9° 33.7736' E

---
Ablauf einer Alarmierung

┌─────────┐                              ┌─────────┐
│ Server  │                              │  Pager  │
└────┬────┘                              └────┬────┘
     │                                        │
     │  p/u/24702004551000/r/1379996A         │
     │  {"msg":"Feuer in Musterstadt"}        │
     │ ─────────────────────────────────────► │
     │                                        │
     │  p/u/24702004551000/ka                 │
     │  {"type":"02"}                         │
     │ ◄───────────────────────────────────── │
     │                                        │
     │  p/u/24702004551000/ka                 │
     │  {"type":"80"}                         │
     │ ◄───────────────────────────────────── │
     │                                        │

1. Server sendet Alarm an Topic p/u/<UID>/r/<RIC>
2. Pager bestätigt Empfang mit {"type":"02"} auf /ka
3.85, Benutzer antwortet (z.B. KOMME) mit {"lat"type":51.5074,"lon":80"} auf /ka

-0.1278,"sig":-68,"ts":1700124001}'-
QoS-Einstellungen

| Topic             | QoS | Begründung                                    |
|-------------------|-----|-----------------------------------------------|
| p/u/<UID>/r/<RIC> | 1   | Alarme müssen zuverlässig zugestellt werden   |
| p/u/<UID>/ka      | 1   | Antworten und KeepAlive zuverlässig empfangen |
| p/u/<UID>/lwt     | 1   | Offline-Status zuverlässig erkennen           |

---
Einstellungen im Pager-Broker

Im Bereich Einstellungen können folgende MQTT-Optionen konfiguriert werden:

| Einstellung                    | Beschreibung                                                                 |
|--------------------------------|------------------------------------------------------------------------------|
| Pager automatisch registrieren | Neue MQTT-Pager werden beim ersten Kontakt automatisch im System angelegt    |
| RICs automatisch abonnieren    | RICs werden automatisch aus den MQTT-Topics erkannt und dem Pager zugeordnet |

Diese Einstellungen gelten nur für MQTT-Pager, nicht für TCP-Verbindungen.

Subscribe to Alarms

mosquitto_sub -h 127.0.0.1 -p 1883 -t "p/u/24702004551000/r/+" -v

Error Handling

  • Invalid JSON: Message is logged but ignored
  • Missing required fields: Partial processing (e.g., no battery update if bat missing)
  • Unknown UID: Message is stored in mqtt_inbound table but not processed
  • Connection lost: Auto-reconnect with exponential backoff (10s retry interval)
nach oben