jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge pull request #3694 from home-assistant/release-0-56

Browse source 
0.56
This commit is contained in:
Fabian Affolter 2017-10-22 00:55:58 +02:00 • committed by GitHub
commit 8791e6e89a
85 changed files with 3242 additions and 525 deletions
Download patch file Download diff file Expand all files Collapse all files

1
source/_components/abode.markdown
View file

@ -26,6 +26,7 @@ There is currently support for the following device types within Home Assistant:
- [Lock](/components/cover.abode/): Reports on `Door Locks` and can be used to lock and unlock the door.
- [Light](/components/light.abode/): Reports on `Dimmer` lights and can be used to dim, change color, or turn the light on and off.
- [Switch](/components/switch.abode/): Reports on `Power Switch` devices and can be used to turn the power switch on and off. Also reports on `Automations` set up in the Abode system and allows you to activate or deactivate them.
- [Sensor](/components/sensor.abode/): Reports on `Temperature`, `Humidity`, and `Light` sensors.
## {% linkable_title Configuration %}

31
source/_components/alarm_control_panel.arlo.markdown Normal file
View file

@ -0,0 +1,31 @@
---
layout: page
title: "Arlo Control Panel"
description: "Instructions how to setup the Netgear Arlo Base Stations as a control panel within Home Assistant."
date: 2017-10-05 17:45
sidebar: true
comments: false
sharing: true
footer: true
logo: arlo.png
ha_category: Alarm
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
The `arlo` control panel platform allows you to control your [Arlo](https://arlo.netgear.com/) base stations.
To get your [Arlo](https://arlo.netgear.com/) base stations working within Home Assistant, please follow the instructions for the general [Arlo component](/components/arlo).
Once you have enabled the [Arlo component](/components/arlo), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
alarm_control_panel:
- platform: arlo
```
Configuration variables:
- **home_mode_name**: (*Optional*): Arlo base station does not have a built-in home mode. You can map one of your custom modes to home assistant's home mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match exactly as you set it up in the Arlo app.

16
source/_components/alarm_control_panel.egardia.markdown
View file

@ -43,7 +43,7 @@ You can change this, however, using the following procedure. This is a more adva
1. Log in into your alarm system's control panel. You will need to access http://[IP of your control panel]. You know this already since you need it in the basic configuration from above. Log in to the control panel with your Egardia/Woonveilig username and password.
2. Once logged in, go to *System Settings*, *Report* and change the Server Address for your primary server to the IP or hostname of your Home Assistant machine. Also, update the port number 85 or to anything you like. The provided software that you will set up in the next steps runs on port 85 by default. **Make sure to change the settings of the primary server otherwise the messages will not come through. Note that this will limit (or fully stop) the number of alarm messages you will get through Egardia's / Woonveilig services.** Maybe, that is just what you want. Make sure to save your settings by selecting 'OK'.
3. On your Home Assistant machine run `$ sudo python3 egardiaserver.py`. Refer to the [python-egardia repository](https://github.com/jeroenterheerdt/python-egardia) for detailed documentation on parameters. This will receive status codes from your alarm control panel and display them. You will need the codes to include in your configuration.yaml. Make sure to change the status of your alarm to all states (disarm, arm, armhome) as well as trigger the alarm in all ways possible to get 100% coverage. **Before triggering the alarm it might be good to disable the siren temporarily (can be done in Panel Settings).**
3. On your Home Assistant machine run `$ sudo python3 egardiaserver.py`. Refer to the [python-egardia repository](https://github.com/jeroenterheerdt/python-egardia) for detailed documentation on parameters. This will receive status codes from your alarm control panel and display them. You will need the codes to include in your configuration.yaml. Make sure to change the status of your alarm to all states (disarm, arm, armhome) by all means possible (all users, remotes, web login, app) as well as trigger the alarm in all ways possible to get 100% coverage. **Before triggering the alarm it might be good to disable the siren temporarily (can be done in Panel Settings).**
4. Once you have the codes, update your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
@ -61,26 +61,30 @@ alarm_control_panel:
triggered: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX
ignore: XXXXXXXXXXXXXXXX
```
Note that for triggered, arm and disarm multiple codes can be entered since each sensor triggers with a different code and each user of the system has its own arm and disarm codes. Also note that your system will do regular system checks which will be reported as well. Since Home Assistant provides no way of handling them properly, you can enter those codes as ignore (again, multiple codes can be used here). The egardia component will ignore these codes and continue returning the old status if it receives any of the codes that are listed as ignore. This is useful for example when you have armed your alarm at night: normally a system check will occur at least once during the night and if that code is not specified anywhere Home Assistant will set the status of the alarm to its default, which is unarmed. This is in fact wrong. Listing the code as ignore changes this behavior and Home Assistant will continue to show the status the alarm is in (disarm, arm, armhome, triggered) even when system checks occur.
5. Start the `egardiaserver.py` script on boot of your Home Assistant machine, for example by using systemd. To use this method, create a shell script named `egardiaserver.sh` that contains the following:
Note that for triggered, arm and disarm multiple codes can be entered since each sensor triggers with a different code and each user of the system has its own arm and disarm codes. Also note that your system will do regular system checks which will be reported as well. Since Home Assistant provides no way of handling them properly, you can enter those codes as ignore (again, multiple codes can be used here). The egardia component will ignore these codes and continue returning the old status if it receives any of the codes that are listed as ignore. This is useful for example when you have armed your alarm at night: normally a system check will occur at least once during the night and if that code is not specified anywhere Home Assistant will set the status of the alarm to its default, which is unarmed. This is in fact wrong. Listing the code as ignore changes this behavior and Home Assistant will continue to show the status the alarm is in (disarm, arm, armhome, triggered) even when system checks occur.
5. Start the `egardiaserver.py` script on boot of your Home Assistant machine, for example by using `systemctl` by `systemd`. To use this method, create a shell script named `egardiaserver.sh` that contains something like the following:
```bash
source /srv/homeassistant/homeassistant_venv/bin/activate
python3 /srv/homeassistant/homeassistant_venv/lib/python3.4/site-packages/pythonegardia/egardiaserver.py -host [YOURHOST] -password '[YOURPASSWORD]' -ssl True > /tmp/egardiaserver.log 2>&1
$ source /srv/homeassistant/bin/activate
$ python3 /srv/homeassistant/lib/python3.5/site-packages/pythonegardia/egardiaserver.py -host [YOURHOST] -password '[YOURPASSWORD]' -ssl True > /tmp/egardiaserver.log 2>&1
```
Mark it as executable (`$ chmod +x`) and run `sudo nano /lib/systemd/system/egardiaserver.service`. Enter the following into the `egardiaserver.service` file:
```bash
[Unit]
Description=Egardia Server Service
[Service]
ExecStart=/srv/homeassistant/homeassistant_venv/lib/python3.4/site-packages/pythonegardia/egardiaserver.sh
ExecStart=/bin/bash /srv/homeassistant/homeassistant_venv/lib/python3.5/site-packages/pythonegardia/egardiaserver.sh
StandardOutput=journal+console
[Install]
WantedBy=multi-user.target
Alias=egardiaserver.service
```
Save and then run `sudo systemctl enable egardiaserver.service` and `sudo systemctl start egardiaserver.service`.
6. Test your setup and enjoy. The component will update if the alarm status changes, including triggers. You can use this to build your own automations and send notifications as you wish.

23
source/_components/alarm_control_panel.manual_mqtt.markdown
View file

@ -21,12 +21,14 @@ The component will accept the following commands from your Alarm Panel via the `
- `DISARM`
- `ARM_HOME`
- `ARM_AWAY`
- `ARM_NIGHT`
When the state of the manual alarm changes, Home Assistant will publish one of the following states to the `state_topic`:
- 'disarmed'
- 'armed_home'
- 'armed_away'
- 'armed_night'
- 'pending'
- 'triggered'
@ -47,6 +49,8 @@ All configuration variables from the base manual alarm platform are available:
- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds.
- **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds.
- **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state.
- **armed_home|armed_away|armed_night|triggered** (*Optional*): State specific settings
- **pending_time**: State specific pending time override.
Additionally, the following MQTT configuration variables are also available:
@ -56,6 +60,23 @@ Additionally, the following MQTT configuration variables are also available:
- **payload_disarm** (*Optional*): The payload to disarm this Alarm Panel. Default is "DISARM".
- **payload_arm_home** (*Optional*): The payload to set armed-home mode on this Alarm Panel. Default is "ARM_HOME".
- **payload_arm_away** (*Optional*): The payload to set armed-away mode on this Alarm Panel. Default is "ARM_AWAY".
- **payload_arm_night** (*Optional*): The payload to set armed-night mode on this Alarm Panel. Default is "ARM_NIGHT".
In the config example below, armed_home state will have no pending time and triggered state will have a pending time of 20 seconds whereas armed_away state will have a default pending time of 30 seconds.
```yaml
# Example configuration.yaml entry
alarm_control_panel:
- platform: manual_mqtt
state_topic: home/alarm
command_topic: home/alarm/set
pending_time: 30
armed_home:
pending_time: 0
triggered:
pending_time: 20
trigger_time: 4
```
## {% linkable_title Examples %}
@ -70,11 +91,13 @@ To change the state of the alarm, publish one of the following messages to the `
- `DISARM`
- `ARM_HOME`
- `ARM_AWAY`
- `ARM_NIGHT`
To receive state updates from HA, subscribe to the `state_topic`. Home Assistant will publish a new message whenever the state changes:
- `disarmed`
- `armed_home`
- `armed_away`
- `armed_night`
- `pending`
- `triggered`

2
source/_components/arlo.markdown
View file

@ -31,7 +31,7 @@ Configuration variables:
It is recommended to create a dedicated user on Arlo website to be used within Home Assistant and then share your Arlo cameras.
Finish its configuration by visiting the [Arlo sensor page](/components/sensor.arlo/) or [Arlo camera page](/components/camera.arlo/).
Finish its configuration by visiting the [Arlo sensor page](/components/sensor.arlo/) or [Arlo camera page](/components/camera.arlo/) or [Arlo control panel page](/components/alarm_control_panel.arlo/).
The Arlo component also provides a service to enable/disable the motion detection sensor. The example below enables the motion detection every time the Home Assistant service starts.

19
source/_components/binary_sensor.modbus.markdown
View file

@ -36,3 +36,22 @@ Configuration variables:
- **name** (*Required*): Name of the sensor.
- **slave** (*Required*): The number of the slave (Optional for TCP and UDP Modbus).
- **coil** (*Required*): Coil number.
It's possible to change the default 30 seconds scan interval for the sensor updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation.
### {% linkable_title Full example %}
Example a sensor with a 10 seconds scan interval:
```yaml
binary_sensor:
- platform: modbus
scan_interval: 10
coils:
- name: Sensor1
slave: 1
coil: 100
- name: Sensor2
slave: 1
coil: 110
```

6
source/_components/binary_sensor.netatmo.markdown
View file

@ -27,8 +27,7 @@ If you want to select a specific sensor, set discovery to False for [netatmo](/c
binary_sensor:
platform: netatmo
home: home_name
timeout: 15
offset: 90
timeout: 90
cameras:
- camera_name1
welcome_sensors:
@ -45,8 +44,7 @@ binary_sensor:
Configuration variables:
- **home** (*Optional*): Will use the cameras of this home only.
- **timeout** (*Optional*): The Welcome binary sensors will reflect the events from the last X minutes. (default: 15)
- **offset** (*Optional*): The Presence binary sensors will stay on for X seconds after detection. (default: 90)
- **timeout** (*Optional*): The Welcome/Presence binary sensors will stay on for X seconds after detection. (default: 90)
- **cameras** array (*Optional*): Cameras to use. Multiple entities allowed.
- 'camera_name': Name of the camera to display.
- **welcome_sensors** array (*Optional*): List of monitored conditions.

33
source/_components/binary_sensor.skybell.markdown Normal file
View file

@ -0,0 +1,33 @@
---
layout: page
title: "Skybell Binary Sensor"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Binary Sensor
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
To get your [Skybell.com](https://skybell.com/) binary sensors working within Home Assistant, please follow the instructions for the general [Skybell component](/components/skybell).
Once you have enabled the [Skybell component](/components/skybell), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: skybell
monitored_conditions:
- button
- motion
```
Configuration variables:
- **monitored_conditions** array (*Required*): Conditions to display in the frontend. The following conditions can be monitored.
- **button**: Return a boolean value when the doorbell button was pressed.
- **motion**: Return a boolean value when movement was detected by the Skybell doorbell.

2
source/_components/binary_sensor.xiaomi_aqara.markdown
View file

@ -183,7 +183,7 @@ Available events are `single`, `double`, `hold`, `long_click_press` and `long_cl
#### {% linkable_title Xiaomi Cube %}
Available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`.
Available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`. The component stores the last action as the attribute `last_action`.
```yaml
- alias: Cube event flip90

24
source/_components/camera.skybell.markdown Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: "Skybell Camera"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Camera
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
To get your [Skybell.com](https://skybell.com/) cameras working within Home Assistant, please follow the instructions for the general [Skybell component](/components/skybell).
Once you have enabled the [Skybell component](/components/skybell), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
camera:
- platform: skybell
```

96
source/_components/camera.yi.markdown Normal file
View file

@ -0,0 +1,96 @@
---
layout: page
title: "Yi Home Camera"
description: "Instructions on how to integrate a video feed (via FFmpeg) as a camera within Home Assistant."
date: 2017-10-10 13:00
sidebar: true
comments: false
sharing: true
footer: true
logo: yi.png
ha_category: Camera
ha_release: 0.56
ha_iot_class: "Local Polling"
---
The `yi` camera platform allows you to utilize Yi Home Cameras within Home
Assistant. Specifically, this platform supports the line of Yi Home Cameras
that are based on the Hi3518e Chipset; these include:
* Yi Home 17CN
* Yi 1080p Home
* Yi Dome
* Yi 1080p Dome
To successfully implement this platform, the Home Assistant host should be
capable of multiple simultaneous reads; for every concurrent Home Assistant
user, a connection will be made to the camera every 10 seconds.
This should normally not be a problem.
## {% linkable_title Preparing the Device %}
### {% linkable_title Installing Alternative Firmware %}
In order to integrate the camera with Home Assitant, it is necessary to install
a custom firmware on the device. Instructions for doing so can be found via the
[yi-hack-v3 GitHub project](https://github.com/shadow-1/yi-hack-v3).
Once installed, please ensure that you have enabled FTP and Telnet on your
device.
<p class='note warning'>
Some alternative Yi firmwares enable an experimental RTSP server, which will
allow you to connect to your camera via other Home Assistant camera platforms.
However, this RTSP server disables the ability to use the supremely-useful Yi
Home app. In order to maintain both Home Assistant compatibility _and_ the native
app, this platform retrieves videos via FTP.
</p>
### {% linkable_title Changing the FTP Password %}
Once the custom firmware is installed, a password must be added to the FTP
server. To do so:
1. Telnet into your camera: `telnet <IP ADDRESS>`.
2. Enter `root` as the username and `<blank>` as the password.
3. Type `passwd` and hit `<Enter>`.
4. Enter your new password twice.
5. Log out of Telnet.
## {% linkable_title Configuring the Platform %}
To enable the platform, add the following lines to your
`configuration.yaml` file:
```yaml
camera:
- platform: yi
host: '192.168.1.100'
password: my_password_123
```
Configuration variables:
- **host** (*Required*): the IP address or hostname of the camera
- **password** (*Required*): the password to the FTP server on the camera (from above)
- **username** (*Optional*): the user that can access the FTP server (default: `root`)
- **name** (*Optional*): a human-friendly name for the camera
- **ffmpeg_arguments** (*Optional*): extra options to pass to `ffmpeg` (e.g. image quality or video filter options)
## {% linkable_title Image quality %}
Any option supported by the `ffmpeg` client can be utilized via the
`ffmpeg_arguments` configuration parameter.
One particularly useful adjustment deals with video size. Since Yi videos are
fairly large (especially on the 1080p cameras), the following configuration will
bring them down to a manageable size:
```yaml
camera:
- platform: yi
name: My Camera
host: '192.168.1.100'
password: my_password_123
ffmpeg_arguments: '-vf scale=800:450'
```

18
source/_components/climate.toon.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Toon"
description: "Instructions how to integrate Toon Climate devices within Home Assistant."
date: 2017-10-21 12:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Climate
ha_release: 0.56
logo: toon.png
ha_iot_class: "Cloud Polling"
---
The `toon` climate platform allows you to interact with your Toon device.
The requirement is that you have setup the [`toon`](/components/toon/) component.

1
source/_components/cover.rflink.markdown
View file

@ -12,6 +12,7 @@ ha_category: Cover
ha_release: 0.55
---
The `rflink` cover platform supports devices that use [RFLink gateway firmware](http://www.nemcon.nl/blog2/), for example, the [Nodo RFLink Gateway](https://www.nodo-shop.nl/nl/21-rflink-gateway). RFLink gateway is an Arduino firmware that allows two-way communication with a multitude of RF wireless devices using cheap hardware (Arduino + transceiver).
First, you have to set up your [rflink hub](/components/rflink/).

2
source/_components/device_tracker.automatic.markdown
View file

@ -51,6 +51,8 @@ automation:
event_type: automatic_update
event_data:
type: "ignition:on"
vehicle:
id: "C_1234567890abcdefc"
action:
- service: light.turn_off
```

1
source/_components/device_tracker.unifi.markdown
View file

@ -33,5 +33,6 @@ Configuration variables:
- **password** (*Required*): The password for your given admin account.
- **site_id** (*Optional*): Allows you to specify a `site_id` for device tracking. Defaults to `default`. Found in the URL of the controller (i.e. https://CONTROLLER:PORT/manage/site/SITE_ID/dashboard).
- **verify_ssl** (*Optional*): Controls if the SSL certificate running on your Unifi webserver must be trusted by a known Certificate Authority on the server running Home Assistant. Defaults to 'True' but can also be a value that points to your custom cert "path/to/custom_cert.pem".
- **detection_time** (*Optional*): The Unifi component will not return a device that has not been seen by the controller in the last 180 seconds. You can adjust this threshold with this variable and accepts seconds or `00:00:00` time formats.
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.

102
source/_components/google_assistant.markdown Normal file
View file

@ -0,0 +1,102 @@
---
layout: page
title: "Google Assistant"
description: "Setup for Google Assistant integration"
date: 2017-10-17 12:30
sidebar: true
comments: false
sharing: true
footer: true
logo: google-assistant.png
ha_category: Voice
featured: true
ha_release: 0.56
---
# Google Assistant Docs
The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.
### {% linkable_title Configuration %}
```yaml
# Example configuration.yaml entry
google_assistant:
project_id: someproject-2d0b8
client_id: [long URL safe random string]
access_token: [a different long URL safe random string]
exposed_domains:
- switch
- light
- group
```
*Note:* It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance.
*Configuration Variables:*
* *expose_by_default* (Optional): Expose devices in all supported domains by default.
* *project_id* (Required): Project ID from the Google Developer console (looks like `words-2ab12`)
* *client_id* (Required): A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth.
* *access_token* (Required): Another different long random URL safe string.
* *exposed_domains* (Optional): An array of Home Assistant domains to expose to Google Assistant.
You can also customize your devices similar to other components by adding keys to entities:
```yaml
homeassistant:
customize:
master_bedroom_light:
google_assistant: true
google_assistant_name: bedroom light
bedroom_blinds:
aliases:
- bedroom shades
- bedroom covers
```
*Entity Customization Keys:*
* *google_assistant*: True exposes entity, false will hide it
* *google_assistant_name*: Can be used to override the primary name of an entity. By default the `friendly_name` of an entity is used.
* *aliases*: Provides "nicknames" to Google Assistant. These function as alternate names for an entity that Assistant will understand when spoken.
### {% linkable_title Setup %}
1. Install the [gactions CLI](https://developers.google.com/actions/tools/gactions-cli) (you'll use this later)
2. Create a new file named `project.json` and replace the `[YOUR HOME ASSISTANT URL]` below with the URL you use to access Home Assistant.
Note: This must be an HTTPS URL to work.
```json
{
"actions": [{
"name": "actions.devices",
"deviceControl": {
},
"fulfillment": {
"conversationName": "automation"
}
}],
"conversations": {
"automation" :
{
"name": "automation",
"url": "https://[YOUR HOME ASSISTANT URL]/api/google_assistant"
}
}
}
```
3. Create a new project in the [developer console](https://console.actions.google.com/).
1. Add/Import project
2. Go to Build under the Actions SDK box
3. Copy the command that looks like:
`gactions update --action_package PACKAGE_NAME --project doctest-2d0b8`
4. Replace `PACKAGE_NAME` with `project.json` and run that command from the same directory you saved `project.json` in. It should output a URL like `https://console.actions.google.com/project/doctest-2d0b8/overview` Go there.
5. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant.
6. The final item on that page `Account linking` is required for your app to interact with Home Assistant.
1. Grant type: `Implicit`
2. Client ID: Should be the same as `client_id` from your hass config above
3. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`
4. Configure your client. Add scopes for `email` and `name`
5. Testing instructions: doesn't matter since you won't submit this app
7. Back on the main app draft page. Click `Test Draft`. That will take you to the simulator (which won't work) so just close that window.
8. Open the Google Assistant app and go into `Settings > Home Control`
9. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead to you the screen where you can set rooms for your devices or nicknames for your devices.

15
source/_components/homematic.markdown
View file

@ -14,9 +14,10 @@ featured: false
---
The [Homematic](http://www.homematic.com/) component provides bi-directional communication with your CCU/Homegear. It uses a XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit.
The [Homematic](http://www.homematic.com/) component provides bi-directional communication with your CCU/Homegear. It uses a XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit.
If you are using Homegear with paired [Intertechno](http://intertechno.at/) devices, uni-directional communication is possible as well.
Device support is available for most of the wired and wireless devices, as well as a few IP devices. If you have a setup with mixed protocols, you have to configure additional hosts with the appropriate ports. The default is using port 2001, which are wireless devices. Wired devices usually are available through port 2000 and IP devices through port 2010.
Device support is available for most of the wired and wireless devices, as well as a few IP devices. If you have a setup with mixed protocols, you have to configure additional hosts with the appropriate ports. The default is using port 2001, which are wireless devices. Wired devices usually are available through port 2000 and IP devices through port 2010. The virtual thermostatgroups the CCU provides use port 9292 **and** require you to set the `path` setting to `/groups`.
If you want to see if a specific device you have is supported, head over to the [pyhomematic](https://github.com/danielperna84/pyhomematic/tree/master/pyhomematic/devicetypes) repository and browse through the source code. A dictionary with the device identifiers (e.g. HM-Sec-SC-2) can be found within the relevant modules near the bottom. If your device is not supported, feel free to contribute.
@ -41,7 +42,7 @@ Configuration variables (global):
Configuration variables (host):
- **ip** (*Required*): IP address of CCU/Homegear device.
- **port** (*Optional*): Port of CCU/Homegear XML-RPC Server. Default is 2001, use 2000 for wired and 2010 for IP.
- **port** (*Optional*): Port of CCU/Homegear XML-RPC Server. Wireless: 2001, wired: 2000, IP: 2010, thermostatgroups: 9292.
- **callback_ip** (*Optional*): Set this, if Home Assistant is reachable under a different IP from the CCU (NAT, Docker etc.).
- **callback_port** (*Optional*): Set this, if Home Assistant is reachable under a different port from the CCU (NAT, Docker etc.).
- **resolvenames** (*Optional*): [`metadata`, `json`, `xml`] Try to fetch device names. Defaults to `false` if not specified.
@ -49,6 +50,7 @@ Configuration variables (host):
- **password** (*Optional*): When fetching names via JSON-RPC, you need to specify the password of the user you have configured above.
- **primary** (*Optional*): Set to `true` when using multiple hosts and this host should provide the services and variables.
- **variables** (*Optional*): Set to `true` if you want to use CCU2/Homegear variables. Should only be enabled for the primary host. When using a CCU credentials are required.
- **path** (*Optional*): Set to `/groups` when using port 9292.
#### Example configuration with multiple protocols and some other options set:
@ -71,6 +73,13 @@ homematic:
ip:
ip: 127.0.0.1
port: 2010
groups:
ip: 127.0.0.1
port: 9292
resolvenames: json
username: Admin
password: secret
path: /groups
```
### {% linkable_title The `resolvenames` option %}

10
source/_components/knx.markdown
View file

@ -76,10 +76,10 @@ knx:
fire_event_filter: ["1/0/*", "6/2,3,4-6/*"]
```
* **fire_event** (Optional) if set to True, platform will write all received KNX messages to event bus
* **fire_event_filter** If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HASS event bus.
* **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus
* **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HASS event bus.
* **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behaviour.
Service
-------
@ -92,8 +92,8 @@ Service: send
Service Data: {"address": "1/0/15", "payload": 0}
```
* **address** : KNX group address
* **payload** : payload, either an integer or an array of integers
* **address**: KNX group address
* **payload**: Payload, either an integer or an array of integers

24
source/_components/light.skybell.markdown Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: "Skybell Light"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Light
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
To get your [Skybell.com](https://skybell.com/) LED light working within Home Assistant, please follow the instructions for the general [Skybell component](/components/skybell).
Once you have enabled the [Skybell component](/components/skybell), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: skybell
```

2
source/_components/lock.tesla.markdown
View file

@ -9,7 +9,7 @@ sharing: true
footer: true
logo: tesla.png
ha_category: Lock
ha_iot_class: "Coud Push"
ha_iot_class: "Cloud Push"
ha_release: 0.53
---

19
source/_components/map.markdown Executable file
View file

@ -0,0 +1,19 @@
---
layout: page
title: "Map"
description: "Offers a map to show tracked devices."
date: 2017-10-11 10:01
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: "Other"
---
This offers a map on the frontend to display the location of tracked devices. To set up tracked devices, look at the [device tracker](/components/device_tracker/) documentation.
```yaml
# Example configuration.yaml entry
map:
```

49
source/_components/media_player.monoprice.markdown Normal file
View file

@ -0,0 +1,49 @@
---
layout: page
title: "Monoprice 6-Zone Amplifier"
description: "Instructions on how to integrate Monoprice 6-Zone Home Audio Controller into Home Assistant."
date: 2017-10-02 11:45
sidebar: true
comments: false
sharing: true
footer: true
logo: monoprice.svg
ha_category: Media Player
ha_release: 0.56
ha_iot_class: "Local Polling"
---
The `monoprice` platform allows you to control [Monoprice 6-Zone Amplifier](https://www.monoprice.com/product?p_id=10761) using a serial connection.
To add a Monoprice device to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: monoprice
port: /dev/ttyUSB0
zones:
11:
name: Main Bedroom
12:
name: Living Room
13:
name: Kitchen
14:
name: Bathroom
15:
name: Dining Room
16:
name: Guest Bedroom
sources:
1:
name: Sonos
5:
name: Chromecast
```
Configuration variables:
- **port** (*Required*): The serial port to which Monoprice amplifier is connected
- **zones** (*Required*): This is the list of zones available. Valid zones are 11,12,13,14,15,16. In case multiple Monoprice devices are stacked together the list of valid zones is extended by 21,22,23,24,25,26 for the second device and 31,32,33,34,35,36 for the third device. Each zone must have a name assigned to it.
- **sources** (*Required*): The list of sources available. Valid source numbers are 1,2,3,4,5,6. Each source number corresponds to the input number on the Monoprice amplifier. Similar to zones, each source must have a name assigned to it.

2
source/_components/modbus.markdown
View file

@ -33,6 +33,7 @@ Configuration variables:
- **type** (*Required*): Type of the connection to Modbus.
- **host** (*Required*): The IP address of your Modbus device, eg. 192.168.1.1.
- **port** (*Required*): The port for the communication.
- **timeout** (*Optional*): Timeout for slave response in seconds. (default: 3)
For a serial connection:
@ -57,6 +58,7 @@ Configuration variables:
- **stopbits** (*Required*): The stopbits for the serial connection.
- **bytesize** (*Required*): The bytesize for the serial connection.
- **parity** (*Required*): The parity for the serial connection.
- **timeout** (*Optional*): Timeout for slave response in seconds. (default: 3)
### {% linkable_title Services %}

47
source/_components/namecheapdns.markdown Normal file
View file

@ -0,0 +1,47 @@
---
layout: page
title: "NamecheapDNS"
description: "Keep your namecheap dynamic DNS up to date"
date: 2017-10-11 20:16
sidebar: true
comments: false
sharing: true
footer: true
logo: namecheap.png
ha_category: Utility
featured: false
ha_release: 0.56
---
With the namecheapDNS component you can automatically update your dynamic DNS entry.
<p class='note warning'>
Namecheap only supports IPv4 adresses to update.
</p>
To use the component in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
namecheapdns:
host: @
domain: example.com
access_token: 0123_Dynamic_DNS_Password
```
{% configuration %}
host:
description: The host part or "subdomain" part you want to update (If you want your domain leave the @ sign)
required: true
type: string
domain:
description: Your namecheap TLD (example.com).
required: true
type: string
access_token:
description: The namecheap "Dynamic DNS Password" you can find under the "Advanced DNS" Tab
required: true
type: string
{% endconfiguration %}
See the [How do I set up a Host for Dynamic DNS?](https://www.namecheap.com/support/knowledgebase/article.aspx/43/11/how-do-i-set-up-a-host-for-dynamic-dns) for further instructions

46
source/_components/notify.clickatell.markdown Normal file
View file

@ -0,0 +1,46 @@
---
layout: page
title: "Clikatell SMS"
description: "Instructions on how to add Clickatell notifications to Home Assistant."
date: 2017-10-09 00:00
sidebar: true
comments: false
sharing: true
footer: true
logo: clickatell.png
ha_category: Notifications
ha_release: 0.56
---
The `clickatell` platform uses [Clickatell](https://clickatell.com) to deliver SMS notifications from Home Assistant.
### Get your Clickatell API Credentials
Go to your [Clickatell SMS Platform Portal](https://portal.clickatell.com/#/) section and create a new SMS integration. There are three screens of information required to creater an integration. Please ensure the following:
1. Give the new Integration an identification name
2. ensure it is set for 'production' use
3. select 'HTTP' as your API type
4. Ensure that the you select for the messaging type to be 'one way messaging'
5. Be aware of the international number format option as this impacts the structure of the phone numbers you provide
6. Once you have completed entering your details an API key is generated. Copy the API key
### Configuration
To add Clickatell to your installation, add the following to your Home Assistant `configuration.yaml` file:
```yaml
notify:
- platform: clickatell
name: USER_DEFINED_NAME
api_key: CLICKATELL_API_KEY
recipient: PHONE_NO
```
Configuration variables:
* **name** (Optional): Setting the optional parameter name allows multiple notifiers to be created. The default value is `Clickatell`. The notifier will bind to the service notify.NOTIFIER_NAME.
* **api_key** (Required): Your `API Key`.
* **recipient** (Required): Your phone no. This is where you want to send your notification SMS messages. eg: `61444333444`
To use notifications, please see the [getting started with automation page](https://home-assistant.io/getting-started/automation/).

7
source/_components/notify.clicksendaudio.markdown → source/_components/notify.clicksend_tts.markdown
View file

@ -1,6 +1,6 @@
---
layout: page
title: "ClickSend"
title: "ClickSend text-to-speech"
description: "Instructions on how to add ClickSend text-to-speech (TTS) notifications to Home Assistant."
date: 2017-10-04 00:00
sidebar: true
@ -10,10 +10,11 @@ footer: true
logo: clicksend.png
ha_category: Notifications
ha_release: 0.55
redirect_from: /components/notify.clicksendaudio/
---
The `clicksendaudio` platform uses [ClickSend](https://clicksend.com) to deliver text-to-speech (TTS) notifications from Home Assistant.
The `clicksend_tts` platform uses [ClickSend](https://clicksend.com) to deliver text-to-speech (TTS) notifications from Home Assistant.
Go to your [ClickSend Dashboard](https://dashboard.clicksend.com) section and create your new project. After creating your project, you should now be able to obtain your `username` and `api_key`.
@ -21,7 +22,7 @@ To add ClickSend to your installation, add the following to your Home Assistant
```yaml
notify:
- platform: clicksend
- platform: clicksend_tts
name: ClickSend
username: CLICKSEND_USERNAME
api_key: CLICKSEND_API_KEY

38
source/_components/notify.html5.markdown
View file

@ -33,24 +33,33 @@ Configuration variables:
### {% linkable_title Getting ready for Chrome %}
- Create new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard).
- Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain.
- After that, go to [https://console.firebase.google.com](https://console.firebase.google.com) and select import Google project, select the project you created.
- Then, click the cogwheel on top left and select "Project settings".
- Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID'.
1. Create new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard).
2. Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain.
3. After that, go to [https://console.firebase.google.com](https://console.firebase.google.com) and select import Google project, select the project you created.
4. Then, click the cogwheel on top left and select "Project settings".
5. Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID'.
#### {% linkable_title Verify your domain with Hass.io %}
1. For verifying your domain you need to download a file in step 2.
2. Create a dictionary named "www" in you Hass.io configuration dictionary.
3. Place the file (something like this: google*.html) in the "www" directory.
4. You can open it by going to **https://yourdomain/local/exact_file_name.html**
5. Proceed with step 3.
### {% linkable_title Requirements %}
The `html5` platform can only function if all of the following requirements are met:
(On Hass.io these requirements are already met.)
* You are using Chrome and/or Firefox on any desktop platform, ChromeOS, or Android.
* You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android.
* Your Home Assistant instance is exposed to the world.
* If using a proxy, HTTP basic authentication must be off for registering or unregistering for push notifications. It can be re-enabled afterwards.
* `pywebpush` must be installed. `libffi-dev`, `libpython-dev`, and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install).
* You have configured SSL for your Home Assistant. It doesn't need to be configured in Home Assistant though, i.e. you can be running [NGINX](/ecosystem/nginx/) in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed).
* You are willing to accept the notification permission in your browser.
### {% linkable_title Setting up %}
Assuming you have already added the platform to your configuration:
@ -62,6 +71,7 @@ Assuming you have already added the platform to your configuration:
5. Assuming you accept, that's all there is to it!
6. (Optional, but highly recommended!) Open the `html5_push_registrations.conf` file in your configuration directory. You will see a new entry for the browser you just added. Rename it from `unnamed device` to a name of your choice, which will make it easier to identify later. _Do not change anything else in this file!_ You need to restart Home Assistant after making any changes to the file.
### {% linkable_title Usage %}
The `html5` platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload.
@ -93,7 +103,7 @@ Chrome supports notification actions, which are configurable buttons that arrive
#### {% linkable_title Data %}
Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](#automating-notification-events).
Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](#automating-notification-events).
```json
{
@ -183,13 +193,13 @@ During the lifespan of a single push notification, Home Assistant will emit a fe
Common event payload parameters are:
| Parameter | Description |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `action` | The `action` key that you set when sending the notification of the action clicked. Only appears in the `clicked` event. |
| `data` | The data dictionary you originally passed in the notify payload, minus any parameters that were added to the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`). |
| `tag` | The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications. |
| `target` | The target that this notification callback describes. |
| `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. |
| Parameter | Description |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `action` | The `action` key that you set when sending the notification of the action clicked. Only appears in the `clicked` event. |
| `data` | The data dictionary you originally passed in the notify payload, minus any parameters that were added to the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `image`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`). |
| `tag` | The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications. |
| `target` | The target that this notification callback describes. |
| `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. |
You can use the `target` parameter to write automations against a single `target`. For more granularity, use `action` and `target` together to write automations which will do specific things based on what target clicked an action.

56
source/_components/notify.rocketchat.markdown Normal file
View file

@ -0,0 +1,56 @@
---
layout: page
title: "Rocket.Chat"
description: "Instructions on how to add Rocket.Chat notifications to Home Assistant."
date: 2017-09-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: rocketchat.png
ha_category: Notifications
ha_release: 0.56
---
The `rocketchat` platform allows you to send messages to your [Rocket.Chat](https://rocket.chat/) instance from Home Assistant.
To add Rocket.Chat to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- platform: rocketchat
name: NOTIFIER_NAME
url: https://rocketchat.example.com
username: USERNAME
password: PASSWORD
room: my-awesome-room
```
- **name** (*Optional*): Name displayed in the frontend. The notifier will bind to the service `notify.NOTIFIER_NAME`.
- **url** (*Required*): The URL of your Rocket.Chat instance.
- **username** (*Required*): The Rocket.Chat username.
- **password** (*Required*): The Rocker.Chat password.
- **room** (*Required*): The chat room name to send messages to.
### {% linkable_title script.yaml example %}
```yaml
rocketchat_notification:
sequence:
- service: notify.NOTIFIER_NAME
data:
message: "Message to Rocket.Chat from Home Assistant!"
data:
emoji: ":smirk:"
```
#### {% linkable_title Message variables %}
- **message** (*Required*): Message to be displayed.
- **data** (*Optional*): Dictionary containing any of the variables defined in the
[Rocket.Chat docs](https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage#message-object-example)
To use notifications, please see the [getting started with automation page](/getting-started/automation/).

1
source/_components/notify.xmpp.markdown
View file

@ -35,6 +35,7 @@ Configuration variables:
- **recipient** (*Required*): The Jabber ID (JID) that will receive the messages.
- **tls** (*Optional*): Allow to disable TLS. Defaults to `true`.
- **verify** (*Optional*): Allow disabling SSL certificate validity check (e.g., self-signed certificate). Defaults to `true`.
- **room** (*Optional*): Room's name (e.g., example@conference.jabber.org). If set, send a message to chatroom instead of the sender.
All Jabber IDs (JID) must include the domain. Make sure that the password matches the account provided as sender.

20
source/_components/sensor.abode.markdown Normal file
View file

@ -0,0 +1,20 @@
---
layout: page
title: "Abode Sensor"
description: "Instructions how to integrate Abode sensors into Home Assistant."
date: 2017-10-05 14:00
sidebar: true
comments: false
sharing: true
footer: true
logo: abode.jpg
ha_release: 0.56
ha_category: Sensor
ha_iot_class: "Cloud Push"
---
The `abode` sensor platform allows you to monitor your [Abode](https://goabode.com/) sensors.
This platform supports Abode `Temperature`, `Humidity`, and `Light` sensors.
The requirement is that you have setup your [Abode hub](/components/abode/).

6
source/_components/sensor.airvisual.markdown
View file

@ -45,6 +45,7 @@ sensor:
latitude: 42.81212
longitude: 108.12422
radius: 500
show_on_map: false
```
Configuration variables:
@ -58,6 +59,8 @@ defined under the `homeassistant` key in `configuration.yaml` will be used
defined under the `homeassistant` key in `configuration.yaml` will be used
- **radius** (*Optional*): the radius (in meters) around the latitude/longitude to
search for the nearest city; defaults to `1000`
- **show_on_map** (*Optional*): whether to show a marker on the map at the specified
location; defaults to `true`
## {% linkable_title Configuring the Platform via City/State/Country %}
@ -74,6 +77,7 @@ sensor:
city: southend-on-sea
state: essex
country: uk
show_on_map: false
```
Configuration variables:
@ -84,6 +88,8 @@ Configuration variables:
- **city** (*Optional*): the city to monitor
- **state** (*Optional*): the state/region to monitor
- **country** (*Optional*): the country to monitor
- **show_on_map** (*Optional*): whether to show a marker on the map at the specified
location; defaults to `true`
To easily determine the proper values for a particular location, use the
[AirVisual region directory](https://airvisual.com/world). Once you browse to the particular city you want,

1
source/_components/sensor.darksky.markdown
View file

@ -66,6 +66,7 @@ Configuration variables:
- **apparent_temperature_max**: Today's expected apparent high temperature.
- **apparent_temperature_min**: Today's expected apparent low temperature.
- **precip_intensity_max**: Today's expected maximum intensity of precipitation.
- **uv_index**: The current UV index.
- **units** (*Optional*): Specify the unit system. Default to `si` or `us` based on the temperature preference in Home Assistant. Other options are `auto`, `us`, `si`, `ca`, and `uk2`.
`auto` will let Dark Sky decide the unit system based on location.
- **update_interval** (*Optional*): Minimum time interval between updates. Default is 2 minutes. Supported formats:

24
source/_components/sensor.modbus.markdown
View file

@ -56,3 +56,27 @@ Configuration variables:
- **offset** (*Optional*): Final offset (output = scale * value + offset), default 0
- **precision** (*Optional*): Number of valid decimals, default 0
- **data_type** (*Optional*): Response representation (int, float). If float selected, value will be converted to IEEE 754 floating point format. default int
It's possible to change the default 30 seconds scan interval for the sensor updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation.
### {% linkable_title Full example %}
Example a temperature sensor with a 10 seconds scan interval:
```yaml
sensor:
- platform: modbus
scan_interval: 10
registers:
- name: Room_1
slave: 10
register: 0
register_type: holding
update_interval: 2.5
unit_of_measurement: °C
count: 1
scale: 0.1
offset: 0
precision: 1
data_type: int
```

2
source/_components/sensor.mqtt_room.markdown
View file

@ -35,7 +35,7 @@ Configuration variables:
- **name** (*Optional*): The name of the sensor.
- **state_topic** (*Optional*): The topic that contains all subtopics for the rooms.
- **timeout** (*Optional*): The time in seconds after which a room presence state is considered old. An example: device1 is reported at scanner1 with a distance of 1. No further updates are sent from scanner1. After 5 seconds scanner2 reports device1 with a distance of 2. The old location info is discarded in favor of the new scanner2 information as the timeout has passed.
- **away_timeout** (*Optional*): The time in seconds after which the state should be set to `away` if there were no updates. `0` disables the check and is the default.
- **away_timeout** (*Optional*): The time in seconds after which the state should be set to `not_home` if there were no updates. `0` disables the check and is the default.
Example JSON that should be published to the room topics:

9
source/_components/sensor.netdata.markdown
View file

@ -44,3 +44,12 @@ Configuration variables:
- 'ipv4_in': Amount of inbound IPv4 packets per second
- 'ipv4_out': Amount of outbound IPv4 packets per second
- 'disk_free': Free disk space
- 'cpu_iowait': CPU spent spent waiting for IO operations
- 'cpu_user': CPU time spent executing user tasks
- 'cpu_system': CPU time spent executing system tasks
- 'cpu_softirq': CPU time spent servicing soft interrupts
- 'cpu_guest': CPU time spent on guest tasks (such as VMs)
- 'uptime': Time (in seconds) since last boot
- 'packets_received': Amount of packets received
- 'packets_sent': Amount of packets sent
- 'connections': Total active connections

6
source/_components/sensor.plex.markdown
View file

@ -15,7 +15,9 @@ ha_iot_class: "Local Polling"
The `plex` sensor platform will monitor activity on a given [Plex Media Server](https://plex.tv/). It will create a sensor that shows the number of currently watching users as the state. If you click the sensor for more details it will show you who is watching what.
If your Plex server is on the same local network as Home Assistant, all you need to provide in the `configuration.yaml` is the host or IP address. If you want to access a remote Plex server, you must provide the Plex username, password, and optionally the server name of the remote Plex server. If no server name is given it will use the first server listed. If you use the username and password, all servers in that account are monitored.
If your Plex server is on the same local network as Home Assistant, all you need to provide in the `configuration.yaml` is the host or IP address. If you want to access a remote Plex server, you must provide the Plex username, password, and optionally the server name of the remote Plex server. If no server name is given it will use the first server listed. If you use the username and password, all servers in that account are monitored.
If you don't know your token, see [Finding your account token / X-Plex-Token](https://support.plex.tv/hc/en-us/articles/204059436).
If you want to enable the plex sensor, add the following lines to your `configuration.yaml`:
@ -33,4 +35,4 @@ Configuration variables:
- **username** (*Optional*): The username for the remote Plex server.
- **password** (*Optional*): The password for your given account on the remote Plex server.
- **server** (*Optional*): The name of your remote Plex server.
- **token** (*Optional*): X-Plex-Token of your remote Plex server.

55
source/_components/sensor.serial.markdown Normal file
View file

@ -0,0 +1,55 @@
---
layout: page
title: "Serial Sensor"
description: "Instructions how to integrate data from serial connected sensors into Home Assistant."
date: 2017-10-13 07:00
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Sensor
ha_release: 0.56
ha_iot_class: "Local Polling"
---
The `serial` sensor platform is using the data provided by a device connected to the serial port of the system where Home Assistant is running. With [`ser2net`](http://ser2net.sourceforge.net/) and [`socat`](http://www.dest-unreach.org/socat/) would it also work for sensors connected to a remote system.
To check what kind of data is arriving at your serial port, use a command-line tool like `minicom` or `picocom` on Linux, on a macOS you can use `screen` or on Windows `putty`.
```bash
$ sudo minicom -D /dev/ttyACM0
```
To setup a serial sensor to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: serial
port: /dev/ttyACM0
```
{% configuration %}
port:
description: Local serial port where the sensor is connected and access is granted.
required: true
type: string
name:
description: Friendly name to use for the frontend. Default to "Serial sensor".
required: false
type: string
{% endconfiguration %}
## {% linkable_title `value_template` for Template sensor %}
### {% linkable_title TMP36 %}
{% raw %}
```yaml
"{{ (((states('sensor.serial_sensor') | float * 5 / 1024 ) - 0.5) * 100) | round(1) }}"
```
{% endraw %}

31
source/_components/sensor.skybell.markdown Normal file
View file

@ -0,0 +1,31 @@
---
layout: page
title: "Skybell Sensor"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Sensor
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
To get your [Skybell.com](https://skybell.com/) sensors working within Home Assistant, please follow the instructions for the general [Skybell component](/components/skybell).
Once you have enabled the [Skybell component](/components/skybell), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: skybell
monitored_conditions:
- chime_level
```
Configuration variables:
- **monitored_conditions** array (*Required*): Conditions to display in the frontend. The following conditions can be monitored.
- **chime_level**: Return a value between 0-3, indicating no chime, low, medium, and high respectively.

6
source/_components/sensor.statistics.markdown
View file

@ -16,11 +16,15 @@ ha_release: "0.30"
The `statistics` sensor platform is consuming the state from other sensors. Beside the maximal and the minimal value also the total, the mean, the median, the variance, and the standard deviation are as attributes available. If it's a binary sensor then only the state changes are counted.
It can take time till the sensor starts to work because a couple of attributes need more than one value to do the calculation.
If you are running the [recorder](/components/recorder/) component, on startup the data is read from the database. So after a restart of the platform, you will immediately have data available. If you're using the [history](/components/history/) component, this will automatically also start the recoder component on startup.
If you are *not* running the `recorder` component, it can take time till the sensor starts to work because a couple of attributes need more than one value to do the calculation.
To enable the statistics sensor, add the following lines to your `configuration.yaml`:
```yaml
# enable the recorder component (optional)
recorder:
# Example configuration.yaml entry
sensor:
- platform: statistics

18
source/_components/sensor.toon.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Toon"
description: "Instructions how to integrate Toon Climate devices within Home Assistant."
date: 2017-10-21 12:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Sensor
ha_release: 0.56
logo: toon.png
ha_iot_class: "Cloud Polling"
---
The `toon` sensor platform allows you to observe your Toon device.
The requirement is that you have setup the [`toon`](/components/toon/) component.

2
source/_components/sensor.transmission.markdown
View file

@ -27,6 +27,7 @@ sensor:
- 'current_status'
- 'download_speed'
- 'upload_speed'
- 'active_torrents'
```
Configuration variables:
@ -40,6 +41,7 @@ Configuration variables:
- **current_status**: The status of your Transmission daemon.
- **download_speed**: The current download speed.
- **upload_speed**: The current upload speed.
- **active_torrents**: The current number of active torrents.
To use the monitoring, your transmission client needs to allow remote access. If you are running the graphical transmission client (transmission-gtk) go to **Edit** -> **Preferences** and choose the tab **Remote**. Check **Allow remote access**, enter your username and your password, and uncheck the network restriction as needed.

39
source/_components/sensor.travisci.markdown Normal file
View file

@ -0,0 +1,39 @@
---
layout: page
title: "Travis-CI Sensor"
description: "Instructions on how to integrate the test build results reported by Travis-CI within Home Assistant."
date: 2017-09-04 10:00
sidebar: true
comments: false
sharing: true
footer: true
logo: travisci.svg
ha_category: Sensor
ha_release: "0.56"
ha_iot_class: "Cloud Polling"
---
With this sensor platform, you will be able to integrate the test build results reported by [Travis-CI](https://travis-ci.org/) working within Home Assistant.
To enable this platform, please add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: travisci
github_token: 123456789
```
Configuration variables:
- **api_key** (*Required*): GitHub [access token](https://github.com/settings/applications) with the following scopes: *read:org*, *user:email*, *repo_deployment*, *repo:status*, *write:repo_hook*.
- **branch** (*Optional*): Determine which default branch should be used by the **state** condition. Defaults to *master*.
- **scan_interval** (*Optional*): How frequently to query for new data. Defaults to 30 seconds.
- **monitored_conditions** array (*Optional*): Conditions to display in the frontend. If not specified, all conditions below will be enabled by default. The following conditions can be monitored.
- **last_build_id**: Turn the last build job ID.
- **last_build_duration**: Return the time elapsed in seconds to run the last test job.
- **last_build_finished_at**: Return the timestamp of when the last test job finished.
- **last_build_started_at**: Return the timestamp of when the last test job started.
- **last_build_state**: Return the state from the latest test job/PR. The conditions can be: 'passed', 'failed' or 'started'.
- **state**: Return the build test from the branch specified at by **branch** parameter.
- **repository:** array (*Optional*): Name from the GitHub repositories to be monitored. If not specified, all GitHub repositories linked to Travis-CI will be enabled by default.

30
source/_components/sensor.uptime.markdown Normal file
View file

@ -0,0 +1,30 @@
---
layout: page
title: "Uptime Sensor"
description: "Instructions how to integrate an uptime sensor into Home Assistant."
date: 2017-10-13 10:30
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Sensor
ha_iot_class: "Local Pushing"
logo: home-assistant.png
ha_release: 0.56
---
The `uptime` sensor platform displays the time since the last Home Assistant restart.
To enable this sensor, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
sensor:
- platform: uptime
```
Configuration variables:
- **name** (*Optional*): Name of the sensor. Defaults to `Uptime`.
- **unit_of_measurement** (*Optional*): Units for uptime measurement in either `days` or `hours`. Defaults to `days`.

34
source/_components/skybell.markdown Normal file
View file

@ -0,0 +1,34 @@
---
layout: page
title: "Skybell"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Hub
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
The `skybell` implementation allows you to integrate your [Skybell.com](https://skybell.com) doorbells in Home Assistant.
Currently only the Skybell HD is supported by this platform.
To enable devices set up with your [Skybell.com](https://skybell.com/) account, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
skybell:
username: you@example.com
password: secret
```
Configuration variables:
- **username** (*Required*): The username for accessing your Skybell account.
- **password** (*Required*): The password for accessing your Skybell account.
Finish your configuration by visiting the [Skybell binary sensor](/components/binary_sensor.skybell/), [Skybell camera](/components/camera.skybell/), [Skybell light](/components/light.skybell/), [Skybell sensor](/components/sensor.skybell/), or [Skybell switch](/components/switch.skybell/) documentation.

33
source/_components/switch.skybell.markdown Normal file
View file

@ -0,0 +1,33 @@
---
layout: page
title: "Skybell Switch"
description: "Instructions on how to integrate your Skybell HD devices within Home Assistant."
date: 2017-10-03 16:00
sidebar: true
comments: false
sharing: true
footer: true
logo: skybell.png
ha_category: Switch
ha_release: 0.56
ha_iot_class: "Cloud Polling"
---
To get your [Skybell.com](https://skybell.com/) switches working within Home Assistant, please follow the instructions for the general [Skybell component](/components/skybell).
Once you have enabled the [Skybell component](/components/skybell), add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
switch:
- platform: skybell
monitored_conditions:
- do_not_disturb
- motion_sensor
```
Configuration variables:
- **monitored_conditions** array (*Required*): Conditions to display in the frontend. The following conditions can be monitored.
- **do_not_disturb**: Control the state of your doorbells indoor chime.
- **motion_sensor**: Control the state of your doorbells motion sensor.

20
source/_components/switch.tesla.markdown Normal file
View file

@ -0,0 +1,20 @@
---
layout: page
title: "Tesla Switch"
description: "Instructions on how to integrate Tesla charging switch into Home Assistant."
date: 2017-09-19 12:20
sidebar: true
comments: false
sharing: true
footer: true
logo: tesla.png
ha_category: Switch
ha_iot_class: "Cloud Push"
ha_release: 0.54
---
The `Tesla` platform allows you to control your [Tesla](https://www.tesla.com/) charger (enable/disable charging) from within Home Assistant.
The switch platform will be automatically configured if Tesla component is configured.
For more configuration information see the [Tesla component](/components/tesla/) documentation.

18
source/_components/switch.toon.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Toon"
description: "Instructions how to integrate Toon Climate devices within Home Assistant."
date: 2017-10-21 12:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Switch
ha_release: 0.56
logo: toon.png
ha_iot_class: "Cloud Polling"
---
The `toon` switch platform allows you to control your Toon device.
The requirement is that you have setup the [`toon`](/components/toon/) component.

1
source/_components/switch.wink.markdown
View file

@ -28,4 +28,3 @@ The requirement is that you have setup [Wink](/components/wink/).
- iHome smart plug (No Wink hub required)
- Wink switch groups (User created groups of switches)

36
source/_components/switch.xiaomi_miio.markdown Normal file
View file

@ -0,0 +1,36 @@
---
layout: page
title: "Xiaomi Smart WiFi Socket and Smart Power Strip"
description: "Instructions how to integrate your Xiaomi Smart WiFi Socket aka Plug or Xiaomi Smart Power Strip within Home Assistant."
date: 2017-08-26 10:18
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Switch
ha_version: 0.56
ha_iot_class: "Local Polling"
---
The `xiaomi_miio` switch platform allows you to control the state of your Xiaomi Smart WiFi Socket aka Plug or Xiaomi Smart Power Strip.
Currently, the supported features are `on`, `off`. If the device provides the current load, it will be reported.
Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
To add a plug to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entries
switch:
- platform: xiaomi_miio
name: Original Xiaomi Mi Smart WiFi Socket
host: 192.168.130.59
token: YOUR_TOKEN
```
Configuration variables:
- **host** (*Required*): The IP of your plug.
- **token** (*Required*): The API token of your plug.
- **name** (*Optional*): The name of your plug.

1
source/_components/tesla.markdown
View file

@ -22,6 +22,7 @@ This component provides the following platforms:
- Device tracker - to track location of your car
- Lock - Door lock. Enables you to control Tesla's door lock
- Climate - HVAC control. Allow you to control (turn on/off, set target temperature) your Tesla's HVAC system.
- Switch - Charger switch. Allow you to start/stop charging.
To use Tesla in your installation, add the following to your `configuration.yaml` file:

37
source/_components/toon.markdown Normal file
View file

@ -0,0 +1,37 @@
---
layout: page
title: "Toon"
description: "Instructions how to integrate Toon within Home Assistant."
date: 2017-10-21 12:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Hub
ha_release: 0.56
logo: toon.png
ha_iot_class: "Cloud Polling"
---
The `toon` component platform can be used to control your Toon thermostat. This component adds a climate device for your Toon thermostat and sensors for power and gas consumption. The component also auto-detects any smart plugs, solar panels and smoke detectors connected to Toon and adds sensors and switches for them.
For the `toon` component to work, you'll need an active Toon subscription with Eneco. The component uses your Mijn Eneco credentials to control your thermostat through the [toonopafstand](https://toonopafstand.eneco.nl) website.
To use your Toon thermostat in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
toon:
username: YOUR_USERNAME
password: YOUR_PASSWORD
```
Configuration variables:
- **username** (*Required*): Username for Mijn Eneco.
- **password** (*Required*): Password for Mijn Eneco.
Toon is a smart thermostat delivered by the Eneco power company in The Netherlands. It can measure energy consumption (power and gas), but also the amount of energy generated in case solar panels are connected to it. Toon also acts as a z-wave hub for supported Fibaro devices like the wall plug and the smoke detector. This component uses the [toonlib library](https://github.com/costastf/toonlib) by Costas Tyfoxylos that connects to the unofficial API on [https://toonopafstand.eneco.nl](https://toonopafstand.eneco.nl).
The current version of this component supports setting any of the four built-in programs and setting the temperature manually. It polls the Toon API at 30 second intervals so the status is relatively fresh without overloading the API.

38
source/_components/tradfri.markdown
View file

@ -14,44 +14,8 @@ ha_iot_class: "Local Polling"
ha_release: 0.43
---
The `tradfri` component supports for the IKEA Trådfri (Tradfri) gateway. The gateway can control lights connected to it and Home Assistant will automatically discover its presence on your network.
The `tradfri` component supports for the IKEA Trådfri (Tradfri) gateway. The gateway can control lights connected to it and Home Assistant will automatically discover its presence on your network.
For this to work, you need to install a modified lib-coap library.
<p class='note warning'>
This component does **not** work on Windows, as the modified lib-coap doesn't exists for Windows.
</p>
<p class='note'>
If you are using [Hass.io](/hassio/) then just move forward to the configuration as all requirements are already fulfilled.
</p>
Linux:
```bash
$ sudo apt-get install libtool
$ sudo apt-get install autoconf
$ git clone --depth 1 --recursive -b dtls https://github.com/home-assistant/libcoap.git
$ cd libcoap
$ ./autogen.sh
$ ./configure --disable-documentation --disable-shared --without-debug CFLAGS="-D COAP_DEBUG_FD=stderr"
$ make
$ sudo make install
```
macOS:
```bash
$ brew install libtool
$ brew install autoconf
$ brew install automake
$ git clone --depth 1 --recursive -b dtls https://github.com/home-assistant/libcoap.git
$ cd libcoap
$ ./autogen.sh
$ ./configure --disable-documentation --disable-shared --without-debug CFLAGS="-D COAP_DEBUG_FD=stderr"
$ make
$ make install
```
You will be prompted to configure the gateway through the Home Assistant interface, Enter the security key when prompted and click configure
<p class='note'>

145
source/_components/vacuum.xiaomi_miio.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Xiaomi Mi Robot Vacuum"
description: "Instructions how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant."
description: "Instructions on how to integrate your Xiaomi Mi Robot Vacuum within Home Assistant."
date: 2017-05-05 18:11
sidebar: true
comments: false
@ -13,16 +13,29 @@ ha_release: 0.51
ha_iot_class: "Local Polling"
---
The `xiaomi miio` vacuum platform allows you to control the state of your [Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/).
The `xiaomi miio` vacuum platform allows you to control the state of your
[Xiaomi Mi Robot Vacuum](http://www.mi.com/roomrobot/).
Current supported features are `turn_on`, `pause`, `stop`, `return_to_home`, `turn_off` (stops goes to dock), `locate`, `clean_spot`, `set_fanspeed` and even remote control your robot.
Currently supported features are:
Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
- `turn_on`
- `pause`
- `stop`
- `return_to_home`
- `turn_off` (stop all activity and return to dock)
- `locate`
- `clean_spot`
- `set_fanspeed`
- remote control of your robot.
To add a vacuum to your installation, add the following to your `configuration.yaml` file:
Please follow [Retrieving the Access Token](/components/vacuum.xiaomi/#retrieving-the-access-token) to retrieve the API token used in
`configuration.yaml`.
## {% linkable_title Configuring the Platform %}
To add a vacuum to your installation, add the following to `configuration.yaml`:
```yaml
# Example configuration.yaml entry
vacuum:
- platform: xiaomi_miio
host: 192.168.1.2
@ -35,77 +48,99 @@ Configuration variables:
- **token** (*Required*): The API token of your robot.
- **name** (*Optional*): The name of your robot.
### {% linkable_title Platform services %}
## {% linkable_title Platform Services %}
In addition to all [`vacuum` component services](/components/vacuum#component-services) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`, `set_fanspeed` and `send_command`), the `xiaomi` platform introduces specific services to access the remote control mode of the botvac.
In addition to [all of the services provided by the `vacuum` component]
]) (`turn_on`, `turn_off`, `start_pause`, `stop`, `return_to_home`, `locate`,
`set_fanspeed` and `send_command`), the `xiaomi` platform introduces specific
services to access the remote control mode of the robot. These are:
These are: `xiaomi_remote_control_start`, `xiaomi_remote_control_stop`, `xiaomi_remote_control_move` and `xiaomi_remote_control_move_step`.
- `xiaomi_remote_control_start`
- `xiaomi_remote_control_stop`
- `xiaomi_remote_control_move`
- `xiaomi_remote_control_move_step`
#### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %}
### {% linkable_title Service `vacuum/xiaomi_remote_control_start` %}
Start the remote control mode of the vacuum cleaner. You can then move it with `remote_control_move`, when done call `remote_control_stop`.
Start the remote control mode of the robot. You can then move it with
`remote_control_move`; when done, call `remote_control_stop`.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
| `entity_id` | yes | Only act on specific robot; default targets all |
#### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %}
### {% linkable_title Service `vacuum/xiaomi_remote_control_stop` %}
Exit the remote control mode of the vacuum cleaner.
Exit the remote control mode of the robot.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
| `entity_id` | yes | Only act on specific robot; default targets all |
#### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %}
### {% linkable_title Service `vacuum/xiaomi_remote_control_move` %}
Remote control the vacuum cleaner, make sure you first set it in remote control mode with `remote_control_start`.
Remote control the robot. Please ensure you first set it in remote control
mode with `remote_control_start`.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
| `velocity` | no | Speed, between -0.29 and 0.29. |
| `rotation` | no | Rotation, between -179 degrees and 179 degrees. |
| `duration` | no | Parameter affecting the duration of the movement. |
| `entity_id` | yes | Only act on specific robot; default targets all |
| `velocity` | no | Speed: between -0.29 and 0.29 |
| `rotation` | no | Rotation: between -179 degrees and 179 degrees |
| `duration` | no | The number of seconds that the robot should move for |
#### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %}
### {% linkable_title Service `vacuum/xiaomi_remote_control_move_step` %}
Use this call to enter the remote control mode, make one move, and stop and exit the remote control mode.
Enter remote control mode, make one move, stop, and exit remote control mode.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on specific botvac. Else targets all. |
| `velocity` | no | Speed, between -0.29 and 0.29. |
| `rotation` | no | Rotation, between -179 degrees and 179 degrees. |
| `duration` | no | Parameter affecting the duration of the movement. |
| `entity_id` | yes | Only act on specific robot; default targets all |
| `velocity` | no | Speed: between -0.29 and 0.29. |
| `rotation` | no | Rotation: between -179 degrees and 179 degrees. |
| `duration` | no | The number of seconds that the robot should move for |
### {% linkable_title Attributes %}
## {% linkable_title Attributes %}
In addition to all [`vacuum` component attributes] (`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, `params`), the `xiaomi` platform introduces specific attributes to get information of the botvac.
In addition to [all of the attributes provided by the `vacuum` component](https://home-assistant.io/components/vacuum/#attributes),
(`battery_icon`, `cleaned_area`, `fan_speed`, `fan_speed_list`, `status`, and
`params`), the `xiaomi` platform introduces specific attributes. These are:
These are: `cleaning_time`, `do_not_disturb`, `main_brush_left`, `side_brush_left`, `filter_left`, `cleaning_count`, `total_cleaned_area` and `total_cleaning_time`.
- `cleaning_time`
- `do_not_disturb`
- `main_brush_left`
- `side_brush_left`
- `filter_left`
- `cleaning_count`
- `total_cleaned_area`
- `total_cleaning_time`
The following table shows the units of measurement for the single attributes.
The following table shows the units of measurement for each attribute:
| Attribute | Unit of measurement | Description |
|---------------------------|---------------------|-------------------------------------------------------|
| `do_not_disturb` | | DND mode on / off |
| `cleaning_time` | minutes | Last / actual cleaning time in minutes |
| `cleaned_area` | square meter | Last / actual cleaned area in square meter |
| `cleaned_area` | square meter | Last / actual cleaned area in square meters |
| `main_brush_left` | hours | Hours left until a change of the main brush is needed |
| `side_brush_left` | hours | Hours left until a change of the side brush is needed |
| `filter_left` | hours | Hours left until a change of the filter is needed |
| `cleaning_count` | | Number of total cleaning passage |
| `total_cleaned_area` | square meter | Total cleaned area in square meter |
| `cleaning_count` | | Number of total cleaning cycles |
| `total_cleaned_area` | square meter | Total cleaned area in square meters |
| `total_cleaning_time` | minutes | Total cleaning time in minutes |
### {% linkable_title Retrieving the Access Token %}
## {% linkable_title Retrieving the Access Token %}
<p class='note'>
This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot Vacuum and Xiaomi Philips Light. The Xiaomi Gateway uses another security method and requires a `key` (16 alphanumeric chars) which can be obtained easily via a hidden menu item at the Mi-Home app.
This token (32 hexadecimal characters) is required for the Xiaomi Mi Robot
Vacuum and Xiaomi Philips Lights. The Xiaomi Gateway uses another security
method and requires a `key` (16 alphanumeric chars), which can be obtained
easily via a hidden menu item at the Mi-Home app.
</p>
#### {% linkable_title Windows and Android %}
Follow the pairing process using your phone and Mi-Home app. You will be able to retrieve the token from a SQLite file inside your phone.
Before you begin you need to install `libffi-dev` and `libssl-dev` by running the command below. This is needed for `python-mirobo` to be installed correctly.
@ -123,8 +158,6 @@ $ source /srv/homeassistant/bin/activate
To fetch the token follow these instructions depending on your mobile phone platform.
#### {% linkable_title Windows and Android %}
1. Configure the robot with the Mi-Home app.
2. Enable developer mode and USB debugging on the Android phone and plug it into the computer.
3. Get and install the [ADB tool for Windows](https://developer.android.com/studio/releases/platform-tools.html).
@ -152,10 +185,44 @@ $ java.exe -jar ../android-backup-extractor/abe.jar unpack backup.ab backup.tar
#### {% linkable_title Linux and Android (rooted!) %}
1. Configure the light with the Mi-Home app.
Follow the pairing process using your phone and Mi-Home app. You will be able to retrieve the token from a SQLite file inside your phone.
Before you begin you need to install `libffi-dev` and `libssl-dev` by running the command below. This is needed for `python-mirobo` to be installed correctly.
```bash
$ sudo apt-get install libffi-dev libssl-dev
```
If your Home Assistant installation is running in a [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant), make sure you activate it by running the commands below.
```bash
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
```
To fetch the token follow these instructions depending on your mobile phone platform.
1. Configure the robot with the Mi-Home app.
2. Enable developer mode, USB debugging and root permission only for ADB on the Android phone and plug it into the computer.
3. Get ADB f.e. `apt-get install android-tools-adb`
4. `adb devices` should list your device
5. `adb root` (does work for development builds only: ones with `ro.debuggable=1`)
6. `adb shell`
7. `echo "select name,localIP,token from devicerecord;" | sqlite3 /data/data/com.xiaomi.smarthome/databases/miio2.db` returns a list of all registered devices including IP address and token.
#### {% linkable_title iOS %}
1. Configure the robot with the Mi-Home app.
2. Using iTunes, create an unencrypted backup of your iPhone.
3. Install [iBackup Viewer](Get ADB f.e. `apt-get install android-tools-adb`), open it, and open your backup.
4. Open the "Raw Data" module.
5. Navigate to `com.xiaomi.mihome`.
6. Search for a file that looks like this: `123456789_mihome.sqlite` – note that `_mihome.sqlite` is *not* the correct file.
7. Save this file to your filesystem.
8. Install [DB Browser for SQLite](http://sqlitebrowser.org/).
9. Open DB Browser and load the `.sqlite` file you saved from your backup.
10. Click on the `Execute SQL` tab.
11. Input and run this query: `SELECT ZTOKEN FROM ZDEVICE WHERE ZNAME = "Mi Robot Vacuum"`
12. Copy the returned 32-digit hexadecimal string to your clipboard.
13. Open `Terminal` and execute this command: `echo '0: <YOUR HEXADECIMAL STRING>' | xxd -r -p | openssl enc -d -aes-128-ecb -nopad -nosalt -K 00000000000000000000000000000000`
14. Use the resulting string as your token.

150
source/_components/wink.markdown
View file

@ -145,3 +145,153 @@ Home Assistant entity_ids for Wink devices are based on the Wink device's name.
The Wink hub, by default, can only be accessed via the cloud. This means it requires an active internet connection and you will experience delays when controlling and updating devices (~3s).
</p>
### Custom Wink devices and their services
- GoControl siren and strobe
- Dome siren/chime/strobe
### {% linkable_title Service `set_siren_auto_shutoff` %}
You can use the service wink/set_siren_auto_shutoff to set how long the siren will sound before shuting off.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `auto_shutoff` | no | Int. One of [None, -1, 30, 60, 120] (None and -1 are forever. Use None for gocontrol, and -1 for Dome)
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren.
Example:
```yaml
script:
set_all_sirens_to_one_minute_auto_shutoff:
sequence:
- service: wink.set_siren_auto_shutoff
data:
auto_shutoff: 60
```
<p class='note'>
The following services only work with the Dome siren/chime.
</p>
### {% linkable_title Service `set_chime_volume` %}
You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `volume` | no | String. One of ["low", "medium", "high"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
Example:
```yaml
script:
set_chime_volume_to_low_for_all_chimes
sequence:
- service: wink.set_chime_volume
data:
volume: "low"
```
### {% linkable_title Service `set_siren_volume` %}
You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `volume` | no | String. One of ["low", "medium", "high"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
Example:
```yaml
script:
set_siren_volume_to_low_for_all_sirens
sequence:
- service: wink.set_siren_volume
data:
volume: "low"
```
### {% linkable_title Service `enable_chime` %}
You can use the service wink/enable_chime to set the tone and enable the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep", "inactive"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
Example:
```yaml
script:
execute_doorbell
sequence:
- service: wink.enable_chime
data:
tone: "doorbell"
```
### {% linkable_title Service `set_siren_tone` %}
You can use the service wink/set_siren_tone to set the tone on your Dome siren. This tone will be used the next time the siren is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
Example:
```yaml
script:
set_siren_to_alert:
sequence:
- service: wink.set_siren_tone
data:
tone: "alert"
```
### {% linkable_title Service `set_siren_strobe_enabled` %}
You can use the service wink/set_siren_strobe_enabled to enable or disable the strobe when the siren is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean. True or False.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
Example:
```yaml
script:
disable_siren_strobe:
sequence:
- service: wink.set_siren_strobe_enabled
data:
enabled: False
```
### {% linkable_title Service `set_chime_strobe_enabled` %}
You can use the service wink/set_chime_strobe_enabled to enable or disable the strobe when the chime is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean. True or False.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of chime/chime.
Example:
```yaml
script:
disable_chime_strobe:
sequence:
- service: wink.set_chime_strobe_enabled
data:
enabled: False
```