Das bestehende JSON-Output-Schema für decodierte Funksignale (von DecodedMessage abgeleitet) enthält die Protokoll-Preamble (z.B. W125#) als Präfix im Feld payload. Dies erschwert die automatische Verarbeitung durch Downstream-Systeme (wie MQTT-Clients oder andere FHEM-Module), da diese die Preamble manuell entfernen müssen, um an die reinen Nutzdaten zu gelangen. Des Weiteren fehlt eine standardisierte Möglichkeit, protokollspezifische Metadaten (wie Protokollname, Format, Taktfrequenz) im Output bereitzustellen, ohne diese in der allgemeinen metadata-Struktur zu verstecken.
Wir werden das JSON-Output-Schema von DecodedMessage wie folgt anpassen:
1. Nutzdaten-Bereinigung: Die Protokoll-Preamble wird aus dem Nutzdatenfeld entfernt. Dieses Feld enthält nur noch die vom Protokolldecoder erzeugten reinen Daten (Hex- oder Bit-String).
2. Hinzufügen des protocol Feldes: Ein neues Feld protocol vom Typ dict wird zur DecodedMessage hinzugefügt, um strukturierte, protokollspezifische Informationen zu enthalten.
Die Umbenennung des Nutzdatenfeldes von payload zu data sowie die Einführung des Feldes raw (für die ursprüngliche Nachricht) sind in ADR-007 dokumentiert, das dieses Schema ergänzt und präzisiert. Dieses ADR dient als Grundlage für die Einführung des protocol-Feldes und die Bereinigung des Nutzdateninhalts.
Der JSON-Output für MQTT-Nutzdaten muss kompakt (ohne Zeilenumbrüche und Einrückungen) serialisiert werden, um die Kompatibilität mit MQTT-Brokern und Downstream-Systemen zu gewährleisten, die multiline-Nutzdaten falsch interpretieren könnten. Dies wird durch das Weglassen des indent-Parameters beim json.dumps-Aufruf in MqttPublisher sichergestellt.
| Feld | Typ | Beschreibung |
|---|---|---|
|
|
Die bereinigten Nutzdaten (meist Hex-String) ohne Preamble/Postamble. Repräsentiert die protokollspezifischen Daten (ersetzt |
|
|
Die ursprüngliche, unveränderte Nachricht vom Signalduino (z.B. |
|
|
Container für strukturierte Metadaten der erfolgreichen Protokolldemodulation. |
|
|
Die interne ID des Protokolls (z.B. |
|
|
Der menschenlesbare Name des Protokolls (aus |
|
|
Die Preamble (z.B. |
|
|
Das Format bzw. die Modulationsart des Signals (z.B. |
|
|
Der Takt-Wert in Mikrosekunden ( |
|
|
(Optional) Der RF-Modus (z.B. |
|
|
(Optional) Die tatsächliche Bitlänge der |
|
|
(Optional) Die Anzahl der erkannten Wiederholungen dieses Pakets, relevant für Duplikaterkennung. |
Positiv:
* Das data-Feld ist jetzt "sauber" und enthält nur die Nutzdaten.
* Protocolspezifische Metadaten sind standardisiert im protocol-Feld abrufbar.
* Vereinfacht die Integration mit Systemen, die strukturierte Daten erwarten.
* Das neue raw-Feld (siehe ADR-007) ermöglicht besseres Debugging und vollständige Nachvollziehbarkeit.
Negativ:
* Dies ist ein Breaking Change für alle existierenden Konsumenten des DecodedMessage-Outputs, die darauf angewiesen sind, dass die Preamble im payload enthalten ist.
* Alle Demodulations- und Parser-Logik muss angepasst werden, um die Preamble separat zu behandeln und das protocol-Feld sowie das neue raw-Feld zu befüllen.
-
Preamble in
metadataverschieben: Hätte den Nutzdatenfeld gereinigt, aber die Protokolldetails weiterhin unstrukturiert gelassen. Abgelehnt, da ein dediziertesprotocol-Feld die semantische Klarheit verbessert. -
Beibehaltung der alten Struktur: Hätte Abwärtskompatibilität gewährleistet, aber die Notwendigkeit für eine Nutzdatenreinigung durch jeden Konsumenten beibehalten. Abgelehnt, da die verbesserte Struktur die Wartbarkeit und zukünftige Erweiterbarkeit deutlich erhöht.