This guide is based on the GitHub project: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt#installation
Preparation #
Before getting started, ensure that Home Assistant is installed and the Dongle is connected to the host's USB port. If not yet installed, please follow the Home Assistant Installation Guide.
Step 1: Install Apps #
When connecting HA through the Zigbee2MQTT App(formerly Add-on), you need to install two Apps:
- Mosquitto broker (MQTT Broker)
- Zigbee2MQTT
Install MQTT Broker #
Go to Settings → Apps → Install app, and install the Mosquitto broker app, then start it.

Install Zigbee2MQTT #
1. Add Repository
Go back to the App(formerly Add-on Store), click" ⋮ "→ "Repositories", fill in
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
and click "Add" → "Close" or click the "Add repository" button below, click "Add" → "Close"

2. Install Zigbee2MQTT
Return to the store list, find Zigbee2MQTT, and proceed with installation.

Step 2: Configure Zigbee2MQTT #
Open the Zigbee2MQTT App → Configuration page.
You need to configure the device's adapter type and serial port path under serial.

The following format:
adapter: Adapter Type
port: Dongle Serial Port PathYAML
Example Configuration for Dongle-PP10:
adapter: zstack
port: /dev/ttyUSB0YAML⚠️ The serial port path may vary depending on the host system. On Linux, you can find the serial path by running:
ls -l /dev/serial/by-idZshExample output:
coolkit@coolkit-All-Series:~$ ls -l /dev/serial/by-id
total 0
lrwxrwxrwx 1 root root 13 3月 31 18:09 usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_76536147c914ef11950378b8bf9df066-if00-port0 -> ../../ttyUSB0ZshThe serial port path in this case is:
/dev/ttyUSB0ZshFor other operating systems, please refer to the respective connection instructions.
After completing the configuration, start the Zigbee2MQTT App. Wait for about two minutes, then you can click to enter the Web UI Console to add and manage devices.
