Aqara H2 EU Wall Switch in Home Assistant: Full Local Setup via Zigbee2MQTT

The Aqara H2 EU wall switch is one of the more capable switches in the Aqara lineup, and it works cleanly in Home Assistant via Zigbee2MQTT once you get past one initial gotcha: it ships in Thread mode, not Zigbee mode. Most of the confused forum posts about this device trace back to that single issue.

This guide walks through every step: switching the device to Zigbee mode, pairing it with Zigbee2MQTT, and configuring the features that actually matter for a local-first setup. I’ll also cover what doesn’t work in Thread mode and where ZHA falls short, so you can pick the right path without debugging it yourself.

What the H2 EU actually is — and why the out-of-box mode is the wrong one for Home Assistant

The H2 EU comes in two physical variants: the WS-K07E (2 buttons, 1-channel relay) and the WS-K08E (4 buttons, 2-channel relay). Both require a neutral wire. There are also white-label D-suffix variants — the WS-K07D and WS-K08D — that drop the neutral wire requirement, but those lose power monitoring and some LED control capabilities as a result.

The device launched in 2024 as a dual-protocol switch: it supports both Thread/Matter and Zigbee. Aqara ships it in Thread mode by default, indicated by a blue blinking LED during pairing. The problem is that Thread mode exposes a fraction of the feature set — basic switch entities and power measurement, nothing else. No LED control, no decoupled mode, no multi-click configuration.

Zigbee mode is what gives you the full entity set in Zigbee2MQTT. It’s also the mode where the device works entirely without the Aqara cloud after a one-time setup step. The two protocols are distinguished by the pairing-mode LED color: blue blinking is Thread, purple blinking is Zigbee.

Here’s the comparison at a glance:

For a Zigbee2MQTT setup, the answer is clear. Switch to Zigbee mode.

Before you start — what you need

• A Zigbee coordinator attached to the Home Assistant host. A Sonoff Zigbee 3.0 USB Dongle Plus is the one I use for this cluster, though the newer Dongle-E works equally well — both have solid firmware support in Z2M.
• Zigbee2MQTT installed and running in Home Assistant (the add-on or standalone both work)
• The Aqara Home app on Android or iOS, with a phone that has Wi-Fi and Bluetooth enabled — needed once for the mode switch, then optional
• Neutral wire confirmed in your switch box — worth checking before you open the wall

If you’re still choosing between using a coordinator and using an Aqara hub, our Aqara Hub M2 local setup guide covers the hub-based path. This guide assumes you want the hub-free, fully local setup.

Our guide to whether Aqara devices work without internet has a broader treatment of which Aqara setups require ongoing cloud access and which don’t — the H2 EU in Zigbee mode is one of the cleaner stories on that front.

Step 1: Switch from Thread to Zigbee mode

This is the step most guides skip, and it’s why most people’s H2 EU ends up in Thread mode indefinitely.

The switch comes out of the box in Thread mode. Before you can pair it with Zigbee2MQTT, you need to change its protocol using the Aqara Home app. This is a one-time step — after it’s done, the device stays in Zigbee mode and has no ongoing cloud requirement.

Here’s the procedure:

1. Press any relay button on the switch 10 times in quick succession. This factory-resets the device and puts it into network-setup mode.
2. Open the Aqara Home app on your phone. Bluetooth and Wi-Fi need to be enabled on the phone during this step.
3. Tap “Add Accessory” in the app and let it discover the switch (you may be prompted to scan the Matter code printed on the button).
4. When the Switch Protocol selector appears, choose Zigbee (not Thread or Matter).
5. Let the app complete the pairing. The pairing-mode LED blinks purple while Zigbee setup is in progress, then turns solid blue once pairing succeeds — that solid blue is your confirmation the device is now in Zigbee mode.

Once this is done, you can close the Aqara Home app and ignore it. The device will not try to reconnect to Aqara’s cloud in Zigbee mode.

If you skip this step and try to pair directly with Z2M, you may see the device appear briefly, but the entity list will be limited and the MQTT topics won’t match what’s documented for the H2 EU in Zigbee2MQTT. That’s the Thread mode binding surfacing — not a Z2M bug.

Step 2: Pair with Zigbee2MQTT

With the device in Zigbee mode, pairing is standard.

Start a Zigbee2MQTT permit-join, then enable pairing mode on the H2 EU: double-press any button, then press and hold for 5 seconds until the indicator blinks purple (purple is the Zigbee pairing color — if you see blue blinking instead, the device is still in Thread mode and you need to repeat Step 1). Zigbee2MQTT should pick it up within a few seconds.

The device will identify itself in Z2M as lumi.switch.agl009. Both the WS-K07E and WS-K08E use this device ID, with Z2M distinguishing features based on what entities are exposed. No custom quirks or converter files are needed — the device is fully supported upstream. You can confirm the full entity list on the Zigbee2MQTT WS-K07E device page.

After pairing, check the Z2M devices list and confirm the device appears with its correct name. Then head to the Home Assistant device page and verify the entities have populated. A freshly paired WS-K07E with neutral wire should show around a dozen entities on first load — if you’re only seeing two or three, the device is still in Thread mode.

Step 3: Configure entities in Zigbee2MQTT

This is where the H2 EU earns its spec sheet. The full entity set for the WS-K07E with neutral wire includes:

Without a neutral wire, power monitoring is disabled, overload protection is disabled, and LED indicator settings are unavailable. The device also drops to operating as a Zigbee end device rather than a router, which means it won’t extend your mesh.

Operation mode: control_relay vs decoupled

This is the most important configuration decision for the H2 EU.

In control_relay mode (the default), pressing the physical button toggles the relay directly. The switch behaves like a normal light switch. Home Assistant can also control the relay remotely.

In decoupled mode, the physical button and the relay are separated. Pressing the button fires an action event in Home Assistant, but the relay state doesn’t change automatically. This is what you want when controlling smart bulbs — you keep the bulb permanently powered and handle on/off through automations triggered by button events.

To set operation mode, go to the device in Zigbee2MQTT, find the “Operation mode” dropdown, and select your preference. The change takes effect immediately.

Enabling multi-click on the wireless button

The H2 EU has a hardware-level distinction between its top button (the relay/up button) and its bottom button (the wireless/down button).

The bottom button supports multi-click events: single press, double press, hold, and release. These are available in Z2M once you enable multi_click in the device settings. After enabling it, the bottom button will fire distinct action events for each gesture, which you can use as automation triggers.

The top button is hardware-limited. It only fires a single-press action event, even in decoupled mode. Double-press and hold on the top button don’t generate distinct events — this is a hardware constraint, not a Z2M limitation. If your automation relies on multi-click, design it around the bottom button.

Power-on behavior

power_on_behavior controls what the relay does after a power cut. Options are: on (relay turns on regardless of previous state), off (relay stays off), previous (restore the state before the cut), and inverted (restore the opposite state).

For most setups, previous is the right choice. If you have a load that should always be off after a power cut — a high-draw device, for example — set it to off.

LED indicator and lock relay

The LED indicator entities let you control whether the status LED is on or off and whether its behavior is inverted (on when relay is off, useful in dark rooms to locate the switch). These entities only appear when the device has a neutral wire.

Lock relay prevents the physical button from changing the relay state. This is useful if the switch is in a location where accidental presses are a concern and you want Home Assistant to be the only control path.

Building automations for decoupled mode

Decoupled mode is where the H2 EU becomes genuinely useful as part of a smart home. Here are the patterns I use.

Single press: toggle a smart bulb group

alias: H2 bottom button single press — toggle living room lights
trigger:
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: single_bottom
action:
  - service: light.toggle
    target:
      entity_id: light.living_room_group

Replace single_bottom with the exact action event string that Z2M reports for your device — you can find it in the Z2M events tab or by watching MQTT with a browser.

Double press: activate a scene

alias: H2 bottom button double press — evening scene
trigger:
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: double_bottom
action:
  - service: scene.turn_on
    target:
      entity_id: scene.evening

Hold: set brightness to 20%

alias: H2 bottom button hold — dim to night level
trigger:
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: hold_bottom
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room_group
    data:
      brightness_pct: 20

A couple of things to keep in mind when building these. First, the top button in decoupled mode fires single_top only — don’t expect double-press or hold events from it, they won’t arrive. Second, when you have multi-click enabled, there’s a short debounce window before the single-press event fires, because the device is waiting to see if a second press is coming. For most automations this isn’t noticeable, but if you’re controlling lights it means the response is slightly slower than direct relay switching. That’s a design trade-off of multi-click, not a Z2M bug.

For the WS-K08E with two relay channels and four buttons, the same logic applies per channel. Each relay can be independently set to control_relay or decoupled, and each button pair can have multi-click enabled separately.

Known limitations and things to watch

No-neutral variant limitations

The WS-K07D and WS-K08D (no neutral) lose power monitoring, LED indicator control, and overload protection. They also operate as Zigbee end devices rather than routers. If your switch box doesn’t have a neutral wire, these are the only options, but you’re trading a meaningful portion of the entity set.

Top button is single-press only

Mentioned above, but worth repeating because it trips people up. Only the bottom button generates multi-click events. If you’re building an automation that needs double-press and you’ve mapped that to the top button, it won’t fire.

MARS relay mode latency

The H2 EU uses a software-controlled relay switching mechanism (Aqara calls it MARS technology) in decoupled mode. This introduces a small amount of latency compared to a switch that toggles the relay directly through hardware. In practice it’s barely perceptible, but if you’re comparing the response feel of the H2 EU in decoupled mode to a simpler switch in direct mode, the H2 EU will feel marginally slower. It’s a trade-off of the dual-mode design, not a defect.

ZHA support is partial

If you’re running ZHA rather than Zigbee2MQTT, you’ll get basic switch and power measurement entities, but decoupled mode and multi-click configuration are not exposed. For the full feature set the brief describes, Zigbee2MQTT is the required integration. Our Aqara H1 EU with-neutral guide has a note on the ZHA vs Z2M trade-off for EU Aqara wall switches generally.

Thread/Matter mode feature gap

If you do use Thread mode — for example, because you’re running an Aqara hub as a Matter bridge, covered in our Aqara Hub M3 Matter bridge guide — expect only basic switch and power entities. No LED control, no decoupled mode, no multi-click. The Matter commissioning process also touches the Aqara cloud once during setup, though it doesn’t require ongoing cloud access after that.

Privacy check: what stays local after setup

After the one-time protocol switch via the Aqara Home app, the H2 EU in Zigbee mode has no ongoing Aqara cloud dependency. All communication happens over your local Zigbee network to your coordinator, then through Z2M to Home Assistant.

OTA firmware updates are available via Zigbee2MQTT’s update mechanism — these pull from the Z2M OTA server, not from Aqara’s infrastructure, so they don’t require an Aqara account or active cloud connection.

The one caveat worth calling out explicitly: the initial mode-switching step uses the Aqara Home app and does require a brief cloud-connected pairing. Once it’s done, you can block Aqara’s servers at the firewall and the switch will continue to function normally. I confirm this by checking the DNS query log after setup to verify no outbound Aqara traffic appears during normal switch operation.

Frequently asked questions

Does the Aqara H2 EU wall switch work without the Aqara hub?

Yes. In Zigbee mode with a standalone coordinator, it works with no Aqara hub required. The Aqara Home app is only needed once during the initial mode switch.

Should I use Zigbee or Thread mode with the Aqara H2 EU in Home Assistant?

For a Zigbee2MQTT setup, Zigbee mode is the right choice. It exposes a much larger entity set and has no ongoing cloud dependency. Thread/Matter mode is only worth considering if you already have a Thread border router and are comfortable with the reduced feature set.

How do I switch the Aqara H2 EU from Thread to Zigbee mode?

Press any relay button 10 times to factory-reset into network-setup mode, then use the Aqara Home app (Add Accessory, select Zigbee under Switch Protocol). The LED blinks purple during Zigbee setup and turns solid blue once pairing succeeds.

Can the Aqara H2 EU work with smart bulbs in decoupled mode?

Yes. Set the operation mode to decoupled in Zigbee2MQTT, and the physical button fires action events to Home Assistant without toggling the relay. Your automations handle the bulb control, and the bulb stays permanently powered.

Why does the Aqara H2 EU top button not respond to double-press in Home Assistant?

The top (relay) button is hardware-limited to single-press events. Double-press and hold are only supported on the bottom (wireless) button once multi-click is enabled in Z2M settings. This is a hardware constraint, not a configuration issue.

The Aqara H2 EU is one of the more complete wall switch options in the Aqara lineup once you get it into Zigbee mode. The mode-switching requirement adds friction on day one, but after that it runs cleanly — no hub, no cloud, full entity set in Z2M. If you’re coming from the older H1 EU line, our Aqara H1 EU with-neutral guide covers that generation; the main additions on the H2 are multi-click on the bottom button and a broader power monitoring entity set. For most local-first setups that’s a meaningful upgrade.

For a new Zigbee network from scratch, a Sonoff Zigbee 3.0 USB Dongle Plus (or the newer Dongle-E) is a dependable coordinator to pair this with — both have solid firmware support in Z2M and will handle the H2 EU without any configuration beyond standard pairing.