mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-21 08:16:53 +00:00
Collection of Markdown/YAML cleanups (#16817)
This commit is contained in:
Franck Nijhof
GitHub
parent
f467f4929b
commit
1a49a1b181
@ -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 {}"
|
||||
```
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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] }}
|
||||
|
||||
@ -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
|
||||
|
||||
</div>
|
||||
|
||||
### 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"
|
||||
```
|
||||
|
||||
<div class='note warning'>
|
||||
@ -620,15 +621,15 @@ Do not prefix numbers with a zero - using `'00'` instead of '0' for example will
|
||||
|
||||
</div>
|
||||
|
||||
### Webhook trigger
|
||||
## Webhook trigger
|
||||
|
||||
Webhook trigger fires when a web request is made to the webhook endpoint: `/api/webhook/<webhook_id>`. 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 `
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
```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.
|
||||
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 %}
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
<div class='note tip'>
|
||||
Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the integration name.
|
||||
</div>
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -15,10 +15,6 @@ Remember to follow the [securing checklist](/docs/configuration/securing/) befor
|
||||
|
||||
</div>
|
||||
|
||||
<div class='note'>
|
||||
Home Assistant no longer support remote access via IP address since release 0.77, you have to use a domain name.
|
||||
</div>
|
||||
|
||||
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 `<router model> 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/).
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
<div class='note'>
|
||||
|
||||
|
||||
[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`).
|
||||
|
||||
</div>
|
||||
|
||||
<div class='note warning'>
|
||||
|
||||
|
||||
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()`:
|
||||
</div>
|
||||
|
||||
{% 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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user