Skip to main content

Zigbee Support in Enapter Gateway with Zigbee2MQTT

What is Zigbee?

Zigbee is a wireless communication standard designed for short-range, low-power digital communication among devices. It is primarily used in applications such as home automation, industrial automation, and sensor networks.

Zigbee-enabled energy devices encompass a wide variety, including smart meters, thermostats, underfloor heating controllers, and many others.

What is Zigbee2MQTT?

Zigbee2MQTT is an open-source project that serves as a bridge between Zigbee devices and MQTT (Message Queuing Telemetry Transport) communication protocol. This software allows users to integrate Zigbee-based smart devices into automation systems using the MQTT protocol.

Enapter Gateway runs the MQTT broker, which makes installation and integration of Zigbee2MQTT intuitive and straight forward.


Connecting Adapter to Enapter Gateway

In general, the SONOFF Zigbee 3.0 USB Dongle Plus-E comes pre-flashed with coordinator firmware. Therefore, in most cases, it would be enough to connect your dongle to USB port of your Enapter Gateway.

Zigbee2MQTT Web Interface

To ensure that the dongle is recognized correctly, connect to the Gateway Terminal either over SSH or Cloud. Start the shell with the bash command and run the ls -al /dev/ttyA* command.

Zigbee2MQTT Web Interface

If you see the /dev/ttyACM0 - everything is set up in the right way.

In case you don't see the ttyACM0 device in the list, you need to check which firmware is installed in your Zigbee adapter. For more information and flashing instructions, check out the following resources:


To flash the firmware you need to open adapter's enclosure to get access to the Flash button

Setting up MQTT Broker on Enapter Gateway

Enapter Gateway has a built-in MQTT broker which can be used for receiving devices telemetry as well as publishing MQTT messages from other services. In our case, we will be using MQTT broker as a backend for Zigbee2MQTT.

We need to set the public MQTT username and password. To do this, connect to the Gateway Terminal either over SSH or Cloud, switch to configuration mode with the configure command, and then run several commands:

set public-mqtt authentication username "public"
set public-mqtt authentication password "password"

Remember to choose a unique username and password instead of the default ones (public/password) provided in this example.

Public MQTT is running on port 9883.

This information is required for the next steps.


More information can be found at Enapter Handbook

Setting up Zigbee2MQTT Using Docker Container

Connect to the Gateway Terminal either over SSH or Cloud and switch to the root shell.

Connect to the Gateway Terminal either over SSH or Cloud. Switch to the shell using the bash command, and then switch to root with the sudo su - command.

Create Zigbee2MQTT data directory at /user/zigbee2mqtt-data/

Create Zigbee2MQTT data directory: mkdir -p /user/zigbee2mqtt-data/.

Open /user/etc/docker-compose/docker-compose.yml with nano editor and put the configuration below under services section.

Zigbee2MQTT Web Interface
container_name: zigbee2mqtt
restart: unless-stopped
image: koenkk/zigbee2mqtt
- /user/zigbee2mqtt-data:/app/data
- /run/udev:/run/udev:ro
- 9080:8080
privileged: true
- TZ=Asia/Yerevan
- /dev/ttyACM0:/dev/ttyACM0

Press CTRL+X to exit, save your configuration and restart docker compose with systemctl restart enapter-docker-compose command.

If everything was done correctly, you will be able to connect to Zigbee2MQTT web interface using URL http://YOUR_GATEWAY_IP:9080.

Zigbee2MQTT Web Interface

Configuring Zigbee2MQTT

Navigate to Settings -> Settings -> MQTT.

Configure the following settings:

  • Base topic: zigbee2mqtt
  • MQTT server: mqtt://

The IP address is the default IP address of Enapter Gateway in the Docker network. Public MQTT default port is 9883.

Zigbee2MQTT Web Interface

Submit configuration using Submit button.

Navigate to Settings -> Settings -> Serial.

Configure the following settings:

  • Port: /dev/ttyACM0
  • Adapter: auto
Zigbee2MQTT Web Interface

Submit configuration using Submit button.

Navigate to Settings -> Tools, click on Restart Zigbee2MQTT red button and confirm the action.

Zigbee2MQTT Web Interface

Adding Zigbee Device

Navigate to Zigbee2MQTT Web Interface and click on Permit join (All) button in the top right corner. After this, you will have around 4 minutes to add your devices.

Zigbee2MQTT Web Interface

Follow the instructions provided by your device to connect it to the Zigbee network. In many cases, this is achieved by a long press of the button located on your device. Once the device is discovered, it will appear in the list on the 'Devices' page.

Click on blue Rename device button and set it nice and friendly name.

Zigbee2MQTT Web Interface

Your device is successfully sending data over MQTT, and you are able to subscribe to receive it now.

Checking MQTT connection (subscribing to messages)

You are able to check connection using MQTTX Desktop Client. The detailed guide on how to use it available at this page

You need to subscribe to the topic you set in Zigbee2MQTT MQTT settings (zigbee2mqtt/# in this guide).

Zigbee2MQTT testing with MQTTX Desktop Client


  • At the moment of writing this article, Virtual UCM had no support for subscribing/publishing to MQTT, but it is still possible to integrate by setting up the 'MQTT to REST HTTP API.' The most convenient tool for this is Node-RED, which can also be run in a Docker container.


Feel free to ask any questions or give any proposals for improving this guide in our Discord

Hardware diversity is welcome. Integrate any device into a unified energy network.
© 2024 Enapter
Developer toolkit