Here is Kenneth’s guide to deCONZ high level debugging
I see many questions and answers related to deCONZ issues where it is clear that is may not be so easy to understand what is happening where.
There are many interfaces to keep track of and it is important to know them when you want to debug a problem.
In Text graphics the chain looks like this
Devices <-> Conbee USB stick <-> deCONZ software <-> deCONZ Home Assistant Integration <-> Home Assistant “Engine”
Instead of the Conbee you may have a Raspbee hat but it works the same except for the USB stuff and the USB device name will be different.
The Device to Conbee interface is a radio interface running on 2.4 GHz in the same spectrum as Wifi and Bluetooth.
Problems with the radio interface will manifest themselves as
- Unstable and occasionally slow connection between devices and Home Assistant
- One or few devices showing unavailable at times
Problems with radio interface will normally NOT BE
- All devices unavailable
- Conbee stick not available
The solutions for radio problems are:
- Computers create a lot of electromagnetic noise around them and this can make it difficult for the Conbee to receive the more weak signals from battery devices and devices that are far away. The recommendation is to connect the Conbee to the computer via a 1 meter long USB cable.
- You can improve the range of the Conbee by placing it so radio waves meet less obstacles from furniture etc. Place the computer in a central position
- Make sure you have several mains powered devices that work as routers (bulbs, smartsockets, or zigbee repeaters)
- Make sure all Zigbee mains devices are powered 24/7. If you turn off a device on the wall socket or a lamp switch, it will take time for the Zigbee network to heal and you will experience bad connection. Especially battery powered device can take time to work again if their previous partner is suddenly not there
Wifi and Zigbee share the spectrum. The channel numbers are very different from each other. If you hard code your Wifi router and access points to channel 1 or channel 6 and set Zigbee to channel 25 then there is no overlap at all. This can help with interference problems. At least from your own Wifi network. If it is your neighbors Wifi that gives interference then try and move the computer with the Conbee to a different place in the house away from the interferer.
If a device is permanently not available then it may be the pairing that has gone wrong, maybe because of a bug in the device. Then the cure is to try to re-pair the device. First try without resetting the device. If not reset the device and pair it. If it still does not work then the device is probably broken. You did check the battery, right?
The Conbee to Computer interface is via a USB port.
If deCONZ cannot see the USB stick then there are two possibilities
- The stick is broken. It is a rare fault but it will happen
- You run Raspberry Pi 4 with a USB disk connected to a USB3 port – this is known to not work. Google for more info on this special case. Moving disk to USB2 normally fixes it (and slows down disk access)
- The device name is wrong - this is much more likely to be the issue
The Conbee Stick will always be discovered as a /dev/ttyACM# device where # is usually 0. If you have more than one device that registers as /dev/ttyACM… then you will experience that after a boot of the computer ttyACM0 and ttyACM1 will have swapped places. The typical situation is that you have both a Conbee II stick and an Z-wave stick like the Aeotec stick.
In modern distributions the device manager (udev) will create symbolic links to the devices that are predictable. Something like /dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE1961234-if00
There is a problem however. The current version of the deCONZ Addon does not work reliably with this symbolic link. On my installation it works 8 out of 10 times you start the Addon.
There has been one attempt to fix this but it did not cure the problem. The Addon is as I write this still unstable in this respect.
My advice for the device name problem is
- If you only have one device that is registered as /dev/ttyACM0 then use that and you are good.
- If you have two /dev/ttyACM devices then you have these choices
- Use the /dev/ttyACM device that is most likely to be chosen at boots and use this in the Addon settings. Reboot again when it goes wrong
- Use the /dev/serial/by-id/… link and be prepared to restart the Addon several times manually until you succeed.
- If you are on a computer with a full Ubuntu/Debian based operating system (not HassOS) you can add the Dresden Elektronik repository to your apt environment and install deCONZ via apt. That is what I ended up doing. I got tired with the problems with the Addon. deCONZ running on bare metal auto discovers the Conbee device and does not care if the device changes name after a reboot
Note that seen from Home Assistant a missing connection between deCONZ and the Conbee will appear as all devices not available. This is the same symptom as deCONZ not running, or broken link between the Home Assistant Integration and deCONZ.
To check, open Phoscon - and verify that it can connect to the Conbee stick.
If you run the Addon check that it is running.
If you run deCONZ installed from apt - check that the deCONZ daemon is running. It is called deCONZ
OK we assume that you have deCONZ running and it can see the USB Stick.
Next interface is between the Home Assistant Integration and deCONZ
It is important to understand the difference between the deCONZ Integration and the deCONZ Addon.
deCONZ is the software written by Dresden Elektronik. The API portion of it is open source. Home Assistant developers have put this in an Addon (a docker image that the Home Assistant supervisor starts). The deCONZ Integration is written by the Home Assistant community and part of Home Assistant.
You can install deCONZ on a different computer on your network. It does not have to be the Home Assistant Addon. No matter if you run deCONZ as the Addon, or on same computer in the host OS or on a different remote computer, the connection type is the same. The Home Assistant Deconz integration connects via TCP/IP network (physical or virtual) to the deCONZ software. If you can see and confirm that deCONZ is running, and it can see the USB stick in Phoscon, then the problem must be that the Integration does not connect to deCONZ.
Note that part of the initial pairing of the Integration with deCONZ you need to create an API key. In Phoscon you go to the Gateway settings and find the button Authenticate App. Then you have 60 seconds to trigger the Integration to connect. If for some reason you get something reset that you should not have then this can be a thing to check
If the integration suddenly stops connecting to deCONZ after a restart or an upgrade can be more tricky to debug. It should show up in your Home Assistant log if this link is broken. Many people have reported problems with recent updates to the Addon but I have not see any clear single root cause and I guess most people just remove the integration and add it again and clean up the mess it makes when device names are going back to the defaults
If you want to go the route of trying to re-install the Integration then the best advice is to walk through all deCONZ sourced devices in the Home Assistant Integration and check if their names match the names in Phoscon. If not - rename the device to match in Phoscon. This way when you remove the integration and add it again, most names should become the same. If you renamed entities instead, then consider using this for the naming in Phoscon. After all it is the entity names you want preserved as they are used in your automations and in the Lovelace cards
Long post – but I hope it can be a reference to be used when people have one of the common issues in the all too long official deCONZ thread.