# Shelly Modul

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
- aktivierte RPC-Statusmeldungen (`rpc_ntf`)
- optional aktivierte vollständige Statusmeldungen (`status_ntf`)

Shelly-Geräte der ersten Generation mit `shellies/...`-Topics verwenden ein
anderes Protokoll und werden von diesem Modul nicht verarbeitet.

## Freie MQTT-Namen

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`.

Das Modul erkennt die Geräte-Topics anhand ihrer Endung:

| 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 optionaler Topic-Filter kann in den Moduleinstellungen aktiviert werden.
Ohne aktivierten Filter werden alle gültigen Shelly-RPC-Topics verarbeitet.

## Datenpunktauswahl

In der Konfiguration kann für jede Gruppe festgelegt werden, ob neue
Variablen angelegt und vorhandene Variablen aktualisiert werden:

- 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

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

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, 'symcon', 0, true);
SHELLY_SetOutput($instanceID, 'gebaeude/etage/aktor', 1, false);
```

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.

## Einrichtung

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.

Bei einem externen MQTT-Broker muss der MQTT Client die passenden Topics
abonnieren. Zugangsdaten gehören niemals in die Modulkonfiguration.

## Migration

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.