openHAB and zigbee2mqtt Tutorial for Beginners

As stated in github, the availability works well on main powered devices and there are drawbacks on battery powered devices… They are not gettting pinged so that there is no battery drain. Therefore the implementation is, that if they don’t report for 25h, the payload on this topic is unavailable .

How I check for zigbee devices being online is to set up a DateTime item, which gets the current time when an update hits the broker for this item. after a timout of 12h, when no update is received after that, the device is marked as offline. It’s the same logic as in zigbee2mqtt, but only done in OH (of except for the main powered devices, which are getting pinged).

For your initial question, the battery powered devices send to the bridge an update depenent on their heart beat. This must not be directly after an Raspb reboot. But after some time, every device should have pinged a new update to the bridge. Pressing a button on the device normally directly sends an update

Thank you for the detailed answer. I found another error in my configuration.yaml “permit_join : true” . When changed to “false”, then after restarting the raspberry pi everything started working as you described. How do you think, that was the reason?

No, the reason the devices are shown as offline when you startup the Pi is as @NoneWhereTo described: battery powered devices only send out a heartbeat every so often (minutes/hours?, or when you press a button on the device), so when openHAB first starts it doesn’t know that the device is online until it receives the next heartbeat (which might be minutes/hours away).

permit_join shouldn’t affect this.

(As an aside, you can toggle between true and false for permit_join directly from openHAB if you’re interested)

1 Like

I am wondering as well. Did you figure this out?

are you still convinced? I am just about to switch to this solution and wanted make sure its still a sound way to do. :slight_smile:

I won’t speak for @vzorglub, but for me the incredible number of supported devices makes zigbee2mqtt incredibly useful. And if you’re already up to speed with MQTT it’s incredibly fast to incorporate into openHAB, whilst also maintaining a level of separation which can be useful at times.

thanks! indeed…
I was waiting for +6months that the Opple Swtich is added to the native zigbee binding.
In Z2M its there and many more. So I think I should finally move.

Yes absolutely

Still convinced, and with the more powerful coordinators that have come out since then it is better than ever. I am now using the zzh! stick and the range and response is orders of magnitude better than the CC2531

Is there step by step tutorial how to setup zigbee2mqtt (on cc 2531 stick ) on OH3 from clean OH3 to totally working solution, and then, for example, connect first xiaomi wall switch to stick.
now i have:

  • cc 2531 stick with firmware (seller say it zigbee2mqtt completable)
  • clean OpenHub3 on raspberry pi 4

Or maybe there another way, i find zigbee bunding inside OH3 it but it not work…

1 Like

I switched to the sonoff ZB bridge since a couple of weeks, flashed with Tasmota. For me this is a lot easier then playing with a separate raspberry pi and the range is much better (at least for me).

I created things for all my devices (in this case an Aqara temp & hum sensor)

UID: mqtt:topic:mosquitto:thp_ground
label: THP ground
thingTypeUID: mqtt:topic
configuration: {}
bridgeUID: mqtt:broker:mosquitto
location: Office
  - id: temperature
    channelTypeUID: mqtt:number
    label: temperature ground
    description: ""
      stateTopic: tele/sonoffbridge/THP_ground/SENSOR
      transformationPattern: REGEX:(.*\"Temperature\".*)∩JSONPATH:$.ZbReceived.THP_ground.Temperature
      unit: °C
  - id: humidity
    channelTypeUID: mqtt:number
    label: humidity ground
    description: null
      stateTopic: tele/sonoffbridge/THP_ground/SENSOR
      transformationPattern: REGEX:(.*\"Humidity\".*)∩JSONPATH:$.ZbReceived.THP_ground.Humidity
      unit: "%"
  - id: linkquality
    channelTypeUID: mqtt:number
    label: linkquality ground
    description: null
      stateTopic: tele/sonoffbridge/THP_ground/SENSOR
      transformationPattern: REGEX:(.*\"LinkQuality\".*)∩JSONPATH:$.ZbReceived.THP_ground.LinkQuality
      unit: / 255
  - id: battery
    channelTypeUID: mqtt:number
    label: battery ground
    description: null
      stateTopic: tele/sonoffbridge/THP_ground/SENSOR
      transformationPattern: REGEX:(.*\"BatteryPercentage\".*)∩JSONPATH:$.ZbReceived.THP_ground.BatteryPercentage
      unit: "%"


// Equipmment
Group                   thp_ground                 "thp ground"              <Equipment_Sensor>    (office)          ["Sensor"]
 // items
Number:Temperature      thp_ground_temperature     "Temperature ground"      <temperature>         (thp_ground)      ["Measurement","Temperature"]    {channel="mqtt:topic:mosquitto:thp_ground:temperature"}
Number:Dimensionless    thp_ground_humidity        "Humidity ground"         <humidity>            (thp_ground)      ["Measurement","Humidity"]       {channel="mqtt:topic:mosquitto:thp_ground:humidity"}
Number                  thp_ground_linkQuality     "Link Quality ground"     <energy>              (thp_ground)      ["Status", "Level"]              {channel="mqtt:topic:mosquitto:thp_ground:linkquality"}
Number                  thp_ground_batteryLevel    "Battery level ground"    <battery>             (thp_ground)      ["LowBattery", "Level"]          {channel="mqtt:topic:mosquitto:thp_ground:battery"}

There’s five steps to this:

  1. Install Mosquitto MQTT broker.
  2. Install zigbee2mqtt on your Pi. Follow the instructions from zigbee2mqtt.
  3. Pair your Zigbee device with zigbee2mqtt - find your device in this list and follow the instructions.
  4. Connect openHAB to Mosquitto
  5. Create a Generic MQTT Thing and configure it with the information for your Zigbee device.

Steps 1 & 4 are described here.

Step 5 depends on your Zigbee device. An example for a bulb is here.

Note that this assumes that your cc2531 already has the correct firmware, as per

If not, you will have to flash it using these instructions.

1 Like

I haven’t transitioned to OH3 yet, as my system with 2.5.10 is very stable. Will probably wait until OH3.1 is released before taking the plunge.
What I did do since the tutorial was written is change to the zig-a-zig-ah adapter instead of the CC2531 stick and this greatly improved stability and range with about 30 zigbee devices in my system.

i successfully instal mqtt with Mosquitto, but when I try to instal zigbee2mqtt have an error . Try to do another instal on top, but always fail on this “npm start” command. I use clean OH3.0.1.

PS this my second try, in the first try I easy instal zigbee2mqtt (on clean OH), but the first time I have another problem with mqtt broker, maybe I broke something and can’t connect zigbe2mqtt to mqtt server). Now in the new (third) try, i will format my sd again and try to setup zigbee2mqtt first and then MQTT on clean OH

Make sure that you selected the correct user during installation


i try instal again (on top of existing zigbee2mqtt) now I have this a litle different error

can you give an example of your /opt/zigbee2mqtt/data/configuration.yaml file?

now I try to erase my OP3 and try from start on version 3.1 snapshot, I hope it helps…

PS how to check if my c2531 stick work correct?

after erasing my OH3.0.0.1 I setup a new 3.1.0.m1 and try setup zigbee2mqtt first, and all go ok like in the tutorial (the only problem that no MQTT server to connect). Then setup mosquito and MQTT broker they go online. Then I check
the status of zigbe2mqtt but I don’t know it works or not? how I can add new devices from the scan button in the thing menu?

Looking at the log, it seems your zigbee2mqtt works.
For auto discovery, if I am not wrong, you need to activate the home assistant feature in your zigbee2mqtt conf though. (I don’t use auto discovery, only use generic mqtt things and manually add them).

I looking in the log and connect 2 devices (water leak sensor and wall switch) and they show in log But how to discover them automatically from UI (as things), it is possible? or only manual by writing the text?

for example, I have this and what do with this? i totally don’t understand this tutorial!!!

I always do it manually using the OH3 interface (generic MQTT thing).
Yes, I know it is quite tedious work.