Zigbee
The Zigbee page manages Zigbee wireless device networks using the zigbee-herdsman library. You can pair and remove Zigbee devices, create GEM zones, configure cluster attributes, and set up command and response mappings between Zigbee clusters and GEM zone commands/attributes.
Prerequisites
Create a Zigbee coordinator device in System > Devices with the driver set to zigbee and Enabled set to Yes. Configure the serial port for the Zigbee USB coordinator stick (e.g., /dev/ttyUSB0).
Supported Adapters
The following Zigbee coordinator hardware is supported:
| Adapter Type | Example Hardware |
|---|---|
| zstack (default) | CC2531, CC2538, CC2652, Sonoff ZBDongle-P, TubesZB, ZigStar |
| ember | Home Assistant Connect ZBT-1/ZBT-2, Sonoff ZBDongle-E, SMLight slzb-06m/07 |
| deconz | Conbee II, Conbee III |
| zboss | Nordic Zigbee NCP |
| zigate | ZiGate PL2303HX, ZiGate+ V2 |
Set the adapter attribute on the device to match your hardware (defaults to zstack if not set).
Optional Device Attributes
| Attribute | Type | Description |
|---|---|---|
adapter | string | Adapter type: zstack, ember, deconz, zboss, zigate. Default: ember |
pan_id | integer | PAN ID for the Zigbee network. Default: 0x1a62 |
channel_list | json | Zigbee channels to use. Default: [11] |
baudrate | integer | Serial port baud rate. Set only if your adapter requires a non-default rate. |
disable_led | boolean | Disable LED on the coordinator. Default: false |
usb_auto_discover | boolean | Auto-promote /dev/tty* to a stable /dev/serial/by-id/... path on connect, and re-discover the dongle by USB descriptor if the configured path no longer exists. Default: true. Disable on hosts that have multiple identical Zigbee coordinators where the wrong one might be picked up. |
Page Layout
The page uses a two-panel layout. At the top is a coordinator section with permit join controls. Below that, the main content area is split into a Devices panel on the left (35% width) and a Device Configuration panel on the right.
Coordinator Section
Coordinator Selector
A dropdown at the top lists all Zigbee coordinator devices (devices with the zigbee driver). Each entry shows the device ID, name, and address. Select a coordinator to load its Zigbee devices and enable the pairing controls.
Permit Join and Device Controls
These controls appear after selecting a coordinator:
| Control | Description |
|---|---|
| Permit Join Start | Opens the Zigbee network for new devices to join (60 seconds). A confirmation prompt appears before starting. |
| Permit Join Stop | Closes the network to new devices. Disabled until permit join is started. |
| Remove Device | Removes the currently selected device from the Zigbee network. Disabled until a device is selected. |
| Reset | Performs a soft reset of the Zigbee coordinator. |
Pairing a New Device
- Select your Zigbee coordinator from the dropdown.
- Click Start in the Permit Join group.
- Confirm the prompt.
- Put the Zigbee device into pairing mode (typically hold the reset button for 5+ seconds, or follow the manufacturer instructions).
- Wait for the device to pair. Toast messages notify you when a device joins and when the interview completes.
- Click Stop to end permit join, or it will expire automatically after 60 seconds.
Removing a Device
- Select the device in the Devices panel.
- Click Remove Device in the coordinator section.
- Confirm the removal prompt.
Devices Panel (Left)
The left panel displays a list of all Zigbee devices on the selected coordinator's network. The panel header shows "Zigbee Devices" and has a refresh icon to reload the device list.
Each device in the list shows:
- Manufacturer name
- Model ID
- Last 6 characters of the IEEE address for identification
Click a single device to select it and load its details in the right panel.
Device Configuration Panel (Right)
The right panel shows configuration options for the selected Zigbee device. It contains three sections: Zone Management, Cluster Configuration, and Mappings (the last only appears when a zone is selected).
Zone Management
This section lets you create GEM zones for the selected Zigbee device or select existing zones.
Existing Zones: A SelectSearch dropdown showing all zones already assigned to this coordinator and device. Selecting a zone populates the subsystem, endpoint, and control type fields. A Delete button removes the selected zone and all its associated attributes and UI zones (with confirmation).
Below the existing zones selector, there are fields for creating a new zone:
| Field | Description |
|---|---|
| Subsystem | The GEM subsystem for the zone (e.g., lighting, climate, security). Disabled when an existing zone is selected. |
| Endpoint | The Zigbee endpoint number. Endpoints represent different functions on multi-function devices. Disabled when an existing zone is selected. |
| Control Type | The control type for the zone (e.g., light_dimmer, light_switch, thermostat). Disabled when an existing zone is selected. |
Click Create Zone to create a new zone. A prompt asks for the zone name (pre-filled with the manufacturer and model formatted as a lowercase name). The zone is created with the address set to {ieee_addr}:{endpoint}.
Device Scanning
Click Scan Device to automatically discover all readable clusters and attributes on the selected endpoint. The scan results show:
- Cluster name and ID
- Attributes with their names, current values (for mains-powered devices), and whether they support reporting
For battery-powered (sleepy) devices, live values cannot be read while the device is asleep — the scan shows ZCL attribute definitions instead.
Use Device Scanning to quickly identify which clusters and attributes are available before manually configuring command and response mappings.
Cluster Configuration
This section lets you browse and interact with Zigbee clusters for the selected device endpoint.
| Field | Description |
|---|---|
| Cluster | A dropdown listing all input clusters for the current endpoint. Each entry shows the cluster ID in brackets, the cluster name, and the direction. Selecting a cluster also loads its available attribute definitions. |
After selecting a cluster, two sets of controls appear:
Attribute Read/Write:
- Attribute Name: Enter the ZCL attribute name (e.g.,
onOff,currentLevel,measuredValue). - Value: Enter a value for write operations.
- Read button: Reads the current attribute value from the device. The result appears in the output area below.
- Write button: Writes the entered value to the attribute on the device.
Command Send:
- Command Name: Enter the ZCL command name (e.g.,
on,off,moveToLevel,toggle). - Payload (JSON): Enter the command payload as JSON (e.g.,
{"level": 254, "transtime": 10}). - Send button: Sends the command to the device.
Use the Read/Write and Send controls to verify that communication with the Zigbee device is working correctly before creating command and response mappings.
Mappings
This section appears only when a zone is selected in the Zone Management section above. It uses two sub-tabs: Command Mappings and Response Mappings.
Command Mappings Tab
Command mappings link GEM zone commands (like on, off, set_level) to Zigbee cluster commands. When a zone command is triggered, GEM sends the mapped Zigbee command.
- Select a Cluster in the Cluster Configuration section above.
- Enter the Command Name and optional Payload.
- Select a Zone Command from the dropdown.
- Click Map Command to create the mapping.
The Mapped Commands list below shows all existing command mappings. Each entry displays the zone command name, the linked cluster, command, and payload. Each mapped command has:
| Icon | Description |
|---|---|
| Test (remote icon) | Sends the zone command to test the mapping. |
| Delete (delete icon) | Removes the command mapping. |
Response Mappings Tab
Response mappings link Zigbee attribute reports to GEM zone attributes. When the Zigbee device reports a value change, GEM updates the mapped zone attribute.
- Select a Cluster in the Cluster Configuration section above.
- Select a Cluster Attribute from the dropdown (populated from the cluster's ZCL definition), or enter a custom attribute name.
- Enter or select a GEM Attribute Name (e.g.,
level,temperature,state). - Optionally set a Scale divisor — the raw Zigbee value is divided by this number before being stored (e.g., set to
100for temperature clusters that report in hundredths of a degree). - Optionally enable Map Values and define value translations using the Key-Value Editor.
- Click Map Response to create the mapping.
The Mapped Responses list below shows all existing response mappings. Each entry displays the attribute name, cluster, and any value map. Each mapped response has a Delete icon to remove it.
Real-Time Updates
The page subscribes to the selected Zigbee coordinator for real-time event notifications:
| Event | Description |
|---|---|
| device_joined | A new device has joined the network. The device list refreshes automatically. |
| device_interview | Device interview started, completed, or failed. The device list refreshes on success. |
| device_left | A device left the network. The device list refreshes automatically. |
| permit_join_changed | Permit join state changed (active/inactive with time remaining). |
| adapter_disconnected | The USB coordinator adapter was disconnected. |
Common Zigbee Clusters
| Cluster | Name | Common Attributes | Common Commands |
|---|---|---|---|
| 0 | genBasic | modelId, manufacturerName, powerSource | resetFactDefault |
| 6 | genOnOff | onOff | on, off, toggle |
| 8 | genLevelCtrl | currentLevel | moveToLevel, move, stop |
| 768 | lightingColorCtrl | currentHue, currentSaturation, colorTemperature | moveToHueAndSaturation, moveToColorTemp |
| 1026 | msTemperatureMeasurement | measuredValue | |
| 1029 | msRelativeHumidity | measuredValue | |
| 1030 | msOccupancySensing | occupancy | |
| 1280 | ssIasZone | zoneStatus, zoneType |
Troubleshooting
Device Won't Pair
- Verify the coordinator is in permit join mode (Start button was clicked).
- Confirm the device is in pairing mode (check manufacturer instructions — usually hold reset 5+ seconds).
- Move the device closer to the coordinator for initial pairing (within 15 feet).
- Try factory resetting the device before re-pairing.
- Check that the device is not already paired to another coordinator.
Device Not Responding
- Verify the device is powered on.
- Check that the device is within range of the coordinator or a router device.
- Reset the coordinator if communication issues persist.
- For battery-powered devices, wake the device before configuring (usually press a button).
Attribute Read Returns Error
- Verify the cluster and attribute name are correct for the device.
- Not all devices support all attributes in a cluster — check the device documentation.
- For battery devices, the device must be awake to respond to reads.
Related Documentation
- Devices - Zigbee coordinator device configuration
- Zones - Zone configuration
- Command Sets - Zone command definitions