Recording device messages

Recording device messages

Due to various reasons, the ioBroker may offer states for devices which are not updated or which will not generate any response by the device itself. Debugging this behaviour usually requires access to the device. As the devices available to the developers are limited, they need to rely on assistance from device owners to obtain the required information. This page is supposed to provide a step by step description on how to record the required messages.

Note that this page is mainly for situations where a device is recognised and most of its states work as desired, with only a limited number of states not operating as desired.

Initial information

Before starting to record anything, the following pieces of information should be recorded:

• Adapter version used for this test
• A list of affected states, each with their ID (id), Name (common.name), type (common.type) and if reading and/or writing is allowed (common.read, common.write). The information can be read from the admin by selecting the edit button in the object list.
• A description of the desired functional compared to the current function
• the device IEEE Address, i.e. the 10 digit hex number used to identify the device in the object tree (0xaabbccddeeff0055)

Note that this procedure does not require any specific adapter version or for the device to be deleted and paired anew. It also requires no knowledge of programming or internal working of the adapter. It does require access to a text editor which can handle large log files - Microsoft Notepad may not be good enough for this.

Preparation

Recording the device messages is done using the ioBroker log file. Unless the log file is used for any kind of direct monitoring / recording it is advised to delete the log file before starting this procedure and once the information has been extracted from the log file.

• Stop the zigbee adapter.
• Change the zigbee adapter to debug mode (You may need to enable the expert mode in the instance list to get access to the adapter log level)
• delete the log file
• start the zigbee adapter.
• open the log view
• enter the last 4 digits from the IEEE number as Message filter

Recording

For the first half of the test attempt to trigger device changes / device messages. With battery powered devices, this can usually be done by forcing a state change (e.g. holding a temperature sensor in your hand to force it to report a temperature, pushing a button on a remote or similar). Alternatively, most battery powered devices will wake if their pairing button is pressed for a short period of time (less than two seconds). Devices which are connected to power can be forced to send information by disconnecting and reconnecting them from power. The key point at this stage is to record which actions result in a message from this device being recorded in the log file. If the mismatch between expected and provided behaviour is linked to on device controls, these controls need also be activated to record any messages they generate. As a rule of thumb - activating more controls and checking more states is preferable over limiting the test to the bare minimum.

Keeping a separate (paper?) log of the actions taken will help with analysing the log entries later.

The second half of the test is meant to test the other direction. For this test, please modify the states in question to trigger a 'state change' event. These will always generate a log entry.

Obtaining the log

With the actual recording complete, you now need to obtain the complete log file. Due to limitations of the in built log viewer, copying text from the log view of the iobroker admin does not provide a complete log. Therefore, it is vital that you use the 'download log' (log herunterladen) button to obtain the entire log file. Note that this file will include messages from all adapters and devices.

In order to limit the log file size, it is advisable to set the zigbee adapter back to 'info' before downloading the log.

With the log file downloaded (saved to disk and opened in a text editor), it needs to be stripped of unwanted information.

Filtering the log

As a first step, you need to remove all log entries which are not generated by the zigbee adapter. Assuming your zigbee adapter is running as instance 0, you should delete any line which does not list zigbee.0 as its source. The source of any log entry is printed as 3rd item after timestamp and message severity. If the log contains any lines which do not start with timestamp and severity of the message, these may safely be deleted at this point too. They can be generated when errors are raised by an adapter and are usually not required in this case.

Once this is done, the log should only contain messages generated by the zigbee adapter. Depending on the number of your zigbee devices, it may contain a lot of messages which are not connected to the device in question. These must also be filtered out. As some messages do not (yet) include information to the connected device, the next step is to remove all messages which include an IEEE address which does not match the device in question.

Note: If you want to record messages for more than one device you need to generate two separate log files with the confirmed messages for each of the two devices. It is advisable to record the device messages in two separate procedures to correctly match the messages to the devices.

Once all messages which clearly do not address the affected device are removed the final step is to eliminate unnecessary "Publish" messages. As these messages do not indicate the device which they are generated by, these need to be identified by matching the content of the message with preceding "message received" messages.

Final notes

Please do not forget to return the zigbee adapter to 'info' logging mode. With debug activated, the adapter will generate a lot of information. A log for a full day can easily exceed 2 GB in size for larger zigbee networks.

For especially stubborn devices, activating the lower level logging by checking the "zigbee herdsman debug info" checkbox in the adapter configuration before enabling debug mode may be beneficial, but be advised that this will increase the size of the log file significantly. Running the adapter for a long time with debug and zigbee herdsman debug info activated is not advisable.