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

Devices & Integrations Community Created Drivers
1

Testers wanted for the US models!

Zigbee Edge Driver for lumi.switch.agl009, lumi.switch.agl010, lumi.switch.agl004 and lumi.switch.agl005

This driver targets the Zigbee mode of the Aqara H2 wall switches and is designed for SmartThings Edge.

Supported Zigbee model fingerprints:

  • Aqara / lumi.switch.agl009
    Aqara H2 EU single channel / two-button wall switch
    Retail model commonly documented as WS-K07E
  • Aqara / lumi.switch.agl010
    Aqara H2 EU two channel / four-button wall switch
    Retail models commonly documented as WS-K08E and WS-K08D
  • Aqara / lumi.switch.agl004
    Aqara H2 US single channel / two-button wall switch
    Retail model commonly documented as WS-K02E
  • Aqara / lumi.switch.agl005
    Aqara H2 US two channel / two-button wall switch
    Retail model commonly documented as WS-K03E

Why this driver exists

The Aqara H2 family is a dual-protocol product line. Aqara documents the switch as supporting Thread / Matter and Zigbee, but the richer Aqara-specific feature set is exposed on the Zigbee side. Aqara’s own product documentation highlights the dual-protocol design and public Zigbee integrations such as Zigbee2MQTT and ZHA expose the vendor-specific features that are not typically surfaced by generic Matter switch support.

That matters for SmartThings:

  • Matter / Thread is excellent for generic cross-platform switch support.
  • Zigbee is where the Aqara-specific features become visible:
    • decoupled / wireless switch mode
    • LED indicator control
    • flipped LED logic
    • relay lock
    • power-on behavior
    • multi-click enablement for the lower buttons
    • richer button event handling

In other words: if you want the switch to behave like a generic Matter switch, Matter is fine. If you want the Aqara-specific bells and whistles, Zigbee is the interesting path.

Matter vs Zigbee: practical comparison

Area Matter / Thread path Zigbee path
SmartThings onboarding Excellent for generic switch support Requires using the switch in Zigbee mode
Standard switch control Yes Yes
Separate relay tiles Yes, via the SmartThings Matter switch driver Yes, via this Zigbee driver’s child devices
Aqara-specific LED settings Not typically exposed Yes, via Aqara manufacturer cluster
Decoupled / wireless switch mode Not typically exposed Yes
Relay lock Not typically exposed Yes
Power-on behavior Not typically exposed Yes
Multi-click enablement Not typically exposed Yes
Rich button behavior Limited by generic Matter modeling Richer and better documented in Zigbee integrations
Best choice for this driver Good baseline Best choice for full feature access

Important note about wiring

Aqara documents that the H2 supports both neutral and no-neutral wiring, but also states that power monitoring/reporting is tied to with-neutral setups. So real-time power and energy features depend on the actual installation.

Supported devices

Aqara H2 EU 1CH

WS-K07E
WS-K07E512×512 117 KB

  • Zigbee model: lumi.switch.agl009
  • Common retail name: WS-K07E
  • Layout:
    • 1 relay
    • 2 button surfaces

SmartThings layout in this driver:

  • Parent:
    • main aggregate button component
    • up button component
    • down button component
    • powerMeter
    • energyMeter
  • Child devices:
    • relay1

Aqara H2 EU 2CH

WS-K08E
WS-K08E512×512 120 KB

  • Zigbee model: lumi.switch.agl010
  • Common retail names: WS-K08E, WS-K08D
  • Layout:
    • 2 relays
    • 4 button surfaces

SmartThings layout in this driver:

  • Parent:
    • main aggregate button component
    • left
    • right
    • leftDown
    • rightDown
    • powerMeter
    • energyMeter
  • Child devices:
    • relay1 = left relay
    • relay2 = right relay

Aqara H2 US 1CH

WS-K02E
WS-K02E512×512 16.2 KB

  • Zigbee model: lumi.switch.agl004
  • Common retail name: WS-K02E
  • Layout:
    • 1 relay
    • 2 button surfaces

SmartThings layout in this driver:

  • Parent:
    • main aggregate button component
    • top
    • bottom
    • powerMeter
    • energyMeter
  • Child devices:
    • relay1

Aqara H2 US 2CH

WS-K03E
WS-K03E512×512 12.9 KB

  • Zigbee model: lumi.switch.agl005
  • Common retail name: WS-K03E
  • Layout:
    • 2 relays
    • 2 button surfaces

SmartThings layout in this driver:

  • Parent:
    • main aggregate button component
    • top
    • bottom
    • powerMeter
    • energyMeter
  • Child devices:
    • relay1 = top relay
    • relay2 = bottom relay

Preferences

Screenshot_20260405_023222_SmartThings
Screenshot_20260405_023222_SmartThings726×1473 43.7 KB

The driver exposes Aqara-specific settings as SmartThings preferences.

Shared preferences

  • LED indicator
  • Flip LED
  • Power-on mode

agl009

  • Up mode
    • relay
    • decoupled
  • Lock up relay
  • Down multi-click

agl010

  • Left mode
    • relay
    • decoupled
  • Right mode
    • relay
    • decoupled
  • Lock left relay
  • Lock right relay
  • Left-down multi-click
  • Right-down multi-click

agl004

  • Top mode
    • relay
    • decoupled
  • Lock top relay
  • Bottom multi-click

agl005

  • Top mode
    • relay
    • decoupled
  • Bottom mode
    • relay
    • decoupled
  • Lock top relay
  • Lock bottom relay

These preferences are not random UI extras; they map directly to Aqara attributes in 0xFCC0.

Installation

1. Driver Installation

  1. Open the driver channel invitation link.
  2. Sign in with your Samsung account.
  3. Accept the invitation.
  4. Enroll the SmartThings Hub that should receive the driver.
  5. Under Available Drivers, install the Aqara H2 Wall Switches (EU/US - 1CH/2CH) driver onto the enrolled hub.

1. Put the switch into Zigbee mode

This driver is for the Zigbee mode of the H2, not the Matter / Thread mode.

Aqara documents that the H2 is a dual-protocol device. If the switch is still operating in Matter / Thread mode, SmartThings will not use this Zigbee driver. If the switch was previously added in Matter mode, remove that Matter device first and then re-add it in Zigbee mode. Pair the Aqara H2 Wall Switches, or reassign / re-pair it if it is already paired with another driver.

2. Confirm the result in the app

After pairing:

  • the parent device should appear as the button / settings / metering device
  • one or two child relay devices should appear for the real relay outputs

If you only see one generic device, the switch is usually still in the wrong protocol mode or the driver is not installed on the hub that performed pairing.

Why this driver uses child devices

Screenshot_20260405_023030_SmartThings
Screenshot_20260405_023030_SmartThings774×288 14.4 KB

This Zigbee driver intentionally uses a parent + child device layout:

  • Parent device
    • buttons
    • aggregate power / energy
    • Aqara-specific preferences
  • Child devices
    • one child per real relay / load output

This was chosen for two reasons.

SmartThings officially supports this model

SmartThings documents Zigbee parent/child devices explicitly. A parent device can create EDGE_CHILD devices, assign them a parent_assigned_child_key, and manage endpoint-owned functionality through the parent device object.

The official SmartThings Matter switch driver already uses a very similar idea

The SmartThings Matter Switch driver creates child devices for additional switch endpoints. That is a very elegant representation because each relay gets its own clean SmartThings switch tile instead of forcing everything into one giant multi-component device.

For the Aqara H2 family that split feels natural:

  • buttons belong together on the parent
  • physical relays are better represented as separate child switches

This keeps the Zigbee driver conceptually aligned with the SmartThings Matter experience.

Screenshot_20260405_023109_SmartThings
Screenshot_20260405_023109_SmartThings1199×3577 118 KB

Driver architecture overview

Driver architecture overview

Parent device responsibilities

The parent device is the “brains” of the SmartThings representation:

  • button events
  • aggregate power
  • aggregate energy
  • refresh
  • Aqara-specific preferences and read/write logic
  • Zigbee reporting setup

Child device responsibilities

Each child device represents one real relay endpoint:

  • switch
  • refresh
  • healthCheck

This is cleaner than a giant multi-component relay device and mirrors the way the official SmartThings Matter switch driver models multi-endpoint switches.

Endpoint map

lumi.switch.agl009

This is the 1-channel model.

Endpoint 1

  • main relay
  • upper / primary button events
  • Aqara configuration attributes
  • metering / electrical measurement base clusters

Endpoint 4

  • secondary / lower button events
  • Aqara multi_click attribute

Endpoint 21

  • special power reporting endpoint
  • public ZHA support maps this endpoint to a dedicated power-measurement handling path

lumi.switch.agl010

This is the 2-channel model.

Endpoint 1

  • left relay
  • left upper button events
  • shared Aqara settings
  • metering / electrical measurement base clusters

Endpoint 2

  • right relay
  • right upper button events
  • per-channel Aqara settings

Endpoint 4

  • left-down button events
  • multi_click_left

Endpoint 5

  • right-down button events
  • multi_click_right

Endpoint 21

  • special power reporting endpoint
  • public ZHA support maps this endpoint to a dedicated power-measurement handling path

lumi.switch.agl004

This is the US 1-channel model.

Endpoint 1

  • main relay
  • top button events
  • Aqara configuration attributes
  • metering / electrical measurement base clusters

Endpoint 4

  • bottom button events
  • Aqara multi_click attribute

Endpoint 21

  • special power reporting endpoint
  • public ZHA support maps this endpoint to a dedicated power-measurement handling path

lumi.switch.agl005

This is the US 2-channel model.

Endpoint 1

  • top relay
  • top button events
  • shared Aqara settings
  • metering / electrical measurement base clusters

Endpoint 2

  • bottom relay
  • bottom button events
  • per-channel Aqara settings

Endpoint 21

  • special power reporting endpoint
  • public ZHA support maps this endpoint to a dedicated power-measurement handling path

Zigbee clusters used by the driver

Standard clusters

0x0006 On/Off

Used for the actual relay state and relay commands.

0x0012 Multistate Input

Used for button action events. This cluster is especially important on the H2 because button actions are not just simple on/off presses.

0x000C Analog Input

Used on endpoint 21 for power reporting.

0x0702 Simple Metering

Used for accumulated energy (kWh).

0x0B04 Electrical Measurement

Used as a supplementary path for instantaneous power and scaling values.

Other standard clusters seen on the device

Depending on model and endpoint, public integrations also show the usual clusters such as:

  • 0x0000 Basic
  • 0x0003 Identify
  • 0x0004 Groups
  • 0x0005 Scenes
  • 0x000A Time
  • 0x0019 OTA

The Aqara manufacturer-specific cluster

The most important part of the Zigbee implementation is Aqara’s custom manufacturer-specific cluster:

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

This is where the interesting H2-specific settings live.

Known Aqara H2 attributes in 0xFCC0

Attribute ID Meaning Type / notes
power_on_mode 0x0517 startup behavior after power restore uint8 enum
operation_mode 0x0200 relay mode vs decoupled mode uint8 enum
led_indicator 0x0203 LED enable / disable bool
flip_led_indicator 0x00F0 reverse indicator logic bool carried as uint8 in ZHA
lock_relay 0x0285 relay lock bool carried as uint8 in ZHA
multi_click 0x0286 enables multi-click actions uint8; ZHA maps off=1, on=2

Value mapping used by public integrations

operation_mode

  • 0x00 = decoupled
  • 0x01 = relay / control relay

power_on_mode

  • 0x00 = on
  • 0x01 = previous
  • 0x02 = off
  • 0x03 = inverted

multi_click

Public ZHA support does not treat this as a plain 0/1 boolean. It maps:

  • 1 = off
  • 2 = on

That is an easy detail to miss and one of the reasons a dedicated driver is useful.

Features exposed by the driver

Relay control

  • separate SmartThings child device for each relay
  • standard switch capability for each child

Buttons

agl009

  • aggregate main
  • up
  • down

agl010

  • aggregate main
  • left
  • right
  • leftDown
  • rightDown

agl004

  • aggregate main
  • top
  • bottom

agl005

  • aggregate main
  • top
  • bottom

Button behavior currently modeled in SmartThings

Based on current testing and the current driver model:

  • EU upper buttons advertise pushed
  • EU lower buttons advertise pushed, double and held
  • WS-K02E top button advertises pushed
  • WS-K02E bottom button advertises pushed and double
  • WS-K03E top and bottom buttons advertise pushed
  • main acts as an aggregate button surface

This matches the practical observation that the lower buttons are the ones with explicit multi_click preferences and reliably exposed extra button actions, while the upper buttons behave more like standard relay-backed buttons.

Power and energy

The H2 is a little unusual here.

Power

Public ZHA support shows a dedicated power-measurement path on endpoint 21, based on AnalogInput.PresentValue, and configures reporting there.

This driver follows that idea and treats endpoint 21 as the preferred instantaneous-power path.

Energy

Accumulated energy comes from Simple Metering on the main relay endpoint.

Caveat

Aqara’s own product documentation says with-neutral wiring enables power monitoring and reports. So if the switch is wired without neutral, metering behavior may be limited or unavailable.

What public Zigbee integrations expose

Zigbee2MQTT

For WS-K07E, WS-K08E, WS-K02E and WS-K03E, Zigbee2MQTT documents exposure of items such as:

  • power
  • current
  • energy
  • LED indicator
  • flipped indicator
  • switch state
  • device temperature
  • power outage count
  • power-on behavior
  • operation mode
  • relay lock
  • multi-click
  • action events

ZHA

The public ZHA quirk work for the H2 defines:

  • a custom Aqara manufacturer cluster for H2 features
  • endpoint 21 power measurement handling
  • per-endpoint operation mode, lock relay, and multi-click settings
  • button automation triggers including single, double, hold, and release in the quirk mapping

That ZHA work is one of the strongest public references for understanding the H2’s Zigbee behavior.

Current driver scope

This driver is focused on the core SmartThings experience that is both useful and maintainable.

Implemented / intended core scope

  • child relay switches
  • button events
  • LED indicator preference
  • flipped LED preference
  • power-on behavior preference
  • decoupled mode preference
  • relay lock preference
  • multi-click preference
  • power meter
  • energy meter

Documented by public integrations, but not necessarily exposed yet

Depending on the exact build revision, the following capabilities may still be future work rather than guaranteed SmartThings features:

  • currentMeasurement
  • device temperature
  • power outage count
  • release button events

The README lists them because they are relevant to the device and documented in Zigbee2MQTT / ZHA, but they should not be confused with a promise that every one of them is already exposed in the SmartThings UI.

Why not just use a single giant multi-component device?

That would work technically, but it is less elegant.

Using child devices gives you:

  • one switch tile per relay
  • clearer automations
  • a structure that feels more like the official SmartThings Matter switch handling
  • a clean separation between relay outputs and button surfaces

For a device like the H2, that is a very natural representation.

Known design trade-offs

  • The device is dual-protocol, but this driver intentionally focuses on Zigbee mode because that is where the device-specific Aqara feature surface is visible.
  • Public Zigbee integrations document more features than a conservative SmartThings driver should necessarily expose on day one.
  • Power / energy behavior may depend on neutral wiring.
  • If child devices are deleted manually, SmartThings parent/child models often require re-creation during onboarding or driver-managed reconciliation.

Sources

Official Aqara

Public Zigbee references

2 Likes
2

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 …

3

Driver added to GitHub