108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
# 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.
|
|
|
|
## 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`
|
|
|
|
Shelly-Geräte der ersten Generation mit `shellies/...`-Topics werden nicht
|
|
unterstützt.
|
|
|
|
## Einrichtung
|
|
|
|
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.
|
|
|
|
## Konfiguration
|
|
|
|
| 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. |
|
|
|
|
Ein benutzerdefinierter Shelly-`topic_prefix` muss mit
|
|
`DeviceTopicPrefix` übereinstimmen. Das Feld ist ein einfacher Präfix und
|
|
kein regulärer Ausdruck.
|
|
|
|
## Automatisch angelegte Objekte
|
|
|
|
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.
|
|
|
|
| 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` |
|
|
|
|
Neue Inputs und Outputs werden dynamisch ergänzt. Bestehende Objekte werden
|
|
nicht automatisch gelöscht, wenn ein Datenpunkt später nicht mehr gemeldet
|
|
wird.
|
|
|
|
## 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:
|
|
|
|
```php
|
|
SHELLY_SetOutput($instanceID, 'shellyplus1pm-a1b2c3', 0, true);
|
|
```
|
|
|
|
## Unterstützte RPC-Struktur
|
|
|
|
Das Modul verarbeitet Publish-Pakete (`PacketType = 3`) mit JSON-Payloads
|
|
nach folgendem Muster:
|
|
|
|
```json
|
|
{
|
|
"src": "shellyplus1pm-a1b2c3",
|
|
"method": "NotifyStatus",
|
|
"params": {
|
|
"switch:0": {
|
|
"output": true,
|
|
"temperature": {"tC": 42.5}
|
|
},
|
|
"input:0": {"state": false}
|
|
}
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
## Hinweise zur Adaption
|
|
|
|
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.
|