Debugging 101 – Setup issues.

This page describes how we try to help others debug. This is a small path we follow with users to figure out what’s wrong. We write this so others can figure issues out themselves and see whats wrong with their setup. We often first link wiki articles on known issues. It is always useful to see if the issue is already described. For example, users reporting that devices have funny names we always ask if they can provide a screenshot of the basic cluster and then search the Github for the Model identifier / Manufacturer name. Most of the time if a device has a Hex name, it isn’t supported yet. It could also be that a device is supported but not paired fully. In that case, this page helps with that.

Step 1: Did anything change?

The first step is always to determine if something has changed. Especially with setups being stable for a long time, it could be wise to see if you changed something. Best practice is to undo the change and see if it fixes things. If it doesn’t, let’s move on.

Step 2: Gather logs.

If stuff stops working, it’s generally a good idea to gather logs. We can get logs in 2 ways:

Option 1: To get debug logs in a GUI installation, open deCONZ and click Help. After that, click Debug View. The following debug levels need to be enabled for proper logging: INFO, INFO_L2, ERROR, ERROR_L2, APS, APS_L2. Please note that in the HA Addon and Docker webVNC you can't copy paste. You need to use a Native VNC Client. HA Addon How-To , Docker Environment Vars.

Option 2: To get debug logs in a headless installation / ssh session, use the following commands: sudo systemctl stop deconz-gui sudo systemctl stop deconz /usr/bin/deCONZ -platform minimal --dbg-aps=2 --dbg-info=2 --dbg-error=2 | tee debug.txt

When done, exit the process with CTRL+C. You can now start the systemctl service again. Your logs will be printed in the console, as well as saved to a file named debug.txt in the current directory. Be sure to capture at least a few minutes worth of logs. When sharing these logs, DO NOT attempt to paste them into a channel. Instead use a pastebin service such as this or this.

Afterwards, don't forget to disable logging. This is especially important when running off an SD card, as the debug logging will cause unnessecary writes, and might shorten the life of your media.

We generally ask for 2 a 3 minutes of logging. In case of a device not joining, We always ask to include logging while trying to pair. This often gives a clear example.

Step 3: Process the logs.

Depending on the issues,We often look for error codes. We just Search for error codes listed here: https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Zigbee-Error-Codes-in-the-Log Just doing an page search trough them with each code. There’s also codes not listed there(as they are rare) so we also search for “error” in the logs. Often this gives a good idea. If you see a of 0xD0, it is helpful to check the deCONZ GUI and see the connections around the device that is giving them. Perhaps there’s some weak connections in your setup and that’s why stuff is dropping out. If you see a lot of 0xE1, you might need to add an extension cable as it is interference.

TODO: See indications of new devices when pairing fails for whatever reason.

An sample of a new device inclusion(log levels INFO/INFO_L2/APS/APS_L2/ZDP.

19:26:26:846 unknown node 0x7CB03EAA0A04A5A4 (0xE0C7), lqi: 252
19:26:26:848 APS-DATA.indication from unknown node 0x7CB03EAA0A04A5A4
19:26:26:853 void deCONZ::zmNode::setFetched(deCONZ::RequestId, bool) fetched item: 2, node: 0xE0C7
19:26:26:855 void deCONZ::zmNode::setFetched(deCONZ::RequestId, bool) fetched item: 1, node: 0xE0C7
19:26:26:856 new node - ext: 0x7cb03eaa0a04a5a4, nwk: 0xE0C7
19:26:26:858 device announce 0x7CB03EAA0A04A5A4 (0xE0C7) mac capabilities 0x8E
19:26:26:859 device announce 0x7CB03EAA0A04A5A4 (0xE0C7) mac capabilities 0x8E
19:26:26:866 ZDP get node descriptor for 0xE0C7
19:26:26:867 ZDP get node descriptor for 0xE0C7
19:26:27:138 void deCONZ::zmNode::setFetched(deCONZ::RequestId, bool) fetched item: 3, node: 0xE0C7
19:26:27:140 DB pushZdpDescriptorDb()
19:26:27:141 DB save zll database items 0x00000881
19:26:27:162 DB sql exec UPDATE devices SET nwk = 57543 WHERE mac = '7c:b0:3e:aa:0a:04:a5:a4';INSERT INTO devices (mac,nwk,timestamp) SELECT '7c:b0:3e:aa:0a:04:a5:a4', 57543, strftime('%s','now') WHERE (SELECT changes() = 0);
19:26:27:182 DB saved in 41 ms
19:26:27:184 DB UPDATE device_descriptors SET data = x'01408eaabb4000000000000003', timestamp = 1641407187 WHERE device_id = (SELECT id FROM devices WHERE mac = '7c:b0:3e:aa:0a:04:a5:a4') AND endpoint = 0 AND type = 2

This shows that there's a new device seen while pairing. If you don't see this in your log while pairing, perhaps the device isn't in pairing mode.

concluding

If we am sure it's a bug that can be reproduced, we refer people to the github. If it is not clear, we always redirect them to the forums. We really want to keep the Github clear of user questions and if we can't be sure, it's best to ask on the forums.