[ST EDGE] Aqara H2 Wall Switch EU/US 1CH/2CH/3CH (Zigbee, decoupled mode, LED control, multi-click, ...)

[Andreas_Roedl]

Zigbee Edge Driver for Aqara H2 Wall Switches and Dimmer

This SmartThings Edge driver targets the Zigbee mode of the Aqara H2 wall-switch family.

Supported devices

Retail model	Zigbee model	Region / type	Loads	Physical buttons
WS-K07E	lumi.switch.agl009	EU 1-channel switch	1 relay	2
WS-K08E / WS-K08D	lumi.switch.agl010	EU 2-channel switch	2 relays	4
WS-K02E	lumi.switch.agl004	US 1-channel switch	1 relay	2
WS-K03E	lumi.switch.agl005	US 2-channel switch	2 relays	2
WS-K04E	lumi.switch.agl006	US 3-channel switch	3 relays	4
WS-K05E	lumi.switch.agl007	US dimmer	1 dimmable load	3

Device images

WS-K07E

WS-K08E / WS-K08D

WS-K02E

WS-K03E

WS-K04E

---

Why this driver exists

The Aqara H2 family is a dual-protocol product line. Aqara documents the devices as supporting Thread / Matter and Zigbee, but the richer Aqara-specific feature set is exposed on the Zigbee side. Public integrations such as Zigbee2MQTT and ZHA expose vendor-specific features that are not typically available through generic Matter switch support.

In practical terms:

• Matter / Thread provides excellent generic cross-platform switch and dimmer support.
• Zigbee adds Aqara-specific features such as decoupled mode, LED settings, relay lock, power-on behavior, multi-click configuration, richer button events and, on the WS-K05E, dimmer tuning.

If you want a generic switch or dimmer, Matter is fine. If you want the Aqara-specific bells and whistles, Zigbee is the more interesting path.

---

Matter vs Zigbee

Area	Matter / Thread	Zigbee with this driver
Generic on/off control	Yes	Yes
Brightness control	Yes, on the dimmer	Yes, on the WS-K05E
Separate relay tiles	Via the SmartThings Matter switch driver	Via child devices on relay models
Aqara LED settings	Not typically exposed	Yes
Decoupled mode	Not typically exposed	Yes
Relay lock	Not typically exposed	Yes
Power-on behavior	Not typically exposed	Yes
Multi-click configuration	Not typically exposed	Yes
Rich button events	Limited by generic Matter modeling	Model-specific button support
Dimmer phase and brightness limits	Not typically exposed	Yes, on the WS-K05E
Best use case	Generic compatibility	Full Aqara feature access

Wiring and metering

For the wall-switch models, Aqara documents both neutral and no-neutral wiring, but power monitoring is tied to supported with-neutral installations. Metering availability therefore depends on the exact model, firmware and wiring.

---

SmartThings device layout

Model	Parent / main device	Child devices
agl009 / WS-K07E	main, up, down, power and energy	relay1
agl010 / WS-K08E / WS-K08D	main, left, right, leftDown, rightDown, power and energy	relay1 = left, relay2 = right
agl004 / WS-K02E	main, top, bottom, power and energy	relay1
agl005 / WS-K03E	main, top, bottom, power and energy	relay1 = top, relay2 = bottom
agl006 / WS-K04E	main, top, center, bottom, wireless, power and energy	relay1 = top, relay2 = center, relay3 = bottom
agl007 / WS-K05E	switch, switchLevel, main, power, bright, dim, power and energy	None; the single dimmable load is controlled directly through the main device

For the relay-based models, buttons, settings and metering remain on the parent device, while each real relay is represented by a separate child switch. The WS-K05E is different because it has only one dimmable load, so its on/off and brightness controls remain directly on the main device.

---

Preferences

All supported models expose these shared preferences:

• LED indicator
• Flip LED
• Power-on mode

Model-specific preferences:

Model	Operation modes	Relay locks	Multi-click	Dimmer settings
agl009	Up	Up	Down	—
agl010	Left, right	Left, right	Left-down, right-down	—
agl004	Top	Top	Bottom	—
agl005	Top, bottom	Top, bottom	—	—
agl006	Top, center, bottom	Top, center, bottom	Wireless	—
agl007	Power, brightness-up, brightness-down	—	Power, brightness-up, brightness-down	Phase, minimum brightness, maximum brightness

Operation-mode choices are relay and decoupled.

WS-K05E dimmer options:

Preference	Values
Dimming phase	forward, reverse
Minimum brightness	0–99%
Maximum brightness	1–100%

These preferences map directly to Aqara attributes in manufacturer-specific cluster 0xFCC0.

---

Installation

1. Install the driver

1. Open the driver channel invitation link.
2. Sign in with your Samsung account and accept the invitation.
3. Enroll the SmartThings Hub that should receive the driver.
4. Under Available Drivers, install Aqara H2 Wall Switches.

2. Put the device into Zigbee mode

This driver supports the Zigbee mode of the H2 family, not Matter / Thread mode.

If the device is still operating through Matter / Thread, SmartThings will not select this Zigbee driver. Remove any existing Matter device before pairing it again in Zigbee mode.

The WS-K05E may initially ship with Thread / Matter firmware and must be switched to or flashed with Zigbee firmware through the Aqara Home app before it can pair with this driver.

3. Confirm the result

After pairing:

• relay models should create one parent device and one, two or three relay child devices
• the WS-K05E should appear as one dimmer device with on/off, brightness, buttons, preferences and metering

If the device appears only as a generic switch, it is usually still in the wrong protocol mode or the driver is not installed on the hub that performed pairing.

---

Why child devices are used

SmartThings officially supports Zigbee parent/child devices. The relay-based H2 models use this structure because it provides one clean switch tile per physical relay while keeping buttons, preferences and aggregate metering together on the parent.

The official SmartThings Matter switch driver uses a similar approach for additional switch endpoints.

Parent device	Child relay devices
Buttons and aggregate button state	One standard switch per physical relay
Aqara-specific preferences	Independent automations and tiles
Power and energy	refresh and healthCheck
Zigbee reporting and read/write logic	Endpoint-specific relay control

The WS-K05E does not need a child device because it has one dimmable load.

---

Technical reference

Driver architecture

Area	Parent / main device	Child device
Relay models	Buttons, preferences, metering, reporting and child management	One real relay endpoint
WS-K05E	Buttons, preferences, metering, on/off and brightness	Not used
Capabilities	Button, power, energy, refresh and model-specific controls	switch, refresh, healthCheck

---

Endpoint map

Model	Endpoint	Function
agl009	1	Main relay, upper button, shared Aqara settings, base metering clusters
	4	Lower button and multi_click
	21	Dedicated power-reporting path
agl010	1	Left relay, left upper button, shared settings and base metering
	2	Right relay, right upper button and per-channel settings
	4	Left-down button and multi-click
	5	Right-down button and multi-click
	21	Dedicated power-reporting path
agl004	1	Main relay, top button, shared settings and base metering
	4	Bottom button and multi_click
	21	Dedicated power-reporting path
agl005	1	Top relay, top button, shared settings and base metering
	2	Bottom relay, bottom button and per-channel settings
	21	Dedicated power-reporting path
agl006	1	Top relay, top button, shared settings and base metering
	2	Center relay, center button and per-channel settings
	3	Bottom relay, bottom button and per-channel settings
	4	Wireless button and multi_click
	21	Dedicated power-reporting path
agl007	1	Main dimmable load, on/off, brightness, power button, shared settings and base metering
	2	Brightness-up button, operation mode and multi-click
	3	Brightness-down button, operation mode and multi-click
	21	Dedicated power-reporting path
	71, 72	Additional level-related endpoints; brightness reports are accepted from them

The WS-K05E is controlled through endpoint 1. Endpoints 71 and 72 are accepted as additional brightness-reporting paths documented by the public converter.

---

Zigbee clusters

Cluster	ID	Purpose
On/Off	0x0006	Relay states and commands; WS-K05E on/off state
Level Control	0x0008	WS-K05E brightness commands and reports
Multistate Input	0x0012	Button action events
Analog Input	0x000C	Power reporting on endpoint 21
Simple Metering	0x0702	Accumulated energy in kWh
Electrical Measurement	0x0B04	Supplementary instantaneous-power and scaling path

Other standard clusters seen on the devices include Basic (0x0000), Identify (0x0003), Groups (0x0004), Scenes (0x0005), Time (0x000A) and OTA (0x0019).

---

Aqara manufacturer-specific cluster

The main device-specific settings use:

• Cluster ID: 0xFCC0
• Manufacturer code: 0x115F

Attribute	ID	Meaning	Values / notes
flip_led_indicator	0x00F0	Reverse LED logic	Boolean carried as uint8
operation_mode	0x0200	Relay/load control or decoupled mode	0 = decoupled, 1 = relay/control load
led_indicator	0x0203	LED enable / disable	Boolean
lock_relay	0x0285	Relay lock	Boolean carried as uint8
multi_click	0x0286	Multi-click enablement	1 = off, 2 = on
phase	0x030A	WS-K05E dimming phase	0 = forward, 1 = reverse
min_brightness	0x0515	WS-K05E minimum brightness	0–99%
max_brightness	0x0516	WS-K05E maximum brightness	1–100%
power_on_mode	0x0517	State after power restoration	0 = on, 1 = previous, 2 = off, 3 = inverted

---

Button components and events

Model	Button components	Advertised events
agl009 / WS-K07E	up, down	Up: pushed; down: pushed, double, held
agl010 / WS-K08E / WS-K08D	left, right, leftDown, rightDown	Upper: pushed; lower: pushed, double, held
agl004 / WS-K02E	top, bottom	Top: pushed; bottom: pushed, double
agl005 / WS-K03E	top, bottom	pushed
agl006 / WS-K04E	top, center, bottom, wireless	pushed, double, held on all four
agl007 / WS-K05E	power, bright, dim	pushed, double, held on all three

Every model also has an aggregate main button surface. Button support is deliberately defined per model rather than assuming that all H2 buttons generate the same events.

The public integrations also document release actions, but the driver does not currently expose them as SmartThings button events.

---

Relay, dimmer and metering behavior

Feature	Relay-based models	WS-K05E
Load control	Child switch devices	Main switch
Brightness	—	Main switchLevel
Brightness command	—	Zigbee MoveToLevelWithOnOff
Level conversion	—	Zigbee 0–254 ↔ SmartThings 0–100%
Power	Preferred Analog Input path on endpoint 21	Same
Energy	Simple Metering on the main load endpoint	Same intended path
Child devices	One per physical relay	None

Metering behavior can depend on the model, firmware and wiring.

---

Public integration coverage

Source	H2 features documented
Zigbee2MQTT	Power, current, energy, LED settings, switch state, device temperature, outage count, power-on behavior, operation mode, relay lock, multi-click and action events
Zigbee2MQTT for WS-K05E	Brightness, level configuration, dimming phase, minimum brightness and maximum brightness
ZHA quirks	Aqara manufacturer cluster, endpoint 21 power handling, per-endpoint settings and button triggers including single, double, hold and release

---

Driver scope

Implemented / intended	Documented publicly but not currently guaranteed in the SmartThings UI
Child relay switches	currentMeasurement
WS-K05E on/off and brightness	Device temperature
Button events	Power outage count
LED and flipped-LED preferences	Release button events
Power-on behavior	mode_switch
Decoupled mode
Relay lock and multi-click
WS-K05E phase and brightness limits
Power and energy meters

Known design trade-offs

• The driver intentionally focuses on Zigbee mode, where the Aqara-specific feature surface is available.
• Public Zigbee integrations document more features than a conservative SmartThings driver should necessarily expose.
• Power and energy behavior may depend on the model, firmware and neutral wiring.
• Manually deleted child devices may need to be recreated through onboarding or driver-managed reconciliation.
• WS-K05E support should be considered experimental until its complete feature set has been validated on real hardware.

---

Sources

Source	Link
Aqara Light Switch H2 EU product page	Aqara Light Switch H2 – Dual Connectivity Smart Switch for Aqara Home & Apple Home Integration – Aqara LLC
Aqara Light Switch H2 EU specifications	Light Switch H2 EU – Aqara LLC
Aqara support: Light Switch H2 EU	Light Switch H2 EU – Help Center
Aqara Light Switch H2 US specifications	Light Switch H2 US-Specs - Aqara
Zigbee2MQTT: WS-K07E	Aqara WS-K07E control via MQTT | Zigbee2MQTT
Zigbee2MQTT: WS-K08E	Aqara WS-K08E control via MQTT | Zigbee2MQTT
Zigbee2MQTT: WS-K02E	Aqara WS-K02E control via MQTT | Zigbee2MQTT
Zigbee2MQTT: WS-K03E	Aqara WS-K03E control via MQTT | Zigbee2MQTT
Zigbee2MQTT: WS-K04E	Aqara WS-K04E control via MQTT | Zigbee2MQTT
Zigbee2MQTT: WS-K05E	Aqara WS-K05E control via MQTT | Zigbee2MQTT
ZHA PR: Aqara H2 switches (EU)	Added Support for Aqara H2 switches (EU+US) by lonevvolf · Pull Request #4141 · zigpy/zha-device-handlers · GitHub
ZHA PR: Aqara H2 switches (US)	Add Aqara light switch H2 US quirk by jerry0317 · Pull Request #4008 · zigpy/zha-device-handlers · GitHub

[Andreas_Roedl]

Added held button events to the lower buttons of the EU models.

Turns out that the buttons need to be held for at least 4 seconds …

[Andreas_Roedl]

Driver added to GitHub

[The_Halo_Bros (Halo Bros)]

Will this functionality ever come to Thread, and how come custom clusters can’t be done in Thread?

[Andreas_Roedl]

@The_Halo_Bros

Will this functionality ever come to Thread, and how come custom clusters can’t be done in Thread?

Private Clusters can be done in Matter, but they shouldn’t be necessary for device settings/configuration, because Matter already has a Mode Select Cluster. Shortest explanation:

2.9. Mode Select - 2. Developing with the SDK - ESP32 - — Espressif's SDK for...

The Eve Energy plug is the only Matter device with special handling of a private cluster in the SmartThings drivers:

drivers/SmartThings/matter-switch/src/sub_drivers/eve_energy/init.lua

( @mocelet knows all the secrets )

The problem is that the platforms need to implement the handling too. In SmartThings, we have modular profiles for capabilities, but not for preferences. They should be as dynamic as the capabilities - otherwise we’d be back to static profiles.

[johnconstantelo]

Hi @Andreas_Roedl, Thanks for developing this. I have their older double rocker w/neutral switch (lumi.switch.b2naus01), and I wouldn’t mind switching over to a more fully functional driver rather than my own and very simple driver. I know your driver is likely not going to support the older version, but you’ve given me reason to look into getting a new switch.

[Andreas_Roedl]

@johnconstantelo

my own and very simple driver. I know your driver is likely not going to support the older version

Have you tried this driver from @veonua ?

Edit: yeah, looks very basic:

xiaomi-switch/profiles/switch-power.yml

[johnconstantelo]

I hadn’t seen that one, or at least I don’t recall. Mine didn’t create child devices, but kept them all in one.:

I ended up creating virtual switches and corresponding routines for what I wanted to do, but that overhead would be eliminated with a switch upgrade, along with your driver. That was enough to motivate me to upgrade.

[veonua (Andrew Me)]

I am in Europe and depends on external testers for feedback on US devices.

But what features are you looking for?

[RaySorian]

First, Thank you for making this!

Second, how do I update this to support the Aqara WS-K04E (3ch) version?

[Andreas_Roedl]

@RaySorian

Aqara WS-K04E (3ch)

If I remember correctly, this device is very different to the other devices. I’ll see what I can do. Going to take a couple of days to assess the feasibility.

[Andreas_Roedl]

Added support for the Aqara WS-K04E (3ch) / lumi.switch.agl006. You might have to delete the device, re-install the driver to get the latest version and add the device back again.

Expected behavior:

• pairing should match Aqara / lumi.switch.agl006
• parent device should expose main, top, center, bottom, wireless
• three relay child devices should be created
• relay control should target endpoints 1, 2, and 3
• button actions should decode pushed, double, and held
• release events will be ignored, as with the existing design
• operation mode / relay lock should map to top, center, and bottom
• multi-click should map to the wireless endpoint

This is the config block of the device in my driver:

  ["lumi.switch.agl006"] = {
    main_endpoint = 1,
    energy_endpoint = 1,
    power_endpoint = 21,
    switch_endpoints = { 1, 2, 3 },
    button_endpoint_to_component = {
      [1] = "top",
      [2] = "center",
      [3] = "bottom",
      [4] = "wireless",
    },
    component_to_endpoint = {
      main = 1,
      top = 1,
      center = 2,
      bottom = 3,
      wireless = 4,
    },
    endpoint_to_component = {
      [1] = "top",
      [2] = "center",
      [3] = "bottom",
      [4] = "wireless",
      [21] = "main",
    },
    button_components = { "main", "top", "center", "bottom", "wireless" },
    button_supported_values = {
      main = { "pushed", "double", "held" },
      top = { "pushed", "double", "held" },
      center = { "pushed", "double", "held" },
      bottom = { "pushed", "double", "held" },
      wireless = { "pushed", "double", "held" },
    },
    main_button_count = 4,
    child_relays = {
      { endpoint = 1, key = "relay1", label_suffix = "Top Relay", profile = "aqara-h2-relay-child" },
      { endpoint = 2, key = "relay2", label_suffix = "Center Relay", profile = "aqara-h2-relay-child" },
      { endpoint = 3, key = "relay3", label_suffix = "Bottom Relay", profile = "aqara-h2-relay-child" },
    },
    preferences = {
      ledIndicator = { endpoint = 1, attr = ATTR_LED_INDICATOR, kind = "bool" },
      flipLed = { endpoint = 1, attr = ATTR_FLIP_LED, kind = "uint8_bool" },
      powerOnMode = { endpoint = 1, attr = ATTR_POWER_ON_MODE, kind = "power_on_mode" },
      opModeTop = { endpoint = 1, attr = ATTR_OPERATION_MODE, kind = "operation_mode" },
      opModeCenter = { endpoint = 2, attr = ATTR_OPERATION_MODE, kind = "operation_mode" },
      opModeBottom = { endpoint = 3, attr = ATTR_OPERATION_MODE, kind = "operation_mode" },
      lockRelayTop = { endpoint = 1, attr = ATTR_LOCK_RELAY, kind = "uint8_bool" },
      lockRelayCenter = { endpoint = 2, attr = ATTR_LOCK_RELAY, kind = "uint8_bool" },
      lockRelayBottom = { endpoint = 3, attr = ATTR_LOCK_RELAY, kind = "uint8_bool" },
      multiClickWireless = { endpoint = 4, attr = ATTR_MULTI_CLICK, kind = "multi_click" },
    },
  },

[hojongs]

Thank you so much. You saved me <3

[Andreas_Roedl]

@hojongs

Thank you so much. You saved me <3

Can you tell me which model you’re using?

[hojongs]

Sure!

• lumi.switch.agl004

• lumi.switch.agl005

• lumi.switch.agl006

[Andreas_Roedl]

Very cool. Thanks for the feedback, because support for all of the US devices was implemented blindly without a device in hand.

[hojongs]

Awesome! it works well mostly.

But double click and helding are not working despite wireless multi-click enabled in ST app.

Let me ask a question, Should I need to configure multi-clicking in Aqara home app?

[Andreas_Roedl]

@hojongs

wireless multi-click enabled in ST app

Try turning it off and on again. The timing is also important: long-press is about 4 seconds.

Should I need to configure multi-clicking in Aqara home app?

No. Don’t add it to Aqara at all. Is your device still connected to an Aqara hub?

By the way: it’s important to re-add the device after installing the driver. Simply switching the driver is not enough.

[hojongs]

Wow it works to turning off and on again!

Thank you so much!!

[hojongs]

By the way, for agl005, does it not support multi click?