Aqara Wireless Remote Switch H1 (WRS-R02): Zigbee2MQTT Setup Guide
The WRS-R02 is one of those Aqara devices that looks dead simple but has a few specific traps: a ZHA quirk that fails silently, an action entity that disappears before your automation can catch it, and a pairing sequence that requires you to keep the device awake manually. Get past those three things and you have a battery-powered double-rocker that sticks anywhere, exposes twelve distinct button actions, and sends zero traffic outside your network.
This guide covers everything end-to-end: pairing via Zigbee2MQTT, the entities that appear in Home Assistant, how to wire button actions to automations reliably, and why ZHA is the wrong choice for this device.
What the WRS-R02 actually is
The full model name is Aqara Wireless Remote Switch H1 (Double Rocker). The Zigbee device ID is lumi.remote.b28ac1. It is battery-powered, with no wiring required — you peel the adhesive backing and stick it wherever you want a switch.
It is a Zigbee end device, not a router. That matters for one practical reason: it does not extend your Zigbee mesh. If you have a thin mesh with few mains-powered routers, don’t expect the WRS-R02 to help fill the gaps. Keep it within reliable range of your coordinator or a Zigbee router. For the broader picture on running Aqara Zigbee gear without the Aqara hub, see our guide to Aqara Zigbee devices in Home Assistant without a hub.
There is no wired equivalent here. The WRS-R02 is often confused with the H1 wall switch (WS-EUK02) — that’s a different product entirely, hardwired into a wall box. The WRS-R02 needs no mains connection.
What you need
- A Zigbee coordinator (Sonoff Zigbee 3.0 USB Dongle Plus, HUSBZB-1, or similar)
- Zigbee2MQTT running as a Home Assistant add-on or standalone
- Home Assistant
You do not need an Aqara hub, the Aqara Home app, or any cloud account. Once paired via Z2M, the device operates entirely on your local network.
Pairing to Zigbee2MQTT
Put Zigbee2MQTT into pairing mode (Permit join on) from the Z2M frontend or the HA integration.
To trigger pairing on the WRS-R02, hold the left rocker button for approximately 10 seconds. The LEDs will flash to confirm it has entered pairing mode.
Here is the one thing that will trip you up if you don’t know it ahead of time: the WRS-R02 is a sleepy end device. After pairing mode is initiated, it will go back to sleep within seconds if you do nothing. While Z2M is configuring the device, press one of the rockers every second or so to keep it awake. If Z2M fails to configure the device fully the first time — you see it appear in the device list but the action entity is missing or shows unavailable — remove the device and re-pair while actively pressing a button through the entire join process.
Once paired successfully, the device will appear in Z2M with the model WRS-R02 and device ID lumi.remote.b28ac1. Home Assistant will discover it automatically through the Z2M MQTT integration.
What entities appear in Home Assistant
After a clean pair you get three entities:
| Entity | Type | Notes |
|---|---|---|
sensor.<name>_action |
Sensor | The main button action entity — the one you automate on |
sensor.<name>_battery |
Sensor | Battery voltage (not percentage) |
sensor.<name>_linkquality |
Sensor | Link quality indicator |
Battery percentage is not directly exposed. You monitor battery health through the voltage entity. A fresh CR2032 or equivalent at 3.0V reads full, and the device will start behaving unreliably well before the voltage bottoms out, so watch for readings dropping below around 2.7V.
The 12 button actions explained
Z2M exposes the following action types for the WRS-R02:
| Action | Trigger |
|---|---|
single_left |
One press, left rocker |
double_left |
Two presses, left rocker |
triple_left |
Three presses, left rocker |
hold_left |
Hold left rocker |
single_right |
One press, right rocker |
double_right |
Two presses, right rocker |
triple_right |
Three presses, right rocker |
hold_right |
Hold right rocker |
single_both |
One press, both rockers simultaneously |
double_both |
Two presses, both rockers |
triple_both |
Three presses, both rockers |
hold_both |
Hold both rockers |
That is twelve distinct triggers from one two-rocker device. One caveat: the WRS-R02 exposes a click_mode setting in Z2M, and the default fast mode only sends single clicks. To get double, triple, and hold actions, set click_mode to multi on the device’s settings page in Z2M. In practice, I find single and double presses on each rocker plus the hold actions cover most use cases — triple and both-button combos are available if you need the extra scene slots.
If you are working from an older blueprint that uses action names like button_1_single or button_2_double, those are from an earlier Z2M format and will not fire with current Z2M versions. The current format is single_left, double_right, and so on as listed above.
Building automations the reliable way
The action entity works differently from a standard state entity, and if you don’t account for this, your automations will miss button presses.
When you press a rocker, the action sensor briefly shows the action string — single_left, for example — then Z2M immediately publishes an empty string to reset it. If you use an entity state trigger watching for single_left, HA may or may not catch the transition before it clears. The timing is tight enough that missed triggers are common.
The reliable method is to trigger directly on the MQTT topic instead of the entity state. Z2M publishes the device’s full JSON state to zigbee2mqtt/<device_name>, with the action value in the action field, the moment the button event occurs. An MQTT trigger in HA catches that publish consistently, with no dependence on how quickly the sensor entity is read before it resets.
In your automation:
trigger:
- platform: mqtt
topic: zigbee2mqtt/your_switch_name/action
payload: single_left
Replace your_switch_name with whatever you named the device in Z2M. Repeat the trigger block for each action you want to respond to, or use a template condition in the action block if multiple triggers share the same response.
This approach is more verbose than a device trigger, but it is the reliable one. Device triggers in the HA UI are built on the entity state path and will occasionally miss fast presses.
Using the community blueprint
There are two blueprint versions in the HA community forums for the WRS-R02: the original thread and an updated version that added triple-press and hold support.
If you want a ready-made blueprint rather than building automations from scratch, use the updated version — it covers the full action set and uses the correct single_left style naming. Import via the blueprint import URL from the HA frontend (Settings > Automations > Blueprints > Import Blueprint).
Once imported, the blueprint creates an automation where you map each of the twelve actions to a service call or script. It handles the MQTT trigger internally so you don’t have to write the topic configuration yourself.
ZHA vs. Zigbee2MQTT for the WRS-R02
Do not use ZHA for this device. I’m flagging this prominently because it fails silently, which is worse than a hard error.
When paired through ZHA — including with the SkyConnect dongle — the WRS-R02’s required device quirk (aqara_h1_remote.RemoteH1DoubleRocker2) is not automatically applied. The result is that button presses register no events in HA at all. The device appears paired and healthy in the ZHA device list. Nothing appears to be wrong. But presses don’t fire anything.
There is a second failure mode specific to ZHA: even in cases where some events do appear, both the left and right rockers fire the same event (remote_button_short_press). The distinction between left and right is lost entirely. This makes the device nearly useless as a multi-scene controller.
A workaround exists involving manual custom_quirks_path configuration in ZHA, but it requires placing a custom Python quirk file on the HA filesystem and restarting ZHA — not something I’d recommend as a baseline setup path when Z2M works cleanly. This is a known open issue in the HA core tracker (issue #112045) with no committed fix timeline.
Use Z2M. You get all twelve actions, reliable triggers, and a clean pairing experience.
HomeKit Controller path
If you are running the WRS-R02 through an Aqara hub using the HomeKit Controller integration, be aware of what you lose. The device appears in HA as AR009 and does not expose button sensor data that HA automations can act on. You get device presence, but you cannot trigger automations from button presses through this path.
This is a fundamental limitation of how the Aqara hub exposes remotes through HomeKit. The hub handles button events internally and uses them to trigger hub-side automations, but those events are not forwarded to HA in a form that the automation engine can use. If button-driven HA automations are your goal, Z2M direct pairing is the only path that actually works. For more on what stays local versus what needs the hub, see does Aqara work without internet.
Privacy: what this switch sends
When paired via Zigbee2MQTT, the WRS-R02 sends nothing outside your network. No outbound traffic to Aqara servers, no telemetry, no cloud callbacks. The Zigbee radio communicates only with your coordinator. Z2M publishes to your local MQTT broker. HA subscribes locally.
The Aqara Home app is not required after initial pairing. You can uninstall it if that was the only device you were setting up this way.
Troubleshooting
Device paired but action entity is missing or shows unavailable. Almost always the keep-awake issue during pairing. Remove the device from Z2M, start a fresh pair, and press a rocker button every second throughout the join process. The entity should appear within 30 seconds of a clean pair.
Actions stopped firing after battery replacement. The device re-registers with the coordinator after battery removal, but occasionally the Z2M interview doesn’t complete if the device went to sleep. Press a button a few times after reinserting the battery to wake it and let Z2M re-interview. If the action entity goes unavailable, remove and re-pair.
Automations fire unreliably. Check whether you are using entity state triggers or MQTT triggers. Switch to the MQTT topic method described above. Entity state triggers on the action sensor are prone to missing events because Z2M resets the value to an empty string immediately after each press.
Only single clicks register; no double, triple, or hold. The device is in click_mode: fast. Open the device’s settings in Z2M and switch click_mode to multi to enable the full action set.
Both buttons firing the same action. This is the ZHA quirk failure described above. If you paired via ZHA, migrate to Z2M. If you are already on Z2M and both rockers fire the same action, re-pair — the device may have not completed the interview properly.
Battery reads lower than expected immediately after pairing. The battery entity has approximately a 24-hour reporting delay after first pairing. The reading you see in the first day may not reflect actual charge. Check again after 24 hours.
Related switches in the same category: the Aqara Wireless Switch E1 (WXKG15LM/WXKG16LM) covers the E1 single-rocker and two-rocker wireless switches, which use a similar action structure. The Aqara Wireless Mini Switch T1 (WXKG14LM) is the single-button alternative for simpler trigger setups. If you want a controller with gesture-based inputs instead of discrete button presses, the Aqara Cube T1 Pro handles rotation, tap, and flip actions in a similar local-only Z2M workflow.