From eb9ba845d848d704a50d581f32a8da022634efa8 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sat, 19 Dec 2015 23:13:49 -0800 Subject: [PATCH 01/11] Upgrade components with template docs --- source/_components/automation.markdown | 27 +++++++++++++++++++++++++ source/_components/light.mqtt.markdown | 6 ++++++ source/_components/sensor.rest.markdown | 6 +++--- 3 files changed, 36 insertions(+), 3 deletions(-) diff --git a/source/_components/automation.markdown b/source/_components/automation.markdown index d90887ee8af..42ecbb4ea45 100644 --- a/source/_components/automation.markdown +++ b/source/_components/automation.markdown @@ -147,6 +147,17 @@ automation: offset: '-00:45:00' ``` +#### {% linkable_title Template trigger %} + +Template triggers work by evaluating a [template] on each state change. The trigger will fire if the state change caused the template to render 'true'. + +```yaml +automation: + trigger: + platform: template + value_template: '{% raw %}{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}{% endraw %}' +``` + #### {% linkable_title Time trigger %} Time can be triggered in many ways. The most common is to specify `after` and trigger at a specific point in time each day. Alternatively, you can also match if the hour, minute or second of the current time has a specific value. For example, by only setting minutes in the config to 5 it will trigger every hour when it is 5 minutes past whole. You cannot use `after` together with hour, minute or second. @@ -215,6 +226,8 @@ automation: # At least one of the following required above: 17 below: 25 + # Optional + value_template: '{% raw %}{{ state.attributes.battery }}{% endraw %}' ``` #### {% linkable_title State condition %} @@ -229,6 +242,18 @@ automation: state: not_home ``` +#### {% linkable_title Template condition %} + +The template condition will test if [given template][template] renders a value equal to true. + + +```yaml +automation: + condition: + platform: template + value_template: '{% raw %}{{ state.attributes.battery }}{% endraw %}' +``` + #### {% linkable_title Time condition %} The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week @@ -302,3 +327,5 @@ INFO [homeassistant.components.automation] Initialized rule Rain is over The Logbook component will show a line entry when an automation is triggered. You can look at the previous entry to determine which trigger in the rule triggered the event. ![Logbook example](/images/components/automation/logbook.png) + +[template]: /getting-started/templating/ \ No newline at end of file diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index 2efd163e0b4..07c24d8eaa7 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -33,6 +33,9 @@ light: brightness_command_topic: "office/rgb1/brightness/set" rgb_state_topic: "office/rgb1/rgb/status" rgb_command_topic: "office/rgb1/rgb/set" + state_value_format: "{% raw %}{{ value_json.state }}{% endraw %}" + brightness_value_format: "{% raw %}{{ value_json.brightness }}{% endraw %}" + rgb_value_format: "{% raw %}{{ value_json.rgb | join(',') }}{% endraw %}" qos: 0 payload_on: "ON" payload_off: "OFF" @@ -63,6 +66,9 @@ Configuration variables: - **brightness_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's brightness. - **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates. - **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state. +- **state_value_format** (*Optional*): Defines a [template](/getting-started/templating/) to extract the state value. +- **brightness_value_format** (*Optional*): Defines a [template](/getting-started/templating/) to extract the brightness value. +- **rgb_value_format** (*Optional*): Defines a [template](/getting-started/templating/) to extract the RGB value. - **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. - **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". - **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". diff --git a/source/_components/sensor.rest.markdown b/source/_components/sensor.rest.markdown index a7ffa015c44..59bfb47f70a 100644 --- a/source/_components/sensor.rest.markdown +++ b/source/_components/sensor.rest.markdown @@ -20,9 +20,9 @@ To enable this sensor, add the following lines to your `configuration.yaml` file sensor: platform: rest resource: http://IP_ADDRESS/ENDPOINT + value_template: '{% raw %}{{ value_json.thermostat }}{% endraw %}' method: GET name: REST GET sensor - value_template: '{% raw %}{{ value_json.x }}{% endraw %}' unit_of_measurement: "°C" ``` @@ -34,7 +34,7 @@ sensor: platform: rest resource: http://IP_ADDRESS/ENDPOINT method: POST - value_template: '{% raw %}{{ template }}{% endraw %}' + value_template: '{% raw %}{{ value_json.thermostat }}{% endraw %}' payload: '{ "device" : "heater" }' name: REST POST sensor unit_of_measurement: "°C" @@ -44,7 +44,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** (*Required*): Defines a [template](/getting-started/templating/) to extract the value. +- **value_template** (*Optional*): Defines a [template](/getting-started/templating/) to extract the value. - **payload** (*Optional*): The payload to send with a POST request. Usualy formed as a dictionary. - **name** (*Optional*): Name of the REST sensor. - **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any. From c36914e68725e1d0bd34836c920f505f61589676 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 00:08:28 -0800 Subject: [PATCH 02/11] Add link to templating in menu --- source/_includes/custom/navigation.html | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 5da7853c2e5..52f378b5495 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -7,6 +7,7 @@
  • Adding devices
  • Presence detection
  • Automation
    • +
  • Templating
  • Configuration cookbook
    • From 3110bd5a037cbd846122003344ec251debcdab69 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 00:08:38 -0800 Subject: [PATCH 03/11] Add templating to notify --- source/_components/notify.markdown | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/_components/notify.markdown b/source/_components/notify.markdown index 7082d2f4b37..ed8f64c4d7d 100644 --- a/source/_components/notify.markdown +++ b/source/_components/notify.markdown @@ -35,12 +35,16 @@ Once loaded, the `notify` platform will expose a service that can be called to s | `title` | yes | Title of the notification. Default is `Home Assistant`. | `target` | yes | Some platforms will allow specifying a recipient that will receive the notification. See your platform page if it is supported. +The notification component supports specifying [templates] for both the `message` and the `title`. This will allow you to use the current state of Home Assistant in your notifications. + +[templates]: /getting-started/templating/ + ### {% linkable_title Test if it works %} A simple way to test if you have set up your notify platform correctly is to use **Call Service** from the **Developer Tools** to call your notify service. Choose your service (*notify/xyz*) from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**. ```json { - "message": "A simple test message from HA." + "message": "The sun is {% raw %}{% if is_state('sun.sun', 'above_horizon') %}up{% else %}down{% endif %}{% endraw %}!" } ``` From 616402f8e854d00e7e0b4e422f74c19f5c2e7394 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 01:05:31 -0800 Subject: [PATCH 04/11] Update templating docs --- source/getting-started/templating.markdown | 125 ++++++++++++++------- 1 file changed, 86 insertions(+), 39 deletions(-) diff --git a/source/getting-started/templating.markdown b/source/getting-started/templating.markdown index 6b3c354ab0e..7151428bba2 100644 --- a/source/getting-started/templating.markdown +++ b/source/getting-started/templating.markdown @@ -9,59 +9,106 @@ sharing: true footer: true --- -The template helper enables one to mathematically manipulate values, use variables to extract values from JSON, and create customized messages to send with the [notification component](components/notify/). If the entity has template support then the `value_template` key can be set and used (eg. `message:` in `data:` of an automation rule) in the `configuration.yaml` file. +

    +This is an advanced feature of Home Assistant. You need a basic understanding of the [Home Assistant architecture], especially states. +

    + +[Home Assistant architecture]: /developers/architecture/ + +Templating is a powerful feature in Home Assistant that allows the user control over information that is going into and out of the system. It is used for: + + - Formatting outgoing messages in, for example, the [notify] and [alexa] components. + - Process incoming data from sources that provide raw data, like [MQTT], [Rest sensor] or the [command line sensor]. + +[notify]: /components/notify/ +[alexa]: /components/alexa/ +[MQTT]: /components/mqtt/ +[Rest sensor]: /components/sensor.rest/ +[command line sensor]: /components/sensor.command_line/ + +## {% linkable_title Building templates %} + +Templating in Home Assistant is powered by the Jinja2 templating engine. This means that we are using their syntax and make some custom Home Assistant variables available to templates during rendering. We will not go over the basics of the syntax, as Jinja2 does a lot better job at this in their [Jinja2 documentation]. + +[Jinja2 documentation]: http://jinja.pocoo.org/docs/dev/templates/ + +

    +The frontend has a template editor developer tool to help develop and debug templates. +

    + +Templates can get pretty big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates: ```yaml -value_template: '{% raw %}{{ value.x }}{% endraw %}' +script: + msg_who_is_home: + sequence: + - service: notify.notify + data: + message: > + {% raw %}{% if is_state('device_tracker.paulus', 'home') %} + Ha, Paulus is home! + {% else %} + Paulus is at {{ states('device_tracker.paulus')) }}. + {% endif %}{% endraw %} ``` -To check your templates on-the-fly checkout the **Template Editor** from the **Developer Tools**. +### {% linkable_title Home Assistant template extensions %} -For a complete overview, check the [Jinja2 documentation](http://jinja.pocoo.org/docs/dev/templates/). - -### {% linkable_title Accessing variables %} - -The [variables](http://jinja.pocoo.org/docs/dev/templates/#variables) are handled the same way as in Python. - -| Method | description | -| -------------- | ---------- | -| `{% raw %}{{ value.x }}{% endraw %}` or `{% raw %}{{ value.['x'] }}{% endraw %}` | Normal value | -| `{% raw %}{{ value_json.x }}{% endraw %}` | JSON value | - -The evaluation leads to an empty string if it's unsuccessful and printed or iterated over. - -### {% linkable_title The `states` variable %} - -The template support has a special `states` variable: +Home Assistant adds extensions to allow templates to access all of the current states: - Iterating `states` will yield each state sorted alphabetically by entity id - Iterating `states.domain` will yield each state of that domain sorted alphabetically by entity id - `states.sensor.temperature` returns state object for `sensor.temperature` + - `states('device_tracker.paulus')` will return the state string (not the object) of given entity or `unknown` if it doesn't exist. + - `is_state('device_tracker.paulus', 'home')` will test if given entity is specified state. + - Filter `multiply(x)` will convert input to number and multiply it with `x` + - Filter `round(x)` will convert input to number and round it to `x` decimals. -Example templates and what they could result in: +#### {% linkable_title Examples %} -| Template | Output | -| ------------ | ---------- | -| `{% raw %}{{ states.device_tracker.paulus.state }}{% endraw %}` | home | -| `{% raw %}{% for state in states.sensor %}{{ state.entity_id }}={{ state.state }}, {% endfor %}{% endraw %}`| senor.thermostat=24, sensor.humidity=40, | +```jinja2 +{% raw %} +# Next two statements result in same value if state exists +# Second one will result in an error if state does not exist +{{ states('device_tracker.paulus') }} +{{ states.device_tracker.paulus.state }} -### {% linkable_title Mathematical functions %} +# Print an attribute if state is defined +{% if states.device_tracker.paulus %} +{{ states.device_tracker.paulus.attributes.battery }} +{% else %} +?? +{% endif %} -The mathematical methods convert strings to numbers automatically before they are doing their job. This could be useful if you recieve data in the wrong unit of measurement and want to convert it. They are used like the standard [Jinja2 filters](http://jinja.pocoo.org/docs/dev/templates/#filters). +# Print out a list of all the sensor states +{% for state in states.sensor %} + {{ state.entity_id }}={{ state.state }}, +{% endfor %} -| Method | description | -| -------------- | ---------- | -| `multiply(x)` | Multiplies the value with `x` | -| `round(x)` | Maximal number `x` of decimal places for the value | +{% if is_state('device_tracker.paulus', 'home') %} + Ha, Paulus is home! +{% else %} + Paulus is at {{ states('device_tracker.paulus')) }}. +{% endif %} -A sample sensor entry for your `configuration.yaml` file could look like this: - -```yaml -# Example configuration.yaml entry -sensor: - platform: dweet - device: temp-sensor012 - value_template: '{% raw %}{{ value_json.temperature | multiply(1.02) | round(2) }}{% endraw %}' - unit_of_measurement: "°C" +{{ states.sensor.temperature | multiply(10) | round(2) }}{% endraw %} ``` +## {% linkable_title Processing incoming data %} + +The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data that you care about. This will work only for platforms and components that mentioned support for this in their documentation. + +It depends per component or platform but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions: + +| Variable | Description | +| ------------ | ----------- | +| `value` | The incoming value. +| `value_json` | The incoming value parsed as JSON. + +```jinja2 +# Incoming value: +{"primes": [2, 3, 5, 7, 11, 13]} + +# Extract third prime number +{% raw %}{{ value_json.primes[2] }}{% endraw %} +``` From 20170a170a1fe323df2b29ee58e60716100f8014 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 01:11:40 -0800 Subject: [PATCH 05/11] Update README --- README.markdown | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.markdown b/README.markdown index 15e62ba00d5..da2a7f70358 100644 --- a/README.markdown +++ b/README.markdown @@ -1,8 +1,8 @@ # Home Assistant website -This is the source for the [Home Assistant](https://github.com/balloob/home-assistant) website available at [Home-Assistant.io](https://home-assistant.io). +This is the source for the [Home Assistant](https://github.com/balloob/home-assistant) website available at [Home-Assistant.io](https://home-assistant.io). All commits made to the master branch will be automatically pushed to production. -## Jekyll project to generate and deploy +## Jekyll project to generate and deploy | Command | Action | |---|---| @@ -10,6 +10,7 @@ This is the source for the [Home Assistant](https://github.com/balloob/home-assi | `rake generate` | Generate new version of the site | `rake deploy` | Deploy a new version of the site +_Generating and deploying is no longer necessary as we now have auto-deply._ ## Setup @@ -38,7 +39,7 @@ $ rake preview The preview is now available on [http://127.0.0.1:4000](http://127.0.0.1:4000). -## Steps for the deployment of the site +## Steps for the deployment of the site All developers with write access to the repositories are able to deploy the website. The deploy process is fully automated with `rake generate && rake deploy`. From 2d1ae4a17cbad0c198d9409faedd4925911e77a2 Mon Sep 17 00:00:00 2001 From: happyleaves Date: Sun, 20 Dec 2015 18:34:48 -0500 Subject: [PATCH 06/11] torque sensor doc --- source/_components/sensor.torque.markdown | 50 +++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 source/_components/sensor.torque.markdown diff --git a/source/_components/sensor.torque.markdown b/source/_components/sensor.torque.markdown new file mode 100644 index 00000000000..057de9dbfe9 --- /dev/null +++ b/source/_components/sensor.torque.markdown @@ -0,0 +1,50 @@ +--- +layout: component +title: "Torque sensor" +description: "Instructions how to integrate Torque sensors into Home Assistant." +date: 2015-12-20 18:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Sensor +--- + +The `torque` platform will allow you to monitor [Torque](http://torque-bhp.com/) data relayed from a bluetooth OBD2 stick via the Torque mobile application. + +## {% linkable_title Configuration %} +To use Torque sensors with your installation, you must configure both the Torque mobile application and Home Assistant. + +### {% linkable_title Torque application %} + +In **Settings** -> **Data Logging & Upload**: + +Under the **Logging Preferences** header: + +- Touch **Select what to log**, activate the menu in the upper right, and select **Add PID to log**. +- Select items of interest. + +Under the **Realtime Web Upload** header: + +- Check **Upload to webserver**. +- Enter `http://HOST:PORT/api/torque` as the **Webserver URL**, where `HOST` and `PORT` are your externally-accessible Home Assistant HTTP host and port. +- Enter an email address in **User Email Address**. +- Optionally set the **Web Logging Interval**. The 2-second default may quickly fill up the Home Assistant history database. + +### {% linkable_title Home Assistant %} + +Add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +sensor: + platform: torque + name: Your Vehicle Name + email: your_configured@email.com +``` + +Configuration variables: + +- **name** (*Required*): Vehicle name (your choice). +- **email**: Email address configured in Torque application. + From cd539236f3663c96497371661bd2d34b693bded1 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 16:58:43 -0800 Subject: [PATCH 07/11] Update REST API docs --- source/developers/rest_api.markdown | 37 ++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index d35b6f1ef73..d76449fea94 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -212,10 +212,20 @@ Returns a state object for specified entity_id. Returns 404 if not found. Sample `curl` command: -```$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ +```bash +$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \ http://IP_ADDRESS:8123/api/states/sensor.kitchen_temperature ``` +#### {% linkable_title GET /api/error_log %} +Retrieve all errors logged during the current session of Home Assistant as a plaintext response. + +```text +15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions +15-12-20 11:03:03 netdisco.ssdp: Error fetching description at http://192.168.1.1:8200/rootDesc.xml +15-12-20 11:04:36 homeassistant.components.alexa: Received unknown intent HelpIntent +``` + #### {% linkable_title POST /api/states/<entity_id> %} Updates or creates the current state of an entity. @@ -249,8 +259,8 @@ Sample `curl` command: ```bash $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ - -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \ - http://localhost:8123/api/states/sensor.kitchen_temperature + -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \ + http://localhost:8123/api/states/sensor.kitchen_temperature ``` #### {% linkable_title POST /api/events/<event_type> %} @@ -309,14 +319,29 @@ Sample `curl` command: ```bash $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \ - -d '{"entity_id": "switch.christmas_lights", "state": "on"}' \ - http://localhost:8123/api/services/switch/turn_on + -d '{"entity_id": "switch.christmas_lights", "state": "on"}' \ + http://localhost:8123/api/services/switch/turn_on ```

    -The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system. +The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.

    +#### {% linkable_title POST /api/template %} +Render a Home Assistant template. [See template docs for more information.](/getting-started/templating/) + +```json +{ + "template": "Paulus is at {% raw %}{{ states('device_tracker.paulus') }}{% endraw %}!" +} +``` + +Returns the rendered template in plain text. + +```text +Paulus is at work! +``` + #### {% linkable_title POST /api/event_forwarding %} Setup event forwarding to another Home Assistant instance. From 1a4599572f4902fdab8897e71baf1644b6463cf5 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 17:24:35 -0800 Subject: [PATCH 08/11] Tweak torque docs --- source/_components/sensor.torque.markdown | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/_components/sensor.torque.markdown b/source/_components/sensor.torque.markdown index 057de9dbfe9..146b6c3c9aa 100644 --- a/source/_components/sensor.torque.markdown +++ b/source/_components/sensor.torque.markdown @@ -1,6 +1,6 @@ --- layout: component -title: "Torque sensor" +title: "Torque (OBD2)" description: "Instructions how to integrate Torque sensors into Home Assistant." date: 2015-12-20 18:00 sidebar: true @@ -27,7 +27,7 @@ Under the **Logging Preferences** header: Under the **Realtime Web Upload** header: - Check **Upload to webserver**. -- Enter `http://HOST:PORT/api/torque` as the **Webserver URL**, where `HOST` and `PORT` are your externally-accessible Home Assistant HTTP host and port. +- Enter `http://HOST:PORT/api/torque?api_password=YOUR_PASSWORD` as the **Webserver URL**, where `HOST` and `PORT` are your externally-accessible Home Assistant HTTP host and port and YOUR_PASSWORD is your password. - Enter an email address in **User Email Address**. - Optionally set the **Web Logging Interval**. The 2-second default may quickly fill up the Home Assistant history database. @@ -47,4 +47,3 @@ Configuration variables: - **name** (*Required*): Vehicle name (your choice). - **email**: Email address configured in Torque application. - From 76cd19a506d5e8358b20412b1afe9b1d6e6d7f0c Mon Sep 17 00:00:00 2001 From: Philip Lundrigan Date: Mon, 21 Dec 2015 12:50:54 -0700 Subject: [PATCH 09/11] Tweak template documentation --- source/_components/automation.markdown | 8 +++++--- source/_components/sensor.arest.markdown | 2 ++ 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/source/_components/automation.markdown b/source/_components/automation.markdown index 42ecbb4ea45..0c841d24b6f 100644 --- a/source/_components/automation.markdown +++ b/source/_components/automation.markdown @@ -149,7 +149,7 @@ automation: #### {% linkable_title Template trigger %} -Template triggers work by evaluating a [template] on each state change. The trigger will fire if the state change caused the template to render 'true'. +Template triggers work by evaluating a [template] on each state change. The trigger will fire if the state change caused the template to render 'true'. This is achieved by having the template result in a true boolean expression (`{% raw %}{{ is_state('device_tracker.paulus', 'home') }}{% endraw %}`) or by having the template render 'true' (example below). ```yaml automation: @@ -244,14 +244,16 @@ automation: #### {% linkable_title Template condition %} -The template condition will test if [given template][template] renders a value equal to true. +The template condition will test if [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. ```yaml automation: condition: platform: template - value_template: '{% raw %}{{ state.attributes.battery }}{% endraw %}' + value_template: '{% raw %}{{ state.attributes.battery > 50 }}{% endraw %}' + # Or value_template could be: + # {% raw %}{% if state.attributes.battery > 50 %}true{% else %}false{% endif %}{% endraw %} ``` #### {% linkable_title Time condition %} diff --git a/source/_components/sensor.arest.markdown b/source/_components/sensor.arest.markdown index 2b95d576628..89326f3db32 100644 --- a/source/_components/sensor.arest.markdown +++ b/source/_components/sensor.arest.markdown @@ -25,6 +25,7 @@ sensor: monitored_variables: - name: temperature unit_of_measurement: '°C' + value_template: '{% raw %}{{ value | round(1) }}{% endraw %}' - name: humidity unit_of_measurement: '%' pins: @@ -43,6 +44,7 @@ Configuration variables: - **monitored_variables** array (*Optional*): List of exposed variables. - **name** (*Required*): The name of the variable you wish to monitor. - **unit** (*Optional*): Defines the units of measurement of the sensor, if any. + - **value_template** (*Optional*): Defines a [template](/getting-started/templating/) 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. - **name** (*Optional*): The name of the variable you wish to monitor. - **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any. From 4ae724bcc6c0d06152cd7b8810b01ac9e82365fc Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 20 Dec 2015 17:33:44 -0800 Subject: [PATCH 10/11] Remove word sensor from sensor titles that do not have multiple platforms --- source/_components/sensor.dweet.markdown | 2 +- source/_components/sensor.efergy.markdown | 2 +- source/_components/sensor.eliqonline.markdown | 2 +- source/_components/sensor.twitch.markdown | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_components/sensor.dweet.markdown b/source/_components/sensor.dweet.markdown index 102d7e9b427..eec0d5d6f84 100644 --- a/source/_components/sensor.dweet.markdown +++ b/source/_components/sensor.dweet.markdown @@ -1,6 +1,6 @@ --- layout: component -title: "Dweet.io sensor" +title: "Dweet.io" description: "Instructions how to integrate Dweet.io sensors within Home Assistant." date: 2015-12-10 10:15 sidebar: true diff --git a/source/_components/sensor.efergy.markdown b/source/_components/sensor.efergy.markdown index 8f58f25b0cb..8a61b44a3f2 100644 --- a/source/_components/sensor.efergy.markdown +++ b/source/_components/sensor.efergy.markdown @@ -1,6 +1,6 @@ --- layout: component -title: "Efergy sensor" +title: "Efergy" description: "Instructions how to integrate Efergy devices within Home Assistant." date: 2015-07-11 0:15 sidebar: true diff --git a/source/_components/sensor.eliqonline.markdown b/source/_components/sensor.eliqonline.markdown index 51ed7c45dff..e8e767b3b17 100644 --- a/source/_components/sensor.eliqonline.markdown +++ b/source/_components/sensor.eliqonline.markdown @@ -1,6 +1,6 @@ --- layout: component -title: "Eliqonline sensor" +title: "Eliqonline" description: "Instructions how to integrate Eliqonline devices within Home Assistant." date: 2015-07-11 0:15 sidebar: true diff --git a/source/_components/sensor.twitch.markdown b/source/_components/sensor.twitch.markdown index 182270cba5d..18f449e00ed 100644 --- a/source/_components/sensor.twitch.markdown +++ b/source/_components/sensor.twitch.markdown @@ -1,6 +1,6 @@ --- layout: component -title: "Twitch sensor" +title: "Twitch" description: "Instructions how to integrate Twitch sensors into Home Assistant." date: 2015-12-19 09:00 sidebar: true From 61192ae960bae41356338a53ecc7004fb0b707c6 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 22 Dec 2015 01:38:06 -0800 Subject: [PATCH 11/11] Finalize release 0.10 blogpost --- source/_components/alexa.markdown | 24 +++-- ...-amazon-echo-icloud-and-templates.markdown | 92 +++++++++++++++++++ source/getting-started/templating.markdown | 6 +- 3 files changed, 114 insertions(+), 8 deletions(-) create mode 100644 source/_posts/2015-12-20-amazon-echo-icloud-and-templates.markdown diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index f9c48dd40bb..8e4d95966b4 100644 --- a/source/_components/alexa.markdown +++ b/source/_components/alexa.markdown @@ -14,19 +14,27 @@ featured: false The Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information within Home Assistant by using your voice. There are no supported sentences out of the box as of now, you will have to define them all yourself. This component does not yet allow the control of devices connected to Home Assistant. +

    + +

    + + ### Requirements before using Amazon requires the endpoint of a skill to be hosted via SSL. Self-signed certificates are ok because our skills will only run in development mode. Read more on [our blog][blog-lets-encrypt] about how to set up encryption for Home Assistant. If you are unable to get https up and running, consider using [this AWS Lambda proxy for Alexa skills](https://forums.developer.amazon.com/forums/thread.jspa?messageID=18604). [blog-lets-encrypt]: https://home-assistant.io/blog/2015/12/13/setup-encryption-using-lets-encrypt/ To get started with Alexa skills: - - log in to [Amazon developer console](https://developer.amazon.com) + + - Log in to [Amazon developer console](https://developer.amazon.com) - Go to Apps & Services => Alexa => Alexa Skill Kit - Get Started - Add a new skill - Name: Home Assistant - Invocation name: home assistant (or be creative, up to you) - Version: 1.0 - - Endpoint: https / https://YOUR_HOST/api/alexa?api_password=YOUR_API_PASSWORD + - Endpoint: + - https + - https://YOUR_HOST/api/alexa?api_password=YOUR_API_PASSWORD ### Configuring your Amazon Alexa skill @@ -69,9 +77,11 @@ This means that we can now ask Alexa things like: ### Configuring Home Assistant -Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on a templates that you define. Each template will have access to the existing state as per the `states` variable but will also have access to all variables defined in the intent. +Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on [templates] that you define. Each template will have access to the existing states via the `states` variable but will also have access to all variables defined in the intent. -The values of `speech/text`, `card/title` and `card/content` will be parsed as a template. +You can use [templates] for the values of `speech/text`, `card/title` and `card/content`. + +[templates]: /getting-started/templating/ Configuring the Alexa component for the above intents would look like this: @@ -88,8 +98,8 @@ alexa: is_state('device_tracker.anne_therese', 'home') -%} You are both home, you silly {%- else -%} - Anne Therese is at {{ states("device_tracker.anne_therese") }} and - Paulus is at {{ states("device_tracker.paulus") }} + Anne Therese is at {{ states("device_tracker.anne_therese") }} and + Paulus is at {{ states("device_tracker.paulus") }} {% endif %} LocateIntent: @@ -97,7 +107,7 @@ alexa: type: plaintext text: > {%- for state in states.device_tracker -%} - {%- if state.name[:4].lower() == User.lower() -%} + {%- if state.name.lower() == User.lower() -%} {{ state.name }} is at {{ state.state }} {%- endif -%} {%- else -%} diff --git a/source/_posts/2015-12-20-amazon-echo-icloud-and-templates.markdown b/source/_posts/2015-12-20-amazon-echo-icloud-and-templates.markdown new file mode 100644 index 00000000000..c6b8c2729fd --- /dev/null +++ b/source/_posts/2015-12-20-amazon-echo-icloud-and-templates.markdown @@ -0,0 +1,92 @@ +--- +layout: post +title: "0.10: Amazon Echo, iCloud, Dweet.io, Twitch and templating support!" +description: "Home Assistant 0.10 has been released with a bunch of added components and brand new templating support." +date: 2015-12-22 01:30:00 -0800 +date_formatted: "December 22, 2015" +author: Paulus Schoutsen +author_twitter: balloob +comments: true +categories: Release-Notes +# og_image: +--- + +Alrighty, it's time for Home Assistant 0.10. A lot amazing things have changed and sadly we also had to introduce a bunch of backwards incompatible changes. I would like to give a big shoutout to Philip Lundrigan ([@philipbl]) who put a lot in effort in helping the migration to move towards using templates for a wide variety of platforms. + +
    + + + + - Device tracker: [iCloud] platform added ([@xorso], [@kevinpanaro]) + - Frontend: Improved caching using service workers if served over SSL ([@balloob]) + - Sensor: [Twitch] platform added ([@happyleavesaoc]) + - [Template] support ([@balloob], [@philipbl], [@fabaff]) + - Thermostat: [Heatmiser] platform added ([@andylockran]) + - Sensor: [Dweet.io] platform added ([@fabaff]) + - [Alexa/Amazon echo] component added ([@balloob]) + - Device Tracker: [FritzBox] platform added ([@deisi], [@caiuspb]) + - Sensor: [Wink] now supports the Egg minders ([@w1ll1am23]) + - Sensor: [ELIQ Online] platform added ([@molobrakos]) + - Binary sensor: [REST] platform added ([@fabaff]) + - Sensor: [Torque (OBD2)] platform added ([@happyleavesaoc]) + +[iCloud]: /components/device_tracker.icloud/ +[Twitch]: /components/sensor.twitch/ +[Template]: /getting-started/templating/ +[Heatmiser]: /components/thermostat.heatmiser/ +[Dweet.io]: /components/sensor.dweet/ +[Alexa/Amazon echo]: /components/alexa/ +[FritzBox]: /components/device_tracker.fritzbox/ +[Wink]: /components/sensor.wink/ +[ELIQ Online]: /components/sensor.eliqonline/ +[REST]: /components/binary_sensor.rest/ +[Torque (OBD2)]: /components/sensor.torque/ +[@andylockran]: https://github.com/andylockran +[@balloob]: https://github.com/balloob +[@caiuspb]: https://github.com/caiuspb +[@deisi]: https://github.com/deisi +[@fabaff]: https://github.com/fabaff +[@happyleavesaoc]: https://github.com/happyleavesaoc +[@kevinpanaro]: https://github.com/kevinpanaro +[@molobrakos]: https://github.com/molobrakos +[@philipbl]: https://github.com/philipbl +[@w1ll1am23]: https://github.com/w1ll1am23 +[@xorso]: https://github.com/xorso + + + +### Templates + +This release introduces templates. This will allow you to parse data before it gets processed or create messages for notifications on the fly based on data within Home Assistant. The notification component and the new Alexa/Amazon Echo component are both using the new template functionality to render responses. A template editor has been added to the developer tool section in the app so you can get instant feedback if your templates are working or not. + +```jinja2 +The temperature at home is {% raw %}{{ states('sensor.temperature') }}{% endraw %}. +``` + +More information and examples can be found in the [template documentation][Template]. + +### Breaking changes + +Templates will now be the only way to extract data from 'raw' sources like REST, CommandSensor or MQTT. This will replace any specific option that used to do this before. This means that `precision`, `factor`, `attribute` or `json_path` etc will no longer work. + +Affected components and platforms: + + - sensor: [arest][sensor.arest] + - sensor: [command_sensor][sensor.command] + - sensor: [rest][sensor.rest] + - sensor: [MQTT][sensor.mqtt] + - switch: [MQTT][switch.mqtt] + - rollershutter: [MQTT][rollershutter.mqtt] + - light: [MQTT][light.mqtt] + - binary_sensor: [MQTT][binary_sensor.mqtt] + - automation: [numeric_state][automation-numeric-state] + +[sensor.arest]: /components/sensor.arest/ +[sensor.command]: /components/sensor.command_sensor/ +[sensor.rest]: /components/sensor.rest/ +[sensor.mqtt]: /components/sensor.mqtt/ +[switch.mqtt]: /components/switch.mqtt/ +[rollershutter.mqtt]: /components/rollershutter.mqtt/ +[light.mqtt]: /components/light.mqtt/ +[binary_sensor.mqtt]: /components/binary_sensor.mqtt/ +[automation-numeric-state]: /components/automation/#numeric-state-trigger diff --git a/source/getting-started/templating.markdown b/source/getting-started/templating.markdown index 7151428bba2..925221519ee 100644 --- a/source/getting-started/templating.markdown +++ b/source/getting-started/templating.markdown @@ -91,7 +91,11 @@ Home Assistant adds extensions to allow templates to access all of the current s Paulus is at {{ states('device_tracker.paulus')) }}. {% endif %} -{{ states.sensor.temperature | multiply(10) | round(2) }}{% endraw %} +{{ states.sensor.temperature | multiply(10) | round(2) }} + +{% if states('sensor.temperature') | float > 20 %} + It is warm! +{%endif %}{% endraw %} ``` ## {% linkable_title Processing incoming data %}