@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user