ControllerX ist ein mächtiges und sehr gut dokumentiertes Tool, um Zigbee-Eingabegeräte in Homeassistant zu verwenden. ControllerX greift dabei auf die Funktionalitäten von Appdaemon zurück und erlaubt es nahezu jedes auf dem Markt verfügbare Eingabegerät nahtlos mit Homeassistant zu verwenden.

Vorraussetzungen zur Nutzung

AppDaemon

AppDaemon ist essentiell für die Nutzung von ControllerX und steht als eigenes Add-On im Supervisor von Homeassistant zur Installation bereit. Ist die Installation erfolgt, muss das Add-On manuell gestartet werden.

Screenshot vom Appdaemon Add-on

HACS

HACS ist ein Community-Appstore zur Erweiterung von Homeassistants Basisfunktionen.

ControllerX

ControllerX kann über HACS installiert und aktualisiert werden. Es wird unter dem Menüpunkt Automation gelistet und mit einem Klick auf Install installiert werden.

Screenshot von ControllerX in HACS

Zigbee-Hub mit Homeassistant Integration

Ein Zigbee-Hub dient als Router für alle Zigbee-Geräte. Über diese Hardware wird jedes Gerät eingebunden und in Homeassistant als Entity zur Verfügung gestellt. Als Universalhub für alle Hersteller spreche ich eine klare Empfehlung für den Conbee 2 von Dresden Elektronik aus. Der Conbee 2 kann zusammen mit dem offiziellen deCONZ Add-On genutzt werden und stellt zum Pairing der Geräte eine Web UI namens Phoscon zur Verfügung. Über diese kann im Browser ein neues Gerät eingebunden, benannt und gruppiert werden.

Exkurs: Zigbee Events und der Event Bus

Im Herzen von Homeassistant schlägt der Event Bus. Jede Änderung eines States wird dort in einem fortlaufenden Stream dargestellt und im Recorder festgehalten. Nutzt man die deCONZ-Integration, kann explizit nach Events von Zigbee-Geräten gefiltert werden. Dazu muss unter DEVELOPER TOOLS > EVENTS in der Sektion Listen to Events im Eingabefeld deconz_event eingegeben werden und auf den Button Start listening geklickt werden. Für andere Integrationen als deCONZ sei auf die Docs von ControllerX verwiesen.

Hello Friend

Drückt man nun einen Knopf an einem Zigbee-Eingabegerät, wie bspw. einem Aqara Button, erscheint - exemplarisch - eine Ausgabe im JSON-Format:

{
    "event_type": "deconz_event",
    "data": {
        "id": "button_wohnzimmer",
        "unique_id": "00:15:8d:00:01:e8:7f:26",
        "event": 1002,
        "device_id": "6f7383674eed4fb3b0aabca03e9a32e1"
    },
    "origin": "LOCAL",
    "time_fired": "2021-07-08T19:23:01.451187+00:00",
    "context": {
        "id": "89f14979b86490040adef6588e0789d8",
        "parent_id": null,
        "user_id": null
    }
}

Interessant für die Automationen sind die Daten im Objekt data: {}. Zur Erläuterung:

Key Funktion
id Ist der Name des Zigbee-Geräts, den die Deconz-Integration an Homeassistant durchreicht.
unique_id Ist die eindeutige Hardware-Adresse des Zigbee-Geräts.
event Der Event-Code entspricht einer bestimmten Aktion des Geräts, bspw. einem einfach Klick oder dem Gedrückthalten eines Tasters.
device_id Eine interne ID, die Homeassistant führt und automatisch dem Gerät zuweist. Im Gegensatz zur unique_id ist sie nicht persistent und kann wechseln, wenn das Gerät nach einem Unpairing neu verbunden wird.

Die id und unique_id sind essentiell für die Nutzung des Geräts mit ControllerX. Mit einem der beiden Parameter kann jedes Gerät eindeutig ermittelt und der gesendete event_code zugeordnet werden. Dieser kann dann als Trigger für Aktionen benutzt werden. Per default verwendet ControllerX die id.

Controller einbinden

Nach der Installation von AppDaemon ist unter ./config/appdaemon/apps/ eine Datei namens apps.yaml verfügbar, in der alle Eingabegeräte konfiguriert werden.

Als einfaches Beispiel sei hier die Konfiguration für die Fernbedienung E1766 meines IKEA Fyrtur Rollos dargestellt, dem zuvor schon ein Post gewidmet wurde:

rollo_schlafzimmer:
  module: controllerx
  class: E1766CoverController
  controller: tradfri_open_close_remote
  integration: deconz
  cover: cover.rollo_schlafzimmer

Die einzelnen Konfigurationsparameter im Detail:

Parameter Funktion
rollo_schlafzimmer Ein eindeutiger Name, der vergeben werden muss.
module Weist AppDaemon an, dass ControllerX verwendet werden soll.
class ControllerX hat unterschiedliche Standardanweisungen für jeden Controller parat. Der E1766-Controller kann bspw. auch zur Steuerung eines Lichts oder eines Schalters verwendet werden.
controller Der Entity Name der Fernbedienung in Homeassistant.
integration Neben der deCONZ-Integration beherrscht ControllerX noch weitere Integrationen, wie Zigbee Home Automation (zha) oder Zigbee2MQTT (z2m)
cover Der Entity Name des Rollos in Homeassistant.

Eine große Stärke von ControllerX ist, dass jede vordefinierte Aktion überschrieben werden kann. Dabei wird unterschieden zwischen mapping und merge_mapping:

  • mapping: Überschreibt die Grundfunktionen des Controllers komplett. Nicht definierte Events werden ignoriert.
  • merge_mapping: Behält die Grundfunktionen und überschreibt nur bestimmte Events.

Beispiele aus meinen Automationen

Da es dem Menschen zu gerne an Phantasie mangelt, möchte ich ein paar Beispiele präsentieren, wie ich Zigbee-Eingabegeräte in meinem Alltag nutze. Alle Beispiele zur Nutzung von ControllerX erfolgen unter der Verwendung der deCONZ-Integration und müssen ggf. angepasst werden, wenn ZHA oder Z2M verwendet werden.

Hue Dimmer Switch

In jedem meiner Räume hängt eine Hue Dimmer Switch. Sämtliche Lichter eines Raumes sind über die Phoscon App gruppiert und erscheinen als eine einzige steuerbare Entity in Homeassistant. Ich nutze die Dimmschalter zum Einschalten und Dimmen der Lampen und habe jeweils den Einschalt- und den Ausschaltknopf mit einem merge_mapping angepasst. Geändert wurden die folgenden Event Codes:

Event Code Aktion
1000 Ein einfacher Click auf die I-Taste startet eine Szene, in der alle Leuchten mit voller Leuchtstärke erstrahlen.
1001 Das Gedrückthalten der I-Taste startet eine Szene, in der alle Leuchten gedimmt erstrahlen.
4001 Das Gedrückthalten der O-Taste startet ein Script, das ausgeführt wird wenn ich das Haus verlasse und alle Lichter und Media Player ausschaltet.

Der entsprechende Eintrag in der .config/appdaemon/apps/apps.yaml sieht dann folgendermaßen aus:

hue_dimmer_flur:
  module: controllerx
  class: HueDimmerController
  controller: flur_dimmschalter
  integration: deconz
  light: light.deconz_licht_flur
  merge_mapping:
    1000: # Click I
      - scene: scene.flur_hell
    1001: # Hold I
      - scene: scene.flur_gedimmt
    4001: # Hold O
      - service: script.turn_on
        entity_id: script.leaving_home

Aqara Buttons

Für kleines Geld können simple Buttons von Aqara erstanden werden. Diese gibt es jedoch in zwei unterschiedlichen Varianten:

Variante Eigenschaften
WXKG11LM lumi.sensor_switch.aq2 4 unterschiedliche Aktionen verfügbar
WXKG11LM lumi.remote.b1acn01 3 Unterschiedliche Aktionen verfügbar

In diesem Beispiel kommt die erste Variante mit 4 möglichen Aktionen zum Tragen und es werden alle Standardfunktion des Buttons mittels mapping überschrieben. Das zugewiesene Licht light.schlafzimmer_decke ist also nur ein Alibi-Eintrag, denn ein Licht wird in diesem Fall nicht direkt gesteuert.

button_schlafzimmer:
  module: controllerx
  class: WXKG11LMSensorSwitchLightController
  controller: button_schlafzimmer
  integration: deconz
  light: light.schlafzimmer_decke
  mapping:
    1002: # 1 Click
      - service: switch.toggle
        entity_id: switch.scene_schlafzimmer_nachtlicht
    1004: # 2 Clicks
      - service: switch.toggle
        entity_id: switch.schlafzimmer_steckdose_cast
    1005: # 3 Clicks
      - service: script.turn_on
        entity_id: script.schlafzimmer_readytosleep
    1006: # 4 Clicks
      - service: script.turn_on
        entity_id: script.sz_soundtouch_aus_1h

Das neu festgelegte Mapping der Events führt folgende Aktionen aus:

Event Code Aktion
1002 Ein einfacher Klick wechselt über einen Template Switch zwischen meiner Nachtbeleuchtung oder ganz ausgeschaltetem Licht im Schlafzimmer.
1004 Ein doppelter Klick schaltet ebenfalls einen Template Switch für eine Steckdose, an der ein Monitor, ein Chromecast und ein paar Boxen hängen.
1005 Ein dreifacher Klick startet ein Script, das den Schlafmodus einleitet. Das Rollo wird heruntergefahen, alle Mediaplayer ausgeschaltet und das Licht geht nicht mehr automatisch über den Bewegungssensor an.
1006 Ein vierfacher Klick startet einen Timer von 1h für meine Schlafzimmeranlage. Ist der Timer abgelaufen schaltet sich die Box automatisch aus.

Aqara Magic Cube

Der Magic Cube ist ein merkwürdiges Gerät. Es hat so viel Funktionen, dass ich jedes mal nach fünf Minuten vergesse, womit ich sie belegt habe. Trotzdem lässt er sich wunderbar mit ControllerX verwenden. In diesem Fall wird aber nicht ein Event ausgelesen, sondern eine bereits interpretierte Geste (gesture), wie bspw. das Schütteln, Drehen oder das Schieben des Würfels verwendet. Den Magic Cube nutze ich für meine Lichter im Wohnzimmer und zur Steuerung meines Fernsehers und AV-Receivers.

Die Gestures und gewählten Aktionen im Detail:

Gesture Code Gesture Aktion
1 Schütteln Schaltet den Fernseher ein
3 90° Flip Aktiviert Szene
4 180° Flip Aktiviert weitere Szene
6 Doppelt tippen auf Oberfläche Schaltet den Eingang des AV-Receivers auf HDMI2
7 Rotation Rechts Erhöht die Lautstärke des AV-Receivers
8 Rotation Links Reduziert die Lautstärke des AV-Receivers

Der zugehörige Eintrag in der .config/appdaemon/apps/apps.yaml lautet:

magiccube_wohnzimmer:
  module: controllerx
  class: MFKZQ01LMLightController
  controller: zauberwurfel_wohnzimmer
  integration:
    name: deconz
    type: gesture
  light: light.wohzimmer_esstisch
  mapping:
    1: # Shake
      - service: media_player.toggle
        entity_id: media_player.sony_bravia
    3: # Flip 90°
      - scene: scene.wohnzimmer_fernsehen
    4: # Flip 180°
      - scene: scene.wohnzimmer_chill
    6: # Double Tap on Surface
      - service: media_player.select_source
        data:
          entity_id: media_player.av_receiver
          source: "HDMI2"
    7: # Rotate Right
      - service: media_player.volume_up
        entity_id: media_player.av_receiver
    8: # Rotate Left
      - service: media_player.volume_down
        entity_id: media_player.av_receiver

Sonderfall: Tradfri Shortcut Button

IKEA hat vor kurzem sein Sortiment an Zigbee-Geräten um einen simplen Shortcut Button (E1812) erweitert. Dieser sendet folgende Event Codes auf Homeassistants Event Bus:

Event Code Aktion
1001 Button wird gedrückt und gehalten
1002 Button wird einmal gedrückt
1003 Button wird nach dem gedrückt halten wieder losgelassen

Ich nutze den Button für meine Waschmaschine. Meine Waschmaschine hat gefühlt 32 Millionen unterschiedliche Waschprogramme. Da ich aber ein einfacher Mann bin, verwende ich immer nur 2 davon: 40°-Wäsche uund 60°-Wäsche. Beide Waschvorgänge dauern unterschiedlich lange.

Waschvorgang Dauer
40°-Wäsche 01:58:00
60°-Wäsche 01:48:00

Ich habe meinen Button direkt neben der Waschmaschine an die Wand geklebt und kann mit einem einfachen Click einen Timer für die 40°-Wäsche in Homeassistant starten. Wird der Button gedrückt gehalten, startet der Timer für die 60°-Wäsche. Ist einer der beiden Timer abgelaufen, bekomme ich eine Pushnachricht auf mein iPhone.

Dafür werden in Homeassistant zwei Timer benötigt:

timer:
  laundry_40:
    duration: '01:48:00'
  laundry_60:
    duration: '01:58:00'

Des weiteren die Automation für die Benachrichtigung per Push-Nachricht:

- alias: Notify Waschmaschine fertig
  trigger:
    - platform: event
      event_type: timer.finished
      event_data:
        entity_id: timer.laundry_40
    - platform: event
      event_type: timer.finished
      event_data:
        entity_id: timer.laundry_60        
  action:
    - service: notify.mobile_app_mizar
      data:
        title: "Waschmaschine 🧺"
        message: "Die Waschmaschine ist fertig"
        data:
          channel: Info
          tag: "PUSH_WASCHMASCHINE_FERTIG"

Und im finalen Schritt muss eine Konfiguration in .config/appdaemon/apps/apps.yaml eingetragen werden. Der Tradfri Shortcut Button ist unter den Zigbee-Geräten in Verbindung mit der Phoscon-App ein Sonderfall. Er wird in der App nicht aufgeführt. Daher besteht keine Möglichkeit den Namen und somit seine id zu ändern. Besitzt man mehrere Shortcut Buttons, senden sie also alle unter der gleichen ID tradfri_shortcut_button und können somit von ControllerX nicht auseinandergehalten werden. Ich habe daraufhin den Entwickler von ControllerX xaviml angeschrieben und er hat mit dem Release 4.14.0 eine Möglichkeit geschaffen die unterschiedlichen Shortcut Buttons über einen weiteren Identifier zu unterscheiden. Dieser Identifier ist die hardware-basierte unique_id, die einmalig für jeden Button ist:

tradfri_button_laundry:
  module: controllerx
  class: E1812LightController
  controller: "58:8e:81:ff:fe:3f:05:fc"
  integration: 
    name: deconz
    listen_to: unique_id
  light: light.wohnzimmer_couch
  mapping:
    1002: # Click
      - service: timer.start
        data:
          entity_id: timer.laundry_40
      - service: timer.cancel
        data:
          entity_id: timer.laundry_60
    1001: # Hold
      - service: timer.start
        data:
          entity_id: timer.laundry_60
      - service: timer.cancel
        data:
          entity_id: timer.laundry_40

Da ich manchmal schusselig bin und dazu tendiere den falschen Timer zu starten, habe ich für jeden Timer noch die Funktion timer.cancel eingebaut, der bei einer Korrekturangabe, den falschen Timer wieder beendet und den richtigen startet.

Viel Spaß beim experimentieren mit ControllerX.