99 lines
4.0 KiB
Markdown
99 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
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 |
|
|
| --- | --- | --- |
|
|
| `<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 |
|
|
| --- | --- | --- |
|
|
| `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. |
|
|
|
|
## Öffentliche Funktion
|
|
|
|
```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.
|