Zigbee2mqtt

An dieser Seite wird momentan noch gearbeitet.

Darstellung in FHEMWEB

zigbee2mqtt ist ein open-source Projekt, mit dem zigbee-Geräte über MQTT direkt angesprochen werden können, ohne dass hierfür eine Bridge eines Herstellers benötigt wird.

Installation von zigbee2mqtt

Die Installation des zigbee2mqtt-Diensts ist auf der Homepage des Projekts beschrieben. Ergänzend muss in der configuration.yaml eine client_id unter mqtt (z.B. zigbee_pi) vergeben werden.

mqtt:
  client_id: 'zigbee_pi'

tbd: weitere sinnvolle Einstellungen, availability, ...

Da der Dienst auch später in den Anlernmodus versetzt werden kann, kann man auch gleich permit_join: false setzen, um das versehentliche Einbinden neuer oder fremder Geräte zu unterbinden.

Zur Verbesserung der Bedienerfreundlichkeit empfiehlt es sich, das frontend von zigbee2mqtt zu aktivieren:

Hier kann man einige Einstellungen bequem vornehmen (beispielsweise den "friendly name") und auch die gepairten Geräte direkt schalten.

frontend:
  # Optional, default 8080
  port: 8080
  # Optional, default 0.0.0.0
  host: 0.0.0.0
  # Optional, enables authentication, disabled by default
  auth_token: your-secret-token

Wird ein CC2531 auf demselben Linux-Computer verwendet, auf dem auch FHEM installiert ist, kann es vorkommen, dass FHEM diesen mit einem CUL verwechselt und durch initialUsbCheck in FHEM einbindet, wodurch er für den zigbee2mqtt-Dienst nicht mehr verfügbar ist. Dann sollte initialUsbCheck deaktiviert und das automatisch angelegte CUL-Device wieder gelöscht werden. Weiter sollte der CC2531 auch in FHEM und zigbee2mqtt by-id eingebunden werden, um Probleme beim gleichzeitigen Einsatz anderer Geräte, die /dev/ttyACMx belegen können, zu vermeiden (betrifft z.B. CUL/MapleCUL ).

Zwischenzeitlich stehen neben den CC2531 bzw. CC2530 einige weitere, wesentlich leistungsfähigere Coordinator-Chipsets zur Verfügung. Ein Blick auf die betreffenden Info-Seiten bei zigbee2mqtt sei daher ausdrücklich empfohlen!

Define eines MQTT2-Devices als "Bridge"

Dann kann eine Art "Grund-Device" angelegt werden, das für die Ansteuerung des eigentlichen Server-Dienstes genutzt wird, der bereits unmittelbar nach der erfolgreichen Konfiguration von zigbee2mqtt zur Verfügung steht. In der Regel sollte dieses automatisch erstellt werden, wenn der zigbee2mqtt-Dienst (oder der betreffende Rechner) neu gestartet wird (oder FHEM oder dort ein Sensor einen Messwert sendet). Beispiel:

defmod MQTT2_zigbee_pi MQTT2_DEVICE zigbee_pi
attr MQTT2_zigbee_pi IODev MQTT2_FHEM_Server
attr MQTT2_zigbee_pi readingList zigbee_pi:zigbee2mqtt/bridge/state:.* state\
  zigbee_pi:zigbee2mqtt/0x90fd9ffffe65db16:.* { json2nameValue($EVENT, ) }\
  zigbee_pi:zigbee2mqtt/0x90fd9ffffe0bcd51:.* { json2nameValue($EVENT, ) }\
  zigbee_pi:zigbee2mqtt/bridge/log:.* { json2nameValue($EVENT, 'log_') }
attr MQTT2_zigbee_pi room MQTT2_DEVICE

Für die Funktion einer zigbee2mqtt-Bridge steht ein template bereit, das direkt die passenden Attribute vergibt, um dem zigbee2mqtt-Dienst passende Anweisungen geben zu können und weitere Geräte für die eigentlichen Aktoren und Sensoren anzulegen:

set MQTT2_zigbee_pi attrTemplate zigbee2mqtt_bridge

Ist dieses angelegt, kann zigbee2mqtt mit

set MQTT2_zigbee_pi permit_join true

in den Anlernmodus versetzt werden, anzulernende Geräte müssen anschließend jeweils nach Bedienungsanleitung in den Anlernmodus gebracht werden.

Vereinzeln der eigentlichen Geräte

Über das mit dem template vergebene bridgeRegexp-Attribut

attr MQTT2_zigbee_pi bridgeRegexp zigbee2mqtt/([A-Za-z0-9]*)[/]?.*:.* "zigbee_$1"

werden anschließend neue MQTT2_DEVICE-Geräte automatisch angelegt, sobald ein bisher unbekanntes Zigbee-Gerät einen neuen Status (z.B. einen Messwert) meldet. Um zu erfragen, welche Geräte dem zigbee-Deinst bekannt sind, kann via get MQTT2_zigbee_pi devicelist true eine Liste abgefragt werden, die weitere Informationen zu den bereits angelernten Geräten enthält. Geräte, die nicht automatisch etwas senden, kann man mit Hilfe des MQTT2_SERVER-Geräts einmalig schalten, damit diese ihren Status bzw. das erfolgreiche Schalten zurückmelden, Beispiel:

set MQTT2_FHEM_Server publish zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"ON","brightness":60}

(Alternativ kann man das Gerät auch über das Frontend von zigbee2mqtt schalten, um das Device in FHEM automatisch anzulegen.)

Für Gerätetypen, für die bereits templates vorhanden sind, ist es am einfachsten, diese einmalig auf die Geräte anzuwenden. Das Vorgehen entspricht dabei dem oben für die Bridge beschriebenen. Dafür wird immer vorausgesetzt, dass ein neues Device mit autocreate (ggf. über die bridgeRegexp) angelegt wurde

Beispiele:

IKEA-Tradfri-Birne

Wie wähle ich nun das richtige Template für mein Leuchtmittel aus?

-> Es wird nicht zwischen einer Birne/Bulb/Lampe und einem LED-Controller unterschieden sondern anhand der möglichen Lichtdarstellung des Gerätes:

light_dimmer: Das anzusteuernde Geräte besitzt ausschließlich eine feste Lichtfarbe welche gedimmt werden kann.

light_cct: Das anzusteuernde Gerät besitzt eine warmweiße sowie kaltweiße Lichtfarbe welche verändert sowie gedimmt werden kann.

light_rgb_xxx: Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und kann gedimmt werden.

light_rgbw_xxx: Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und besitzt eine warmweiße ODER kaltweiße Lichtfarbe welche eingestellt sowie gedimmt werden kann.

light_rgbcct_xxx: Das anzusteuernde Gerät besitzt die Möglichlichkeit einer farbigen Lichtdarstellung (Rot, Grün, Blau) und besitzt eine warmweiße UND kaltweiße Lichtfarbe welche verändert sowie gedimmt werden kann.

  xxx:
     hex:   Farbänderung mit hex
     rgb:   Farbänderung mit r g b
     xy:   Farbänderung mit x sowie y
     hue:   Farbänderung mit hue und saturation

Warum diese Einteilung in "hex", "rgb", "xy" sowie "hue"? -> Zigbee2MQTT unterstützt das Übermitteln aller dieser Werte, allerdings unterscheiden sich hier die Geräte. Manche "verstehen" nur z.B. Hex-Farbänderungen, andere halt nur eine Farbänderung mit rgb-Werten. -> Aus diesem Grund muss an dieser Stelle probiert werden mit welchem der 4 Templates sich die Farbveränderung des Gerätes steuern lässt!

HINWEIS: Templates für Farbänderungen mithilfe von XY- sowie HUE-Werten wurden bis heute nicht angelegt!

Beispiel eines dimmbaren Tradfri-Leuchtmittels

defmod IKEA_Bulb2 MQTT2_DEVICE
attr IKEA_Bulb2 IODev MQTT2_FHEM_Server
attr IKEA_Bulb2 icon light_control
attr IKEA_Bulb2 devStateIcon {zigbee2mqtt_devStateIcon255($name)}
attr IKEA_Bulb2 readingList zigbee_pi:zigbee2mqtt/0x90fd9ffffe0bcd51:.* { json2nameValue($EVENT) }
attr IKEA_Bulb2 setList on:noArg zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"ON"}\
    off:noArg zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"OFF"}\
    brightness:colorpicker,BRI,0,15,255 zigbee2mqtt/0x90fd9ffffe0bcd51/set {"state":"on","$EVTPART0":"$EVTPART1"}
attr IKEA_Bulb2 webCmd toggle:on:off:brightness
attr IKEA_Bulb2 model L_02a_zigbee2mqtt_bulb

Kann man auch die Farbtemperatur einstellen, wird die setList wie folgt erweitert oder das entsprechende template angewendet:

...
color_temp:colorpicker,CT,250,1,454 zigbee2mqtt/0x90fd9ffffe0bcd51/set {"$EVTPART0":"$EVTPART1"}

Die templates sind dabei in der Regel so gestaltet, dass eventuell mehr Optionen in FHEMWEB erscheinen, als tatsächlich vorhanden oder erwünscht sind. Da sich obige einfarbige dimmbare Lampe durch Klicken auf das devStateIcon schalten lässt, ist für die vollständige Ansteuerung bereits dieses webCmd hinreichend:

attr IKEA_Bulb2 webCmd brightness

Temp/Hum. Sensor

tbd

Motion Sensor

Als MQTT-Server wird hier mosquitto verwendet, als IO-Device wird daher ein MQTT2_CLIENT-Gerät definiert:

defmod mqtt2_client MQTT2_CLIENT 192.168.2.4:1883
attr mqtt2_client autocreate 1
attr mqtt2_client rawEvents zigbee2mqtt/GB_Bewegungsmelder:.*
attr mqtt2_client room test
attr mqtt2_client subscriptions #

Das eigentliche Device sieht dann so aus:

defmod GB_Bewegungsmelder_MQTT2 MQTT2_DEVICE zigbee_158d0001f9d030
attr GB_Bewegungsmelder_MQTT2 IODev mqtt2_client
attr GB_Bewegungsmelder_MQTT2 devStateIcon motion:motion_detector@red off:motion_detector@green no_motion:motion_detector@green
attr GB_Bewegungsmelder_MQTT2 icon motion_detector@blue
attr GB_Bewegungsmelder_MQTT2 readingList mqtt2client:zigbee2mqtt/GB_Bewegungsmelder:.* { json2nameValue($EVENT) }
attr GB_Bewegungsmelder_MQTT2 room MQTT2_DEVICE
attr GB_Bewegungsmelder_MQTT2 stateFormat {\
if(ReadingsVal("$name","occupancy",0) eq "true") {\
	sprintf("motion");;\
	} else {\
	sprintf("no_motion");;	\
	}\
}

Anlegen von Zigbee2MQTT-Gruppen in FHEM

Die nachfolgende Darstellung ist vorläufig!

Bevor man eine Gruppe mithilfe von Zigbee2MQTT anlegen kann, sollte man sicherstellen, dass man über die aktuelleste Version von Zigbee2MQTT verfügt (min. vom 15. Februar 2019). Außerdem sollte auch der Koordinator (zumeist CC2531) die aktuellste Firmware besitzen (min. vom 15. Februar 2019). Falls ein flashen des Koordinators mit der neusten Firmware erfolgen soll, ist darauf zu achten, dass nach einem flashen alle Geräte neu angelernt werden müssen! (Hinweise zum flashen ohne erneutem anlernen sind hier zu finden: https://www.zigbee2mqtt.io/information/flashing_without_re-pairing.html)

Erstellen einer Zigbee2MQTT-Gruppe

Bevor das Ganze in FHEM funktioniert, muss eine Gruppe in der "configuration.yaml" angelegt werden, dieser Vorgang ist auf folgender Seite beschrieben: https://www.zigbee2mqtt.io/information/groups.html Wenn die Geräte anschließend über den FHEM MQTT2-Server der Gruppe hinzugefügen werden sollen, kann dies mit folgendem Befehl erfolgen:

set <MQTT2-Server> publish zigbee2mqtt/bridge/group/<Zigbee2MQTT Friendly-Gruppenname>/add <Zigbee2MQTT Friendly-Gerätename>

Beispiel:

set MQTT2_FHEM_Server publish zigbee2mqtt/bridge/group/Wohnzimmer/add Stehlampe

Dieser Befehl kann so oft verwendet werden, wie man Geräte zu einer Gruppe hinzufügen möchte.

Zum Entfernen eines Gerätes aus einer Gruppe kann folgender Befehl verwendet werden:

set <MQTT2-Server> publish zigbee2mqtt/bridge/group/<Zigbee2MQTT Friendly-Gruppenname>/remove <Zigbee2MQTT Friendly-Gerätename>

Beispiel:

set MQTT2_FHEM_Server publish zigbee2mqtt/bridge/group/Wohnzimmer/remove Kuechenlampe

Anlegen der Gruppe in FHEM

Da Gruppen in Zigbee2MQTT aktuell keine Rückmeldung über ihren Status geben, wird auch beim einmaligen Schalten kein Gerät automatisch in FHEM angelegt. Aus diesem Grund muss dies mit folgendem Befehl noch manuell erfolgen:

defmod <FHEM NAME> MQTT2_DEVICE

Beispiel

defmod lichtWohnzimmer MQTT2_DEVICE

Anschließend wird auch für dieses Gerät wieder ein passendes template ausgewählt, als wäre es ein normales Zigbee2MQTT-Gerät. Im anschließenden Dialogfenster, welches sich nach dem Setzen des templates öffnet, müssen die folgenden Werte durch passende ersetzt werden:

BASE_TOPIC -> zigbee2mqtt
DEV_ID -> <Zigbee2MQTT Friendly-Gruppenname>

Danach sollte sich die Gruppe wie ein normales Zigbee2MQTT Gerät steuern lassen.