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

There are two versions of the hub: v1 and v2.

v1 can be used with Home Assistant without any problems.

v2 might be less straightforward when it comes to enabling the local API. It might even require you to open up your device to do so. Xiaomi has suggested this is in the pipeline. If you have a Hub 2 and are experiencing issues, check out the troubleshooting section.

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.

Configuration Variables Looking for your configuration file?

Covers

The cover entity allows you to control connected Aquara 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 setup 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

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

Motion

- alias: "If there is motion and it's dark turn on the gateway light"
  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: "If there no motion for 5 minutes turn off the gateway light"
  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: "If the window is open turn off the radiator"
  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: "If the window is closed for 5 minutes turn on the radiator again"
  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: "Smart schedule"
- alias: "Notify if door is opened when away"
  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: "The door has been opened"
Smoke 
- alias: "Send notification on fire alarm"
  triggers:
    - trigger: state
      entity_id: binary_sensor.smoke_sensor_158d0001574899
      from: "off"
      to: "on"
  actions:
    - action: notify.html5
      data:
        title: "Fire alarm!"
        message: "Fire/Smoke detected!"
    - action: xiaomi_aqara.play_ringtone
      data:
        gw_mac: xxxxxxxxxxxx
        ringtone_id: 2
        ringtone_vol: 100
- alias: "Send notification on gas alarm"
  triggers:
    - trigger: state
      entity_id: binary_sensor.natgas_sensor_158dxxxxxxxxxx
      from: "off"
      to: "on"
  actions:
    - action: notify.html5
      data:
        title: "Gas alarm!"
        message: "Gas with a density of {{ 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: "Toggle dining light on single press"
  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: "Toggle couch light on double click"
  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: "Let a dog bark on long press"
  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: "Cube event flip90"
  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: "Cube event flip180"
  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: "Cube event move"
  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: "Cube event tap_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: "Cube event shake_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: "Decrease brightness of the gateway light"
  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 %}
          {% endif %}
- alias: "Increase brightness of the gateway light"
  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 %}
          {% endif %}
- alias: "Turn off the gateway light"
  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: "Turn on Living Room Lamp on vibration"
  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: "Turn on Living Room Lamp on tilt"
  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.
Actions 
The gateway provides the following actions:
Action xiaomi_aqara.play_ringtone 
Play a specific ringtone. The version of the gateway firmware must be 1.4.1_145 at least. Take a look at the examples below.
Data attribute
Optional
Description
Custom ringtones (uploaded by the Mi Home app) starting from 10001
Action xiaomi_aqara.stop_ringtone 
Stops a playing ringtone immediately.
Data attribute
Optional
Description
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: "Let a dog bark on long press"
  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: "Stop barking immediately on single click"
  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: "Double Click to toggle living room lamp"
  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.
  Help us improve our documentation
  Suggest an edit to this page, or provide/view feedback for this page.
    
 Provide feedback
    
 View pending feedback
  
The Xiaomi Gateway (Aqara)  integration  was introduced in Home Assistant 0.57, and it's used by 
          2606 active installations.
            We are incredibly grateful to the following contributors who currently maintain this integration:

          
 @danielhiversen
 @syssi

Action xiaomi_aqara.play_ringtone
Action xiaomi_aqara.stop_ringtone
Action xiaomi_aqara.add_device
Action xiaomi_aqara.remove_device
Examples
Long press on smart button 1st generation
Double click on smart button
Troubleshooting
Initial setup problem
Connection problem
              For partnership inquiries please check out Works With Home Assistant. For media, get in touch here. For other questions, you can contact us here (No technical support!)
              Website powered by Jekyll

              Originally based on the Oscailte theme