feat: Aktualisiere JSON-Ausgabe-Schema zur Verbesserung der Datenstruktur und -klarheit; entferne Preamble aus Payload und füge neues Feld 'raw' hinzu

Author: sidey79

.gitignore

@@ -2,13 +2,11 @@ pycache/
 *.pyc
 .venv/
 .env/
-temp_repo/
 SIGNALDuino-Firmware/
 .devcontainer/devcontainer.env
 .devcontainer/.devcontainer.env
 .devcontainer/mosquitto/data/
 .devcontainer/mosquitto/log/
-
 .devcontainer/fhem-data/*
 !.devcontainer/fhem-data/FHEM
 .devcontainer/fhem-data/FHEM/*

README.adoc

@@ -39,6 +39,32 @@ Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Reposito
 * **Ausführbares Hauptprogramm** – `main.py` bietet eine sofort einsatzbereite Lösung mit Logging, Signalbehandlung und Timeout‑Steuerung.
 * **Komprimierte Datenübertragung** – Effiziente Payload‑Kompression für MQTT‑Nachrichten.
 
+[NOTE]
+.JSON Output Schema
+====
+Decodierte Nachrichten werden als JSON-Objekte publiziert. Die Protokoll-Metadaten sind nun im Feld `protocol` enthalten, das `data`-Feld enthält die reinen, von der Protokoll-Preamble bereinigten Nutzdaten, und das `raw`-Feld enthält die unveränderte, rohe Nachrichtenzeichenkette der Firmware.
+ 
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",
+  "protocol_id": "125",
+  "raw": "MS;P0=-32001;P1=488;D=0101;CP=1;R=48;",
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  },
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  }
+}
+----
+====
+
 == Demo
 
 === MQTT-CLI-Integration

docs/01_user_guide/mqtt_api.adoc

@@ -36,6 +36,49 @@ Alle nachfolgenden Beispiele verwenden `signalduino/v1` als Basis.
 | Dekodierte Funknachrichten.
 |===
 
+=== Empfangene Nachrichten (Output-Schema)
+
+Dekodierte Funksignale werden auf dem Topic `signalduino/v1/state/messages` publiziert.
+
+Die Payload folgt dem neuen, strukturierten Schema, bei dem protokollspezifische Metadaten im Feld `protocol` enthalten sind, das `data`-Feld die reinen, von der Protokoll-Preamble bereinigten Nutzdaten enthält, und das `raw`-Feld die unveränderte, rohe Nachrichtenzeichenkette der Firmware.
+
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",
+  "protocol_id": "125",
+  "raw": "MS;P0=-32001;P1=488;D=0101;CP=1;R=48;",
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  },
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  }
+}
+----
+
+==== Detailierte Felder der Output-Nachricht
+
+[cols="1,3", options="header"]
+|===
+| Feld | Beschreibung
+| `data`
+| Der dekodierte, bereinigte Payload (Hex- oder Bit-String), *ohne* Protokoll-Preamble (z.B. `W125#`).
+| `protocol_id`
+| Die numerische oder alphanumerische ID des erkannten Protokolls.
+| `raw`
+| Die ursprüngliche, unmodifizierte Nachrichtenzeichenkette (`string`), die von der Firmware empfangen wurde (z.B. `MS;P0=-32001;P1=488;D=0101;CP=1;R=48;`).
+| `metadata`
+| Allgemeine gerätespezifische Metadaten (z.B. `rssi`, `freq_afc`).
+| `protocol`
+| Ein Dictionary mit spezifischen Protokoll-Details, wie `name`, `id`, `preamble`, `format` und dem verwendeten `clock`-Wert.
+|===
+
 === Request- und Response-Format
 
 Alle Requests verwenden das folgende JSON-Format. Für einfache Befehle (meiste GETs) kann die Payload einfach `{}` sein.

docs/03_protocol_reference/protocol_details.adoc

@@ -6,6 +6,27 @@ PySignalduino unterstützt eine Vielzahl von Funkprotokollen im 433 MHz und 868
 
 Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Protokollparameter (Timings, Preambles, Methoden).
 
+=== Dekodiertes Nachrichtenformat
+
+Die dekodierten Nachrichten sind standardisierte JSON-Objekte, die protokollspezifische Metadaten im Feld `protocol` bereitstellen, den bereinigten Daten-Payload im Feld `data` (ohne Protokoll-Preamble), sowie die unveränderte, rohe Nachrichtenzeichenkette der Firmware im Feld `raw`.
+
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",
+  "protocol_id": "125",
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  },
+  "metadata": { ... },
+  "raw": "MS;P0=-32001;P1=488;D=0101;CP=1;R=48;"
+}
+----
+
 == Auszug unterstützter Protokolle
 
 * **ID 10:** Oregon Scientific v2/v3 (Manchester, 433 MHz)

docs/architecture/decisions/ADR-006-json-output-schema.adoc

@@ -0,0 +1,70 @@
+= ADR-006: JSON Output Schema Refinement
+:toc: macro
+:toc-title: Inhaltsverzeichnis
+
+== Status
+* **Status:** Proposed
+* **Datum:** 2026-01-11
+* **Architecture Owner:** Roo (Architect)
+
+== Kontext
+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.
+
+== Entscheidung
+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 link:ADR-007-data-and-raw-fields.adoc[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.
+
+=== Details zur neuen Struktur (Präzisiert durch ADR-007)
+
+| Feld | Typ | Beschreibung |
+|---|---|---|
+| `protocol_id` | `str` | Die numerische oder alphanumerische ID des erkannten Protokolls. |
+| `data` | `str` | Die bereinigten Nutzdaten **ohne** Preamble und Postamble (ersetzt `payload`). |
+| `raw` | `str` | Die ursprüngliche, unveränderte Nachricht vom Signalduino (z.B. `MU;...`). |
+| `protocol` | `dict` | Strukturierte Metadaten des Protokolls. |
+| `protocol.id` | `str` | Die ID des Protokolls (Redundanz zur einfachen Konsumierbarkeit). |
+| `protocol.name` | `str` | Der menschenlesbare Name des Protokolls (aus `protocols.json`). |
+| `protocol.preamble` | `str` | Die Preamble des Protokolls (z.B. `W125#`). |
+| `protocol.format` | `str` | Das Format des Signals (z.B. `manchester`, `twostate`, `2-FSK`) (aus `protocols.json`). |
+| `protocol.clock` | `int`/`float` | Der Clock-Wert, der für die Demodulation verwendet wurde (entweder `clockabs` oder `clockrange` Mittelwert/demodulierter Takt). |
+| `protocol.modulation` | `str` | (Optional) Modulationsart (z.B. `2-FSK`, `GFSK`) für FSK-Protokolle. |
+
+=== Beispiel für die Datenstruktur (Präzisiert durch ADR-007)
+
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",
+  "raw": "MC;LL=-1017;LH=932;...",
+  "protocol_id": "125",
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  },
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  }
+}
+----
+
+== Konsequenzen
+**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 link:ADR-007-data-and-raw-fields.adoc[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.
+
+== Alternativen
+1.  **Preamble in `metadata` verschieben:** Hätte den Nutzdatenfeld gereinigt, aber die Protokolldetails weiterhin unstrukturiert gelassen. Abgelehnt, da ein dediziertes `protocol`-Feld die semantische Klarheit verbessert.
+2.  **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.

docs/architecture/decisions/ADR-007-data-and-raw-fields.adoc

@@ -0,0 +1,64 @@
+= ADR-007: Renaming Payload to Data and Adding Raw Field
+:doctype: article
+:encoding: utf-8
+:lang: de
+:status: Proposed
+:decided-at: 2026-01-11
+:decided-by: Roo (Architect)
+
+[#adr-context]
+== Kontext
+
+Im Zuge der Definition des neuen JSON-Output-Schemas (siehe ADR-006) wurde Feedback gesammelt, das zwei wesentliche Verbesserungen vorschlägt:
+
+1.  **Ambiguität des Feldes `payload`:** Der Begriff `payload` wird in MQTT- und Messaging-Kontexten häufig für den gesamten Nachrichteninhalt verwendet. Die Verwendung von `payload` für die spezifischen, decodierten Hex-Daten kann daher zu Verwirrung führen.
+2.  **Bedarf an Rohdaten:** Für Debugging-Zwecke und fortgeschrittene Analysen ist es notwendig, Zugriff auf die ursprüngliche, unveränderte Nachricht zu haben, wie sie vom Signalduino-Gerät empfangen wurde (z.B. der komplette `MU;...`- oder `MC;...`-String), bevor irgendeine Verarbeitung oder Parsing stattgefunden hat.
+
+[#adr-decision]
+== Entscheidung
+
+Wir passen das in ADR-006 definierte Schema wie folgt an:
+
+1.  **Umbenennung `payload` zu `data`:**
+    Das Feld, das bisher `payload` hieß und die bereinigten Hex- oder Binärdaten (ohne Preamble) enthielt, wird in **`data`** umbenannt.
+
+2.  **Einführung des Feldes `raw`:**
+    Es wird ein neues Feld **`raw`** auf der obersten Ebene des JSON-Objekts eingeführt. Dieses Feld enthält den ursprünglichen Nachrichten-String, der an den Parser übergeben wurde.
+
+=== Aktualisierte Datenstruktur
+
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",   // Ehemals "payload"
+  "raw": "MC;LL=-1017;LH=932;...",          // Der originale Input-String
+  "protocol_id": "125",
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  },
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  }
+}
+----
+
+[#adr-consequences]
+== Konsequenzen
+
+=== Positive Konsequenzen
+*   **Klarere Semantik:** `data` ist ein neutralerer Begriff für den Dateninhalt und vermeidet die Überladung des Begriffs `payload`.
+*   **Verbesserte Debugging-Möglichkeiten:** Durch das `raw`-Feld können Entwickler und User jederzeit nachvollziehen, was genau vom Gerät empfangen wurde, und Parser-Fehler leichter diagnostizieren.
+*   **Vollständigkeit:** Keine Information geht verloren; sowohl die Rohdaten als auch die interpretierten Daten stehen zur Verfügung.
+
+=== Negative Konsequenzen
+*   **Breaking Change:** Dies ändert das gerade in ADR-006 vorgeschlagene Schema. Da ADR-006 jedoch noch neu ist, sollte der Anpassungsaufwand gering sein. Code, der bereits `payload` verwendet, muss auf `data` umgestellt werden.
+
+[#adr-alternatives]
+== Alternativen
+*   **Beibehaltung von `payload`:** Wurde verworfen, um die Ambiguität aufzulösen.
+*   **`raw` als Objekt:** Es wurde erwogen, `raw` strukturierter zu gestalten, aber für die einfache Nachvollziehbarkeit ist der originale String am wertvollsten.

docs/architecture/proposals/json_schema_refinement.adoc

@@ -0,0 +1,88 @@
+= Architecture Proposal: JSON Output Schema Refinement
+:toc: macro
+:toc-title: Inhaltsverzeichnis
+
+== Status
+* **Status:** Proposed
+* **Datum:** 2026-01-11
+* **Autor:** Roo (Architect)
+
+== Kontext
+Das aktuelle JSON-Nachrichtenschema für decodierte Signale vermischt Protokoll-Metadaten (die Preamble) mit den eigentlichen Nutzdaten (Payload). Zudem fehlen strukturierte Informationen über das erkannte Protokoll, die für weiterverarbeitende Systeme (z.B. Home Assistant, FHEM via MQTT) nützlich wären.
+
+Aktuelles Beispiel:
+[source,json]
+----
+{
+  "payload": "W125#30E0A1AA4241DE6C000200000BC5",
+  "metadata": { ... },
+  "protocol_id": "125"
+}
+----
+
+== Problemstellung
+1.  **Verschmutzter Payload:** Der Payload enthält die Preamble (z.B. `W125#`), was nachgelagerte Parser zwingt, diese zu entfernen.
+2.  **Fehlende Protokolldetails:** Es gibt kein dediziertes Feld, das alle relevanten statischen und dynamischen Eigenschaften des erkannten Protokolls zusammenfasst.
+
+== Lösungsvorschlag
+
+=== 1. Bereinigung des Payloads
+Die Preamble wird aus dem `payload`-Feld entfernt. Der Payload enthält nur noch die reinen Daten (Hex-String).
+
+=== 2. Erweiterung um `protocol`-Objekt
+Ein neues Feld `protocol` wird eingeführt, das strukturierte Informationen enthält.
+
+Neues Schema:
+[source,json]
+----
+{
+  "payload": "30E0A1AA4241DE6C000200000BC5",
+  "protocol_id": "125",
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "manchester",
+    "clock": 17257, // Optional: erkannter oder definierter Takt
+    "modulation": "2-FSK" // Optional: aus Protokolldefinition
+  },
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  }
+}
+----
+
+== Betroffene Komponenten
+
+=== `sd_protocols`
+Die Mixins für die Demodulation müssen angepasst werden, um die Preamble nicht mehr an den Payload anzuhängen, sondern separat zurückzugeben oder verfügbar zu machen.
+
+*   `sd_protocols/manchester.py`: `_demodulate_mc_data`
+*   `sd_protocols/message_synced.py`: `demodulate_ms`
+*   `sd_protocols/message_unsynced.py`: `demodulate_mu`
+*   `sd_protocols/sd_protocols.py`: `demodulate_mc`, `demodulate_mn`
+
+=== `signalduino/types.py`
+Die Klasse `DecodedMessage` muss um das Feld `protocol` erweitert werden.
+
+[source,python]
+----
+@dataclass(slots=True)
+class DecodedMessage:
+    protocol_id: str
+    payload: str
+    raw: RawFrame
+    metadata: dict = field(default_factory=dict)
+    protocol: dict = field(default_factory=dict) # Neu
+----
+
+=== `signalduino/parser`
+Die Parser-Klassen (`MCParser`, `MSParser`, `MUParser`, `MNParser`) müssen sicherstellen, dass das `protocol`-Feld korrekt aus den Rückgabewerten der Protokollschicht befüllt wird.
+
+== Migration
+Dies ist eine **Breaking Change** für Konsumenten, die erwarten, dass die Preamble Teil des Payloads ist. Die Versionsnummer sollte entsprechend (Minor oder Major, je nach Versionierungsstrategie) erhöht werden.
+
+== Alternativen
+*   **Status Quo beibehalten:** Führt zu unnötigem Parsing-Aufwand bei jedem Client.
+*   **Preamble nur in Metadata:** Löst das Payload-Problem, bietet aber keine strukturierte Sicht auf das Protokoll.

signalduino/mqtt.py

@@ -246,9 +246,10 @@ def _raw_frame_to_dict(raw_frame: RawFrame) -> dict:
             message_dict["raw"] = _raw_frame_to_dict(message_dict["raw"])
 
         # Remove empty or non-useful fields for publication
-        message_dict.pop("raw", None) # Do not publish raw frame data by default
+        # Note: 'raw' is now a string (ADR-007) and should be published.
+        # The pop operation (line 249 in original) is removed to include it.
 
-        # Append preamble to payload for FHEM compatibility (PreambleProtocolID#HexData)
+        # Append preamble to data for FHEM compatibility (PreambleProtocolID#HexData)
         preamble = ""
         if self._protocol_handler:
             try:
@@ -260,8 +261,8 @@ def _raw_frame_to_dict(raw_frame: RawFrame) -> dict:
         # Add new 'preamble' field
         message_dict["preamble"] = preamble
 
-        # Ensure payload is uppercase, but DO NOT prepend preamble anymore
-        message_dict["payload"] = message.payload.upper()
+        # Ensure data (formerly payload) is uppercase
+        message_dict["data"] = message.data.upper()
 
         return json.dumps(message_dict, indent=4)