feat: JSON streucture optimized and docs updated

sidey79 · sidey79 · commit 673730031c3e · 2026-01-11T22:53:04.000Z
diff --git a/.devcontainer/fhem-data/FHEM/99_MyUtils.pm b/.devcontainer/fhem-data/FHEM/99_MyUtils.pm
@@ -13,70 +13,6 @@ sub MyUtils_Initialize {
 
 # Enter you functions below _this_ line.
 
-sub MqttSignalduino_DispatchFromJSON {
-  my ($json_str, $name) = @_;
-  
-  if (!defined($json_str) || !defined($name)) {
-    Log3 $name, 3, "MqttSignalduino_DispatchFromJSON: Missing arguments (JSON or Name)";
-    return;
-  }
-
-  my $hash = $defs{$name};
-  if (!defined($hash)) {
-    Log3 $name, 3, "MqttSignalduino_DispatchFromJSON: Device $name not found";
-    return;
-  }
-
-  my $data;
-  eval {
-    $data = decode_json($json_str);
-  };
-  if ($@) {
-    Log3 $name, 3, "MqttSignalduino_DispatchFromJSON: JSON decode error: $@";
-    return;
-  }
-  #print Dumper($data);
-
-  $hash->{Clients}    = 'SD_WS:';
-  $hash->{MatchList}  = { '12:SD_WS'            => '^W\d+x{0,1}#.*' };
-
-  # Extract fields based on expected JSON structure from MQTT
-  # The full dispatch message is now constructed by combining 'preamble' (e.g., W126#) and 'state' (e.g., HexData).
-  
-  my $rmsg = $data->{rawmsg} // undef;
-  my $dmsg = $data->{payload} // undef; 
-  my $rssi = $data->{metadata}->{rssi} // undef;
-  my $id = $data->{protocol}->{id} // undef;
-  my $freqafc = $data->{metadata}->{freqafc} // undef;
-
-  if (!defined($dmsg)) {
-     Log3 $name, 4, "MqttSignalduino_DispatchFromJSON: No dmsg found in JSON";
-     return;
-  }
-
-  # Update hash with latest values
-  #$hash->{RAWMSG} = $rmsg if (defined($rmsg));
-  #$hash->{RSSI} = $rssi if (defined($rssi));
-  
-  # Prepare addvals similar to SIGNALduno_Dispatch
-  my %addvals = (
-    Protocol_ID => $id
-  );
-  
-  if (defined($rmsg)) {
-      $addvals{RAWMSG} = $rmsg;
-  }
-  if (defined($rssi)) {
-      $addvals{RSSI} = $rssi;
-  }
-  if (defined($freqafc)) {
-      $addvals{FREQAFC} = $freqafc;
-  }
-
-  Log3 $name, 5, "MqttSignalduino_DispatchFromJSON: Dispatching $dmsg";
-  
-  # Call FHEM Dispatch function
-  Dispatch($hash, $dmsg, \%addvals);
-}
+# MqttSignalduino_DispatchFromJSON wurde nach FHEM/lib/SD_Dispatch.pm verschoben.
 
 1;
diff --git a/.devcontainer/fhem-data/fhem_signalduino_example.cfg b/.devcontainer/fhem-data/fhem_signalduino_example.cfg
@@ -40,7 +40,7 @@ attr mqtt_broker autocreate simple
 define PySignalDuino MQTT2_DEVICE
 setuuid PySignalDuino 695e9c21-f33f-c986-4f81-a9f0ab37b6bcedf8
 attr PySignalDuino IODev mqtt_broker
-attr PySignalDuino readingList signalduino/v1/state/messages:.* { MqttSignalduino_DispatchFromJSON($EVENT, $NAME);; json2nameValue($EVENT,'MSG_');; }\
+attr PySignalDuino readingList signalduino/v1/state/messages:.* { use FHEM::Devices::SIGNALDuino::Message;; FHEM::Devices::SIGNALDuino::Message::json2Dispatch($EVENT, $NAME);; json2nameValue($EVENT,'MSG_');; }\
   signalduino/v1/responses:.* { json2nameValue($EVENT, 'RESP_') }\
   signalduino/v1/errors:.* { json2nameValue($EVENT, 'ERR_') }
 # attr PySignalDuino Clients :CUL_EM:CUL_FHTTK:CUL_TCM97001:CUL_TX:CUL_WS:Dooya:FHT:FLAMINGO:FS10:FS20:Fernotron:Hideki:IT:KOPP_FC:LaCrosse:OREGON:PCA301:RFXX10REC:Revolt:SD_AS:SD_Rojaflex:SD_BELL:SD_GT:SD_Keeloq:SD_RSL:SD_UT:SD_WS07:SD_WS09:SD_WS:SD_WS_Maverick:SOMFY:Siro:SIGNALduino_un:
diff --git a/README.adoc b/README.adoc
@@ -44,26 +44,8 @@ Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Reposito
 ====
 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
-  }
-}
-----
-====
+include::./docs/architecture/snippets/json_output_schema_example.adoc[]
+
 
 == Demo
 
diff --git a/docs/architecture/decisions/ADR-006-json-output-schema.adoc b/docs/architecture/decisions/ADR-006-json-output-schema.adoc
@@ -21,7 +21,6 @@ Die Umbenennung des Nutzdatenfeldes von `payload` zu `data` sowie die Einführun
 
 | 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. |
@@ -34,25 +33,7 @@ Die Umbenennung des Nutzdatenfeldes von `payload` zu `data` sowie die Einführun
 
 === 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
-  }
-}
-----
+include::../snippets/json_output_schema_example.adoc[]
 
 == Konsequenzen
 **Positiv:**
diff --git a/docs/architecture/decisions/ADR-007-data-and-raw-fields.adoc b/docs/architecture/decisions/ADR-007-data-and-raw-fields.adoc
@@ -27,25 +27,7 @@ Wir passen das in ADR-006 definierte Schema wie folgt an:
 
 === 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
-  }
-}
-----
+include::../snippets/json_output_schema_example.adoc[]
 
 [#adr-consequences]
 == Konsequenzen
diff --git a/docs/architecture/snippets/json_output_schema_example.adoc b/docs/architecture/snippets/json_output_schema_example.adoc
@@ -0,0 +1,18 @@
+[source,json]
+----
+{
+  "data": "30E0A1AA4241DE6C000200000BC5",
+  "raw": "MC;LL=-1017;LH=932;...",
+  "metadata": {
+    "rssi": -74,
+    "freq_afc": 123
+  },
+  "protocol": {
+    "name": "WH31",
+    "id": "125",
+    "preamble": "W125#",
+    "format": "2-FSK",
+    "clock": 17257
+  }
+}
+----
diff --git a/signalduino/mqtt.py b/signalduino/mqtt.py
@@ -253,8 +253,10 @@ def _raw_frame_to_dict(raw_frame: RawFrame) -> dict:
         preamble = ""
         if self._protocol_handler:
             try:
-                # check_property returns the value or default
-                preamble = self._protocol_handler.check_property(message.protocol_id, 'preamble', '')
+                protocol_id = message.protocol.get('id')
+                if protocol_id:
+                    # check_property returns the value or default
+                    preamble = self._protocol_handler.check_property(protocol_id, 'preamble', '')
             except Exception as e:
                 self.logger.warning("Failed to get preamble: %s", e)
 
@@ -289,6 +291,7 @@ async def publish(self, message: DecodedMessage) -> None:
             topic = f"{self.base_topic}/state/messages"
             payload = self._message_to_json(message)
             await self.client.publish(topic, payload)
-            self.logger.debug("Published message for protocol %s to %s", message.protocol_id, topic)
+            protocol_id = message.protocol.get('id', 'N/A')
+            self.logger.debug("Published message for protocol %s to %s", protocol_id, topic)
         except Exception:
             self.logger.error("Failed to publish message", exc_info=True)
diff --git a/signalduino/parser/mc.py b/signalduino/parser/mc.py
@@ -105,7 +105,6 @@ def parse(self, frame: RawFrame) -> Iterable[DecodedMessage]:
             payload = raw_payload[preamble_len:]
 
             yield DecodedMessage(
-                protocol_id=protocol_id_str,
                 data=payload,
                 raw=frame.line,
                 metadata=decoded.get("meta", {}),
diff --git a/signalduino/parser/mn.py b/signalduino/parser/mn.py
@@ -179,7 +179,6 @@ def parse(self, frame: RawFrame) -> Iterable[DecodedMessage]:
             self.logger.info("MN Parse: Decoded matched MN Protocol id %s dmsg=%s", pid, final_payload)
             
             yield DecodedMessage(
-                protocol_id=str(pid),
                 data=final_payload,
                 raw=frame.line,
                 metadata={
@@ -188,4 +187,5 @@ def parse(self, frame: RawFrame) -> Iterable[DecodedMessage]:
                     "modulation": modulation,
                     "rfmode": proto_rfmode
                 },
+                protocol={"id": str(pid), "model": "MN"}
             )
diff --git a/signalduino/parser/ms.py b/signalduino/parser/ms.py
@@ -59,10 +59,10 @@ def parse(self, frame: RawFrame) -> Iterable[DecodedMessage]:
                 continue
 
             yield DecodedMessage(
-                protocol_id=str(decoded["protocol_id"]),
                 data=str(decoded.get("payload", "")),
                 raw=frame.line,
                 metadata=decoded.get("meta", {}),
+                protocol={"id": str(decoded["protocol_id"]), "model": "MS"},
             )
 
     def _parse_to_dict(self, line: str) -> Dict[str, Any]:
diff --git a/signalduino/parser/mu.py b/signalduino/parser/mu.py
@@ -92,7 +92,6 @@ def parse(self, frame: RawFrame) -> Iterable[DecodedMessage]:
             payload = raw_payload[preamble_len:]
 
             yield DecodedMessage(
-                protocol_id=protocol_id_str,
                 data=payload,
                 raw=frame.line,
                 metadata=decoded.get("meta", {}),
diff --git a/signalduino/types.py b/signalduino/types.py
@@ -25,7 +25,6 @@ class RawFrame:
 class DecodedMessage:
     """Higher-level frame after running through the parser."""
 
-    protocol_id: str
     data: str
     raw: str
     metadata: dict = field(default_factory=dict)
diff --git a/tests/test_controller.py b/tests/test_controller.py
@@ -194,7 +194,7 @@ async def test_send_command_timeout(mock_transport, mock_parser, mock_controller
 async def test_message_callback(mock_transport, mock_parser, mock_controller_initialize):
     """Test message callback invocation."""
     callback_mock = Mock()
-    decoded_msg = DecodedMessage(protocol_id="1", data="test", raw="")
+    decoded_msg = DecodedMessage(data="test", raw="", protocol={"id": "1"})
     mock_parser.parse_line.return_value = [decoded_msg]
     
     # Use side_effect to return the line once, then fall back to the fixture's yielding None
diff --git a/tests/test_mc_parser.py b/tests/test_mc_parser.py
@@ -62,7 +62,7 @@ def test_mc_parser_valid_message(mc_parser, mock_protocols, line, expected_proto
     assert len(result) == 1
     
     # Neue/geänderte Assertions
-    assert result[0].protocol_id == expected_protocol
+    assert result[0].protocol["id"] == expected_protocol
     assert result[0].data == expected_payload  # Erwartet die bereinigte Payload
     assert result[0].raw == line
     
diff --git a/tests/test_mn_bresser_lightning.py b/tests/test_mn_bresser_lightning.py
@@ -30,7 +30,7 @@ def test_bresser_lightning_decoding(caplog):
     assert len(messages) == 1
     msg = messages[0]
     
-    assert msg.protocol_id == expected_protocol_id
+    assert msg.protocol["id"] == expected_protocol_id
     assert msg.data == expected_payload
     assert msg.raw == line
     assert msg.metadata["rfmode"] == "Bresser_lightning"
diff --git a/tests/test_mn_parser.py b/tests/test_mn_parser.py
@@ -110,7 +110,7 @@ def test_mn_parser_messages(
         if not raises_exception:
             assert len(result) == expected_message_count
             if result:
-                assert result[0].protocol_id == expected_protocol_id
+                assert result[0].protocol["id"] == expected_protocol_id
         else:
             assert not result
     else:
@@ -202,7 +202,7 @@ def test_mn_parser_messages_perl_migration(
     if expected_message_count > 0:
         # Verify first message's protocol ID only if expected_protocol_id is set
         if expected_protocol_id is not None:
-            assert result[0].protocol_id == expected_protocol_id
+            assert result[0].protocol["id"] == expected_protocol_id
         
         # Verify freq_afc if expected
         if expected_freq_afc is not None:
diff --git a/tests/test_mqtt.py b/tests/test_mqtt.py
@@ -26,7 +26,6 @@ def mock_controller():
 @pytest.fixture
 def mock_decoded_message() -> DecodedMessage:
     return DecodedMessage(
-        protocol_id="1",
         data="9374A400",
         raw="MS;P1=1154;P2=-697;P3=559;P4=-1303;P5=-7173;D=351234341234341212341212123412343412341234341234343434343434343434;CP=3;SP=5;R=247;O;",
         metadata={
@@ -35,6 +34,7 @@ def mock_decoded_message() -> DecodedMessage:
             "message_bits": "101010101011101111001100",
             "is_repeat": False,
         },
+        protocol={"id": "1"}, # Hinzugefügtes Protokoll-ID-Feld
     )
 
 @pytest.fixture
@@ -129,7 +129,7 @@ async def test_mqtt_publisher_publish_success(MockClient, mock_decoded_message,
     assert isinstance(published_payload, str)
     
     payload_dict = json.loads(published_payload)
-    assert payload_dict["protocol_id"] == "1"
+    assert payload_dict["protocol"]["id"] == "1"
     
     # Payload sollte KEINE Preamble mehr enthalten, aber das neue Feld "preamble" schon
     # Protocol 1 (Conrad RSL v1) hat Preamble "P1#"
diff --git a/tests/test_ms_parser.py b/tests/test_ms_parser.py
@@ -57,5 +57,5 @@ def test_correct_mc_cul_tcm_97001(self, parser):
         assert len(results) > 0
         
         # Optional: Check if it matched Protocol 0
-        p0_match = any(r.protocol_id == '0' for r in results)
+        p0_match = any(r.protocol.get('id') == '0' for r in results)
         assert p0_match
diff --git a/tests/test_mu_parser.py b/tests/test_mu_parser.py
@@ -48,7 +48,7 @@ def test_mu_parser_valid_messages(mu_parser, mock_protocols, line, expected_prot
     assert len(result) == 1
     
     # Neue/geänderte Assertions
-    assert result[0].protocol_id == expected_protocol
+    assert result[0].protocol["id"] == expected_protocol
     assert result[0].data == expected_clean_payload
     assert result[0].raw == line
     
