AqaraHub

This is an open-source Zigbee hub for Xiaomi Aqara devices, as pictured here. It aims to be a replacement to the Xiaomi Gateway that does not require communication to outside servers, and uses a saner communication option (e.g. MQTT).

Although this project was specifically written for Xiaomi Aqara devices, other Zigbee devices will very likely work too.

July 2018: MQTT Topics changed

To add support for devices that send other things than the standard "Report Attributes", for example the Aqara water leak sensor and smoke detector, the MQTT topic pattern has been changed. Documentation on the new format is available here.

Get in touch!

I've been writing this thing on my own, and it appears to solve my use-case fairly well, but I'd love to get feedback from others!

Some of the things I'd like to know:

• Is anyone else even interested in a project like this?
• Were others able to compile it ?
• Has anyone actually got it to run ?
• Is anyone missing specific functionality ?

So instead of only following or starring this project, just drop me a message at fw@hardijzer.nl too :)

Getting Started

At this point, reporting attributes received from the Xiaomi devices to MQTT appears to be working quite well. If this is all that you require, I encourage you to give it a shot. Support for sending things back, like turning the Smart Plug on or off, is still on the to-do list.

Libraries and tools used

This project uses a lot of C++14 features, so obviously a compiler supporting these is required. GCC 5 or later, Clang 3.4 or later, or Microsoft Visual Studio 2017 should fit the bill.

On top of that it makes heavy use of the Boost C++ Libraries, the Adobe Software Technology Lab Concurrency Libraries (hereafter "STLab-libraries"), Takatoshi Kondo's excellent mqtt_cpp library, and The Art of C++ / JSON libraries.

All dependencies except for Boost can be pulled in as git submodules:

git submodule update --init --recursive

There is no need to compile these libraries, as they are all header-only.

The Boost libraries should be available on most Linux distributions, likely named either boost-devel, boost-libs, or just boost.

Compiling using CMake

On my machine, I can compile using the following commands:

git submodule update --init --recursive
mkdir build
cd build
cmake ..
make

Afterwards a binary named AqaraHub should have appeared in the build folder.

Deployment

Prerequisites

To run AqaraHub, several things are needed:

• A CC2531 Zigbee USB dongle, like one of these
• A programmer to flash the CC2531, like one of these
• A cable from the standard double-row 2.54-spaced connector to the teeny-tiny connector on the CC2531, like one of these
• A functioning MQTT Server
• One or more Xiaomi Aqara devices

Flashing the Zigbee dongle

The Zigbee dongle should be running the Z-Stack firmware modified by Koenkk, available here. You can use CC-Tool from here or here to flash it to the dongle.

I've succesfully flashed my device using the following steps:

git clone https://github.com/dashesy/cc-tool.git
cd cc-tool
./configure
make
wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/CC2531/bin/CC2531ZNP-Prod_20190223.zip
unzip CC2531ZNP-Prod_20190223.zip

Next connect the programmer to the dongle. Note that there is a very small "1" on one side of the plug on the dongle, and a "10" on the other side. The cable should be plugged in to have the red wire on the side of the "1". Then connect the USB dongle to the computer, and finally plug in the programmer to the computer. I'm not entirely sure why, but any other order does not appear to work for me. Finally, instruct cc-tool to flash the firmware:

sudo ./cc-tool -e -w CC2531ZNP-Prod.hex

Note that I'm using sudo as otherwise cc-tool is unable to use libusb, for some reason. This is not the safest decision. If anyone knows the proper way to give this executable access to libusb, please let me know!

Finally disconnect both the dongle and the programmer from your computer, disconnect the debugging cable, and plug the dongle back in the computer. Once the green light turns off, The dongle should be ready to be used by AqaraHub.

Running AqaraHub

Running AqaraHub is relatively simple. Simply instruct it to which serial port the USB dongle is using, the MQTT server to connect to, and the topic under which to publish all received information:

./AqaraHub --port /dev/ttyACM0 --mqtt mqtt://ArchServer/ --topic AqaraHub

Pairing Xiaomi zigbee Devices

At first start the CC2531 does not know your Xiaomi zigbee devices. You have to pair them by activating pairing mode manually. Over MQTT send a number, e.g. 60, to the AqaraHub/control/permitjoin topic:

mosquitto_pub -h ArchServer -t AqaraHub/control/permitjoin -m 60

AqaraHub should respond on the AqaraHub/report/permitjoin topic, with the same number, and at that point you have 60 seconds (depending on what you sent) to pair devices. Once the 60 seconds elapse, you'll get another message to AqaraHub/report/permitjoin with the content "0".

Pairing a temperature or door sensor should be done by sticking a paperclip into the little hole, and keeping it pressed until a LED starts blinking blue. Pairing information is being kept in the CC2531 stick.

Contributing

Any and all help would be greatly appreciated. Feel free to make pull requests or add issues through Github.

Code formatting wise, I try to stick to the Google C++ Style Guide. Don't feel obligated to make pull requests perfect, most of the formatting can be solved with clang-format, and we can always clean it up together...

Contributors

Thanks goes to these wonderful people (emoji key):

Frans-Willem Hardijzer 💻 📖	HW 💻	Alexander 💻	Christian Burckas 📖	Gabor9 📖 🐛	digitallez 🐛	mclei-asw 🐛 🤔
Adam Baxter 🚇 💻	michlv 💻	Eriks Dobelis 💻	Guillermo Miravalles 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

If you contributed in any way, but I've forgotten to add you to this list, please shoot me an e-mail!

License

AqaraHub is licensed under the GNU General Public License, version v3.0. See LICENSE-gpl-3.0.txt or the online version for more information.

Acknowledgments

I'd like to thank the zigbee-shepherd project both as inspiration as well as being a very good example on ZNP programming. It's debug output has helped me immensely in actually getting started programming the ZNP dongle.