Aqara Display Switch V1 (WS-K02D): Zigbee2MQTT & Home Assistant Setup
The Aqara Display Switch V1 (WS-K02D) is one of the more interesting wall switches I’ve come across in the Aqara lineup — a dual-relay panel with a color LCD that can show a clock, weather, or a live sensor reading from your home. On paper, it ticks a lot of boxes. In practice, the path to actually using it without Aqara’s cloud is less documented than it should be.
The short version: the WS-K02D is not in Zigbee2MQTT’s official supported devices list as of June 2026. But a working external converter exists, and once it’s in place the device pairs cleanly and exposes a solid set of entities in Home Assistant. This guide covers the setup from start to finish.
If you’re still deciding between ZHA and Zigbee2MQTT for Aqara devices generally, that comparison is worth reading first.
What is the Aqara Display Switch V1 (WS-K02D)?
The WS-K02D is a Zigbee 3.0 wall switch with two independent relay channels, four capacitive touch buttons, a color LCD panel, and a proximity sensor. The display can show a digital clock, weather data, or a reading from a linked sensor — temperature from a nearby sensor, for instance. It requires a neutral wire.
Because it’s wired with neutral, it also acts as a Zigbee router, extending mesh coverage. That’s useful in a larger install.
One thing to clarify upfront: the WS-K02D is frequently confused with the WS-K01D. The WS-K01D is a different device entirely — it’s the Aqara H1 20A single rocker with neutral, no display, and it’s officially supported in Zigbee2MQTT. If you’re on the WS-K01D, you don’t need this guide. If you have the display panel, read on.
In Chinese market listings and renovation communities, this switch appears under the product family 绿米 (Lümi/Aqara) and is commonly referred to as the 妙控开关 V1 (Myco Control Switch V1 — a community nickname for the V1 LCD series). It’s a popular choice for new-home builds where buyers want a premium-looking switch that shows information, but the local integration path is essentially undocumented in most Chinese renovation guides.
Two paths to Home Assistant — and why one of them involves Aqara’s cloud
Before getting into the setup, it’s worth understanding the two available integration paths, because they have meaningfully different implications.
Path A: Matter-over-Bridge via an Aqara Hub
Aqara’s own integration story goes through an Aqara Hub (M2, M3, or M1S Gen 2), which exposes the WS-K02D via Matter to Home Assistant. Our Matter bridge guide has a full breakdown of how the Matter bridge path works.
The catch is that setup requires an Aqara cloud account and initial internet access, and the hub remains in the loop for ongoing operation. More specifically: the display’s weather content is pulled from Aqara’s cloud, not from a local source. If you’re trying to eliminate that cloud dependency entirely, the Matter bridge path doesn’t get you there.
Path B: Direct Zigbee via Zigbee2MQTT
The Z2M path bypasses the Aqara Hub completely. The WS-K02D connects directly to your Zigbee coordinator, pairs with Zigbee2MQTT via an external converter, and all display data — weather, sensor readings — is pushed from Home Assistant locally. No Aqara account, no hub, no cloud in the data path.
This is the privacy distinction that the Chinese community discussion on V2EX surfaces clearly. Users in those threads note that even when Aqara devices support HomeKit, the device can still connect to Aqara’s own app at the same time — HomeKit integration doesn’t prevent Aqara from maintaining its own data collection surface. The Z2M path eliminates that surface entirely. Community consensus: use Zigbee2MQTT, block Aqara cloud at the firewall if you want to be sure.
For anyone who bought this switch specifically to get local weather and sensor data on a wall panel without routing it through a vendor’s servers, the Z2M path is the right choice.
Installing the external converter in Zigbee2MQTT
Since the WS-K02D isn’t in Z2M’s native device database (at time of writing — check the Z2M supported devices list for updates), you need an external converter: a JavaScript file that tells Z2M how to talk to the device.
Here’s what the setup looks like.
1. Locate or create the external_converters directory
In your Zigbee2MQTT data folder (the same directory as configuration.yaml), create an external_converters directory if it doesn’t already exist:
mkdir -p /path/to/zigbee2mqtt-data/external_converters
Z2M automatically loads any .js files in this directory on startup — no changes to configuration.yaml needed.
2. Add the WS-K02D converter file
Download or create aqara_ws_k02d.js in that directory. The current working converter for this device, with full display and button support, is published in SmartHomeScene’s WS-K02D integration guide — the best English reference for the file as of mid-2026. Community converters move, so confirm you’re copying the latest version from that page before pasting it in.
3. Restart Zigbee2MQTT
Z2M will load the converter on startup. Check the Z2M log output to confirm it picked up the file — you should see a line mentioning the external converter loading successfully.
What I didn’t expect on first run was that Z2M logged the converter as loaded but then failed to match the device immediately after pairing — it turned out the device identifier in the JS file needed to match what the WS-K02D was advertising over Zigbee (the converter targets the lumi.switch.aeu003 model ID). If you hit that, check the Z2M “Devices” tab after pairing; if the device shows up as “unsupported” rather than “Aqara Display Switch V1,” the converter file may need the model identifier updated to match your firmware’s advertised model.
Pairing the WS-K02D
With the converter in place, pairing is the standard Zigbee flow.
- In the Z2M web UI, click “Permit join (all)” to open the network.
- On the WS-K02D, press and hold the top-left button for 5 seconds. The display will show a pairing animation.
- The device should appear in Z2M within 30–60 seconds.
Once paired, the device shows up as “Aqara Display Switch V1” in Z2M’s device list, and its entities propagate to Home Assistant via MQTT discovery.
What entities you get in Home Assistant
After pairing with the external converter, the WS-K02D exposes a useful set of entities:
Relay switches
– switch.state_l1 — controls relay channel 1
– switch.state_l2 — controls relay channel 2
Both relay channels can be controlled independently from HA.
Power monitoring
– sensor.voltage
– sensor.current
– sensor.power
– sensor.energy
The power monitoring is a practical feature — you can see how much energy the switched circuits are drawing without an additional clamp meter.
Button action events
All four touch buttons fire action events when set to “button” mode (see below). These show up on the device’s action value and are standard HA events you can trigger automations from.
Display configuration entities
– number.brightness — screen brightness
– select.screen_saver_type — clock, weather, or sensor reading
– select.time_zone — inherited from HA’s timezone setting
The display configuration is pushed to the switch from HA via Z2M, all locally.
Configuring the display and button behavior
Button mode: relay vs. button
Each of the four touch buttons can operate in one of two modes. In relay mode, pressing the button directly toggles the corresponding relay. In button mode, the button fires an action event that you handle in HA automations — useful for controlling things unrelated to the local relays (a light in a different room, a scene, whatever).
One limitation: in button mode over Zigbee, only single press is supported. Double-press and long-hold actions are not available via Z2M as of June 2026. If you need those, the Matter bridge path may expose them, but you’re back to the cloud dependency.
Screen saver options
The display screen saver has three modes:
- Digital clock — shows time, pulled from HA’s system time (local, no cloud call).
- Weather — requires linking a HA weather entity. The weather data is pulled from whatever integration provides your
weather.entity in HA — that could be a local forecast provider or a cloud one, depending on your setup. The WS-K02D itself doesn’t call Aqara’s weather servers in this path. - Sensor reading — links to any HA sensor entity. Temperature from a nearby Aqara sensor, CO2 from an air quality monitor, whatever makes sense at the installation location.
Icons and labels
Each of the four button positions has a configurable icon and label shown on the display. These are set via Z2M entities and propagate to the display immediately.
Pushing weather and sensor data to the display
To feed live data to the display, you publish to the device’s Z2M set topic from a Home Assistant automation. The key thing to get right is the destination topic — it’s zigbee2mqtt/<friendly_name>/set — and the payload keys, which are defined by the converter you installed. The converter guide lists the exact display-control keys; treat the example below as the wiring pattern and substitute the field names from that guide:
alias: Push outdoor temperature to WS-K02D display
trigger:
- platform: state
entity_id: sensor.outdoor_temperature
action:
- service: mqtt.publish
data:
topic: zigbee2mqtt/Aqara Display Switch V1/set
payload: >
{"<display_field_from_converter>": {{ states('sensor.outdoor_temperature') | float(0) }}}
Use the same pattern to push an indoor humidity reading or any other HA sensor value — only the source entity and the converter’s display field change. If you’re unsure which field a given screen-saver mode reads from, the converter guide documents each one; Z2M’s “Exposes” tab for the device is the other reliable place to confirm the writable keys.
Using button actions in automations
When a button is in button mode, pressing it publishes an action string on the device’s MQTT state topic, which you can match in an automation. The robust pattern is an MQTT-topic trigger that watches the device’s action field:
alias: Button 1 triggers evening scene
trigger:
- platform: mqtt
topic: zigbee2mqtt/Aqara Display Switch V1
action:
- choose:
- conditions:
- condition: template
value_template: "{{ trigger.payload_json.action == 'button_1_single' }}"
sequence:
- service: scene.turn_on
target:
entity_id: scene.evening
The exact action string each button emits (the value you compare against — for example a button_1_single-style label) is defined by the converter and shown live on the device’s action value in Z2M when you press a button. Press each button once with the Z2M device page open, note the string it emits, and use that literal value in your template. The four buttons give you four independent triggers per switch, which is more than enough for scene control or grouped lighting.
Limitations to know before you buy
No double-press or hold over Zigbee
Single press only in button mode. If button gesture variety matters, the Matter bridge path may support more, but that trade-off puts Aqara’s hub back in the loop.
External converter means no OTA updates via Z2M
Because the device isn’t in Z2M’s native database, you won’t get OTA firmware updates through Z2M. If Aqara releases a firmware update for the WS-K02D, you’ll need to apply it through the Aqara Home app — which requires pairing the device temporarily to an Aqara Hub. It’s an annoying two-step, but it’s infrequent enough that it’s not a dealbreaker for most setups. Once updated, re-pair to Z2M and continue.
Official Z2M support pending
The WS-K02D isn’t in the Z2M supported devices list yet. That could change — native support is tracked in the Z2M GitHub new-device-support issue for the Display Switch V1 EU (#26407). If a community contributor lands a PR there, the device will eventually appear natively and the external converter won’t be needed.
Honestly, I think the external converter situation is fine for a device of this type — it’s not complex hardware, and the converter covers the full feature set. What I’d rather see is the OTA gap closed so users don’t have to shuffle the switch between HA and the Aqara app for firmware updates. That friction is the one real rough edge here.
Does it work offline after setup?
Yes, within the bounds of your HA instance. Once paired via Z2M, the WS-K02D does not require internet access for relay control or button events. The display’s clock and sensor readings come from HA locally.
The only caveat is the weather display: if your HA weather entity pulls from an internet source (like the Met.no or OpenWeatherMap integration), then weather data on the display indirectly requires internet — but that’s your HA weather provider, not Aqara. Switch to a local weather integration if that matters to you.
At the firewall level, you can block all outbound traffic from the WS-K02D’s Zigbee coordinator address and the device will continue operating. That’s the clean local setup.
Quick FAQ
Does the Aqara Display Switch V1 work with Home Assistant without a hub?
Yes — with Zigbee2MQTT and the external converter. No Aqara Hub or account needed.
What shows on the display when connected via Zigbee2MQTT?
Clock (from HA system time), weather (from your HA weather entity), or a sensor reading (any HA sensor). All pushed locally from HA via MQTT.
Can the WS-K02D work completely offline?
Yes, for relay control and button events. Weather data depends on your HA weather integration.
What’s the difference between the Zigbee path and the Matter-over-Bridge path?
Zigbee2MQTT: no hub required, no cloud, full local control, display content from HA locally. Matter bridge: Aqara Hub required, cloud account needed for setup, display weather from Aqara’s cloud. See our Matter bridge guide for the bridge path in detail.
Is the WS-K02D the same as the WS-K01D?
No. The WS-K01D is the H1 20A single-rocker (no display), officially supported in Z2M. The WS-K02D is the display switch and needs an external converter.
The official Z2M device entry for the WS-K02D, if it ever lands, will likely clean up the OTA gap and possibly add double-press support. Until then, the external converter route is what there is — and it works. If you want a related panel-style controller that also runs fully local via Z2M, see our Aqara Rotary Knob H1 guide.