Device messaging debug - ioBroker/ioBroker.zigbee GitHub Wiki

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.

Note that using the device tile will fill said state with the full IEEE of the desired device. If a device has active device debug due to a partial IEEE match with the state zigbee.x.info.debugmessages, the bug icon will show orange.

The debug interface and its parts

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 section of the UI consists of a header line and a number of content lines.

global header

the global header simply contains the text Debug information by device, as well as a number of buttons which affect all sections and messages displayed.

Each of the displayed 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)

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.
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.
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.
This button removes the messages from the queue. Note that this clears the UI and the message queue in the adapter.

device header

The device header contains device information and a device specific refresh and delete button.

Name of the device
IEEE of the device
name of the device model
icon of the devive. (note the icon of the device is a link to the model page at zigbee2mqtt.io)

Within the device section, there are two subsections:

incoming messages

The header line for the incoming messages contains buttons to filter and collapse/expand this sections 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.

For devices which are well supported and working, this section should have SUCCESS flags in all lines. This means that all messages received from the device are fully handled and generate data which is sent to the various device states. There are two common cases where error flags may appear.

If a state payload does not match to any state available, ID will show no state in red, and value will show no value in red. This is often mixed in with additional states for which information is contained in the same zigbee payload, which is why it will show SUCCESS. If the payload is empty, there is nothing amiss. If there is a payload, the exposed states do not necessaryly match the results from the converters. This may require a tweak in the zigbee adapter.
A line showing the error NOCONV indicates that the zigbee payload contains data which could not be matched to any converter provided by the Zigbee-Herdsman-Converters library. As long as the normal device operation is fine, this can be ignored.

If no lines show up for a device, the adapter does not receive any message from the respective device. This can indicate one of 3 things:

a broken or disconnected devivce - this requires intervention on the device level. To see if a device is disconnected, send a message to the device (via a state change) and then check the outgoing section for results.
a device which does not report anything by itself - this may be absolutely normal, depending on the device
a device lacks the required device configuration in order to report data - this can be fixed by performing a reconfigure from the device tile.

Posting the data provided by the button at the front of the line will assist greatly in determining what exactly is happening.

outgoing messages

The header line for the outgoing messages contains buttons to filter and collapse/expand this sections 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.

For devices which are well supported and connected to the adapter, this section should have SUCCESS flags in all lines. This means that all messages sent to the device are fully handled. There are three distictly different error cases which can show up here:

errors in the device definition in the zigbee-herdsman-converters or the zigbee adapter. This usually shows up as a pair ID/Value not generating a proper zigbee payload, and/or an error message
errors sending data to the device, usually with an error code EXSET - this indicates that the payload could not be sent to the device.
There are cases where the debug interface shows up to 4 codes (01,02,03,04) but neither SUCCESS nor an error flag. This is an indicator that the communication is not yet complete. It is likely, hoewever, that this will lead in an EXSET error when the communication with the device times out.

As with the incoming messages, posting the data provided by the button at the front of the line will assist greatly in determining what exactly is happening.