Aqara Wireless Mini Switch (WXKG11LM): Pair with Zigbee2MQTT and Build Home Assistant Automations Without the Aqara Hub

The Aqara Wireless Mini Switch is a CR2032-powered Zigbee button that fits in a shirt pocket and sticks anywhere with double-sided tape. Single press, double press, hold — three distinct actions from a $10 device, no wiring required.

The catch: Aqara’s official setup path runs through the Aqara hub and the Aqara Home app, both of which phone home to Aqara’s cloud servers. Every button press, every automation trigger, routes through Aqara’s infrastructure before reaching your lights.

Zigbee2MQTT cuts that dependency entirely. The WXKG11LM pairs directly to your Zigbee coordinator, actions appear in Home Assistant as device triggers, and everything stays on your LAN. No Aqara account. No hub. No cloud.

This guide covers pairing, action types, and building clean HA automations for each press type.

Prerequisites

Before starting, you need:

If you don’t have Z2M set up yet, see the Xiaomi/Aqara Zigbee + Zigbee2MQTT overview for coordinator recommendations and initial setup.

Model Clarification — Which Aqara Button Do You Have?

Aqara makes several similar-looking single-button switches. Confirm your model before proceeding — the action sets differ.

WXKG11LM — Aqara Wireless Mini Switch (this guide)

Flat, square form factor. Single physical button. Core actions in Zigbee2MQTT: single, double, hold, release. Some hardware revisions also expose triple and quadruple. This is the most common Aqara button and the subject of this guide.

WXKG12LM — Aqara D1 Wireless Mini Switch

Similar appearance to the WXKG11LM but consistently exposes an expanded action set including triple and many (rapid presses). If you have a WXKG12LM, the pairing process is identical but your automation triggers will differ. Check the label on the back of the device — the model number is printed there.

Both devices pair natively with Zigbee2MQTT. This guide uses WXKG11LM action values throughout.

Pairing the WXKG11LM with Zigbee2MQTT

Enable Permit Join in Z2M

Open Zigbee2MQTT’s web interface — typically http://your-ha-ip:8080 for standalone installs (port may differ based on your config), or via the HA sidebar if using the add-on. Click Permit join (All) to open a pairing window. You can also permit join for a specific device group if you prefer to limit exposure.

Trigger Pairing Mode on the Switch

With the permit join window open:

The switch will attempt to join the nearest Zigbee coordinator. Pairing typically completes within 15 seconds.

Confirm Pairing in Z2M

Once paired, the Z2M device list will show a new entry: Aqara WXKG11LM (or similar, depending on your Z2M version). The device will appear with a model name, IEEE address, and link quality indicator.

Home Assistant will automatically discover the new device via the Z2M MQTT integration. Navigate to Settings → Devices & Services → MQTT → Devices to confirm it appears.

Troubleshooting: Pairing Failures

Device doesn’t appear in Z2M: Battery contact is the most common cause on new devices. Remove the battery, wait 10 seconds, reinsert, and retry pairing within the permit join window. If the battery was pre-installed at the factory, it may have a protective film — check and remove if present.

Device pairs but shows no actions in HA: This is usually a configuration issue — see the section below on action entity changes and legacy mode in Zigbee2MQTT.

Understanding Action Types in Zigbee2MQTT

WXKG11LM Action Values

The WXKG11LM exposes these action values via Z2M:

For most automations, you’ll use single, double, and hold. release is useful if you want push-and-hold dimming behavior (increment brightness while held, stop on release). Whether triple and quadruple appear depends on your specific device revision.

How Z2M Exposes Actions: Current vs Legacy Behavior

Zigbee2MQTT exposes button actions via MQTT device triggers in Home Assistant — this is the recommended path and works in all current Z2M versions. When you press the button, Z2M publishes to the device’s MQTT topic (e.g., zigbee2mqtt/aqara_mini_switch) with a payload like {"action": "single"}, and HA’s MQTT integration surfaces this as a device trigger you can attach automations to.

There are two deprecated mechanisms you may encounter:

Deprecated click event: By default on some device firmware combinations, a legacy click event is exposed alongside action. Disable it by adding legacy: false to that device’s entry in your Z2M configuration.yaml:

devices:
  '0x12345678':
    friendly_name: aqara_mini_switch
    legacy: false

Deprecated action sensor entity: Older Z2M setups exposed a persistent sensor._action entity that you’d trigger automations on via state change. In current Z2M this requires explicitly setting homeassistant: {legacy_action_sensor: true} in Z2M config. It’s deprecated and will be removed — use device triggers instead.

To confirm actions are working: Open the Z2M web interface, navigate to your device, and watch the live MQTT log while pressing the button. You should see the action payload appear immediately. Alternatively, open HA’s Developer Tools → MQTT (if you have the MQTT integration) and subscribe to zigbee2mqtt/ to watch messages in real time.

Building Automations in Home Assistant

Method 1 — Using the HA UI (Device Triggers)

The fastest path for simple automations:

HA handles the event subscription and action mapping for you. This works for straightforward one-trigger-one-action automations.

Note: device triggers in HA are discovered after the action fires at least once — press your button once after pairing to make the trigger types appear in the UI.

Example: UI-generated YAML for a single press light toggle

alias: Mini Switch — Single Press Toggle Bedroom Light
description: ""
trigger:
  - platform: device
    domain: mqtt
    device_id: <your_device_id>  # filled automatically by UI
    type: action
    subtype: single
condition: []
action:
  - action: light.toggle
    target:
      entity_id: light.bedroom_ceiling
mode: single

Method 2 — YAML Automation with Multiple Triggers (All Press Types)

For handling all press types in a single automation, the choose block approach is cleaner than three separate automations:

alias: Mini Switch — All Actions
description: "Handles single, double, and hold for the bedroom mini switch"
trigger:
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: single
    id: single
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: double
    id: double
  - platform: device
    domain: mqtt
    device_id: <your_device_id>
    type: action
    subtype: hold
    id: hold
condition: []
action:
  - choose:
      - conditions:
          - condition: trigger
            id: single
        sequence:
          - action: light.toggle
            target:
              entity_id: light.bedroom_ceiling
      - conditions:
          - condition: trigger
            id: double
        sequence:
          - action: scene.turn_on
            target:
              entity_id: scene.movie_mode
      - conditions:
          - condition: trigger
            id: hold
        sequence:
          - action: notify.mobile_app_your_phone
            data:
              title: "Alert"
              message: "Mini switch hold triggered"
mode: single  # prevents queued actions from rapid double presses

mode: single is important here. Without it, if someone taps the button rapidly, HA will queue multiple action executions. mode: single ignores new triggers while an action is running — cleaner behavior for a button that might get pressed impatiently.

Practical Automation Examples

Single press — toggle bedroom light: The example above covers this. Works well as the “primary” function of the button.

Double press — run a scene: The scene.movie_mode example above dims lights, turns off overhead lighting, and activates whatever devices you’ve configured in the scene. Double press is useful for multi-device state changes that would be tedious to configure as individual toggle actions.

Hold — send a push notification (or trigger an alarm): Good for a low-cost “panic button” use case. An Aqara mini switch stuck behind a bedside table becomes a discreet alert trigger. Pair this with a notify action to your phone or a local alarm system automation.

Release — push-and-hold dimming (advanced): If you want to dim a light while holding the button and stop when released:

# In the "hold" sequence:
- action: input_boolean.turn_on
  target:
    entity_id: input_boolean.mini_switch_held
- repeat:
    while:
      - condition: state
        entity_id: input_boolean.mini_switch_held
        state: "on"
    sequence:
      - action: light.turn_on
        target:
          entity_id: light.bedroom_ceiling
        data:
          brightness_step: -10  # dim by 10 each iteration
      - delay:
          milliseconds: 300

# In the "release" sequence:
- action: input_boolean.turn_off
  target:
    entity_id: input_boolean.mini_switch_held

This requires an input_boolean helper to track held state. For most users, the simpler single/double/hold approach without release is sufficient.

Using a Blueprint (Optional — Fastest Path)

If you want to skip manual YAML entirely, the HA community has published blueprints specifically for the WXKG11LM. Search the Home Assistant Blueprint Exchange for “WXKG11LM.”

Blueprints let you assign actions to each press type through a UI form — no YAML editing. They’re a good fit if your automation needs are straightforward and you don’t want to maintain raw YAML.

The tradeoff: blueprints are less flexible if you need conditional logic, multiple targets, or press-type combinations. They also still require you to have completed Z2M pairing first — blueprints abstract the automation, not the Zigbee setup.

For anything beyond simple toggle/scene actions, the YAML approach gives you full control.

Privacy and Local-Only Operation

With this setup, the data flow is:

Button press → Zigbee RF → Coordinator → Zigbee2MQTT (local MQTT broker) → Home Assistant → your automation

Nothing leaves your LAN. No DNS lookups to Aqara servers, no cloud authentication, no telemetry.

Compare this to the official Aqara path: button press → Aqara hub → Aqara cloud → action returned to hub → your device. Every press creates an external network event, whether or not you ever look at the Aqara app again.

The WXKG11LM paired via Z2M has no persistent connection to Aqara’s infrastructure. The device broadcasts a Zigbee packet; Z2M receives it. That’s the entire interaction. Aqara has no visibility into when or how often you press the button.

Battery Life and Monitoring

The WXKG11LM runs on a single CR2032. Under normal usage — a few presses per day — expect 12–24 months of battery life. Zigbee button devices are among the most battery-efficient in the ecosystem because they’re radio-silent between presses.

Z2M exposes a battery entity for the device in HA. Set up a low-battery alert so you’re not caught off-guard:

alias: Mini Switch — Low Battery Alert
trigger:
  - platform: numeric_state
    entity_id: sensor.aqara_mini_switch_battery
    below: 20
condition:
  - condition: template
    value_template: >
      {{ (now() - states.sensor.aqara_mini_switch_battery.last_changed).total_seconds() > 86400 }}
action:
  - action: notify.mobile_app_your_phone
    data:
      title: "Low Battery"
      message: "Aqara mini switch battery below 20%"
mode: single

The condition prevents repeated alerts every time HA restarts and re-evaluates the battery state — it only fires if the sensor has been below 20% for more than 24 hours.

CR2032 cells are available anywhere and cost under $1 each. Keep a small stock.

Wrapping Up

The Aqara Wireless Mini Switch is one of the easiest local Zigbee wins available — under $10, no wiring, no hub, pairs in under a minute with Z2M. Three distinct actions give you enough flexibility to cover most button-automation use cases without reaching for a more expensive controller.

The Aqara ecosystem has plenty of other local-compatible devices worth pairing with this setup. If you want more actions per device, the Aqara Cube T1 Pro exposes rotation, flip, shake, and tap — useful when a button isn’t expressive enough. For wired wall switch replacements, the Aqara H1 switch in decoupled mode turns a standard wall switch into a Z2M device trigger without rewiring the load.

By N. Lee