Direkt zum Hauptinhalt

API Spezifikation für Telemetrie-Upload

API Spezifikation für Telemetrie-Upload

Version: 1.1
Stand: 2026-03-13

Übersicht

Diese Spezifikation beschreibt die REST-API-Anforderungen für die Übermittlung von Telemetriedaten der Safe Fire House Brandwarnanlage.

Parameter Wert
Method POST
Content-Type application/json
Accept application/json
Frequenz Zyklisch (stündlich) 24/7, azyklisch bei Alarm
Rate Limit Max. 60 Requests/Minute

Authentication

Eine der folgenden Authentifizierungsmethoden muss unterstützt werden:

Methode Header / Mechanismus Beispiel
API-Key X-API-Key X-API-Key: sk_live_abc123...
Bearer Token (JWT) Authorization: Bearer Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X.509 Client-Zertifikat mTLS (Mutual TLS) Client-Zertifikat im TLS-Handshake

Payload-Struktur

Root
├── timestamp
├── fireStation
├── deviceId
└── vehicles[]
    ├── vehicleId
    ├── sign
    ├── callSign
    ├── vehicleType
    └── smokeDetectors[]
        ├── name
        ├── address
        ├── type
        └── ...

Root-Objekt

Key Description Type Constraints
timestamp Zeitstempel der Erstellung string ISO 8601 UTC (YYYY-MM-DDTHH:mm:ssZ)
fireStation Wache (Name, Adresse) string Max. 150 Zeichen
deviceId Seriennummer der Zentrale string 14 Zeichen, hexadezimal
vehicles Auflistung der Fahrzeuge array Array von Vehicle-Objekten

Beispiel:

{
  "timestamp": "2026-03-13T11:24:13Z",
  "fireStation": "Feuerwehr Feuerstadt, Hauptstr. 112, 01234 Feuerstadt",
  "deviceId": "001A2B3C4D5E6F",
  "vehicles": [ ... ]
}

Vehicle-Objekt

Key Description Type Constraints
vehicleId Fahrzeug-Identifikationsnummer (VIN) string Max. 50 Zeichen
sign Kennzeichen string Max. 50 Zeichen
callSign Funkrufname string Max. 50 Zeichen
vehicleType Fahrzeugtyp string Max. 50 Zeichen
smokeDetectors Auflistung der Rauchsensoren array Array von SmokeDetector-Objekten

Beispiel:

{
  "vehicleId": "WVWZZZ3CZWE123456",
  "sign": "FS-FW 112",
  "callSign": "1-HLF20-1",
  "vehicleType": "HLF20",
  "smokeDetectors": [ ... ]
}

SmokeDetector-Objekt

Key Description Type Constraints
name Rauchsensorbezeichnung string Max. 30 Zeichen
address Rauchsensoradresse string 14 Zeichen, hexadezimal
type Rauchsensortyp string Max. 20 Zeichen
version Hardware-Version integer ≥ 1
firmware Firmware-Version string Max. 9 Zeichen, Pattern: [0-9.]+
group Gruppierung string 0–9 oder leer
teams Reserviert array —
rssiDevice Funkempfangswert Gerät (dBm) integer −128 bis 128
rssiPeer Funkempfangswert Sender (dBm) integer −128 bis 128
unreachState Flag: Gerät nicht erreichbar boolean true / false
unreachCumulative Kumulierte Nichterreichbarkeit (Tage) integer 0–9999
operationtime Betriebszeit (Tage) integer 0–9999
battery Flag: Batterieleistung niedrig boolean true / false
voltage Batteriespannung (V) float 0.0–3.2
errorcode Fehlercode integer 0–99
alarmstate Alarmstatus integer 0–3 (siehe Enum)
smokelevel Raucherkennungsgrad (%) float 0.0–100.0
dirtlevel Verschmutzungsgrad (%) float 0.0–100.0
chamber Flag: Rauchkammer verschmutzt boolean true / false

Beispiel:

{
  "name": "1-HLF20-1 RM1",
  "address": "00AABBCCDDEE11",
  "type": "DXO-SFH-SD-XX-02",
  "version": 1,
  "group": "",
  "teams": [],
  "firmware": "1.0.6",
  "rssiDevice": -65,
  "rssiPeer": 0,
  "battery": false,
  "unreachState": false,
  "unreachCumulative": 0,
  "operationtime": 180,
  "dirtlevel": 0.0,
  "smokelevel": 0.0,
  "alarmstate": 0,
  "voltage": 3.0,
  "chamber": false,
  "errorcode": 0
}

Enums

alarmstate

Wert Bedeutung
0 Ruhezustand – Kein Rauch erkannt
1 Lokaler Alarm – Rauch erkannt
2 Reserviert
3 Broadcast Alarm – Anderer Sensor in Funkreichweite hat Rauch erkannt

Flag-Logik

Flag Bedeutung wenn true Zusatzinfo
chamber Rauchkammer verschmutzt Siehe dirtlevel (%)
battery Batterieleistung niedrig Siehe voltage (V)
unreachState Gerät nicht erreichbar Siehe unreachCumulative (Tage)

Response

Erwartete HTTP Status Codes

Code Bedeutung
200 OK Erfolgreich verarbeitet
400 Bad Request Ungültiger Payload
401 Unauthorized Fehlende oder ungültige Authentifizierung
403 Forbidden Keine Berechtigung
429 Too Many Requests Rate Limit überschritten
500 Internal Server Error Serverfehler
503 Service Unavailable Service nicht verfügbar

Success Response

{
  "status": "ok",
  "received": "2026-03-13T11:24:13Z"
}

Error Response

{
  "error": "invalid_payload",
  "message": "Field 'address' invalid"
}

Vollständiges Payload-Beispiel

{
  "timestamp": "2026-03-13T11:24:13Z",
  "fireStation": "Feuerwehr Feuerstadt, Hauptstr. 112, 01234 Feuerstadt",
  "deviceId": "001A2B3C4D5E6F",
  "vehicles": [
    {
      "vehicleId": "WVWZZZ3CZWE123456",
      "sign": "FS-FW 112",
      "callSign": "1-HLF20-1",
      "vehicleType": "HLF20",
      "smokeDetectors": [
        {
          "name": "1-HLF20-1 RM1",
          "address": "00AABBCCDDEE11",
          "type": "DXO-SFH-SD-XX-02",
          "version": 1,
          "group": "",
          "teams": [],
          "firmware": "1.0.6",
          "rssiDevice": -65,
          "rssiPeer": 0,
          "battery": false,
          "unreachState": false,
          "unreachCumulative": 0,
          "operationtime": 180,
          "dirtlevel": 0.0,
          "smokelevel": 0.0,
          "alarmstate": 0,
          "voltage": 3.0,
          "chamber": false,
          "errorcode": 0
        },
        {
          "name": "1-HLF20-1 RM2",
          "address": "00AABBCCDDEE22",
          "type": "DXO-SFH-SD-XX-02",
          "version": 1,
          "group": "",
          "teams": [],
          "firmware": "1.0.6",
          "rssiDevice": -72,
          "rssiPeer": 0,
          "battery": false,
          "unreachState": false,
          "unreachCumulative": 0,
          "operationtime": 180,
          "dirtlevel": 0.0,
          "smokelevel": 0.0,
          "alarmstate": 0,
          "voltage": 3.0,
          "chamber": false,
          "errorcode": 0
        }
      ]
    }
  ]
}
nach oben