home-assistant.io/source/_components/xiaomi_aqara.markdown

layout, title, description, date, sidebar, comments, sharing, footer, logo, ha_category, ha_release, ha_iot_class, redirect_from

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_release	ha_iot_class	redirect_from
page	Xiaomi Gateway (Aqara)	Instructions for how to integrate the Xiaomi Gateway (Aqara) within Home Assistant.	2017-07-21 16:34	true	false	true	true	xiaomi.png	Hub	0.57	Local Push	/components/xiaomi/

The xiaomi_aqara component allows you to integrate Xiaomi Aqara-compatible devices into Home Assistant.

{% linkable_title Supported Devices %}

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

{% linkable_title Unsupported Devices %}

• 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

{% linkable_title 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 {{ page.title }} in your installation, add the following to your configuration.yaml file:

{% linkable_title One Gateway %}

# You can leave MAC empty if you only have one gateway.
xiaomi_aqara:
  discovery_retry: 5
  gateways:
    - key: xxxxxxxxxxxxxxxx

{% linkable_title Multiple Gateways %}

# 12 characters MAC can be obtained from the gateway.
xiaomi_aqara:
  gateways:
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx

{% linkable_title Search for gateways on specific interface %}

# 12 characters MAC can be obtained from the gateway.
xiaomi_aqara:
  interface: '192.168.0.1'
  gateways:
    - mac: xxxxxxxxxxxx
      key: xxxxxxxxxxxxxxxx

{% configuration %} gateways: description: A list of gateways to set up. required: true type: map keys: mac: description: The MAC address of your gateway. Optional if only using one gateway. required: false type: string key: description: The key of your gateway. Optional if only using sensors and/or binary sensors. required: false type: string host: description: The host/IP address of the gateway. If this parameter is used the multicast discovery of the gateway is skipped. required: false type: string disable: description: Disable the gateway. This is only useful if you don't want to integrate a specific gateway. required: false type: boolean default: false discovery_retry: description: Number of times that Home Assistant should try to reconnect to the gateway. required: false type: int default: 3 interface: description: Which network interface to use. required: false type: string default: any {% endconfiguration %}

{% linkable_title Services %}

The gateway provides the following services:

{% linkable_title Service 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.

Service data attribute	Optional	Description
gw_mac	no	MAC address of the Xiaomi Aqara Gateway
ringtone_id	no	One of the allowed ringtone ids
ringtone_vol	yes	The volume in percent

Allowed values of the ringtone_id are:

• Alarms
  • 0 - Police car 1
  • 1 - Police car 2
  • 2 - Accident
  • 3 - Countdown
  • 4 - Ghost
  • 5 - Sniper rifle
  • 6 - Battle
  • 7 - Air raid
  • 8 - Bark
• Doorbells
  • 10 - Doorbell
  • 11 - Knock at a door
  • 12 - Amuse
  • 13 - Alarm clock
• Alarm clock
  • 20 - MiMix
  • 21 - Enthusiastic
  • 22 - GuitarClassic
  • 23 - IceWorldPiano
  • 24 - LeisureTime
  • 25 - ChildHood
  • 26 - MorningStreamLiet
  • 27 - MusicBox
  • 28 - Orange
  • 29 - Thinker
• Custom ringtones (uploaded by the Mi Home app) starting from 10001

{% linkable_title Service xiaomi_aqara.stop_ringtone %}

Stops a playing ringtone immediately.

Service data attribute	Optional	Description
gw_mac	no	MAC address of the Xiaomi Aqara Gateway

{% linkable_title Service xiaomi_aqara.add_device %}

Enables the join permission of the Xiaomi Aqara Gateway for 30 seconds. A new device can be added afterwards by pressing the pairing button once.

Service data attribute	Optional	Description
gw_mac	no	MAC address of the Xiaomi Aqara Gateway

{% linkable_title Service xiaomi_aqara.remove_device %}

Removes a specific device. The removal is required if a device shall be paired with another gateway.

Service data attribute	Optional	Description
gw_mac	no	MAC address of the Xiaomi Aqara Gateway
device_id	no	Hardware address of the device to remove

{% linkable_title Examples %}

{% linkable_title 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
  trigger:
    platform: event
    event_type: click
    event_data:
      entity_id: binary_sensor.switch_158d000xxxxxc2
      click_type: long_click_press
  action:
    service: xiaomi_aqara.play_ringtone
    data:
      gw_mac: xxxxxxxxxxxx
      ringtone_id: 8
      ringtone_vol: 8

- alias: Stop barking immediately on single click
  trigger:
    platform: event
    event_type: click
    event_data:
      entity_id: binary_sensor.switch_158d000xxxxxc2
      click_type: single
  action:
    service: xiaomi_aqara.stop_ringtone
    data:
      gw_mac: xxxxxxxxxxxx

{% linkable_title 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
  trigger:
    platform: event
    event_type: click
    event_data:
      entity_id: binary_sensor.switch_158d000xxxxxc2
      click_type: double
  action:
    service: light.toggle
    data:
      entity_id: light.living_room_lamp

{% linkable_title Troubleshooting %}

{% linkable_title 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.

{% linkable_title 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 leave the MAC address mac: blank.
• Try to set discovery_retry: 10.
• 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.
• If the required library "PyXiaomiGateway" cannot be installed you will need to install some missing system dependencies python3-dev, libssl-dev, libffi-dev manually (e.g., $ sudo apt-get install python3-dev libssl-dev libffi-dev).