Aqara Shutter Switch H2: From ZHA Events to a Blueprint

How we got there?

I picked up the Aqara Shutter Switch H2 EU for a roller shutter, expecting it to work out of the box with ZHA. The shutter control worked, but the two additional “wireless” buttons were nowhere to be found.

I could open and close the cover, but I could not trigger automations from the extra buttons. That is where the journey began.

Step 1: Understand what ZHA sees

The first step was to watch raw device events. In Home Assistant, that means listening for zha_event and pressing the buttons. The device was sending events, but only as single presses. Double and hold events were not showing.

That pointed to the multi‑click mode not being enabled. The device was probably emitting different attribute values, but ZHA was not interpreting them.

Step 2: Get the quirk loaded

I wrote a custom quirk and placed it under custom_zha_quirks. It loaded, but the first pass failed because my quirk used a newer zha-quirks API than the version shipped with my Home Assistant.

After aligning the code to the version I had installed, the quirk loaded correctly. I verified it by looking for the Checking quirks for Aqara lumi.switch.aeu003 log entries and by observing entities created by the quirk.

Step 3: Make the extra buttons usable

Once the quirk loaded, the additional endpoints appeared, but events still only showed single clicks. The key change was enabling the multi‑click attribute on the manufacturer cluster. With that on, I started seeing 3_double, 3_hold, 3_release, and the equivalent for button 4.

To enable multi‑click reporting, I wrote the manufacturer‑specific multi‑click attribute directly on the Aqara cluster via ZHA’s service call. This flips the device into a mode where it emits *_double, *_hold, and *_release events instead of only *_single. In Home Assistant, I did this from Developer Tools → Services using:

action: zha.issue_zigbee_cluster_command
data:
  ieee: "54:ef:44:10:01:3e:3d:b5"
  endpoint_id: 3
  cluster_id: 0xFCC0
  command_type: "client"
  manufacturer: 0x115F
  command: 2
  args:
    - 0x0286
    - 0x20
    - 2

At that point I had enough signal to build automations.

Step 4: Control a cover properly

There was a bigger problem, though. The cover UI in Home Assistant kept greying out. It was acting as if the cover was always moving, or at end position when it was not.

We tried mapping a raw “position” attribute. It turned out to be a counter that only incremented on button events, not an absolute position. That meant it could not be used as a reliable end stop.

The solution was to avoid pretending we had perfect position and instead focus on reliable open, close, and stop behaviour. We also kept the raw position value only as a diagnostic sensor and made it disabled by default.

Step 5: Design the button behaviour

After the device was stable, I mapped button 3 and 4 to a consistent model in an automation:

Single click toggles a light.
Double click runs a custom action.
Hold dims or brightens, depending on mode.
Release stops dimming.

Two issues had to be dealt with here:

Hold behaviour intially caused flickering. The initial implementation toggled direction on every loop, which caused the light to jump between on and off. I added two helper booleans to store the current hold direction per button. This avoids flickering.
I noticed that aggressive intervals can flood the Zigbee protocol and can cause disconnects. I added a minimum interval, a maximum hold duration, and a warning in the logbook when settings are too aggressive.

Step 6: Build a blueprint

Once the behaviour worked in automations, I turned it into a blueprint so it can be reused.

The blueprint allows fo:

Choosing lights for button 3 and button 4
Choosing custom actions for double‑clicks
Configuring hold step and interval
Setting a maximum hold duration, with 0 meaning no limit

This is much easier to share and re-use than a raw automation.

Step 7: Create the repository

With a working blueprint, the next step was to package it properly in a dedicated repository.

The README is split into two sections: Blueprint and Custom ZHA quirk. The quirk section is a placeholder for now as it is not yet finalized, but the blueprint side is fully documented.

Codeberg Repo GitHub Repo

Design choices recap

Use zha_event as the truth rather than trying to interpret derived entities.
Keep rate limiting in mind because Zigbee devices can be overwhelmed easily.
Expose double‑click as a custom action since it is often user specific.
Use helpers for hold direction to avoid flicker.

The repo

It now contains:

The blueprint: blueprints/automation/aqara-multifunction-shutter-switch-h2.yaml
A README with setup instructions and helper definitions
A place for the custom quirk to live next

Closing thoughts

This started as “why do my buttons not show up” and ended in a reusable blueprint and a clean repository. The main lesson was that ZHA gives you enough signal, but only if you listen to the right events and avoid over‑interpreting unreliable attributes.

I will add the finished quirk next so the device can be set up end‑to‑end and will also contribute the custom quirk to the community repo.