# Shelly Modul

> Status: Implementiert. Der Parser verarbeitet Shelly-NG-Komponenten der
> Generationen 2, 3 und 4 generisch und unabhängig vom Gerätenamen.

Das Modul verarbeitet Shelly-RPC- und Statusmeldungen über das native
IP-Symcon-MQTT-Datenflussinterface. Es gehört zu Enelix Utils und besitzt
keine Abhängigkeit zum Enelix EMS.

## Ziel und Abgrenzung

- freie MQTT-Client-ID und freie ein- oder mehrstufige Topic-Präfixe
- automatische Erkennung aller gemeldeten Komponenten und skalaren Werte
- vollständige Speicherung von Listen als JSON-String
- konfigurierbare Erzeugung nach Datenpunktgruppen
- weiterhin schaltbare `Switch.Set`-Ausgänge
- keine Verwaltung von Broker- oder Shelly-Zugangsdaten
- keine Shelly-Gen1-`shellies/...`-Topics

Die generische Verarbeitung ist absichtlich nicht an eine statische Liste von
Gerätemodellen gekoppelt. Neue Komponenten landen in der Gruppe `Other` und
können damit ohne Moduländerung eingelesen werden.

## MQTT-Datenfluss

| Richtung | Topic | Inhalt |
| --- | --- | --- |
| Shelly nach Symcon | `<Prefix>/online` | Online-Status |
| Shelly nach Symcon | `<Prefix>/events/rpc` | `NotifyStatus` oder `NotifyEvent` |
| Shelly nach Symcon | `<Prefix>/status/<Komponente>` | Komponentenstatus |
| Shelly nach Symcon | `<Prefix>/status` | Gerätestatus |
| Shelly nach Symcon | `<Prefix>/announce` | Geräteinformationen |
| Symcon nach Shelly | `<Prefix>/rpc` | RPC-Aufruf `Switch.Set` |

Der Gerätepräfix wird vom bekannten Topic-Ende her bestimmt. Dadurch sind
`symcon/events/rpc` und `gebaeude/etage/aktor/events/rpc` gleichermassen
gültig. Die MQTT-Client-ID ist nicht Bestandteil der Erkennungslogik.

## Properties

| Ident | Standard | Beschreibung |
| --- | --- | --- |
| `UseDeviceTopicFilter` | `false` | Aktiviert den optionalen Präfixfilter. |
| `DeviceTopicPrefix` | `shelly` | Filterwert; ohne aktivierten Filter wirkungslos. |
| `CreateOnline` | `true` | Online-Status. |
| `CreateDeviceInfo` | `true` | Modell- und Geräteinformationen. |
| `CreateInputs` | `true` | Inputs und Eingangsereignisse. |
| `CreateSwitches` | `true` | Schaltausgänge und Schalterstatus. |
| `CreateCovers` | `true` | Cover- und Beschattungswerte. |
| `CreateLights` | `true` | Licht-, Dimm- und Farbwerte. |
| `CreatePower` | `true` | Wirk- und Scheinleistung. |
| `CreateVoltage` | `true` | Spannungswerte. |
| `CreateCurrent` | `true` | Stromwerte. |
| `CreateEnergy` | `true` | Bezogene und zurückgelieferte Energie. |
| `CreateFrequency` | `true` | Netzfrequenz. |
| `CreatePowerFactor` | `true` | Leistungsfaktor. |
| `CreateMeterDetails` | `true` | Weitere Zählerdaten. |
| `CreateTemperature` | `true` | Temperaturwerte. |
| `CreateHumidity` | `true` | Feuchtewerte. |
| `CreateIlluminance` | `true` | Helligkeit und Beleuchtungsstärke. |
| `CreateBattery` | `true` | Batterie- und Versorgungswerte. |
| `CreateEnvironment` | `true` | Weitere Umweltsensoren. |
| `CreateSystem` | `false` | System- und Netzwerkstatus. |
| `CreateOther` | `false` | Unbekannte und zukünftige Komponenten. |
| `Debug` | `false` | Diagnoseausgaben der Instanz. |

Ein deaktivierter Bereich wird weder neu angelegt noch aktualisiert. Eine
automatische Löschung bestehender Objekte findet nicht statt.

## Typabbildung

| Shelly-Wert | IP-Symcon-Typ |
| --- | --- |
| Boolean | Boolean |
| bekannte IDs, Revisionen und Zeitangaben | Integer |
| übrige numerische Messwerte | Float |
| String | String |
| Liste | JSON-String |
| `null` | wird ignoriert |

Verschachtelte Objekte werden rekursiv in stabile Pfade wie
`switch:0.aenergy.total` zerlegt. Technische Idents enthalten einen kurzen
Hash, damit Sonderzeichen, lange Pfade und ähnlich benannte Punkte nicht
kollidieren.

## Öffentliche Funktion

```php
SHELLY_SetOutput(
    int $InstanzID,
    string $DeviceTopic,
    int $Output,
    bool $Value
): void;
```

Die Funktion validiert das Topic und den Ausgangsindex. Ein fehlendes oder
inaktives MQTT-Gateway erzeugt eine verständliche Exception.

## Kompatibilität

Die bestehenden Variablen für Online, Typ, Inputs, Switch-Ausgänge und die
Switch-Temperatur behalten ihre bisherigen Idents. Der frühere Präfixwert
`shelly` wirkt nach dem Update nur noch, wenn der neue Filter explizit
aktiviert wird.

## Prüfung

- Parser-Tests für freie und mehrstufige Topics
- Tests für unbekannte Modelle und generische Komponenten
- Tests für Gruppenklassifikation, Ereignisse und Typabbildung
- PHP-Syntaxprüfung und JSON-Prüfung
- Praxistest in IP-Symcon 8.0 mit projektseitigen Gen2-, Gen3- und
  Gen4-Geräten bleibt nach dem Merge erforderlich