jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-24 01:37:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update script docs

Browse Source
This commit is contained in:
Paulus Schoutsen 2016-05-01 19:25:52 +02:00
parent 99536c46da
commit 4be4102776
18 changed files with 417 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
sass/custom/_paulus.scss
View File

@ -113,6 +113,7 @@ article.post, article.page, article.listing {
img, table {
border-radius: 3px;
box-shadow: rgba(0,0,0,0.06) 0 0 10px;
vertical-align: middle;
}
img.no-shadow {

9
source/_components/alexa.markdown
View File

@ -45,7 +45,7 @@ Please note that you can use Haaska and the built-in Alexa component side-by-sid
### {% linkable_title I want to build custom commands to use with Echo %}
The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. There are no supported sentences out of the box as of now, you will have to define them all yourself.
The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. Home Assistant offers no built-in sentences but offers a framework for you to define your own.
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/1Ke3mtWd_cQ" frameborder="0" allowfullscreen></iframe>
@ -113,7 +113,10 @@ Out of the box, the component will do nothing. You have to teach it about all in
You can use [templates] for the values of `speech/text`, `card/title` and `card/content`.
Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
[templates]: /topics/templating/
[Home Assistant Script Syntax]: /getting-started/scripts/
Configuring the Alexa component for the above intents would look like this:
@ -137,8 +140,8 @@ alexa:
LocateIntent:
action:
service: notify.notify
data:
message: Your location has been queried via Alexa.
data_template:
message: The location of {{ User }} has been queried via Alexa.
speech:
type: plaintext
text: >

34
source/_components/script.markdown
View File

@ -11,15 +11,27 @@ logo: home-assistant.png
ha_category: Automation
---
The script component allows users to create a sequence of service calls and delays. Scripts can be started using the service `script/turn_on` and interrupted using the service `script/turn_off`.
The script component allows users to specify a sequence of actions to be executed by Home Assistant when turned on. The script component will create an entity for each script and allow them to be controlled via services.
The sequence of actions is specified using the [Home Assistant Script Syntax].
[Home Assistant Script Syntax]: /getting-started/scripts/
```yaml
# Example configuration.yaml entry
script:
message_temperature:
sequence:
# This is Home Assistant Script Syntax
- service: notify.notify
data_template:
message: Current temperature is {% raw %}{{ states.sensor.temperature.state }}{% endraw %}
# Turns on the bedroom lights and then the living room lights 1 minute later
wakeup:
alias: Wake Up
sequence:
# This is Home Assistant Script Syntax
- event: LOGBOOK_ENTRY
event_data:
name: Paulus
@ -32,10 +44,28 @@ script:
entity_id: group.bedroom
brightness: 100
- delay:
# supports seconds, milliseconds, minutes, hours, etc.
# supports seconds, milliseconds, minutes, hours
minutes: 1
- alias: Living room lights on
service: light.turn_on
data:
entity_id: group.living_room
```
### {% linkable_title Passing parameters in service calls %}
As part of the service, parameters can be passed in that will be made available to the script as variables within templates.
There are two ways to activate scripts. One is using the generic `script.turn_on` service. To pass variables to the script with this service, call it using the following parameters:
```yaml
{
"entity_id": "script.wakeup",
"variables": {
"hello": "world",
"name": "Paulus"
}
}
```
If you are calling the script service directly, for example `script.wakeup`. All service data will be made available as variables.

10
source/_includes/asides/getting_started_navigation.html
View File

@ -21,7 +21,7 @@
<li>{% active_link /getting-started/devices/ Setting up devices %}</li>
<li>{% active_link /getting-started/customizing-devices/ Customizing devices and services %}</li>
<li>{% active_link /getting-started/presence-detection/ Presence Detection %}</li>
<li>{% active_link /getting-started/troubleshooting-configuration/ Troubleshooting configuration.yaml %}</li>
<li>{% active_link /getting-started/troubleshooting-configuration/ Troubleshooting %}</li>
</ul>
</li>
<li>
@ -31,6 +31,14 @@
<li>{% active_link /getting-started/automation-trigger/ Triggers %}</li>
<li>{% active_link /getting-started/automation-condition/ Conditions %}</li>
<li>{% active_link /getting-started/automation-action/ Actions %}</li>
<li>{% active_link /getting-started/automation-templating/ Templates %}</li>
</ul>
</li>
<li>
{% active_link /getting-started/scripts/ Scripts %}
<ul>
<li>{% active_link /getting-started/scripts-service-calls/ Service Calls %}</li>
<li>{% active_link /getting-started/scripts-conditions/ Conditions %}</li>
</ul>
</li>
<li>

31
source/getting-started/automation-action.markdown
View File

@ -9,11 +9,19 @@ sharing: true
footer: true
---
When an automation rule fires, it calls a service. For this service you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness).
The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax] which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness).
You can also call the service to activate [a scene] which will allow you to define how you want your devices to be and have Home Assistant call the right services.
[script syntax]: /getting-started/scripts/
[a scene]: /components/scene/
```yaml
automation:
# Change the light in the kitchen and living room to 150 brightness and color red.
trigger:
platform: sun
event: sunset
action:
service: homeassistant.turn_on
entity_id:
@ -22,15 +30,20 @@ automation:
data:
brightness: 150
rgb_color: [255, 0, 0]
```
```yaml
automation:
automation 2:
# Notify me on my mobile phone of an event
trigger:
platform: sun
event: sunset
offset: -00:30
action:
service: notify.notify
data:
message: Something just happened, better take a look!
# Actions are scripts so can also be a list of actions
- service: notify.notify
data:
message: Beautiful sunset!
- delay: 0:35
- service: notify.notify
data:
message: Oh wow you really missed something great.
```
If you want to specify multiple services to be called, or to include a delay, have a look at the [script component](/components/script/). If you want to describe the desired state of certain entities, check out the [scene component](/components/scene/).

102
source/getting-started/automation-condition.markdown
View File

@ -11,18 +11,6 @@ footer: true
Conditions are an optional part of an automation rule and be used to prevent an action from happening when triggered. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off.
An automation rule can have multiple conditions. By default the action will only fire if all conditions pass. An optional key `condition_type: 'or'` can be set on the automation rule to fire action if any condition matches. In the example below, the automation would trigger if the time is before 05:00 _OR_ after 20:00.
```yaml
automation:
condition_type: or
condition:
- platform: time
before: '05:00'
- platform: time
after: '20:00'
```
If your triggers and conditions are exactly the same, you can use a shortcut to specify conditions. In this case, triggers that are not valid conditions will be ignored.
```yaml
@ -30,92 +18,6 @@ automation:
condition: use_trigger_values
```
#### {% linkable_title Numeric state condition %}
The available conditions for an automation are the same as for the script syntax. So see that page for a [full list of available conditions][script-condition].
This type of condition attempts to parse the state of specified entity as a number and triggers if the value matches all of the above or below thresholds.
Either `above` or `below`, or both need to be specified. If both are used, the condition is true when the value is >= `before` *and** < `after`.
You can optionally use a `value_template` to make the value of the entity the same type of value as the condition.
```yaml
automation:
condition:
platform: numeric_state
entity_id: sensor.temperature
above: 17
below: 25
```
#### {% linkable_title State condition %}
Tests if an entity is a specified state.
```yaml
automation:
condition:
platform: state
entity_id: device_tracker.paulus
state: not_home
# optional: trigger only if state was this for last X time.
for:
hours: 1
minutes: 10
seconds: 5
```
#### {% linkable_title Sun condition %}
The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger](#sun-trigger).
```yaml
automation:
condition:
platform: sun
after: sunset
# Optional offset value
after_offset: "-1:00:00"
```
#### {% linkable_title Template condition %}
The template condition will test if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'.
```yaml
automation:
condition:
platform: template
value_template: '{% raw %}{{ state.attributes.battery > 50 }}{% endraw %}'
# Or value_template could be:
# {% raw %}{% if state.attributes.battery > 50 %}true{% else %}false{% endif %}{% endraw %}
```
#### {% linkable_title Time condition %}
The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week
```yaml
automation:
condition:
platform: time
# At least one of the following is required.
after: '15:00:00'
before: '23:00:00'
weekday:
- mon
- wed
- fri
```
Valid values for `weekday` are (`sun`, `mon`, `tue`, `wed`, `thu`, `fri` & `sat`)
#### {% linkable_title Zone condition %}
Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently this is limited to the [OwnTracks platform](/components/device_tracker.owntracks/) and the [iCloud platform](/components/device_tracker.icloud/).
```yaml
automation:
condition:
platform: zone
entity_id: device_tracker.paulus
zone: zone.home
```
[script-condition]: /getting-started/scripts-conditions/

14
source/getting-started/automation-create-first.markdown
View File

@ -74,7 +74,7 @@ automation:
Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights!
We hook the switch up to Home Assistant and grab the entity ID0 from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on.
We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on.
```yaml
# Example configuration.yaml entry
@ -98,3 +98,15 @@ automation:
service: homeassistant.turn_on
entity_id: group.living_room
```
### {% linkable_title Learn more %}
- [Triggers]
- [Conditions]
- [Actions]
- [Templating] (advanced)
[Triggers]: /getting-started/automation-trigger/
[Conditions]: /getting-started/automation-condition/
[Actions]: /getting-started/automation-action/
[Templating]: /getting-started/automation-templating/

98
source/getting-started/automation-templating.markdown Normal file
View File

@ -0,0 +1,98 @@
---
layout: page
title: "Automation Templating"
description: "Advanced automation documentation using templating."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
In Home Assistant 0.19 we introduced a new powerful feature: variables in scripts and automations. This makes it possible to adjust your condition and action based on the information of the trigger.
The trigger data made is available during template rendering as the `trigger` variable.
```yaml
# Example configuration.yaml entries
automation:
trigger:
platform: state
entity_id: device_tracker.paulus
action:
service: notify.notify
data_template:
message: >{% raw %}
Paulus just changed from {{ trigger.from_state.state }}
to {{ trigger.to_state.state }}{% endraw %}
automation 2:
trigger:
platform: mqtt
topic: /notify/+
action:
service_template: >{% raw %}
notify.{{ trigger.topic.split('/')[-1] }}
data_template:
message: {% raw %}{{ trigger.payload }}{% endraw %}
```
### {% linkable_title Available Trigger Data %}
The following tables show the available trigger data per platform.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `event`.
| `trigger.event` | Event object that matched.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `mqtt`.
| `trigger.topic` | Topic that received payload.
| `trigger.payload` | Payload.
| `trigger.qos` | QOS of payload.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `numeric_state`
| `trigger.entity_id` | Entity ID that we observe.
| `trigger.below` | The below treshold, if any.
| `trigger.above` | The above treshold, if any.
| `trigger.from_state` | The previous state of the entity.
| `trigger.to_state` | The new state that triggered trigger.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `state`
| `trigger.entity_id` | Entity ID that we observe.
| `trigger.from_state` | The previous state of the entity.
| `trigger.to_state` | The new state that triggered trigger.
| `trigger.for` | Timedelta object how long state has been to state, if any.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `sun`
| `trigger.event` | The event that just happened: `sunset` or `sunrise`.
| `trigger.offset` | Timedelta object with offset to the event, if any.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `template`
| `trigger.entity_id` | Entity ID that caused change.
| `trigger.from_state` | Previous state of entity that caused change.
| `trigger.to_state` | New state of entity that caused template to change.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `time`
| `trigger.now` | DateTime object that triggered the time trigger.
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `zone`
| `trigger.entity_id` | Entity ID that we are observing.
| `trigger.from_state` | Previous state of the entity.
| `trigger.to_state` | New state of the entity.
| `trigger.zone` | State object of zone
| `trigger.event` | Event that trigger observed: `enter` or `leave`.

4
source/getting-started/automation-trigger.markdown
View File

@ -53,13 +53,13 @@ automation:
#### {% linkable_title State trigger %}
Triggers when the state of an entity changes. If only entity_id given will match all state changes.
Triggers when the state of tracked entities change. If only entity_id given will match all state changes.
```yaml
automation:
trigger:
platform: state
entity_id: device_tracker.paulus
entity_id: device_tracker.paulus, device_tracker.anne_therese
# Optional
from: 'not_home'
to: 'home'

49
source/getting-started/automation.markdown
View File

@ -11,23 +11,35 @@ footer: true
When all your devices are set up it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) but mainly you'll be using the automation component to set up your own rules.
Home Assistant offers a wide range of automations. In the next few pages we'll try to guide you through all the different possibilities and options. Besides this documentation there are also a couple of people who have made their automation configurations [publicly available][cookbook-config].
[cookbook-config]: /cookbook/#example-configurationyaml
### {% linkable_title The basics of automation %}
Every automation rule consists of triggers, an action to be performed and optional conditions.
Before you can go ahead and create your own automations, it's important to learn the basics. To explore the basics, let's have a look at the following example home automation rule:
Triggers can be anything observed in Home Assistant. For example, it can be a certain point in time or a person coming home, which can be observed by the state changing from `not_home` to `home`.
```text
(trigger) When Paulus arrives home
(condition) and it is after sunset:
(action) Turn the lights in the living room on
```
Actions will call services within Home Assistant. For example, turn a light on, set the temperature on your thermostat or activate a scene.
The example consists of three different parts: a trigger, a condition and an action.
Conditions are used to prevent actions from firing unless certain conditions are met. For example, it is possible to only turn on the light if someone comes home and it is after a certain point in time.
The first line is the 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 difference between a condition and a trigger can be confusing. The difference is that the trigger looks at the event that is happening, e.g., a car engine turning on. Conditions looks at the current state of the system, e.g., is the car engine on.
The second line is the condition part of the automation rule. 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.
The third part is the action which will be performed when a rule is triggered and all conditions are met.For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
<p class='note'>
The difference between a condition and a trigger can be confusing as they are very similar. Triggers are looking at the actions while conditions look at the result: turning a light on vs a light being on.
</p>
### {% linkable_title Exploring the internal state %}
Automation rules are based on the internal state of Home Assistant. This is available for exploring in the app using the developer tools. The first icon will show you the available services and the second icon will show you the current devices.
Each device is represented in Home Assistant as an entity consisting of the following parts:
Automation rules interact directly with the internal state of Home Assistant so you'll need to familiarize yourself with it. Home Assistant exposes it's current state via the developer tools which are available at the bottom of the sidebar in the frontend. The <img src='/images/screenshots/developer-tool-states-icon.png' class='no-shadow' height='38' /> icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
| Name | Description | Example |
| ---- | ----- | ---- |
@ -35,23 +47,8 @@ Each device is represented in Home Assistant as an entity consisting of the foll
| State | The current state of the device. | `home`
| Attributes | Extra data related to the device and/or current state. | `brightness`
A service can be called to have Home Assistant perform an action. Turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light device in your system. Services can be passed parameters to for example tell which device to turn on or what color to use.
State changes can be used as the source of triggers and the current state can be used in conditions.
Actions are all about calling services. To explore the available services open the <img src='/images/screenshots/developer-tool-services-icon.png' class='no-shadow' height='38' /> Services developer tool. Services allow to change anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use.
### {% linkable_title Further reading %}
We went over the basics of creating a home automation rule. Now, go automate!
- Learn about the available [automation triggers](/getting-started/automation-trigger/)
- Learn about the available [automation conditions](/getting-started/automation-condition/)
- Learn about [scripts](/components/script/) to help you trigger multiple actions and delays
- Learn about [scenes](/components/scene/) to help you set many entities at once to your liking
- Setup a [notification platform](/components/#notifications) to sent yourself messages
- For more advanced automation using Python, write your own [custom component](/developers/creating_components/).
- Check out the [slides](http://events.linuxfoundation.org/sites/events/files/slides/OpenIoT%202016%20-%20Automating%20your%20Home%20with%20Home%20Assistant.pdf) from [OpenIoT 2016 summit](http://events.linuxfoundation.org/events/openiot-summit)
<p class='note warning'>
Whenever you write the value <code>on</code> or <code>off</code>, surround it with quotes to avoid
the YAML parser interpreting the values as booleans.
</p>
### [Next step: Your First Automation &raquo;](/getting-started/automation-create-first/)

95
source/getting-started/scripts-conditions.markdown Normal file
View File

@ -0,0 +1,95 @@
---
layout: page
title: "Conditions"
description: "Documentation about all available conditions."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
Conditions can be used within a script or automation to prevent further execution. A condition will look at the system right now. For example a condition can test if a switch is currently turned on or off.
#### {% linkable_title Numeric state condition %}
This type of condition attempts to parse the state of specified entity as a number and triggers if the value matches all of the above or below thresholds.
For above, the condition passes if `value >= above`. For below, the condition passes if `value <= below`. If both `below` and `above` are specified, both tests have to pass.
You can optionally use a `value_template` to process the value of the state before testing it.
```yaml
condition: numeric_state
entity_id: sensor.temperature
above: 17
below: 25
# If your sensor value needs to be adjusted
value_template: {{ float(state.state) + 2 }}
```
#### {% linkable_title State condition %}
Tests if an entity is a specified state.
```yaml
condition: state
entity_id: device_tracker.paulus
state: not_home
# optional: trigger only if state was this for last X time.
for:
hours: 1
minutes: 10
seconds: 5
```
#### {% linkable_title Sun condition %}
The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger](#sun-trigger).
```yaml
condition: sun
after: sunset
# Optional offset value
after_offset: "-1:00:00"
```
#### {% linkable_title Template condition %}
The template condition will test if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'.
```yaml
condition: template
value_template: '{% raw %}{{ state.attributes.battery > 50 }}{% endraw %}'
```
Within an automation, template conditions also have access to the `trigger` variable as [described here][automation-templating].
[automation-templating]: /getting-started/automation-templating/
#### {% linkable_title Time condition %}
The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week
```yaml
condition: time
# At least one of the following is required.
after: '15:00:00'
before: '23:00:00'
weekday:
- mon
- wed
- fri
```
Valid values for `weekday` are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.
#### {% linkable_title Zone condition %}
Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. Currently this is limited to the [OwnTracks platform](/components/device_tracker.owntracks/) and the [iCloud platform](/components/device_tracker.icloud/).
```yaml
condition: zone
entity_id: device_tracker.paulus
zone: zone.home
```

70
source/_topics/service_calls.markdown → source/getting-started/scripts-service-calls.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Service Calls"
description: "Instructions how to call services in Home Assistant."
date: 2016-03-12 12:00 -0800
sidebar: false
sidebar: true
comments: false
sharing: true
footer: true
@ -16,7 +16,7 @@ The configuration options to call a config are the same between all components a
Examples on this page will be given as part of an automation component configuration but different approaches can be used for other components too.
<p class='note'>
Use the service developer tool in the frontend to discover available services.
Use the <img src='/images/screenshots/developer-tool-services-icon.png' class='no-shadow' height='38' /> service developer tool in the frontend to discover available services.
</p>
### {% linkable_title The basics %}
@ -24,13 +24,8 @@ Use the service developer tool in the frontend to discover available services.
Call the service `homeassistant.turn_on` on the entity `group.living_room`. This will turn all members of `group.living_room` on. You can also omit `entity_id` and it will turn on all possible entities.
```yaml
automation:
- trigger:
platform: sun
event: sunset
action:
service: homeassistant.turn_on
entity_id: group.living_room
service: homeassistant.turn_on
entity_id: group.living_room
```
### {% linkable_title Passing data to the service call %}
@ -38,16 +33,11 @@ automation:
You can also specify other parameters beside the entity to target. For example, the light turn on service allows specifying the brightness.
```yaml
automation:
- trigger:
platform: sun
event: sunset
action:
service: light.turn_on
entity_id: group.living_room
data:
brightness: 120
rgb_color: [255, 0, 0]
service: light.turn_on
entity_id: group.living_room
data:
brightness: 120
rgb_color: [255, 0, 0]
```
### {% linkable_title Use templates to decide which service to call %}
@ -55,18 +45,13 @@ automation:
You can use [templating] support to dynamically choose which service to call. For example, you can call a certain service based on if a light is on.
```yaml
automation:
- trigger:
platform: sun
event: sunset
action:
service_template: >
{% raw %}{% if states.sensor.temperature | float > 15 %}
switch.turn_on
{% else %}
switch.turn_off
{% endif %}{% endraw %}
entity_id: switch.ac
service_template: >
{% raw %}{% if states.sensor.temperature | float > 15 %}
switch.turn_on
{% else %}
switch.turn_off
{% endif %}{% endraw %}
entity_id: switch.ac
```
### {% linkable_title Use templates to determine the attributes %}
@ -74,20 +59,15 @@ automation:
Templates can also be used for the data that you pass to the service call.
```yaml
automation:
- trigger:
platform: sun
event: sunset
action:
service_template: thermostat.set_temperature
data_template:
entity_id: >
{% raw %}{% if is_state('device_tracker.paulus', 'home') %}
thermostat.upstairs
{% else %}
thermostat.downstairs
{% endif %}{% endraw %}
temperature: {% raw %}{{ 22 - distance(states.device_tracker.paulus) }}{% endraw %}
service: thermostat.set_temperature
data_template:
entity_id: >
{% raw %}{% if is_state('device_tracker.paulus', 'home') %}
thermostat.upstairs
{% else %}
thermostat.downstairs
{% endif %}{% endraw %}
temperature: {% raw %}{{ 22 - distance(states.device_tracker.paulus) }}{% endraw %}
```
[templating]: /topics/templating/

89
source/getting-started/scripts.markdown Normal file
View File

@ -0,0 +1,89 @@
---
layout: page
title: "Script Syntax"
description: "Documention for the Home Assistant Script Syntax."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
Scripts are a sequence of actions that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in [automations] and [Alexa/Amazon Echo] configurations.
The script syntax basic structure is a list of key/value maps that contain actions. If a script contains only 1 action, the wrapping list can be omitted.
```yaml
# Example script component containing script syntax
script:
example_script:
sequence:
# This is written using the Script Syntax
- service: light.turn_on
entity_id: light.ceiling
- service: notify.notify
data:
message: 'Turned on the ceiling light!'
```
#### {% linkable_title Call a Service %}
The most important one is the action to call a service. This can be done in various ways. For all the different possibilities, have a look at the [service calls page].
```yaml
alias: Bedroom lights on
service: light.turn_on
data:
entity_id: group.bedroom
brightness: 100
```
#### {% linkable_title Test a Condition %}
While executing a script you can add a condition to stop further execution. When a condition does not return `true`, the script will finish. There are many different conditions which are documented at the [conditions page].
```yaml
condition: state
entity_id: device_tracker.paulus
state: 'home'
```
#### {% linkable_title Delay %}
Delays are useful for temporarily suspending your script and start it at a later moment. We support different syntaxes for a delay as shown below.
```yaml
# Waits 1 hour
delay: 01:00
```
```yaml
# Waits 1 minute, 30 seconds
delay: 00:01:30
```
```yaml
# Waits 1 minute
delay:
# supports seconds, minutes, hours, days
minutes: 1
```
#### {% linkable_title Fire an Event %}
This action allows you to fire an event. Events can be used for many things. It could trigger an automation or indicate to another component that something is happening. For instance, in the below example it is used to create an entry in the logbook.
```yaml
event: LOGBOOK_ENTRY
event_data:
name: Paulus
message: is waking up
entity_id: device_tracker.paulus
domain: light
```
[Script component]: /components/script/
[automations]: /getting-started/automation-action/
[Alexa/Amazon Echo]: /components/alexa/
[service calls page]: /getting-started/scripts-service-calls/
[conditions page]: /getting-started/scripts-conditions/

BIN
source/images/screenshots/developer-tool-about-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.7 KiB

BIN
source/images/screenshots/developer-tool-events-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
source/images/screenshots/developer-tool-services-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 KiB

BIN
source/images/screenshots/developer-tool-states-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

BIN
source/images/screenshots/developer-tool-templates-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.2 KiB