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)

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.

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.

A number of options exist to fine tune the adapter behaviour

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.

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.

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 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).

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.

• 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.

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.

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.

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