Aqara cubes zijn een fantastische manier om verschillende apparaten in een slim huis aan en uit te schakelen. Ze met Home Assistant laten werken is echter niet vanzelfsprekend … Hier lees je hoe ik zo’n schattige kubus aan Home Assistant koppelde om mijn keukenverlichting te bedienen.

Elk huis of appartement heeft waarschijnlijk wel enkele dingen die je na een tijdje beginnen te ergeren. In ons appartement is dat de plaats van de lichtschakelaar in de keuken. Je gaat de keuken binnen … je kunt er niet bij … je verlaat de keuken en beseft dat het licht nog aan is … dan moet je door de keuken naar de schakelaar en in het donker terug, … Na enkele tientallen keren wordt dat vervelend. Als proof-of-concept plaatste ik al een Sonoff Mini (met tasmota-firmware) achter die schakelaar, zodat ik het licht met mijn telefoon kan bedienen. Nu dat werkt, is het tijd voor een fysieke schakelaar op een handigere plaats. Daarom besloot ik Home Assistant uit te breiden met een apparaat waarmee ik de keukenverlichting en andere slimme lampen in het hele appartement kan bedienen. Aqara cubes zijn kleine kubussen waarop je kunt tikken en die je kunt draaien, schudden, kantelen, … om verschillende apparaten te bedienen: perfect voor mijn idee. Ze vereisen wel een extra hub, en ik wil geen bijkomende slimme hub. Mijn Raspberry Pi moet als centrale hub voor alle apparaten fungeren … Dat bleek gemakkelijker gezegd dan gedaan!

Aqara cubes (en andere Aqara-sensoren, schakelaars, …) communiceren via het Zigbee-protocol met een hub. Dat is een erg efficiënt protocol voor apparaten op batterijen (vergeleken met wifi), maar je hebt een hub nodig of moet die beperking omzeilen … Ik koos voor dat laatste en breidde mijn Raspberry Pi met Home Assistant uit met een Zigbee-antenne.
Home Assistant kan helaas niet rechtstreeks met Zigbee-apparaten communiceren. Daarom moest de standaardfirmware op de Zigbee-dongle worden vervangen door de Z-Stack-firmware. In combinatie met Zigbee2MQTT kunnen Zigbee-apparaten koppelen met de Raspberry Pi en Zigbee-antenne. Zigbee2MQTT vangt de communicatie op, vertaalt ze en stuurt ze door naar een MQTT-broker … waar Home Assistant naar kan luisteren.

Dit is nogal abstract en moeilijk te bevatten, dus tekende ik een overzicht van hoe alles samenhangt.

Overzicht van de verbindingen tussen de verschillende software en apparaten

Update 27/03/2021: Onlangs voegde ik enkele Aqara-sensoren toe (temperatuur, luchtvochtigheid en luchtdruk), die via Zigbee2MQTT en de hier voorbereide stick verbinding maken met Home Assistant. Meer details vind je in deze post.

Update 03/12/2020: Deze post werd geschreven voor Home Assistant 0.92.3. Omdat ik onlangs overstapte naar versie 0.118.4, kan ik bevestigen dat alles nog actueel is, behalve light.toggle in een van de automatiseringen: daarmee worden niet langer alle lampen geschakeld en moet elk apparaat afzonderlijk worden opgegeven. Dit gedeelte werd bijgewerkt, maar verschilt voor elke opstelling. Merk ook op dat je MQTT-apparaten nu via gebruiksvriendelijke opties in de interface kunt configureren.

Onderdelenlijst

Hiervoor kocht ik enkele dingen op Amazon:

  • Een Arduino Uno van een ander merk, met USB-kabel (USB-A, de oude, grote aansluiting)
  • Een Zigbee-dongle op basis van de CC2531-chip
  • Een Aqara Cube

Verder heb je enkele kabels nodig om de Arduino met de Zigbee-stick te verbinden. Afhankelijk van de gekozen aanpak heb je mogelijk een soldeerbout en soldeertin, krimpkous, enkele pinheaders en connectoren voor de kabels nodig.

Omdat de Zigbee-dongle een kale printplaat is, printte ik een behuizing in 3D die hansaya voor dit type dongle ontwierp. Je vindt ze op Thingiverse. Hieronder zie je alle onderdelen die ik gebruikte.

Alle benodigde onderdelen, behalve de Raspberry Pi met HA, op één foto

Aan de softwarekant heb je behoorlijk wat pakketten nodig:

Tot slot moeten Home Assistant en de Mosquitto MQTT Broker op een apparaat draaien en heb je enkele slimme schakelaars en/of lampen nodig om aan en uit te zetten.

Opmerking: De meeste stappen dienen om de Zigbee2MQTT-firmware op een courante Zigbee-antenne met de CC2531-chip te krijgen. Er bestaan antennes waarop deze firmware vooraf is geïnstalleerd en die maar enkele euro’s meer kosten. Wil je dus gewoon alles aan de praat krijgen, kies dan zo’n stick en ga meteen naar stap 4.

Stap 0: test alles

Test het apparaat met de standaardconfiguratie voordat je met firmware begint. Zodra je alternatieve firmware flasht, zeker wanneer je daarvoor draden rechtstreeks aan pinnen soldeert, vervalt je garantie. Controleer of de Arduino en Zigbee-stick worden herkend wanneer je ze op een USB-poort van je computer aansluit.

Stap 1: bereid de Arduino voor

Installeer eerst de Arduino IDE. Daarmee upload je de CCLoader-firmware naar de Arduino. Zodra de Arduino IDE is geïnstalleerd, sluit je de Arduino UNO aan en wacht je tot de stuurprogramma’s geïnstalleerd zijn. Haal vervolgens de CCLoader-code van GitHub, pak hem uit en open Arduino\CCLoader\CCLoader.ino in de Arduino IDE. Selecteer onder Tools het juiste type Arduino en de juiste poort, en klik op de uploadknop om de CCLoader-code te compileren en de firmware naar de Arduino te uploaden.

Stap 2: verbind de Arduino met Zigbee

De Arduino wordt gebruikt om nieuwe firmware naar de Zigbee-antenne te flashen. Daarvoor moeten vier kabels met de debugpinnen van de Zigbee-antenne worden verbonden. De Zigbee2MQTT-documentatie bevat veel informatie over hoe dat kan. Omdat ik de stick later niet opnieuw hoef te programmeren, boog ik de debugpinnen op de dongle om er gemakkelijk bij te kunnen. Ik soldeerde een kabel aan elke vereiste pin en aan het andere uiteinde een standaard-headerpin die in de Arduino past. Door de pinnen te buigen en er soldeertin op aan te brengen, worden ze waarschijnlijk onbruikbaar voor andere toepassingen. Deze dongles zijn echter zo goedkoop dat een tweede exemplaar met standaardfirmware mocht dat ooit nodig zijn (onwaarschijnlijk), geen grote uitgave is.

Debugpinnen op de Zigbee-dongle met aangesloten draden Zigbee-dongle met aangesloten kabels

Stap 3: bereid de MQTT-firmware voor en flash de Zigbee-dongle

Voor dit gedeelte is de Zigbee2MQTT-documentatie uitstekend. Het enige waarmee ik moeite had, was binutils aan de praat krijgen. Cygwin installeren en het binutils-pakket aan de installatie toevoegen, bood de oplossing. Je kunt ook de verwerkte firmware die ik gebruikte hier downloaden.

Vervolgens kun je die firmware met CCLoader naar de Zigbee-dongle flashen. Dat gebeurt met één opdracht, zoals hieronder.

CCLoader_x86_64.exe [Number of the COM port] CC2531ZNP-Prod_sepro.bin 0

Zorg dat er tijdens dit proces geen andere software draait die met de Arduino kan communiceren. Daar hoort ook de Arduino IDE bij! Ik verspilde een halfuur aan het zoeken naar fouten voor ik dat besefte. Nadat ik de IDE sloot en CCLoader uitvoerde, kreeg ik eindelijk het onderstaande scherm: succes! Merk ook op dat wanneer je de Zigbee-dongle met vier draden verbindt, hij tijdens het flashen via zijn USB-poort van stroom moet worden voorzien. Zorg dus dat hij is aangesloten.

De firmware werd met succes naar de stick geflasht!

Je kunt controleren of het flashen van de Z-Stack-firmware gelukt is door Apparaatbeheer (Windows) te openen. De Zigbee-dongle moet nu als USB Serial Device verschijnen.

De nieuwe firmware werkt: het apparaat wordt nu herkend als USB Serial Device

Stap 4: Mosquitto en Zigbee2MQTT installeren

Sluit eerst de Zigbee-dongle met de nieuwe firmware aan op het apparaat waarop Home Assistant draait. Meld je vervolgens op dat apparaat aan, want we moeten enkele zaken installeren en configureren. Eerst installeren we de Mosquitto MQTT- broker, het centrale schakelbord voor MQTT-apparaten. Alle apparaten sturen hun status naar de MQTT- broker, die de informatie doorstuurt naar apparaten die moeten reageren. Belangrijker nog: dit is de software waarmee Home Assistant kan communiceren. Op een Raspberry Pi installeer je dit met slechts enkele opdrachten.

sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl status mosquitto

Als dit lukt, draait de MQTT-broker nu op je Raspberry Pi. Vervolgens is Zigbee2MQTT aan de beurt. Dat is een Node.js- applicatie, dus eerst moeten zowel Node als npm worden geïnstalleerd. Hiervoor verwijs ik naar de officiële installatiehandleiding van Zigbee2MQTT: https://www.zigbee2mqtt.io/getting_started/running_zigbee2mqtt.html. Mijn enige aanpassing was alles installeren als gebruiker homeassistant, omdat ik Home Assistant daarmee uitvoer (en niet met de standaardgebruiker pi). Vervang gewoon het woord pi door de gebruikersnaam die je nodig hebt.

Nadat ik alle stappen had uitgevoerd en alle apparaten had gekoppeld (in mijn geval slechts één), zag mijn configuratiebestand in /opt/zigbee2mqtt/data/configuration.yaml er als volgt uit. Ik schakelde ondersteuning voor Home Assistant in en voorkwam dat nieuwe apparaten konden koppelen (doe dit pas nadat alle apparaten gekoppeld zijn). Omdat Mosquitto op hetzelfde apparaat draait, staat de MQTT-server op localhost.

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://localhost'
serial:
  port: /dev/ttyACM0
devices:
  '0x00158d0003495e50':
    friendly_name: 'Aqara Cube'

Eén onderdeel neem ik wel over uit de officiële documentatie: de opdrachten hieronder. Daarmee start en stop je de service en bekijk je de logboeken. Dat laatste is erg handig bij het debuggen, omdat je precies ziet wat apparaten verzenden (en het is ook de opdracht die ik steeds vergeet).

# Stopping Zigbee2MQTT
sudo systemctl stop zigbee2mqtt

# Starting Zigbee2MQTT
sudo systemctl start zigbee2mqtt

# View the log of Zigbee2MQTT
sudo journalctl -u zigbee2mqtt.service -f

Wanneer Zigbee2MQTT draait, zie je alle verbonden apparaten en de berichten die ze doorgeven.

Zigbee2MQTT ontvangt gegevens van de Aqara Cube

Nu alles werkt, kan de 3D-geprinte behuizing op de Zigbee-stick worden geklikt en kunnen we naar de laatste fase.

Zigbee-stick met 3D-geprinte behuizing

Stap 5: Home Assistant configureren

Tijd om alles samen te brengen en Home Assistant te configureren. We moeten enkele zaken toevoegen aan configuration.yaml (in /home/homeassistant/.homeassistant/). Home Assistant moet weten dat er een MQTT- broker is waarnaar het moet luisteren. Daarvoor voegen we deze regels toe aan configuration.yaml.

mqtt:
  discovery: true
  broker: localhost
  birth_message:
    topic: 'hass/status'
    payload: 'online'
  will_message:
    topic: 'hass/status'
    payload: 'offline'

Ik voegde ook een invoerlijst toe aan het configuratiebestand om met de Aqara Cube door kleuren te bladeren. Hiervoor kwam het volgende gedeelte in configuration.yaml:

input_select:
  color:
      initial: CadetBlue
      options:
        - CadetBlue
        - CornflowerBlue
        - DarkSlateBlue
        - DarkOrchid
        - DeepPink
        - FireBrick
        - OrangeRed
        - DarkOrange
        - Gold
        - GreenYellow
        - Green
        - LightSeaGreen

Ga nu in de Home Assistant-interface naar de configuratie, controleer of de configuratiebestanden nog geldig zijn en herstart HA. Dan kunnen we eindelijk automatiseringen maken die van de kubus een fysieke schakelaar voor mijn keukenverlichting maken. Open automations.yaml en voeg het onderstaande gedeelte toe.

- id: '1597674578966'
  alias: Cube Kitchen Light
  trigger:
    platform: mqtt
    topic: zigbee2mqtt/Aqara Cube
  condition:
    condition: template
    value_template: '{{ "flip90" == trigger.payload_json.action }}'
  action:
    entity_id: switch.sonoff
    service: switch.toggle

Deze automatisering gaat af telkens wanneer de kubus 90 graden wordt gekanteld. Ze schakelt gewoon de Sonoff Mini die tussen de voeding en de lamp zit. Bewaar het bestand, herlaad de scripts via het configuratiepaneel van HA en kantel de kubus.

Daarmee was mijn probleem met de keukenverlichting opgelost. De Aqara Cube kan met verschillende bewegingen echter nog meer apparaten bedienen. Ik heb nog een slimme lamp die ik graag wil bedienen: een ledstrip die indirect licht bij de tv geeft. Die verlichting gaat al automatisch aan en uit met de tv, maar het zou handig zijn om ze zonder de tv in te schakelen en door enkele favoriete kleuren te bladeren.

Om die lampen in te schakelen gebruiken we de volledige kantelbeweging, waarbij je de kubus optilt en op zijn bovenkant terugzet. De kubus als een draaiknop draaien is een andere ondersteunde beweging, die we gebruiken om de kleuren te bedienen. Dit vergde wat experimenteren met verschillende opties en veel googelen, maar de aanhouder wint: de volgende automatiseringen werkten.

- id: '1597674578967'
  alias: Cube TV Light
  trigger:
    platform: mqtt
    topic: zigbee2mqtt/Aqara Cube
  condition:
    condition: template
    value_template: '{{ "flip180" == trigger.payload_json.action }}'
  action:
  - service: light.toggle
    entity_id: light.tv_led_strip
  - service: light.toggle
    data: {}
    entity_id: light.blinkstick

- id: '1597674578968'
  alias: Cube - rotate CW
  trigger:
  - platform: mqtt
    topic: zigbee2mqtt/Aqara Cube
  condition:
  - condition: template
    value_template: '{{ trigger.payload_json.action in [''rotate_right''] }}'
  - condition: state
    entity_id: light.tv_led_strip
    state: 'on'
  action:
  - entity_id: input_select.color
    service: input_select.select_next
  - data_template:
      color_name: '{{ states(''input_select.color'') }}'
      entity_id: light.tv_led_strip
      transition: 0
    service: light.turn_on
  initial_state: 'on'

- id: '1597674578969'
  alias: Cube - rotate CCW
  trigger:
  - platform: mqtt
    topic: zigbee2mqtt/Aqara Cube
  condition:
  - condition: template
    value_template:  '{{ trigger.payload_json.action in [''rotate_left''] }}'
  - condition: state
    entity_id: light.tv_led_strip
    state: 'on'
  action:
  - entity_id: input_select.color
    service: input_select.select_previous
  - data_template:
      color_name: '{{ states(''input_select.color'') }}'
      entity_id: light.tv_led_strip
      transition: 0
    service: light.turn_on
  initial_state: 'on'

De eerste automatisering schakelt gewoon de lichtgroep (de ledstrip en de maanlamp uit een vorige post), net als bij de keukenverlichting. De andere twee zijn wat ingewikkelder. Wanneer de kubus als een draaiknop wordt gedraaid en de ledstrip aanstaat, wordt de vorige of volgende kleur gekozen (gedefinieerd in een invoerlijst in configuration.yaml) en vervolgens aan de ledstrip toegewezen.

Conclusie

Aanvankelijk leek dit een intimiderend project, maar Zigbee2MQTT heeft uitstekende documentatie die het proces veel eenvoudiger maakt dan je zou verwachten. Er zijn bovendien veel slimme apparaten die via het Zigbee-protocol communiceren (bijvoorbeeld de nieuwe slimme lampen van Ikea), zodat we met deze configuratie onze slimme apparaten verder kunnen uitbreiden. De kubus kan ook nog tikken, schudden en schuiven detecteren, waarmee je bijkomende apparaten zou kunnen bedienen …