Home

Welcome to the ioBroker.zigbee Wiki

This wiki will provide information for operation and management of the ioBroker Zigbee Adapter. Most pages will be in english only. A dedicated documentation of basic functionalities is available in german (Deutsche Dokumentation) and englisch (English Documentation)

Adapter Installation

The adapter should always be installed using the iobroker admin interface. Installations directly from NPM or GitHub should only be done on direct request of the adapter developers.

Adapter Configuration

Basic configuration

After installation, the adapter is preconfigured with what the developers consider a good default set of parameters. This includes the encryption parameters for the zigbee network, which are randomized at first start. The user is required to provide the settings for

• the communication port (USB / TCP)
• the coordinator type (chipset / driver)
• the baud rate - if the driver uses this setting.

Additionally, it is advised to check the current channel load to pick the best zigbee channel for the new network.

Key items in the configuration are verified against an existing coordinator backup and the current recommended settings. This is done automatically upon loading the hardware tab. There are three possible results:

• a green check mark - this indicates that the value matches the existing coordinator backup
• a red x - this indicates that the value does not match the existing coordinator backup, or that no backup exists.
• a yellow triangle - this can appear beside either of the two previously described marks. It warns that a value is not within the recommended range for this configuration item.

With all settings set, the zigbee subsystem can be configured for automatic start at adapter start.

A step-by-step guide on how to best configure the adapter is available here.

Advanced configuration

A number of options exist to fine tune the adapter behaviour

Device Availability

The adapter uses two methods to determine device availability. For Routers, the adapter will send a periodic message to the device to see if it repsonds. Any device which does not respond to this message is listed as unavailable. As soon as the coordinator receives a message from a device marked as unavailable, this device will be marked available again. There are different options for this availability query. By default, the adatper uses the default method defined in the Zigbee-Herdsman. For some networks and/or devices, alternative methods of querying specific ZCL cluster/attribute combination provide better results. The adapter also offers the option to set the severity of the messages generated if a device cannot be reached for availability, as well as a time between sending these queries. Note: The time configured here may be adjusted by the adapter based on network size.

EndDevices use a different system to determine availability, as they usually do not respond to any request from the coordinator unless they have been woken up. Therefore, availability is solely based on a timeout between messages received. Up to Version 3.3.0, this timeout is 25 hrs.

Additionally, the adapter offers an Available update timeout. If set to a value > 0, the available state will be refreshed when a message is received before the 25 hr timeout but more than the configured value after the previous update of the state. If the value is set to 0, the available state will not be refreshed unless it falls to false.

Internal backup

With this option not set, the adapter will generate a copy of the adapters local data (shepherd.db, nvbackup.json, LocalOverrides.json) at adapter start. These files will remain in the adapter data folder and will be included in the zigbee backup generated by the backitup Adapter. A maximum of backups is kept locally, with the oldest being deleted first. The ability to restore the data from these local backups is available on the Hardware Tab.

Zigbee-herdsman debug info

This setting can be used to generate in depth debug logs which include debug information from the Zigbee-Herdsman. Note that it has no effect unless the adapter is running in debug mode. Running the adapter in debug mode with this active will increase the log messages to several 100 MB per day even on small networks.

It is strongly discouraged to run the adapter for extended periods of time with adapter debug and herdsman debug active.

External converters

External converters can be used to enable the adapter to use devices which are not supported by the linked zigbee library. External converters generated by the configurable PTVO Firmware or for use with the zigbee-herdsman-converters can usually be used with minimal modification. Using an external converter requires the file to be placed in the adapters data folder. Once that is done, the filename (including any subfolders) can be entered into the External Converters field. At adapter start, the adapter will report to the iobroker protocol if the file was read, if it was successfully interpreted and if it provides any device description(s).

Global Options

The global options affect the network load and state generation for the network. Some options are more sensible to be used on larger or smaller networks.

• List devices at start: With this set, the adapter will list every single connected device when the adapter is started. Without this setting, only the number of devices is placed written to the log. This setting has little impact based on network size, but listing each device may trigger false positives for unknown devices with large networks.
• Try to read all states at adapter start: With this set, the adapter will trigger a device query for every device on the network. Due to the severe impact on performance, this needs to be delayed by a few seconds. The setting for this is available as read delay in seconds. The delay can be set between 0.1 and 10 seconds.
• Read states at device annouce: with this checked, the adapter will perform a device_query whenever it receives a device announce message unless this message appears while the network is open. Devices with unsuccessful interviews will also not trigger a device query
• use channels for complex exposes This setting has next to no impact currently, but the future impact can already be seen for color capable lightsources, where the states for different color modes (Hue/Saturatuon, RGB, XY) are placed in channels and work in conjunction with a collector state. This method will be used for other like situations in the future, for example for states for defining weekly shedules.

Legacy options

• force start adapter with inconsistent configuration: This setting is provided for legacy purposes only. It forces the Zigbee-Herdsman to start the zigbee network even if the configuration in the adapter and on the coordinator do not match. With the CC2538 based coordinators becoming obsolete, this setting should no longer be needed. The current hardware configuration tab offers all the tools needed to ensure that the configuration between adapter and coordinator match.
• Disable LED for cc2531: This setting allows to turn off the status LED on the cc2531 coordinator. As these are becoming obsolete, this setting has little practical effect and is only provided for legacy reasons.

Operation

Operation of the zigbee adapter is done via a combination of three methods:

• using the states of the devices in the objects tree (Objects entry in Admin). These can also be accessed via scripts, alias, or other automatisation options.
• using the exposed states on the device tiles on the zigbee tab (Zigbee in Admin). The operation and management options on these tiles provide the main adapter controlled interface to the devices.
• using the device manager (Device manager entry in Admin). The device manager offers a subset of capabilities of the zigbee tab, adding the zigbee devices to the unified device management of the ioBroker Admin.

This document focuses on the operation using the zigbee tab.

Device control

The tiles in the adapter UI offer the ability to access a subset of the states generated for every device. Most, if not all general operation should be possible through the device tile, while detail device configuration or reading specific non-standard values may require looking at the states in the object tree.

In addition to the standard device operation, the device tiles offer the ability to perform certain management tasks

• Managing group memberships for devices
• Managing device configuration options, names, icons, as well as triggering a device read or a device reconfiguration.

Groups

Groups are considered devices for normal operation. They can be created and deleted from the zigbee tab. Adding devices to a group is done from the device itself, while removing devices from the group can also be done from the group itself.

Map

The adapter interface can generate a map which displays a snapshot of the known device connections. Note that this is a momentary snapshot and reliant on the devices providing the required data when queried. As not all devices provide the map data, connections may exist which are not shown on the list. Furthermore, the map data is cached for 60 minutes in order to limit network load from reloading the map.

Bindings

Zigbee bindings offer the option of directly connecting Actors (Lights, Outlets, Groups, etc) with Controllers (Remotes, other Lights, etc.). As this connection is formed within the zigbee network, it will provide the ability to control the Actors from the remotes, even if the zigbee Adapter is not active.

Support for bindings depends on adherence of the devices to the zigbee standard. As such, there will be Actors and Controllers which will not allow binding with each other. Alternatively, it is possible that a binding is possible, but no control can be established.

While the adapter is running, it will attempt to catch control commands from the Controller in order to read the result of the control from the Actor afterwards. The effectiveness of this depends on the connection between the Coordinator and the Controller and Actor. Note that it is possible that a connection between Controller and Actor is present while either of them do not communicate with the Coordinator

Device query and payload based operation

The adapter provides a number states which are not part of the device definition, and have no direct link to the device itself. These exist in order to offer additional control option as well as user information:

available

The available state is set based on the communication between the adapter and the device. For devices classified as device by the adapter, this is done by sending a message to the device in regular intervals and checking if the device responds. As long as the device responds to this ping, it will be marked as available. For devices classified as enddevice, this method can not be used as those usually do not respond to communication initiated by the adapter unless the device is awoken beforehand. For these devices the adapter tracks the time between received messages. If no message is received for 25 hrs, the device will be marked as unavailable. This time can be modified using the offline_timeout option. Restarting the adapter does not reset the timeout.

link quality

The link_quality state provides an indication on the strength of the wireless connection to the respective device. The values range from 0 to 255. At adapter start, the link_quality state is initialised with the value 10

Message from Zigbee

The msg_from_zigbee state changes with every message received for the device from the zigbee network. It contains the raw, unfiltered data sent by the device. Use of the information contained in this data requires knowledge of the device sending the data. In some cases - especially for TuYa devices - data is sent as binary blobs instead of clear text messages. Note Update of this state will be tied to a configuration / model/device option in the near future to reduce system load with large zigbee networks.

Device Query

The devie_query state provides the option to trigger a read on every single state which offers the ability to read data from the device. Due to the internal workings of the ZHC library, this method is not optimised to minimise network traffic. As such, triggering the device_query is locked behind a timeout of 10 seconds, which starts once the previous device_query has completed. note depending on the stability of the device communication, a single device query can take up to 5 minutes to complete.

Send Payload

The send_payload state offers device control options independently from the ioBroker object tree. Predefined payloads are:

• configure or reconfigure - trigger a configuration of the device
• interview - trigger an interview of the device.
• checkota or check_ota Trigger a check for availability of new firmware for an OTA update.
• startota or start_ota - Start an OTA firmware update - IF a previous check has found that a firmware update is available
• ota - trigger a complete OTA update cycle for this device (first check if a new firmware is available, and if it is, start the OTA update) In addition to the predefined commands, most of the payloads listed on the respective device description on zigbee2mqtt.io can be sent using this state. Note: there is limited syntax checking on entered payloads. Finding the correct payload for specific actions may require additional information.

ZHC defined options.

The Zigbee-Herdsman-Converters provide a number of options. These are listed together with the possible values and their effect on the device page at zigbee2mqtt.io.

Model specific configuration

Model specific features can be configured using the Local Data tab in the adapter configuration. Configuration done on the model will override the ZHC default values, but can be overridden on the device level. The items which can be configured for the models falls into three different categories.

General configuration items

This includes the default model name and the default model icon. Icons need to to be uploaded to the adapters data folder or a subfolder thereof.## Model specific adapter defined options

resend States

Setting this option (resend_states) forces the adapter to send the current (or given) value of the listed state(s) when the adapter receives a device announce message. Note that setting this option overrides the general setting for Read states at device announce for the affected devices. If device states should be read afterwards, the state device_query needs to be listed explicitly in the option. The device query is performed after all other states have been sent, independent of the order the states are listed in the option. States can be entered in one of 3 ways:

• as flat list of states, i.e. state; brightness; color_temp, split with either a , or a ;. In this case, the value currently stored in the object tree is sent to the device.
• as a flat list of states with values, i.e. state:false,brightness:0,color_temp:150. In this case, the value entered is sent (as string) to the device.
• as a stringified Object, i.e. {"state":false, "brightness":0}

This option is valid and has an effect on any device, but may cause issues with battery powered devices.

Note Values given need to be given in the same format as the ioBroker State expects them.

read Brightness/State

This option (link_states) links various states. Which states can be linked is defined in the state definition. Linked states ensure that if one state is changed, the other state(s) are read from the device after a delay.

It works similarly as the global read brightness and state option. If the global option is set, the model (or device specific) option has no effect.

This option is only available when the state definition contains linkable states. The states to be linked need to be selected in the option.

ignore Delete

This option (ignore_delete)is specifically made for some TuYa devices which will randomly send device_leave messages to the network when they lose power, without actually leaving the network. With this option set, the network will ignore the device_leave message, if it originates from the device, i.e. devices can still be deleted from the network from the adapter.

Note: This option is not tested as I have no tester with the affected device, and there was no response on the request for testing by the person raising the issue.

This is a boolean option. It is only active if it is present and set to true

This option is available for all devices.

legacy device

Setting this option (legacy) triggers the adapter to use the Legacy definition for states and device behaviour. Up to Adapter version 2.0, this was the default method for device integration. For this, the device definition needed to match between Zigbee Adapter and ZHC Library. Starting with adapter version 2.0, the Zigbee Adapter uses the ZHC exposes for device definition, effectively eliminating the need for code changes if a device integration changes in the ZHC, or if devices are added to ZHC.

The legacy definition is provided for compatibility reasons AS IS only. It is no longer maintained by the adapters maintainers. Nor is it part of the testing routine. Use of the legacy integration is at the users risk, and may require extensive use of the modify state option.

This option is available for devices which have a legacy definition.

offline timeout

This option (offline_timeout) changes the amount of time the adapter will let elapse between communicating with any battery powered device before said device is set as offline. It defines the number of hours between communication needed for a device to remain available. Default value (used when the option is not present) is 25 hrs.

This option is available for all battery powered devices.

filter state

This option is currently in development.

Goal of this option (filter_state) is to remove states which the user does not intend to use. Any state listed in this option will not be generated by the adapter. Messages for these states are ignored, but listed if the affected device is listed for device_debug

The option accepts a list of states, split by ';' or ',';

modify state

The option (modify_state) is implemented to enable the user to work around device or model specific peculiarities in message handling, as well as set additional state details through the adapter where the system does not allow manual edit. Typical uses are:

• renaming a state (using the name entry)
• changing the role of a state (using the role entry)
• changing how the state interacts with zigbee messages (using a combination of the prop and setattr option)
• changing how the state is shown on the devices tab (using the category entry - current values in use are config, dimming, color, diagnostic, noshow)

An example for a valid entry is { "power_on_behavior": { "prop":"power_on_behavior_l1","setattr":"power_on_behavior"}}, which fixes an error in the converter, where setting the states sends the payload {"power_on_behavior":<value?}, while reading the state generates a {"power_on_behavior_l1":<value?} payload. By overriding the prop and setattr payload, this issue can be resolved.

This option is available for all devices, but requires an adapter restart after change before it becomes active.

Note: this option is still under development. It does work, but there is no detailed parsing during option entry.

allow query

This option is currently in development.

This option (allow_query) is geared towards providing a device_query button in the adapters interface for devices where the coded automation does not provide it.

meta state

This option (meta_state) is needed for devices where the converter expects the value of (s) specific state(s) to be present in the meta.state information sent to the ZHC together with the device.

Once a device is known to require this option for proper operation, it can be entered as default option in the adapter code. This is currently the case for the following devices:

'S60ZBTPF': 'state'
'WT-A03E': 'sensor'
'BSD-2': 'manual_smoke_alarm,manual_burglar_alarm,broadcast_alarms'

meta message

This option (meta_message) is needed for devices where the converter expects a the value of aspecific state(s) to be present in the meta.message information sent to the ZHC together with the device.

Once a device is known to require this option for proper operation, it can be entered as default option in the adapter code. This is currently the case for the following devices:

'CK-BL702-AL-01': 'brightness'
'CK-BL702-AL-01(7008_Z102LG01-1)': 'brightness'

Device specific configuration

Model specific features can be configured on a per device level using the Local Data tab in the adapter configuration. Configuration done per device will override both any per model configuration and the ZHC default values The items which can be configured for the devices fall into three different categories.

General configuration items

This includes the default model name and the default model icon. Icons need to to be uploaded to the adapters data folder or a subfolder thereof.

ZHC defined options.

The Zigbee-Herdsman-Converters provide a number of options. These are listed together with the possible values and their effect on the device page at zigbee2mqtt.io.

Device specific adapter defined options

Certain of the model specific options are also available as device specific options. These are:

• resend States
• read Brightness/State
• ignore Delete
• offline timeout

Data persistance

Common errors and countermeasures

Debugging device behaviour

Debugging device behaviour relies heavily on taking a very close look at the messages sent from the device to the adapter and vice versa. In order to do this, the adapter has it's own device message recording function. As this designation is unwieldy, it is simply called device debug and is available as its own tab on the sidebar page.

Enabling device debug can be done in one of two ways:

• via the device tile, by turning the bug icon green
• via the state zigbee.x.info.debugmessages, which contains a ; separated list of partial device IEEE addresses for which device debug is active.

It groups clusters of messages by device and direction - the first section being incoming messages which the adapter receives from the device and the second section being outgoing messages which lists messages sent to the device from the adapter - usually triggered by a state change.

Each of these message clusters are by default also sent to the ioBroker protocol. This can be deactivated by switching this button from green to red:

The following buttons control the amount of data displayed in the tab. They are available globally (as seen in the screenshot) and locally for each device and section (in/out)

1. This button switches the filter between displaying all messages and displaying only messages of different type, as defined by the states affected by the message. If used on a section, this button will only affect the respective section.
2. This button collapses and expands the messages for all devices with debug active. If used on a section, this button will only affect the respective section.
3. This button loads new messages from the adapter. For performance reasons, debug messages are not automatically sent to the UI, but need to be requested. This can be done by reloading the UI or using the refresh button. If used on a device section, only messages for this device are refreshed. Note The adapter holds a maximum number of messages at the same time for each device. Therefore, messages may get lost on refresh.
4. This button removes the messages from the queue. Note that this clears the UI and the message queue in the adapter.

incoming messages

Each line will show the incoming zigbee message, the state payload(s) generated for this message, the stateID and value contained in this payload as well as the flags, which may contain SUCCESS, various Flags or error codes.

The button at the front of the line gives access to all messages which belong to this line as well as the exact time this message queue was started, including markdown code tags to post them with proper formatting.

outgoing messages

Each line will show the trigger for the event, the affected endpoint (if applicable), the target ID and value, the generated payload which is sent to the device as well as the flags, which may contain SUCCESS, various Flags or error codes.

The button at the front of the line gives access to all messages which belong to this line as well as the exact time this message queue was started, including markdown code tags to post them with proper formatting.

A more in depth explanation is available here