mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-05-16 16:08:58 +00:00
0b4c6b188b
1) Added missing notifiers to general notifier page and rearranged notifiers to be in alphabetical order. 2) Added documentation about new name property for notifiers and how it works into the service call.
152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
---
|
|
layout: page
|
|
title: "Automation"
|
|
description: "Instructions how to setup automation within Home Assistant."
|
|
date: 2015-01-20 22:36
|
|
sidebar: false
|
|
comments: false
|
|
sharing: true
|
|
footer: true
|
|
---
|
|
|
|
This page will talk about automating Home Assistant using the `automation` component. For more advanced ways of automation, see the [create a component]({{site_root}}/developers/creating_components.html) page.
|
|
|
|
Each part of automation consists of two parts: the trigger part and the action part. The final result will look something like this:
|
|
|
|
```
|
|
automation:
|
|
# Optional alias that the logs will use to refer to the entry
|
|
alias: Sunset notification
|
|
|
|
# Type of trigger and information for the trigger
|
|
platform: state
|
|
state_entity_id: sun.sun
|
|
state_from: 'above_horizon'
|
|
state_to: 'below_horizon'
|
|
|
|
# Action to be done when trigger activated
|
|
execute_service: notify.NOTIFIER_NAME
|
|
service_data: {"message":"The sun has set"}
|
|
```
|
|
|
|
## {% linkable_title Setting up triggers %}
|
|
|
|
#### {% linkable_title Time-based automation %}
|
|
This allows you to trigger actions whenever the time matches your filter. You can setup filters to match on hours, minutes and seconds. Any filter that you omit will match all values.
|
|
|
|
Here are some example values:
|
|
|
|
```
|
|
# Match at the start of every hour
|
|
platform: time
|
|
time_minutes: 0
|
|
time_seconds: 0
|
|
|
|
# Match at 4pm
|
|
platform: time
|
|
time_hours: 16
|
|
time_minutes: 0
|
|
time_seconds: 0
|
|
```
|
|
|
|
#### {% linkable_title State-based automation %}
|
|
This allows you to trigger actions based on state changes of any entity within Home Assistant. You can omit the `state_from` and `state_to` to match all.
|
|
|
|
```
|
|
# Match when the sun sets
|
|
platform: state
|
|
state_entity_id: sun.sun
|
|
state_from: 'above_horizon'
|
|
state_to: 'below_horizon'
|
|
|
|
# Match when a person comes home
|
|
platform: state
|
|
state_entity_id: device_tracker.Paulus_OnePlus_One
|
|
state_from: 'not_home'
|
|
state_to: 'home'
|
|
|
|
# Match when a light turns on
|
|
platform: state
|
|
state_entity_id: light.Ceiling
|
|
state_from: 'off'
|
|
state_to: 'on'
|
|
```
|
|
|
|
<p class='note'>
|
|
Use quotes around your values for <code>state_from</code> and <code>state_to</code> to avoid the YAML parser interpreting some values as booleans.
|
|
</p>
|
|
|
|
#### {% linkable_title MQTT-based automation %}
|
|
This allows you to trigger actions based on messages on an MQTT topic. You can specify an optional payload to match as well.
|
|
|
|
```
|
|
# Match any changes to bathroom light
|
|
platform: mqtt
|
|
mqtt_topic: home/bathroom/light
|
|
|
|
# Match only if bathroom light is turned on
|
|
platform: mqtt
|
|
mqtt_topic: home/bathroom/light
|
|
mqtt_payload: 'on'
|
|
```
|
|
|
|
## {% linkable_title Setting up the action %}
|
|
|
|
Currently the only supported action is calling a service. Services are what devices expose to be controlled, so this will allow us to control anything that Home Assistant can control.
|
|
|
|
```
|
|
# Turn the lights Ceiling and Wall on.
|
|
execute_service: light.turn_on
|
|
service_entity_id: light.Ceiling,light.Wall
|
|
|
|
# Turn the lights Ceiling and Wall on and turn them red.
|
|
execute_service: light.turn_on
|
|
service_entity_id: light.Ceiling,light.Wall
|
|
service_data: {"rgb_color": [255, 0, 0]}
|
|
|
|
# Notify the user
|
|
execute_service: notify.NOTIFIER_NAME
|
|
service_data: {"message":"YAY"}
|
|
```
|
|
|
|
## {% linkable_title Putting it all together %}
|
|
For every combination of a trigger and an action we will have to combine the configuration lines and add it to an `automation` component entry in `configuration.yaml`. You can add an optional `alias` key to the configuration to make the logs more understandable. To setup multiple entries, append 2, 3 etc to the section name. An example of a `configuration.yaml` file:
|
|
|
|
```
|
|
automation:
|
|
alias: Sunset notification
|
|
|
|
platform: state
|
|
state_entity_id: sun.sun
|
|
state_from: 'above_horizon'
|
|
state_to: 'below_horizon'
|
|
|
|
execute_service: notify.NOTIFIER_NAME
|
|
service_data: {"message":"The sun has set"}
|
|
|
|
automation 2:
|
|
alias: Turn lights off at 8am in the morning
|
|
|
|
platform: time
|
|
time_hours: 8
|
|
time_minutes: 0
|
|
time_seconds: 0
|
|
|
|
execute_service: light.turn_off
|
|
|
|
automation 3:
|
|
alias: Turn lights in study room on when Paulus comes home
|
|
|
|
platform: state
|
|
state_entity_id: device_tracker.Paulus_OnePlus
|
|
state_from: 'not_home'
|
|
state_to: 'home'
|
|
|
|
execute_service: homeassistant.turn_on
|
|
service_entity_id: group.Study_Room
|
|
```
|
|
|
|
<p class='note'>
|
|
All configuration entries have to be sequential. If you have <code>automation:</code>, <code>automation 2:</code> and <code>automation 4:</code> then the last one will not be processed.
|
|
</p>
|