Don’t forget that the first post in a community guide is a wiki - feel free to add to it or correct it.
This guide was written and tested these versions but should also work similarly with later versions:
Home Assistant 2023.8.4
Supervisor 2023.09.2
Operating System 10.5
Frontend 20230911.0 - latest
Background
Until recently Philips Hue devices have been controlled locally through a bridge, but the company has now started asking users to open a cloud account, which will ultimately hold details of all their activity. (At the time of writing it only contains basic information about the bridge itself.)
The rationale is that this will allow all users to control their Hue devices remotely and securely. HA users already can, and for many in the community, there are obvious privacy concerns. There is a blog post about it here. The issue has prompted some to bite the bullet and fully move/migrate all their Philips Hue products (and other Zigbee devices) to the native ZHA (Zigbee Home Automation) integration that is built-into Home Assistant.
Requirements
This post assumes that:
- You have been using a Philips Hue Bridge V2 (the square one). If you have one of the round V1 Philips Hue Bridges (still supported by HA, but not by Philips) none of this is necessary as they no longer have internet access. It is however still worth considering moving to the ZHA integratuion as Philips Hue Bridge v1 is no longer receiving security updates.
- Your lights have been set up using the official Hue app from Philips.
- You are currently using the Philips Hue integration in HA
- You have purchased a Zigbee Coordinator USB adapter recommended for ZHA integration.
- Home Assistant SkyConnect USB dongle is the “official” device from Nabu Casa and is highly recommended since not only do you get a plug-and-play configuration but also easy to update its firmware if using a Home Assistant Operating System installation (and as a bonus the profit from it goes to pay developers working on improving Home Assistant).
Limitations
This is a summary of the migration process, which is straightforward but may be long-winded as you have to move devices one by one (allow a whole evening if you have a lot of lights). You can run Philips Hue Bridge with the Hue integration and the ZHA integration with a Zigbee Coordinator USB adapter side-by-side if you want to take a more leisurely test-as-you-go approach - but a Zigbee device can’t be joined to both Zigbee networks at the same time, (Zigbee devices can only be paired with a single Zigbee gateway/bridge/hub/controller).
What you be aware of before getting started
Zigbee is a low power radio protocol which relies heavily on its mesh networking technology to automatically workaround and overcome the limitations of the weak radios in each device. In hardware terms, it usually consists of a Zigbee Coordinator USB radio adapter plugged directly into the machine running Home Assistant, and a mixture of other devices, (such as example lightbulbs, motion sensors and buttons), where most of your mains-powered products act as “Zigbee Router” devices that will work as signal-repeaters/extenders, while your batter-powered devices are “Zigbee End Devices” and as such do not forward on any communication-messages to other devices.
Important here is to be aware that Zigbee messages and commands are relayed back and forth to Zigbee Coordinator USB radio adapter and the communication is indirect through a chain of intermediate devices (e.i. your Zigbee Router devices). This makes a network mesh with many Zigbee Router devices very resilient since there are many possible routes for the communication messages to take, and although the signal from each radio is weak the communication messages can find their way round walls and other obstructions as long as you have enough Zigbee Router devices. Zigbee communication messages can also cover large areas and longer distances, provided there are enough Zigbee Router devices that can distribute the traffic along the way. If you live in a modern building with thin walls then this is not something you probably do not have to worry about, but if you are living in a home with thick or dense building materials then you have to remember to add enough Zigbee Router devices at not to far distances so that all communication-messages can go through without problems.
If you have Philips Hue lights then yo are already using a Zigbee network, so there’s no reason why a Zigbee Coordinator USB adapter dongle shouldn’t work just as well (although the antenna in the Hue hub is probably better than the one in your new Zigbee Coordinator USB adapter dongle, so some tweaking may be necessary); on the other hand, if you’re already having connection problems with Hue, you’ll probably get them with your new Zigbee Coordinator USB adapter dongle too.
Most problems are caused by EMF (electromagnetic field) interference from other electrical equipment that is placed too close to Zigbee products - you need to look into this before you tackle the move. There’s a post on the subject here. If your Hue network is problem-free it may be a good idea to position the Zigbee Coordinator USB adapter dongle on the end of a long USB extension cable away from the computer running Home Assistant and any other electric appliances/peripherals/cables, (but preferably close to where you kept your old Philips Hue Bridge if you can).
To forward communication messages and relay commands, Zigbee Router devices have to be mains-powered, connected and always on. In the Hue ecosystem lightbulbs do the heavy lifting; battery-powered devices like buttons and motion sensors can only come at the end of the chain. In the image below they are the round outlying nodes connected by a single route. (The ovals are mains-powered devices relaying signals and the co-ordinator is the rectangle in the centre.)
Setup
Note! There are alternative instructions for setting up Home Assistant SkyConnect USB dongle here, and the ZHA ingeration documentation has more details on available configuration options here.
- Using the included or other USB extension cable, connect the Zigbee radio USB dongle to a USB port on your Home Assistant host machine.
- It should be discovered automatically, and you will be invited to configure the ZHA integration.
- Click “configure” and follow the instructions to set up the co-ordinator. To begin with this will be the only device on the network and you will return to it to set up each additional bulb, sensor or button.
- If you are using another Zigbee Coordinator USB adapter on the ZHA list of recommended Zigbee adapters but is not not the list of USB discoverable adapters then you will have click on “ADD INTEGRATION” to search for and install the “Zigbee Home Automation” integration then configure the settings for that adapter (choosing the right radio type, etc. for what you purchased instead).
- Click “configure” and follow the instructions to set up the co-ordinator. To begin with this will be the only device on the network and you will return to it to set up each additional bulb, sensor or button.
Adding devices (paring/joining a device)
Adding devices to the network is very straightforward. For each device in turn:
- Put it into “pairing mode”
- Wait for it to be discovered by the new Zigbee network
- Adjust its new ZHA configuration to match the old Hue one so that automations etc. keep running
To put a device into pairing mode, simply delete it in the Philips Hue app - there should be a delete button on the device setup page. This will also remove it from the Philips Hue integration in HA. (If for some reason this doesn’t work other ways of switching on pairing mode are discussed below.)
In HA, open the ZHA integration (Settings | Devices & Services | Integrations), then the co-ordinator and click on Add devices via this device.
After 30 seconds or so it will be discovered by HA and added to the ZHA card.
A good strategy is to move from room to room, working outwards from the Zigbee Coordinator USB radio adapter, keeping a balance of mains- and battery-powered devices on both the old and the new network.
So try to move/migration by first first migrating most of your mains-powered devices that you know act as “Zigbee Router” devices, and beginning with the ones that are located closest to the Zigbee Coordinator USB radio adapter and go on from there. That way you will build those devices as a backbone in your new Zigbee network mesh. Preferably only after migrating all or most of your mains-powered devices should you migrate any battery-powered devices or other devices that you know are Zigbee End Devices. FYI, it is well known within the community that Sengled lightbulbs and all non-neatutral/2-wire dimmers/switches, as well as most Zemismart switches are not Zigbee Router devices.
It is however not a good idea to leave all your battery-powered devices until the very last. Once you have deleted all the lightbulbs from the Hue app, any left over movement sensors and buttons will show as “Not accessible” if there is at least not some main-powered devices left in range because the network supporting them has been removed, and you will have to put them in pairing mode using another method.
Tip: If you have problems pairing a device, do not move it closer to the Zigbee Coordinator USB radio adapter. Even though that approach is recommended by some manufacturers, the general best practice if that Zigbee devices should be paired in the location where it’s going to be used.
Other ways to put devices into pairing mode
Most battery powered Hue devices have a pinhole reset button. For motion sensors this is on the back, at the top.
For other devices it is inside the battery compartment. The exception is the outdoor motion sensor, which has to be waterproof. This has a press button on the back (you have to take it off the wall to access it).
In each case, hold down the button for 10 seconds, until the LED turns green then starts to flash orange and green.
For bulbs, you need a Hue dimmer switch. Turn the light on, then hold the switch as close as you can to it. Press and hold the top and bottom buttons on the switch together for about 10 seconds or until the bulb flashes. It’s now in pairing mode.
Naming
Once you have moved a device to the SkyConnect network, you can give it a friendly name by clicking on the edit icon, top right on the device screen.
If you don’t do this all your devices will be named after the Hue model number and it will be hard to tell them apart. When you click “save” a dialogue box will pop up asking if you want to rename the device’s entities too. Unless you have a good reason to do this, click “no”.
If you have already been using your devices via the Hue bridge and the Philips Hue integration, the associated entities will probably be included in a lot of automations and scripts. Take the time now to edit the new entity IDs to make them the same as the old ones - that way your automations should carry on working as before.
If you were unable to delete a device in the Hue app you may find that the old entities still exist in HA, and you are unable to rename the new ones. To deal with this you can rename the old entities temporarily - to something like sensor.bathroom_dimmer_switch_battery_old for example. Old entities, including renamed ones, will be removed when you finally delete Philips Hue integration.
If you have been using device IDs in your automations… Sorry, you’re out of luck - you’re going to have to edit every one to put in the new device ID.
You can now delete the Philips Hue integration in HA (any left over entities will be deleted too) and unplug the Hue bridge.
Groups
Devices in Home Assistant can be grouped together using a helper, but they are still controlled as separate entities - if you watch carefully grouped lights come on one at a time. If you wish you can group zigbee devices so that they are controlled as a single entity.
Open the co-ordinator and click on Add devices via this device as described above, then click on the Groups tab at the top of the page.
Click on Create group, give the group a name, select the devices you want to include and click on Create group at the bottom of the screen.
The new group will be added as an entity on the Zigbee co-ordinator page, where you can edit name, icon and entity id as required. Notice that a new group will not be created unless it contains at least two devices.
A warning about Zigbee groups
Group commands are network-wide broadcasts that are bounced back and forth between all devices to make sure every possible group member has a chance to “hear” the message. It is not a good idea to issue several in quick succession - for example in an automation - as this may swamp the network. Better to address the devices individually, or use HA groups.
Binding
You can bind a dimmer switch or button to a light or group of lights so that commands pass directly between the two. This means that the button or switch will continue functioning even when Home Assistant is down. (Note: the method below has only been tested with the RWL022 dimmer switch - earlier models may not work.)
Open the dimmer switch page in Devices & Services | Devices, click on the three dots next to Reconfigure and select Manage zigbee device from the dropdown list.
Click on the Bindings tab.
To bind with an individual light select one from the Bindable devices dropdown. To bind with a group, select one from the Bindable groups dropdown and tick the kind of binding you want (On/Off at least, but if you’re not sure, you can tick them all).
Important: before you click Bind press the buttons on the dimmer switch a few times to wake it up.
The switch will now control the light, even without Home Assistant.
Updating SkyConnect firmware
The simplest way to do this is with the Silicon Labs Flasher add-on, which defaults to the latest firmware for SkyConnect.
- Do a full backup of HA (just in case)
- Download the flasher from the add-on store and install it
- In Devices & Services | Integrations, disable ZHA
- Make sure the SkyConnect option is selected in the flasher configuration page
- Click Start on the Info page.
The process should take 30 seconds or so (you can follow progress on the log page) and the flasher will stop when it has finished. You can then enable ZHA again.
SML001 and SML002 motion sensors
There is a known issue with older Hue motion sensors - they disconnect repeatedly and can be hard to pair with the network again. This is because they are trying to reconnect as new devices, which the network will not allow. There is a simple fix for this problem here.
Oddities
Entities derived from the ZHA integration will not be exactly the same as the old Hue ones. Here are a few things to watch out for:
-
When you pair a Hue motion sensor via ZHA you will see an additional binary sensor entity “Occupancy”. This is the one that you should use in automations. The entity “Motion” doesn’t seem to do anything and can be disabled.
-
Using the Philips Hue integration, there were switch entities which allowed you to turn off motion detection. These don’t seem to exist in ZHA.
