feat: Aktualisiere FHEM-Konfiguration und Dokumentation zur Integration von PySignalduino über MQTT;

Author: sidey79

.devcontainer/fhem-data/FHEM/99_MyUtils.pm

@@ -1,9 +1,11 @@
 attr global userattr cmdIcon devStateIcon:textField-long devStateStyle icon sortby webCmd webCmdLabel:textField-long widgetOverride
+attr global autoload_undefined_devices 1
 attr global autosave 0
 attr global logfile log/fhem-%Y-%m-%d.log
 attr global modpath .
 attr global nofork 0
 attr global pidfilename log/fhem.pid
+attr global showInternalValues 1
 attr global statefile ./log/fhem.save
 attr global updateInBackground 1
 attr global verbose 3
@@ -12,6 +14,7 @@ attr global verbose 3
 # This file is loaded by the FHEM container via CONFIGTYPE environment variable.
 
 define autocreate autocreate
+setuuid autocreate 696cb3f6-f33f-c986-f3b0-817e6b68814552c3
 
 # 1. Define FHEMWEB instance to access FHEM via Browser (Port 8083)
 define WEB FHEMWEB 8083 global
@@ -33,61 +36,20 @@ setuuid eventTypes 695e9c21-f33f-c986-9ac3-190c47641a98acb9
 define mqtt_broker MQTT2_CLIENT mqtt:1883
 setuuid mqtt_broker 695e9c21-f33f-c986-e617-d7301881c4685bc6
 attr mqtt_broker autocreate simple
+attr mqtt_broker verbose 3
 # end::broker_config[]
 
 # tag::device_config[]
 # 5. Define the SignalDuino MQTT Device
-define PySignalDuino MQTT2_DEVICE
-setuuid PySignalDuino 695e9c21-f33f-c986-4f81-a9f0ab37b6bcedf8
-attr PySignalDuino IODev mqtt_broker
-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:
-attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
-  cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
-  # System GET commands (noArg) \
-  version:noArg signalduino/v1/commands/get/system/version \
-  freeram:noArg signalduino/v1/commands/get/system/freeram \
-  uptime:noArg signalduino/v1/commands/get/system/uptime \
-  # Decoder state commands \
-  decoder_state:noArg signalduino/v1/commands/get/config/decoder \
-  decoder_ms_enable:noArg signalduino/v1/commands/set/config/decoder_ms_enable \
-  decoder_ms_disable:noArg signalduino/v1/commands/set/config/decoder_ms_disable \
-  decoder_mu_enable:noArg signalduino/v1/commands/set/config/decoder_mu_enable \
-  decoder_mu_disable:noArg signalduino/v1/commands/set/config/decoder_mu_disable \
-  decoder_mc_enable:noArg signalduino/v1/commands/set/config/decoder_mc_enable \
-  decoder_mc_disable:noArg signalduino/v1/commands/set/config/decoder_mc_disable \
-  # CC1101 GET commands (noArg) \
-  cc_config:noArg signalduino/v1/commands/get/cc1101/config \
-  cc_patable_get:noArg signalduino/v1/commands/get/cc1101/patable \
-  cc_register:noArg signalduino/v1/commands/get/cc1101/register \
-  cc_freq_get:noArg signalduino/v1/commands/get/cc1101/frequency \
-  cc_bandwidth_get:noArg signalduino/v1/commands/get/cc1101/bandwidth \
-  cc_rampl_get:noArg signalduino/v1/commands/get/cc1101/rampl \
-  cc_sensitivity_get:noArg signalduino/v1/commands/get/cc1101/sensitivity \
-  cc_datarate_get:noArg signalduino/v1/commands/get/cc1101/datarate \
-  cc_settings_get:noArg signalduino/v1/commands/get/cc1101/settings \
-  cc_deviation_get:noArg signalduino/v1/commands/get/cc1101/deviation\
-  # CC1101 SET commands \
-  cc_frequency_set:textField signalduino/v1/commands/set/cc1101/frequency $EVTPART1 \
-  cc_rampl_set:select,24,27,30,33,36,38,40,42 signalduino/v1/commands/set/cc1101/rampl $EVTPART1 \
-  cc_sensitivity_set:select,4,8,12,16 signalduino/v1/commands/set/cc1101/sensitivity $EVTPART1 \
-  cc_patable_set:select,-30_dBm,-20_dBm,-15_dBm,-10_dBm,-5_dBm,0_dBm,5_dBm,7_dBm,10_dBm signalduino/v1/commands/set/cc1101/patable $EVTPART1 \
-  cc_bandwidth_set:textField signalduino/v1/commands/set/cc1101/bandwidth $EVTPART1 \
-  cc_datarate_set:textField signalduino/v1/commands/set/cc1101/datarate $EVTPART1 \
-  cc_deviation_set:textField signalduino/v1/commands/set/cc1101/deviation $EVTPART1 \
-\
-  # Maintenance commands \
-  factory_reset:noArg signalduino/v1/commands/set/factory_reset
-attr PySignalDuino stateFormat state
+define SignalDuino_MQTT SIGNALduino mqtt
+setuuid SignalDuino_MQTT 696cb50e-f33f-c986-0810-0617456cfc539073
+attr SignalDuino_MQTT verbose 3
 # end::device_config[]
-# Map JSON payload to readings
-# Define setter commands
 
 # Logfile for SignalDuino
-define FileLog_PySignalDuino FileLog ./log/PySignalDuino-%Y.log PySignalDuino
-setuuid FileLog_PySignalDuino 695e9c21-f33f-c986-1981-abe9a5a366b3c989
-attr FileLog_PySignalDuino logtype text
+define FileLog_SignalDuino_MQTT FileLog ./log/FileLog_SignalDuino_MQTT-%Y.log SignalDuino_MQTT
+setuuid FileLog_SignalDuino_MQTT 696cb3f6-f33f-c986-687a-e2f563d64a4e8bbe
+attr FileLog_SignalDuino_MQTT logtype text
+
 define Logfile FileLog /opt/fhem/log/fhem-%Y-%m-%d.log Logfile
-setuuid Logfile 695e9c21-f33f-c986-cfda-4915c3e60c145721
+setuuid Logfile 696cb3f6-f33f-c986-3db0-979283e5714bf221

.devcontainer/fhem-data/fhem_signalduino_example.cfg

@@ -59,7 +59,20 @@ Ein neues FHEM-Modul, das die MQTT-Nachrichten von PySignalDuino abonniert und i
 |**Notwendige Änderungen** | **FHEM:** Neues Perl-Modul (z.B. `98_PySignalDuinoBridge.pm` oder `00_PySignalDuinoBridge.pm`) muss erstellt werden, das den JSON-Payload empfängt, `preamble` und `payload` verknüpft.
 |===
 
-=== Option 3: Anpassung in PySignalDuino (FHEM-Mode)
+=== Option 3: Direkte SIGNALduino-Integration über MQTT-Wrapper (`SD_MQTT.pm`)
+
+PySignalDuino publiziert Nachrichten an den `MQTT-Broker`, und das `SIGNALduino`-Modul in FHEM abonniert diese Nachrichten direkt über eine interne Wrapper-Logik (`SD_MQTT.pm`), die `MQTT2_Dispatcher` nutzt, wodurch die Notwendigkeit eines separaten `MQTT2_DEVICE` entfällt.
+
+[cols="1,3"]
+|===
+|Kriterium | Beschreibung
+|**Vorteile** | **Nahtlose Integration**. Fühlt sich für den Nutzer wie ein USB/Netzwerk-Signalduino an, aber über MQTT. Kein separates `MQTT2_DEVICE` oder Bridge-Modul nötig. Nutzt die bestehende Dispatch-Logik von `SIGNALduino`.
+|**Nachteile** | Erfordert Anpassung am `SIGNALduino`-Modul (via Wrapper).
+|**Implementierungsaufwand (grob)** | **Mittel**. Implementierung des Wrappers `SD_MQTT.pm` und Integration in `00_SIGNALduino.pm`.
+|**Notwendige Änderungen** | **FHEM:** `00_SIGNALduino.pm` muss erweitert werden, um `SD_MQTT` zu laden. Konfiguration eines `MQTT2_CLIENT` (Broker).
+|===
+
+=== Option 3b: Anpassung in PySignalDuino (FHEM-Mode)
 
 PySignalDuino wurde bereits angepasst, um die Felder `preamble` und `payload` zu senden, die zusammen dem FHEM-Dispatch-Format entsprechen.
 
@@ -93,13 +106,13 @@ PySignalDuino publiziert die demodulierten Nachrichten in einem standardisierten
 [cols="1,1,1,2"]
 |===
 |Option | PySignalDuino-Payload | FHEM-spezifische Konsequenzen | Systemübergreifende Eignung (HA/Node-RED)
-|**1, 1b, 2** | Standardisiertes JSON | Konvertierung/Parsing in FHEM notwendig. | **Gut.** Diese Systeme können JSON nativ und effizient parsen, benötigen aber eigene Logik (Templates/Scripts) zur Interpretation der Rohdaten, wenn FHEM dies nicht übernimmt.
-|**3** | FHEM-spezifischer String (z.B. P49#...) | Direkte Integration in FHEM möglich. | **Schlecht.** HA/Node-RED müssten proprietäre FHEM-Strings parsen oder PySignalDuino müsste doppelt senden (JSON + String), was Bandbreite/Performance kostet.
+|**1, 1b, 2, 3** | Standardisiertes JSON | Konvertierung/Parsing in FHEM notwendig. | **Gut.** Diese Systeme können JSON nativ und effizient parsen, benötigen aber eigene Logik (Templates/Scripts) zur Interpretation der Rohdaten, wenn FHEM dies nicht übernimmt.
+|**3b** | FHEM-spezifischer String (z.B. P49#...) | Direkte Integration in FHEM möglich. | **Schlecht.** HA/Node-RED müssten proprietäre FHEM-Strings parsen oder PySignalDuino müsste doppelt senden (JSON + String), was Bandbreite/Performance kostet.
 |**4** | Dekodiertes JSON (Werte) | Keine Dispatch-Logik nötig; direkte Nutzung der Readings. | **Exzellent.** Der "Gold Standard". MQTT-Nachrichten sind selbsterklärend und sofort nutzbar. Ermöglicht Plug & Play.
 |===
 
 **Fazit:** 
-*   Varianten, die das standardisierte JSON von PySignalDuino beibehalten (Option 1, 1b, 2), sind für eine Koexistenz gut geeignet.
+*   Varianten, die das standardisierte JSON von PySignalDuino beibehalten (Option 1, 1b, 2, 3), sind für eine Koexistenz gut geeignet.
 *   **Option 4** ist der klare Gewinner für moderne IoT-Landschaften (HA, Node-RED), erfordert aber den größten Aufwand in PySignalDuino.
 
 
@@ -214,7 +227,45 @@ sequenceDiagram
     D ->> D: Handle Message
 ....
 
-=== Option 3: Anpassung in PySignalDuino (FHEM-Mode)
+=== Option 3: Direkte SIGNALduino-Integration über MQTT-Wrapper (`SD_MQTT.pm`)
+
+**FHEM-Konfiguration:**
+[source,fhem]
+----
+# tag::broker_config[]
+# 4. Define the MQTT Client (Broker Connection)
+# 'mqtt' is the hostname of the broker service in docker-compose.yml
+define mqtt_broker MQTT2_CLIENT mqtt:1883
+setuuid mqtt_broker 695e9c21-f33f-c986-e617-d7301881c4685bc6
+attr mqtt_broker autocreate simple
+attr mqtt_broker verbose 3
+# end::broker_config[]
+
+# tag::device_config[]
+# 5. Define the SignalDuino MQTT Device
+define SignalDuino_MQTT SIGNALduino mqtt
+setuuid SignalDuino_MQTT 696cb50e-f33f-c986-0810-0617456cfc539073
+attr SignalDuino_MQTT verbose 3
+# end::device_config[]
+----
+
+**Flussdiagramm:**
+[mermaid]
+....
+sequenceDiagram
+    participant P as PySignalDuino
+    participant M as MQTT Broker
+    participant S as SIGNALduino (SD_MQTT)
+    participant D as Dispatcher
+
+    P ->> M: Publish JSON Payload
+    M ->> S: MQTT Message (via IO/Select)
+    S ->> S: SD_MQTT::Read() -> Parse JSON
+    S ->> D: Dispatch(msg)
+    D ->> D: Handle Message (Logical Modules)
+....
+
+=== Option 3b: Anpassung in PySignalDuino (FHEM-Mode)
 
 **PySignalDuino-Code (in link:../../../signalduino/mqtt.py[`signalduino/mqtt.py`]):**
 [source,python]
@@ -305,15 +356,15 @@ sequenceDiagram
 
 == Detaillierte Bewertung
 
-[cols="1,1,1,1,1"]
+[cols="1,1,1,1,1,1,1"]
 |===
-|Feature | Option 1 (Mapping) | Option 1b (Utils) | Option 2 (Bridge-Modul) | Option 4 (Portierung)
-|**Architektur** | "Bastel"-Lösung, unübersichtlich in Attributen | Sauberer Code, aber manuelle Integration nötig | Volle, standardkonforme FHEM-Integration | "Gold Standard", komplette Entkopplung
-|**Dispatch-Fähigkeit** | **Kritisch:** Erfordert manuelles `Clients`-Attribut (fehleranfällig) | **Kritisch:** Erfordert manuelles `Clients`-Attribut | **Automatisch:** Integriert im Modul | Nicht nötig (Werte kommen direkt)
-|**Konfigurationsaufwand** | Hoch (komplexe Regex im Attribut) | Mittel (Datei + Attribut) | Niedrig (ein `define`) | Sehr Niedrig (Auto-Create Readings)
-|**Wartbarkeit** | Schlecht | Gut (Code ist versionierbar) | Sehr gut (gekapseltes Modul) | Sehr gut (zentral in Python)
-|**Systemübergreifend** | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | **Exzellent** (Universal nutzbar)
-|**Entwicklungsaufwand** | Niedrig | Mittel | Mittel | **Sehr Hoch**
+|Feature | Option 1 (Mapping) | Option 1b (Utils) | Option 2 (Bridge-Modul) | Option 3 (Wrapper) | Option 3b (Anpassung) | Option 4 (Portierung)
+|**Architektur** | "Bastel"-Lösung, unübersichtlich in Attributen | Sauberer Code, aber manuelle Integration nötig | Volle, standardkonforme FHEM-Integration | Wrapper-Integration in Standard-Modul | JSON-Payload-Nutzung | "Gold Standard", komplette Entkopplung
+|**Dispatch-Fähigkeit** | **Kritisch:** Erfordert manuelles `Clients`-Attribut (fehleranfällig) | **Kritisch:** Erfordert manuelles `Clients`-Attribut | **Automatisch:** Integriert im Modul | **Automatisch:** Integriert via Wrapper | **Kritisch:** Erfordert manuelles `Clients`-Attribut | Nicht nötig (Werte kommen direkt)
+|**Konfigurationsaufwand** | Hoch (komplexe Regex im Attribut) | Mittel (Datei + Attribut) | Niedrig (ein `define`) | Niedrig (zwei `define`s) | Hoch (komplexe Regex/Funktion) | Sehr Niedrig (Auto-Create Readings)
+|**Wartbarkeit** | Schlecht | Gut (Code ist versionierbar) | Sehr gut (gekapseltes Modul) | Gut (Wrapper kapselt Logik) | Schlecht | Sehr gut (zentral in Python)
+|**Systemübergreifend** | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | Neutral (JSON bleibt erhalten) | **Exzellent** (Universal nutzbar)
+|**Entwicklungsaufwand** | Niedrig | Mittel | Mittel | Mittel | Niedrig (Erledigt) | **Sehr Hoch**
 |===
 
 == Empfehlung