The Xiaomi Gateway (Aqara) integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to integrate Xiaomi Aqara-compatible devices into Home Assistant.

Supported devices

• Aqara Air Conditioning Companion (lumi.acpartner.v3)
• Aqara Intelligent Door Lock (lock.aq1)
• Aqara Wall Switch (Double)
• Aqara Wall Switch (Single)
• Aqara Wall Switch LN (Double)
• Aqara Wall Switch LN (Single)
• Aqara Wireless Switch (Double)
• Aqara Wireless Switch (Single)
• Battery
• Button 1st generation (Single, Double, Long Click)
• Button 2nd generation (Single, Double)
• Cube
• Door and Window Sensor (1st and 2nd generation)
• Gas Leak Detector (reports alarm and density)
• Gateway (Light, Illumination Sensor, Ringtone play)
• Intelligent Curtain
• Motion Sensor (1st and 2nd generation)
• Plug aka Socket (Zigbee version, reports power consumed, power load, state and if the device is in use)
• Smoke Detector (reports alarm and density)
• Temperature and Humidity Sensor (1st and 2nd generation)
• Vibration Sensor
• Wall Plug (reports power consumed, power load, and state)
• Water Leak Sensor
• Xiaomi Mijia Gateway (lumi.gateway.v2, lumi.gateway.v3)

Unsupported devices

• Xiaomi Aqara Gateway (lumi.gateway.aqhm01), as it is not possible to activate dev mode in the Mi Home App.
• Gateway Radio
• Gateway Button
• Xiaomi Mi Air Conditioning Companion (lumi.acpartner.v2)
• Aqara Intelligent Air Conditioner Controller Hub (lumi.acpartner.v1)
• Decoupled mode of the Aqara Wall Switches (Single & Double)
• Additional alarm events of the Gas and Smoke Detector: Analog alarm, battery fault alarm (smoke detector only), sensitivity fault alarm, I2C communication failure

Setup

Follow the setup process using your phone and Mi-Home app. From here you will be able to retrieve the key (password) from within the app following this tutorial.

To enable Xiaomi Gateway (Aqara) in your installation, go to Settings > Devices & services. Xiaomi Aqara gateways should be discovered automatically and should show up in the overview. Hit configure and go through the steps to specify the optional settings. If your Aqara gateway does not show up automatically, click the + icon in the lower right. Then, search for “xiaomi_aqara” and enter the setup. Multiple gateways can be configured by simply repeating the setup multiple times.

Entities

The Xiaomi Gateway (Aqara) integration supports the following entities.

Covers

The cover entity allows you to control connected Aqara covers. You can do the following:

• Open the cover.
• Close the cover.
• Stop the cover motion.
• Move the cover to a specific position.
• See the current position of the cover.

Lights

The light entity allows you to control the internal light of the Xiaomi gateway. The entity is called light.gateway_light_28ffffffffff. You can do the following:

• Turn the light on and off.
• Set the brightness.
• Set the color using HS or RGB color coding.

The requirement is that you have set up Xiaomi aqara.

Locks

An Aqara lock cannot be controlled by Home Assistant. However, the lock entity allows you to view the following data:

• The property changed_by provides the user/key ID of the last successful unlock.

• If someone tries to unlock the device but fails more than 3 times, the verified_wrong_times attribute will be incremented. The counter resets on a successful unlock.

Binary sensors

The binary sensor entities allow you to get data from your Xiaomi binary sensors.

Type of binary sensors supported

List of supported binary sensors, including the following properties (if available): name, model no., Zigbee entity, states, and, event, event, key, and event values.

• Motion Sensor (1st gen)

  • Model no.: RTCGQ01LM
  • Zigbee entity: motion
  • States: on, off
  • Event: xiaomi_aqara.motion

• Motion Sensor (2nd gen)

  • Model no.: RTCGQ11LM
  • Zigbee entity: sensor_motion.aq2
  • States: on, off
  • Event: xiaomi_aqara.motion

• Xiaomi Door and Window Sensor (1st gen)

  • Model no.: MCCGQ01LM
  • Zigbee entity: magnet
  • States: on, off

• Aqara Door and Window Sensor (2nd gen)

  • Model no.: MCCGQ11LM
  • Zigbee entity: sensor_magnet.aq2
  • States: on, off

• Smoke Detector

  • Model no.: JTYJ-GD-01LM/BW
  • Zigbee entity: smoke
  • States: on, off

• Gas Leak Detector

  • Model no.: JTQJ-BF-01LM/BW
  • Zigbee entity: natgas
  • States: on, off

• Water Leak Sensor

  • Model no.: SJCGQ11LM
  • Zigbee entity: sensor_wleak.aq1
  • States: on, off

• Button (1st gen)

  • Model no.: WXKG01LM
  • Zigbee entity: switch
  • States: on (through long_click_press), off
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: long_click_press, hold, single, double

• Button (2nd gen)

  • Model no.: WXKG11LM
  • Zigbee entity: sensor_switch.aq2, remote.b1acn01
  • States: on (through long_click_press), off
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single, double, long_click_press, hold

• Button (2nd gen, model b)

  • Model no.: WXKG12LM
  • Zigbee entity: sensor_switch.aq3
  • States: off (always)
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single, double, long_click_press, shake

• Aqara Wireless Switch (Single)

  • Model no.: WXKG03LM
  • Zigbee entity: 86sw1
  • States: off (always)
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single

• Aqara Wireless Switch (Double)

  • Model no.: WXKG02LM
  • Zigbee entity: 86sw2
  • States: off (always)
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single, both

• Aqara Wireless Switch (Single) (2nd gen)

  • Model no.: WXKG03LM
  • Zigbee entity: remote.b186acn01
  • States: off (always)
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single, double, long

• Aqara Wireless Switch (Double) (2nd gen)

  • Model no.: WXKG02LM
  • Zigbee entity: remote.b286acn01
  • States: off (always)
  • Event: xiaomi_aqara.click
  • Event key: click_type
  • Event values: single, double, long, both, double_both, long_both

• Cube

  • Model no.: MFKZQ01LM
  • Zigbee entity: cube
  • States: off (always)
  • Event: xiaomi_aqara.cube_action
  • Event key: action_type, action_value (rotate)
  • Event values: flip90, flip180, move, tap_twice, shake_air, swing, alert, free_fall, rotate (degrees at action_value)

• Vibration Sensor

  • Model no.: DJT11LM
  • Zigbee entity: vibration
  • States: off (always)
  • Event: xiaomi_aqara.movement
  • Event key: movement_type
  • Event values: vibrate, tilt, free_fall

Automation examples for binary sensors

Motion

- alias: "Ifthereismotionandit'sdarkturnonthegatewaylight"
 triggers:
 - trigger: state
 entity_id: binary_sensor.motion_sensor_158d000xxxxxc2
 from: "off"
 to: "on"
 conditions:
 - condition: numeric_state
 entity_id: sensor.illumination_34ce00xxxx11
 below: 300
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_34ce00xxxx11
 data:
 brightness: 5
 - action: automation.turn_on
 target:
 entity_id: automation.MOTION_OFF
- alias: "Iftherenomotionfor5minutesturnoffthegatewaylight"
 triggers:
 - trigger: state
 entity_id: binary_sensor.motion_sensor_158d000xxxxxc2
 from: "on"
 to: "off"
 for:
 minutes: 5
 actions:
 - action: light.turn_off
 target:
 entity_id: light.gateway_light_34ce00xxxx11
 - action: automation.turn_off
 target:
 entity_id: automation.Motion_off

Door and/or indow binary sensors

- alias: "Ifthewindowisopenturnofftheradiator"
 triggers:
 - trigger: state
 entity_id: binary_sensor.door_window_sensor_158d000xxxxxc2
 from: "off"
 to: "on"
 actions:
 - action: climate.set_operation_mode
 target:
 entity_id: climate.livingroom
 data:
 operation_mode: "Off"
- alias: "Ifthewindowisclosedfor5minutesturnontheradiatoragain"
 triggers:
 - trigger: state
 entity_id: binary_sensor.door_window_sensor_158d000xxxxxc2
 from: "on"
 to: "off"
 for:
 minutes: 5
 actions:
 - action: climate.set_operation_mode
 target:
 entity_id: climate.livingroom
 data:
 operation_mode: "Smartschedule"
- alias: "Notifyifdoorisopenedwhenaway"
 triggers:
 - trigger: state
 entity_id: binary_sensor.door_window_sensor_15xxxxxxc9xx6b
 from: "off"
 to: "on"
 conditions:
 - condition: state
 entity_id: group.family
 state: "not_home"
 actions:
 - action: notify.notify_person
 data:
 message: "Thedoorhasbeenopened"

Smoke

- alias: "Sendnotificationonfirealarm"
 triggers:
 - trigger: state
 entity_id: binary_sensor.smoke_sensor_158d0001574899
 from: "off"
 to: "on"
 actions:
 - action: notify.html5
 data:
 title: "Firealarm!"
 message: "Fire/Smokedetected!"
 - action: xiaomi_aqara.play_ringtone
 data:
 gw_mac: xxxxxxxxxxxx
 ringtone_id: 2
 ringtone_vol: 100

Gas

- alias: "Sendnotificationongasalarm"
 triggers:
 - trigger: state
 entity_id: binary_sensor.natgas_sensor_158dxxxxxxxxxx
 from: "off"
 to: "on"
 actions:
 - action: notify.html5
 data:
 title: "Gasalarm!"
 message: "Gaswithadensityof{{state_attr('binary_sensor.natgas_sensor_158dxxxxxxxxxx','density')}}detected."

Xiaomi Wireless Button

There are 3 versions of the Xiaomi Wireless button:

• For the round shaped button, the available events are single, double, hold, long_click_press and long_click_release.
• Aqara branded buttons are square shaped. Model WXKG11LM only supports single, double, long_click_pressand hold events. WXKG12LM supports single, double, long_click_press and shake events.

For the Aqara versions, the delay between two clicks to generate a double-click must be larger than with the round button. Clicking too quickly generates a single-click event.

- alias: "Toggledininglightonsinglepress"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: single
 actions:
 - action: switch.toggle
 target:
 entity_id: switch.wall_switch_left_158d000xxxxx01
- alias: "Togglecouchlightondoubleclick"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: double
 actions:
 - action: switch.toggle
 target:
 entity_id: switch.wall_switch_right_158d000xxxxx01
- alias: "Letadogbarkonlongpress"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: long_click_press
 actions:
 - action: xiaomi_aqara.play_ringtone
 data:
 gw_mac: xxxxxxxxxxxx
 ringtone_id: 8
 ringtone_vol: 8

Xiaomi Cube

Available events are flip90, flip180, move, tap_twice, shake_air, swing, alert, free_fall and rotate. The integration stores the last action as the attribute last_action.

- alias: "Cubeeventflip90"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.cube_action
 event_data:
 entity_id: binary_sensor.cube_15xxxxxxxxxxxx
 action_type: flip90
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_28xxxxxxxxxx
 data:
 color_name: "springgreen"
- alias: "Cubeeventflip180"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.cube_action
 event_data:
 entity_id: binary_sensor.cube_15xxxxxxxxxxxx
 action_type: flip180
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_28xxxxxxxxxx
 data:
 color_name: "darkviolet"
- alias: "Cubeeventmove"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.cube_action
 event_data:
 entity_id: binary_sensor.cube_15xxxxxxxxxxxx
 action_type: move
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_28xxxxxxxxxx
 data:
 color_name: "gold"
- alias: "Cubeeventtap_twice"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.cube_action
 event_data:
 entity_id: binary_sensor.cube_15xxxxxxxxxxxx
 action_type: tap_twice
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_28xxxxxxxxxx
 data:
 color_name: "deepskyblue"
- alias: "Cubeeventshake_air"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.cube_action
 event_data:
 entity_id: binary_sensor.cube_15xxxxxxxxxxxx
 action_type: shake_air
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_28xxxxxxxxxx
 data:
 color_name: "blue"

Aqara Wireless Switch

The Aqara Wireless Switch is available as single-key and double-key version. Each key behaves like the Wireless Button limited to the click event single. The double key version adds a third device called binary_sensor.wall_switch_both_158xxxxxxxxx12 which reports a click event called both if both keys are pressed.

- alias: "Decreasebrightnessofthegatewaylight"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.wall_switch_left_158xxxxxxxxx12
 click_type: single
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_34xxxxxxxx13
 data:
 brightness: >-
 {% if state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') %}
 {% if state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') - 60 >= 10 %}
 {{state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') - 60}}
 {% else %}
 {{state_attr('light.gateway_light_34xxxxxxxx13', 'brightness')}}
 {% endif %}
 {% else %}
 10
 {% endif %}

- alias: "Increasebrightnessofthegatewaylight"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.wall_switch_right_158xxxxxxxxx12
 click_type: single
 actions:
 - action: light.turn_on
 target:
 entity_id: light.gateway_light_34xxxxxxxx13
 data:
 brightness: >-
 {% if state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') %}
 {% if state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') + 60 <= 255 %}
 {{state_attr('light.gateway_light_34xxxxxxxx13', 'brightness') + 60}}
 {% else %}
 {{state_attr('light.gateway_light_34xxxxxxxx13', 'brightness')}}
 {% endif %}
 {% else %}
 10
 {% endif %}

- alias: "Turnoffthegatewaylight"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.wall_switch_both_158xxxxxxxxx12
 click_type: both
 actions:
 - action: light.turn_off
 target:
 entity_id: light.gateway_light_34xxxxxxxx13

Vibration sensor

This automation toggles the living room lamp on vibration/tilt.

- alias: "TurnonLivingRoomLamponvibration"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.movement
 event_data:
 entity_id: binary_sensor.vibration_xxxx000000
 movement_type: vibrate
 actions:
 - action: light.toggle
 target:
 entity_id: light.living_room_lamp
- alias: "TurnonLivingRoomLampontilt"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.movement
 event_data:
 entity_id: binary_sensor.vibration_xxxx000000
 movement_type: tilt
 actions:
 - action: light.toggle
 target:
 entity_id: light.living_room_lamp

Sensors

The sensor entity allows you to read data from your Xiaomi sensors.

The following sensor types are supported:

• Battery level (in percentage)
• Bed activity / vibration (in micrometers)
• Coordination
• Humidity (in percentage)
• Illumination (in lux)
• Power consumed (in kWh)
• Power load (in Watt)
• Pressure (in hPa)
• Temperature (depends on UI settings, Celsius or Fahrenheit)
• Tilt angle

Switches

The switch entity allows you to get data from your Xiaomi aqara switches and to switch between states.

List of actions

The Xiaomi Gateway (Aqara) integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Add device (xiaomi_aqara.add_device) Enables pairing mode on a Xiaomi Aqara Gateway to add a new device.

• Play ringtone (xiaomi_aqara.play_ringtone) Plays a specific ringtone on a Xiaomi Aqara Gateway.

• Remove device (xiaomi_aqara.remove_device) Removes a specific device from a Xiaomi Aqara Gateway.

• Stop ringtone (xiaomi_aqara.stop_ringtone) Stops a playing ringtone on a Xiaomi Aqara Gateway.

For an overview of every action across all integrations, see the actions reference.

Examples

Long press on smart button 1st generation

This example plays the sound of a dog barking when the button is held down and stops the sound when the button is pressed once. Only works for the round button of the 1st generation.

Note: The sound will stop playing automatically when it has ended.

- alias: "Letadogbarkonlongpress"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: long_click_press
 actions:
 - action: xiaomi_aqara.play_ringtone
 data:
 gw_mac: xxxxxxxxxxxx
 ringtone_id: 8
 ringtone_vol: 8

- alias: "Stopbarkingimmediatelyonsingleclick"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: single
 actions:
 - action: xiaomi_aqara.stop_ringtone
 data:
 gw_mac: xxxxxxxxxxxx

Double click on smart button

This example toggles the living room lamp on a double click of the button.

- alias: "DoubleClicktotogglelivingroomlamp"
 triggers:
 - trigger: event
 event_type: xiaomi_aqara.click
 event_data:
 entity_id: binary_sensor.switch_158d000xxxxxc2
 click_type: double
 actions:
 - action: light.toggle
 target:
 entity_id: light.living_room_lamp

Troubleshooting

Initial setup problem

If you run into trouble initializing the gateway with your app, try another smartphone. E.g., it didn’t work on an OnePlus 3, but it worked with a Nexus 5.

Connection problem

2017-08-20 16:51:19 ERROR (SyncWorker_0) [homeassistant.components.xiaomi] No gateway discovered
2017-08-20 16:51:20 ERROR (MainThread) [homeassistant.setup] Setup failed for xiaomi: Component failed to initialize.

That means that Home Assistant is not getting any response from your Xiaomi gateway. Might be a local network problem or your firewall.

• Make sure you have enabled LAN access.
• Turn off the firewall on the system where Home Assistant is running.
• Ensure your router supports multicast as this is a requirement of the Xiaomi Gateway.
• Try to disable and then enable LAN access.
• Hard reset the gateway: Press the button of the gateway 30 seconds and start again from scratch.
• If you are using Home Assistant in Docker, make sure to use --net=host.
• If you receive an {"error":"Invalid key"} in your log while trying to control the gateway light
  • You should generate the key again using an Android Phone or alternatively an emulator such as bluestacks. In some instances, there is an issue with keys being generated using the iOS application.
  • You need to make sure to have multicast support on your network. If you are running Home Assistant in a virtual machine (like Proxmox), try echo 0 >/sys/class/net/vmbr0/bridge/multicast_snooping on the host and restart the service or reboot the host.

If your gateway’s MAC address starts with 04:CF:8C or 7C:49:EB, there is a good chance that the required port 9898 is closed on your gateway and thus, this method doesn’t work. There are workarounds available online, however this requires soldering and working with electricity.