How to support a new device

You have a new device. When you pair it with your zigbee network, it shows up as an unknown device and there are no states to control / interface with it.

At this stage, we need to distinguish between 2 cases. Identification which of these cases is true can be done by reviewing the documentation on supported devices on zigbee2mqtt.io

The device is not supported by the zigbee-herdsman-converters project

New devices fall into one of two categories:

Devices which are similar to once already implemented:

In this case, it is worth to test if simply adding the device identifier (Zigbee Model and Hardware identifier) as fingerprint in node-modules/zigbee-herdsman-converters/devices.js. If this already succeeds, the only required remaining tasks are: Fork the zigbee-herdsman-converters project, modify the devices.js file, generate a pull request against zigbee-herdsman-converters.

Devices which are completely new or have no likely candidate for a copy:

In this case it is required to follow the documentation for implementing new devices. Note that when using this documentation with ioBroker, a number of steps are required as preparation. Additionally, it is possible to perform some additional actions to speed up the process.

Preparation

• enable the 'zigbee herdsman debug info' in the configuration of the zigbee adapter.
• activate the debug log for the zigbee instance to be used for the test
• wait for the zigbee adapter to restart.
• delete the current log file

Test Part 1

• pair the device
• check the Device card for ieee Address, input clusters, output clusters and endpoints
• Try to operate the device 'at the device', if this is possible. When doing this, keep track of what you did and when to be able to cross-reference that with the logs later

Test Part 2

• navigate to the developer tab on the zigbee adapter configuration
• select the correct device (by ieee Address) and endpoint and attempt to read device fitting attributes from the input cluster and output cluster. This is done by first selecting the cluster and attribute, then selecting foundation and read(0) before pressing the blue run button. Which attributes offer best chance for success depends on the kind of device you want to implement.
• Note the response printed in the log window of the developer tab. These should be -- success (with a value) -- a zigbee error code with a number (example: UNSUPPORTED_ATTRIBUTE) -- a timeout message if the device does not respond at all to the read request

Analysis

During the Test Part 1 you might have to follow the steps described in points 1 and 2 of the linked documentation. Note that when the document asks you to restart zigbee2mqtt, you restart the zigbee adapter instead. Note also that depending on your installation, the location for the required files can either be /opt/iobroker/node_modules/zigbee-herdsman-converters or /opt/iobroker/node_modules/iobroker.zigbee/node_modules/zigbee-herdsman-converters. If both folders exist, please use the second one for your modifications.

In order to analyse the log, you need to:

• download the log as text file
• trim down the log by removing all lines which do NOT include the ieee Address. These are not needed
• cross-reference the log entries with your notes on the actions taken on the device or the developer tab.

The log should contain 'message received' events from the device which usually include a cluster id, a type and some data. These are similar to the information referenced in point 3 in the documentation.

At this point, you can either choose to attempt to implement the device yourself. All the necessary detail information is included in the documentation. Errors you make cannot damage anything - as a worst case, you can remove the zigbee-herdsman-converters project and reinstall the zigbee adapter to get back to the previous version. If you succeed with this, you can then commit your changes to the zigbee-herdsman-converters project.

Note: The documentation on the zigbee2mqtt.io page does not explicitly explain how to handle the exposes, yet exposes will become the main characteristic through which most new devices will be handled in the zigbee adapter. Reading through the documentation on exposes is well worth the time if you intend to implement the device yourself.

If you choose not to do this you can post the results as details to a device support request issue. Depending on the scope of data and the type of device there is a decent chance that a developer will pick this information up and attempt to commit this to the zigbee-herdsman-converters project.

The device is supported by the zigbee-herdsman-project and not explicitly defined in the zigbee adapter

This case is similar to the above. The key difference is presence of No converter available for '_device name_' with cluster '_some cluster_' messages. If these messages exist the device is sending data which the zigbee-herdsman-converters cannot or do not handle. For these messages, refer to the paragraph about handling devices which are not supported by the project, and only look to the specific messages. If these messages do not appear but you are still missing states to use the device the device either needs to be defined explicitly in the zigbee adapter because it offers functions which cannot easily be handled by the "expose" mechanic, or the respective expose is not handled correctly.

Both cases require a more in depth programming knowledge, so the safe bet would be to post a device support issue with the information gained from the analysis.