diff --git a/source/_docs/authentication/multi-factor-auth.markdown b/source/_docs/authentication/multi-factor-auth.markdown
index d295b48b4be..240224f0a83 100644
--- a/source/_docs/authentication/multi-factor-auth.markdown
+++ b/source/_docs/authentication/multi-factor-auth.markdown
@@ -94,7 +94,7 @@ message:
homeassistant:
auth_mfa_modules:
- type: totp
- name: Authenticator app
+ name: "Authenticator app"
- type: notify
message: "I almost forget, to get into my clubhouse, you need to say {}"
```
diff --git a/source/_docs/automation/action.markdown b/source/_docs/automation/action.markdown
index 3297a6749ef..74ccbe6f9e7 100644
--- a/source/_docs/automation/action.markdown
+++ b/source/_docs/automation/action.markdown
@@ -11,23 +11,24 @@ You can also call the service to activate [a scene](/integrations/scene/) which
automation:
# Change the light in the kitchen and living room to 150 brightness and color red.
trigger:
- platform: sun
- event: sunset
+ - platform: sun
+ event: sunset
action:
- service: light.turn_on
- data:
- brightness: 150
- rgb_color: [255, 0, 0]
- entity_id:
- - light.kitchen
- - light.living_room
+ - service: light.turn_on
+ target:
+ entity_id:
+ - light.kitchen
+ - light.living_room
+ data:
+ brightness: 150
+ rgb_color: [255, 0, 0]
automation 2:
# Notify me on my mobile phone of an event
trigger:
- platform: sun
- event: sunset
- offset: -00:30
+ - platform: sun
+ event: sunset
+ offset: -00:30
variables:
notification_service: notify.paulus_iphone
action:
@@ -47,9 +48,9 @@ Conditions can also be part of an action. You can combine multiple service calls
automation:
- alias: "Office at evening"
trigger:
- platform: state
- entity_id: sensor.office_occupancy
- to: "on"
+ - platform: state
+ entity_id: sensor.office_occupancy
+ to: "on"
action:
- service: notify.notify
data:
diff --git a/source/_docs/automation/basics.markdown b/source/_docs/automation/basics.markdown
index 87a1d384f25..0ad584c5e5e 100644
--- a/source/_docs/automation/basics.markdown
+++ b/source/_docs/automation/basics.markdown
@@ -15,7 +15,7 @@ We can break up this automation into the following three parts:
(action) Turn the lights on in the living room
```
-The first part is the [trigger](/docs/automation/trigger/) of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
+The first part is the [trigger](/docs/automation/trigger/) of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from `not_home` to `home`.
The second part is the [condition](/docs/automation/condition/). Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set.
diff --git a/source/_docs/automation/condition.markdown b/source/_docs/automation/condition.markdown
index b530f18e5de..d9f7076920d 100644
--- a/source/_docs/automation/condition.markdown
+++ b/source/_docs/automation/condition.markdown
@@ -15,19 +15,19 @@ Example of using condition:
automation:
- alias: "Enciende Despacho"
trigger:
- platform: state
- entity_id: sensor.mini_despacho
- to: "on"
+ - platform: state
+ entity_id: sensor.mini_despacho
+ to: "on"
condition:
- condition: or
- conditions:
- - condition: numeric_state
- entity_id: sun.sun
- attribute: elevation
- below: 4
- - condition: numeric_state
- entity_id: sensor.sensorluz_7_0
- below: 10
+ - condition: or
+ conditions:
+ - condition: numeric_state
+ entity_id: sun.sun
+ attribute: elevation
+ below: 4
+ - condition: numeric_state
+ entity_id: sensor.sensorluz_7_0
+ below: 10
action:
- service: scene.turn_on
target:
@@ -44,9 +44,9 @@ The `condition` option of an automation, also accepts a single condition templat
automation:
- alias: "Enciende Despacho"
trigger:
- platform: state
- entity_id: sensor.mini_despacho
- to: "on"
+ - platform: state
+ entity_id: sensor.mini_despacho
+ to: "on"
condition: "{{ state_attr('sun.sun', 'elevation') < 4 }}"
action:
- service: scene.turn_on
diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown
index 0b72cd1e459..38da81fa0bf 100644
--- a/source/_docs/automation/templating.markdown
+++ b/source/_docs/automation/templating.markdown
@@ -127,19 +127,19 @@ The following tables show the available trigger data per platform.
# Example configuration.yaml entries
automation:
trigger:
- platform: state
- entity_id: device_tracker.paulus
+ - platform: state
+ entity_id: device_tracker.paulus
action:
- service: notify.notify
- data:
- message: >
- Paulus just changed from {{ trigger.from_state.state }}
- to {{ trigger.to_state.state }}
+ - service: notify.notify
+ data:
+ message: >
+ Paulus just changed from {{ trigger.from_state.state }}
+ to {{ trigger.to_state.state }}
automation 2:
trigger:
- platform: mqtt
- topic: /notify/+
+ - platform: mqtt
+ topic: "/notify/+"
action:
service: >
notify.{{ trigger.topic.split('/')[-1] }}
diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown
index 55ee1a5d69d..8f8a730b958 100644
--- a/source/_docs/automation/trigger.markdown
+++ b/source/_docs/automation/trigger.markdown
@@ -3,7 +3,7 @@ title: "Automation Trigger"
description: "All the different ways how automations can be triggered."
---
-### What are triggers
+## What are triggers
Triggers are what starts the processing of an automation rule. When _any_ of the automation's triggers becomes true (trigger _fires_), Home Assistant will validate the [conditions](/docs/automation/condition/), if any, and call the [action](/docs/automation/action/).
@@ -11,11 +11,11 @@ An automation can be triggered by an event, with a certain entity state, at a gi
The following sections introduce all trigger types and further details to get started.
-### Trigger variables
+## Trigger variables
Similar to [script level variables](/integrations/script/#variables), `trigger_variables` will be available in trigger templates with the difference that only [limited templates](/docs/configuration/templating/#limited-templates) can be used to pass a value to the trigger variable.
-### Event trigger
+## Event trigger
Fires when an event is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present.
@@ -24,16 +24,16 @@ Events can be fired by integrations or via the API. There is no limitation to th
```yaml
automation:
trigger:
- platform: event
- event_type: MY_CUSTOM_EVENT
- # optional
- event_data:
- mood: happy
- context:
- user_id:
- # any of these will match
- - MY_USER_ID
- - ANOTHER_USER_ID
+ - platform: event
+ event_type: "MY_CUSTOM_EVENT"
+ # optional
+ event_data:
+ mood: happy
+ context:
+ user_id:
+ # any of these will match
+ - "MY_USER_ID"
+ - "ANOTHER_USER_ID"
```
It is also possible to listen for multiple events at once. This is useful for
@@ -42,10 +42,10 @@ event that contain no, or similar, data and contexts.
```yaml
automation:
trigger:
- platform: event
- event_type:
- - automation_reloaded
- - scene_reloaded
+ - platform: event
+ event_type:
+ - automation_reloaded
+ - scene_reloaded
```
It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `event_type`, `event_data` and `context` options.
@@ -65,36 +65,36 @@ automation:
node: ac
value: on
trigger:
- platform: event
- event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}"
+ - platform: event
+ event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}"
```
{% endraw %}
-### Home Assistant trigger
+## Home Assistant trigger
Fires when Home Assistant starts up or shuts down.
```yaml
automation:
trigger:
- platform: homeassistant
- # Event can also be 'shutdown'
- event: start
+ - platform: homeassistant
+ # Event can also be 'shutdown'
+ event: start
```
-### MQTT trigger
+## MQTT trigger
Fires when a specific message is received on given MQTT topic. Optionally can match on the payload being sent over the topic. The default payload encoding is 'utf-8'. For images and other byte payloads use `encoding: ''` to disable payload decoding completely.
```yaml
automation:
trigger:
- platform: mqtt
- topic: living_room/switch/ac
- # Optional
- payload: "on"
- encoding: "utf-8"
+ - platform: mqtt
+ topic: "living_room/switch/ac"
+ # Optional
+ payload: "on"
+ encoding: "utf-8"
```
The `payload` option can be combined with a `value_template` to process the message received on the given MQTT topic before matching it with the payload.
@@ -105,10 +105,10 @@ The trigger in the example below will trigger only when the message received on
```yaml
automation:
trigger:
- platform: mqtt
- topic: "living_room/switch/ac"
- payload: "on"
- value_template: "{{ value_json.state }}"
+ - platform: mqtt
+ topic: "living_room/switch/ac"
+ payload: "on"
+ value_template: "{{ value_json.state }}"
```
{% endraw %}
@@ -130,16 +130,16 @@ automation:
node: "ac"
value: "on"
trigger:
- platform: mqtt
- topic: "{{ room ~ '/switch/' ~ node}}"
- # Optional
- payload: "{{ 'state:' ~ value }}"
- encoding: "utf-8"
+ - platform: mqtt
+ topic: "{{ room ~ '/switch/' ~ node}}"
+ # Optional
+ payload: "{{ 'state:' ~ value }}"
+ encoding: "utf-8"
```
{% endraw %}
-### Numeric state trigger
+## Numeric state trigger
Fires when the numeric value of an entity's state (or attribute's value if using the `attribute` property) crosses a given threshold. On state change of a specified entity, attempts to parse the state as a number and fires if the value is changing from above to below or from below to above the given threshold.
@@ -148,20 +148,20 @@ Fires when the numeric value of an entity's state (or attribute's value if using
```yaml
automation:
trigger:
- platform: numeric_state
- entity_id: sensor.temperature
- # Optional
- value_template: "{{ state.attributes.battery }}"
- # At least one of the following required
- above: 17
- below: 25
- # If given, will trigger when the value of the given attribute for the given entity changes
- attribute: attribute_name
- # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds.
- for:
- hours: 1
- minutes: 10
- seconds: 5
+ - platform: numeric_state
+ entity_id: sensor.temperature
+ # Optional
+ value_template: "{{ state.attributes.battery }}"
+ # At least one of the following required
+ above: 17
+ below: 25
+ # If given, will trigger when the value of the given attribute for the given entity changes
+ attribute: attribute_name
+ # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds.
+ for:
+ hours: 1
+ minutes: 10
+ seconds: 5
```
{% endraw %}
@@ -177,11 +177,11 @@ the trigger more dynamic, like:
```yaml
automation:
trigger:
- platform: numeric_state
- entity_id: sensor.temperature
- # input_number entity id can be specified for above and/or below thresholds
- above: input_number.temperature_threshold_high
- below: input_number.temperature_threshold_low
+ - platform: numeric_state
+ entity_id: sensor.temperature
+ # input_number entity id can be specified for above and/or below thresholds
+ above: input_number.temperature_threshold_high
+ below: input_number.temperature_threshold_low
```
The `for:` can also be specified as `HH:MM:SS` like this:
@@ -191,16 +191,16 @@ The `for:` can also be specified as `HH:MM:SS` like this:
```yaml
automation:
trigger:
- platform: numeric_state
- entity_id: sensor.temperature
- # Optional
- value_template: "{{ state.attributes.battery }}"
- # At least one of the following required
- above: 17
- below: 25
+ - platform: numeric_state
+ entity_id: sensor.temperature
+ # Optional
+ value_template: "{{ state.attributes.battery }}"
+ # At least one of the following required
+ above: 17
+ below: 25
- # If given, will trigger when condition has been for X time.
- for: "01:10:05"
+ # If given, will trigger when condition has been for X time.
+ for: "01:10:05"
```
{% endraw %}
@@ -212,26 +212,26 @@ You can also use templates in the `for` option.
```yaml
automation:
trigger:
- platform: numeric_state
- entity_id:
- - sensor.temperature_1
- - sensor.temperature_2
- above: 80
- for:
- minutes: "{{ states('input_number.high_temp_min')|int }}"
- seconds: "{{ states('input_number.high_temp_sec')|int }}"
+ - platform: numeric_state
+ entity_id:
+ - sensor.temperature_1
+ - sensor.temperature_2
+ above: 80
+ for:
+ minutes: "{{ states('input_number.high_temp_min')|int }}"
+ seconds: "{{ states('input_number.high_temp_sec')|int }}"
action:
- service: persistent_notification.create
- data:
- message: >
- {{ trigger.to_state.name }} too high for {{ trigger.for }}!
+ - service: persistent_notification.create
+ data:
+ message: >
+ {{ trigger.to_state.name }} too high for {{ trigger.for }}!
```
{% endraw %}
The `for` template(s) will be evaluated when an entity changes as specified.
-### State trigger
+## State trigger
Fires when the state of any of given entities changes. If only `entity_id` is given, the trigger will fire for all state changes, even if only state attributes change.
If only one of `from_state` or `to_state` are given, the trigger will fire on any matching state change, but not if only attributes change.
@@ -245,14 +245,14 @@ The values you see in your overview will often not be the same as the actual sta
```yaml
automation:
trigger:
- platform: state
- entity_id:
- - device_tracker.paulus
- - device_tracker.anne_therese
- # Optional
- from: "not_home"
- # Optional
- to: "home"
+ - platform: state
+ entity_id:
+ - device_tracker.paulus
+ - device_tracker.anne_therese
+ # Optional
+ from: "not_home"
+ # Optional
+ to: "home"
```
It's possible to give a list of from_states or to_states:
@@ -260,15 +260,15 @@ It's possible to give a list of from_states or to_states:
```yaml
automation:
trigger:
- platform: state
- entity_id: vacuum.test
- from:
- - "cleaning"
- - "returning"
- to: "error"
+ - platform: state
+ entity_id: vacuum.test
+ from:
+ - "cleaning"
+ - "returning"
+ to: "error"
```
-#### Holding a state
+### Holding a state
You can use `for` to have the state trigger only fire if the state holds for some time.
@@ -278,11 +278,11 @@ state for 30 seconds:
```yaml
automation:
trigger:
- platform: state
- entity_id: light.office
- # Must stay "on" for 30 seconds
- to: "on"
- for: "00:00:30"
+ - platform: state
+ entity_id: light.office
+ # Must stay "on" for 30 seconds
+ to: "on"
+ for: "00:00:30"
```
Please note, that when holding a state, changes to attributes are ignored and
@@ -297,11 +297,11 @@ the time specified, but doesn't care about "playing" or "paused".
```yaml
automation:
trigger:
- platform: state
- entity_id: media_player.kitchen
- # Not "off" for 30 minutes
- from: "off"
- for: "00:30:00"
+ - platform: state
+ entity_id: media_player.kitchen
+ # Not "off" for 30 minutes
+ from: "off"
+ for: "00:30:00"
```
Please note, that when using `from`, `to` and `for`, only the value of the
@@ -313,10 +313,10 @@ same for `for` the time specified, regardless of the current state value.
```yaml
automation:
trigger:
- platform: state
- entity_id: media_player.kitchen
- # The media player remained in its current state for 1 hour
- for: "01:00:00"
+ - platform: state
+ entity_id: media_player.kitchen
+ # The media player remained in its current state for 1 hour
+ for: "01:00:00"
```
When the `attribute` option is specified, all of the above works, but only
@@ -328,11 +328,11 @@ For example, this trigger only fires if the boiler was heating for 10 minutes:
```yaml
automation:
trigger:
- platform: state
- entity_id: climate.living_room
- attribute: hvac_action
- to: "heating"
- for: "00:10:00"
+ - platform: state
+ entity_id: climate.living_room
+ attribute: hvac_action
+ to: "heating"
+ for: "00:10:00"
```
You can also use templates in the `for` option.
@@ -342,16 +342,18 @@ You can also use templates in the `for` option.
```yaml
automation:
trigger:
- platform: state
- entity_id: device_tracker.paulus, device_tracker.anne_therese
- to: "home"
- for:
- minutes: "{{ states('input_number.lock_min')|int }}"
- seconds: "{{ states('input_number.lock_sec')|int }}"
+ - platform: state
+ entity_id:
+ - device_tracker.paulus
+ - device_tracker.anne_therese
+ to: "home"
+ for:
+ minutes: "{{ states('input_number.lock_min')|int }}"
+ seconds: "{{ states('input_number.lock_sec')|int }}"
action:
- service: lock.lock
- target:
- entity_id: lock.my_place
+ - service: lock.lock
+ target:
+ entity_id: lock.my_place
```
{% endraw %}
@@ -364,9 +366,9 @@ Use quotes around your values for `from` and `to` to avoid the YAML parser from
-### Sun trigger
+## Sun trigger
-#### Sunset / Sunrise trigger
+### Sunset / Sunrise trigger
Fires when the sun is setting or rising, i.e., when the sun elevation reaches 0°.
@@ -383,14 +385,14 @@ Since the duration of twilight is different throughout the year, it is recommend
```yaml
automation:
trigger:
- platform: sun
- # Possible values: sunset, sunrise
- event: sunset
- # Optional time offset. This example will trigger 45 minutes before sunset.
- offset: "-00:45:00"
+ - platform: sun
+ # Possible values: sunset, sunrise
+ event: sunset
+ # Optional time offset. This example will trigger 45 minutes before sunset.
+ offset: "-00:45:00"
```
-#### Sun elevation trigger
+### Sun elevation trigger
Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most automations intended to run during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example:
@@ -398,17 +400,17 @@ Sometimes you may want more granular control over an automation than simply suns
```yaml
automation:
- alias: "Exterior Lighting on when dark outside"
- trigger:
- platform: numeric_state
- entity_id: sun.sun
- attribute: elevation
- # Can be a positive or negative number
- below: -4.0
- action:
- service: switch.turn_on
- target:
- entity_id: switch.exterior_lighting
+ - alias: "Exterior Lighting on when dark outside"
+ trigger:
+ - platform: numeric_state
+ entity_id: sun.sun
+ attribute: elevation
+ # Can be a positive or negative number
+ below: -4.0
+ action:
+ - service: switch.turn_on
+ target:
+ entity_id: switch.exterior_lighting
```
{% endraw %}
@@ -426,7 +428,7 @@ Although the actual amount of light depends on weather, topography and land cove
A very thorough explanation of this is available in the Wikipedia article about the [Twilight](https://en.wikipedia.org/wiki/Twilight).
-### Tag trigger
+## Tag trigger
Fires when a [tag](/integrations/tag) is scanned. For example, a NFC tag is
scanned using the Home Assistant Companion mobile application.
@@ -434,8 +436,8 @@ scanned using the Home Assistant Companion mobile application.
```yaml
automation:
trigger:
- platform: tag
- tag_id: A7-6B-90-5F
+ - platform: tag
+ tag_id: A7-6B-90-5F
```
Additionally, you can also only trigger if a card is scanned by a specific
@@ -444,9 +446,9 @@ device/scanner by setting the `device_id`:
```yaml
automation:
trigger:
- platform: tag
- tag_id: A7-6B-90-5F
- device_id: 0e19cd3cf2b311ea88f469a7512c307d
+ - platform: tag
+ tag_id: A7-6B-90-5F
+ device_id: 0e19cd3cf2b311ea88f469a7512c307d
```
Or trigger on multiple possible devices for multiple tags:
@@ -454,16 +456,16 @@ Or trigger on multiple possible devices for multiple tags:
```yaml
automation:
trigger:
- platform: tag
- tag_id:
- - A7-6B-90-5F
- - A7-6B-15-AC
- device_id:
- - 0e19cd3cf2b311ea88f469a7512c307d
- - d0609cb25f4a13922bb27d8f86e4c821
+ - platform: tag
+ tag_id:
+ - "A7-6B-90-5F"
+ - "A7-6B-15-AC"
+ device_id:
+ - 0e19cd3cf2b311ea88f469a7512c307d
+ - d0609cb25f4a13922bb27d8f86e4c821
```
-### Template trigger
+## Template trigger
Template triggers work by evaluating a [template](/docs/configuration/templating/) when any of the recognized entities change state. The trigger will fire if the state change caused the template to render 'true' (a non-zero number or any of the strings `true`, `yes`, `on`, `enable`) when it was previously 'false' (anything else).
@@ -476,11 +478,11 @@ With template triggers you can also evaluate attribute changes by using is_state
```yaml
automation:
trigger:
- platform: template
- value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}"
+ - platform: template
+ value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}"
- # If given, will trigger when template remains true for X time.
- for: "00:01:00"
+ # If given, will trigger when template remains true for X time.
+ for: "00:01:00"
```
{% endraw %}
@@ -492,10 +494,10 @@ You can also use templates in the `for` option.
```yaml
automation:
trigger:
- platform: template
- value_template: "{{ is_state('device_tracker.paulus', 'home') }}"
- for:
- minutes: "{{ states('input_number.minutes')|int(0) }}"
+ - platform: template
+ value_template: "{{ is_state('device_tracker.paulus', 'home') }}"
+ for:
+ minutes: "{{ states('input_number.minutes')|int(0) }}"
```
{% endraw %}
@@ -504,23 +506,23 @@ The `for` template(s) will be evaluated when the `value_template` becomes 'true'
Templates that do not contain an entity will be rendered once per minute.
-### Time trigger
+## Time trigger
The time trigger is configured to fire once a day at a specific time, or at a specific time on a specific date. There are three allowed formats:
-#### Time String
+### Time String
A string that represents a time to fire on each day. Can be specified as `HH:MM` or `HH:MM:SS`. If the seconds are not specified, `:00` will be used.
```yaml
automation:
- trigger:
- platform: time
- # Military time format. This trigger will fire at 3:32 PM
- at: "15:32:00"
+ - trigger:
+ - platform: time
+ # Military time format. This trigger will fire at 3:32 PM
+ at: "15:32:00"
```
-#### Input Datetime
+### Input Datetime
The Entity ID of an [Input Datetime](/integrations/input_datetime/).
@@ -535,9 +537,9 @@ has_date | has_time | Description
```yaml
automation:
- trigger:
- platform: state
- entity_id: binary_sensor.motion
- to: "on"
+ - platform: state
+ entity_id: binary_sensor.motion
+ to: "on"
action:
- service: climate.turn_on
target:
@@ -549,69 +551,68 @@ automation:
datetime: >
{{ (now().timestamp() + 2*60*60)
| timestamp_custom('%Y-%m-%d %H:%M:%S') }}
-
- trigger:
- platform: time
- at: input_datetime.turn_off_ac
+ - platform: time
+ at: input_datetime.turn_off_ac
action:
- service: climate.turn_off
- target:
- entity_id: climate.office
+ - service: climate.turn_off
+ target:
+ entity_id: climate.office
```
{% endraw %}
-#### Sensors of datetime device class
+### Sensors of datetime device class
The Entity ID of a [sensor](/integrations/sensor/) with the "timestamp" device class.
```yaml
automation:
- trigger:
- platform: time
- at: sensor.phone_next_alarm
+ - platform: time
+ at: sensor.phone_next_alarm
action:
- service: light.turn_on
- target:
- entity_id: light.bedroom
+ - service: light.turn_on
+ target:
+ entity_id: light.bedroom
```
-#### Multiple Times
+### Multiple Times
Multiple times can be provided in a list. Both formats can be intermixed.
```yaml
automation:
trigger:
- platform: time
- at:
- - input_datetime.leave_for_work
- - "18:30:00"
+ - platform: time
+ at:
+ - input_datetime.leave_for_work
+ - "18:30:00"
```
-### Time pattern trigger
+## Time pattern trigger
With the time pattern trigger, you can match if the hour, minute or second of the current time matches a specific value. You can prefix the value with a `/` to match whenever the value is divisible by that number. You can specify `*` to match any value (when using the web interface this is required, the fields cannot be left empty).
```yaml
automation:
trigger:
- platform: time_pattern
- # Matches every hour at 5 minutes past whole
- minutes: 5
+ - platform: time_pattern
+ # Matches every hour at 5 minutes past whole
+ minutes: 5
automation 2:
trigger:
- platform: time_pattern
- # Trigger once per minute during the hour of 3
- hours: "3"
- minutes: "*"
+ - platform: time_pattern
+ # Trigger once per minute during the hour of 3
+ hours: "3"
+ minutes: "*"
automation 3:
trigger:
- platform: time_pattern
- # You can also match on interval. This will match every 5 minutes
- minutes: "/5"
+ - platform: time_pattern
+ # You can also match on interval. This will match every 5 minutes
+ minutes: "/5"
```
@@ -620,15 +621,15 @@ Do not prefix numbers with a zero - using `'00'` instead of '0' for example will
-### Webhook trigger
+## Webhook trigger
Webhook trigger fires when a web request is made to the webhook endpoint: `/api/webhook/`. The webhook endpoint is created automatically when you set it as the `webhook_id` in an automation trigger.
```yaml
automation:
trigger:
- platform: webhook
- webhook_id: some_hook_id
+ - platform: webhook
+ webhook_id: "some_hook_id"
```
You can run this automation by sending an HTTP POST request to `http://your-home-assistant:8123/api/webhook/some_hook_id`. Here is an example using the **curl** command line program, with an empty data payload:
@@ -641,21 +642,21 @@ Webhook endpoints don't require authentication, other than knowing a valid webho
Note that a given webhook can only be used in one automation at a time. That is, only one automation trigger can use a specific webhook ID.
-### Zone trigger
+## Zone trigger
Zone trigger fires when an entity is entering or leaving the zone. The entity can be either a person, or a device_tracker. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. This includes [GPS Logger](/integrations/gpslogger/), the [OwnTracks platform](/integrations/owntracks/) and the [iCloud platform](/integrations/icloud/).
```yaml
automation:
trigger:
- platform: zone
- entity_id: person.paulus
- zone: zone.home
- # Event is either enter or leave
- event: enter # or "leave"
+ - platform: zone
+ entity_id: person.paulus
+ zone: zone.home
+ # Event is either enter or leave
+ event: enter # or "leave"
```
-### Geolocation trigger
+## Geolocation trigger
Geolocation trigger fires when an entity is appearing in or disappearing from a zone. Entities that are created by a [Geolocation](/integrations/geo_location/) platform support reporting GPS coordinates.
Because entities are generated and removed by these platforms automatically, the entity id normally cannot be predicted. Instead, this trigger requires the definition of a `source`, which is directly linked to one of the Geolocation platforms.
@@ -666,18 +667,17 @@ This isn't for use with `device_tracker` entities. For those look above at the `
-
```yaml
automation:
trigger:
- platform: geo_location
- source: nsw_rural_fire_service_feed
- zone: zone.bushfire_alert_zone
- # Event is either enter or leave
- event: enter # or "leave"
+ - platform: geo_location
+ source: nsw_rural_fire_service_feed
+ zone: zone.bushfire_alert_zone
+ # Event is either enter or leave
+ event: enter # or "leave"
```
-### Device triggers
+## Device triggers
Device triggers encompass a set of events that are defined by an integration. This includes, for example, state changes of sensors as well as button events from remotes.
[MQTT device triggers](/integrations/device_trigger.mqtt/) are set up through autodiscovery.
@@ -686,7 +686,7 @@ In contrast to state triggers, device triggers are tied to a device and not nece
To use a device trigger, set up an automation through the browser frontend.
If you would like to use a device trigger for an automation that is not managed through the browser frontend, you can copy the YAML from the trigger widget in the frontend and paste it into your automation's trigger list.
-### Multiple triggers
+## Multiple triggers
It is possible to specify multiple triggers for the same rule. To do so just prefix the first line of each trigger with a dash (-) and indent the next lines accordingly. Whenever one of the triggers fires, [processing](#what-are-triggers) of your automation rule begins.
@@ -701,7 +701,7 @@ automation:
event: sunset
```
-### Multiple Entity IDs for the same Trigger
+## Multiple Entity IDs for the same Trigger
It is possible to specify multiple entities for the same trigger. To do so add multiple entities using a nested list. The trigger will fire and start, [processing](#what-are-triggers) your automation each time the trigger is true for each entity listed.
diff --git a/source/_docs/automation/yaml.markdown b/source/_docs/automation/yaml.markdown
index 77a869289f0..b8bc80f455a 100644
--- a/source/_docs/automation/yaml.markdown
+++ b/source/_docs/automation/yaml.markdown
@@ -15,8 +15,8 @@ automation: !include automations.yaml
# Labeled automation block
automation kitchen:
-- trigger:
- platform: ...
+ - trigger:
+ - platform: ...
```
You can add as many labeled `automation` blocks as you want.
@@ -53,54 +53,53 @@ automation my_lights:
before: "23:00:00"
action:
# With a single service call, we don't need a '-' before service - though you can if you want to
- service: homeassistant.turn_on
- target:
- entity_id: group.living_room
+ - service: homeassistant.turn_on
+ target:
+ entity_id: group.living_room
# Turn off lights when everybody leaves the house
- alias: "Rule 2 - Away Mode"
trigger:
- platform: state
- entity_id: all
- to: "not_home"
- action:
- service: light.turn_off
- target:
+ - platform: state
entity_id: all
+ to: "not_home"
+ action:
+ - service: light.turn_off
+ target:
+ entity_id: all
# Notify when Paulus leaves the house in the evening
- alias: "Leave Home notification"
trigger:
- platform: zone
- event: leave
- zone: zone.home
- entity_id: device_tracker.paulus
+ - platform: zone
+ event: leave
+ zone: zone.home
+ entity_id: device_tracker.paulus
condition:
- condition: time
- after: "20:00"
+ - condition: time
+ after: "20:00"
action:
- service: notify.notify
- data:
- message: "Paulus left the house"
+ - service: notify.notify
+ data:
+ message: "Paulus left the house"
# Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi component.
- alias: "Xiaomi Cube Action"
initial_state: false
trigger:
- platform: event
- event_type: cube_action
- event_data:
- entity_id: binary_sensor.cube_158d000103a3de
+ - platform: event
+ event_type: cube_action
+ event_data:
+ entity_id: binary_sensor.cube_158d000103a3de
action:
- service: notify.pushover
- data:
- title: "Cube event detected"
- message: "Cube has triggered this event: {{ trigger.event }}"
+ - service: notify.pushover
+ data:
+ title: "Cube event detected"
+ message: "Cube has triggered this event: {{ trigger.event }}"
```
{% endraw %}
-
## Extra options
When writing automations directly in YAML, you will have access to advanced options that are not available in the user interface.
@@ -114,7 +113,7 @@ automation:
- alias: "Automation Name"
initial_state: false
trigger:
- - platform: ...
+ - platform: ...
```
## Migrating your YAML automations to `automations.yaml`
diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown
index c514467a495..2f88a109dc4 100644
--- a/source/_docs/blueprint/schema.markdown
+++ b/source/_docs/blueprint/schema.markdown
@@ -171,10 +171,10 @@ mode: restart
max_exceeded: silent
trigger:
- platform: state
- entity_id: !input motion_entity
- from: "off"
- to: "on"
+ - platform: state
+ entity_id: !input motion_entity
+ from: "off"
+ to: "on"
action:
- service: light.turn_on
diff --git a/source/_docs/blueprint/tutorial.markdown b/source/_docs/blueprint/tutorial.markdown
index d26eaa99bed..97bef2a2254 100644
--- a/source/_docs/blueprint/tutorial.markdown
+++ b/source/_docs/blueprint/tutorial.markdown
@@ -191,17 +191,17 @@ blueprint:
domain: light
trigger:
- platform: state
- entity_id: !input motion_sensor
+ - platform: state
+ entity_id: !input motion_sensor
action:
- service: >
- {% if trigger.to_state.state == "on" %}
- light.turn_on
- {% else %}
- light.turn_off
- {% endif %}
- target: !input target_light
+ - service: >
+ {% if trigger.to_state.state == "on" %}
+ light.turn_on
+ {% else %}
+ light.turn_off
+ {% endif %}
+ target: !input target_light
```
{% endraw %}
diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown
index d1d5396947d..8a42d18bcd5 100644
--- a/source/_docs/configuration/basic.markdown
+++ b/source/_docs/configuration/basic.markdown
@@ -14,17 +14,17 @@ homeassistant:
longitude: 117.22743
elevation: 430
unit_system: metric
- time_zone: America/Los_Angeles
+ time_zone: "America/Los_Angeles"
external_url: "https://www.example.com"
internal_url: "http://homeassistant.local:8123"
allowlist_external_dirs:
- - /usr/var/dumping-ground
- - /tmp
+ - "/usr/var/dumping-ground"
+ - "/tmp"
allowlist_external_urls:
- "http://images.com/image1.png"
media_dirs:
- media: /media
- recordings: /mnt/recordings
+ media: "/media"
+ recordings: "/mnt/recordings"
legacy_templates: false
```
diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown
index 0f93b43382a..61e10fce226 100644
--- a/source/_docs/configuration/devices.markdown
+++ b/source/_docs/configuration/devices.markdown
@@ -25,7 +25,7 @@ sensor:
state_topic: "home/kitchen/temperature"
name: "MQTT Sensor 2"
- platform: rest
- resource: http://IP_ADDRESS/ENDPOINT
+ resource: "http://IP_ADDRESS/ENDPOINT"
name: "Weather"
switch:
@@ -49,7 +49,7 @@ sensor kitchen:
sensor weather:
platform: rest
- resource: http://IP_ADDRESS/ENDPOINT
+ resource: "http://IP_ADDRESS/ENDPOINT"
name: "Weather"
switch 1:
@@ -65,10 +65,12 @@ Once you have several devices set up, it is time to organize them into groups.
Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the {% my developer_states title="States page in the Developer Tools" %}.
```yaml
-# Example configuration.yaml entry showing two styles
+# Example configuration.yaml entry
group:
living_room:
- entities: light.table_lamp, switch.ac
+ entities:
+ - light.table_lamp
+ - switch.ac
bedroom:
entities:
- light.bedroom
diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown
index 21b49a04cfd..9680a6b30e1 100644
--- a/source/_docs/configuration/packages.markdown
+++ b/source/_docs/configuration/packages.markdown
@@ -57,21 +57,22 @@ light:
There are some rules for packages that will be merged:
1. Platform based integrations (`light`, `switch`, etc) can always be merged.
-2. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file.
+2. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file.
For example if we have the following in the main configuration. You are not allowed to re-use "my_input" again for `input_boolean` in a package:
-
+
```yaml
input_boolean:
my_input:
```
+
3. Any integration that is not a platform [1], or dictionaries with Entity ID keys [2] can only be merged if its keys, except those for lists, are solely defined once.
Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the integration name.
-### Create a packages folder
+## Create a packages folder
One way to organize packages is to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a YAML file. This entry in your `configuration.yaml` will load all packages:
@@ -101,7 +102,7 @@ subsystem1_functionality1:
automation:
```
-### Customizing entities with packages
+## Customizing entities with packages
It is possible to [customize entities](/docs/configuration/customizing-devices/) within packages. Just create your customization entries under:
diff --git a/source/_docs/configuration/platform_options.markdown b/source/_docs/configuration/platform_options.markdown
index af528461dc9..f632baa4128 100644
--- a/source/_docs/configuration/platform_options.markdown
+++ b/source/_docs/configuration/platform_options.markdown
@@ -9,7 +9,7 @@ These options are being phased out and are only available for single platform in
Some integrations or platforms (those that are based on the [entity](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py) class) allows various extra options to be set.
-### Entity namespace
+## Entity namespace
By setting an entity namespace, all entities will be prefixed with that namespace. That way `light.bathroom` can become `light.holiday_house_bathroom`.
@@ -20,7 +20,7 @@ light:
entity_namespace: holiday_house
```
-### Scan Interval
+## Scan Interval
Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a `scan_interval` configuration key. In the example below we set up the `your_lights` platform but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds.
diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown
index a829d9e2b7e..975afd8884a 100644
--- a/source/_docs/configuration/remote.markdown
+++ b/source/_docs/configuration/remote.markdown
@@ -15,10 +15,6 @@ Remember to follow the [securing checklist](/docs/configuration/securing/) befor
-
-Home Assistant no longer support remote access via IP address since release 0.77, you have to use a domain name.
-
-
The most common approach is to set up port forwarding (for any port) from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching ` port forwarding instructions`. You can use any free port on your router and forward that to port 8123.
A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/).
diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown
index 8dec4f4c6c5..9fac0e3d9ce 100644
--- a/source/_docs/configuration/secrets.markdown
+++ b/source/_docs/configuration/secrets.markdown
@@ -30,7 +30,7 @@ homeassistant:
The `secrets.yaml` file contains the corresponding password assigned to the identifier.
```yaml
-http_password: YOUR_PASSWORD
+http_password: "YOUR_PASSWORD"
```
## Debugging secrets
diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown
index 5bfbc9d3233..bb7edc22e6a 100644
--- a/source/_docs/configuration/splitting_configuration.markdown
+++ b/source/_docs/configuration/splitting_configuration.markdown
@@ -16,14 +16,14 @@ In this lighter version we will still need what could be called the core snippet
```yaml
homeassistant:
# Name of the location where Home Assistant is running
- name: My Home Assistant Instance
+ name: "My Home Assistant Instance"
# Location required to calculate the time the sun rises and sets
latitude: 37
longitude: -121
# 'metric' for Metric, 'imperial' for Imperial
unit_system: imperial
# Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
- time_zone: America/Los_Angeles
+ time_zone: "America/Los_Angeles"
customize: !include customize.yaml
```
@@ -38,18 +38,18 @@ history:
frontend:
logbook:
http:
- api_password: ImNotTelling!
+ api_password: "ImNotTelling!"
ifttt:
- key: [nope]
+ key: ["nope"]
wink:
- access_token: [wouldn't you]
- refresh_token: [like to know]
+ access_token: ["wouldn't you"]
+ refresh_token: ["like to know"]
zwave:
- usb_path: /dev/ttyUSB0
- config_path: /usr/local/share/python-openzwave/config
+ usb_path: "/dev/ttyUSB0"
+ config_path: "/usr/local/share/python-openzwave/config"
polling_interval: 10000
mqtt:
@@ -88,7 +88,7 @@ Nesting `!include`s (having an `!include` within a file that is itself `!include
```yaml
light:
- platform: group
- name: Bedside Lights
+ name: "Bedside Lights"
entities:
- light.left_bedside_light
- light.right_bedside_light
@@ -104,7 +104,7 @@ where `light-groups.yaml` might look like:
```yaml
- platform: group
- name: Outside Lights
+ name: "Outside Lights"
entities:
- light.porch_lights
- light.patio_lights
@@ -114,11 +114,11 @@ with `light-switches.yaml` containing:
```yaml
- platform: switch
- name: Patio Lights
+ name: "Patio Lights"
entity_id: switch.patio_lights
- platform: switch
- name: Floor Lamp
+ name: "Floor Lamp"
entity_id: switch.floor_lamp_plug
```
@@ -129,8 +129,8 @@ Let's look at the `device_tracker.yaml` file from our example:
```yaml
- platform: owntracks
- platform: nmap_tracker
- hosts: 192.168.2.0/24
home_interval: 3
+ hosts: 192.168.2.0/24
track_new_devices: true
interval_seconds: 40
@@ -164,15 +164,15 @@ This (large) sensor configuration gives us another example:
#### STEAM FRIENDS ##################################
- platform: steam_online
- api_key: [not telling]
+ api_key: ["not telling"]
accounts:
- 76561198012067051
#### TIME/DATE ##################################
- platform: time_date
display_options:
- - 'time'
- - 'date'
+ - "time"
+ - "date"
- platform: worldclock
time_zone: Etc/UTC
name: "UTC"
@@ -303,7 +303,7 @@ alexa:
action:
service: notify.pushover
data:
- message: Your location has been queried via Alexa.
+ message: "Your location has been queried via Alexa."
speech:
type: plaintext
text: >
@@ -341,7 +341,7 @@ alexa:
action:
service: notify.pushover
data:
- message: Your location has been queried via Alexa.
+ message: "Your location has been queried via Alexa."
speech:
type: plaintext
text: >
@@ -376,22 +376,22 @@ speech:
automation:
- alias: "Automation 1"
trigger:
- platform: state
- entity_id: device_tracker.iphone
- to: "home"
+ - platform: state
+ entity_id: device_tracker.iphone
+ to: "home"
action:
- service: light.turn_on
- target:
- entity_id: light.entryway
+ - service: light.turn_on
+ target:
+ entity_id: light.entryway
- alias: "Automation 2"
trigger:
- platform: state
- entity_id: device_tracker.iphone
- from: "home"
+ - platform: state
+ entity_id: device_tracker.iphone
+ from: "home"
action:
- service: light.turn_off
- target:
- entity_id: light.entryway
+ - service: light.turn_off
+ target:
+ entity_id: light.entryway
```
can be turned into:
@@ -407,22 +407,22 @@ automation: !include_dir_merge_list automation/
```yaml
- alias: "Automation 1"
trigger:
- platform: state
- entity_id: device_tracker.iphone
- to: "home"
+ - platform: state
+ entity_id: device_tracker.iphone
+ to: "home"
action:
- service: light.turn_on
- target:
- entity_id: light.entryway
+ - service: light.turn_on
+ target:
+ entity_id: light.entryway
- alias: "Automation 2"
trigger:
- platform: state
- entity_id: device_tracker.iphone
- from: "home"
+ - platform: state
+ entity_id: device_tracker.iphone
+ from: "home"
action:
- service: light.turn_off
- target:
- entity_id: light.entryway
+ - service: light.turn_off
+ target:
+ entity_id: light.entryway
```
It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen [-]). Each file may contain one or more entries.
@@ -434,17 +434,17 @@ It is important to note that when using `!include_dir_merge_list`, you must incl
```yaml
group:
bedroom:
- name: Bedroom
+ name: "Bedroom"
entities:
- light.bedroom_lamp
- light.bedroom_overhead
hallway:
- name: Hallway
+ name: "Hallway"
entities:
- light.hallway
- thermostat.home
front_yard:
- name: Front Yard
+ name: "Front Yard"
entities:
- light.front_porch
- light.security
@@ -465,7 +465,7 @@ group: !include_dir_merge_named group/
```yaml
bedroom:
- name: Bedroom
+ name: "Bedroom"
entities:
- light.bedroom_lamp
- light.bedroom_overhead
@@ -480,7 +480,7 @@ hallway:
```yaml
front_yard:
- name: Front Yard
+ name: "Front Yard"
entities:
- light.front_porch
- light.security
diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown
index 3f3852ffa3c..73b694f2075 100644
--- a/source/_docs/configuration/templating.markdown
+++ b/source/_docs/configuration/templating.markdown
@@ -29,6 +29,7 @@ The frontend has a {% my developer_templates title="template editor tool" %} to
Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates:
{% raw %}
+
```yaml
script:
msg_who_is_home:
@@ -42,6 +43,7 @@ script:
Paulus is at {{ states('device_tracker.paulus') }}.
{% endif %}
```
+
{% endraw %}
### Important Template Rules
@@ -87,20 +89,24 @@ Besides the normal [state object methods and properties](/topics/state_object/),
The next two statements result in the same value if the state exists. The second one will result in an error if the state does not exist.
{% raw %}
+
```text
{{ states('device_tracker.paulus') }}
{{ states.device_tracker.paulus.state }}
```
+
{% endraw %}
Print out a list of all the sensor states:
{% raw %}
+
```text
{% for state in states.sensor %}
{{ state.entity_id }}={{ state.state }},
{% endfor %}
```
+
{% endraw %}
Other state examples:
@@ -128,8 +134,8 @@ Other state examples:
{{ as_timestamp(now()) - as_timestamp(states.binary_sensor.garage_door.last_changed) }}
{{ as_local(states.sensor.time.last_changed) }}
-
```
+
{% endraw %}
### Attributes
@@ -141,6 +147,7 @@ You can print an attribute with `state_attr` if state is defined.
#### Attributes examples
{% raw %}
+
```text
{% if states.device_tracker.paulus %}
{{ state_attr('device_tracker.paulus', 'battery') }}
@@ -148,11 +155,13 @@ You can print an attribute with `state_attr` if state is defined.
??
{% endif %}
```
+
{% endraw %}
With strings:
{% raw %}
+
```text
{% set tracker_name = "paulus"%}
@@ -162,6 +171,7 @@ With strings:
??
{% endif %}
```
+
{% endraw %}
### Working with Groups
@@ -173,22 +183,26 @@ The `expand` function and filter can be used to sort entities and expand groups.
#### Expand examples
{% raw %}
+
```text
{% for tracker in expand('device_tracker.paulus', 'group.child_trackers') %}
{{ state_attr(tracker, 'battery') }}
{%- if not loop.last %}, {% endif -%}
{% endfor %}
```
+
{% endraw %}
The same thing can also be expressed as a filter:
{% raw %}
+
```text
{{ expand(['device_tracker.paulus', 'group.child_trackers'])
| selectattr("attributes.battery", 'defined')
| join(', ', attribute="attributes.battery") }}
```
+
{% endraw %}
### Time
@@ -208,10 +222,12 @@ The same thing can also be expressed as a filter:
- `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks.
{% raw %}
+
```yaml
# 77 minutes before curret time.
{{ now() - timedelta( hours = 1, minutes = 17 ) }}
```
+
{% endraw %}
- Filter `timestamp_local` converts an UNIX timestamp to its string representation as date/time in your local timezone.
@@ -219,13 +235,13 @@ The same thing can also be expressed as a filter:
- Filter `timestamp_custom(format_string, local_time=True)` converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is default. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime).
-
+
[UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) is the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. Therefore, if used as a function's argument, it can be substituted with a numeric value (`int` or `float`).
-
+
If your template is returning a timestamp that should be displayed in the frontend (e.g., as a sensor entity with `device_class: timestamp`), you have to ensure that it is the ISO 8601 format (meaning it has the "T" separator between the date and time portion). Otherwise, frontend rendering on macOS and iOS devices will show an error. The following value template would result in such an error:
{% raw %}
@@ -245,9 +261,11 @@ To fix it, enforce the ISO conversion via `isoformat()`:
{% raw %}
+
```yaml
{{ 120 | timestamp_local }}
```
+
{% endraw %}
### To/From JSON
@@ -263,20 +281,24 @@ In this example, the special character '°' will be automatically escaped in ord
*Template*
{% raw %}
+
```text
{% set temp = {'temperature': 25, 'unit': '°C'} %}
stringified object: {{ temp }}
object|to_json: {{ temp|to_json }}
```
+
{% endraw %}
*Output*
{% raw %}
+
```text
stringified object: {'temperature': 25, 'unit': '°C'}
object|to_json: {"temperature": 25, "unit": "\u00b0C"}
```
+
{% endraw %}
Conversely, `from_json` can be used to de-serialize a JSON string back into an object to make it possible to easily extract usable data.
@@ -284,18 +306,22 @@ Conversely, `from_json` can be used to de-serialize a JSON string back into an o
*Template*
{% raw %}
+
```text
{% set temp = '{"temperature": 25, "unit": "\u00b0C"}'|from_json %}
The temperature is {{ temp.temperature }}{{ temp.unit }}
```
+
{% endraw %}
*Output*
{% raw %}
+
```text
The temperature is 25°C
```
+
{% endraw %}
### Distance
@@ -311,6 +337,7 @@ If only one location is passed in, Home Assistant will measure the distance from
{% raw %}
```text
+
Using Lat Lng coordinates: {{ distance(123.45, 123.45) }}
Using State: {{ distance(states.device_tracker.paulus) }}
@@ -319,6 +346,7 @@ These can also be combined in any combination:
{{ distance(123.45, 123.45, 'device_tracker.paulus') }}
{{ distance('device_tracker.anne_therese', 'device_tracker.paulus') }}
```
+
{% endraw %}
#### Closest examples
@@ -326,35 +354,42 @@ These can also be combined in any combination:
The closest function and filter will find the closest entity to the Home Assisant location:
{% raw %}
+
```text
Query all entities: {{ closest(states) }}
Query all entities of a specific domain: {{ closest(states.device_tracker) }}
Query all entities in group.children: {{ closest('group.children') }}
Query all entities in group.children: {{ closest(states.group.children) }}
```
+
{% endraw %}
Find entities closest to a coordinate or another entity. All previous arguments still apply for second argument.
{% raw %}
+
```text
Closest to a coordinate: {{ closest(23.456, 23.456, 'group.children') }}
Closest to an entity: {{ closest('zone.school', 'group.children') }}
Closest to an entity: {{ closest(states.zone.school, 'group.children') }}
```
+
{% endraw %}
Since closest returns a state, we can combine it with distance too.
{% raw %}
+
```text
{{ closest(states).name }} is {{ distance(closest(states)) }} kilometers away.
```
+
{% endraw %}
The last argument of the closest function has an implicit `expand`, and can take any iterable sequence of states or entity IDs, and will expand groups:
{% raw %}
+
```text
Closest out of given entities:
{{ closest(['group.children', states.device_tracker]) }}
@@ -364,8 +399,12 @@ Closest to some entity:
{{ closest(states.zone.school, ['group.children', states.device_tracker]) }}
```
+{% endraw %}
+
It will also work as a filter over an iterable group of entities or groups:
+{% raw %}
+
```text
Closest out of given entities:
{{ ['group.children', states.device_tracker] | closest }}
@@ -441,9 +480,11 @@ This means that if the incoming values looks like the sample below:
The template for `on` would be:
{% raw %}
+
```yaml
'{{value_json.on}}'
```
+
{% endraw %}
Nested JSON in a response is supported as well:
@@ -464,42 +505,49 @@ Nested JSON in a response is supported as well:
Just use the "Square bracket notation" to get the value.
{% raw %}
+
```yaml
"{{ value_json['values']['temp'] }}"
```
+
{% endraw %}
The following overview contains a couple of options to get the needed values:
+{% raw %}
+
```text
# Incoming value:
{"primes": [2, 3, 5, 7, 11, 13]}
# Extract third prime number
-{% raw %}{{ value_json.primes[2] }}{% endraw %}
+{{ value_json.primes[2] }}
# Format output
-{% raw %}{{ "%+.1f" | value_json }}{% endraw %}
+{{ "%+.1f" | value_json }}
# Math
-{% raw %}{{ value_json | float * 1024 }}{% endraw %}
-{% raw %}{{ float(value_json) * (2**10) }}{% endraw %}
-{% raw %}{{ value_json | log }}{% endraw %}
-{% raw %}{{ log(1000, 10) }}{% endraw %}
-{% raw %}{{ sin(pi / 2) }}{% endraw %}
-{% raw %}{{ cos(tau) }}{% endraw %}
-{% raw %}{{ tan(pi) }}{% endraw %}
-{% raw %}{{ sqrt(e) }}{% endraw %}
+{{ value_json | float * 1024 }}
+{{ float(value_json) * (2**10) }}
+{{ value_json | log }}
+{{ log(1000, 10) }}
+{{ sin(pi / 2) }}
+{{ cos(tau) }}
+{{ tan(pi) }}
+{{ sqrt(e) }}
# Timestamps
-{% raw %}{{ value_json.tst | timestamp_local }}{% endraw %}
-{% raw %}{{ value_json.tst | timestamp_utc }}{% endraw %}
-{% raw %}{{ value_json.tst | timestamp_custom('%Y' True) }}{% endraw %}
+{{ value_json.tst | timestamp_local }}
+{{ value_json.tst | timestamp_utc }}
+{{ value_json.tst | timestamp_custom('%Y' True) }}
```
-To evaluate a response, go to **Developer Tools** -> **Template**, create your output in "Template editor", and check the result.
+{% endraw %}
+
+To evaluate a response, go to **{% my developer_templates title="Developer Tools -> Template" %}**, create your output in "Template editor", and check the result.
{% raw %}
+
```yaml
{% set value_json=
{"name":"Outside",
@@ -511,6 +559,7 @@ To evaluate a response, go to **Developer Tools** -> **Template**, create your o
{{value_json.data.hum[:-1]}}
```
+
{% endraw %}
## Some more things to keep in mind
@@ -524,9 +573,11 @@ If your template uses an `entity_id` that begins with a number (example: `states
The default priority of operators is that the filter (`|`) has priority over everything except brackets. This means that:
{% raw %}
+
```yaml
{{ states('sensor.temperature') | float / 10 | round(2) }}
```
+
{% endraw %}
Would round `10` to 2 decimal places, then divide `states('sensor.temperature')` by `10` (rounded to 2 decimal places so 10.00). This behavior is maybe not the one expected, but priority rules imply that.
diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown
index 34d3677582a..399853c9148 100644
--- a/source/_docs/configuration/troubleshooting.markdown
+++ b/source/_docs/configuration/troubleshooting.markdown
@@ -13,7 +13,7 @@ Whenever an integration or configuration option results in a warning, it will be
When an integration does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the `home-assistant.log` file and see if there are any errors related to your integration you are trying to set up.
-If you have incorrect entries in your configuration files you can use the configuration check command (below) to assist in identifying them.
+If you have incorrect entries in your configuration files you can use the configuration check command (below) to assist in identifying them.
### Problems with the configuration
diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown
index 1bf3d3d238c..e0e4ff9d4de 100644
--- a/source/_docs/configuration/yaml.markdown
+++ b/source/_docs/configuration/yaml.markdown
@@ -5,7 +5,7 @@ description: "Details about YAML to configure Home Assistant."
Home Assistant uses the [YAML](https://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.
-While more and more integrations are configured through the UI, for some, you will add code in your `configuration.yaml` file to specify its settings.
+While more and more integrations are configured through the UI, for some, you will add code in your `configuration.yaml` file to specify its settings.
The following example entry assumes that you would like to set up the [notify integration](/integrations/notify) with the [pushbullet platform](/integrations/pushbullet).
@@ -41,8 +41,8 @@ The other properties (like `name:`) are specified using mappings. Note that the
```yaml
input_select:
threat:
- name: Threat level
-# A collection is used for options
+ name: "Threat level"
+ # A collection is used for options
options:
- 0
- 1
@@ -56,9 +56,9 @@ The following example shows nesting a collection of mappings in a mapping. In Ho
```yaml
sensor:
- platform: mqtt
- state_topic: sensor/topic
+ state_topic: "sensor/topic"
- platform: mqtt
- state_topic: sensor2/topic
+ state_topic: "sensor2/topic"
```
## Including values
@@ -111,7 +111,7 @@ Home Assistant is case sensitive, a state of `'on'` is not the same as `'On'` or
If you're having trouble, check the case that Home Assistant is reporting in the dev-state menu, under *Developer tools*.
-### Booleans
+### Booleans
YAML treats `Y`, `true`, `Yes`, `ON` all as `true` and `n`, `FALSE`, `No`, `off` as `false`. This means that if you want to set the state of an entity to `on` you *must* quote it as `'on'` otherwise it will be translated as setting the state to true. The same applies to `off`.