Posting this as a sort of PSA for newbies. I spent numerous frustrating hours attempting to get Zigbee and MQTT to play nicely together, and finally figure it out. The process is far from intuitive for a newcomer who is unfamliar with Home Assistant’s ecosystem. Making matters worse for newbies is the fact that I couldn’t find a single tutorial or guide that explained things in enough detail for me to grasp what I was doing wrong, so here goes.
First off, let’s set some parameters around my experience. I have:
- Fresh install of HAOS (Home Assistant Operating System) version 11.2
- Core version 2023.12.0
- HAOS installed on bare metal x86 architecture
- Z-Wave USB stick
- ZigStar v0.3 Zigbee controller connected via network/LAN
This guide was by far the most helpful that I found, but it still did not fill in some of the nuanced details that I just wasn’t getting. More on that in a moment.
The problems I kept encountering in the Zigbee2MQTT app were:
- Can’t start herdsman
- Socket errors
Here’s the crux of what I was missing / not grasping, which I hope will help others:
- You must have the MQTT broker installed in HA. Do this before you attempt to install Zigbee2MQTT.
- After you install the MQTT broker, reboot your system.
- Go into the configuation for MQTT broker. Copy the username and its password. Copy the server info. You will need all of this information.
- If you have not already setup your ZigStar, do so and confirm you can access its built-in HTTP socket from your web browser on a PC, connected to the same LAN the ZigStar is on. Take a look at its configuration and note it’s IP address. Also note its port.
- Go back to HA and install Zigbee2MQTT. Do NOT attempt to start it. Install it.
- Go into the configuration for Zigbee2MQTT. You need to set that up according to the article I posted a link to above. Alternatively, login to your ZigStar’s HTTP interface. There’s a tab on the left nav bar that will show you the proper configuration settings for HA. Find that nav page and walk thru it. Pretty self explanatory when you see it. Copy that info for MQTT.
- So, back to the Zigbee2MQTT config. The important part I kept missing before is that you must enter the username and password of MQTT Broker in the ‘server’ section. You also need to enter the port of the ZigStar.
Your config for Zigbee2MQTT will end up looking something like this:
under the ‘mqtt’ section:
base_topic: zigbee2mqtt
server: mqtt://core-mosquitto:1883
user: <username indicated in MQTT Broker config>
password: <pw for above username, also found in MQTT Broker config>
The “server” portion above should match the server name and port number found in the configuration of your MQTT Broker app. So, if yours is different (go look), then plug your info in.
Now, in the ‘serial’ section of Zigbee2MQTT’s config, enter:
port: tcp://<ZigStar IP address>:<ZigStar port number>
baudrate: 115200
Note, the default port for Zigstar is 6638
And just to be clear, do NOT enter the < > brackets I typed above. That is just to encapsulate the contextual clues for you.
After all that, start the Zigbee2MQTT service/app.