Diese Dokumentation beschreibt immer die neueste Version des Moduls, aktuell 1.1.7 in den Kanälen Beta und Testing. Im Kanal Stable liegt noch die Version 1.0.3. Dort können Funktionen fehlen, die hier beschrieben sind.
ShellyBLUDevice
Mit dieser Instanz wird ein Shelly BLU-Gerät (z. B. Button, Door/Window, H&T, Motion) angelegt, das an einem oder mehreren Gateways angelernt ist (BLU Gateway, Shelly mit Bluetooth-Gateway). Das Gerät wird über seine MAC-Adresse erkannt, es genügt eine Instanz je BLU-Gerät. BLU TRVs (Thermostate) sind davon ausgenommen, sie laufen an genau einem Gateway und werden über die Komponenten-Instanz angelegt.
Idealerweise wird die Instanz über den Konfigurator angelegt (Gruppe “BLU-Geräte”), dann wird die gesamte Konfiguration korrekt ausgefüllt.
Inhaltsverzeichnis
1. Konfiguration
| Feld | Beschreibung |
|---|---|
| Haupt-Gateway (MQTT Topic) | Das Topic des Gateways, von dem die Nummerierung der Variablen stammt. Das Gerät muss an diesem Gateway angelernt sein. |
| MAC-Adresse des BLU-Geräts | MAC-Adresse des BLU-Geräts, z. B. aa:bb:cc:dd:ee:ff (Groß-/Kleinschreibung egal). |
| Weitere Gateways | Alle weiteren Gateways (MQTT Topics), an denen dasselbe Gerät angelernt ist. Alle Gateways müssen mit demselben MQTT Server/Client verbunden sein. |
| Stärkstes Gateway: maximales Alter | Ein Gateway zählt für “Stärkstes Gateway” nur, wenn es das Gerät in dieser Zeit (Sekunden) gehört hat. |
| Debug: Fehlende Idents | Zusätzliche Debug-Ausgaben, falls Variablen fehlen. |
| Variablen | Auswahl der Variablen, ebenfalls die Funktion “Zeroing” (Variable wird zurückgesetzt, wenn alle Gateways offline sind). |
2. Variablen
Alle Variablen einer Instanz. Die Namen der Variablen des Geräts beginnen mit dem Namen des Geräts, den man am Gateway vergeben hat, sonst mit der MAC-Adresse (z. B. aa:bb:cc:dd:ee:ff - Battery). In der Liste “Variablen” der Instanz kann man einzelne abwählen.
2.1 Variablen des Geräts
Der Ident beginnt mit bthomedevice_<N>_, <N> ist die Nummer des Geräts am Haupt-Gateway.
| Variable | Ident | Typ | Beschreibung |
|---|---|---|---|
| RSSI | rssi | Ganzzahl (dBm) | Signalstärke, mit der das Gerät empfangen wird. Bei mehreren Gateways der Wert des stärksten Gateways. |
| Battery | battery | Ganzzahl (%) | Batteriestand. |
| Letzte Aktualisierung | last_updated_ts | Datum/Uhrzeit | Wann das letzte Paket des Geräts empfangen wurde (der neueste Zeitpunkt aller Gateways). |
| Gekoppelt | paired | Ja/Nein | Ob das Gerät am Gateway angelernt ist. |
| Schlüssel hinterlegt | key | Ja/Nein | Ob am Gateway ein Verschlüsselungsschlüssel für das Gerät hinterlegt ist (nur bei verschlüsselten Geräten nötig). |
| Firmware-Version | fw_ver | Text | Firmware des BLU-Geräts. |
| Fehler | errors | Text | Fehler des Geräts als Text (z. B. “Entschlüsselung fehlgeschlagen” bei einem fehlenden oder falschen Schlüssel), leer wenn keiner vorliegt. |
| Störung | fault | Ja/Nein | true, sobald ein Fehler vorliegt, praktisch für Ereignisse und Benachrichtigungen. |
2.2 Tasten und Rad
Sie kommen als Ereignis des Geräts (beim Druck bzw. Drehen), nicht beim Auslesen. Welche es gibt, steht in der Modellliste (siehe 3.).
| Variable | Ident | Typ | Beschreibung |
|---|---|---|---|
| Taste | button | Text | Letzter Tastendruck: Einfach gedrückt, Doppelt gedrückt, Dreifach gedrückt, Lang gedrückt oder Gehalten. Bei Geräten mit mehreren Tasten heißt sie Taste 1. |
| Taste 2 bis Taste 4 | button2 bis button4 | Text | Die weiteren Tasten (BLU RC Button 4, Wall Switch 4). Die Tastennummer liefert das Gerät im Ereignis. |
| Rad | dial | Text | Letzte Drehrichtung des Drehrads (BLU Remote Control ZB): Hoch gedreht oder Runter gedreht. |
| Rad Schritte | dialsteps | Ganzzahl | Schritte der letzten Drehung, runter negativ. |
Geräte mit einer Taste als Hauptfunktion (z. B. Button, Wall Switch) haben die Variable von Anfang an. Bei den übrigen (z. B. Tür-/Fenstersensor, H&T, Motion) entsteht sie beim ersten Tastendruck.
2.3 Sensoren (Messwerte)
Je Sensor des Geräts gibt es eine Variable mit dem Messwert und eine mit dem Zeitpunkt der letzten Meldung ("bthomesensor_<Objekt * 100 + Index>_value bzw. ..._last_updated_ts (z. B. bthomesensor_4500_value für das Fenster), an allen Gateways gleich. Name, Typ und Einheit kommen vom Gerät bzw. aus der Liste unten. Die Batterie hat keine eigene Sensor-Variable, sie steht schon bei den Variablen des Geräts.
Die Sensoren, die ein Modell sendet, legt die Instanz sofort an (Liste siehe 3.), sie füllen sich mit dem ersten Paket des Geräts. Bis dahin zeigen sie den Standardwert (0, “Keine Bewegung”) und bei der Zeit “-”. Sendet ein Gerät einen Sensor nicht (mehr), bleibt die Variable bei dem letzten bekannten Wert.
| Sensor | BTHome-Objekt | Typ | Werte | Geräte (Beispiele) |
|---|---|---|---|---|
| Fenster | 45 | Ja/Nein | Offen / Geschlossen | Tür-/Fenstersensor |
| Bewegung | 33 | Ja/Nein | Bewegung / Keine Bewegung | Motion, Motion ZB |
| Temperatur | 69 | Zahl | °C | HT, H&T Display, Wetterstation |
| Luftfeuchtigkeit | 46 | Zahl | % | HT, H&T Display, Wetterstation |
| Beleuchtungsstärke | 5 | Zahl | lx | Tür-/Fenstersensor, Motion, Wetterstation |
| Drehung | 63 | Zahl | ° | Tür-/Fenstersensor: Öffnungswinkel. Remote Control ZB: drei Werte “Drehung 1” bis “Drehung 3” (Bedeutung vom Hersteller nicht beschrieben, vermutlich Lage des Geräts, ändern sich beim Drehen des Rads nicht) |
| Helligkeitsstufe | 100 | Aufzählung | Dunkel / Dämmerung / Hell | Motion ZB, Tür-/Fenstersensor ZB, H&T Display |
| Licht | 30 | Ja/Nein | Hell / Dunkel | H&T Display |
| Batterie schwach | 21 | Ja/Nein | Schwach / OK | H&T Display |
| Abstand | 64 | Zahl | mm | Distance |
| Kanal | 96 | Zahl | aktiver Kanal | Remote Control ZB |
| Luftdruck, Taupunkt, Spannung, Niederschlag, Feuchtigkeit (Regen), Wind (Geschwindigkeit und Böen), UV-Index, Richtung | 4, 8, 12, 95, 32, 68, 70, 94 | Zahl bzw. Ja/Nein | hPa, °C, V, mm, Nass/Trocken, m/s, -, ° | Wetterstation (nach der Doku, nicht an einem echten Gerät geprüft) |
2.4 Berechnete Werte (Wetterstation)
Hat das Gerät Temperatur, Luftfeuchtigkeit und Windgeschwindigkeit bzw. eine Windrichtung (z. B. Wetterstation), legt die Instanz zwei weitere Variablen an, die sie aus den Messwerten berechnet. Der Ident beginnt wie beim Gerät mit bthomedevice_<N>_. Sie werden bei jedem neuen Messwert aktualisiert und lassen sich in der Liste Variablen abwählen.
| Variable | Ident | Typ | Beschreibung |
|---|---|---|---|
| Gefühlte Temperatur | feels_like | Zahl (°C) | Bei höchstens 10 °C und mehr als 4,8 km/h Wind die Windchill-Temperatur, ab 27 °C der Hitzeindex (aus Temperatur und Luftfeuchtigkeit), sonst die gemessene Temperatur. Die Windgeschwindigkeit (mittlere Geschwindigkeit, m/s) wird für die Formel in km/h umgerechnet. |
| Windrichtung (Text) | wind_direction_text | Text | Die Windrichtung als Himmelsrichtung in 16 Stufen (N, NNO, NO, ONO, O, …). |
2.5 Variablen der Instanz (mehrere Gateways)
Beim Zusammenführen der Gateways gilt:
- Messwerte: der Wert mit dem neuesten Zeitstempel (
last_updated_ts) aller Gateways. - Tastendruck: von jedem Gateway; derselbe Druck, den zwei Gateways kurz nacheinander melden, wird nur einmal gezählt.
| Variable | Ident | Typ | Beschreibung |
|---|---|---|---|
| Erreichbar | Reachable | Online/Offline | Online, solange mindestens ein Gateway online ist. |
| RSSI ( | GwRssi_... | Ganzzahl (dBm) | Signalstärke, mit der dieses Gateway das Gerät empfängt (eine Variable je Gateway). |
| Letzte Aktualisierung ( | GwSeen_... | Datum/Uhrzeit | Wann dieses Gateway das Gerät zuletzt gehört hat (eine Variable je Gateway). |
| Stärkstes Gateway | NearestGateway | Text | Das Gateway mit dem stärksten Signal (nur Gateways, die online sind und das Gerät innerhalb des maximalen Alters gehört haben), z. B. für die Raumerkennung. Fällt ein Gateway aus, wechselt die Anzeige zum nächsten, sobald der MQTT-Server dessen Status “offline” meldet. |
3. Funktionen
void SHY_requestComponentsStatus(integer $InstanzID);
Ruft die Komponenten aller Gateways ab und legt die Variablen an. Die Funktion wird automatisch beim Anlegen der Instanz, nach Änderungen an der Konfiguration und nach einem Update des Moduls aufgerufen. Beim Start von IP-Symcon ruft die Instanz nichts ab: Die Zuordnung zu den Gateways wird gespeichert, und die Gateways melden laufend.
4. Modelle
Welches BLU-Gerät es ist, steht in der Modell-ID (attrs.model_id der Komponente am Gateway). Die Liste der bekannten Modelle ist im Modul hinterlegt (Name, Taste, Thermostat und die BTHome-Objekte, die das Modell sendet). Für diese Modelle gibt es die Sensor-Variablen (Fenster, Luftfeuchtigkeit, Temperatur, …) sofort beim Anlegen der Instanz, auch wenn das Gateway sie noch nicht gemeldet hat; die Variablen füllen sich beim ersten Paket des Geräts. Unbekannte Modelle funktionieren weiter, aber nur mit den Sensoren, die das Gateway meldet.
5. Spenden
Dieses Modul ist für die nicht kommerzielle Nutzung kostenlos, Schenkungen als Unterstützung für den Autor werden hier akzeptiert:
