Using specialized Zigbee-coordinator hardware, the adapter creates and manages a Zigbee Network which can control and connect a large number of Zigbee Devices. The list of compatible devices inlcudes > 4000 devices from > 450 different vendors. The number of devices in the network depends on the available coordinator hardware. Common coordinator hardware are USB sticks with Texas Instruments CC26xx, Silicon Labs EZSP or ZIGate chipsetz. Some branded USB devices (Sonoff ZB-Dongle, Dresden Electronic Conbee) can also be used. There are also network-based hubs from various manufacturers.
By working directly with the coordinator, the driver allows you to manage devices without additional application / gateways / bridge from device manufacturers (Xiaomi / TRADFRI / Hue / Tuya). More information about the Zigbee-network can be read here (in English).
One coordinator device is required for each Zigbee Adapter instance. The device must be flashed with the respective coordinator firmware. A list of supported coordinators, the necessary equipment for the firmware and the device preparation process for different coordinator devices are described here in English or smarthomescene.com or here in Russian
Recommended devices are based on either the CC2652 or CC1352 chip. Devices based on cc253x chips are still supported but are no longer recommended. Only CC26xx/cc1352/cc2538 Devices support extraction of the NVRam backup which should allow to swap coordinator hardware without having to reconnect all zigbee devices to the network. Current firmware files for these devices can be found on GitHub
recommended:
- ConBee II
- RaspBee II
no longer recommended:
- ConBee I
- RaspBee
While Conbee/RaspBee Support is no longer considered experimental in the zigbee-herdsman and zigbee-herdsman-converters libraries used by the zigbee Adapter, use of these devices with the adapter may limit functionality. Known issues are:
- link quality display may be incorrect
- device map metrics may be incorrect
- NVRam Backup is not supported.
Support for Silicon Lab Zigbee based adapters is experimental. The initial support for EZSP v8 is still not yet considered stable, and the project is in need of more developers volunteering to help with this integration. Please refer to the respective documentation on this page and ongoing development discussion with regards to the state of Silabs EmberZNet Serial Protocol (EZSP) adapter implementation integration into the zigbee-herdsman and zigbee-herdsman-converters libraries which it depends on.
Support for ZiGate based adapters is experimental. The initial support for ZiGate is still not yet considered stable, and the project is in need of more developers volunteering to help with this integration. Please refer to the respective documentation on this page and ongoing development discussion with regards to the state of ZiGate adapter implementation into the zigbee-herdsman and zigbee-herdsman-converters libraries which it depends on.
The adapter should always be installed from within the ioBroker Admin. Direct npm and GitHub installations are not recommended.
At first start, it is vital to set up the adapter settings. These include:
- the communication to the zigbee Coordinator (COM Port). This can be a device identifier or a network address for Network-based coordinators
- the required firmware-Type
- the network parameters PanID (a number between 0 and 65565), extended PanID (a 16 digit HEX number) and the zigbee Channel important: Do not run the adapter without changing the values for PanID (6754) and Extended PanID (DDDDDDDDDDDDDDDD) to unique values for your Zigbee Installation.
Please refer to the in depth documentation (german version, russian version) for a detailed explanation on how to configure the adapter.
Once the adapter is up and running, the desired devices need to be integrated into the network. This requires for both the adapter and the device to be in pairing mode. Most new devices will be in pairing-mode when they are powered up for the first time, but some will require a special procedure for this. Please refer to the device manual for information on this.
The adapter is placed in pairing mode by pressing the pairing button:
A dialog showing a pairing countdown appears. When a new device is discovered, interviewed and paired with the network, messages will be shown in this dialog, and the device will show up in the grid of active devices. Any known device should show up with an image and the correct device name, as well as a number of changable settings. Any unknown device will show up with a device name and a ? as icon, while devices which failed the pairing will show up as 'unknown' with the same ? icon. These should be removed from the network to be paired again. Please refer to the documentation linked above for more details.
The adapter allows for the creation of groups via the 'add group' button. Once a group has been formed, devices can be added to and removed from the group from the device card. Removal is also possible from the group card. Groups have the advantage that a single command is sent to control all group members. This is especially helpful when changing the groups brightness and/or color settings. Note that not all devices may be added to groups - the device itself needs to support this feature.
Group configuration is available from the device grid.
Bindings can be used to link a remote control directly to a device, like it is e.g. done for the ikea devices. This binding has the advantage that bound devices will continue to work together even if the Zigbee Coordinator is unavailable. Note that not all devices may be part of a binding - the devices themselves need to support this feature.
The binding configuration is only available from the zigbee tab
The adapter has the ability to generate a map of the mesh network. This usually takes a few minutes and provides a momentary glimpse into how the devices are meshed with each other.
The network map is only available the zigbee tab.
The Adapter offers to collect debug information for specific devices in order to identify problems in device operation and integration. This needs to be enabled on the desired devices from the device grid.
The debug information is only available from the zigbee tab.
Device integration can be modified on a per Model basis, allowing the user to customise the states associated with the device. Note that before version 2.1.0, this is limited to choosing between the default expose based integration and the previous legacy integration. More options for customisation are under development.
The local overrides are only available from the instance configuration
The developer mode offers the ability to communicate with any paired device solely based on the details of the Zigbee communication rules. Use of this requires an insight into Zigbee Clusters, Attributes and messaging structure. It can be used to control devices which are not currently supported. An in depth desctiption of the developer Tab is available in the documentation.
The developer tab is only available from the instance configuration
There is a friendly project with similar functionality which is based on the same technology. It uses the same base libraries for hardware communication and device integration. Any device listed as compatible in this project is likely to be compatible with the ioBroker.zigbee Adapter. Note that there is a delay between device integration into zigbee2mqtt.io and the Zigbee-Adapter, as compatibility with the hardware libraries requires verification before the adapter can move to the latest version.
There are knowledge bases that can be useful for working with Zigbee-devices and equipment:
- in English https://www.zigbee2mqtt.io/ or https://zigbee.blakadder.com
- in Russian https://myzigbee.ru/
Pleae refer to this list to check compatibility. Once a device is listed as compatible there, it is either already compatible with the Zigbee Adapter or can be made compatible using an external converter.
or
You can thank the authors by these links:
- to Arthur Rupp https://paypal.me/ArthurRupp
- (asgothian) ZHC 23.6.0
- (asgothian) ZH 3.3.x
- (asgothian) removed extra logging
- (asgothian) fixed memory issue.
- (asgothian) Configure on Message - 5 attempts.
- (arteck) update transmitPower
- (arteck) back to 2.0.2
- (asgothian) fix configured info
- (asgothian) fix battery voltage (V -> mV)
- (asgothian) enable debug interface v1.0
- (asgothian) Push Zigbee-Herdsman to 2.5.7
- (asgothian) Push Zigbee-Herdsman-Converters to 23.1.1
- (asgothian) fix configure on message
- (asgothian) remove extra warning messages
- (asgothian) fix Adapter-Checker notes
- (asgothian) improve base64 image detection
- (asgothian) removed unused adaptert objects (info.groups, excludes) from adapter config
- (asgothian) expose generation with expose function requiring a device. (Issue #1842)
- (asgothian) fix failure to configure for devices needing multiple configurations (Issue #2375)
- (asgothian) fix hold/release and press/release action handling (Issue #2387)
- (asgothian) fix lib/legacy requirement for external converters (Issue #2376)
- (asgothian) improved external converter handling
- (asgothian) fix OTA bug
- (asgothian) improved message handling for devices which report values outside their defined ranges
- (asgothian) preparation for ZHC 22.x (model definition loaded on demand
- (asgothian) fix legacy definition for devices
- (asgothian) added action state for remotes.
- BREAKING CHANGES
- switch to converters 21 changes the exposes for a large numbern of devices (mostly remotes)
- new method for controlling color based on subchannels for rgb, hs and xy
- Exposes as default for ALL devices. Use of old definition as option only
- Requires Node 20.x or newer
- (asgothian) Fix Pairing
- (asgothian) change ping
- (asgothian) delay map generation until refresh is activated, map messages after generation
- (asgothian) remove bindings tab from zigbee tab
- (asgothian) reorder tabs in configuration
- (asgothian) remove binding tab from configuration
- (asgothian) remove map from configuration
- (asgothian) add debug to zigbee tab
- (asgothian) Herdsman 3.2.5, Converters 21.30.0
- (asgothian) Exposes as default, use of old device definitions as legacy optional
- (asgothian) User specific images (model based, device based)
- (asgothian) Improved group editing - remove members from group card
- (arteck) Herdsman 2.1.9, Converters 20.58.0
- (asgothian) Fix: Aqara T1M (CL-L02D)
- (arteck) deleteDeviceStates change to deleteObj
- (arteck) corr icon download bug (axios)
- (asgothian) corr Channel Scan
- BREAKING CHANGE
- bugs : ChannelScan is currently not available
- (lebrinkma) fix linter errors
- (asgothian) disable map display for deactivated devices
- (asgothian) new option on map: disable physics interaction
- (asgothian) new zigbee-herdsman-converters 20.28.0
- (asgothian) new zigbee-herdsman 2.1.1
- (asgothian) Allow use of keyless converters (used for TuYa and compatible devices in zigbee-herdsman-converters
- (arteck) swap from request to axios
- (arteck) delete groups works again
- (arteck) typo admin settings
- (arteck) eslint config
- (arteck) corr admin settings
- (arteck) add new eslint version
- (arteck) add flow control option
- (asgothian) add new NewHerdsman
- (arteck) add new ezsp coordinator Firmware (7.4.1.0)
- (arteck) icon ota device update
- (arteck) icon fix
- (arteck) core update
- (arteck) dependency update
- (arteck) dependency update
- (arteck) dependency update
- (arteck) Baudrate is now configurable. works ONLY with Deconz/Conbee(38400)
- (arteck) add nvbackup.json delete button
- (arteck) new zigbee-herdsman-converters 18.x
- (arteck) configure message is now a warning
- Powered by new zigbee-herdsman library and new converters database
- Drop support NodeJS 6
- Serialport 8.0.5 (in zigbee-herdsman)
- More new devices
- Some design update
- Binding
The MIT License (MIT)
Copyright (c) 2018-2025 Kirov Ilya [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.