+76
-77
@@ -1,107 +1,106 @@
|
||||
# Shelly Modul
|
||||
|
||||
Das Modul bindet Shelly-Geräte ab Generation 2 über deren MQTT/RPC-Protokoll
|
||||
in IP-Symcon ein. Es erkennt Geräte und Datenpunkte aus Statusmeldungen
|
||||
automatisch und benötigt keine Abhängigkeit zum Enelix EMS.
|
||||
Das Modul bindet Shelly-NG-Geräte der Generationen 2, 3 und 4 über MQTT/RPC
|
||||
in IP-Symcon ein. Es erkennt bekannte und zukünftige Komponenten dynamisch
|
||||
und benötigt keine Abhängigkeit zum Enelix EMS.
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
- IP-Symcon ab Version 8.0
|
||||
- ein eingerichteter IP-Symcon MQTT Server oder MQTT Client
|
||||
- ein Shelly Gen2+-Gerät mit aktivierter MQTT-Verbindung
|
||||
- MQTT-RPC-Ereignisse auf `<Topic>/events/rpc` und der Online-Status auf
|
||||
`<Topic>/online`
|
||||
- aktivierte RPC-Statusmeldungen (`rpc_ntf`)
|
||||
- optional aktivierte vollständige Statusmeldungen (`status_ntf`)
|
||||
|
||||
Shelly-Geräte der ersten Generation mit `shellies/...`-Topics werden nicht
|
||||
unterstützt.
|
||||
Shelly-Geräte der ersten Generation mit `shellies/...`-Topics verwenden ein
|
||||
anderes Protokoll und werden von diesem Modul nicht verarbeitet.
|
||||
|
||||
## Einrichtung
|
||||
## Freie MQTT-Namen
|
||||
|
||||
1. Das Modul über die Enelix-Utils-Bibliothek installieren und eine Instanz
|
||||
`Shelly Modul` anlegen.
|
||||
2. Das gewünschte MQTT-Gateway verbinden. Neue Instanzen verwenden
|
||||
standardmässig den internen MQTT Server; für einen externen Broker kann ein
|
||||
MQTT Client als Gateway gewählt werden.
|
||||
3. Am Shelly MQTT aktivieren und den Broker, Port und gegebenenfalls
|
||||
Zugangsdaten eintragen. Zugangsdaten gehören ausschliesslich in die
|
||||
MQTT-/Shelly-Konfiguration und nicht in dieses Modul.
|
||||
4. Den Topic-Präfix prüfen und die Instanz übernehmen.
|
||||
5. Eine Statusänderung am Gerät auslösen. Der Geräteordner und seine Variablen
|
||||
werden mit der ersten passenden Meldung angelegt.
|
||||
MQTT-Client-ID, Brokername, Benutzername und Kennwort werden ausschliesslich
|
||||
im MQTT-Gateway beziehungsweise im Shelly konfiguriert. Das Modul wertet
|
||||
diese Werte nicht aus. Der Shelly-`topic_prefix` darf frei gewählt werden und
|
||||
auch mehrere Ebenen enthalten, zum Beispiel `symcon` oder
|
||||
`gebaeude/etage/aktor`.
|
||||
|
||||
## Konfiguration
|
||||
Das Modul erkennt die Geräte-Topics anhand ihrer Endung:
|
||||
|
||||
| Property | Standard | Beschreibung |
|
||||
| --- | --- | --- |
|
||||
| `DeviceTopicPrefix` | `shelly` | Nur erste Topic-Ebenen mit diesem Präfix werden verarbeitet; Vergleich ohne Beachtung der Gross-/Kleinschreibung. Leer erlaubt alle gültigen Topic-Namen. |
|
||||
| `Debug` | `false` | Schreibt verarbeitete und gesendete MQTT-Nachrichten in den Instanz-Debug. |
|
||||
| Topic | Verwendung |
|
||||
| --- | --- |
|
||||
| `<Prefix>/online` | Online-Status |
|
||||
| `<Prefix>/events/rpc` | `NotifyStatus` und `NotifyEvent` |
|
||||
| `<Prefix>/status/<Komponente>` | vollständiger Komponentenstatus |
|
||||
| `<Prefix>/status` | vollständiger Gerätestatus |
|
||||
| `<Prefix>/announce` | Geräteinformationen |
|
||||
|
||||
Ein benutzerdefinierter Shelly-`topic_prefix` muss mit
|
||||
`DeviceTopicPrefix` übereinstimmen. Das Feld ist ein einfacher Präfix und
|
||||
kein regulärer Ausdruck.
|
||||
Ein optionaler Topic-Filter kann in den Moduleinstellungen aktiviert werden.
|
||||
Ohne aktivierten Filter werden alle gültigen Shelly-RPC-Topics verarbeitet.
|
||||
|
||||
## Automatisch angelegte Objekte
|
||||
## Datenpunktauswahl
|
||||
|
||||
Für jede erste MQTT-Topic-Ebene wird ein Geräteordner angelegt. Technische
|
||||
Idents bestehen nur aus den von IP-Symcon erlaubten Zeichen und enthalten
|
||||
zusätzlich einen kurzen Hash des originalen Topic-Namens. Damit bleiben auch
|
||||
Namen mit Bindestrichen stabil und kollisionsarm.
|
||||
In der Konfiguration kann für jede Gruppe festgelegt werden, ob neue
|
||||
Variablen angelegt und vorhandene Variablen aktualisiert werden:
|
||||
|
||||
| Anzeige | Typ / Zugriff | MQTT-Quelle |
|
||||
| --- | --- | --- |
|
||||
| Online | Boolean / Anzeige | `<Topic>/online` |
|
||||
| Typ | String / Anzeige | `src` einer RPC-Meldung |
|
||||
| Input n | Boolean / Anzeige | `input:n.state` oder `switch:n.input` |
|
||||
| Output n | Boolean / bedienbar | `switch:n.output` |
|
||||
| Temperatur | Float / Anzeige | erster erkannter Celsiuswert in `temperature`/`tC` |
|
||||
- Online-Status und Geräteinformationen
|
||||
- Eingänge und Eingangsereignisse
|
||||
- Schaltausgänge
|
||||
- Rollladen und Beschattung
|
||||
- Licht, Dimmer und Farbe
|
||||
- Leistung, Spannung, Strom, Energie, Frequenz und Leistungsfaktor einzeln
|
||||
- Temperatur, Feuchte, Helligkeit und Batterie einzeln
|
||||
- weitere Zähler- und Sensorwerte
|
||||
- System- und Netzwerkdaten
|
||||
- unbekannte und zukünftige Komponenten
|
||||
|
||||
Neue Inputs und Outputs werden dynamisch ergänzt. Bestehende Objekte werden
|
||||
nicht automatisch gelöscht, wenn ein Datenpunkt später nicht mehr gemeldet
|
||||
wird.
|
||||
Systemdaten und unbekannte Datenpunkte sind standardmässig deaktiviert, damit
|
||||
nicht unerwartet sehr viele Variablen entstehen. Bereits angelegte Variablen
|
||||
werden beim Abwählen einer Gruppe nicht gelöscht.
|
||||
|
||||
## Dynamische Variablen
|
||||
|
||||
Boolesche Werte werden als Boolean, Zähler und Zeitangaben als Integer,
|
||||
Messwerte als Float und Texte als String angelegt. Listen wie Fehlercodes oder
|
||||
Minutenwerte werden vollständig als JSON-String gespeichert. `null` wird
|
||||
ignoriert, da IP-Symcon keinen Null-Variablentyp besitzt.
|
||||
|
||||
Bekannte Datenpunkte erhalten lesbare Namen und passende Standardprofile,
|
||||
sofern das Profil in IP-Symcon vorhanden ist. Unbekannte Felder werden über
|
||||
ihren Komponenten- und Datenpfad stabil und kollisionsarm identifiziert.
|
||||
|
||||
## Ausgänge schalten
|
||||
|
||||
Eine Bedienung von `Output n` veröffentlicht einen Shelly-RPC-Aufruf
|
||||
`Switch.Set` auf `<Topic>/rpc`. Der Variablenwert wird nicht optimistisch
|
||||
gesetzt; er folgt der nächsten Statusmeldung des Geräts. Dadurch zeigt
|
||||
IP-Symcon keinen erfolgreichen Schaltvorgang an, wenn der Broker oder das
|
||||
Gerät den Auftrag nicht ausführt.
|
||||
|
||||
Aus Skripten kann derselbe Befehl direkt aufgerufen werden:
|
||||
Erkannte `switch:<n>.output`-Variablen bleiben bedienbar. Eine Bedienung
|
||||
veröffentlicht `Switch.Set` auf `<Prefix>/rpc`. Der Variablenwert wird erst
|
||||
mit der nächsten Gerätemeldung aktualisiert.
|
||||
|
||||
```php
|
||||
SHELLY_SetOutput($instanceID, 'shellyplus1pm-a1b2c3', 0, true);
|
||||
SHELLY_SetOutput($instanceID, 'symcon', 0, true);
|
||||
SHELLY_SetOutput($instanceID, 'gebaeude/etage/aktor', 1, false);
|
||||
```
|
||||
|
||||
## Unterstützte RPC-Struktur
|
||||
Andere Komponenten werden derzeit vollständig eingelesen, aber nicht pauschal
|
||||
schreibbar gemacht. Ihre RPC-Befehle unterscheiden sich fachlich, etwa bei
|
||||
Cover-, Light-, RGB- oder Thermostat-Komponenten.
|
||||
|
||||
Das Modul verarbeitet Publish-Pakete (`PacketType = 3`) mit JSON-Payloads
|
||||
nach folgendem Muster:
|
||||
## Einrichtung
|
||||
|
||||
```json
|
||||
{
|
||||
"src": "shellyplus1pm-a1b2c3",
|
||||
"method": "NotifyStatus",
|
||||
"params": {
|
||||
"switch:0": {
|
||||
"output": true,
|
||||
"temperature": {"tC": 42.5}
|
||||
},
|
||||
"input:0": {"state": false}
|
||||
}
|
||||
}
|
||||
```
|
||||
1. Instanz `Shelly Modul` aus Enelix Utils anlegen.
|
||||
2. Internen MQTT Server oder kompatiblen MQTT Client als Gateway verbinden.
|
||||
3. MQTT am Shelly aktivieren und RPC-Statusmeldungen einschalten.
|
||||
4. Gewünschte Datenpunktgruppen auswählen und Änderungen übernehmen.
|
||||
5. Am Gerät einen Statuswechsel auslösen.
|
||||
|
||||
Unvollständige, ungültige oder nicht zum konfigurierten Topic-Präfix passende
|
||||
Nachrichten werden ignoriert. Bei aktiviertem Debug werden fehlerhafte
|
||||
JSON-Payloads und ignorierte Online-Werte nachvollziehbar protokolliert.
|
||||
Bei einem externen MQTT-Broker muss der MQTT Client die passenden Topics
|
||||
abonnieren. Zugangsdaten gehören niemals in die Modulkonfiguration.
|
||||
|
||||
## Hinweise zur Adaption
|
||||
## Migration
|
||||
|
||||
Aus `Shelly_Parser_MQTT` von Enelix 1 wurden MQTT/RPC-Datenfluss,
|
||||
Geräteordner, dynamische Inputs/Outputs, Temperatur und `Switch.Set`
|
||||
fachlich übernommen. Neu implementiert wurden gültige stabile Idents,
|
||||
tatsächlich schaltbares Debug-Logging, strikte Payload-Prüfung, ein
|
||||
konfigurierbarer Topic-Präfix sowie verständliche Fehler bei einem inaktiven
|
||||
MQTT-Gateway. Die pauschale MQTT-`#`-Subscription und dauerhaftes
|
||||
System-Logging wurden verworfen.
|
||||
Der bisherige Wert `DeviceTopicPrefix = shelly` bleibt erhalten, wird aber nur
|
||||
noch ausgewertet, wenn `UseDeviceTopicFilter` aktiviert ist. Bestehende
|
||||
Online-, Typ-, Input-, Output- und Temperaturvariablen werden weiterverwendet.
|
||||
|
||||
## Diagnose
|
||||
|
||||
Mit `Debug` protokolliert die Instanz empfangene und gesendete MQTT-Pakete
|
||||
sowie ungültige JSON-Nutzdaten. Für die Fehlersuche sollte Debug nur
|
||||
vorübergehend aktiviert werden, weil Statusmeldungen umfangreich sein können.
|
||||
|
||||
Reference in New Issue
Block a user