Connecting Hue bulbs to ZHA

[ljorg]

Feedback

The documentation states that removing Hue bulbs from the Hue bridge is not enough to add them to ZHA, and that they also need to be factory reset. This does not seem to be the case anymore, and I have just removed three bulbs from the Hue bridge and could instantly add them to ZHA. Other users report the same in the forum (don't have any links, but easily searchable).

URL

https://www.home-assistant.io/integrations/zha/

Version

2023.8.4

Additional information

No response

[home-assistant]

Hey there @dmulcahey, @Adminiuga, @puddly, mind taking a look at this feedback as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of zha can trigger bot actions by commenting:

• @home-assistant close Closes the feedback.
• @home-assistant rename Awesome new title Renames the feedback.
• @home-assistant reopen Reopen the feedback.
• @home-assistant unassign zha Removes the current integration label and assignees on the feedback, add the integration domain after the command.

[Hedda]

The documentation states that removing Hue bulbs from the Hue bridge is not enough to add them to ZHA, and that they also need to be factory reset.

@ljorg What specifically do you think is needed or should be changed in the general section of ZHA integration documentation?

• https://www.home-assistant.io/integrations/zha#adding-devices
  • https://www.home-assistant.io/integrations/zha#using-router-devices-to-add-more-devices

While it does currently say there "Reset your Zigbee devices to factory default settings according to the device instructions provided by the manufacturer" it does not specifically state that it is required, (that is only mentioned under the troubleshooting section).

That is, I do not think anyone who is not having problems will read/find that as it is only mentioned under the "Troubleshooting" section in its subsection for "[Add Philips Hue bulbs that have previously been added to another bridge", and there it does not essence say that it "required",

• https://www.home-assistant.io/integrations/zha#troubleshooting
  • https://www.home-assistant.io/integrations/zha#add-philips-hue-bulbs-that-have-previously-been-added-to-another-bridge

If you as a user only read the normal sections that are not under troubleshooting then you will only find the section about "Adding devices" (as well as "Using router devices to add more devices") and it does not say actually state that resetting your Zigbee devices to factory default configuration is "required", not do those sections even mention Philips Hue devices specifically.

• https://www.home-assistant.io/integrations/zha#adding-devices
  • https://www.home-assistant.io/integrations/zha#using-router-devices-to-add-more-devices

The fact is that if you have properly removed Philips Hue branded devices (like lightbulbs) from the Philips Hue Bridge using their app (as that will in practice un-pair/un-join the device which actually does reset the configuration on the device), but if you do not manually remove the Philips Hue device (like when for example your Philips Hue Bridge is broken and now dead so you can no longer remove it the app and have it community can that fact with the device) then you do need to follow the manufacturer's instructions for factory reset the device or else it will still remember that it joined/paired to the old Philips Hue Bridge.

So the question is, do you still think that the ZHA documentation needs further guidelines on it or can this issue be closed?

By the way, please note that the ZHA integration documentation will always be in need of more people helping out to improve it and you can do so yourself via GitHub web interface without opening an issue. It is relatively easy for anyone to help improve the ZHA integration documentation yourself, it is just a text-file in markdown format that can be changed via the GitHub web interface if you have an account (just go do the zha.markdown file in the current branch and click “Edit the file in your fork of this project”, change and click “commit changes” then “submit pull request”, you can look at the other older pull requests for how they should be formatted). Suggest some other people here who might also be interested in helping update the other usage and troubleshooting-related sections in ZHA documentation which could all be improved for better readability. Suggest you help edit to this page yourself (click fork and then edit the zha.markdown file to change documentation and get flow for submitting pull request):

https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/zha.markdown

https://github.com/home-assistant/home-assistant.io/blob/current/source/_integrations/zha.markdown

PS: Also be aware of inofficial community guides maintained in the forum by users like these:

• https://community.home-assistant.io/t/migrating-from-a-philips-hue-bridge-to-skyconnect/620862

• https://community.home-assistant.io/t/solution-workaround-for-zigbee-zha-devices-stuck-in-interview-complete-configuring/777247

• https://community.home-assistant.io/t/is-zigbee-right-for-you/693403

• https://community.home-assistant.io/t/zigbee-buyers-guide/654695

• https://community.home-assistant.io/t/zigbee-1-where-can-i-find-a-list-of-supported-devices/706526

• https://community.home-assistant.io/t/mains-powered-zigbee-devices-that-arent-routers/458500

• https://community.home-assistant.io/t/zigbee-network-optimization-a-how-to-guide-for-avoiding-radio-frequency-interference-adding-zigbee-router-devices-repeaters-extenders-to-get-a-stable-zigbee-network-mesh-with-best-possible-range-and-coverage-by-fully-utilizing-zigbee-mesh-networking/515752

• https://community.home-assistant.io/t/zigbee-guide-how-to-setup-local-custom-device-handler-quirks-in-zha-integration/683473

• https://community.home-assistant.io/t/not-many-people-know-that-a-random-collection-of-zigbee-trivia/656267