Home
|
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 statesat 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 asread 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 adevice_querywhenever it receives adevice announcemessage unless this message appears while the network is open. Devices with unsuccessful interviews will also not trigger adevice query -
use channels for complex exposesThis 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.