Getting Philips Hue dimmer switches working with Home Assistant ZHA

Moving my remaining IKEA and Innr bulbs from Philips Hue to Home Assistant’s Zigbee Home Automation (ZHA) integration was a bit step, but it was only part of the job of consolidating my Zigbee networks. I also needed to migrate the Philips Hue dimmer switches that controlled some of the lights.

I have two RWL021 dimmers. One controls six IKEA TRÅDFRI GU10 spotlights in my loft room, while the other controls an Innr bulb in my son’s bedroom. Both are now working through ZHA, although getting all four buttons to behave correctly required some changes to an existing Home Assistant automation blueprint.

Pairing the dimmer

After removing the dimmer from the Hue Bridge, I opened Settings → Devices & services → ZHA in Home Assistant and started adding a device. I used the recessed Setup button on the back of the dimmer to put it into pairing mode, and ZHA discovered it without difficulty.

Unlike a bulb, though, pairing a dimmer doesn’t automatically make it control anything. Its button presses generate Zigbee events, which Home Assistant needs to interpret and act upon.

Rather than create all the automations myself, I used an existing community blueprint for the Philips Hue RWL020 and RWL021 dimmers. A blueprint is a reusable automation template, allowing the same logic to be applied to different devices and lights.

That seemed like a sensible starting point, but the initial results were mixed.

When only some buttons work

The On button worked, but Off and the brightness controls didn’t behave correctly. ZHA was receiving the button presses, so the problem appeared to be in the automation rather than the Zigbee connection.

I enlisted ChatGPT to help me diagnose the problem, working through the zha_event messages generated by the dimmer and comparing them with the conditions in the blueprint. This was a useful example of AI assisting with troubleshooting, although it still needed me to capture the events, test the suggested changes and confirm that they worked.

The Off button generated an off_with_effect command on cluster 6, endpoint 1, but the blueprint was attempting to match the event using assumptions about the args data that didn’t correspond with the events my dimmer was producing. Changing the automation to recognise the command directly fixed the Off button.

The brightness buttons needed a similar adjustment. They generated step commands on cluster 8, with the relevant values available in the structured event parameters. In particular, params.step_mode distinguished brightness up (0) from brightness down (1), while params.step_size indicated the size of the adjustment, with values of 30 and 56 appearing in the events.

With ChatGPT’s help, I modified the blueprint to use these parameters rather than comparing string representations of the event arguments. The two step sizes are handled as 10% and 25% brightness adjustments respectively, rather than exact conversions from Zigbee’s brightness scale. That fixed the brightness controls on my dimmers.

Controlling six lights together

The loft room has six IKEA GU10 spotlights, which I’d already added to a ZHA Zigbee group. I used that group as the target for the dimmer automation.

This is different from targeting the Home Assistant area. A Zigbee group allows supported devices to receive group commands, whereas an area is primarily an organisational construct within Home Assistant. For six spotlights that should behave as one light, the Zigbee group was the more appropriate target.

Improving responsiveness

Once the buttons were working, I noticed that the blueprint included one-second transitions in several light actions. That introduced a deliberate fade, even when I wanted the lights to respond immediately.

I changed seven occurrences of transition: 1 to transition: 0 in my local blueprint. The result was noticeably better for switching, although the brightness buttons still have some latency. Removing the programmed transitions doesn’t eliminate the time required for Home Assistant to process events and send commands to the lights.

There may be scope to improve this further using more direct Zigbee commands, but I haven’t investigated that yet.

I saved the modified blueprint locally in Home Assistant, retaining the original community blueprint as the starting point and correcting the event handling and transitions. I’ve also published my modified blueprint as a GitHub Gist for anyone encountering similar problems.

The blueprint has been tested with my two RWL021 dimmers, although I can’t guarantee compatibility with other firmware versions or event formats. It explicitly handles brightness step sizes of 30 and 56, so other values may require additional changes.

Once the first dimmer was working, I migrated the second one from Hue to ZHA. There was no need to duplicate the blueprint. I simply created another automation from the same corrected version, selected the second dimmer and targeted the bedroom light.

I now have one blueprint and two automations, each assigned to its respective Home Assistant area. I’ve also deleted the original, unmodified blueprint, leaving just the corrected version.

Two working dimmers, no Hue Bridge

Both dimmers now control their respective lights, including On, Off and brightness adjustment. The setup isn’t entirely perfect — the bedroom dimmer seems a little less responsive, and I’d still like to investigate that — but both are usable for everyday lighting control.

More importantly, I can maintain one corrected blueprint rather than two independent sets of automation logic. With the last dimmer migrated, there was nothing left requiring the Hue Bridge, so it could be removed from the network and factory reset.

This is the second post in my Home Assistant ZHA migration series. The first post, yesterday covers moving the bulbs and retiring the Hue Bridge, while the final post, tomorrow looks at two useful Zigbee pairing techniques I discovered along the way.