Add Xiaomi docs for platforms (#3045)

* Add Xiaomi docs for platforms

* Add service details

* Add Aqara Wireless Switch

* Escape templates

* Update 'ha_iot_class'
This commit is contained in:
Fabian Affolter 2017-07-23 20:21:10 +02:00 committed by GitHub
parent c753de1f4e
commit ebd6648b0b
6 changed files with 408 additions and 226 deletions

View File

@ -1,20 +1,25 @@
--- ---
layout: page layout: page
title: "Xiaomi Binary sensors” title: "Xiaomi Binary Sensor"
description: "Instructions how to integrate your Xiaomi Binary sensors within Home Assistant." description: "Instructions how to setup the Xiaomi binary sensors within Home Assistant."
date: 2017-07-21 16:34 date: 2017-07-21 16:34
sidebar: true sidebar: true
comments: false comments: false
sharing: true sharing: true
footer: true footer: true
logo: xiaomi.png logo: xiaomi.png
ha_category: Binary sensor ha_category: Binary Sensor
ha_release: "0.50" ha_release: "0.50"
ha_iot_class: "Local Polling"
--- ---
To get your Xiaomi binary sensors working with Home Assistant, follow the instructions for the general [Xiaomi Gateway component](/components/xiaomi/)
### Type of sensors supported: The `xiaomi` binary sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) binary sensors.
The requirement is that you have setup the [`xiaomi` component](/components/xiaomi/).
### {% linkable_title Type of sensors supported %}
- Motion - Motion
- Door / Window - Door / Window
- Smoke - Smoke
@ -22,11 +27,11 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
- Xiaomi Wireless Button - Xiaomi Wireless Button
- Xiaomi Cube - Xiaomi Cube
### Some automation examples to get you started: ### {% linkable_title Automation examples %}
- Motion
```yaml
# Trigger for motion sensor
#### {% linkable_title Motion %}
```yaml
- alias: If there is motion and its dark turn on the gateway light - alias: If there is motion and its dark turn on the gateway light
trigger: trigger:
platform: state platform: state
@ -42,7 +47,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_34ce00xxxx11 entity_id: light.gateway_light_34ce00xxxx11
data: data:
brightness: 5 brightness: 5
- alias: If there no motion for 5 minutes turn off the gateway light - alias: If there no motion for 5 minutes turn off the gateway light
trigger: trigger:
platform: state platform: state
@ -56,10 +60,9 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_34ce00xxxx11 entity_id: light.gateway_light_34ce00xxxx11
``` ```
- Door / Window #### {% linkable_title Door and/or Window %}
```yaml
# Trigger for door window sensor
```yaml
- alias: If the window is open turn off the radiator - alias: If the window is open turn off the radiator
trigger: trigger:
platform: state platform: state
@ -71,7 +74,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: climate.livingroom entity_id: climate.livingroom
data: data:
operation_mode: 'Off' operation_mode: 'Off'
- alias: If the window is closed for 5 minutes turn on the radiator again - alias: If the window is closed for 5 minutes turn on the radiator again
trigger: trigger:
platform: state platform: state
@ -86,10 +88,10 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
data: data:
operation_mode: 'Smart schedule' operation_mode: 'Smart schedule'
``` ```
- Smoke
```yaml
# Trigger for smoke sensor
#### {% linkable_title Smoke %}
```yaml
- alias: Send notification on fire alarm - alias: Send notification on fire alarm
trigger: trigger:
platform: state platform: state
@ -107,10 +109,10 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
ringtone_id: 2 ringtone_id: 2
ringtone_vol: 100 ringtone_vol: 100
``` ```
- Gas
```yaml
# Trigger for natgas detected
#### {% linkable_title Gas %}
```yaml
- alias: Send notification on gas alarm - alias: Send notification on gas alarm
trigger: trigger:
platform: state platform: state
@ -121,12 +123,14 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
- service: notify.html5 - service: notify.html5
data_template: data_template:
title: Gas alarm! title: Gas alarm!
message: 'Gas with a density of {{ states.binary_sensor.natgas_sensor_158dxxxxxxxxxx.attributes.density }} detected.' message: 'Gas with a density of {% raw %}{{ states.binary_sensor.natgas_sensor_158dxxxxxxxxxx.attributes.density }}{% endraw %} detected.'
``` ```
- Xiaomi Wireless Button (available events are `single`, `double`, `hold`, `long_click_press` and `long_click_release`). For Square version (Aqara brand) only `single` and `double` events are supported. Furthermore the space between two clicks to generate a double click must be quite large now
```yaml
# Trigger for the wireless button with different click types
#### {% linkable_title Xiaomi Wireless Button %}
Available events are `single`, `double`, `hold`, `long_click_press` and `long_click_release`. For Square version (Aqara brand) only `single` and `double` events are supported. Furthermore the space between two clicks to generate a double click must be quite large now.
```yaml
- alias: Toggle dining light on single press - alias: Toggle dining light on single press
trigger: trigger:
platform: event platform: event
@ -137,7 +141,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
action: action:
service: switch.toggle service: switch.toggle
entity_id: switch.wall_switch_left_158d000xxxxx01 entity_id: switch.wall_switch_left_158d000xxxxx01
- alias: Toggle couch light on double click - alias: Toggle couch light on double click
trigger: trigger:
platform: event platform: event
@ -148,7 +151,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
action: action:
service: switch.toggle service: switch.toggle
entity_id: switch.wall_switch_right_158d000xxxxx01 entity_id: switch.wall_switch_right_158d000xxxxx01
- alias: Let a dog bark on long press - alias: Let a dog bark on long press
trigger: trigger:
platform: event platform: event
@ -164,10 +166,11 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
ringtone_vol: 8 ringtone_vol: 8
``` ```
- Xiaomi Cube (available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`). #### {% linkable_title Xiaomi Cube %}
```yaml
# Trigger for a few cube events
Available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`.
```yaml
- alias: Cube event flip90 - alias: Cube event flip90
trigger: trigger:
platform: event platform: event
@ -180,7 +183,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_28xxxxxxxxxx entity_id: light.gateway_light_28xxxxxxxxxx
data: data:
color_name: "springgreen" color_name: "springgreen"
- alias: Cube event flip180 - alias: Cube event flip180
trigger: trigger:
platform: event platform: event
@ -193,7 +195,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_28xxxxxxxxxx entity_id: light.gateway_light_28xxxxxxxxxx
data: data:
color_name: "darkviolet" color_name: "darkviolet"
- alias: Cube event move - alias: Cube event move
trigger: trigger:
platform: event platform: event
@ -206,7 +207,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_28xxxxxxxxxx entity_id: light.gateway_light_28xxxxxxxxxx
data: data:
color_name: "gold" color_name: "gold"
- alias: Cube event tap_twice - alias: Cube event tap_twice
trigger: trigger:
platform: event platform: event
@ -219,7 +219,6 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
entity_id: light.gateway_light_28xxxxxxxxxx entity_id: light.gateway_light_28xxxxxxxxxx
data: data:
color_name: "deepskyblue" color_name: "deepskyblue"
- alias: Cube event shake_air - alias: Cube event shake_air
trigger: trigger:
platform: event platform: event
@ -233,3 +232,63 @@ To get your Xiaomi binary sensors working with Home Assistant, follow the instru
data: data:
color_name: "blue" color_name: "blue"
``` ```
#### #### {% linkable_title 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.
```yaml
- alias: Decrease brightness of the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_left_158xxxxxxxxx12
click_type: single
action:
service: light.turn_on
entity_id: light.gateway_light_34xxxxxxxx13
data_template:
brightness: {% raw %}>-
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60 >= 10 %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60}}
{% else %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
{% endif %}
{% else %}
10
{% endif %}{% endraw %}
- alias: Increase brightness of the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_right_158xxxxxxxxx12
click_type: single
action:
service: light.turn_on
entity_id: light.gateway_light_34xxxxxxxx13
data_template:
brightness: {% raw %}>-
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60 <= 255 %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60}}
{% else %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
{% endif %}
{% else %}
10
{% endif %}{% endraw %}
- alias: Turn off the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_both_158xxxxxxxxx12
click_type: both
action:
service: light.turn_off
entity_id: light.gateway_light_34xxxxxxxx13
```

View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Cover"
description: "Instructions how to setup the Xiaomi cover within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Cover
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` cover platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) covers.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Light"
description: "Instructions how to setup the Xiaomi light within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Light
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` light platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) lights.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Sensor"
description: "Instructions how to setup the Xiaomi sensor within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Sensor
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) sensors.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Switch"
description: "Instructions how to setup the Xiaomi switch within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Switch
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` switch platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) switches.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

View File

@ -9,10 +9,11 @@ sharing: true
footer: true footer: true
logo: xiaomi.png logo: xiaomi.png
ha_category: Hub ha_category: Hub
ha_release: 0.50 ha_release: "0.50"
ha_iot_class: "Local Polling"
--- ---
The `xiaomi_gw` platform allows you to integrate the following devices into HA The `xiaomi_gw` platform allows you to integrate the following [Xiaomi](http://www.mi.com/en/) devices into Home Assistant.
- Temperature and Humidity Sensor (old and new version) - Temperature and Humidity Sensor (old and new version)
- Motion Sensor (old and new version) - Motion Sensor (old and new version)
@ -44,22 +45,24 @@ What's not available?
- Decoupled mode of the Aqara Wall Switches (Single & Double) - 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 - 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 Getting started %}
Follow the setup process using your phone and Mi Home app. From here you will be able to retrieve the key from within the app following [this tutorial](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832) Follow the setup process using your phone and Mi Home app. From here you will be able to retrieve the key from within the app following [this tutorial](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832)
{% linkable_title Configuration %} To enable Xioami gateway in your installation, add the following to your `configuration.yaml` file:
One Gateway One Gateway
```yaml ```yaml
# You can leave mac empty if you only have one gateway # You can leave mac empty if you only have one gateway.
xiaomi: xiaomi:
gateways: gateways:
- mac: - mac:
key: xxxxxxxxxxxxxxxx key: xxxxxxxxxxxxxxxx
``` ```
Multiple Gateway Multiple Gateway
```yaml ```yaml
# 12 characters mac can be obtained from the gateway. # 12 characters mac can be obtained from the gateway.
xiaomi: xiaomi:
@ -71,7 +74,47 @@ One Gateway
``` ```
Configuration variables: Configuration variables:
- **mac** (*Optional*): The MAC of your gateway. Required if you have more than one. - **mac** (*Optional*): The MAC of your gateway. Required if you have more than one.
- **key** (*Optional*): The key of your gateway. Required if you also want to control lights and switches; sensors and binary sensors will still work. - **key** (*Optional*): The key of your gateway. Required if you also want to control lights and switches; sensors and binary sensors will still work.
- **discovery_retry** (*Optional*): Amount of times Home Assitant should try to reconnect to the Xiaomi Gateway. Default is 3. - **discovery_retry** (*Optional*): Amount of times Home Assitant should try to reconnect to the Xiaomi Gateway. Default is 3.
- **interface** (*Optional*): Which network interface to use. Default to any. - **interface** (*Optional*): Which network interface to use. Default to any.
## {% linkable_title Services %}
The gateway provides two services: `xiaomi.play_ringtone` and `xiaomi.stop_ringtone`. To play ringtones by Home Assistant the version of the gateway firmware must be `1.4.1_145` at least. A `ringtone_id` and `gw_mac` must be supplied. The parameter `ringtone_vol` (percent) is optional. Allowed values of the `ringtone_id` are:
- alarm ringtones [0-8]
- doorbell ring [10-13]
- alarm clock [20-29]
- custom ringtones (uploaded by mi home app) starting from 10001
Automation example
```yaml
- 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.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.stop_ringtone
data:
gw_mac: xxxxxxxxxxxx
```