Make the Philips Hue wall switch module work with push button switches in Home Assistant

published Aug 17, 2022, last modified Feb 15, 2023

A step-by-step guide to configuring Hue wall switch modes with only free software. Bonus: how to enable the second switch.

Make the Philips Hue wall switch module work with push button switches in Home Assistant

The problem

It can be frustrating to push your light switch and have your smart light turn on and then immediately off.  This was my experience after I installed a Hue wall switch module — which converts your rocker or push button light switch into a remote for a smart ZigBee light.

Why would that happen?

Ordinarily, you would have a very simple Home Assistant automation that toggles your smart light after the "Turn On" event is received from the Hue wall switch module, which in turn fires when you flick a wall switch.

But what if your wall switch is actually a momentary-type push button switch?  Well, then two "Turn On" events are fired in rapid succession — one when you press the button, and one when you release it.  Why?  Because, by default, the wall module is in rocker type switch mode: it interprets each change in input resistance as one event¹.  A push button action involves two changes in input resistance — close circuit, then open circuit.

The result is that your "Turn On" automation fires twice.  Unhappy campers like me are stuck with a light that is either always on, or always off.

Fortunately, the wall module can be configured in one of four modes:

  • 0 — single rocker type switch
  • 1 — single push button type switch; this is what you want with a push button, as it makes the wall module interpret two successive changes in input resistance as one event (the button push)
  • 2 — double rocker type switch
  • 3 — double push button type switch

Unfortunately, if you are committed to using only open source software (or you don't have a Philips Hue base station) you can't use the Philips Hue application that is required to set this up.  You are stuck in the single rocker type switch configuration.

How the Hue wall module manual describes the application configuration for push button type switches.

The fix — how to configure push button mode on your wall module in Home Assistant

I took the time to read quite a bit of source code, until I finally found this open pull request.  From that, I gleaned the following instructions, which successfully worked for me.  The following instructions assume your wall module is already paired with Home Assistant, is wired properly to your wall switch, and works (other than the pesky "two events firing in a row" problem).

  1. Go to your Settings view in the left sidebar of Home Assistant.
  2. Click on Devices & Services on the list onscreen.
  3. On the top bar, click on Devices.
  4. Find your device and click on its row.  The Device Info box will show up, and list a device RDM001 by Signify Netherlands B.V.  There should be no Philips Hue logo (in particular on the upper right corner of your screen).
  5. Click on the three-dot menu to the right of Reconfigure device in the Device Info box.  Then, in the popup menu, click Manage Zigbee Device (used to be called Manage Clusters in prior HA versions).
  6. The cluster management screen is now open.  Drop down the Clusters menu and select PhilipsBasicCluster (Endpoint id: 1, Id: 0x0000...).
  7. Drop down the Attributes of the selected cluster menu (below the Cluster Attributes heading) and select mode (id: 0x0034).  This is the attribute #52 of the Philips Basic Cluster, and its value signifies which mode the wall module is configured for.  Remember the list of modes above?  That's exactly what this attribute is about.
  8. You are about to retrieve the existing value; for this, you'll need to be close to the switch — otherwise it won't work.  Here is the procedure — read all steps before executing them:
    1. Push the push button connected to the switch.
    2. Then, in less than half a second, click or tap on Read Attribute onscreen.  You gotta do this quickly after pushing the button, otherwise the wall module goes to sleep and it never responds to the attribute read command from Home Assistant.  If the process appears hung after five seconds, push the switch's button now.
    3. Now, in the Value box, you should see something to the effect of enum8.undefined_0x00 or 0.  Congratulations, now you have confirmed that your Philips Hue wall module push button configuration is basically in its factory default state — a value of zero indicates "single rocker switch" mode.

You should be here now:

The Home Assistant device attribute management screen shows the mode attribute freshly fetched from the wall module.

Now change the value to 1.  Then, quickly click Write Attribute.  Don't let too much time pass, or you'll have to do the "push button then click" trick again.  Remember, these wall modules are sleepy devices — they will languish until there's physical activity, then quickly go back to sleep.

Now erase the value from the Value field.  Follow the earlier procedure to get the attribute again, just to confirm that the value is now enum8.undefined_0x01.  Got there?

Congratulations — your wall module is now configured to work properly with push button type switches.

What if I have two push buttons wired to my wall module?

Of course, if your wall switch setup has two switches in one, and both are connected to your Hue wall module, you can follow the same procedure, but use value 3 instead of value 1 when setting the ZigBee attribute.

And if I have two rocker switches?

If you have two rocker switches instead, use value 2.