OpenHAB instances with MQTT and Zigbee

In this post we will see how we can control items i.e. lights from one openHAB instance to another using a Zigbee button and MQTT.

openHAB recently passed into version 3 which comes with a complete revamp of the GUI and a massive rewriting of the backend code. There are mainly two protocols that we will be using in this guide.

Zigbee is a well established smart home protocol that gains more and more traction especially due to lower prices compared to competitive protocols i.e. ZWave and MQTT is also a well established lightweight IoT protocol that facilitates message and data exchange between IoT devices and systems.


The reason I use two openHAB instances is because I have been using openHAB v2 with a few dozen zwave devices and I did not want to upgrade just yet to openhab v3. At the same time I wanted to put some zigbee devices in the mix and I would like to try openHAB v3. Thankfully openHAB v3 offers the openHAB remote binding that allows two openHAB instances to be linked together.


  • Zigbee2MQTT, MQTT Broker and both openHAB systems installed
  • already openHAB v2 set up to control lights
  • installed the following in openHAB v3
    • Remote openHAB binding
    • MQTT Binding
    • JSONPath Transformation
    • RegEx transformation
  • For the purposes of this guide I have created the following in openHAB3
    • Item called Bathroom Lights, a dummy switch that will push this state to the real switch BathLight controlling the bathroom lights in openhab2
    • Thing that represents the MQTT Broker
    • Thing that represents the remote openHAB2 server
    • A generic MQTT Thing that represents the Aqara button

High Level Overview

I have an Aqara button working as a Zigbee device and it support single, double and long presses. Zigbee2MQTT translates those Zigbee messages to MQTT and sends them to an MQTT Broker. OpenHAB3 receives them through the MQTT binding and then at the same time updates a channel located in openHAB2 that controls the lights.

High level overview of openHAB, MQTT and zigbee integration
High Level Overview


You need to have the following 3 Things configured in openHAB3

Things configuration in openhab, zigbee device, mqtt broker and aqara button
openHAB3 Things configuration

The Generic MQTT Thing is the Aqara button (I probably should have changed the name to “Aqara Button”) and is associated to the MQTT broker

openhab menu for the zigbee Generic MQTT Thing
Aqara Button

In the Channels tab you need to create a channel for the button as follows (for Channel Type select Text Value)

Channel configuration of the zigbee device in openhab
Channel of the Aqara Button

The MQTT State topic is the one that the zigbee2mqtt publishes to the broker, you can pick this up using either the mqtt broker logs or the MQTT Explorer application. The Aqara button sends a JSON message in the following format

Single press:


Double press


We will remove all strings and keep only ‘single’ / ‘double’ via the JSONPATH transformation.

Then via the REGEX transformation we will replace single with ON and double with OFF. You need to place the transformation in the Incoming Value Transformation field as indicated in the picture above (make sure you select show advanced checkbox)


You then link the above channel to the dummy switch item Bathroom Lights

Channel configuration for the generic MQTT Thing
Link of the Aqara Button to the dummy openHAB3 switch item

Here is the Bathroom Lights item configuration

Link between the openhab thing channel and item
dummy openHAB3 switch item

Now you go to Things –> Openhab2 server (via the remote openhab binding) –> Channels tab and you select the channel from openhab2 that controls the lights. In this case BathLight

You link that to the dummy switch item as well

Remote openHAB version 2 channel linked to dummy openHAB version 3 Bathroom light switch
Remote openHAB2 channel linked to dummy openHAB3 Bathroomlight switch

It is very important that you change the profile for the openhab2 channel to FOLLOW

Profile of the remote openhab channel
Profile of remote openHAB2 channel

This is required because any update coming from MQTT will not be send as command to the openhab2 channel as explained here.

With the FOLLOW profile, any change on the dummy switch state will cause a change to the openhab2 channel as well.

In the end if you select the dummy item you should be able to see that it is linked to two channels, the incoming MQTT channel from the Aqara button and the outgoing channel towards the openhab2 server.

For all issues with the transformations and messages don’t forget to look at the openhab.log and event.log as they are providing useful insights as to what might have gone wrong

I did not write any rules for this integration which is really cool.

Note:  you can get rid of the JSONPATH transformations by checking this thread

Leave a Comment

Your email address will not be published. Required fields are marked *

This website uses cookies. By continuing to use this site, you accept our use of cookies.