Zigbee is an IEEE 802.15.4-based specification for a suite of high-level communication protocols used to create personal area networks with small, low-power digital radios. It is widely used for home automation, smart lighting, sensors, and other low-power low-bandwidth wireless applications.
The Weble universal gateway Zigbee driver integrates zigbee2mqtt — an open-source Zigbee to MQTT bridge — directly into the gateway. It runs a built-in MQTT broker, starts zigbee2mqtt as a background process, and automatically maps all discovered Zigbee devices and their properties to routable gateway addresses.
The driver provides two interfaces:
- Addresses tab: displays all auto-discovered Zigbee device addresses in a tree structure, with real-time values.
- UI tab: embeds the full zigbee2mqtt web interface in an iframe, allowing device pairing, configuration, network visualization, OTA updates, and all other zigbee2mqtt features directly from the gateway interface.
¶ 1. Getting started
¶ 1.1 Prerequisites
A Zigbee coordinator (USB dongle) must be connected to the gateway. The coordinator must be compatible with zigbee2mqtt supported adapters. Common adapter types include:
- zstack — Texas Instruments CC2531, CC2652, CC1352 based adapters
- deconz — Dresden Elektronik ConBee/RaspBee adapters
- ezsp — Silicon Labs EFR32/EM35x based adapters
¶ 1.2 Gateway configuration
Create a new gateway and select the Zigbee driver. Configure the Serial Port to point to the connected Zigbee coordinator:
- The serial port field provides an auto-complete list of all detected USB/serial interfaces on the gateway.
- You can select the device by its unique ID (recommended — remains stable if USB ports are swapped) or by its system path (e.g.
/dev/ttyACM0).
Set the Adapter type to match your coordinator hardware, or leave it on Auto for automatic detection.
¶ 1.3 Starting the driver
When the gateway is started, the driver:
- Starts a local MQTT broker on port
28522(internal, not exposed externally). - Launches the zigbee2mqtt process, which connects to the coordinator and the internal MQTT broker.
- Waits for zigbee2mqtt to fully initialize.
- Starts a web proxy that exposes the zigbee2mqtt web interface at the
/zigbeepath on the gateway's web server.
Once started, the zigbee2mqtt interface is accessible from the UI tab in the gateway view.
¶ 1.4 Pairing devices
To pair a new Zigbee device, use the zigbee2mqtt interface in the UI tab:
- Switch to the UI tab in the gateway view.
- Click Permit join in the zigbee2mqtt interface to enable pairing mode.
- Put your Zigbee device into pairing mode (usually by pressing a button or power cycling it — refer to the device manual).
- Once the device is discovered, it appears in the zigbee2mqtt device list and its addresses are automatically created in the gateway's Addresses tab.
¶ 1.5 Working with addresses
After a device is paired, the gateway automatically creates addresses for the device and all its exposed properties. For example, a temperature/humidity sensor named LivingRoom would generate:
%zig:LivingRoom— the main device address (receives the full JSON payload with all properties)%zig:LivingRoom/temperature— individual temperature value%zig:LivingRoom/humidity— individual humidity value%zig:LivingRoom/battery— battery level%zig:LivingRoom/set— writable address (for devices that support commands)%zig:LivingRoom/get— readable address (to request current values)
These addresses are routable and loggable like any other gateway address. They can be used in routes to forward Zigbee sensor data to other protocols such as BACnet, Modbus, MQTT, or the cloud.
Note: Addresses are automatically created when devices are discovered. Manual address insertion is not available. However, addresses can be manually deleted if a device has been removed from the network.
¶ 2. Gateway parameters
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this Zigbee gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| Serial Port | serialPort | The serial port of the Zigbee coordinator. Use the auto-complete to select from detected USB/serial interfaces. Can be set by unique ID (recommended, stays stable across reboots and USB port changes) or by system path (e.g. /dev/ttyACM0). |
| Adapter | adapter | The Zigbee coordinator adapter type: Auto (automatic detection), zstack (Texas Instruments CC26xx/CC13xx), deconz (Dresden Elektronik ConBee/RaspBee), or ezsp (Silicon Labs EFR32/EM35x). Leave on Auto unless detection fails. |
| Baudrate | baudrate | Serial communication speed: Auto (recommended), 9600, 19200, 38400, 57600, 76800, or 115200. Most adapters work with Auto. |
| rtscts | rtscts | Enable RTS/CTS hardware flow control on the serial port. Required by some adapters. Default: disabled. |
¶ 2.1 Gateway JSON example
{
"serialPort": "/dev/serial/by-id/usb-Texas_Instruments_XDS110-if00",
"adapter": "",
"baudrate": "",
"rtscts": false
}
¶ 3. Addresses
¶ 3.1 Address format
Zigbee addresses use the prefix %zig: followed by the device friendly name and optionally a property path:
%zig:LivingRoom— main device address (full JSON payload)%zig:LivingRoom/temperature— published property (pushed by the device)%zig:LivingRoom/set— set endpoint (send commands to the device)%zig:LivingRoom/set/brightness— set a specific property%zig:LivingRoom/get— get endpoint (request values from the device)%zig:LivingRoom/get/temperature— request a specific property value
The address names are derived from the friendly name configured in zigbee2mqtt. Renaming a device in the zigbee2mqtt UI will update the address names accordingly.
¶ 3.2 Bridge addresses
In addition to device addresses, the driver automatically creates bridge management addresses for controlling zigbee2mqtt itself:
| Address | Description |
|---|---|
%zig:bridge/state |
Bridge connection state (online / offline). |
%zig:bridge/devices |
JSON list of all paired Zigbee devices with their properties and capabilities. |
%zig:bridge/info |
Bridge information (version, coordinator type, network settings). |
%zig:bridge/request/permit_join |
Write to enable/disable device pairing. |
%zig:bridge/request/restart |
Write to restart zigbee2mqtt. |
%zig:bridge/request/health_check |
Request a health check. |
%zig:bridge/request/networkmap |
Request a network map. |
%zig:bridge/request/backup |
Request a coordinator backup. |
%zig:bridge/request/device/remove |
Remove a device from the network. |
%zig:bridge/request/device/rename |
Rename a device. |
%zig:bridge/request/device/ota_update/check |
Check for OTA firmware updates. |
%zig:bridge/request/device/ota_update/update |
Apply an OTA firmware update. |
%zig:bridge/request/group/add |
Create a Zigbee group. |
%zig:bridge/request/group/remove |
Remove a Zigbee group. |
%zig:bridge/request/group/members/add |
Add a device to a group. |
%zig:bridge/request/group/members/remove |
Remove a device from a group. |
¶ 3.3 Device property access levels
When a Zigbee device is discovered, the driver inspects each property's access level (from the zigbee2mqtt device definition) and creates the appropriate addresses:
| Access | Description | Address created |
|---|---|---|
| Published | The device pushes this value automatically (e.g. sensor readings) | %zig:device/property |
| Settable | The value can be written to the device (e.g. brightness, on/off) | %zig:device/set/property |
| Gettable | The value can be explicitly requested from the device | %zig:device/get/property |
A property can have multiple access levels (e.g. a light's brightness is both published and settable).
¶ 3.4 Reading and writing
Reading a device property address (%zig:device/property) returns the last known value. If the address has a corresponding get endpoint, the driver reads via the get MQTT topic to request a fresh value from the device.
Writing to a device address (%zig:device/property) automatically routes the write to the corresponding set MQTT topic if one exists. If no set endpoint is available, the write returns a "read only" error.
¶ 3.5 Address properties
| Property | Value |
|---|---|
| Readable | No (values are pushed by the device, not polled) |
| Writable | Yes (for settable properties) |
| Routable | Yes |
| Loggable | Yes |
¶ 4. zigbee2mqtt integration details
¶ 4.1 Internal architecture
The Zigbee driver uses the following internal architecture:
- A local MQTT broker runs on port
28522(TCP, localhost only). - zigbee2mqtt connects to this broker and publishes/subscribes to standard zigbee2mqtt MQTT topics.
- The Weble driver's internal MQTT client subscribes to all topics and maps them to gateway addresses with the
%zig:prefix (internally translated from%mqtt:zigbee2mqtt/topics). - The zigbee2mqtt web interface is proxied through the gateway's web server at the
/zigbeepath.
¶ 4.2 Data persistence
The driver automatically backs up and restores the zigbee2mqtt configuration files:
configuration.yaml— zigbee2mqtt settings and device friendly namescoordinator_backup.json— coordinator network state backupdatabase.db— device database
These files are backed up from the zigbee2mqtt data directory to the gateway's data directory, and restored on startup (the most recent version is always used). File changes are automatically watched and backed up.
¶ 4.3 Serial port configuration
The driver updates the serial section of zigbee2mqtt's configuration.yaml at each startup with the configured serial port, adapter, baudrate, and rtscts parameters. This ensures the gateway's configuration always takes precedence over any manual changes in the zigbee2mqtt configuration file.