Convert documentation to use configuration.yaml

This commit is contained in:
Paulus Schoutsen 2015-02-28 10:26:58 -08:00
parent 111338007d
commit 4108e166ff
19 changed files with 150 additions and 154 deletions

View File

@ -14,19 +14,19 @@ This page will talk about automating Home Assistant using the `automation` compo
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
automation:
# Optional alias that the logs will use to refer to the entry
alias: Sunset notification
# Type of trigger and informatino for the trigger
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
# Type of trigger and informatino 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.notify
service_data={"message":"The sun has set"}
# Action to be done when trigger activated
execute_service: notify.notify
service_data: {"message":"The sun has set"}
```
## Setting up triggers
@ -37,17 +37,16 @@ This allows you to trigger actions whenever the time matches your filter. You ca
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
# 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
```
#### State-based automation
@ -55,22 +54,22 @@ This allows you to trigger actions based on state changes of any entity within H
```
# Match when the sun sets
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
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 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
# Match when a light turns on
platform: state
state_entity_id: light.Ceiling
state_from: off
state_to: on
```
## Setting up the action
@ -78,57 +77,57 @@ state_to=on
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.
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]}
# 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.notify
service_data={"message":"YAY"}
# Notify the user
execute_service: notify.notify
service_data: {"message":"YAY"}
```
## 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 `home-assistant.conf`. 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 `home-assistant.conf` file:
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
automation:
alias: Sunset notification
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
platform: state
state_entity_id: sun.sun
state_from: above_horizon
state_to: below_horizon
execute_service=notify.notify
service_data={"message":"The sun has set"}
execute_service: notify.notify
service_data: {"message":"The sun has set"}
[automation 2]
alias=Turn lights off at 8am in the morning
automation 2:
alias: Turn lights off at 8am in the morning
platform=time
time_hours=8
time_minutes=0
time_seconds=0
platform: time
time_hours: 8
time_minutes: 0
time_seconds: 0
execute_service=light.turn_off
execute_service: light.turn_off
[automation 3]
alias=Turn lights in study room on when Paulus comes home
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
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
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.
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>

View File

@ -11,10 +11,10 @@ footer: true
The browser component provides a service to open urls in the default browser on the host machine.
To load this component, add the following lines to your `home-assistant.conf`:
To load this component, add the following lines to your `configuration.yaml`:
```
[browser]
browser:
```
#### Service `browser/browse_url`

View File

@ -13,10 +13,10 @@ footer: true
Chromecasts have recently received a new API which is not yet supported by Home Assistant. Therefore we currently can only detect them and do not know what they are up to.
</p>
Interacts with Chromecasts on your network. Will be automatically discovered if you setup [the discovery component]({{site_root}}/components/discovery.html). Can also be forced to load by adding the following lines to your `home-assistant.conf`:
Interacts with Chromecasts on your network. Will be automatically discovered if you setup [the discovery component]({{site_root}}/components/discovery.html). Can also be forced to load by adding the following lines to your `configuration.yaml`:
```
[chromecast]
chromecast:
```
## Services

View File

@ -17,16 +17,16 @@ Home Assistant has a built-in component called `device_sun_light_trigger` to hel
This component requires the components [sun]({{site_root/components/sun.html}}), [device_tracker]({{site_root}}/components/device_tracker.html) and [light]({{site_root}}/components/light.html) to be enabled.
To enable this component, add the following lines to your `home-assistant.conf`:
To enable this component, add the following lines to your `configuration.yaml`:
```
[device_sun_light_trigger]
# Specify a specific light/group of lights that has to be turned on
light_group=group.living_room
# Specify which light profile to use when turning lights on
light_profile=relax
# Disable lights being turned off when everybody leaves the house
disable_turn_off=1
device_sun_light_trigger:
# Specify a specific light/group of lights that has to be turned on
light_group: group.living_room
# Specify which light profile to use when turning lights on
light_profile: relax
# Disable lights being turned off when everybody leaves the house
disable_turn_off: 1
```
The options `light_group`, `light_profile` and `disable_turn_off` are optional.

View File

@ -9,14 +9,14 @@ sharing: true
footer: true
---
Home Assistant can get information from your wireless router to track which devices are connected. There are three different types of supported wireless routers: tomato, netgear and luci (OpenWRT). To get started add the following lines to your `home-assistant.conf` (example for Netgear):
Home Assistant can get information from your wireless router to track which devices are connected. There are three different types of supported wireless routers: tomato, netgear and luci (OpenWRT). To get started add the following lines to your `configuration.yaml` (example for Netgear):
```
[device_tracker]
platform=netgear
host=192.168.1.1
username=admin
password=MY_PASSWORD
device_tracker:
platform: netgear
host: 192.168.1.1
username: admin
password: MY_PASSWORD
```
<p class='note' data-title='on Tomato'>
@ -32,7 +32,7 @@ Once tracking, the `device_tracker` component will maintain a file in your confi
As an alternative to the router-based device tracking, it is possible to directly scan the network for devices by using nmap. The IP addresses to scan can be specified in any format that nmap understands, including the network-prefix notation (`192.168.1.1/24`) and the range notation (`192.168.1.1-255`).
```
[device_tracker]
platform=nmap_tracker
hosts=192.168.1.1/24
device_tracker:
platform: nmap_tracker
hosts: 192.168.1.1/24
```

View File

@ -17,10 +17,10 @@ Home Assistant can discover and automatically configure zeroconf/mDNS and uPnP d
It will be able to add Google Chreomcasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user.
To load this component, add the following lines to your `home-assistant.conf`:
To load this component, add the following lines to your `configuration.yaml`:
```
[discovery]
discovery:
```
If you are developing a new platform, please read [how to make your platform discoverable]({{site_root}}/developers/add_new_platform.html#discovery).

View File

@ -11,11 +11,11 @@ footer: true
The `downloader` component provides a service to download files. It will raise an error and not continue to set itself up when the download directory does not exist.
To enable it, add the following lines to your `home-assistant.conf`:
To enable it, add the following lines to your `configuration.yaml`:
```
[downloader]
download_dir=downloads
downloader:
download_dir: downloads
```
#### Service `downloader/download_file`

View File

@ -18,8 +18,8 @@ The `keyboard` component simulates key presses on the host machine. It currently
* `keyboard/media_next_track`
* `keyboard/media_prev_track`
To load this component, add the following lines to your `home-assistant.conf`:
To load this component, add the following lines to your `configuration.yaml`:
```
[keyboard]
keyboard:
```

View File

@ -20,15 +20,15 @@ It supports the following platforms:
Preferred way to setup the Philips Hue platform is through the [the discovery component]({{site_root}}/components/discovery.html). For the Wink light platform enable [the wink component]({{site_root}}/components/wink.html).
If you really feel like enabling the light component directly, add the following lines to your `home-assistant.conf`:
If you want to enable the light component directly, add the following lines to your `configuration.yaml`:
```
[light]
platform=hue
light:
platform: hue
```
<p class='note'>
The light component supports multiple entries in <code>home-assistant.conf</code> by appending a sequential number to the section: <code>[light 2]</code>, <code>[light 3]</code> etc.
The light component supports multiple entries in <code>configuration.yaml</code> by appending a sequential number to the section: <code>light 2:</code>, <code>light 3:</code> etc.
</p>
### Service `light.turn_on`

View File

@ -13,29 +13,29 @@ One of the things most people want at some point in their home automation is to
Home Assistant currently supports the awesome [PushBullet](https://www.pushbullet.com/), a free service to send information between your phones, browsers and friends.
To add PushBullet to your installation, add the following to your `home-assistant.conf` file:
To add PushBullet to your installation, add the following to your `configuration.yaml` file:
```
[notify]
platform=pushbullet
api_key=YOUR_API_KEY
notify:
platform: pushbullet
api_key: YOUR_API_KEY
```
### Automation example
Notifications are great to be used within Home Automation. Below is a an example configuration that you can add to your `home-assistant.conf` to be notified when the sun sets.
Notifications are great to be used within Home Automation. Below is a an example configuration that you can add to your `configuration.yaml` to be notified when the sun sets.
```
[automation]
alias=Sun set notification
automation:
alias: Sun set notification
platform=state
state_entity_id=sun.sun
state_from=above_horizon
state_to=below_horizon
platform: state
state_entity_id: sun.sun
state_from: above_horizon
state_to: below_horizon
execute_service=notify.notify
service_data={"message":"YAY"}
execute_service: notify.notify
service_data: {"message":"YAY"}
```
For more automation examples, see the [getting started with automation page]({{site_root}}/components/automation.html).

View File

@ -13,12 +13,12 @@ The component `simple_alarm` is capable of detecting intruders. It does so by ch
This component depends on the compoments [device_tracker]({{site_root}}/components/device_tracker.html) and [light]({{site_root}}/components/light.html) being setup.
To set it up, add the following lines to your `home-assistant.conf`:
To set it up, add the following lines to your `configuration.yaml`:
```
[simple_alarm]
# Which light/light group has to flash when a known device comes home
known_light=light.Bowl
# Which light/light group has to flash red when light turns on while no one home
unknown_light=group.living_room
simple_alarm:
# Which light/light group has to flash when a known device comes home
known_light: light.Bowl
# Which light/light group has to flash red when light turns on while no one home
unknown_light: group.living_room
```

View File

@ -11,14 +11,14 @@ footer: true
The `sun` component will use your current location to track if the sun is above or below the horizon. This is a common ingredient within Home Automation.
To set it up, add the following lines to your `home-assistant.conf`:
To set it up, add the following lines to your `configuration.yaml`:
```
[homeassistant]
latitude=32.87336
longitude=-117.22743
homeassistant:
latitude: 32.87336
longitude: -117.22743
[sun]
sun:
```
<p class='img'>

View File

@ -11,10 +11,10 @@ footer: true
Shows the values of that sensors that is connected to your Tellstick.
To enable it, add the following lines to your `home-assistant.conf`:
To enable it, add the following lines to your `configuration.yaml`:
```
[tellstick_sensor]
tellstick_sensor:
```
<p class='note warning'>

View File

@ -11,13 +11,13 @@ footer: true
Thermostats offer Home Assistant a peek into the current and target temperature in a house. Some thermostats will also offer an away mode that will lower use of heating/cooling. The only supported thermostat right now is the Nest thermostat.
To set it up, add the following information to your `home-assistant.conf` file:
To set it up, add the following information to your `configuration.yaml` file:
```
[thermostat]
platform=nest
username=myemail@mydomain.com
password=mypassword
thermostat:
platform: nest
username: myemail@mydomain.com
password: mypassword
```
<p class='img'>

View File

@ -20,11 +20,11 @@ To get started with the Wink API, you will first need to get yourself an API acc
<iframe src="https://winkbearertoken.appspot.com"
style='width: 100%; height: 200px; border: 0; margin: 0 auto 15px; border-left: 2px solid #049cdb; padding-left: 15px;'></iframe>
After you have gotten your access token, add the following to your `home-assitant.conf`:
After you have gotten your access token, add the following to your `configuration.yaml`:
```
[wink]
access_token=YOUR_ACCESS_TOKEN
wink:
access_token: YOUR_ACCESS_TOKEN
```
This will connect to the Wink hub and automatically set up any lights, switches and sensors that it finds.

View File

@ -16,7 +16,7 @@ Home Assistent runs a webserver accessible on port 8123.
In the package [`homeassistant.remote`](https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the HTTP API can be found.
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (as specified in your `home-assistant.conf`).
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml`).
<p class='note'>
You can append <code>?api_password=YOUR_PASSWORD</code> to any url to log in automatically.

View File

@ -14,13 +14,13 @@ is easy to built your own. If you are the kind of person that likes to learn fro
The first is [hello_world.py](https://github.com/balloob/home-assistant/blob/master/config/custom_components/hello_world.py), which is the classic Hello World example for Home Assistant. The second one is [example.py](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py) which showcases various ways you can tap into Home Assistant to be notified when certain events occur.
If you want to load these components in Home Assistant, add the following lines to your `home-assistant.conf` file:
If you want to load these components in Home Assistant, add the following lines to your `configuration.yaml` file:
```
[hello_world]
hello_world:
[example]
target=TARGET_ENTITY
example:
target: TARGET_ENTITY
```
`TARGET_ENTITY` should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be `light.Ceiling` or `switch.AC` (if you have these devices with those names).
@ -64,8 +64,8 @@ The Home Assistant object contains three objects to help you interact with the s
If your configuration file containes the following lines:
```
[example]
host=paulusschoutsen.nl
example:
host: paulusschoutsen.nl
```
Then in the setup-method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`.

View File

@ -12,12 +12,11 @@ footer: true
Home Assistant uses [Polymer](https://www.polymer-project.org/) for the frontend. Polymer allows building encapsulated and interoperable custom elements that extend HTML itself.
# {% linkable_title Turning on development mode %}
Home Assistant will by default serve the compiled version of the frontend. To change it so that the components are served separately, update your `home-assistant.conf` to have these lines:
Home Assistant will by default serve the compiled version of the frontend. To change it so that the components are served separately, update your `configuration.yaml` to have these lines:
```
[http]
api_password=YOUR_PASSWORD
development=1
http:
development: 1
```
After turning on development mode, you will have to install the webcomponents that the frontend depends on. You can do this by running the `build_frontend` script.

View File

@ -145,23 +145,21 @@ python3 -m homeassistant
## {% linkable_title Configuring Home Assistant %}
The configuration for Home Assistant lives by default in the `config` folder. The file `home-assistant.conf` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example).
The configuration for Home Assistant lives by default in the `config` folder. The file `configuration.yaml` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/configuration.yaml.example`](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example).
When launched for the first time, Home Assistant will write a default configuration enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the interface.
<p class='note'>
You will have to restart Home Assistant for changes in <code>home-assistant.conf</code> to take effect.
You will have to restart Home Assistant for changes in <code>configuration.yaml</code> to take effect.
</p>
### Password protecting the web interface
The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/home-assistant.conf`. Look for the line that says `[http]` and add the line `api_password=YOUR_PASSWORD` below. Your configuration should now look like this:
The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/configuration.yaml` and add the following to the bottom:
```
[http]
api_password=YOUR_PASSWORD
[discovery]
http:
api_password: YOUR_PASSWORD
```
<p class='note'>