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

Merge pull request #5059 from home-assistant/rc

Browse source 
0.66.0
This commit is contained in:
Paulus Schoutsen 2018-03-30 15:16:57 -07:00 • committed by GitHub
commit 58d1fb93f8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
46 changed files with 1887 additions and 194 deletions
Download patch file Download diff file Expand all files Collapse all files

93
source/_components/alarm_control_panel.ifttt.markdown Normal file
View file

@ -0,0 +1,93 @@
---
layout: page
title: "IFTTT Alarm Control Panel"
description: "Instructions on how to integrate IFTTT-controlled security systems into Home Assistant."
date: 2018-03-10 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: ifttt.png
ha_category: Alarm
ha_release: 0.66
---
The `ifttt` platform allows you to integrate security systems that have no open API but can be controlled through [IFTTT](https://ifttt.com/discover).
This platform depends on the [IFTTT](https://home-assistant.io/components/ifttt/) Home Assistant component. See the component's documentation to set it up.
<p class='note'>
It is important to note that this platform fully relies on IFTTT to receive updates when the security system's state changes. Therefore, this platform shows an assumed state.
</p>
To enable this, setup the required IFTTT applets as listed below and add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
ifttt:
key: YOUR_WEBHOOK_KEY
alarm_control_panel:
- platform: ifttt
name: YOUR_ALARM_NAME
code: YOUR_ALARM_CODE
event_arm_away: YOUR_ARM_AWAY_EVENT
event_arm_home: YOUR_ARM_HOME_EVENT
event_arm_night: YOUR_ARM_NIGHT_EVENT
event_disarm: YOUR_DISARM_EVENT
```
<p class='note warning'>
It is strongly discouraged to use this platform when you don't use encryption; otherwise, your API password will be send unprotected through the IFTTT Webhooks. It is adviced to [setup encryption using Let's Encrypt](https://home-assistant.io/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/).
</p>
{% linkable_title Required IFTTT applets %}
This platform supports the services `alarm_disarm`, `alarm_arm_away`, `alarm_arm_home` and `alarm_arm_night`. For each of these services, an IFTTT webhook will be triggered.
For this system to operate correctly, the following IFTTT applets have to be setup. Obviously, if your alarm device does not support some states, no applets have to be provided for those.
* **IF** Webhook event `YOUR_DISARM_EVENT` is called, **THEN** disarm the alarm system.
* **IF** Webhook event `YOUR_ARM_HOME_EVENT` is called, **THEN** set the alarm system to armed home.
* **IF** Webhook event `YOUR_ARM_NIGHT_EVENT` is called, **THEN** set the alarm system to armed away.
* **IF** Webhook event `YOUR_DISARM_EVENT` is called, **THEN** set the alarm system to armed night.
* **IF** the alarm system was disarmed, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "disarmed"}`.
* **IF** the alarm system state changed to armed home, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_home"}`.
* **IF** the alarm system state changed to armed away, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_away"}`.
* **IF** the alarm system state changed to armed night, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_night"}`.
{% configuration %}
name:
description: The name of your Home Assistant alarm control panel.
required: false
type: string
code:
description: The code for the alarm control panel.
required: false
type: string
event_arm_away:
description: IFTTT webhook event to call when the state is set to armed away.
required: false
type: string
default: alarm_arm_away
event_arm_home:
description: IFTTT webhook event to call when the state is set to armed home.
required: false
type: string
default: alarm_arm_home
event_arm_night:
description: IFTTT webhook event to call when the state is set to armed night.
required: false
type: string
default: alarm_arm_night
event_disarm:
description: IFTTT webhook event to call when the state is set to disarmed.
required: false
type: string
default: alarm_disarm
optimistic:
description: Specify if the state will be updated by a ifttt_push_alarm_state call (false) or can be set immediately (true).
required: false
type: boolean
default: false
{% endconfiguration %}

20
source/_components/binary_sensor.bmw_connected_drive.markdown Executable file
View file

@ -0,0 +1,20 @@
---
layout: page
title: "BMW connected drive"
description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
date: 2018-02-22 23:00
sidebar: true
comments: false
sharing: true
footer: true
logo: bmw.png
ha_category: Binary Sensor
ha_release: 0.66
---
The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant.
The binary sensors will be automatically configured if 'bmw_connected_drive' component is configured.
For more configuration information see the [bmw_connected_drive component](/components/bmw_connected_drive/) documentation.

51
source/_components/camera.proxy.markdown
View file

@ -29,17 +29,46 @@ camera:
max_image_width: 720
```
Configuration variables:
- **entity_id** (*Required*): The ID of another Home Assistant camera to post-process.
- **name** (*Optional*): This parameter allows you to override the name of your camera.
- **max_image_width** (*Optional*): The maximum width of single images taken from the camera (aspect ratio will be maintained).
- **max_stream_width** (*Optional*): The maximum width of the MJPEG stream from the camera (aspect ratio will be maintained).
- **image_quality** (*Optional*): The quality level used for resulting JPEG for snapshots (default: 75).
- **stream_quality** (*Optional*): The quality level used for resulting MJPEG streams (default: 75).
- **image_refresh_rate** (*Optional*): The minimum time in seconds between generating successive image snapshots.
- **force_resize** (*Optional*): Resize the image even if the resulting image would take up more bandwidth than the original.
- **cache_images** (*Optional*): Preserve the last image and re-send in the case the camera is not responding.
{% configuration %}
entity_id:
description: The ID of another Home Assistant camera to post-process.
required: true
type: string
name:
description: This parameter allows you to override the name of your camera.
required: false
type: string
max_image_width:
description: The maximum width of single images taken from the camera (aspect ratio will be maintained).
required: false
type: integer
max_stream_width:
description: The maximum width of the MJPEG stream from the camera (aspect ratio will be maintained).
required: false
type: integer
image_quality:
description: The quality level used for resulting JPEG for snapshots.
required: false
type: integer
default: 75
stream_quality:
description: The quality level used for resulting MJPEG streams.
required: false
type: integer
default: 75
image_refresh_rate:
description: The minimum time in seconds between generating successive image snapshots.
required: false
type: float
force_resize:
description: Resize the image even if the resulting image would take up more bandwidth than the original.
required: false
type: boolean
cache_images:
description: Preserve the last image and re-send in the case the camera is not responding.
required: false
type: boolean
{% endconfiguration %}
## {% linkable_title Examples %}

43
source/_components/cover.group.markdown Normal file
View file

@ -0,0 +1,43 @@
---
layout: page
title: "Cover Group"
description: "Instructions how to setup grouped covers in Home Assistant."
date: 2018-02-11 10:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Cover
ha_release: 0.66
ha_iot_class: "Local Push"
logo: home-assistant.png
---
The `group` platform can create a cover that combines several cover entities into one.
To enable `Cover Groups` in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: group
entities:
- cover.hall_window
- cover.living_room_window
```
{% configuration %}
name:
description: Name to use in the frontend.
required: false
type: string
default: "Cover Group"
entities:
description: List of all cover entities you want to control.
required: true
type: [string | list]
{% endconfiguration %}
## {% linkable_title Functionality %}
It works best if you group covers with the same supported features together (like support for `open`/`close`/`stop`/`position`/`tilt controls`), but is not limited to it. In case you have bundled covers with different features together, the controls will only affect those covers that support the actions.

2
source/_components/deconz.markdown
View file

@ -20,9 +20,11 @@ ha_iot_class: "Local Push"
### {% linkable_title Supported device types %}
- [Zigbee Lights](/components/light.deconz/)
- [Consumption Sensors](/components/sensor.deconz/)
- [Humidity Sensors](/components/sensor.deconz/)
- [Light Level Sensors](/components/sensor.deconz/)
- [OpenClose Detectors](/components/binary_sensor.deconz/)
- [Power Sensors](/components/sensor.deconz/)
- [Presence Detectors](/components/binary_sensor.deconz/)
- [Pressure Sensors](/components/sensor.deconz/)
- [Switches (Remote Controls)](/components/sensor.deconz/)

26
source/_components/downloader.markdown
View file

@ -42,3 +42,29 @@ This will download the file from the given URL.
| `subdir` | yes | Download into subdirectory of **download_dir** |
| `filename` | yes | Determine the filename. |
| `overwrite` | yes | Whether to overwrite the file or not, defaults to `false`. |
### {% linkable_title Download Status Events %}
When a download finished successfully, Home Assistant will emit a 'downloader_download_completed' event to the event bus which you can use to write automations against.
In case download failed another event 'downloader_download_failed' is emitted to indicate that the download did not complete successfully.
Along with the event the following payload parameters are available:
| Parameter | Description |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `url` | The `url` that was requested.|
| `filename` | The `name` of the file that was being downloaded.|
#### Example Automation:
```yaml
- alias: Download Failed Notification
trigger:
platform: event
event_type: downloader_download_failed
action:
service: persistent_notification.create
data_template:
message: "{{trigger.event.data.filename}} download failed"
title: "Download Failed"
```

9
source/_components/fan.xiaomi_miio.markdown
View file

@ -71,6 +71,15 @@ name:
## {% linkable_title Platform Services %}
### {% linkable_title Service `fan.set_speed` %}
Set the fan speed/operation mode.
| Service data attribute | Optional | Description |
|---------------------------|----------|---------------------------------------------------------------------|
| `entity_id` | yes | Only act on a specific air purifier. Else targets all. |
| `speed` | no | Fan speed. Valid values are 'Auto', 'Silent', 'Favorite' and 'Idle' |
### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_on` %}
Turn the buzzer on.

16
source/_components/fan.zha.markdown Normal file
View file

@ -0,0 +1,16 @@
---
layout: page
title: "ZigBee Home Automation Fan"
description: "Instructions how to setup ZigBee Home Automation fans within Home Assistant."
date: 2018-02-10 00:00
sidebar: true
comments: false
sharing: true
footer: true
logo: zigbee.png
ha_category: Fan
ha_iot_class: "Local Polling"
ha_release: 0.66
---
To get your ZigBee fans working with Home Assistant, follow the instructions for the general [ZigBee Home Automation component](/components/zha/).

76
source/_components/google_assistant.markdown
View file

@ -131,58 +131,32 @@ If you're not using Linux, you can use sites such as [this one](https://www.brow
### {% linkable_title Setup %}
1. Download the [gactions CLI](https://developers.google.com/actions/tools/gactions-cli) to be used later. You can download and run this anywhere and on any machine. Just remember where you put it for later and don't forget to run `chmod +x gactions` to make it executable on Mac or Linux.
2. Create a new file named `project.json` (in the same directory you downloaded `gactions` to) and replace the `[YOUR HOME ASSISTANT URL:PORT]` below with the URL you use to access Home Assistant.
Note: This must be an HTTPS URL to work. Don't forget to include the port number if you're not using port 443.
```json
{
"actions": [{
"name": "actions.devices",
"deviceControl": {
},
"fulfillment": {
"conversationName": "automation"
}
}],
"conversations": {
"automation":
{
"name": "automation",
"url": "https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant"
}
}
}
```
3. Create a new project in the [developer console](https://console.actions.google.com/).
1. Create a new project in the [developer console](https://console.actions.google.com/).
a. Add/Import project
b. Go to Build under the Actions SDK box
c. 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 in a console from the same directory you saved `project.json` in (you'll need to put `./` before `gactions` so that it reads `./gactions` if you're running it on Linux or Windows). 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: The `client_id` from your Home Assistant configuration above
3. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`. If you have set `api_password:` add this password to the URL `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth?api_password=[YOUR API PASSWORD]`)
4. Configure your client. Add scopes for `email` and `name`.
5. Testing instructions: Enter anything. It 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. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have.
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.
10. If you want to allow other household users to control the devices:
1. Go to the developer console using the address from point 4.
2. Under the gear icon, click `Permissions`
3. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
4. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 7.
11. If you want to use the `google_assistant.request_sync` service, to update devices without unlinking and relinking, in Home Assistant, then enable Homegraph API for your project:
1. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview)
2. Select your project and click Enable Homegraph API
3. Go to Credentials and select API Key from Create Credentials
4. Note down the generated API Key and use this in the configuration
b. Click on `BUILD` on the `Smart home` card
c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable.
d. Click `Done`. Then click on `Overview`, which will lead you to the app details screen.
2. 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.
3. The final item on that page `Account linking` is required for your app to interact with Home Assistant.
a. Grant type: `Implicit`
b. Client ID: The `client_id` from your Home Assistant configuration above
c. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`. If you have set `api_password:` add this password to the URL `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth?api_password=[YOUR API PASSWORD]`)
d. Configure your client. Add scopes for `email` and `name`.
e. Testing instructions: Enter anything. It doesn't matter since you won't submit this app.
4. 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).
5. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have.
6. Open the Google Assistant app and go into `Settings > Home Control`
7. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead you the screen where you can set rooms for your devices or nicknames for your devices.
8. If you want to allow other household users to control the devices:
a. Go to the developer console using the address from point 4.
b. Under the gear icon, click `Permissions`
c. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
d. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point
9. If you want to use the `google_assistant.request_sync` service, to update devices without unlinking and relinking, in Home Assistant, then enable Homegraph API for your project:
a. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview)
b. Select your project and click Enable Homegraph API
c. Go to Credentials, which you can find on the left navigation bar under the key icon, and select API Key from Create Credentials
d. Note down the generated API Key and use this in the configuration
### {% linkable_title Troubleshooting the request_sync service %}

154
source/_components/homekit.markdown
View file

@ -12,7 +12,12 @@ ha_release: 0.64
logo: apple-homekit.png
---
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`.
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
<p class="note warning">
It might be necessary to install an additional package:
`$ sudo apt-get install libavahi-compat-libdnssd-dev`
</p>
{% configuration %}
homekit:
@ -20,18 +25,55 @@ The `HomeKit` component allows you to forward entities from Home Assistant to Ap
required: true
type: map
keys:
pincode:
description: Pin code required during setup of HomeKit Home Assistant accessory. The format needs to be 'XXX-XX-XXX' where X is a number between 0 and 9.
auto_start:
description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start))
required: false
type: string
default: '"123-45-678"'
type: boolean
default: true
port:
description: Port for the HomeKit extension.
required: false
type: int
default: 51826
default: 51827
filter:
description: Filter entities to available in the `Home` app. ([Configure Filter](#configure-filter))
required: false
type: map
keys:
include_domains:
description: Domains to be included.
required: false
type: list
include_entities:
description: Entities to be included.
required: false
type: list
exclude_domains:
description: Domains to be excluded.
required: false
type: list
exclude_entities:
description: Entities to be excluded.
required: false
type: list
entity_config:
description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g. `alarm_control_panel.alarm`.
required: false
type: map
keys:
alarm_control_panel:
description: Additional options for `alarm_control_panel` entities.
required: false
type: map
keys:
code:
description: Code to arm or disarm the alarm in the frontend.
required: false
type: string
default: ''
{% endconfiguration %}
## {% linkable_title Setup %}
To enable the `HomeKit` component in Home Assistant, add the following to your configuration file:
@ -39,18 +81,78 @@ To enable the `HomeKit` component in Home Assistant, add the following to your c
```yaml
# Example for HomeKit setup
homekit:
pincode: '123-45-678'
```
<p class='note'>It is not recommended to choose '123-45-678' as your pin code!</p>
After Home Assistant has started, all supported entities (see the [list](#supported-components) below which components are already integrated) will be exposed to `HomeKit`. To add them:
1. Open the `Home` App.
2. Choose `Add Accessory` and then `Don't Have a Code or Can't Scan?`.
3. The `Home Assistant` Bridge should be listed there. Select it and follow the instructions to complete setup.
After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if the are [supported](#supported-components). To add them:
1. Open the Home Assistant frontend. A new card will display the `pin code`.
1. Open the `Home` app.
2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`.
4. Confirm the you are adding an `Uncertified Accessory` by clicking on `Add Anyway`.
5. Follow the setup be clicking on `Next` and lastly `Done` in the top right hand corner.
6. The `Home Assistant` Bridge and the Accessories should now be listed in the `Home` app.
After the setup is completed you should be able to control your Home Assistant components through `Home` and `Siri`.
## {% linkable_title Considerations %}
### {% linkable_title Accessory ID %}
Currently this component uses the `entity_id` to generate a unique `accessory id (aid)` for `HomeKit`. The `aid` is used to identify a device and save all configurations made for it. This however means that if you decide to change an `entity_id` all configurations for this accessory made in the `Home` app will be lost.
### {% linkable_title Persistence Storage %}
Unfortunately `HomeKit` doesn't support any kind of persistence storage, only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one).
## {% linkable_title Disable Auto Start %}
Depending on your individual setup, it might be necessary to disable `Auto Start` for all accessories to be available for `HomeKit`. Only those entities that are fully setup when the `HomeKit` component is started, can be added. To start `HomeKit` when `auto_start: False`, you can call the service `homekit.start`.
This can be automated using an `automation`.
{% raw %}
```yaml
# Example for Z-Wave
homekit:
auto_start: False
automation:
- alias: 'Start HomeKit'
trigger:
- platform: event
event_type: zwave.network_ready
action:
- service: homekit.start
```
{% endraw %}
{% raw %}
```yaml
# Example using a delay after start of Home Assistant
homekit:
auto_start: False
automation:
- alias: 'Start HomeKit'
trigger:
- platform: homeassistant
event: start
action:
- delay: 00:05 # Waits 5 minutes
- service: homekit.start
```
{% endraw %}
## {% linkable_title Configure Filter %}
To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. By default no entity will be excluded. Keep in mind though that only supported components can be added.
## {% linkable_title Supported Components %}
The following components are currently supported:
@ -59,8 +161,28 @@ The following components are currently supported:
| --------- | --------- | ----------- |
| alarm_control_panel | SecuritySystem | All security systems. |
| climate | Thermostat | All climate devices. |
| cover | Window | All covers that support `set_cover_position`. |
| cover | WindowCovering | All covers that support `set_cover_position`. |
| light | Light | Support for `on / off`, `brightness` and `rgb_color`. |
| sensor | TemperatureSensor | All sensors that have `Celsius` and `Fahrenheit` as their `unit_of_measurement`. |
| switch/remote | Switch | All switches or remotes (represented as switches). |
| sensor | HumiditySensor | All sensors that have `%` as their `unit_of_measurement` |
| switch / remote / input_boolean / script | Switch | All represented as switches. |
<p class='note'>Currently only devices that are setup when Home Assistant is starting can be exposed to `HomeKit`. This means that especially `Z-Wave` components are currently not supported, since they will be setup afterwards. We are working on a solution for this problem.</p>
## {% linkable_title Error reporting %}
If you encounter any issues or bug and want to report them on `GitHub`, please follow these steps to make it easier for others to help and get your issue solved.
1. Enable debugging mode:
```yaml
logger:
default: warning
logs:
homeassistant.components.homekit: debug
```
2. Reproduce the bug / problem you have encountered.
3. Stop Home Assistant and copy the log from the log file. That is necessary since some errors only get logged, when Home Assistant is being shutdown.
4. Follow this link: [home-assistant/issues/new](https://github.com/home-assistant/home-assistant/issues/new?labels=component: homekit) and open a new issue.
5. Fill out all fields and especially include the following information:
- The configuration entries for `homekit` and the `component` that is causing the issue.
- The log / traceback you have generated before.
- Screenshots of the failing entity in the `states` panel.

42
source/_components/homematicip.markdown Normal file
View file

@ -0,0 +1,42 @@
---
layout: page
title: "HomematicIP"
description: "Instructions for integrating HomematicIP into Home Assistant."
date: 2018-03-06 20:40
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Hub
ha_iot_class: "Cloud Polling"
ha_release: 0.66
featured: false
---
The [HomematicIP](http://www.homematicip.com/) component platform is used as an interface to the cloud server.
For for communication [homematicip-rest-api](https://github.com/coreGreenberet/homematicip-rest-api) is used.
To set up the component:
- **generate the authentication token**:
```yaml
generate_auth_token.py
```
- ** add the information to your `configuration.yaml` file:
```yaml
homematicip:
- name: NAME
accesspoint: IDENTIFIER
authtoken: AUTHTOKEN
```
Configuration variables (global):
- **name** (*Required*): Name to identify your access point, this will be
used to prefix your device names.
- **accesspoint** (*Required*): This is the access point id (SGTIN)
- **authtoken** (*Required*): Authentification token generated with
`generate_auth_token.py`.

13
source/_components/light.markdown
View file

@ -19,26 +19,27 @@ The light component supports multiple entries in <code>configuration.yaml</code>
Turns one light on or multiple lights on using [groups]({{site_root}}/components/group/).
Most lights do not support all attributes. You can check the platform documentation of your particular light for hints but in general you will have to try things out and see what works.
Most lights do not support all attributes. You can check the platform documentation of your particular light for hints, but in general, you will have to try things out and see what works.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of lights. Else targets all.
| `transition` | yes | Number that represents the time (in seconds) the light should take to transition to the new state.
| `profile` | yes | String with the name of one of the [built-in profiles](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) (relax, energize, concentrate, reading) or one of the custom profiles defined in `light_profiles.csv` in the current working directory. Light profiles define a xy color and a brightness. If a profile is given and a brightness then the profile brightness will be overwritten.
| `xy_color` | yes | A list containing two floats representing the xy color you want the light to be. Two comma separated floats that represent the color in XY.
| `rgb_color` | yes | A list containing three integers representing the rgb color you want the light to be. Three comma separated integers that represent the color in RGB. You can find a great chart here: [Hue Color Chart](http://www.developers.meethue.com/documentation/hue-xy-values)
| `profile` | yes | String with the name of one of the [built-in profiles](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) (relax, energize, concentrate, reading) or one of the custom profiles defined in `light_profiles.csv` in the current working directory. Light profiles define an xy color and a brightness. If a profile is given and a brightness then the profile brightness will be overwritten.
| `hs_color` | yes | A list containing two floats representing the hue and saturation of the color you want the light to be. Hue is scaled 0-360, and saturation is scaled 0-100.
| `xy_color` | yes | A list containing two floats representing the xy color you want the light to be. Two comma-separated floats that represent the color in XY. You can find a great chart here: [Hue Color Chart](https://developers.meethue.com/documentation/core-concepts#color_gets_more_complicated).
| `rgb_color` | yes | A list containing three integers between 0 and 255 representing the RGB color you want the light to be. Three comma-separated integers that represent the color in RGB. Note that the specified RGB value will not change the light brightness, only the color.
| `white_value` | yes | Integer between 0 and 255 for how bright a dedicated white LED should be.
| `color_temp` | yes | An integer in mireds representing the color temperature you want the light to be.
| `kelvin` | yes | Alternatively, you can specify the color temperature in Kelvin.
| `color_name` | yes | A human readable string of a color name, such as `blue` or `goldenrod`. All [CSS3 color names](https://www.w3.org/TR/2010/PR-css3-color-20101028/#svg-color) are supported.
| `color_name` | yes | A human-readable string of a color name, such as `blue` or `goldenrod`. All [CSS3 color names](https://www.w3.org/TR/2010/PR-css3-color-20101028/#svg-color) are supported.
| `brightness` | yes | Integer between 0 and 255 for how bright the color should be.
| `brightness_pct`| yes | Alternatively, you can specify brightness in percent (a number between 0 and 100).
| `flash` | yes | Tell light to flash, can be either value `short` or `long`.
| `effect`| yes | Applies an effect such as `colorloop` or `random`.
<p class='note'>
In order to apply attributes to an entity you will need to add `data:` to the configuration. See example below
In order to apply attributes to an entity, you will need to add `data:` to the configuration. See example below
</p>
```yaml

99
source/_components/light.xiaomi_miio.markdown
View file

@ -13,9 +13,54 @@ ha_version: 0.53
ha_iot_class: "Local Polling"
---
The `xiaomi_miio` platform allows you to control the state of your Xiaomi Philips LED Ball Lamp, Xiaomi Philips LED Ceiling Lamp and Xiaomi Philips Eyecare Lamp 2.
The `xiaomi_miio` platform allows you to control the state of your Xiaomi Philips LED Ball Lamp, Xiaomi Philips Zhirui LED Bulb E14 Candle Lamp, Xiaomi Philips LED Ceiling Lamp and Xiaomi Philips Eyecare Lamp 2.
Currently, the supported features are `on`, `off`, `set_cct` (colortemp) , `set_bright` (brightness).
## Features
### Philips LED Ball Lamp and Philips Zhirui LED Candle Lamp
* Power (on, off)
* Brightness
* Color temperature (175...333 mireds)
* Scene (1, 2, 3, 4)
* Delayed turn off (Resolution in seconds)
* Attributes
- model
- scene
- delayed_turn_off
### Philips LED Ceiling Lamp
* Power (on, off)
* Brightness
* Color temperature (175...370 mireds)
* Scene (1, 2, 3, 4)
* Night light mode (on, off)
* Delayed turn off (Resolution in seconds)
* Attributes
- model
- scene
- delayed_turn_off
- night_light_mode
- automatic_color_temperature
### Philips Eyecare Smart Lamp 2
* Eyecare light (on, off)
* Ambient light (on, off)
* Brightness (of each light)
* Scene (1, 2, 3, 4)
* Night light mode (on, off)
* Delayed turn off (Resolution in seconds)
* Eye fatigue reminder / notification (on, off)
* Eyecare mode (on, off)
* Attributes
- model
- scene
- delayed_turn_off
- night_light_mode
- reminder
- eyecare_mode
Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
@ -35,7 +80,7 @@ Configuration variables:
- **host** (*Required*): The IP of your light.
- **token** (*Required*): The API token of your light.
- **name** (*Optional*): The name of your light.
- **model** (*Optional*): The model of your light. Valid values are `philips.light.bulb`, `philips.light.sread1`, `philips.light.ceiling` and `philips.light.zyceiling`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available.
- **model** (*Optional*): The model of your light. Valid values are `philips.light.bulb`, `philips.light.candle2`, `philips.light.sread1`, `philips.light.ceiling` and `philips.light.zyceiling`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available.
{% configuration %}
host:
@ -76,3 +121,51 @@ Delayed turn off.
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
| `time_period` | no | Time period for the delayed turn off. |
### {% linkable_title Service `light.xiaomi_miio_reminder_on` %} (Eyecare Smart Lamp 2 only)
Enable the eye fatigue reminder/notification.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
### {% linkable_title Service `light.xiaomi_miio_reminder_off` %} (Eyecare Smart Lamp 2 only)
Disable the eye fatigue reminder/notification.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
### {% linkable_title Service `light.xiaomi_miio_night_light_mode_on` %} (Eyecare Smart Lamp 2 only)
Turn the smart night light mode on.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
### {% linkable_title Service `light.xiaomi_miio_night_light_mode_off` %} (Eyecare Smart Lamp 2 only)
Turn the smart night light mode off.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
### {% linkable_title Service `light.xiaomi_miio_eyecare_mode_on` %} (Eyecare Smart Lamp 2 only)
Turn the eyecare mode on.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |
### {% linkable_title Service `light.xiaomi_miio_eyecare_mode_off` %} (Eyecare Smart Lamp 2 only)
Turn the eyecare mode off.
| Service data attribute | Optional | Description |
|---------------------------|----------|-------------------------------------------------------|
| `entity_id` | yes | Only act on a specific light. Else targets all. |

20
source/_components/lock.bmw_connected_drive.markdown Executable file
View file

@ -0,0 +1,20 @@
---
layout: page
title: "BMW connected drive"
description: "Instructions on how to setup your BMW connected drive account with Home Assistant."
date: 2018-02-22 23:00
sidebar: true
comments: false
sharing: true
footer: true
logo: bmw.png
ha_category: Lock
ha_release: 0.66
---
The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant.
The lock will be automatically configured if 'bmw_connected_drive' component is configured.
For more configuration information see the [bmw_connected_drive component](/components/bmw_connected_drive/) documentation.

19
source/_components/lock.homematic.markdown Normal file
View file

@ -0,0 +1,19 @@
---
layout: page
title: "Homematic Lock"
description: "Instructions on how to integrate Homematic locks within Home Assistant."
date: 2016-06-28 08:30
sidebar: true
comments: false
sharing: true
footer: true
logo: homematic.png
ha_category: Lock
ha_release: 0.66
ha_iot_class: "Local Push"
---
The `homematic` lock platform lets you control [Homematic](http://www.homematic.com/) locks through Home Assistant.
Devices will be configured automatically. Please refer to the [component](/components/homematic/) configuration on how to setup Homematic.

1
source/_components/media_player.philips_js.markdown
View file

@ -30,3 +30,4 @@ Configuration variables:
- **host** (*Required*): IP address of TV.
- **name** (*Optional*): The name you would like to give to the Philips TV.
- **turn_on_action** (*Optional*): A script that will be executed to turn on the TV (can be used with wol).
- **api_version** (*Optional*): The JointSpace API version of your Philips TV, defaults to `1`. This is an experimental option and not all the functionalities are guaranteed to work with API versions different from `1`.

4
source/_components/media_player.plex.markdown
View file

@ -69,6 +69,8 @@ media_player:
show_all_controls: false
use_custom_entity_ids: true
use_episode_art: true
remove_unavailable_clients: true
client_remove_interval: 600
```
- **entity_namespace** (*Optional*): Prefix for entity ID's. Defaults to `null`. Useful when using overlapping components (ex. Apple TV and Plex components when you have Apple TV's you use as Plex clients). Go from _media_player.playroom2_ to _media_player.plex_playroom_
- **include_non_clients** (*Optional*): Display non-recontrollable clients (ex. remote clients, PlexConnect Apple TV's). Defaults to `false`.
@ -76,6 +78,8 @@ media_player:
- **show_all_controls** (*Optional*): Forces all controls to display. Defaults to `false`. Ignores dynamic controls (ex. show volume controls for client A but not for client B) based on detected client capabilities. This option allows you to override this detection if you suspect it to be incorrect.
- **use_custom_entity_ids** (*Optional*): Name Entity ID's by client ID's instead of friendly names. Defaults to `false`. HA assigns entity ID's on a first come first serve basis. When you have identically named devices connecting (ex. media_player.plex_web_safari, media_player.plex_web_safari2), you can't reliably distinguish and or predict which device is which. This option avoids this issue by using unique client ID's (ex. media_player.dy4hdna2drhn).
- **use_episode_art** (*Optional*): Display TV episode art instead of TV show art. Defaults to `false`.
- **remove_unavailable_clients** (*Optional*): Remove stale plex clients from UI after interval. Defaults to `true`.
- **client_remove_interval** (*Optional*): How long a client is to be unavailable for before it is cleaned up. Defaults to `600 seconds (10min)`.
### {% linkable_title Service `play_media` %}

63
source/_components/notify.stride.markdown Normal file
View file

@ -0,0 +1,63 @@
---
layout: page
title: "Stride"
description: "Instructions how to add Stride notifications to Home Assistant."
date: 2018-03-14 15:00
sidebar: true
comments: false
sharing: true
footer: true
logo: stride.png
ha_category: Notifications
ha_release: 0.66
---
The `stride` platform allows you to send notifications from Home Assistant to [Stride](https://stride.com/).
You need to obtain a [Stride API token](https://developer.atlassian.com/cloud/stride/security/authentication/#using-room-tokens) to be able to send notifications. When creating the token, you'll see a section labeled "Use this conversation URL to post messages" - it will look something like "https://api.atlassian.com/site/55872e9f-047e-a619-b32c-19d37fbc6038/conversation/26c98c26-0ffd-a11e-3a55-1b397cb71fe0/message". The first set of numbers and letters (`55872e9f-047e-a619-b32c-19d37fbc6038`) is the Cloud ID, and the second set (`26c98c26-0ffd-a11e-3a55-1b397cb71fe0`) is the Room ID.
To enable the Stride notification in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- platform: stride
cloudid: CLOUD-ID
token: TOKEN
room: ROOM-ID
```
{% configuration %}
name:
description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`.
required: false
default: notify
type: string
cloudid:
description: The Stride Cloud ID to use for sending Stride notification.
required: true
type: string
token:
description: The Stride API token to use for sending Stride notifications.
required: true
type: string
room:
description: The default room to post to if no room is explicitly specified when sending the notification.
required: true
type: string
panel:
description: Setting panel will override the default panel type (`None`) for the notification. By default not setting this will post to Stride without using a panel type. Valid options are 'None', 'info', 'note', 'tip', 'warning'.
required: false
type: string
{% endconfiguration %}
### {% linkable_title Stride service data %}
The following attributes can be placed `data` for extended functionality.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `room` | yes | (int) Same usage as in configuration.yaml. Overrides any setting set in configuration.yaml.
| `panel` | yes | (str) Same usage as in configuration.yaml. Overrides any setting set in configuration.yaml.
To use notifications, please see the [getting started with automation page](/getting-started/automation/).

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

@ -41,6 +41,46 @@ Configuration variables:
- **api_key** (*Required*): Your API key.
- **name** (*Optional*): Additional name for the sensors. Default to platform name.
- **forecast** array (*Optional*): List of days in the 7 day forecast you would like to receive data on, starting with tomorrow as day 1. Any `monitored_condition` with a daily forecast by DarkSky will generate a sensor tagged with `_<day>`.
- **language** (*Optional*): The desired language of the summary properties. Valid options are
- `ar`: Arabic
- `az`: Azerbaijani
- `be`: Belarusian
- `bg`: Bulgarian
- `bs`: Bosnian
- `ca`: Catalan
- `cs`: Czech
- `da`: Danish
- `de`: German
- `el`: Greek
- `en`: English (which is the default)
- `es`: Spanish
- `et`: Estonian
- `fi`: Finnish
- `fr`: French
- `hr`: Croatian
- `hu`: Hungarian
- `id`: Indonesian
- `is`: Icelandic
- `it`: Italian
- `ja`: Japanese
- `ka`: Georgian
- `kw`: Cornish
- `nb`: Norwegian Bokmål
- `nl`: Dutch
- `pl`: Polish
- `pt`: Portuguese
- `ro`: Romanian
- `ru`: Russian
- `sk`: Slovak
- `sl`: Slovenian
- `sr`: Serbian
- `sv`: Swedish
- `tet`: Tetum
- `tr`: Turkish
- `uk`: Ukrainian
- `x-pig-latin`: Igpay Atinlay
- `zh`: simplified Chinese
- `zh-tw`: traditional Chinese
- **latitude** (*Optional*): Latitude coordinate to monitor weather of (required if **longitude** is specified), defaults to coordinates defined in your `configuration.yaml`
- **longitude** (*Optional*): Longitude coordinate to monitor weather of (required if **latitude** is specified), defaults to coordinates defined in your `configuration.yaml`
- **monitored_conditions** array (*Required*): Conditions to display in the frontend.

42
source/_components/sensor.filter.markdown
View file

@ -15,7 +15,7 @@ logo: home-assistant.png
The `filter` platform enables sensors that process the states of other entities.
`filter` applies a signal processing algorithm to a sensor, previous and current states, and generates a `new state` given the chosen algorithm.
`filter` applies a signal processing algorithm to a sensor, previous and current states, and generates a `new state` given the chosen algorithm. The next image depicts an original sensor and the filter sensor of that same sensor using the [History Graph]({{site_roor}}/components/history_graph/) component.
<p class='img'>
<img src='{{site_root}}/images/screenshots/filter-sensor.png' />
@ -37,6 +37,18 @@ sensor:
- filter: lowpass
time_constant: 10
precision: 2
- platform: filter
name: "filtered realistic temperature"
entity_id: sensor.realistic_temperature
filters:
- filter: outlier
window_size: 4
radius: 2.0
- filter: lowpass
time_constant: 10
- filter: time_simple_moving_average
window_size: 00:05
precision: 2
```
Filters can be chained and are applied according to the order present in the configuration file.
@ -53,17 +65,17 @@ name:
filters:
description: Filters to be used.
required: true
type: map
type: list
keys:
filter:
description: Algorithm to be used to filter data. Available filters are `lowpass`, `outlier` and `throttle`.
description: Algorithm to be used to filter data. Available filters are `lowpass`, `outlier`, `throttle` and `time_simple_moving_average`.
required: true
type: string
window_size:
description: Size of the window of previous states.
description: Size of the window of previous states. Time based filters such as `time_simple_moving_average` will require a time period (size in time), while other filters such as `outlier` will require an integer (size in number of states)
required: false
type: int
default: 5
type: [int, time]
default: 1
precision:
description: See [_lowpass_](#low-pass) filter. Defines the precision of the filtered state, through the argument of round().
required: false
@ -78,16 +90,21 @@ filters:
description: See [_outlier_](#outlier) filter. Band radius from median of previous states.
required: false
type: float
default: 2.0
default: 2.0
type:
description: See [_time_simple_moving_average_](#time-simple-moving-average) filter. Defines the type of Simple Moving Average.
required: false
type: string
default: last
{% endconfiguration %}
## {% linkable_title Filters %}
### {% linkable_title Low-pass %}
The Low-pass filter (`lowpass`) is one of signal processing most common filters, as it smooths data by shortcuting peaks and valleys.
The Low-pass filter (`lowpass`) is one of signal processing most common filters, as it smooths data by shortcutting peaks and valleys.
The included Low-pass filter is very basic and is based on a moving average, in which the previous data point is weighted with the new data point.
The included Low-pass filter is very basic and is based on [exponential smoothing](https://en.wikipedia.org/wiki/Exponential_smoothing), in which the previous data point is weighted with the new data point.
```python
B = 1.0 / time_constant
@ -120,3 +137,10 @@ To adjust the rate you need to set the window_size. To throttle a sensor down to
This filter is relevant when you have a sensor which produces states at a very high-rate, which you might want to throttle down for storing or visualization purposes.
### {% linkable_title Time Simple Moving Average %}
The Time SMA filter (`time_simple_moving_average`) is based on the paper [Algorithms for Unevenly Spaced Time Series: Moving Averages and Other Rolling Operators](http://www.eckner.com/papers/Algorithms%20for%20Unevenly%20Spaced%20Time%20Series.pdf) by Andreas Eckner.
The paper defines three types/versions of the Simple Moving Average (SMA): *last*, *next* and *linear*. Currently only *last* is implemented.
Theta, as described in the paper, is the `window_size` parameter, and can be expressed using time notation (e.g., 00:05 for a five minutes time window).

51
source/_components/sensor.foobot.markdown Normal file
View file

@ -0,0 +1,51 @@
---
layout: page
title: "Foobot Air Quality Monitor"
description: "Instructions on how to setup Foobot Air Quality sensor in Home Assistant."
date: 2018-02-14 06:00
sidebar: true
comments: false
sharing: true
footer: true
logo: foobot.png
ha_category: Health
ha_release: 0.66
ha_iot_class: "Cloud Polling"
---
The `foobot` sensor platform will fetch air quality data from your or yours [Foobot device(s)](https://foobot.io/features/).
This sensor requires an API token. Please obtain one at [Foobot API site](https://api.foobot.io/apidoc/index.html).
## {% linkable_title Configuring the Platform %}
To enable this sensor, add the following lines to your `configuration.yaml` file:
```yaml
sensor:
- platform: foobot
token: FOOBOT_SECRET_KEY
username: FOOBOT_USERNAME
```
{% configuration %}
token:
description: The token for the Foobot API.
required: true
type: string
username:
description: Your Foobot username, used to fetch devices associated with an account.
required: true
type: string
{% endconfiguration %}
## {% linkable_title Available Metrics %}
Every ten minutes, it'll fetch the last ten minutes average of the following measurements:
* Temperature
* Humidity
* Co2
* VOC
* PM2.5
* [Index](https://help.foobot.io/hc/en-us/articles/204814371-What-does-central-number-mean-)

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

@ -58,6 +58,9 @@ sensor:
- 'process_thread'
- 'process_sleeping'
- 'cpu_temp'
- 'docker_active'
- 'docker_cpu_use'
- 'docker_memory_use'
```
Configuration variables:
@ -81,5 +84,8 @@ Configuration variables:
- **process_thread**: Number of threads
- **process_sleeping**: Number of sleeping processes
- **cpu_temp**: CPU Temperature (may not available on all platforms)
- **docker_active**: Count of active Docker containers
- **docker_cpu_use**: Total CPU usage in percent of Docker containers
- **docker_memory_use**: Total memory used of Docker containers
Not all platforms are able to provide all metrics. For instance `cpu_temp` is requires installing and configuring `lmsensors` in Ubuntu, and may not be available at all in other platforms.

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

@ -0,0 +1,18 @@
---
layout: page
title: "HomematicIP Sensor"
description: "Instructions on how to integrate Homematic sensors within Home Assistant."
date: 2016-06-28 08:30
sidebar: true
comments: false
sharing: true
footer: true
logo: homematic.png
ha_category: Sensor
ha_release: 0.66
ha_iot_class: "Local Push"
---
The `homematicip` sensor platform lets you control [Homematic](http://www.homematic.com/) sensors through Home Assistant.
Devices will be configured automatically. Please refer to the [component](/components/homematicip/) configuration on how to setup Homematic.

48
source/_components/sensor.spotcrime.markdown
View file

@ -8,13 +8,13 @@ comments: false
sharing: true
footer: true
ha_category: Sensor
ha_release: 0.64
ha_release: 0.65
ha_iot_class: "Cloud Polling"
---
The `spotcrime` sensor allows one to track reported incidents occurring in a given area. Incidents include anything reported to [Spot Crime](http://spotcrime.com). Your regional emergency services may or may not report data. The sensor defaults to counting incidents within one day, but can be customized via configuration.yaml.
## Configuration
You will need to request an API key from [Spotcrime](mailto:pyrrhus@spotcrime.com).
To enable this sensor, add the following lines to your `configuration.yaml`. Your `radius` should be of sufficient size to capture incidents in your area. 0.01 = 1 mile.
@ -23,23 +23,39 @@ sensor:
- platform: spotcrime
name: <any name>
radius: <your radius>
days: <your days>
api_key: <"your_api_key_here">
```
Configuration options for the Crime Reports Sensor:
{% configuration %}
name:
description: Name the sensor what you'd like.
required: true
type: string
radius:
description: Radius you'd like to search within. 0.01 = 1 mile.
required: true
type: float
api_key:
description: The API key to access the service.
required: true
type: string
days:
description: Number of days you'd like see to crime statistics for.
required: false
type: int
include:
description: Event types you want statistics for.
required: false
type: list
exclude:
description: Event types to ignore statistics for.
required: false
type: list
{% endconfiguration %}
- **name** (*Required*): Name the sensor whatever you want.
- **radius** (*Required*): Radius in miles.
- **days** (*Optional*): Defaults to 1 day.
- **latitude** (*Optional*): Defaults to your home zone latitude.
- **longitude** (*Optional*): Defaults to your home zone longitude.
- **include** (*Optional*): List of incident types to include.
- **exclude** (*Optional*): List of incident types to exclude.
## {% linkable_title Notes %}
## Notes
### Incident Types
### {% linkable_title Incident Types %}
You can explicitly include or exclude incident types. Specifying `include`s restricts the incidents to those types. Specifying `exclude`s will return all incident types except those specified.
@ -55,6 +71,6 @@ These incident types are available:
- Vandalism
- Other
### Events
### {% linkable_title Events %}
The `crimealerts` sensor fires a `crimealerts_incident` event when a new incident is detected, including the type, time, and location of the incident.

89
source/_components/sensor.syncthru.markdown Normal file
View file

@ -0,0 +1,89 @@
---
layout: page
title: "Samsung SyncThru Printer"
description: "Instructions on how to integrate a Samsung printer providing SyncThru within Home Assistant."
date: 2018-02-19 23:33
sidebar: true
comments: false
sharing: true
footer: true
logo: samsung.png
ha_category: Sensor
ha_iot_class: "Local Polling"
ha_release: 0.66
---
The Samsung SyncThru Printer platform allows you to read current data from your local Samsung printer.
It usually provides information about the device's state, the left amount of ink or toner and the state of paper trays.
The platform automatically monitors every supported part.
If you wish not to include certain monitored values specify the values that you would like to see in the front-end via the `monitored_conditions` setting.
```yaml
# Example configuration.yaml entry
sensor:
- platform: syncthru
resource: http://my-printer.address
name: My Awesome Printer
monitored_conditions:
- toner_black
- output_tray_0
```
{% configuration %}
resource:
description: The address for connecting to the printer. Equal to the SyncThru Webservice address.
required: true
default: false
type: url
name:
description: A user specified name for the printer. Defaults to "Samsung Printer" and the friendly name will be the name of the printer model.
required: false
default: Samsung Printer
type: string
monitored_conditions:
description: Conditions to display in the frontend.
required: false
default: all values
type: list
keys:
toner_black:
description: Black toner fill level
toner_cyan:
description: Cyan toner fill level
toner_magenta:
description: Magenta toner fill level
toner_yellow:
description: Yellow toner fill level
drum_black:
description: Black drum state
drum_cyan:
description: Cyan drum state
drum_magenta:
description: Magenta drum state
drum_yellow:
description: Yellow drum state
tray_1:
description: First paper input tray state
tray_2:
description: Second paper input tray state
tray_3:
description: Third paper input tray state
tray_4:
description: Fourth paper input tray state
tray_5:
description: Fifth paper input tray state
output_tray_0:
description: First paper output tray state
output_tray_1:
description: Second paper output tray state
output_tray_2:
description: Third paper output tray state
output_tray_3:
description: Fourth paper output tray state
output_tray_4:
description: Fifth paper output tray state
output_tray_5:
description: Sixth paper output tray state
{% endconfiguration %}

29
source/_components/sensor.tibber.markdown
View file

@ -13,7 +13,6 @@ ha_release: 0.55
ha_iot_class: "Cloud Polling"
---
The `tibber` sensor provides the current electricity price if you are a [Tibber](https://tibber.com/) customer.
To add Tibber to your installation, add the following to your `configuration.yaml` file:
@ -31,3 +30,31 @@ sensor:
required: true
type: string
{% endconfiguration %}
## {% linkable_title Examples %}
In this section, you will find some real-life examples of how to use this sensor.
### {% linkable_title Electricity price %}
The electricity price can be used to make automations. The sensor has a `max_price` and `min_price` attribute, with max and min price for the current day. Here is an example to get a notification when the price is above 90% of the maximum price for the day:
{% raw %}
```yaml
- alias: "Electricity price"
trigger:
platform: time
# Matches every hour at 1 minutes past whole
minutes: 1
seconds: 00
condition:
condition: template
value_template: '{{ float(states.sensor.electricity_price_hamretunet_10.state) > 0.9 * float(states.sensor.electricity_price_hamretunet_10.attributes.max_price) }}'
action:
- service: notify.pushbullet
data:
title: "Electricity price"
target: "device/daniel_telefon_cat"
message: "The electricity price is now {{ states.sensor.electricity_price_hamretunet_10.state }}"
```
{% endraw %}

86
source/_components/sensor.trafikverket_weatherstation.markdown Normal file
View file

@ -0,0 +1,86 @@
---
layout: page
title: "Trafikverket WeatherStation"
description: "Instructions how to integrate Trafikverket WeatherStation within Home Assistant."
date: 2018-02-01 12:06
sidebar: true
comments: false
sharing: true
footer: true
logo: trafikverket.png
ha_category: Sensor
ha_release: 0.66.0
---
Showing weather information for air and road temperature provided by [Trafikverket](https://www.trafikverket.se/) in Sweden.
Potential use cases:
- Get weather data in general
- You live near a weather station and want to know the current temperature at home
- Setup automations for your car heating system. If the road is frozen along the way to work, you might want the car heating system to start earlier.
##### {% linkable_title Configuration %}
To enable this sensor, add the following lines to your `configuration.yaml`.
```yaml
sensor:
- platform: trafikverket_weatherstations
name: Trafikverket Road WeatherStation Kungälv
api_key: eXXcbXXXacXXXXc39XX3aXXX4aXX46XX
station: Kungälv
type: road
```
{% configuration %}
name:
description: Unique name of the device in the frontend.
required: true
type: string
api_key:
description: API key from Trafikverket.
required: true
type: string
station:
description: Name of the weather station.
required: true
type: string
type:
description: Defines which temperature you want (`air` or `road`).
required: true
type: string
scan_interval:
description: How frequently to query for new data (in seconds).
required: false
type: int
default: 300
{% endconfiguration %}
##### {% linkable_title Obtaining API key %}
Please click [here](https://api.trafikinfo.trafikverket.se/) and register to obtain the API key.
##### {% linkable_title Weather stations %}
Click [here](https://www.trafikverket.se/trafikinformation/vag/?TrafficType=personalTraffic&map=1/606442.17/6886316.22/&Layers=RoadWeather%2b) to get a map of valid weather stations. Once a station is found, copy the name according to the below picture and paste it in your `configuration.yaml` file as the `station` variable.
<p class='img'>
<img src='{{site_root}}/images/screenshots/get_trafikverket_weather_station_example.png' />
</p>
##### {% linkable_title Examples %}
```yaml
sensor:
- platform: trafikverket_weatherstations
name: Trafikverket Road WeatherStation Kungälv
api_key: eXXcbXXXacXXXXc39XX3aXXX4aXX46XX
station: Kungälv
type: road
- platform: trafikverket_weatherstations
name: Trafikverket Air WeatherStation Lanna
api_key: eXXcbXXXacXXXXc39XX3aXXX4aXX46XX
station: Lanna
type: air
scan_interval: 600
```

7
source/_components/sensor.vasttrafik.markdown
View file

@ -13,7 +13,6 @@ ha_iot_class: "Cloud Polling"
ha_release: "0.30"
---
The `vasttrafik` sensor will provide you traveling details for the larger Göteborg area in Sweden from the [Västtrafik](https://vasttrafik.se/) public transportation service.
You must create an application [here](https://developer.vasttrafik.se/portal/#/applications) to obtain a `key` and a `secret`.
@ -34,10 +33,11 @@ Configuration variables:
- **key** (*Required*): The API key to access your Västtrafik account.
- **secret** (*Required*): The API secret to access your Västtrafik account.
- **departures** array (*Required*): List of traveling routes.
- **departures** array (*Required*): List of travel routes.
- **name** (*Optional*): Name of the route.
- **from** (*Required*): The start station.
- **heading** (*Optional*): Direction of the traveling.
- **lines** (*Optional*): Only consider these lines.
- **delay** (*Optional*): Delay in minutes. Defaults to 0.
The data are coming from [Västtrafik](https://vasttrafik.se/).
@ -54,5 +54,8 @@ sensor:
- name: Mot järntorget
from: Musikvägen
heading: Järntorget
lines:
- 7
- GRÖN
delay: 10
```

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

@ -0,0 +1,55 @@
---
layout: page
title: "Xiaomi Air Quality Monitor"
description: "Instructions how to integrate your Xiaomi Mi Air Quality Monitor within Home Assistant."
date: 2018-02-28 08:35
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Sensor
ha_version: 0.66
ha_iot_class: "Local Polling"
---
The `xiaomi_miio` sensor platform is observing your Xiaomi Mi Air Quality Monitor (PM2.5) and reporting the air quality index.
Currently, the supported features are:
* Air Quality Index (AQI)
* Attributes
- power
- charging
- battery
- time_stat
Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token.
To add a Xiaomi Mi Air Quality Monitor to your installation, add the following to your `configuration.yaml` file:
```yaml
sensor:
# Example configuration.yaml entry
sensor:
- platform: xiaomi_miio
name: Xiaomi Air Quality Monitor
host: 192.168.130.73
token: YOUR_TOKEN
```
{% configuration %}
host:
description: The IP address of your miio device.
required: true
type: string
token:
description: The API token of your miio device.
required: true
type: string
name:
description: The name of your miio device.
required: false
type: string
default: Xiaomi Miio Sensor
{% endconfiguration %}

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

@ -0,0 +1,36 @@
---
layout: page
title: "VeSync Switch"
description: "Instructions on how to set up Etekcity VeSync switches within Home Assistant."
date: 2018-03-09 02:11
sidebar: true
comments: false
sharing: true
footer: true
logo: vesync.png
ha_category: Switch
ha_release: 0.66
---
The `vesync` switch platform enabled integration with Etekcity VeSync smart switches.
To use your VeSync switches, you must first register your switches with the VeSync app. Once registration is complete you must add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
switch:
- platform: vesync
username: username
password: password
```
{% configuration %}
username:
description: Username needed to log in to VeSync.
required: true
type: string
password:
description: Password needed to log in to VeSync.
required: true
type: string
{% endconfiguration %}

70
source/_components/switch.xiaomi_miio.markdown
View file

@ -13,12 +13,38 @@ 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.
The `xiaomi_miio` switch platform allows you to control the state of your Xiaomi Smart WiFi Socket aka Plug, Xiaomi Smart Power Strip and Xiaomi Chuangmi Plug V1.
Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file.
## Features
### Xiaomi Smart WiFi Socket
* Power (on, off)
* Attributes
- Temperature
### Xiaomi Chuangmi Plug V1
* Power (on, off)
* USB (on, off)
* Attributes
- Temperature
### Xiaomi Smart Power Strip
* Power (on, off)
* Wifi LED (on, off)
* Power Price (0...999)
* Power Mode (green, normal) (Power Strip V1 only)
* Attributes
- Temperature
- Current
- Load power
- Wifi LED
- Mode (Power Strip V1 only)
To add a plug to your installation, add the following to your `configuration.yaml` file:
```yaml
@ -35,7 +61,7 @@ Configuration variables:
- **host** (*Required*): The IP of your miio device.
- **token** (*Required*): The API token of your miio device.
- **name** (*Optional*): The name of your miio device.
- **model** (*Optional*): The model of your miio device. Valid values are chuangmi.plug.v1`, `qmi.powerstrip.v1`, `zimi.powerstrip.v2`, `chuangmi.plug.m1` and `chuangmi.plug.v2`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available.
- **model** (*Optional*): The model of your miio device. Valid values are `chuangmi.plug.v1`, `qmi.powerstrip.v1`, `zimi.powerstrip.v2`, `chuangmi.plug.m1` and `chuangmi.plug.v2`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available.
{% configuration %}
host:
@ -56,3 +82,39 @@ model:
required: false
type: string
{% endconfiguration %}
## {% linkable_title Platform Services %}
### {% linkable_title Service `switch.xiaomi_miio_set_wifi_led_on` %} (Power Strip only)
Turn the wifi led on.
| Service data attribute | Optional | Description |
|---------------------------|----------|---------------------------------------------------------|
| `entity_id` | yes | Only act on a specific xiaomi miio switch entity. Else targets all. |
### {% linkable_title Service `switch.xiaomi_miio_set_wifi_led_off` %} (Power Strip only)
Turn the wifi led off.
| Service data attribute | Optional | Description |
|---------------------------|----------|---------------------------------------------------------|
| `entity_id` | yes | Only act on a specific xiaomi miio switch entity. Else targets all. |
### {% linkable_title Service `switch.xiaomi_miio_set_power_price` %} (Power Strip)
Set the power price.
| Service data attribute | Optional | Description |
|---------------------------|----------|---------------------------------------------------------|
| `entity_id` | yes | Only act on a specific xiaomi miio switch entity. Else targets all. |
| `price` | no | Power price, between 0 and 999. |
### {% linkable_title Service `switch.xiaomi_miio_set_power_mode` %} (Power Strip V1 only)
Set the power mode.
| Service data attribute | Optional | Description |
|---------------------------|----------|---------------------------------------------------------------|
| `entity_id` | yes | Only act on a specific xiaomi miio switch entity. Else targets all. |
| `mode` | no | Power mode, valid values are 'normal' and 'green' |

98
source/_components/telegram_bot.markdown
View file

@ -19,10 +19,12 @@ This component creates notification services to send, or edit previously sent, m
If you don't need to receive messages, you can use the [broadcast](/components/telegram_bot.broadcast/) platform instead.
### {% linkable_title Notification services %}
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `edit_message`, `edit_replymarkup`, `edit_caption`, `answer_callback_query`.
## {% linkable_title Notification services %}
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `send_sticker`, `edit_message`, `edit_replymarkup`, `edit_caption` and `answer_callback_query`.
### {% linkable_title Service `telegram_bot.send_message` %}
#### {% linkable_title Service `telegram_bot/send_message` %}
Send a notification.
| Service data attribute | Optional | Description |
@ -36,7 +38,8 @@ Send a notification.
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_photo` %}
### {% linkable_title Service `telegram_bot.send_photo` and `telegram_bot.send_sticker` %}
Send a photo.
| Service data attribute | Optional | Description |
@ -44,16 +47,16 @@ Send a photo.
| `url` | no | Remote path to an image. |
| `file` | no | Local path to an image. |
| `caption` | yes | The title of the image. |
| `username` | yes | Username for a URL which require HTTP basic authentication. |
| `password` | yes | Password for a URL which require HTTP basic authentication. |
| `username` | yes | Username for a URL which requires HTTP basic authentication. |
| `password` | yes | Password for a URL which requires HTTP basic authentication. |
| `authentication` | yes | Define which authentication method to use. Set to `digest` to use HTTP digest authentication. Defaults to `basic`. |
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed chat_id. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
### {% linkable_title Service `telegram_bot.send_video` %}
#### {% linkable_title Service `telegram_bot/send_video` %}
Send a video.
| Service data attribute | Optional | Description |
@ -69,7 +72,8 @@ Send a video.
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_document` %}
### {% linkable_title Service `telegram_bot.send_document` %}
Send a document.
| Service data attribute | Optional | Description |
@ -77,15 +81,16 @@ Send a document.
| `url` | no | Remote path to a document. |
| `file` | no | Local path to a document. |
| `caption` | yes | The title of the document. |
| `username` | yes | Username for a URL which require HTTP basic authentication. |
| `password` | yes | Password for a URL which require HTTP basic authentication. |
| `username` | yes | Username for a URL which requires HTTP basic authentication. |
| `password` | yes | Password for a URL which requires HTTP basic authentication. |
| `authentication` | yes | Define which authentication method to use. Set to `digest` to use HTTP digest authentication. Defaults to `basic`. |
| `target` | yes | An array of pre-authorized chat_ids or user_ids to send the notification to. Defaults to the first allowed chat_id. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_location` %}
### {% linkable_title Service `telegram_bot.send_location` %}
Send a location.
| Service data attribute | Optional | Description |
@ -97,7 +102,8 @@ Send a location.
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_message` %}
### {% linkable_title Service `telegram_bot.edit_message` %}
Edit a previously sent message in a conversation.
| Service data attribute | Optional | Description |
@ -110,7 +116,8 @@ Edit a previously sent message in a conversation.
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_caption` %}
### {% linkable_title Service `telegram_bot.edit_caption` %}
Edit the caption of a previously sent message.
| Service data attribute | Optional | Description |
@ -121,8 +128,9 @@ Edit the caption of a previously sent message.
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_replymarkup` %}
Edit the inline keyboard of a previusly sent message.
### {% linkable_title Service `telegram_bot.edit_replymarkup` %}
Edit the inline keyboard of a previously sent message.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
@ -131,7 +139,8 @@ Edit the inline keyboard of a previusly sent message.
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with associated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/answer_callback_query` %}
### {% linkable_title Service `telegram_bot.answer_callback_query` %}
Respond to a callback query originated by clicking on an online keyboard button. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.
| Service data attribute | Optional | Description |
@ -140,7 +149,7 @@ Respond to a callback query originated by clicking on an online keyboard button.
| `callback_query_id` | no | Unique id of the callback response. In the `telegram_callback` event data: `{{ trigger.event.data.id }}` |
| `show_alert` | yes | True/false for show a permanent notification. Defaults to False. |
#### {% linkable_title Service `telegram_bot/delete_message` %}
### {% linkable_title Service `telegram_bot.delete_message` %}
Delete a previously sent message in a conversation.
| Service data attribute | Optional | Description |
@ -148,12 +157,12 @@ Delete a previously sent message in a conversation.
| `message_id` | no | Id of the message to delete. When answering a callback from a pressed button, the id of the origin message is in: `{{ trigger.event.data.message.message_id }}`. You can use `"last"` to refer to the last message sent to `chat_id`. |
| `chat_id` | no | The chat_id where to delete the message. |
### {% linkable_title `Telegram` notification platform %}
## {% linkable_title `telegram` notification platform %}
The [Telegram notification platform](/components/notify.telegram/) requires the `telegram_bot` component to work with, and it's designed to generate a customized shortcut (`notify.USERNAME`) to send notifications (messages, photos, documents and locations) to a particular `chat_id` with the old syntax, allowing backward compatibility.
The [`telegram` notification platform](/components/notify.telegram/) requires the `telegram_bot` component to work with, and it's designed to generate a customized shortcut (`notify.USERNAME`) to send notifications (messages, photos, documents and locations) to a particular `chat_id` with the old syntax, allowing backward compatibility.
The required yaml configuration now reduces to:
```yaml
notify:
- name: NOTIFIER_NAME
@ -161,8 +170,7 @@ notify:
chat_id: USER_CHAT_ID
```
### {% linkable_title Event triggering %}
## {% linkable_title Event triggering %}
A command looks like `/thecommand`, or `/othercommand with some args`.
@ -189,7 +197,7 @@ chat_id: "<origin chat id>"
chat: "<chat info>"
```
if the message is sent from a [press from an inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and Home Assistant will fire a `telegram_callback` event with:
If the message is sent from a [press from an inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and Home Assistant will fire a `telegram_callback` event with:
```yaml
data: "<data associated to action callback>"
@ -204,7 +212,6 @@ chat_id: "<origin chat id>"
### {% linkable_title Configuration samples %}
Simple ping pong example.
```yaml
@ -221,7 +228,7 @@ action:
message: 'pong'
```
Example that show keyboard interaction with `notify.telegram`
An example that shows keyboard interaction with `notify.telegram`
```yaml
trigger:
@ -256,8 +263,9 @@ action:
entity_id: switch.vision_zm1601eu5_battery_operated_siren_switch_9_0
```
An example to show the use of event_data in the action:
An example to show the use of event_data in action:
{% raw %}
```yaml
- alias: 'Kitchen Telegram Speak'
trigger:
@ -269,17 +277,21 @@ An example to show the use of event_data in the action:
- service: notify.kitchen_echo
data_template:
message: >
Message from {% raw %}{{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}{% endraw %}
Message from {{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}
```
{% endraw %}
### {% linkable_title Sample automations with callback queries and inline keyboards %}
Quick example to show some of the callback capabilities of inline keyboards with a dumb automation consisting in a simple repeater of normal text that presents an inline keyboard with 3 buttons: 'EDIT', 'NO' and 'REMOVE BUTTON':
A quick example to show some of the callback capabilities of inline keyboards with a dumb automation consisting in a simple repeater of normal text that presents an inline keyboard with 3 buttons: 'EDIT', 'NO' and 'REMOVE BUTTON':
- Pressing 'EDIT' changes the sent message.
- Pressing 'NO' only shows a brief notification (answering the callback query).
- Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button.
Text repeater:
{% raw %}
```yaml
- alias: 'Telegram bot that repeats text'
hide_entity: true
@ -290,15 +302,18 @@ Text repeater:
- service: telegram_bot.send_message
data_template:
title: '*Dumb automation*'
target: {% raw %}'{{ trigger.event.data.user_id }}'{% endraw %}
message: 'You said: {% raw %}{{ trigger.event.data.text }}{% endraw %}'
target: '{{ trigger.event.data.user_id }}'
message: 'You said: {{ trigger.event.data.text }}'
disable_notification: true
inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing"
- "Remove this button:/remove button"
```
{% endraw %}
Message editor:
{% raw %}
```yaml
- alias: 'Telegram bot that edits the last sent message'
hide_entity: true
@ -315,19 +330,22 @@ Message editor:
show_alert: true
- service: telegram_bot.edit_message
data_template:
message_id: {% raw %}'{{ trigger.event.data.message.message_id }}'{% endraw %}
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %}
message_id: '{{ trigger.event.data.message.message_id }}'
chat_id: '{{ trigger.event.data.chat_id }}'
title: '*Message edit*'
inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing"
- "Remove this button:/remove button"
message: >
{% raw %}Callback received from {% raw %}{{ trigger.event.data.from_first }}{% endraw %}.
Message id: {% raw %}{{ trigger.event.data.message.message_id }}{% endraw %}.
Data: {% raw %}{{ trigger.event.data.data }}{% endraw %}
Callback received from {{ trigger.event.data.from_first }}.
Message id: {{ trigger.event.data.message.message_id }}.
Data: {{ trigger.event.data.data }}
```
{% endraw %}
Keyboard editor:
{% raw %}
```yaml
- alias: 'Telegram bot that edits the keyboard'
hide_entity: true
@ -339,17 +357,20 @@ Keyboard editor:
action:
- service: telegram_bot.answer_callback_query
data_template:
callback_query_id: {% raw %}'{{ trigger.event.data.id }}'{% endraw %}
callback_query_id: '{{ trigger.event.data.id }}'
message: 'Callback received for editing the inline keyboard!'
- service: telegram_bot.edit_replymarkup
data_template:
message_id: 'last'
chat_id: {% raw %}'{{ trigger.event.data.chat_id }}'{% endraw %}
chat_id: '{{ trigger.event.data.chat_id }}'
inline_keyboard:
- "Edit message:/edit_msg, Don't:/do_nothing"
```
{% endraw %}
Only acknowledges the 'NO' answer:
{% raw %}
```yaml
- alias: 'Telegram bot that simply acknowledges'
hide_entity: true
@ -361,9 +382,10 @@ Only acknowledges the 'NO' answer:
action:
- service: telegram_bot.answer_callback_query
data_template:
callback_query_id: {% raw %}'{{ trigger.event.data.id }}'{% endraw %}
callback_query_id: '{{ trigger.event.data.id }}'
message: 'OK, you said no!'
```
{% endraw %}
For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](/docs/ecosystem/appdaemon/tutorial/) is advised.

1
source/_components/zha.markdown
View file

@ -22,6 +22,7 @@ There is currently support for the following device types within Home Assistant:
- [Sensor](../sensor.zha) (e.g., temperature sensors)
- [Light](../light.zha)
- [Switch](../switch.zha)
- [Fan](../fan.zha)
Known working ZigBee radios: