Skip to content

ADR-005-mqtt-cc1101-response-consistency.adoc

Latest commit

 

History

History
49 lines (38 loc) · 3.03 KB

ADR-005-mqtt-cc1101-response-consistency.adoc

File metadata and controls

49 lines (38 loc) · 3.03 KB

ADR 005: Vereinheitlichung der MQTT-Antwortstruktur für CC1101-Parameter

Table of Contents

Kontext

Aktuell weichen die JSON-Antwortstrukturen für die Abfrage einzelner CC1101-Parameter via MQTT (z.B. Topic get/cc1101/bandwidth) von der Struktur der Gesamt-Abfrage (Topic get/cc1101/settings) ab.

  • Aktuelle Einzelabfrage (angenommen): get/cc1101/bandwidth → {"bandwidth": "X kHz"}

  • Aktuelle Gesamtabfrage (angenommen): get/cc1101/settings → {"cc1101": {"bandwidth": "X kHz", "rampl": "Y dbm", …​}}

Diese Inkonsistenz erschwert die automatisierte Verarbeitung der Antworten, da Clients je nach Abfragetyp unterschiedliche JSON-Pfade parsen müssen. Ziel ist eine konsistente Struktur, bei der die JSON-Knotennamen für die einzelnen Parameter in beiden Abfragetypen identisch sind.

Entscheidung

Die JSON-Antwortstruktur für alle CC1101-Parameter-Abfragen wird vereinheitlicht. Die Schlüsselnamen der einzelnen Parameter in der JSON-Antwort werden in beiden Abfragetypen (Einzelparameter und Gesamt-Settings) identisch verwendet. Es wird entschieden, die Schlüssel der Einzelparameter ohne umschließendes Wrapper-Objekt zu verwenden.

  • Antwort auf get/cc1101/parameter (z.B. get/cc1101/bandwidth): json {"bandwidth": "X kHz"}

  • Antwort auf get/cc1101/settings: json { "bandwidth": "X kHz", "rampl": "Y dbm", "sensitivity": "Z", "datarate": "A kbps" } Die settings-Antwort ist somit eine direkte Aggregation der Einzelparameter-Antworten.

Konsequenzen

Positive Konsequenzen

  • Konsistenz: Vereinfacht das Parsen für MQTT-Clients, da die logischen Parameternamen (z.B. bandwidth) immer als JSON-Schlüssel auf der obersten Ebene der jeweiligen Antwort verwendet werden.

  • Wartbarkeit: Reduziert die Komplexität in der Implementierung, da die Logik zur Generierung der Parameterdaten wiederverwendet werden kann.

Negative Konsequenzen

  • Breaking Change: Bestehende Clients, die sich auf eine Wrapper-Struktur wie {"cc1101": {…​}} bei der Gesamt-Abfrage (get/cc1101/settings) verlassen, müssen angepasst werden.

  • Migration: Die Server-Logik für die MQTT-Antworten in der PySignalduino-Implementierung muss entsprechend geändert werden.

Alternativen

  • Alternative A: Wrapper in Einzelabfragen beibehalten: Man könnte die Einzelabfrage um den CC1101-Wrapper erweitern (z.B. get/cc1101/bandwidth → {"cc1101": {"bandwidth": "X kHz"}}). Dies wurde abgelehnt, da es unnötige Verschachtelung für Einzelwerte einführt und die Lesbarkeit des Payloads verschlechtert.

  • Alternative B: Einzelabfragen als reiner Wert: Die Antwort könnte nur den reinen Wert zurückgeben (z.B. get/cc1101/bandwidth → "X kHz"). Dies wurde abgelehnt, da es das JSON-Format verlässt und der Parametername im Payload verloren ginge, was die Eindeutigkeit erschwert.