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

Merge branch 'current' into next

Browse source
This commit is contained in:
Fabian Affolter 2017-06-03 09:37:04 +02:00
commit 89237a4b2a
No known key found for this signature in database
GPG key ID: E23CD2DD36A4397F
58 changed files with 652 additions and 360 deletions
Download patch file Download diff file Expand all files Collapse all files

6
source/_components/alarm_control_panel.mqtt.markdown
View file

@ -29,9 +29,9 @@ To enable this platform, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
alarm_control_panel:
platform: mqtt
state_topic: "home/alarm"
command_topic: "home/alarm/set"
- platform: mqtt
state_topic: "home/alarm"
command_topic: "home/alarm/set"
```
Configuration variables:

10
source/_components/apiai.markdown
View file

@ -42,16 +42,16 @@ To use this integration you should define a conversation (intent) in Api.ai, con
- Select name, language (if you are planning to use it with Google Actions check [here](https://support.google.com/assistant/answer/7108196?hl=en) supported languages) and time zone
- Click "Save"
- Go to "Fullfiment" (in the left menu)
- Enable Webhook and set your HA url with the apiai endpoint. Eg.: ``https://myhome.duckdns.org/api/apiai?api_password=HA_PASSWORD``
- Enable Webhook and set your Home Assistant URL with the Api.ai endpoint. Eg.: ``https://myhome.duckdns.org/api/apiai?api_password=HA_PASSWORD``
- Click "Save"
- Create a new intent
- Below "User says" write one phrase that you, the user, will tell Api.ai. Eg.: Which is the temperature at home?
- In "Action" set some key (this will be the bind with HA config), eg.: GetTemperature
- In "Response" set "Cannot connect to HA or it is taking to long" (fall back response)
- In "Action" set some key (this will be the bind with Home Assistant configuration), eg.: GetTemperature
- In "Response" set "Cannot connect to Home Assistant or it is taking to long" (fall back response)
- At the end of the page, click on "Fulfillment" and check "Use webhook"
- Click "Save"
- On the top right, where is written "Try it now...", write, or say, the phrase you have previously defined and hit enter
- Api.ai has send a request to your HA server
- Api.ai has send a request to your Home Assistant server
Take a look to "Integrations", in the left menu, to configure third parties.
@ -85,7 +85,7 @@ apiai:
Inside an intent we can define this variables:
- **speech** (*Optional*): Text or template to return to Api.ai
- **action** (*Optional*): Script definition
- **async_action** (*Optional*): If HA should execute the action asynchronously (returning response to Api.ai without waiting the action to finish). Should be set to `True` if Api.ai is returning the "Cannot connect to HA or it is taking to long" message, but then you will not be able to use values based on the result of the action. Defaults to `False`.
- **async_action** (*Optional*): If Home Assistant should execute the action asynchronously (returning response to Api.ai without waiting the action to finish). Should be set to `True` if Api.ai is returning the "Cannot connect to Home Assistant or it is taking to long" message, but then you will not be able to use values based on the result of the action. Defaults to `False`.
## {% linkable_title Examples %}

16
source/_components/binary_sensor.command_line.markdown
View file

@ -32,7 +32,7 @@ Configuration variables:
- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON".
- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF".
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
## {% linkable_title Examples %}
@ -71,10 +71,12 @@ An alternative solution could look like this:
```yaml
binary_sensor:
platform: command_line
name: Printer
command: ping -W 1 -c 1 192.168.1.10 > /dev/null 2>&1 && echo success || echo fail
device_class: connectivity
payload_on: "success"
payload_off: "fail"
- platform: command_line
name: Printer
command: ping -W 1 -c 1 192.168.1.10 > /dev/null 2>&1 && echo success || echo fail
device_class: connectivity
payload_on: "success"
payload_off: "fail"
```
Consider to use the [`ping` sensor ](/components/binary_sensor.ping/) as an alternative to the samples above.

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

@ -33,7 +33,7 @@ Configuration variables:
- **payload_on** (*Optional*): The payload that represents on state. Default is "ON".
- **payload_off** (*Optional*): The payload that represents state. Default is "OFF".
- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
For a quick check you can use the commandline tools shipped with `mosquitto` to send MQTT messages. Set the state of a sensor manually:

4
source/_components/binary_sensor.rest.markdown
View file

@ -16,7 +16,7 @@ ha_iot_class: "Local Polling"
The `rest` binary sensor platform is consuming a given endpoint which is exposed by a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) of a device, an application, or a web service. The binary sensor has support for GET and POST requests.
The JSON messages can contain different values like `1`, `"1"`, `TRUE`, `true`, `on`, or `open`. If the value is nested then use a [template](/topics/templating/).
The JSON messages can contain different values like `1`, `"1"`, `TRUE`, `true`, `on`, or `open`. If the value is nested then use a [template](/docs/configuration/templating/#processing-incoming-data).
```json
{
@ -53,7 +53,7 @@ Configuration variables:
- **method** (*Optional*): The method of the request. Default is GET.
- **name** (*Optional*): Name of the REST binary sensor.
- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value.
- **payload** (*Optional*): The payload to send with a POST request. Usually formed as a dictionary.
- **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to True.
- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`.

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

@ -36,6 +36,6 @@ Configuration options for the a TCP Sensor:
- **payload** (*Required*): What to send to the host in order to get the response we're interested in.
- **value_on** (*Required*): The value returned when the device is "on".
- **timeout** (*Optional*): How long in seconds to wait for a response from the service before giving up and disconnecting. Defaults to 10.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value. By default it's assumed that the entire response is the value.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value. By default it's assumed that the entire response is the value.
- **buffer_size** (*Optional*): The size of the receive buffer in bytes. Set this to a larger value if you expect to receive a response larger than the default. Defaults to 1024.

4
source/_components/camera.generic.markdown
View file

@ -33,8 +33,8 @@ Configuration variables:
- **name** (*Optional*): This parameter allows you to override the name of your camera.
- **username** (*Optional*): The username for accessing your camera.
- **password** (*Optional*): The password for accessing your camera.
- **authentication** (*Optional*): `basic` (default) or `digest` auth for requests.
- **limit_refetch_to_url_change** (*Optional*): true/false value (default: false). Limits refetching of the remote image to when the url changes. Only relevant if using a template to fetch the remote image.
- **authentication** (*Optional*): Type for authenticating the requests `basic` (default) or `digest`.
- **limit_refetch_to_url_change** (*Optional*): True/false value (default: false). Limits refetching of the remote image to when the url changes. Only relevant if using a template to fetch the remote image.
<p class='img'>
<a href='/cookbook/google_maps_card/'>

1
source/_components/camera.mqtt.markdown
View file

@ -30,4 +30,3 @@ Configuration variables:
- **topic** (*Required*): MQTT topic to subscribe to.
- **name** (*Optional*): Name of the camera

2
source/_components/cover.mqtt.markdown
View file

@ -45,7 +45,7 @@ Configuration variables:
- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is `true` if no state topic defined, else `false`.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is `0`. Will also be used when publishing messages.
- **retain** (*Optional*): If the published message should have the retain flag on or not. Default is `false`.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
- **tilt_command_topic** (*Optional*): The MQTT topic to publish commands to control the cover tilt.
- **tilt_status_topic** (*Optional*): The MQTT topic subscribed to receive tilt status update values.
- **tilt_min** (*Optional*): The minimum tilt value. Default is `0`

2
source/_components/cover.rfxtrx.markdown
View file

@ -57,7 +57,7 @@ cover:
devices:
0b1100ce3213c7f210010f70: # Siemens/LightwaveRF
name: Bedroom Shutter
070a00000a000101: # RFY
071a00000a000101: # RFY
name: Bathroom Shutter
```

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

@ -32,8 +32,10 @@ Configuration variables:
- **qos** (*Optional*): The QoS level of the topic.
This platform receives JSON formatted payloads containing GPS information, for example:
```json
{"longitude": 1.0,"gps_accuracy": 60,"latitude": 2.0,"battery_level": 99.9}
```
Where `longitude` is the longitude, `latitude` is the latitude, `gps_accuracy` is the accuracy in meters, `battery_level` is the current battery level of the device sending the update.
`longitude` and `latitude` are required keys, `gps_accuracy` and `battery_level` are optional.

6
source/_components/fan.mqtt.markdown
View file

@ -38,7 +38,7 @@ Configuration variables:
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **payload_on** (*Optional*): The payload that represents the running state. Default is "ON".
- **payload_off** (*Optional*): The payload that represents the stop state. Default is "OFF".
- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the state.
- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the state.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no state topic defined, else `false`.
- **retain** (*Optional*): If the published message should have the retain flag on or not.
@ -46,13 +46,13 @@ Configuration variables:
- **oscillation_command_topic** (*Optional*): The MQTT topic to publish commands to change the oscillation state.
- **payload_oscillation_on** (*Optional*): The payload that represents the oscillation on state. Default is "oscillate_on".
- **payload_oscillation_off** (*Optional*): The payload that presents the oscillation off state. Default is "oscillate_off".
- **oscillation_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the oscillation.
- **oscillation_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the oscillation.
- **speed_state_topic** (*Optional*): The MQTT topic subscribed to receive speed state updates.
- **speed_command_topic** (*Optional*): The MQTT topic to publish commands to change speed state.
- **payload_low_speed** (*Optional*): The payload that represents the fan's low speed.
- **payload_medium_speed** (*Optional*): The payload that represents the fan's medium speed.
- **payload_high_speed** (*Optional*): The payload that represents the fan's high speed.
- **speed_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the speed payload.
- **speed_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload.
- **speeds** array (*Optional*): Valid entries for the list are `off`, `low`, `medium`, and `high`.
<p class='note warning'>

4
source/_components/http.markdown
View file

@ -28,7 +28,7 @@ Configuration variables:
- **api_password** (*Optional*): Protect Home Assistant with a password.
- **server_host** (*Optional*): Only listen to incoming requests on specific ip/host (default: accept all)
- **server_port** (*Optional*): Let you set a port to use. Defaults to 8123.
- **base_url** (*Optional*): The url that Home Assistant is available on the internet. For example: `hass-example.duckdns.org:8123`. Defaults to local IP address. The IOS app finds local installations, if you have a outside url use this so that you can auto fill when discovered in the app.
- **base_url** (*Optional*): The URL that Home Assistant is available on the internet. For example: `hass-example.duckdns.org:8123`. Defaults to local IP address. The IOS app finds local installations, if you have an outside URL use this so that you can auto fill when discovered in the app.
- **development** (*Optional*): Disable caching and load unvulcanized assets. Useful for Frontend development.
- **ssl_certificate** (*Optional*): Path to your TLS/SSL certificate to serve Home Assistant over a secure connection.
- **ssl_key** (*Optional*): Path to your TLS/SSL key to serve Home Assistant over a secure connection.
@ -62,7 +62,7 @@ http:
The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/).
On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/) available.
On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/).
The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP.

3
source/_components/ifttt.markdown
View file

@ -20,7 +20,8 @@ ifttt:
key: xxxxx-x-xxxxxxxxxxxxx
```
`key` is your API key which can be obtained by viewing the **Settings** of the [Maker Channel](https://ifttt.com/maker). It's the last part of the URL.
`key` is your API key which can be obtained by viewing the **Settings** of the [Maker Channel](https://ifttt.com/services/maker_webhooks/settings). It's the last part of the URL (e.g. https://maker.ifttt.com/use/MYAPIKEY) you will find under **Settings** > **Account Info**.
<p class='img'>
<img src='/images/components/ifttt/finding_key.png' />

12
source/_components/light.hue.markdown
View file

@ -75,8 +75,9 @@ More information can be found on the [Philips Hue API documentation](https://www
The Hue platform has it's own concept of Scenes for setting the colors of a group of lights at once. Hue Scenes are very cheap, get created by all kinds of apps (as it is the only way to have 2 or more lights change at the same time), and are rarely deleted. A typical Hue hub might have hundreds of scenes stored in them, many that you've never used, almost all very poorly named.
To avoid user interface overload we don't expose Scenes directly. Instead there is a [light.hue_activate_scene](/components/light/#service-lighthue_activate_scene) service which can be used by `automation` or `script` components. For
instance:
To avoid user interface overload we don't expose Scenes directly. Instead there is a [light.hue_activate_scene](/components/light/#service-lighthue_activate_scene) service which can be used by `automation` or `script` components.
This will have all the bulbs transitioned at once, instead of one at a time using standard scenes in Home Assistant.
For instance:
```yaml
script:
@ -88,6 +89,13 @@ script:
scene_name: "Porch Orange"
```
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `group_name` | no | The group/room name of the lights. Find this in the Hue official app.
| `scene_name` | no | The name of the Scene. Find this in the Hue official app.
*Note*: `group_name` is not linked to Home Assistant group name.
*** Finding Group and Scene Names ***
How do you find these names?

35
source/_components/light.markdown
View file

@ -9,18 +9,7 @@ sharing: true
footer: true
---
This component allows you to track and control various light bulbs.
It has [4 built-in light profiles](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) which you're able to extend by putting a `light_profiles.csv` file in your config dir.
Preferred way to setup the Philips Hue platform is through the [the discovery component]({{site_root}}/components/discovery/). For the Wink light platform enable [the wink component]({{site_root}}/components/wink/).
If you want to enable the light component directly, add the following lines to your `configuration.yaml`:
```yaml
light:
platform: hue
```
This component allows you to track and control various light bulbs. Read the platform documentation for your particular light hardware to learn how to enable it.
<p class='note'>
The light component supports multiple entries in <code>configuration.yaml</code> by appending a sequential number to the section: <code>light 2:</code>, <code>light 3:</code> etc.
@ -30,11 +19,13 @@ 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.
| 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 | Integer that represents the time the light should take to transition to the new state in seconds. *Not supported by all lights.
| `profile` | yes | String with the name of one of the built-in profiles (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 or xy color then the profile values will be overwritten.
| `transition` | yes | Integer that represents the time the light should take to transition to the new state in seconds.
| `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 or xy color then the profile values 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)
| `color_temp` | yes | An INT in mireds representing the color temperature you want the light to be.
@ -42,7 +33,7 @@ Turns one light on or multiple lights on using [groups]({{site_root}}/components
| `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`. *Not supported by all lights.
| `flash` | yes | Tell light to flash, can be either value `short` or `long`.
| `effect`| yes | Applies an effect such as `colorloop` or `random`.
### {% linkable_title Service `light.turn_off` %}
@ -64,17 +55,3 @@ Toggles the state of one or multiple lights using [groups]({{site_root}}/compone
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of lights. Else targets all.
| `transition` | yes | Integer that represents the time the light should take to transition to the new state in seconds.
### {% linkable_title Service `light.hue_activate_scene` %}
If you have hue lights, there is a service call to directly activate
scenes that are stored in your hue hub. This will have all the bulbs
transitioned at once, instead of one at a time using standard scenes
in Home Assistant.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `group_name` | no | The group/room name of the lights. Find this in the Hue official app.
| `scene_name` | no | The name of the Scene. Find this in the Hue official app.
*Note*: `group_name` is not linked to Home Assistant group name.

34
source/_components/light.mqtt.markdown
View file

@ -32,13 +32,13 @@ Configuration variables:
- **brightness_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's brightness.
- **brightness_scale** (*Optional*): Defines the maximum brightness value (i.e. 100%) of the MQTT device (defaults to 255).
- **brightness_state_topic** (*Optional*): The MQTT topic subscribed to receive brightness state updates.
- **brightness_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the brightness value.
- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees).
- **brightness_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the brightness value.
- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees).
- **color_temp_state_topic** (*Optional*): The MQTT topic subscribed to receive color temperature state updates.
- **color_temp_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the color temperature value.
- **effect_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's effect state.
- **effect_state_topic** (*Optional*): The MQTT topic subscribed to receive effect state updates.
- **effect_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the effect value.
- **effect_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the effect value.
- **effect_list** (*Optional*): The list of effects the light supports.
- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'.
- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is true if no state topic defined, else false.
@ -48,15 +48,15 @@ Configuration variables:
- **retain** (*Optional*): If the published message should have the retain flag on or not.
- **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state.
- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates.
- **rgb_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the RGB value.
- **rgb_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value.
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the state value.
- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value.
- **white_value_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's white value.
- **white_value_state_topic** (*Optional*): The MQTT topic subscribed to receive white value updates.
- **white_value_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the white value.
- **white_value_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value.
- **xy_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's XY state.
- **xy_state_topic** (*Optional*): The MQTT topic subscribed to receive XY state updates.
- **xy_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the XY value.
- **xy_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the XY value.
<p class='note warning'>
Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.
@ -114,16 +114,16 @@ To enable a light with brightness (no RGB version) in your installation, add the
```yaml
# Example configuration.yml entry
light:
platform: mqtt
name: "Office light"
state_topic: "office/rgb1/light/status"
command_topic: "office/rgb1/light/switch"
brightness_state_topic: 'office/rgb1/light/brightness'
brightness_command_topic: 'office/rgb1/light/brightness/set'
qos: 0
payload_on: "ON"
payload_off: "OFF"
optimistic: false
- platform: mqtt
name: "Office light"
state_topic: "office/rgb1/light/status"
command_topic: "office/rgb1/light/switch"
brightness_state_topic: 'office/rgb1/light/brightness'
brightness_command_topic: 'office/rgb1/light/brightness/set'
qos: 0
payload_on: "ON"
payload_off: "OFF"
optimistic: false
```
### {% linkable_title Implementations %}

20
source/_components/light.mqtt_template.markdown
View file

@ -39,16 +39,16 @@ Configuration variables:
- **effect_list** (*Optional*): List of possible effects.
- **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state.
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **command_on_template** (*Required*): The template for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`.
- **command_off_template** (*Required*): The template for *off* state changes. Available variables: `state` and `transition`.
- **state_template** (*Optional*): Template to extract state from the state payload value.
- **brightness_template** (*Optional*): Template to extract brightness from the state payload value.
- **red_template** (*Optional*): Template to extract red color from the state payload value.
- **green_template** (*Optional*): Template to extract green color from the state payload value.
- **blue_template** (*Optional*): Template to extract blue color from the state payload value.
- **color_temp_template** (*Optional*): Template to extract color temperature from the state payload value.
- **effect_template** (*Optional*): Template to extract effect from the state payload value.
- **white_value_template** (*Optional*): Template to extract white value from the state payload value.
- **command_on_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`.
- **command_off_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *off* state changes. Available variables: `state` and `transition`.
- **state_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value.
- **brightness_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness from the state payload value.
- **red_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value.
- **green_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract green color from the state payload value.
- **blue_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract blue color from the state payload value.
- **color_temp_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract color temperature from the state payload value.
- **effect_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract effect from the state payload value.
- **white_value_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value.
- **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic or state template is defined, else false.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.

4
source/_components/light.yeelight.markdown
View file

@ -26,8 +26,8 @@ light:
192.168.1.25:
name: Living Room
transition: 1000
use_music_mode: True (defaults to False)
save_on_change: False (defaults to True)
use_music_mode: True #(defaults to False)
save_on_change: False #(defaults to True)
192.168.1.13:
name: Front Door
```

22
source/_components/lock.mqtt.markdown
View file

@ -40,7 +40,7 @@ Configuration variables:
- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no `state_topic` defined, else `false`.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **retain** (*Optional*): If the published message should have the retain flag on or not.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
<p class='note warning'>
Make sure that your topic match exact. `some-topic/` and `some-topic` are different topics.
@ -57,16 +57,16 @@ The example below shows a full configuration for a MQTT lock.
```yaml
# Example configuration.yml entry
lock:
platform: mqtt
name: Frontdoor
state_topic: "home-assistant/frontdoor/"
command_topic: "home-assistant/frontdoor/set"
payload_lock: "LOCK"
payload_unlock: "UNLOCK"
optimistic: false
qos: 1
retain: true
value_template: '{% raw %}{{ value.x }}{% endraw %}'
- platform: mqtt
name: Frontdoor
state_topic: "home-assistant/frontdoor/"
command_topic: "home-assistant/frontdoor/set"
payload_lock: "LOCK"
payload_unlock: "UNLOCK"
optimistic: false
qos: 1
retain: true
value_template: '{% raw %}{{ value.x }}{% endraw %}'
```
Keep an eye on retaining messages to keep the state as you don't want to unlock your door by accident when you restart something.

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

@ -31,7 +31,7 @@ Configuration variables:
- **host** (*Required*): The IP or hostname of the Nuki bridge.
- **port** (*Optional*): The port on which the Nuki bridge is listening on. Defaults to `8080`.
- **token** (*Optional*): The token that was defined when setting up the bridge.
- **token** (*Required*): The token that was defined when setting up the bridge.
## {% linkable_title Full configuration %}

9
source/_components/media_player.markdown
View file

@ -34,15 +34,6 @@ Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`,
| `entity_id` | yes | Target a specific media player. Defaults to all. |
| `volume_level` | no | Float for volume level |
#### {% linkable_title Service `media_player/volume_transition` %}
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------|
| `entity_id` | yes | Target a specific media player. Defaults to all. |
| `volume_level` | no | Float for volume level |
| `transition` | no | Integer for transition time in seconds |
#### {% linkable_title Service `media_player/media_seek` %}
| Service data attribute | Optional | Description |

2
source/_components/notify.mqtt.markdown
View file

@ -20,7 +20,7 @@ The MQTT notification support is different than the other [notification](/compon
```
<p class='img'>
<img src='/images/screenshots/mqtt-notify.png' />
<img src='/images/screenshots/mqtt-notify.png' />
</p>
Using the [REST API](/developers/rest_api/#post-apiservicesltdomainltservice) to send a message to a given topic.

2
source/_components/ring.markdown
View file

@ -30,4 +30,4 @@ Configuration variables:
- **username** (*Required*): The username for accessing your Ring account.
- **password** (*Required*): The password for accessing your Ring account.
Finish its configuration by visiting the [Ring binary_sensor page](/components/binary_sensor.ring/) or [Ring sensor page](/components/sensor.ring/).
Finish its configuration by visiting the [Ring binary sensor](/components/binary_sensor.ring/) or [Ring sensor](/components/sensor.ring/) documentation.

4
source/_components/sensor.arest.markdown
View file

@ -39,12 +39,12 @@ Configuration variables:
- **[variable]** (*Required*): Name of the variable to monitor.
- **name** (*Optional*): The name to use for the frontend.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
- **pins** array (*Optional*): List of pins to monitor. Analog pins need a leading **A** for the pin number.
- **[pin]** (*Required*): Pin number to use.
- **name** (*Required*): The name of the variable you wish to monitor.
- **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
The variables in the `monitored_variables` array must be available in the response of the device. As a starting point you could use the one of the example sketches (eg. [Ethernet](https://raw.githubusercontent.com/marcoschwartz/aREST/master/examples/Ethernet/Ethernet.ino) for an Arduino with Ethernet shield). In those sketches are two variables (`temperature` and `humidity`) available which will act as endpoints.

4
source/_components/sensor.arwn.markdown
View file

@ -18,7 +18,7 @@ To use your ARWN setup, you must already have configured the [MQTT](mqtt) platfo
```yaml
# Example configuration.yaml entry
sensor:
platform: arwn
- platform: arwn
```
Currently all temperature, barometer, and wind sensors will be displayed. Support for rain gauge sensors will happen in the future.
Currently all temperatures, barometers, and wind sensors will be displayed. Support for rain gauge sensors will happen in the future.

27
source/_components/sensor.bitcoin.markdown
View file

@ -21,29 +21,10 @@ To add the Bitcoin sensor to your installation, add a selection of the available
```yaml
# Example configuration.yaml entry
sensor:
platform: bitcoin
display_options:
- exchangerate
- trade_volume_btc
- miners_revenue_usd
- btc_mined
- trade_volume_usd
- difficulty
- minutes_between_blocks
- number_of_transactions
- hash_rate
- timestamp
- mined_blocks
- blocks_size
- total_fees_btc
- total_btc_sent
- estimated_btc_sent
- total_btc
- total_blocks
- next_retarget
- estimated_transaction_volume_usd
- miners_revenue_btc
- market_price_usd
- platform: bitcoin
display_options:
- exchangerate
- trade_volume_btc
```
Configuration variables:

4
source/_components/sensor.command_line.markdown
View file

@ -30,8 +30,8 @@ Configuration variables:
- **command** (*Required*): The action to take to get the value.
- **name** (*Optional*): Name of the command sensor.
- **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **scan_interval** (*Optional*): Defines number of seconds for polling interval
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
- **scan_interval** (*Optional*): Defines number of seconds for polling interval.
## {% linkable_title Examples %}

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

@ -35,7 +35,7 @@ sensor:
- **include_only_feed_id** (*Optional*): Positive integer list of Emoncms feed IDs. Only the feeds with feed IDs specified here will be displayed. Can not be specified if `exclude_feed_id` is specified.
- **exclude_feed_id** (*Optional*): Positive integer list of Emoncms feed IDs. All the feeds will be displayed as sensors except the ones listed here. Can not be specified if `include_only_feed_id` is specified.
- **sensor_names** (*Optional*): Dictionary of names for the sensors created that are created based on feed ID. The dictionary consists of `feedid: name` pairs. Sensors for feeds with their feed ID mentioned here will get the chosen name instead of the default name
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to alter the feed value.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to alter the feed value.
- **scan_interval** (*Optional*): Defines the update interval of the sensor in seconds.
- **unit_of_measurement** (*Optional*): Defines the unit of measurement of for all the sensors. default is "W".

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

@ -30,7 +30,7 @@ Configuration variables:
- **file_path** (*Required*): path to file that stores the sensor data.
- **name** (*Optional*): Name of the sensor to use in the frontend. Defaults to `File`.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
## {% linkable_title Examples %}

13
source/_components/sensor.history_stats.markdown
View file

@ -50,11 +50,10 @@ Configuration variables:
- **duration**: Duration of the measure
<p class='note'>
You have to provide **exactly 2** of `start`, `end` and `duration`.
You have to provide **exactly 2** of `start`, `end` and `duration`.
<br/>
You can use [template extensions](/topics/templating/#home-assistant-template-extensions) such as `now()` or `as_timestamp()` to handle dynamic dates, as shown in the examples below.
You can use [template extensions](/topics/templating/#home-assistant-template-extensions) such as `now()` or `as_timestamp()` to handle dynamic dates, as shown in the examples below.
</p>
## {% linkable_title Sensor type %}
@ -102,12 +101,14 @@ duration:
Here are some examples of periods you could work with, and what to write in your `configuration.yaml`:
**Today**: starts at 00:00 of the current day and ends right now.
```yaml
start: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}'
end: '{% raw %}{{ now() }}{% endraw %}'
```
**Yesterday**: ends today at 00:00, lasts 24 hours.
```yaml
end: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}'
duration:
@ -115,6 +116,7 @@ Here are some examples of periods you could work with, and what to write in your
```
**This morning (6AM - 11AM)**: starts today at 6, lasts 5 hours.
```yaml
start: '{% raw %}{{ now().replace(hour=6).replace(minute=0).replace(second=0) }}{% endraw %}'
duration:
@ -130,6 +132,7 @@ Here, last Monday is _today_ as a timestamp, minus 86400 times the current weekd
```
**Last 30 days**: ends today at 00:00, lasts 30 days. Easy one.
```yaml
end: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}'
duration:
@ -137,11 +140,13 @@ Here, last Monday is _today_ as a timestamp, minus 86400 times the current weekd
```
**All your history** starts at timestamp = 0, and ends right now.
```yaml
start: '{% raw %}{{ 0 }}{% endraw %}'
end: '{% raw %}{{ now() }}{% endraw %}'
```
<p class='note'>
The `/dev-template` page of your home-assistant UI can help you check if the values for `start`, `end` or `duration` are correct.
The `/dev-template` page of your home-assistant UI can help you check if the values for `start`, `end` or `duration` are correct.
If you want to check if your period is right, just click on your component, the `from` and `to` attributes will show the start and end of the period, nicely formatted.
</p>

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

@ -40,7 +40,7 @@ Configuration variables for the server:
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **measurement** (*Required*): Defines the measurement name in InfluxDB (the from clause of the query).
- **where** (*Required*): Defines the data selection clause (the where clause of the query).
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
- **database** (*Optional*): Name of the database to use. Defaults to `home_assistant`.
- **group_function** (*Optional*): The group function to be used. Defaults to `mean`.
- **field** (*Optional*): The field name to select. Defaults to value.

14
source/_components/sensor.miflora.markdown
View file

@ -15,6 +15,18 @@ ha_iot_class: "Local Polling"
The `miflora` sensor platform allows one to monitor to plants. The [Mi Flora plant sensor](https://www.aliexpress.com/item/Newest-Original-Xiaomi-Flora-Monitor-Digital-Plants-Flowers-Soil-Water-Light-Tester-Sensor-Monitor-for-Aquarium/32685750372.html) is a small Bluetooth Low Energy device that monitors not only the moisture, but also light, temperature and conductivity. As only a single BLE device can be polled at the same time, the library implements locking to make sure this is the case.
Start a scan to determine the MAC addresses of the sensor:
```bash
$ sudo hcitool lescan
LE Scan ...
F8:04:33:AF:AB:A2 [TV] UE48JU6580
C4:D3:8C:12:4C:57 Flower mate
[...]
```
Check for `Flower care` or `Flower mate` entries, those are your sensor.
To use your Mi Flora plant sensor in your installation, add the following to your `configuration.yaml` file:
```yaml
@ -26,7 +38,7 @@ sensor:
- temperature
```
- **mac** (*Required*): The MAC address of your sensor. You can find this be running `hcitool lescan` from command line.
- **mac** (*Required*): The MAC address of your sensor.
- **monitored_conditions** array (*Optional*): The paramaters that should be monitored (defaults to monitoring all parameters).
- **moisture**: Moisture in the soil.
- **light**: Brightness at the sensor's location.

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

@ -32,7 +32,7 @@ Configuration variables:
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **expire_after** (*Optional*): Defines the number of seconds after the value expires if it's not updated. Default is 0 (=never expire).
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
## {% linkable_title Examples %}

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

@ -71,7 +71,9 @@ If your QNAP device uses self-signed certificates, set the `verify_ssl` option t
This component has been tested on the following devices:
- TS-410 (QTS 4.2.3)
- TS-419 (QTS 4.2.3)
- TS-451 (QTS 4.2.2)
- TS-470 (QTS 4.2.2)
- TS-639 (QTS 4.2.3)
Other QNAP NAS devices using similar firmware should work fine. For more information about supported devices, or to report issues with your device, please visit the [qnapstats project](https://github.com/colinodell/python-qnapstats#device-support).

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

@ -39,7 +39,7 @@ Configuration variables:
- **resource** (*Required*): The resource or endpoint that contains the value.
- **method** (*Optional*): The method of the request. Default is `GET`.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value.
- **payload** (*Optional*): The payload to send with a POST request. Depends on the service, but usually formed as JSON.
- **name** (*Optional*): Name of the REST sensor.
- **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any.

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

@ -32,7 +32,7 @@ Configuration options for the a TCP Sensor:
- **port** (*Required*): The port to connect to the host on.
- **payload** (*Required*): What to send to the host in order to get the response we're interested in.
- **timeout** (*Optional*): How long in seconds to wait for a response from the service before giving up and disconnecting. Defaults to `10`
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value. By default it's assumed that the entire response is the value.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value. By default it's assumed that the entire response is the value.
- **unit_of_measurement** (*Optional*): The unit of measurement to use for the value.
- **buffer_size** (*Optional*): The size of the receive buffer in bytes. Set this to a larger value if you expect to receive a response larger than the default. Defaults to `1024`.

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

@ -35,7 +35,7 @@ Configuration variables:
- **sensors** array (*Required*): List of your sensors.
- **friendly_name** (*Optional*): Name to use in the Frontend.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **value_template** (*Required*): Defines a [template](/topics/templating/) to extract a value from the event bus.
- **value_template** (*Required*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the event bus.
- **icon_template** (*Optional*): Defines a [template](/topics/templating/) for the icon of the sensor.
- **entity_id** (*Optional*): Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update it's state.

6
source/_components/switch.kankun.markdown
View file

@ -25,9 +25,9 @@ To enable it, add the following lines to your `configuration.yaml`:
# Example configuration.yaml entry
switch:
platform: kankun
switches:
bedroom_heating:
host: hostname_or_ipaddr
switches:
bedroom_heating:
host: hostname_or_ipaddr
```
Configuration variables:

2
source/_components/switch.mqtt.markdown
View file

@ -40,7 +40,7 @@ Configuration variables:
- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is `true` if no `state_topic` defined, else `false`.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **retain** (*Optional*): If the published message should have the retain flag on or not.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
<p class='note warning'>
Make sure that your topic match exact. `some-topic/` and `some-topic` are different topics.

29
source/_components/switch.rest.markdown
View file

@ -28,12 +28,33 @@ Configuration variables:
- **resource** (*Required*): The resource or endpoint that contains the value.
- **name** (*Optional*): Name of the REST switch.
- **body_on** (*Optional*): The body of the POST request that commands the switch to become enabled. Default is "ON". This value can be a [template](/topics/templating/), which is useful if the POST request needs to depend on the state of the system. For example, to enable remote-temperature-sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. On can achieve this using the template `'{"rem_temp":{{states.sensor.bedroom_temp.state}}}'`.
- **body_off** (*Optional*): The body of the POST request that commands the switch to become disabled. Default is "OFF". This value can also be a template.
- **is_on_template** (*Optional*): A [template](/topics/templating/) that determines the state of the switch from the value returned by the GET request on the resource url. This template should compute to a boolean (True or False). Default is equivalent to `'{% raw %}{{ value.json == body_on }}{% endraw %}'`. This means that by default, the state of the switch is on if and only if the response to the GET request matches `body_on`.
- **body_on** (*Optional*): The body of the POST request that commands the switch to become enabled. Default is "ON". This value can be a [template](/topics/templating/).
- **body_off** (*Optional*): The body of the POST request that commands the switch to become disabled. Default is "OFF". This value can also be a [template](/topics/templating/).
- **is_on_template** (*Optional*): A [template](/docs/configuration/templating/#processing-incoming-data) that determines the state of the switch from the value returned by the GET request on the resource URL. This template should compute to a boolean (True or False). If the value is valid JSON, it will be available in the template as the variable `value_json`. Default is equivalent to `'{% raw %}{{ value_json == body_on }}{% endraw %}'`. This means that by default, the state of the switch is on if and only if the response to the GET request matches .
<p class='note warning'>
Make sure that the URL matches exactly your endpoint or resource.
</p>
## {% linkable_title Example %}
### {% linkable_title Switch with templated value %}
This example shows a switch that uses a [template](/topics/templating/) to allow Home Assistant to determine its state. In this example the REST endpoint returns this JSON response with true indicating the switch is on.
```json
{"is_active": "true"}
```
```yaml
switch:
- platform: rest
resource: http://IP_ADDRESS/led_endpoint
body_on: '{"active": "true"}'
body_off: '{"active": "false"}'
is_on_template: '{% raw %}{{value_json.is_active}}{% endraw %}'
```
`body_on` and `body_off` can also depend on the state of the system. For example, to enable a remote temperature sensor tracking on a radio thermostat, one has to send the current value of the remote temperature sensor. This can be achieved by using the template `{% raw %}'{"rem_temp":{{states.sensor.bedroom_temp.state}}}'{% endraw %}`.