ControllerX und Homeassistant

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.

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.

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.

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:

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:

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:

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:

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:

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:

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:

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.

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 Pushnachricht:

- 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önen 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.