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