Shelly MQTT Modul implementieren

docs/module/README.md

@@ -1,7 +1,7 @@
 # Modulübersicht Enelix Utils
 
-> Status: Der Verbrauchskostenreport ist implementiert. Die übrigen Module
-> sind als Diskussionsentwürfe dokumentiert.
+> Status: Verbrauchskostenreport und Shelly Modul sind implementiert. Die
+> übrigen Module sind als Diskussionsentwürfe dokumentiert.
 
 | Modul | Herkunft | EMS-Abhängigkeit |
 | --- | --- | --- |

docs/module/Shelly-Modul/README.md

@@ -1,31 +1,98 @@
 # Shelly Modul
 
-> Status: Diskussionsentwurf. Übernimmt `Shelly_Parser_MQTT` möglichst
-> unverändert und ohne EMS-Abhängigkeit.
+> Status: Implementiert. Die fachliche Funktion von
+> `Shelly_Parser_MQTT` wurde für IP-Symcon 8.0 bereinigt und ohne
+> EMS-Abhängigkeit in Enelix Utils adaptiert.
 
-Das Modul lauscht auf MQTT und legt pro erkanntem Gerät weiterhin einen Ordner
-mit Online-Status, Typ, Inputs, Outputs und Temperatur an.
+Das Modul verarbeitet Shelly Gen2+-Statusmeldungen über das native
+IP-Symcon-MQTT-Datenflussinterface. Ein interner MQTT Server wird beim
+Erstellen als Standard-Parent angeboten; ein kompatibler MQTT Client kann
+manuell als Gateway verbunden werden.
+
+## Ziel und Abgrenzung
+
+- automatische Erkennung von Geräten und vorhandenen Schaltkanälen
+- Anzeige von Online-Status, Typ, Inputs, Outputs und Temperatur
+- Schalten erkannter Outputs über Shelly RPC `Switch.Set`
+- keine Geräteauswahl, Discovery-Instanz oder EMS-Kopplung
+- keine Unterstützung für Shelly Gen1-`shellies/...`-Topics
+- keine Verwaltung von MQTT-Zugangsdaten oder Shelly-Gerätekonfiguration
+
+## MQTT-Datenfluss
+
+| Richtung | Topic | Inhalt |
+| --- | --- | --- |
+| Shelly nach Symcon | `<Topic>/online` | `true`/`false`, `1`/`0` oder `online`/`offline` |
+| Shelly nach Symcon | `<Topic>/events/rpc` | RPC-Payload mit `src` und `params` |
+| Symcon nach Shelly | `<Topic>/rpc` | RPC-Aufruf `Switch.Set` |
+
+Nur MQTT-Publish-Pakete mit `PacketType = 3` werden ausgewertet. Die erste
+Topic-Ebene wird als Geräte-Topic verwendet. Der konfigurierte Präfix wird
+ohne Beachtung der Gross-/Kleinschreibung geprüft.
 
 ## Dynamische Variablen
 
+`<Schlüssel>` ist ein aus dem Geräte-Topic abgeleiteter, für IP-Symcon
+gültiger Ident-Bestandteil mit kurzem Hash.
+
 | Ident-Muster | Typ / Zugriff | Beschreibung |
 | --- | --- | --- |
-| `<Geraet>_online` | Boolean / Anzeige | Online-Meldung. |
-| `<Geraet>_type` | String / Anzeige | Erkannter Gerätetyp. |
-| `<Geraet>_input_n` | Boolean / Anzeige | Dynamisch erkannter Eingang. |
-| `<Geraet>_output_n` | Boolean / bedienbar | Ausgang über vorhandenen Action Handler. |
-| `<Geraet>_temperature` | Float / Anzeige | Erkannte Temperatur. |
+| `<Schlüssel>_online` | Boolean / Anzeige | Online-Meldung. |
+| `<Schlüssel>_type` | String / Anzeige | Aus der RPC-`src` extrahierter Modellteil. |
+| `<Schlüssel>_input_n` | Boolean / Anzeige | `input:n.state` oder `switch:n.input`. |
+| `<Schlüssel>_output_n` | Boolean / bedienbar | `switch:n.output`; schaltet per RPC. |
+| `<Schlüssel>_temperature` | Float / Anzeige | Erster eindeutig erkannter Celsiuswert. |
+
+Die Output-Aktion wartet auf die Rückmeldung des Geräts und setzt den
+Variablenwert nicht vorab. Dynamisch angelegte Datenpunkte werden bei später
+fehlenden Meldungen nicht gelöscht.
 
 ## Properties
 
 | Ident | Typ | Standard / Beschreibung |
 | --- | --- | --- |
-| `Debug` | Boolean | `false`; bestehendes Debug-Logging. |
+| `DeviceTopicPrefix` | String | `shelly`; einfacher Präfix für die erste Topic-Ebene, leer akzeptiert alle gültigen Namen. |
+| `Debug` | Boolean | `false`; Instanz-Debug für empfangene/gesendete MQTT-Daten und Validierungsfehler. |
 
-## Verhalten und offene Punkte
+## Öffentliche Funktion
 
-- MQTT-Abonnements, Geräteordner, technische Idents und der interne Action
-  Handler bleiben erhalten.
-- In diesem Schritt keine Geräte- oder Datenpunktauswahl und keine neue
-  Objektstruktur einführen.
-- Beim Praxistest klären, ob der bestehende Debug-Schalter ausreicht.
+```php
+SHELLY_SetOutput(
+    int $InstanzID,
+    string $DeviceTopic,
+    int $Output,
+    bool $Value
+): void;
+```
+
+Die Funktion validiert Topic-Präfix und Ausgangsindex. Ein fehlendes oder
+inaktives MQTT-Gateway führt zu einer verständlichen Exception.
+
+## Adaption aus Enelix 1
+
+| Teil | Entscheidung |
+| --- | --- |
+| MQTT-Datenfluss-GUIDs und RPC-`Switch.Set` | angepasst übernommen |
+| dynamische Geräteordner und Datenpunkte | angepasst übernommen |
+| Parser für Inputs, Outputs und Temperatur | neu und strenger implementiert |
+| technische Idents mit roher Shelly-ID | verworfen; Bindestriche sind in IP-Symcon-Idents ungültig |
+| gemeinsames Action-Skript | angepasst übernommen und verborgen |
+| globale `#`-Subscription | verworfen; das native MQTT-Gateway liefert Publish-Daten über den Datenfluss |
+| bedingungsloses `IPS_LogMessage` | verworfen; Debug-Ausgabe respektiert die Property |
+| optimistisches Setzen eines Outputs | verworfen; Status folgt der Gerätebestätigung |
+
+## Betrieb und Diagnose
+
+1. MQTT-Gateway muss verbunden und aktiv sein.
+2. Shelly MQTT muss RPC-Statusmeldungen publizieren.
+3. Geräte-Topic und `DeviceTopicPrefix` müssen zusammenpassen.
+4. Bei fehlenden Variablen kurzzeitig `Debug` aktivieren und eine
+   Statusänderung auslösen.
+5. Zugangsdaten niemals in Logs oder Repository-Dokumentation übernehmen.
+
+## Offene Punkte
+
+- Praxistest mit den im Projekt eingesetzten Shelly-Modellen und deren
+  Firmwareständen.
+- Bei Bedarf spätere Erweiterung um weitere Komponenten wie Cover, Light,
+  Meter oder Batteriestatus als separat beschlossene Funktionalität.