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, then set its address:

• USB stick: the serial path, e.g. /dev/ttyUSB0 (or a stable /dev/serial/by-id/... path).
• Networked coordinator (e.g. an SMLight SLZB-06 over Ethernet): host:port, e.g. slzb-06.local:6638.

Then set the adapter attribute to match your hardware (see below). This is the single most important setting: there is no reliable auto-detect, and if you leave it blank the driver assumes an ember adapter — so a CC2652-based (zstack) stick will fail to start until you set adapter to zstack.

Open Zigbee

Supported Adapters

Set the adapter attribute to one of the following, matched to your coordinator's chipset:

adapter	Chipset / Driver	Example Hardware
zstack	Texas Instruments CC253x / CC2652	CC2531, CC2538, CC2652P, Sonoff ZBDongle-P, TubesZB, ZigStar, ITEAD
ember	Silicon Labs EmberZNet (EFR32)	Sonoff ZBDongle-E, SMLight SLZB-06/07, Home Assistant Connect ZBT-1/ZBT-2
deconz	Dresden Elektronik	Conbee II, Conbee III
ezsp	Legacy Silicon Labs EmberZNet	Older EFR32 sticks (e.g. Nortek HUSBZB-1, Elelabs) — use only if ember will not connect
zboss	ZBOSS NCP	Nordic Zigbee NCP

If the adapter attribute is left blank, the driver falls back to ember.

Optional Device Attributes

Set these in the device's Attributes editor (they are catalogued under the zigbee context, so the name picker offers them).

Attribute	Type	Description
adapter	string	Adapter type: zstack, ember, deconz, ezsp, zboss. Falls back to ember when unset — set it explicitly.
pan_id	integer	PAN ID for the Zigbee network, entered as an integer. Default: 6754 (0x1a62).
channel_list	json	Zigbee channel(s) to use, as a JSON array — e.g. [15] or [11, 20, 25]. Default: [11].
baudrate	integer	Serial port baud rate. Set only if your adapter requires a non-default rate.
disable_led	boolean	Disable the 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.
network_key	json	Read-only and secure. The driver mints a random 16-byte network encryption key on first connect and stores it here — you never set this yourself.

note

The coordinator builds its own pairing database on the GEM server. Backing up the server preserves your Zigbee pairings; replacing the coordinator stick or clearing its network key re-creates the mesh from scratch and every device must be re-paired.

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
Start (Permit Join)	Opens the Zigbee network for new devices to join for 60 seconds. A confirmation prompt appears before starting.
Stop (Permit Join)	Closes the network to new devices. Disabled until permit join is active.
Remove Device	Removes the currently selected device from the Zigbee network. Disabled until a device is selected.
Reset	Restarts the coordinator — it disconnects and reconnects the stick. A confirmation prompt warns that connected devices may briefly lose communication.

Pairing a New Device

1. Select your Zigbee coordinator from the dropdown.
2. Click Start in the Permit Join group.
3. Confirm the prompt.
4. Put the Zigbee device into pairing mode (typically hold the reset button for 5+ seconds, or follow the manufacturer instructions).
5. Wait for the device to pair. Toast messages notify you when a device joins and when the interview completes.
6. Click Stop to end permit join, or it will expire automatically after 60 seconds.

Removing a Device

1. Select the device in the Devices panel.
2. Click Remove Device in the coordinator section.
3. 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 Zone Management, Device Data Points, Cluster Configuration, and Mappings. Most of the panel stays empty until you choose an Endpoint in Zone Management — that selection populates the Device Data Points scan and the Cluster list. The Mappings section appears only 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 Data Points

Select an Endpoint in Zone Management first — the Device Data Points section then appears with a Scan Device button. Clicking it discovers the device's functional input clusters and their attributes on that endpoint. Administrative clusters (such as genBasic, genIdentify, and genOta) are skipped so the results focus on usable data points.

Results are grouped by cluster, with one table per cluster:

• Attribute — the ZCL attribute name
• Value — the live value (mains-powered devices), or -- when not read
• Reports — yes when the attribute supports attribute reporting

For battery-powered (sleepy) devices, live values cannot be read while the device is asleep — the scan shows ZCL attribute definitions only (the Value column stays --).

tip

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 (for write): Enter a value for write operations. Numeric and true/false text is converted automatically.
• 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.

tip

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 the zone command runs, GEM sends the mapped Zigbee command to the device.

The Command Name and Payload come from the Cluster Configuration section above — the Command Mappings tab itself only has the Zone Command picker and the Map Command button. To build a mapping:

1. In Cluster Configuration, select the Cluster and enter the Command Name and optional Payload (JSON).
2. In the Command Mappings tab, select the GEM Zone Command to bind it to.
3. Click Map Command.

If you instead fill in a Value (for write) in the Cluster Configuration Read/Write row, the mapping is stored as an attribute write rather than a cluster command — use this for devices controlled by writing a cluster attribute instead of invoking a command. For dimmer/setpoint zone commands, the zone's level or setpoint value is inserted into the payload at run time.

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 (or the driver polls it), GEM updates the mapped zone attribute.

1. In Cluster Configuration, select the Cluster — this loads its ZCL attribute definitions into the Cluster Attribute dropdown.
2. In the Response Mappings tab, set the GEM Attribute Name — pick an existing zone attribute or type a custom one (e.g., level, temperature, state).
3. Choose the Cluster Attribute from the dropdown. This list is fixed to the selected cluster's ZCL attributes — there is no free-text entry here, so select the cluster first if the dropdown is empty.
4. Optionally set a Scale divisor — the raw Zigbee value is divided by this number (and rounded to one decimal) before being stored. For example, temperature clusters report hundredths of a degree, so a scale of 100 turns 2150 into 21.5.
5. Optionally turn on Map Values and define value translations in the editor that appears (e.g., map a raw 0/1 to off/on).
6. Click Map Response.

The Mapped Responses list below shows all existing response mappings. Each entry displays the GEM attribute name, the source cluster.attribute, any scale divisor, 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

1. Verify the coordinator is in permit join mode (Start button was clicked).
2. Confirm the device is in pairing mode (check manufacturer instructions — usually hold reset 5+ seconds).
3. Move the device closer to the coordinator for initial pairing (within 15 feet).
4. Try factory resetting the device before re-pairing.
5. Check that the device is not already paired to another coordinator.

Device Not Responding

1. Verify the device is powered on.
2. Check that the device is within range of the coordinator or a router device.
3. Reset the coordinator if communication issues persist.
4. For battery-powered devices, wake the device before configuring (usually press a button).

Attribute Read Returns Error

1. Verify the cluster and attribute name are correct for the device.
2. Not all devices support all attributes in a cluster — check the device documentation.
3. 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