Controlling Zigbee devices with MQTT

2019/01/06 mqtt iot zigbee

This is a short tutorial on connecting a zigbee device (an Aqara cube) to an MQTT server, so you can control your zigbee devices from the network.

If you’re anything like me, you’re probably a sucker for IoT devices. For a long time, I’ve been using WiFi-enabled lights, and Amazon dash buttons to control them. To keep these (cheap Chinese) internet enabled devices away from your network and their respective cloud services, you’ll probably want to set up a dedicated network in your router (more on this on a future post, maybe). Another disadvantage of WiFi devices is that they’re relatively power hungry.

A popular alternative is using ZigBee for communication. It is a dedicated protocol similar to bluetooth (BLE), with lower power requirements and bitrate.

Take the (super cute) aqara cube as an example. It is a small cube that detects rotation on all of its axes, and tapping events. Here’s a video:

To connect to zigbee devices you will need a zigbee enabled gateway (a.k.a. hub), which connects to your WiFi network and your zigbee devices. Once again, this means adding an internet-enabled device to your home, and probably a couple of cloud services.

As an alternative, you can set up your own zigbee gateway, and control it to your home automation platform of choice (e.g. home assistant). We will cover how to set up a zigbee2mqtt gateway that is also connected to an MQTT server, so you can use MQTT to control your devices and get notifications.

What you need:

You will need to flash your sniffer. For that, you only need to follow the instructions from the zigbee2mqtt documentation.

Once you’re done flashing, you’re ready to set up the zigbee2mqtt server. For convenience, I wrote a simple docker-compose to deploy a zigbee2mqtt server and a test mosquitto server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
version: '2.1'
services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt 
    restart: always
    volumes:
      - ./z2m-data/:/app/data/
    devices:
      - "/dev/ttyACM0"
    networks:
        - hass
  mqtt:
    image: eclipse-mosquitto
    ports:
       - 1883:1883
       - 9001:9001 
    networks:
        - hass
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
networks:
  hass:
    driver: overlay

You can test your installation with:

1
2
3
4
5
6
❯ mosquitto_sub -h localhost -p 1883 -t 'zigbee2mqtt/#'
online
{"battery":17,"voltage":2925,"linkquality":149,"action":"rotate_right","angle":12.8}
{"battery":17,"voltage":2925,"linkquality":141,"action":"slide","side":2}
{"battery":17,"voltage":2925,"linkquality":120}
{"battery":17,"voltage":2925,"linkquality":141,"action":"wakeup"}

zigbee2mqtt supports the following events for the aqara cube: shake, wakeup, fall, tap, slide, flip180, flip90, rotate_left and rotate_right. Every event has additional information, such as the sides involved, or the degrees turned.

Now you are ready to set up home assistant support in zigbee2mqtt following this guide.