Shelly Modul generisch erweitern

docs/module/Shelly-Modul/README.md

@@ -1,58 +1,87 @@
 # Shelly Modul
 
-> 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.
+> Status: Implementiert. Der Parser verarbeitet Shelly-NG-Komponenten der
+> Generationen 2, 3 und 4 generisch und unabhängig vom Gerätenamen.
 
-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.
+Das Modul verarbeitet Shelly-RPC- und Statusmeldungen über das native
+IP-Symcon-MQTT-Datenflussinterface. Es gehört zu Enelix Utils und besitzt
+keine Abhängigkeit zum Enelix EMS.
 
 ## 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
+- freie MQTT-Client-ID und freie ein- oder mehrstufige Topic-Präfixe
+- automatische Erkennung aller gemeldeten Komponenten und skalaren Werte
+- vollständige Speicherung von Listen als JSON-String
+- konfigurierbare Erzeugung nach Datenpunktgruppen
+- weiterhin schaltbare `Switch.Set`-Ausgänge
+- keine Verwaltung von Broker- oder Shelly-Zugangsdaten
+- keine Shelly-Gen1-`shellies/...`-Topics
+
+Die generische Verarbeitung ist absichtlich nicht an eine statische Liste von
+Gerätemodellen gekoppelt. Neue Komponenten landen in der Gruppe `Other` und
+können damit ohne Moduländerung eingelesen werden.
 
 ## 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` |
+| Shelly nach Symcon | `<Prefix>/online` | Online-Status |
+| Shelly nach Symcon | `<Prefix>/events/rpc` | `NotifyStatus` oder `NotifyEvent` |
+| Shelly nach Symcon | `<Prefix>/status/<Komponente>` | Komponentenstatus |
+| Shelly nach Symcon | `<Prefix>/status` | Gerätestatus |
+| Shelly nach Symcon | `<Prefix>/announce` | Geräteinformationen |
+| Symcon nach Shelly | `<Prefix>/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 |
-| --- | --- | --- |
-| `<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.
+Der Gerätepräfix wird vom bekannten Topic-Ende her bestimmt. Dadurch sind
+`symcon/events/rpc` und `gebaeude/etage/aktor/events/rpc` gleichermassen
+gültig. Die MQTT-Client-ID ist nicht Bestandteil der Erkennungslogik.
 
 ## Properties
 
-| Ident | Typ | Standard / Beschreibung |
+| Ident | Standard | Beschreibung |
 | --- | --- | --- |
-| `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. |
+| `UseDeviceTopicFilter` | `false` | Aktiviert den optionalen Präfixfilter. |
+| `DeviceTopicPrefix` | `shelly` | Filterwert; ohne aktivierten Filter wirkungslos. |
+| `CreateOnline` | `true` | Online-Status. |
+| `CreateDeviceInfo` | `true` | Modell- und Geräteinformationen. |
+| `CreateInputs` | `true` | Inputs und Eingangsereignisse. |
+| `CreateSwitches` | `true` | Schaltausgänge und Schalterstatus. |
+| `CreateCovers` | `true` | Cover- und Beschattungswerte. |
+| `CreateLights` | `true` | Licht-, Dimm- und Farbwerte. |
+| `CreatePower` | `true` | Wirk- und Scheinleistung. |
+| `CreateVoltage` | `true` | Spannungswerte. |
+| `CreateCurrent` | `true` | Stromwerte. |
+| `CreateEnergy` | `true` | Bezogene und zurückgelieferte Energie. |
+| `CreateFrequency` | `true` | Netzfrequenz. |
+| `CreatePowerFactor` | `true` | Leistungsfaktor. |
+| `CreateMeterDetails` | `true` | Weitere Zählerdaten. |
+| `CreateTemperature` | `true` | Temperaturwerte. |
+| `CreateHumidity` | `true` | Feuchtewerte. |
+| `CreateIlluminance` | `true` | Helligkeit und Beleuchtungsstärke. |
+| `CreateBattery` | `true` | Batterie- und Versorgungswerte. |
+| `CreateEnvironment` | `true` | Weitere Umweltsensoren. |
+| `CreateSystem` | `false` | System- und Netzwerkstatus. |
+| `CreateOther` | `false` | Unbekannte und zukünftige Komponenten. |
+| `Debug` | `false` | Diagnoseausgaben der Instanz. |
+
+Ein deaktivierter Bereich wird weder neu angelegt noch aktualisiert. Eine
+automatische Löschung bestehender Objekte findet nicht statt.
+
+## Typabbildung
+
+| Shelly-Wert | IP-Symcon-Typ |
+| --- | --- |
+| Boolean | Boolean |
+| bekannte IDs, Revisionen und Zeitangaben | Integer |
+| übrige numerische Messwerte | Float |
+| String | String |
+| Liste | JSON-String |
+| `null` | wird ignoriert |
+
+Verschachtelte Objekte werden rekursiv in stabile Pfade wie
+`switch:0.aenergy.total` zerlegt. Technische Idents enthalten einen kurzen
+Hash, damit Sonderzeichen, lange Pfade und ähnlich benannte Punkte nicht
+kollidieren.
 
 ## Öffentliche Funktion
 
@@ -65,34 +94,21 @@ SHELLY_SetOutput(
 ): void;
 ```
 
-Die Funktion validiert Topic-Präfix und Ausgangsindex. Ein fehlendes oder
-inaktives MQTT-Gateway führt zu einer verständlichen Exception.
+Die Funktion validiert das Topic und den Ausgangsindex. Ein fehlendes oder
+inaktives MQTT-Gateway erzeugt eine verständliche Exception.
 
-## Adaption aus Enelix 1
+## Kompatibilität
 
-| 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 |
+Die bestehenden Variablen für Online, Typ, Inputs, Switch-Ausgänge und die
+Switch-Temperatur behalten ihre bisherigen Idents. Der frühere Präfixwert
+`shelly` wirkt nach dem Update nur noch, wenn der neue Filter explizit
+aktiviert wird.
 
-## Betrieb und Diagnose
+## Prüfung
 
-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.
+- Parser-Tests für freie und mehrstufige Topics
+- Tests für unbekannte Modelle und generische Komponenten
+- Tests für Gruppenklassifikation, Ereignisse und Typabbildung
+- PHP-Syntaxprüfung und JSON-Prüfung
+- Praxistest in IP-Symcon 8.0 mit projektseitigen Gen2-, Gen3- und
+  Gen4-Geräten bleibt nach dem Merge erforderlich