jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Re-organisation Documentation and Getting started (#2055)

Browse source 
* Split MQTT documentation

* Add more details

* Move content to /docs

* Enable sidebar

* Move content to /docs

* Enable sidebar

* Move content

* Update links

* Remove wizard stuff

* Enable sidebar

* Minor changes

* Move MQTT parts to /docs

* update links

* Update links and sync content

* Fix link

* Enable sidebar

* Remove navigation

* Remove navigation and other minor updates

* Update links

* Add overview page

* Make title linkable

* Update

* Plit content

* Update links

* Rearrange content

* New getting-started section

* Add icons for docs

* Update for new structure

* Update for new structure

* Add docs navigation

* Add docs overview page

* Remove ecosystem navigation

* Add docs and remove other collections

* Move ecosystem to docs

* Remove duplicate files

* Re-add ecosystem overview

* Move to ecosystem

* Fix permission

* Update navigation

* Remove collection

* Move overview to right folder

* Move mqtt to upper level

* Move notebook to ecosystem

* Remove un-used files

* Add one more rectangle for iOS

* Move two parts back from docs and rename Run step

* Remove colon

* update getting-started section

* Add redirect

* Update

* Update navigation
This commit is contained in:
Fabian Affolter 2017-02-23 11:09:41 +01:00 • committed by GitHub
parent 0677895b5b
commit 481320128f
138 changed files with 1309 additions and 909 deletions
Download patch file Download diff file Expand all files Collapse all files

26
source/getting-started/automation-create-first.markdown → source/getting-started/automation-2.markdown
View file

@ -1,17 +1,18 @@
---
layout: page
title: "Your First Automation"
description: "Step by step guiding through making your first automation."
title: "Your second Automation"
description: "Step by step guiding through making your second automation."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/automation-create-first/
---
Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets**
After the scratch on the Automation surface, let's dive deeper and create the automation rule: **Turn on the lights when the sun sets**
In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights.
We are defining a [trigger](/docs/automation/trigger/) to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights.
```yaml
# Example configuration.yaml entry
@ -26,9 +27,9 @@ automation:
service: light.turn_on
```
Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when HASS starts set `initial_state:` to `False`.
Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when Home Assistant starts set `initial_state:` to `False`.
After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home.
After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a [condition](/docs/automation/condition/) to only turn on the lights if anyone is home.
```yaml
# Example configuration.yaml entry
@ -78,7 +79,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 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.
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](/docs/automation/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
@ -104,14 +105,5 @@ automation:
entity_id: group.living_room
```
### {% linkable_title Learn more %}
### [Next step: Presence detection »](/getting-started/presence-detection/)
- [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/

72
source/getting-started/automation-action.markdown
View file

@ -1,72 +0,0 @@
---
layout: page
title: "Automation Actions"
description: "Automations result in action."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
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:
- 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
action:
# 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.
```
Conditions can also be part of an action. You can combine multiple service calls and conditions in a single action, and they will be processed in the order you put them in. If the result of a condition is false, the action will stop there so any service calls after that condition will not be executed.
```yaml
automation:
- alias: 'Enciende Despacho'
trigger:
platform: state
entity_id: sensor.mini_despacho
to: 'ON'
action:
- service: notify.notify
data:
message: Testing conditional actions
- condition: or
conditions:
- condition: template
value_template: '{% raw %}{{ states.sun.sun.attributes.elevation < 4 }}{% endraw %}'
- condition: template
value_template: '{% raw %}{{ states.sensor.sensorluz_7_0.state < 10 }}{% endraw %}'
- service: scene.turn_on
entity_id: scene.DespiertaDespacho
```

36
source/getting-started/automation-condition.markdown
View file

@ -1,36 +0,0 @@
---
layout: page
title: "Automation Conditions"
description: "Automations can test conditions when invoked."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
Conditions are an optional part of an automation rule and can 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.
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].
Example of using condition:
```yaml
- alias: 'Enciende Despacho'
trigger:
platform: state
entity_id: sensor.mini_despacho
to: 'on'
condition:
condition: or
conditions:
- condition: template
value_template: '{% raw %}{{ states.sun.sun.attributes.elevation < 4 }}{% endraw %}'
- condition: template
value_template: '{% raw %}{{ states.sensor.sensorluz_7_0.state < 10 }}{% endraw %}'
action:
- service: scene.turn_on
entity_id: scene.DespiertaDespacho
```
[script-condition]: /getting-started/scripts-conditions/

64
source/getting-started/automation-examples.markdown
View file

@ -1,64 +0,0 @@
---
layout: page
title: "Automation Examples"
description: "Some automation examples to get you started."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
```yaml
# Example of entry in configuration.yaml
automation:
# Turns on lights 1 hour before sunset if people are home
# and if people get home between 16:00-23:00
- alias: 'Rule 1 Light on in the evening'
trigger:
# Prefix the first line of each trigger configuration
# with a '-' to enter multiple
- platform: sun
event: sunset
offset: '-01:00:00'
- platform: state
entity_id: group.all_devices
state: 'home'
condition:
# Prefix the first line of each condition configuration
# with a '-'' to enter multiple
- condition: state
entity_id: group.all_devices
state: 'home'
- condition: time
after: '16:00:00'
before: '23:00:00'
action:
service: homeassistant.turn_on
entity_id: group.living_room
# Turn off lights when everybody leaves the house
- alias: 'Rule 2 - Away Mode'
trigger:
platform: state
entity_id: group.all_devices
state: 'not_home'
action:
service: light.turn_off
entity_id: group.all_lights
# 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
condition:
condition: time
after: '20:00'
action:
service: notify.notify
data:
message: 'Paulus left the house'
```

130
source/getting-started/automation-templating.markdown
View file

@ -1,130 +0,0 @@
---
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](/topics/templating/) 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] }}{% endraw %}
data_template:
message: {% raw %}{{ trigger.payload }}{% endraw %}
```
## {% linkable_title Important Template Rules %}
There are a few very important rules to remember when writing automation templates:
1. You ***must*** use `data_template` in place of `data` when using templates in the `data` section of a service call.
1. You ***must*** use `service_template` in place of `service` when using templates in the `service` section of a service call.
1. You ***must*** surround single-line templates with double quotes (`"`) or single quotes (`'`).
1. It is advised that you prepare for undefined variables by using `if ... is not none` or the [`default` filter](http://jinja.pocoo.org/docs/dev/templates/#default), or both.
1. It is advised that when comparing numbers, you convert the number(s) to a [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) or an [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) by using the respective [filter](http://jinja.pocoo.org/docs/dev/templates/#list-of-builtin-filters).
1. While the [`float`](http://jinja.pocoo.org/docs/dev/templates/#float) and [`int`](http://jinja.pocoo.org/docs/dev/templates/#int) filters do allow a default fallback value if the conversion is unsuccessful, they do not provide the ability to catch undefined variables.
Remembering these simple rules will help save you from many headaches and endless hours of frustration when using automation templates.
## {% linkable_title Available Trigger Data %}
The following tables show the available trigger data per platform.
### {% linkable_title event %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `event`.
| `trigger.event` | Event object that matched.
### {% linkable_title mqtt %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `mqtt`.
| `trigger.topic` | Topic that received payload.
| `trigger.payload` | Payload.
| `trigger.payload_json` | Dictonary of the JSON parsed payload.
| `trigger.qos` | QOS of payload.
### {% linkable_title numeric_state %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `numeric_state`
| `trigger.entity_id` | Entity ID that we observe.
| `trigger.below` | The below threshold, if any.
| `trigger.above` | The above threshold, if any.
| `trigger.from_state` | The previous [state object] of the entity.
| `trigger.to_state` | The new [state object] that triggered trigger.
### {% linkable_title state %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `state`
| `trigger.entity_id` | Entity ID that we observe.
| `trigger.from_state` | The previous [state object] of the entity.
| `trigger.to_state` | The new [state object] that triggered trigger.
| `trigger.for` | Timedelta object how long state has been to state, if any.
### {% linkable_title sun %}
| 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.
### {% linkable_title template %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `template`
| `trigger.entity_id` | Entity ID that caused change.
| `trigger.from_state` | Previous [state object] of entity that caused change.
| `trigger.to_state` | New [state object] of entity that caused template to change.
### {% linkable_title time %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `time`
| `trigger.now` | DateTime object that triggered the time trigger.
### {% linkable_title zone %}
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `zone`
| `trigger.entity_id` | Entity ID that we are observing.
| `trigger.from_state` | Previous [state object] of the entity.
| `trigger.to_state` | New [state object] of the entity.
| `trigger.zone` | State object of zone
| `trigger.event` | Event that trigger observed: `enter` or `leave`.
[state object]: /topics/state_object/

149
source/getting-started/automation-trigger.markdown
View file

@ -1,149 +0,0 @@
---
layout: page
title: "Automation Trigger"
description: "All the different ways how automations can be triggered."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
Triggers are what starts the processing of an automation rule. It is possible to specify multiple triggers for the same rule. Once a trigger starts, Home Assistant will validate the conditions, if any, and call the action.
### {% linkable_title Event trigger %}
Triggers when an event is being processed. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data to be present.
```yaml
automation:
trigger:
platform: event
event_type: MY_CUSTOM_EVENT
# optional
event_data:
mood: happy
```
For example, to carry out actions when Home Assistant starts, you can use `event_type: homeassistant_start`. See other 'events' supported by Home Assistant [here](https://home-assistant.io/topics/events/).
### {% linkable_title MQTT trigger %}
Triggers when a specific message is received on given topic. Optionally can match on the payload being sent over the topic.
```yaml
automation:
trigger:
platform: mqtt
topic: living_room/switch/ac
# Optional
payload: 'on'
```
### {% linkable_title Numeric state trigger %}
On state change of a specified entity, attempts to parse the state as a number and triggers if value is above and/or below a threshold.
```yaml
automation:
trigger:
platform: numeric_state
entity_id: sensor.temperature
# Optional
value_template: '{% raw %}{{ state.attributes.battery }}{% endraw %}'
# At least one of the following required
above: 17
below: 25
```
### {% linkable_title State trigger %}
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, device_tracker.anne_therese
# Optional
from: 'not_home'
to: 'home'
# Alias for 'to'
state: 'home'
# If given, will trigger when state has been the to state for X time.
for:
hours: 1
minutes: 10
seconds: 5
```
<p class='note warning'>
Use quotes around your values for `from` and `to` to avoid the YAML parser interpreting values as booleans.
</p>
### {% linkable_title Sun trigger %}
Trigger when the sun is setting or rising. An optional time offset can be given to have it trigger for example 45 minutes before sunset, when dusk is setting in.
```yaml
automation:
trigger:
platform: sun
# Possible values: sunset, sunrise
event: sunset
# Optional time offset. This example is 45 minutes.
offset: '-00:45:00'
```
### {% linkable_title Template trigger %}
Template triggers work by evaluating a [template] on each state change. The trigger will fire if the state change caused the template to render 'true'. This is achieved by having the template result in a true boolean expression (`{% raw %}{{ is_state('device_tracker.paulus', 'home') }}{% endraw %}`) or by having the template render 'true' (example below).
With template triggers you can also evaluate attribute changes by using is_state_attr (`{% raw %}{{ is_state_attr('climate.living_room', 'away_mode', 'off') }}{% endraw %}`)
```yaml
automation:
trigger:
platform: template
value_template: "{% raw %}{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}{% endraw %}"
```
### {% linkable_title Time trigger %}
Time can be triggered in many ways. The most common is to specify `after` and trigger at a specific point in time each day. Alternatively, you can also match if the hour, minute or second of the current time has a specific value. You can prefix the value with a `/` to match whenever the value is divisible by that number. You cannot use `after` together with hour, minute or second.
```yaml
automation:
trigger:
platform: time
# Matches every hour at 5 minutes past whole
minutes: 5
seconds: 00
automation 2:
trigger:
platform: time
# When 'after' is used, you cannot also match on hour, minute, seconds.
# Military time format.
after: '15:32:00'
automation 3:
trigger:
platform: time
# You can also match on interval. This will match every 5 minutes
minutes: '/5'
seconds: 00
```
<p class='note warning'>
Remember that if you are using matching to include both `minutes` and `seconds`. Without `seconds`, your automation will trigger 60 times during the matching minute.
</p>
### {% linkable_title Zone trigger %}
Zone triggers can trigger when an entity is entering or leaving the 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/) as well as the [iCloud platform](/components/device_tracker.icloud/).
```yaml
automation:
trigger:
platform: zone
entity_id: device_tracker.paulus
zone: zone.home
# Event is either enter or leave
event: enter # or "leave"
```

25
source/getting-started/automation-troubleshooting.markdown
View file

@ -1,25 +0,0 @@
---
layout: page
title: "Troubleshooting Automations"
description: "Tips on how to troubleshoot your automations."
date: 2016-04-24 08:30 +0100
sidebar: true
comments: false
sharing: true
footer: true
---
You can verify that your automation rules are being initialized correctly by watching both the realtime logs (`homeassistant.log` in the configuration directory) and also the [Logbook](/components/logbook/). The realtime logs will show the rules being initialized (once for each trigger), example:
```plain
INFO [homeassistant.components.automation] Initialized rule Rainy Day
INFO [homeassistant.components.automation] Initialized rule Rainy Day
INFO [homeassistant.components.automation] Initialized rule Rainy Day
INFO [homeassistant.components.automation] Initialized rule Rain is over
```
The Logbook component will show a line entry when an automation is triggered. You can look at the previous entry to determine which trigger in the rule triggered the event.
![Logbook example](/images/components/automation/logbook.png)
[template]: /topics/templating/

57
source/getting-started/automation.markdown
View file

@ -1,54 +1,31 @@
---
layout: page
title: "Automating Home Assistant"
description: "Steps to help you get automation setup in Home Assistant."
date: 2015-09-19 09:40
description: "Instructions to get started with Automation using Home Assistant."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
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 you'll be using the automation component to set up your own rules, for the most part.
When 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 you'll be using the automation component to set up your own rules, for the most part.
Home Assistant offers a wide range of automation configurations. 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 automations [publicly available][cookbook-config].
If you added a random sensor in the previous step then you can use that sensor for your very first automation:
[cookbook-config]: /cookbook/#example-configurationyaml
### {% linkable_title Automation basics %}
Before you can go ahead and create your own automations, it's important to learn the basics. To explore these, let's have a look at the following example home automation rule:
```text
(trigger) When Paulus arrives home
(condition) and it is after sunset:
(action) Turn the lights in the living room on
```yaml
automation:
- alias: Check sensor value and show notification
trigger:
platform: numeric_state
entity_id: sensor.random
above: 10
action:
service: persistent_notification.create
data:
message: "Sensor value greater than 10"
```
The example consists of three different parts: a trigger, a condition and an action.
For further details about automation, please take the next step or the [automation documentation](/docs/automation/).
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 second line is the **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.
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 look at the actions, while conditions look at the results: turning a light on versus a light being on.
</p>
### {% linkable_title Exploring the internal state %}
Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These 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 |
| ---- | ----- | ---- |
| Entity ID | Unique identifier for the entity. | `light.kitchen`
| State | The current state of the device. | `home`
| Attributes | Extra data related to the device and/or current state. | `brightness`
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.
### [Next step: Your First Automation &raquo;](/getting-started/automation-create-first/)
### [Next step: Home Assistant Automation Part 2 &raquo;](/getting-started/automation-2/)

137
source/getting-started/autostart-init.d.markdown
View file

@ -1,137 +0,0 @@
---
layout: page
title: "Autostart using init.d"
description: "Documentation about setting up Home Assistant as a daemon running under init.d."
release_date: 2016-12-02 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant can run as a daemon within init.d with the script below.
### {% linkable_title 1. Copy script %}
Copy the script at the end of this page to `/etc/init.d/hass-daemon`.
After that, set the script to be executable:
```
sudo chmod +x /etc/init.d/hass-daemon
```
### {% linkable_title 2. Select a user. %}
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute hass.
### {% linkable_title 3. Register the daemon with Linux %}
```
sudo update-rc.d hass-daemon defaults
```
### {% linkable_title 4. Install this service %}
```
sudo service hass-daemon install
```
### {% linkable_title 5. Restart Machine %}
That's it. Restart your machine and Home Assistant should start automatically.
If HA does not start, check the log file output for errors at `/var/opt/homeassistant/home-assistant.log`
### {% linkable_title Extra: Running commands before hass executes %}
If any commands need to run before executing hass (like loading a virutal environment), put them in PRE_EXEC. This command must end with a semicolon.
### {% linkable_title Daemon script %}
```
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
PRE_EXEC=""
RUN_AS="USER"
PID_FILE="/var/run/hass.pid"
CONFIG_DIR="/var/opt/homeassistant"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
start() {
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo 'Starting service…' >&2
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
su -c "$CMD" $RUN_AS
echo 'Service started' >&2
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo 'Stopping service…' >&2
kill $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
echo 'Service stopped' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
echo "999999" > $PID_FILE
chown $RUN_AS $PID_FILE
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
}
uninstall() {
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
rm -fv "$PID_FILE"
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```

31
source/getting-started/autostart-macos.markdown
View file

@ -1,31 +0,0 @@
---
layout: page
title: "Autostart on macOS"
description: "Instructions how to setup Home Assistant to launch on Apple macOS."
date: 2015-9-1 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant on boot and make sure it's always running.
To get Home Assistant installed as a background service, run:
```bash
$ hass --script macos install
Home Assistant has been installed. Open it here: http://localhost:8123
```
Home Assistant will log to `~/Library/Logs/homeassistant.log`
To uninstall the service, run:
```bash
$ hass --script macos uninstall
Home Assistant has been uninstalled.
```

49
source/getting-started/autostart-synology.markdown
View file

@ -1,49 +0,0 @@
---
layout: page
title: "Autostart on Synology NAS boot"
description: "Instructions how to setup Home Assistant to launch on boot on Synology NAS."
date: 2015-9-1 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
To get Home Assistant to automatically start when you boot your Synology NAS:
SSH into your synology & login as admin or root
```bash
$ cd /volume1/homeassistant
```
Create "homeassistant.conf" file using the following code
```bash
# only start this service after the httpd user process has started
start on started httpd-user
# stop the service gracefully if the runlevel changes to 'reboot'
stop on runlevel [06]
# run the scripts as the 'http' user. Running as root (the default) is a bad ide
#setuid admin
# exec the process. Use fully formed path names so that there is no reliance on
# the 'www' file is a node.js script which starts the foobar application.
exec /bin/sh /volume1/homeassistant/hass-daemon start
```
Register the autostart
```bash
$ ln -s homeassistant-conf /etc/init/homeassistant-conf
```
Make the relevant files executable:
```bash
$ chmod -r 777 /etc/init/homeassistant-conf
```
That's it - reboot your NAS and Home Assistant should automatically start

107
source/getting-started/autostart-systemd.markdown
View file

@ -1,107 +0,0 @@
---
layout: page
title: "Autostart using systemd"
description: "Instructions how to setup Home Assistant to launch on boot using systemd."
date: 2015-9-1 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
Newer linux distributions are trending towards using `systemd` for managing daemons. Typically, systems based on Fedora, ArchLinux, or Debian (8 or later) use `systemd`. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using `systemd`, you may check with the following command:
```bash
$ ps -p 1 -o comm=
```
If the preceding command returns the string `systemd`, you are likely using `systemd`.
If you want Home Assistant to be launched automatically, an extra step is needed to setup `systemd`. You need a service file to control Home Assistant with `systemd`. If you are using a Raspberry Pi with Raspbian then replace the `[your user]` with `pi` otherwise use your user you want to run Home Assistant. `ExecStart` contains the path to `hass` and this may vary. Check with `whereis hass` for the location.
```bash
$ su -c 'cat <<EOF >> /etc/systemd/system/home-assistant@[your user].service
[Unit]
Description=Home Assistant
After=network.target
[Service]
Type=simple
User=%i
ExecStart=/usr/bin/hass
[Install]
WantedBy=multi-user.target
EOF'
```
If you've setup Home Assistant in `virtualenv` following our [python installation guide](https://home-assistant.io/getting-started/installation-virtualenv/) or [manual installation guide for raspberry pi](https://home-assistant.io/getting-started/installation-raspberry-pi/), the following template should work for you.
```
[Unit]
Description=Home Assistant
After=network.target
[Service]
Type=simple
User=homeassistant
#make sure the virtualenv python binary is used
Environment=VIRTUAL_ENV="/srv/homeassistant"
Environment=PATH="$VIRTUAL_ENV/bin:$PATH"
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"
[Install]
WantedBy=multi-user.target
```
If you want to use docker, the following template should work for you.
```
[Unit]
Description=Home Assistant
Requires=docker.service
After=docker.service
[Service]
Restart=always
RestartSec=3
ExecStart=/usr/bin/docker run --name="home-assistant-%i" -v /home/%i/.homeassistant/:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
ExecStop=/usr/bin/docker stop -t 2 home-assistant-%i
ExecStopPost=/usr/bin/docker rm -f home-assistant-%i
[Install]
WantedBy=multi-user.target
```
You need to reload `systemd` to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.
```bash
$ sudo systemctl --system daemon-reload
$ sudo systemctl enable home-assistant@[your user]
$ sudo systemctl start home-assistant@[your user]
```
If everything went well, `sudo systemctl start home-assistant@[your user]` should give you a positive feedback.
```bash
$ sudo systemctl status home-assistant@[your user] -l
● home-assistant@fab.service - Home Assistant for [your user]
Loaded: loaded (/etc/systemd/system/home-assistant@[your user].service; enabled; vendor preset: disabled)
Active: active (running) since Sat 2016-03-26 12:26:06 CET; 13min ago
Main PID: 30422 (hass)
CGroup: /system.slice/system-home\x2dassistant.slice/home-assistant@[your user].service
├─30422 /usr/bin/python3 /usr/bin/hass
└─30426 /usr/bin/python3 /usr/bin/hass
[...]
```
To get Home Assistant's logging output, simple use `journalctl`.
```bash
$ journalctl -f -u home-assistant@[your user]
```
Because the log can scroll quite quickly, you might want to open a second terminal to view only the errors:
```bash
$ journalctl -f -u home-assistant@[your user] | grep -i 'error'
```

137
source/getting-started/autostart-upstart.markdown
View file

@ -1,137 +0,0 @@
---
layout: page
title: "Autostart using Upstart"
description: "Instructions how to setup Home Assistant to launch on boot using Upstart."
date: 2015-9-1 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04. If you are unsure if your system is using Upstart, you may check with the following command:
```bash
$ ps -p 1 -o comm=
```
If the preceding command returns the string `init`, you are likely using Upstart.
Upstart will launch init scripts that are located in the directory `/etc/init.d/`. A sample init script for systems using Upstart could look like the sample below.
```bash
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
#
# Installation:
# 1) If any commands need to run before executing hass (like loading a
# virutal environment), put them in PRE_EXEC. This command must end with
# a semicolon.
# 2) Set RUN_AS to the username that should be used to execute hass.
# 3) Copy this script to /etc/init.d/
# sudo cp hass-daemon /etc/init.d/hass-daemon
# sudo chmod +x /etc/init.d/hass-daemon
# 4) Register the daemon with Linux
# sudo update-rc.d hass-daemon defaults
# 5) Install this service
# sudo service hass-daemon install
# 6) Restart Machine
#
# After installation, HA should start automatically. If HA does not start,
# check the log file output for errors.
# /var/opt/homeassistant/home-assistant.log
PRE_EXEC=""
RUN_AS="USER"
PID_FILE="/var/run/hass.pid"
CONFIG_DIR="/var/opt/homeassistant"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
start() {
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo 'Starting service…' >&2
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
su -c "$CMD" $RUN_AS
echo 'Service started' >&2
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo 'Stopping service…' >&2
kill -3 $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
echo 'Service stopped' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
echo "999999" > $PID_FILE
chown $RUN_AS $PID_FILE
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
}
uninstall() {
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
rm -fv "$PID_FILE"
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```
To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:
```bash
$ sudo service hass-daemon start
$ sudo service hass-daemon stop
```
When running Home Assistant with this script, the configuration directory will be located at `/var/opt/homeassistant`. This directory will contain a verbose log rather than simply an error log.
When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.

17
source/getting-started/autostart.markdown
View file

@ -1,17 +0,0 @@
---
layout: page
title: "Autostart Home Assistant"
description: "Instructions how to setup Home Assistant to launch on start."
date: 2015-9-1 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
Once you get started with Home Assistant you want it to start automatically when you launch your machine. To help you get started we've compiled a few guides for different systems.
- [Linux - systemd](/getting-started/autostart-systemd/)
- [Linux - Upstart](/getting-started/autostart-upstart/)
- [macOS](/getting-started/autostart-macos/)
- [Synology NAS](/getting-started/autostart-synology/)

66
source/getting-started/basic.markdown
View file

@ -1,66 +0,0 @@
---
layout: page
title: "Setup basic information"
description: "Setting up the basic info of Home Assistant."
date: 2015-03-23 12:50
sidebar: true
comments: false
sharing: true
footer: true
---
By default, Home Assistant will try to detect your location from IP address geolocation. Home Assistant will automatically select a temperature unit and time zone based on this location. You can overwrite this by adding the following information to your `configuration.yaml`:
```yaml
homeassistant:
# Omitted values in this section will be auto detected using freegeoip.io
# Location required to calculate the time the sun rises and sets
latitude: 32.87336
longitude: 117.22743
# Impacts weather/sunrise data (altitude above sea level in meters)
elevation: 430
# 'metric' for Metric, 'imperial' for Imperial
unit_system: metric
# Pick yours from here:
# http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
time_zone: America/Los_Angeles
# Name of the location where Home Assistant is running
name: Home
```
### {% linkable_title Password protecting the web interface %}
First, you'll want to add a password for the Home Assistant web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section:
```yaml
http:
api_password: YOUR_PASSWORD
```
<p class='note warning'>
If you decide to expose your Home Assistant instance to the internet and forget to set a password, your installation could be accessed by everybody.
</p>
See the [HTTP component documentation](/components/http/) for more options, such as the use of HTTPS encryption.
### {% linkable_title Setting up your phone or tablet %}
Home Assistant runs as a self-hosted web application and can be pinned to your home screen (with the new W3C standard). If you're on Android, follow [the visual guide]({{site_root}}/getting-started/android/). For other devices, open Home Assistant on your mobile browser and tap the "Add to Home Screen" (or similar) option.
### {% linkable_title Remote access %}
If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible.
The most common approach is to set up port forwarding 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`.
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/).
Remember: just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post.
If you want the very best security, check out [the instructions how to use Tor to access your home](/cookbook/tor_configuration/).
### [Next step: Setting up devices &raquo;](/getting-started/devices/)

82
source/getting-started/browsers.markdown
View file

@ -1,82 +0,0 @@
---
layout: page
title: "Browsers"
description: "Browser Compatibility List"
date: 2016-06-25 08:00
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant requires a web browser to show the frontend and supports all major modern browsers. We don't test the web interface against all available browsers but this page tracks different browsers on various operating systems and should help you to pick a browser which works.
We would appreciate if you help to keep this page up-to-date and add feedback.
## {% linkable_title Microsoft Windows %}
| Browser | Release | State | Comments |
| :------------------------ |:---------------|:-----------|:-------------------------|
| Internet Explorer ([IE]) | 11 | Not supported | Does not support promises. |
| Microsoft [Edge] | deli. Win 10 | works | Streaming updates not working. |
| [Chrome] | 50.0.2661.102 | works | |
| [Firefox] | 43.0.1 | works | |
| [Iridium] | 48.2 | works | |
| [Opera] | 42.0.2393.351 | works | |
## {% linkable_title macOS %}
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Safari] | | works | |
## {% linkable_title Linux %}
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Firefox] | 49.0 | works | |
| [Midori] | 0.5.11 | works | |
| [Chromium] | 53.0.2785.143 | works | |
| [Conkeror] | 1.0.2 | works | |
| [Konqueror] | | unknown | |
| [Uzbl] | 0.9.0 | works | |
| [Opera] | 42.0.2393.351 | works | |
| [Lynx] | 2.12 | fails | loads empty page |
| [elinks] | | fails | page with manifest and import |
| [w3m] | 0.5.3 | fails | display the icon shown while loading HA |
| [Epiphany] | 3.18.5 | works | |
| [surf] | 0.7 | works | |
## {% linkable_title Android %}
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Chrome] | 50.0.2661.89 | works | Can also be added to desktop |
| [Firefox] | 46.0.1 | works | Can also be added to desktop |
| [Opera] | 42.0.2246.112628 | works | Can also be added to desktop |
## {% linkable_title iOS %}
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Safari] | | works | Can also be added to desktop |
| [Chrome] | | works | |
[Firefox]: https://www.mozilla.org/en-US/firefox/
[Midori]: http://midori-browser.org/
[Chrome]: https://www.google.com/chrome/
[Iridium]: https://iridiumbrowser.de/
[Opera]: http://www.opera.com/
[Edge]: https://www.microsoft.com/en-us/windows/microsoft-edge
[IE]: http://windows.microsoft.com/en-us/internet-explorer/download-ie
[Safari]: http://www.apple.com/safari/
[Chromium]: https://www.chromium.org/
[Conkeror]: http://conkeror.org/
[Konqueror]: https://konqueror.org/
[Uzbl]: http://www.uzbl.org/
[Lynx]: http://lynx.browser.org/
[elinks]: http://elinks.or.cz/
[w3m]: http://w3m.sourceforge.net/
[Epiphany]: https://wiki.gnome.org/Apps/Web
[surf]: http://surf.suckless.org/

35
source/getting-started/configuration.markdown
View file

@ -1,36 +1,27 @@
---
layout: page
title: "Configuring Home Assistant"
description: "Configuring Home Assistant."
date: 2015-03-23 12:50
title: "Configure Home Assistant"
description: "Instructions to get Home Assistant configured."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and appear in the user interface.
When launched for the first time, Home Assistant will write a default configuration file, called `configuration.yaml`, enabling the web interface and [device discovery](/components/discovery/). It can take up to a minute for your devices to be discovered and appear in the user interface.
The location of the folder differs between operating systems:
The `configuration.yaml` is written in [YAML](/docs/configuration/yaml/), stored in [`.homeassistant`](/docs/configuration/), and can be modified with a text editor.
| OS | Path |
| -- | ---- |
| macOS | `~/.homeassistant` |
| Linux | `~/.homeassistant` |
| Windows | `%APPDATA%/.homeassistant` |
See the [components overview page](/components/) to find sample entries for your devices and services. For a sensor that is showing [random values](/components/sensor.random/), the entry would looks like the sample below:
If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`.
```yaml
sensor:
- platform: random
```
Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains components to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality.
The [Setting up devices part](/docs/configuration/devices/) contains of the documentation additional details about adding device and services and [customizization](docs/configuration/customizing-devices/).
<p class='note'>
You will have to restart Home Assistant for changes to `configuration.yaml` to take effect.
</p>
For further details about configuration, please take a look at the [configuration documentation](/docs/configuration/).
If you run into trouble while configuring Home Assistant, have a look at the [configuration troubleshooting page](/getting-started/troubleshooting-configuration/) and at the [configuration.yaml examples](/cookbook/#example-configurationyaml).
<p class='note tip'>
Test any changes to your configuration files from the command line with `hass --script check_config`. This script allows you to test changes without the need to restart Home Assistant.
</p>
### [Next step: Get familiar with YAML &raquo;](/getting-started/yaml/)
### [Next step: Automate Home Assistant &raquo;](/getting-started/automation/)

57
source/getting-started/customizing-devices.markdown
View file

@ -1,57 +0,0 @@
---
layout: page
title: "Customizing devices and services"
description: "Simple customization for devices and services in the frontend."
date: 2016-04-20 06:00
sidebar: true
comments: false
sharing: true
footer: true
---
By default, all of your devices will be visible and have a default icon determined by their domain. You can customize the look and feel of your front page by altering some of these parameters. This can be done by overriding attributes of specific entities.
```yaml
homeassistant:
name: Home
unit_system: metric
# etc
customize:
# Add an entry for each entity that you want to overwrite.
sensor.living_room_motion:
hidden: true
thermostat.family_room:
entity_picture: https://example.com/images/nest.jpg
friendly_name: Nest
switch.wemo_switch_1:
friendly_name: Toaster
entity_picture: /local/toaster.jpg
switch.wemo_switch_2:
friendly_name: Kitchen kettle
icon: mdi:kettle
switch.rfxtrx_switch:
assumed_state: false
```
### {% linkable_title Possible values %}
| Attribute | Description |
| --------- | ----------- |
| `friendly_name` | Name of the entity
| `hidden` | Set to `true` to hide the entity.
| `entity_picture` | Url to use as picture for entity
| `icon` | Any icon from [MaterialDesignIcons.com](http://MaterialDesignIcons.com). Prefix name with `mdi:`, ie `mdi:home`.
| `assumed_state` | For switches with an assumed state two buttons are shown (turn off, turn on) instead of a switch. By setting `assumed_state` to `false` you will get the default switch icon.
| `sensor_class` | Sets the [class of the sensor](/components/binary_sensor/), changing the device state and icon that is displayed on the UI (see below).
### {% linkable_title Reloading customize %}
Home Assistant offers a service to reload the core configuration while Home Assistant is running called `homeassistant/reload_core_config`. This allows you to change your customize section and see it being applied without having to restart Home Assistant. To call this service, go to the <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> service developer tools, select the service `homeassistant/reload_core_config` and click "Call Service".
<p class='note warning'>
New customize information will be applied the next time the state of the entity gets updated.
</p>
### [Next step: Setting up presence detection &raquo;](/getting-started/presence-detection/)

70
source/getting-started/devices.markdown
View file

@ -1,70 +0,0 @@
---
layout: page
title: "Adding devices to Home Assistant"
description: "Steps to help you get your devices in Home Assistant."
date: 2015-09-19 09:40
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component]({{site_root}}/components/discovery/) enabled (the default setting).
See the [components overview page](/components/) to find installation instructions for your devices and services. If you can't find support for your favorite device or service, [consider adding support](/developers/add_new_platform/).
Usually every entity needs its own entry in the `configuration.yaml` file. There are two styles for multiple entries:
#### {% linkable_title Style 1: Collect every entity under the "parent" %}
```yaml
sensor:
- platform: mqtt
state_topic: "home/bedroom/temperature"
name: "MQTT Sensor 1"
- platform: mqtt
state_topic: "home/kitchen/temperature"
name: "MQTT Sensor 2"
- platform: rest
resource: http://IP_ADDRESS/ENDPOINT
switch:
- platform: vera
```
#### {% linkable_title Style 2: List each device separately %}
You need to append numbers or strings to differentiate the entries, as in the example below. The appended number or string must be unique.
```yaml
media_player livingroom:
platform: mpd
server: IP_ADDRESS
media_player kitchen:
platform: plex
camera 1:
platform: generic
camera 2:
platform: mjpeg
```
### {% linkable_title Grouping devices %}
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 Set State page in the Developer Tools (![<>](https://cdn.rawgit.com/Templarian/MaterialDesign/master/icons/svg/code-tags.svg)).
```yaml
# Example configuration.yaml entry showing two styles
group:
living_room: light.table_lamp, switch.ac
bedroom:
- light.bedroom
- media_player.nexus_player
```
For more details please check the [Group](https://home-assistant.io/components/group/) page.
### [Next step: Customizing devices and services &raquo;](/getting-started/customizing-devices/)

129
source/getting-started/hassbian-common-tasks.markdown
View file

@ -1,129 +0,0 @@
---
layout: page
title: "Common tasks on Hassbian"
description: "Instructions how to do common tasks on Hassbian."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
### {% linkable_title Login to the Raspberry Pi %}
To login to your Raspberry Pi running HASSbian your going to be using a ssh client. Depending on your platform there are several alternatives for doing this. Linux and Max OS generally have a ssh client installed. Windows users are recommended to download and install the ssh client [Putty][ssh-putty].
Connect to the Raspberry Pi over ssh. Default user name is `pi` and password is `raspberry`.
Linux and Mac OS users execute the following command in a terminal.
```bash
$ ssh pi@ip-address-of-pi
```
Windows users start [Putty][ssh-putty], enter the IP address of the Raspberry Pi in the *Host name* field and port 22 in the *Port* field. Then click *Open* and a terminal window will open. Enter the credentials. Default user name is `pi` and password is `raspberry`.
Optionally, starting with Windows 10 anniversary update, you can use the built-in '[Bash on Windows][bash-windows]' to use SSH if you have enabled Developer mode and have installed the "Windows Subsystem for Linux (beta)" feature.
### {% linkable_title Start/Stop/Restart Home Assistant %}
Log in as the `pi` account account and execute the following commands:
```bash
$ sudo systemctl stop home-assistant@homeassistant.service
```
Replace `stop` with `start` or `restart` to get the desired functionality.
To get the current state of the `homeassistant.service` replace `stop` with `status`.
### {% linkable_title Update Home Assistant %}
Log in as the `pi` account and execute the following commands:
```bash
$ sudo systemctl stop home-assistant@homeassistant.service
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ pip3 install --upgrade homeassistant
$ exit
$ sudo systemctl start home-assistant@homeassistant.service
```
This will in order do the following:
- Stop the Home Assistant service running on HASSbian
- Open a shell as the `homeassistant` user running the Homeassistant service and that has ownership over the Home Assistant installation.
- Change into the virtual Python environment at `/srv/homeassistant/` containing the Home Assistant installation.
- Upgrade the Home Assistant installation to the latest release.
- Exit the shell and return to the `pi` user.
- Restart the Home Assistant service.
### {% linkable_title Manually launch Home Assistant %}
Log in as the `pi` account and execute the following commands:
```bash
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass
```
This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first.
### {% linkable_title Check your configuration %}
Log in as the `pi` account and execute the following commands:
```bash
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ hass --script check_config
```
This will output any errors in your configuration files to console.
### {% linkable_title Read the Home Assistant log file %}
Log in as the `pi` account and execute the following commands:
```bash
$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano homeassistant.log
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the log file in the nano editor.
Optionaly, you can also view the log with `journalctl`.
Log in as the `pi` account and execute the following commands:
```bash
$ sudo journalctl -fu home-assistant@homeassistant.service
```
### {% linkable_title Edit the Home Assistant configuration %}
Log in as the `pi` account and execute the following commands:
```bash
$ sudo su -s /bin/bash homeassistant
$ cd /home/homeassistant/.homeassistant
$ nano configuration.yaml
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the configuration file in the nano editor.
It's generally recommended that you read the [Getting started][configuring-homeassistant] guide for how to configure Home Assistant.
### {% linkable_title Change locale, timezone and keyboard layout %}
```bash
$ sudo raspi-config
```
[configuring-homeassistant]: /getting-started/configuration/
[ssh-putty]: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
[stop-homeassistant]: /getting-started/installation-raspberry-pi-image/#startstoprestart-home-assistant-on-hassbian
[bash-windows]: https://msdn.microsoft.com/en-us/commandline/wsl/about

22
source/getting-started/hassbian-customization.markdown
View file

@ -1,22 +0,0 @@
---
layout: page
title: "Customization"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
To allow you to customize your installation further, we have included a set of Hassbian scripts.
- Install Samba. Allows anyone on your network to edit your configuration from any computer. This share is unsecured and it's usage is not recommended if you share your network with others.
- Install Libcec. Adds local [HDMI CEC support][cec].
- Install Mossquitto MQTT server. Installs the latest Mosquitto package and client tools from the Mosquitto projects offical repository. Now includes websocket support.
- Install Open Z-Wave. Installs Open Z-Wave and prepares for using a USB or GPIO ZWave controller.
All of these scripts are available in the directory `/home/pi/hassbian-scripts/`. For more information about these scripts have a look at the [hassbian-scripts repository][hassbian-repo].
[hassbian-repo]: https://github.com/home-assistant/hassbian-scripts#the-included-scripts
[cec]: /components/hdmi_cec/

51
source/getting-started/hassbian-installation.markdown
View file

@ -1,51 +0,0 @@
---
layout: page
title: "Installing Hassbian"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/installation-raspberry-pi-image/
---
The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~10 minutes).
1. [Download the Hassbian 1.1 image][image-download] (359MB)
2. Use [Etcher][etcher] to flash the image to your SD card
3. Ensure your Raspberry Pi has access to the internet.
4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.
These instructions are also available as a [video](https://www.youtube.com/watch?v=iIz6XqDwHEk).
After initial boot, you can reach Home Assistant in your browser at [http://hassbian.local:8123]. If you want to login via SSH, the default username is `pi` and password is `raspberry` (please change this by running `passwd`). The Home Assistant configuration is located at `/home/homeassistant/.homeassistant/`.
The following extras are included on the image:
- GPIO pins are ready to use.
- Bluetooth is ready to use (supported models only, no Bluetooth LE).
### {% linkable_title Technical Details %}
- Home Assistant is installed in a virtual Python environment at `/srv/homeassistant/`
- Home Assistant will be started as a service run by the user `homeassistant`
- The configuration is located at `/home/homeassistant/.homeassistant`
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
### [Learn how to configure Home Assistant &raquo;](/getting-started/configuration/)
### [Learn common tasks in Hassbian &raquo;](/getting-started/hassbian-common-tasks/)
[image-download]: https://github.com/home-assistant/pi-gen/releases/download/v1.1/image_2017-02-03-HASSbian.zip
[etcher]: https://etcher.io/
[http://hassbian.local:8123]: http://hassbian.local:8123

100
source/getting-started/hassbian-integrations.markdown
View file

@ -1,100 +0,0 @@
---
layout: page
title: "Raspberry Pi integrations"
description: "Home Assistant integrations specific to the Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
Some components that are specific for the Raspberry Pi can require some further configuration outside of Home Assistant. All commands below are assumed to be executed with the `pi` account. For full documentation of these components refer to the [components](/components) page.
### {% linkable_title Bluetooth Tracker %}
The Bluetooth tracker will work on a Raspberry Pi 3 with the built-in Bluetooth module or with a USB Bluetooth device on any of the other Raspberry Pi's.
Install the following external dependencies.
```bash
$ sudo apt-get install bluetooth libbluetooth-dev
```
After this follow the [Bluetooth Tracker component](/components/device_tracker.bluetooth_tracker/) and [Device Tracker page](/components/device_tracker/) pages.
### {% linkable_title Raspberry Pi Camera %}
The Raspberry Pi Camera is a specific camera for the Raspberry Pi boards. For more information about the camera I suggest reading the [documentation](https://www.raspberrypi.org/documentation/usage/camera/) from the Raspberry Pi foundation.
To use the camera it needs to be enabled with the `raspi-config` utility.
```bash
$ sudo raspi-config
```
Select `Enable camera` choose `<Yes>` and hit `Enter`, then go to `Finish` and you'll be prompted to reboot.
After reboot add your `homeassistant` account to the `video` group.
```bash
$ sudo adduser homeassistant video
```
After this follow the [Raspberry Pi Camera component](/components/camera.rpi_camera/) page.
### {% linkable_title Raspberry Pi GPIO %}
Each of the following devices are connected to the GPIO pins on the Raspberry Pi.
For more details about the GPIO layout, visit the [documentation](https://www.raspberrypi.org/documentation/usage/gpio/) from the Raspberry Pi foundation.
Since these are not normally used some extra permission will need to be added.
In general the permission that is needed is granted by adding the `homeassistant` account to the `gpio` group.
### {% linkable_title Raspberry Pi Cover %}
Add your `homeassistant` account to the `gpio` group
```bash
$ sudo adduser homeassistant gpio
```
After this follow the [Raspberry Pi Cover component](/components/cover.rpi_gpio/) page.
### {% linkable_title DHT Sensor %}
Add your `homeassistant` account to the `gpio` group
```bash
$ sudo adduser homeassistant gpio
```
After this follow the [DHT Sensor component](/components/sensor.dht/) page.
### {% linkable_title Raspberry PI GPIO Binary Sensor %}
Add your `homeassistant` account to the `gpio` group
```bash
$ sudo adduser homeassistant gpio
```
After this follow the [Raspberry PI GPIO Binary Sensor component](/components/binary_sensor.rpi_gpio/) page.
### {% linkable_title Raspberry PI GPIO Switch %}
Add your `homeassistant` account to the `gpio` group.
```bash
$ sudo adduser homeassistant gpio
```
After this follow the [Raspberry PI GPIO Switch component](/components/switch.rpi_gpio/) page.
### {% linkable_title Raspberry Pi RF Switch %}
Add your `homeassistant` account to the `gpio` group
```bash
$ sudo adduser homeassistant gpio
```
After this follow the [Raspberry Pi RF Switch component](/components/switch.rpi_rf/) page.
### {% linkable_title One wire Sensor %}
The One wire sensor requires that support for it is enabled on the Raspberry Pi and that the One Wire device is connected to GPIO pin 4.
To enable One Wire support add the following line to the end of `/boot/config.txt`
```yaml
dtoverlay=w1-gpio
```
After this follow the [One Wire Sensor component](/components/sensor.onewire/) page.

29
source/getting-started/hassbian-upgrading.markdown
View file

@ -1,29 +0,0 @@
---
layout: page
title: "Upgrading Hassbian"
description: "Instructions how to upgrade Hasbian to the latest version."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following.
Log in as the `pi` account and execute the following commands:
```bash
$ sudo apt-get update
$ sudo apt-get upgrade
```
Press `Y` to confirm that you would like to continue.
#### {% linkable_title Upgrading the hassbian-scripts %}
To update the hassbian-scripts directory execute the following command as the `pi` user.
```bash
$ cd hassbian-scripts
$ git pull
```

22
source/getting-started/hassbian.markdown
View file

@ -1,22 +0,0 @@
---
layout: page
title: "Hassbian"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
Hassbian is our customized operating system for the Raspberry Pi 3. It is the easiest way of installing Home Assistant.
- [Install Hassbian][install]
- [Customize your installation][customize]
- [Pi specific integrations][integrations]
- [Learn how to perform common tasks][common]
[install]: /getting-started/hassbian-installation/
[customize]: /getting-started/hassbian-customization/
[common]: /getting-started/hassbian-common-tasks/
[integrations]: /getting-started/hassbian-integrations/

18
source/getting-started/index.markdown
View file

@ -12,13 +12,13 @@ footer: true
You will need to install Home Assistant before we can get started. You can install Home Assistant on your computer or you can turn a Raspberry Pi into a dedicated Home Assistant hub.
<div class="text-center hass-option-cards" markdown="0">
<a class='option-card' href='/getting-started/hassbian-installation/'>
<a class='option-card' href='/docs/hassbian/installation/'>
<div class='img-container'>
<img src='/images/supported_brands/raspberry-pi.png' />
</div>
<div class='title'>Install Hassbian on your Raspberry Pi 3</div>
</a>
<a class='option-card' href='/getting-started/installation-python/'>
<a class='option-card' href='/docs/installation/python/'>
<div class='img-container'>
<img src='/images/supported_brands/python.svg' />
</div>
@ -26,16 +26,8 @@ You will need to install Home Assistant before we can get started. You can insta
</a>
</div>
### {% linkable_title Alternative methods %}
For alternative installation methods please take a look at the [installation documentation](/docs/installation/).
For advanced users we have several alternative guides for installing Home Assistant.
If you run into any issues, please see [the troubleshooting page](/docs/installation/troubleshooting/) or [communication channels](/help/). It contains solutions to many commonly encountered issues.
- [Docker](/getting-started/installation-docker/)
- [Manual Raspberry Pi installation](/getting-started/installation-raspberry-pi/) (requires existing Raspbian installation)
- [Raspberry Pi All-In-One Installer Script](/getting-started/installation-raspberry-pi-all-in-one/) (requires existing Raspbian installation)
- [Vagrant](/getting-started/installation-vagrant/)
- [Synology NAS](/getting-started/installation-synology/)
- [Virtualenv Linux](/getting-started/installation-virtualenv/)
[rpi]: /getting-started/installation-raspberry-pi-image/
[python]: /getting-started/installation-python/
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

42
source/getting-started/installation-docker.markdown
View file

@ -1,42 +0,0 @@
---
layout: page
title: "Installation on Docker"
description: "Instructions to install Home Assistant on a Docker."
date: 2016-04-16 11:36
sidebar: true
comments: false
sharing: true
footer: true
---
Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it:
```bash
$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
```
This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
<p class='note'>
When using boot2docker on macOS you are unable to map the local time to your Docker container. Replace `-v /etc/localtime:/etc/localtime:ro` with `-e "TZ=America/Los_Angeles"` (replacing America/Los_Angeles with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
</p>
If you change the config you have to restart the server.
To do that you have 2 options.
1. You can go to the <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> service developer tools, select the service `homeassistant/restart` and click "Call Service".
2. Or you can restart it from an terminal by running `docker restart home-assistant`
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

54
source/getting-started/installation-python.markdown
View file

@ -1,54 +0,0 @@
---
layout: page
title: "Installation on your computer"
description: "Step by step guide to install Home Assistant on your computer."
date: 2014-12-18 22:57
sidebar: true
comments: false
sharing: true
footer: true
---
Installing and running Home Assistant on your local machine is easy. The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least Python 3.5 and for other operating systems at least Python 3.4.2.
Once installed, execute the following code in a console:
```bash
$ pip3 install homeassistant
$ hass --open-ui
```
Running these commands will:
- Install Home Assistant
- Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123)
If you're running a Linux-based platform, we suggest you follow the [VirtualEnv Linux instructions][virtualenv] to avoid using root.
Video tutorials of this process for various operating systems are available here:
- [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY)
- [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls)
- [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0)
### {% linkable_title Updating %}
To update Home Assistant to the latest release check the [Updating section](/getting-started/updating/).
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting
### {% linkable_title What's next? %}
To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)
[virtualenv]: /getting-started/installation-virtualenv/

114
source/getting-started/installation-raspberry-pi-all-in-one.markdown
View file

@ -1,114 +0,0 @@
---
layout: page
title: "Raspberry Pi All-In-One Installer"
date: 2016-05-12 01:39
comments: false
sharing: true
footer: true
---
The [Raspberry Pi All-In-One Installer](https://github.com/home-assistant/fabric-home-assistant) deploys a complete Home Assistant server including support for MQTT with websockets, Z-Wave, and the Open-Zwave Control Panel.
The only requirement is that you have a Raspberry Pi with a fresh installation of [Raspbian](https://www.raspberrypi.org/downloads/raspbian/) connected to your network.
<p class='note'>
Note that as of 2016-11-30 SSH is disabled by default in the official Raspbian images. Adding an empty file called `ssh` to `/boot/` or the FAT32 partition will enable it. More information is on the Raspberry Pi Foundation [Blog](https://www.raspberrypi.org/blog/page/2/?fish#a-security-update-for-raspbian-pixel)
</p>
* Login to Raspberry Pi. For example with `ssh pi@your_raspberry_pi_ip`
* Run the following command
```bash
$ curl -O https://raw.githubusercontent.com/home-assistant/fabric-home-assistant/master/hass_rpi_installer.sh && sudo chown pi:pi hass_rpi_installer.sh && bash hass_rpi_installer.sh
```
<p class='note warning'>
Note this command is one-line and not run as sudo.
</p>
Installation will take approx. 1-2 hours depending on the Raspberry Pi model the installer is being run against. The installer will identitfy what Raspberry PI hardware revision you are using and adjust commands accordingly. A complete log of the install is located at: `/home/pi/fabric-home-assistant/installation_report.txt` The installer has been updated to simply log any errors encountered, but resume installing. Please consult the "installation report" if your install encountered issues.
[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=VGl3KTrYo6s) explaining how to install Raspbian on your Raspberry Pi and install Home Assistant using the All-In-One Installer.
Once rebooted, your Raspberry Pi will be up and running with Home Assistant. You can access it at [http://your_raspberry_pi_ip:8123](http://your_raspberry_pi_ip:8123).
The Home Assistant configuration is located at `/home/homeassistant/.homeassistant` (or `/home/hass/.homeassistant` if installed prior to December 2016). The [virtualenv](https://virtualenv.pypa.io/en/latest/) with the Home Assistant installation is located at `/srv/homeassistant/homeassistant_venv`. As part of the secure installation, a new user (**homeassistant**) is added to your Raspberry Pi to run Home Assistant. This is a system account and does not have login or other abilities by design. When editing your `configuration.yaml` files, you will need to run the commands with `sudo` or by switching user.
<p class='note note'>
*Windows users*: Setting up WinSCP to allow this seemlessly is at the end of this page.
</p>
By default, installation makes use of a Python Virtualenv. If you wish to not follow this recommendation, you may add the flag `-n` to the end of the install command specified above.
The All-In-One Installer script will do the following automatically:
* Create all needed directories
* Create needed service accounts
* Install OS and Python dependencies
* Setup a python virtualenv to run Home Assistant and components inside.
* Run as `homeassistant` service account
* Install Home Assistant in a virtualenv
* Install Mosquitto with websocket support running on ports 1883 and 9001
* Build and Install Python-openzwave in the Home Assistant virtualenv
* Build openzwave-control-panel in `/srv/homeassistant/src/open-zwave-control-panel`
* Add Home Assistant to systemd services to start at boot
### {% linkable_title Upgrading %}
To upgrade the All-In-One setup manually:
* Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
* Change to homeassistant user `sudo su -s /bin/bash homeassistant`
* Change to virtual enviroment `source /srv/homeassistant/homeassistant_venv/bin/activate`
* Update HA `pip3 install --upgrade homeassistant`
* Type `exit` to logout the hass user and return to the `pi` user.
<p class='note note'>
If you deployed Home Assistant via the AiO installer prior to December 2016, replace `sudo su -s /bin/bash homeassistant` with `sudo su -s /bin/bash hass` and `source /srv/homeassistant/homeassistant_venv/bin/activate` with `source /srv/hass/hass_venv/bin/activate`</p>
To upgrade with fabric:
* Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
* Change to `cd ~/fabric-home-assistant`
* Run `fab upgrade_homeassistant`
After upgrading, you can restart Home Assistant a few different ways:
* Restarting the Raspberry Pi `sudo reboot`
* Restarting the Home-Assistant Service `sudo systemctl restart home-assistant.service`
### {% linkable_title To change the MQTT default password %}
* Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
* Change password `sudo mosquitto_passwd /etc/mosquitto/pwfile pi`
* Restart mosquitto `sudo systemctl restart mosquitto.service`
* Be sure to update your `configuration.yaml` to reflect the new password.
### {% linkable_title Using the OZWCP web application %}
To launch the OZWCP web application:
* Make sure Home Assistant is not running! So stop that first
* Login to Raspberry Pi `ssh pi@your_raspberry_pi_ip`
* Change to the ozwcp directory `cd /srv/homeassistant/src/open-zwave-control-panel/`
* Launch the control panel `sudo ./ozwcp -p 8888`
* Open a web browser to `http://your_pi_ip:8888`
* Specify your zwave controller, for example `/dev/ttyACM0` and hit initialize
<p class='note note'>
If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/`
</p>
<p class='note warning'>
Don't check the USB box regardless of using a USB based device.
</p>
### {% linkable_title Using the GPIOs %}
The (**homeassistant**)user is added to the GPIO group as part of the install now.
### {% linkable_title WinSCP %}
If you are Windows users who is using [WinSCP](https://winscp.net/), please note that after running the installer, you will need to modify settings allowing you to "switch users" to edit your configuration files.
First create a new session on WinSCP using Protocol **SCP** pointing to your Pi IP address and port 22 and then modify the needed setting by click on **Advanced...** -> **Environment** -> **SCP/Shell** -> **Shell** and selecting `sudo su -`.

87
source/getting-started/installation-raspberry-pi.markdown
View file

@ -1,87 +0,0 @@
---
layout: page
title: "Manual installation on a Raspberry Pi"
description: "Instructions to install Home Assistant on a Raspberry Pi runnning Raspbian Lite."
date: 2016-09-05 16:00
sidebar: true
comments: false
sharing: true
footer: true
---
This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/).
The installation will be installed in a [Virtual Environment](/getting-started/installation-virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
Connect to the Raspberry Pi over ssh. Default password is `raspberry`.
You will need to enable ssh access. The raspberry pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/).
```bash
$ ssh pi@ipadress
```
Changing the default password is encouraged.
```bash
$ passwd
```
Update the system.
```bash
$ sudo apt-get update
$ sudo apt-get upgrade -y
```
Install the dependencies.
```bash
$ sudo apt-get install python3 python3-venv python3-pip
```
Add an account for Home Assistant called `homeassistant`.
Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory.
```bash
$ sudo useradd -rm homeassistant
```
Next we will create a directory for the installation of Home Assistant and change the owner to the `homeassistant` account.
```bash
$ cd /srv
$ sudo mkdir homeassistant
$ sudo chown homeassistant:homeassistant homeassistant
```
Next up is to create and change to a virtual environment for Home Assistant. This will be done as the `homeassistant` account.
```bash
$ sudo su -s /bin/bash homeassistant
$ cd /srv/homeassistant
$ python3 -m venv .
$ source bin/activate
```
Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant.
```bash
(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant
```
Start Home Assistant for the first time. This will complete the installation, create the `.homeasssistant` configuration directory in the `/home/homeassistant` directory and install any basic dependencies.
```bash
(homeassistant) $ hass
```
You can now reach your installation on your raspberry pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123).
For instruction on how to configure Home Assistant continue on with [Configuring Home Assistant](/getting-started/configuration/).
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
### {% linkable_title What's next %}
If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-systemd/).
To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

244
source/getting-started/installation-synology.markdown
View file

@ -1,244 +0,0 @@
---
layout: page
title: "Installation on a Synology NAS"
description: "Instructions to install Home Assistant on a Synology NAS."
date: 2016-04-16 11:36
sidebar: true
comments: false
sharing: true
footer: true
---
The following configuration has been tested on Synology 413j running DSM 6.0-7321 Update 1.
Running these commands will:
- Install Home Assistant
- Enable Home Assistant to be launched on [http://localhost:8123](http://localhost:8123)
Using the Synology webadmin:
- Install python3 using the Synology Package Center
- Create homeassistant user and add to the "users" group
SSH onto your synology & login as admin or root
- Log in with your own administrator account
- Switch to root using:
```bash
$ sudo -i
```
Check the path to python3 (assumed to be /volume1/@appstore/py3k/usr/local/bin)
```bash
$ cd /volume1/@appstore/py3k/usr/local/bin
```
Install PIP (Python's package management system)
```bash
$ ./python3 -m ensurepip
```
Use PIP to install Homeassistant package
```bash
$ ./python3 -m pip install homeassistant
```
Create homeassistant config directory & switch to it
```bash
$ mkdir /volume1/homeassistant
$ cd /volume1/homeassistant
```
Create hass-daemon file using the following code (edit the variables in uppercase if necessary)
```bash
#!/bin/sh
# Package
PACKAGE="homeassistant"
DNAME="Home Assistant"
# Others
USER="homeassistant"
PYTHON_DIR="/volume1/@appstore/py3k/usr/local/bin"
PYTHON="$PYTHON_DIR/python3"
HASS="$PYTHON_DIR/hass"
INSTALL_DIR="/volume1/homeassistant"
PID_FILE="$INSTALL_DIR/home-assistant.pid"
FLAGS="-v --config $INSTALL_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $INSTALL_DIR/home-assistant.log 2>&1"
start_daemon ()
{
sudo -u ${USER} /bin/sh -c "$PYTHON $HASS $FLAGS $REDIRECT;"
}
stop_daemon ()
{
kill `cat ${PID_FILE}`
wait_for_status 1 20 || kill -9 `cat ${PID_FILE}`
rm -f ${PID_FILE}
}
daemon_status ()
{
if [ -f ${PID_FILE} ] && kill -0 `cat ${PID_FILE}` > /dev/null 2>&1; then
return
fi
rm -f ${PID_FILE}
return 1
}
wait_for_status ()
{
counter=$2
while [ ${counter} -gt 0 ]; do
daemon_status
[ $? -eq $1 ] && return
let counter=counter-1
sleep 1
done
return 1
}
case $1 in
start)
if daemon_status; then
echo ${DNAME} is already running
exit 0
else
echo Starting ${DNAME} ...
start_daemon
exit $?
fi
;;
stop)
if daemon_status; then
echo Stopping ${DNAME} ...
stop_daemon
exit $?
else
echo ${DNAME} is not running
exit 0
fi
;;
restart)
if daemon_status; then
echo Stopping ${DNAME} ...
stop_daemon
echo Starting ${DNAME} ...
start_daemon
exit $?
else
echo ${DNAME} is not running
echo Starting ${DNAME} ...
start_daemon
exit $?
fi
;;
status)
if daemon_status; then
echo ${DNAME} is running
exit 0
else
echo ${DNAME} is not running
exit 1
fi
;;
log)
echo ${LOG_FILE}
exit 0
;;
*)
exit 1
;;
esac
```
Create links to python folders to make things easier in the future:
```bash
$ ln -s /volume1/@appstore/py3k/usr/local/bin python3
$ ln -s /volume1/@appstore/py3k/usr/local/lib/python3.5/site-packages/homeassistant
```
Set the owner and permissions on your config folder
```bash
$ chown -R homeassistant:users /volume1/homeassistant
$ chmod -R 664 /volume1/homeassistant
```
Make the daemon file executable:
```bash
$ chmod 777 /volume1/homeassistant/hass-daemon
```
Update your firewall (if it is turned on on the Synology device):
- Go to your Synology control panel
- Go to security
- Go to firewall
- Go to Edit Rules
- Click Create
- Select Custom: Destination port "TCP"
- Type "8123" in port
- Click on OK
- Click on OK again
Copy your configuration.yaml file into the config folder
That's it... you're all set to go
Here are some useful commands:
- Start Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon start
```
- Stop Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon stop
```
- Restart Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon restart
```
- Upgrade Home Assistant::
```bash
$ /volume1/@appstore/py3k/usr/local/bin/python3 -m pip install --upgrade homeassistant
```
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
### {% linkable_title What's next %}
If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-synology/).
To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

100
source/getting-started/installation-vagrant.markdown
View file

@ -1,100 +0,0 @@
---
layout: page
title: "Installation on Vagrant"
description: "Instructions to run Home Assistant on a Vagrant VM."
date: 2016-05-28 10:00
sidebar: true
comments: false
sharing: true
footer: true
---
A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them.
<p class='note'>
Vagrant is intended for testing/development only. It is NOT recommended for permanent installations.
</p>
## {% linkable_title Install Vagrant %}
You must have [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/wiki/Downloads) installed on your workstation.
## {% linkable_title Get Home Assistant source code %}
Download the Home Assistant source code by either downloading the .zip file from [GitHub releases page](https://github.com/home-assistant/home-assistant/releases) or by using [Git](https://git-scm.com/)
```bash
$ git clone https://github.com/home-assistant/home-assistant.git
$ cd home-assistant/virtualization/vagrant
```
<p class='note'>
The following instructions will assume you changed your working directory to be `home-assistant/virtualization/vagrant`. This is mandatory because Vagrant will look for informations about the running VM inside that folder and won't work otherwise
</p>
<p class='note'>
When using Vagrant on Windows, change git's `auto.crlf` to input before cloning the Home Assistant repository. With input setting git won't automatically change line endings from Unix LF to Windows CRLF. Shell scripts executed during provision won't work with Windows line endings.
</p>
```bash
$ git config --global core.autocrlf input
```
## {% linkable_title Create the Vagrant VM and start Home Assistant %}
```bash
$ vagrant up
```
This will download and start a virtual machine using Virtualbox, which will internally setup the development environment necessary to start Home Assistant process and run test suite as well. After the VM has started successfully, the Home Assistant frontend will be accessible locally from your browser at [http://localhost:8123](http://localhost:8123)
## {% linkable_title Stopping Vagrant %}
To shutdown the Vagrant host:
```bash
$ vagrant halt
```
To start it again, just run `vagrant up`
## {% linkable_title Restarting Home Assistant process to test changes %}
The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Getting started section](https://home-assistant.io/getting-started/configuration/) for more information about how to configure Home Assistant).
Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it:
```bash
$ touch restart ; vagrant provision
```
## {% linkable_title Run test suite (Tox) %}
To run tests against your changes:
```bash
$ touch run_tests ; vagrant provision
```
## {% linkable_title Cleanup %}
To completely remove the VM:
```bash
$ rm setup_done ; vagrant destroy -f
```
You can now recreate a completely new Vagrant host with `vagrant up`
### {% linkable_title Troubleshooting %}
If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
In addition to this site, check out these sources for additional help:
- [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

132
source/getting-started/installation-virtualenv.markdown
View file

@ -1,132 +0,0 @@
---
layout: page
title: "Installation in virtualenv"
description: "Instructions how to install Home Assistant in a virtual environment."
date: 2016-4-16 16:40
sidebar: true
comments: false
sharing: true
footer: true
---
There are several reasons why it makes sense to run Home Assistant in a virtual environment. A [virtualenv](https://virtualenv.pypa.io/en/latest/) encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant won't interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer won't break Home Assistant, and it means you don't need to install Python packages as root.
Virtualenvs are pretty easy to setup. This example will walk through one method of setting one up (there are certainly others). We'll be using Debian in this example (as many Home Assistant users are running Raspbian on a Raspberry Pi), but all of the Python related steps should be the same on just about any platform.
### {% linkable_title Step 0: Install some dependencies %}
```bash
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install python-pip python3-dev
$ sudo pip install --upgrade virtualenv
```
### {% linkable_title Step 1: Create a Home Assistant user %}
This step is optional, but it's a good idea to give services like Home Assistant their own user. It gives you more granular control over permissions, and reduces the exposure to the rest of your system in the event there is a security related bug in Home Assistant. This is a reasonably Linux oriented step, and will look different on other operating systems (or even other Linux distributions).
```bash
$ sudo adduser --system homeassistant
```
Home Assistant stores its configuration in `$HOME/.homeassistant` by default, so in this case, it would be in `/home/homeassistant/.homeassistant`
If you plan to use a Z-Wave controller, you will need to add this user to the `dialout` group
```bash
$ sudo usermod -G dialout -a homeassistant
```
### {% linkable_title Step 2: Create a directory for Home Assistant %}
This can be anywhere you want. As example we put it in `/srv`. You also need to change the ownership of the directory to the user you created above (if you created one).
```bash
$ sudo mkdir /srv/homeassistant
$ sudo chown homeassistant:homeassistant /srv/homeassistant
```
### {% linkable_title Step 3: Become the new user %}
This is obviously only necessary if you created a `homeassistant` user, but if you did, be sure to switch to that user whenever you install things in your virtualenv, otherwise you'll end up with mucked up permissions.
```bash
$ sudo su -s /bin/bash homeassistant
```
The `su` command means 'switch' user. We use the '-s' flag because the `homeassistant` user is a system user and doesn't have a default shell by default (to prevent attackers from being able to log in as that user).
### {% linkable_title Step 4: Set up the virtualenv %}
All this step does is stick a Python environment in the directory we're using. That's it. It's just a directory. There's nothing special about it, and it is entirely self-contained.
It will include a `bin` directory, which will contain all the executables used in the virtualenv (including hass itself). It also includes a script called `activate` which we will use to activate the virtualenv.
```bash
$ virtualenv -p python3 /srv/homeassistant
```
### {% linkable_title Step 5: Activate the virtualenv %}
```bash
$ source /srv/homeassistant/bin/activate
```
After that, your prompt should include `(homeassistant)`.
### {% linkable_title Step 6: Install Home Assistant %}
Once your virtualenv has been activated, you don't need to `sudo` any of your `pip` commands. `pip` will be installing things in the virtualenv, which the `homeassistant` user has permission to modify.
```bash
(homeassistant)$ pip3 install --upgrade homeassistant
```
And that's it... you now have Home Assistant installed, and you can be sure that every bit of it is contained in `/srv/homeassistant`.
### {% linkable_title Finally... Run Home Assistant %}
There are two ways to launch Home Assistant. If you are **in** the virtualenv, you can just run `hass` and it will work as normal. If the virtualenv is not activated, you just use the `hass` executable in the `bin` directory mentioned earlier. There is one caveat... Because Home Assistant stores its configuration in the user's home directory, we need to be the user `homeassistant` user or specify the configuration with `-c`.
```bash
$ sudo -u homeassistant -H /srv/homeassistant/bin/hass
```
The `-H` flag is important. It sets the `$HOME` environment variable to `/home/homeassistant` so `hass` can find its configuration.
### {% linkable_title Upgrading Home Assistant %}
Upgrading Home Assistant is simple, just repeat steps 3, 5 and 6.
### {% linkable_title Starting Home Assistant on boot %}
The [autostart instructions](/getting-started/autostart/) will work just fine, just be sure to replace `/usr/bin/hass` with `/srv/homeassistant/bin/hass` and specify the `homeassistant` user where appropriate.
### {% linkable_title Installing python-openzwave in a virtualenv %}
If you want to use Z-Wave devices, you will need to install `python-openzwave` in your virtualenv. This requires a small tweak to the instructions in [the Z-Wave Getting Started documentation](/getting-started/z-wave/)
Install the dependencies as normal (Note: you will need to do this as your normal user, since `homeassistant` isn't a sudoer).
```bash
$ sudo apt-get install cython3 libudev-dev python3-sphinx python3-setuptools git
```
Then, activate your virtualenv (steps 3 and 5 above) and upgrade cython.
```bash
(homeassistant)$ pip3 install --upgrade cython==0.24.1
```
Finally, get and install `python-openzwave`.
```bash
(homeassistant)$ mkdir /srv/homeassistant/src
(homeassistant)$ cd /srv/homeassistant/src
(homeassistant)$ git clone https://github.com/OpenZWave/python-openzwave.git
(homeassistant)$ cd python-openzwave
(homeassistant)$ git checkout python3
(homeassistant)$ PYTHON_EXEC=`which python3` make build
(homeassistant)$ PYTHON_EXEC=`which python3` make install
```

33
source/getting-started/mobile.markdown
View file

@ -1,33 +0,0 @@
---
layout: page
title: "Getting started on Mobile"
description: "Android/iOS instructions to add Home Assistant to your homescreen."
date: 2015-03-08 21:36
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/android/
---
Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new W3C [manifest.json](https://w3c.github.io/manifest/) support, allowing mobile devices to add the "web app" to your homescreen as if it was native.
### {% linkable_title Android %}
1. Open Chrome
2. Navigate to your Home Assistant instance
3. Tap on the Menu icon (three vertical bars)
4. Tap on Add to Homescreen
5. A dialog will popup; tap on Add
<p class='img' style='width:500px; margin-left: auto; margin-right: auto;'>
<img src='/images/screenshots/android-homescreen-guide.gif' />
</p>
### {% linkable_title iOS %}
1. Open Safari
2. Navigate to your Home Assistant instance
3. Tap on the Share icon in the middle of the bottom toolbar
4. Tap on "Add to Home Screen"
5. A dialog will popup; tap on Add

6
source/getting-started/presence-detection.markdown
View file

@ -2,7 +2,7 @@
layout: page
title: "Setting up presence detection"
description: "Instructions how to setup presence detection within Home Assistant."
date: 2015-10-4 12:08
date: 2015-10-04 12:08
sidebar: true
comments: false
sharing: true
@ -41,8 +41,6 @@ OwnTracks communicates directly with your MQTT broker; no data will pass through
Home Assistant will know the location of your device if you are using OwnTracks. By [setting up zones][zone] you will be able to add names to the locations of your devices. This way you can easily spot on the state page where the people in your house are and use it as [triggers][trigger] and [conditions][condition] for automation.
### [Next step: Setting up automation &raquo;](/getting-started/automation/)
[routers]: /components/#presence-detection
[nmap]: /components/device_tracker.nmap_tracker/
[ha-owntracks]: /components/device_tracker.owntracks/
@ -53,3 +51,5 @@ Home Assistant will know the location of your device if you are using OwnTracks.
[trigger]: /getting-started/automation-trigger/#zone-trigger
[condition]: /getting-started/automation-condition/#zone-condition
### [Next step: Use Home Assistant &raquo;](/getting-started/use/)

178
source/getting-started/scripts-conditions.markdown
View file

@ -1,178 +0,0 @@
---
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 AND condition %}
Test multiple conditions in 1 condition statement. Passes if all embedded conditions are valid.
```yaml
condition:
condition: and
conditions:
- condition: state
entity_id: 'device_tracker.paulus'
state: 'home'
- condition: numeric_state
entity_id: 'sensor.temperature'
below: '20'
```
### {% linkable_title OR condition %}
Test multiple conditions in 1 condition statement. Passes if any embedded conditions is valid.
```yaml
condition:
condition: or
conditions:
- condition: state
entity_id: 'device_tracker.paulus'
state: 'home'
- condition: numeric_state
entity_id: 'sensor.temperature'
below: '20'
```
### {% linkable_title MIXED AND and OR conditions %}
Test multiple AND and OR conditions in 1 condition statement. Passes if any embedded conditions is valid.
This allows you to mix several AND and OR conditions together.
```yaml
condition:
condition: and
conditions:
- condition: state
entity_id: 'device_tracker.paulus'
state: 'home'
- condition: or
conditions:
- condition: state
entity_id: sensor.weather_precip
state: 'rain'
- condition: numeric_state
entity_id: 'sensor.temperature'
below: '20'
```
### {% 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:
condition: numeric_state
entity_id: sensor.temperature
above: 17
below: 25
# If your sensor value needs to be adjusted
value_template: {% raw %}{{ float(state.state) + 2 }}{% endraw %}
```
### {% linkable_title State condition %}
Tests if an entity is a specified state.
```yaml
condition:
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].
[sun_trigger]: /getting-started/automation-trigger/#sun-trigger
```yaml
condition:
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:
condition: template
value_template: '{% raw %}{{ states.device_tracker.iphone.attributes.battery > 50 }}{% endraw %}'
```
Within an automation, template conditions also have access to the `trigger` variable as [described here][automation-templating].
[template]: /topics/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:
condition: time
# At least one of the following is required.
after: '15:00:00'
before: '02:00:00'
weekday:
- mon
- wed
- fri
```
Valid values for `weekday` are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.
Time condition windows can span across the midnight threshold. In the example above, the condition window is from 3pm to 2am.
### {% 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:
condition: zone
entity_id: device_tracker.paulus
zone: zone.home
```
### {% linkable_title Examples %}
```yaml
condition:
- condition: numeric_state
entity_id: sun.sun
value_template: '{{ state.attributes.elevation }}'
below: 1
- condition: state
entity_id: light.living_room
state: 'off'
- condition: time
before: '23:00:00'
after: '14:00:00'
- condition: state
entity_id: script.light_turned_off_5min
state: 'off'
```

84
source/getting-started/scripts-service-calls.markdown
View file

@ -1,84 +0,0 @@
---
layout: page
title: "Service Calls"
description: "Instructions how to call services in Home Assistant."
date: 2016-03-12 12:00 -0800
sidebar: true
comments: false
sharing: true
footer: true
---
Various components allow calling services when a certain event occurs. The most common one is calling a service when an automation trigger happens. But a service can also be called from a script or via the Amazon Echo.
The configuration options to call a config are the same between all components and are described on this page.
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 <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 %}
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
service: homeassistant.turn_on
entity_id: group.living_room
```
### {% linkable_title Passing data to the service call %}
You can also specify other parameters beside the entity to target. For example, the light turn on service allows specifying the brightness.
```yaml
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 %}
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
service_template: >
{% raw %}{% if states.sensor.temperature | float > 15 %}
switch.turn_on
{% else %}
switch.turn_off
{% endif %}{% endraw %}
entity_id: switch.ac
```
### {% linkable_title Using the Services Developer Tool %}
You can use the Services Developer Tool to test data to pass in a service call.
For example, you may test turning on or off a 'group' (See [groups] for more info)
To turn a group on or off, pass the following info:
Domain: `homeassistant`
Service: `turn_on`
Service Data: `{ "entity_id": "group.kitchen" }`
### {% linkable_title Use templates to determine the attributes %}
Templates can also be used for the data that you pass to the service call.
```yaml
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/

95
source/getting-started/scripts.markdown
View file

@ -1,95 +0,0 @@
---
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
```
```yaml
# Waits however many minutes input_slider.minute_delay is set to
# Valid formats include HH:MM and HH:MM:SS
delay: {% raw %}'00:{{ states.input_slider.minute_delay.state | int }}:00'{% endraw %}
```
### {% 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/

29
source/getting-started/securing.markdown
View file

@ -1,29 +0,0 @@
---
layout: page
title: "Securing"
description: "Instructions how to secure your Home Assistant installation."
date: 2016-10-06 06:00
sidebar: true
comments: false
sharing: true
footer: true
---
One major advantage of Home Assistant is that it's not dependent on cloud services. Even if you're only using Home Assistant on a local network, you should take steps to secure your instance.
### {% linkable_title Checklist %}
- [Protect your web interface with a password](https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface)
- Secure your host. Sources could be [Red Hat Enterprise Linux 7 Security Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/pdf/Security_Guide/Red_Hat_Enterprise_Linux-7-Security_Guide-en-US.pdf), [CIS Red Hat Enterprise Linux 7 Benchmark](https://benchmarks.cisecurity.org/tools2/linux/CIS_Red_Hat_Enterprise_Linux_7_Benchmark_v1.0.0.pdf), or the [Securing Debian Manual](https://www.debian.org/doc/manuals/securing-debian-howto/index.en.html).
- Restrict network access to your devices. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use SSH keys for authentication instead of passwords.
- Don't run Home Assistant as root – consider the Principle of Least Privilege.
- Keep your [secrets](/topics/secrets/) safe.
If you want to allow remote access, consider these additional points:
- Protect your communication with [TLS](/blog/2015/12/13/setup-encryption-using-lets-encrypt/)
- Protect your communication with [Tor](/cookbook/tor_configuration/)
- Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/)
- Use a [proxy](/cookbook/apache_configuration/)

88
source/getting-started/troubleshooting-configuration.markdown
View file

@ -1,88 +0,0 @@
---
layout: page
title: "Troubleshooting your configuration"
description: "Common problems with tweaking your configuration and their solutions."
date: 2015-01-20 22:36
sidebar: true
comments: false
sharing: true
footer: true
---
It can happen that you run into trouble while configuring Home Assistant. Perhaps a component is not showing up or is acting strangely. This page will discuss a few of the most common problems.
Before we dive into common issues, make sure you know where your configuration directory is. Home Assistant will print out the configuration directory it is using when starting up.
Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log` in the configuration directory. This file is reset on start of Home Assistant.
### {% linkable_title My component does not show up %}
When a component 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 component you are trying to set up.
If you have incorrect entries in your configuration files you can use the `check_config` script to assist in identifying them: `hass --script check_config`.
#### {% linkable_title Problems with the configuration %}
One of the most common problems with Home Assistant is an invalid `configuration.yaml` file.
- You can test your configuration using the command line with: `hass --script check_config`
- You can verify your configuration's yaml structure using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/).
- To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well).
`configuration.yaml` does not allow multiple sections to have the same name. If you want to load multiple platforms for one component, you can append a [number or string](/getting-started/devices/#style-2-list-each-device-separately) to the name or nest them using [this style](/getting-started/devices/#style-1-collect-every-entity-under-the-parent):
```yaml
sensor:
- platform: forecast
...
- platform: bitcoin
...
```
Another common problem is that a required configuration setting is missing. If this is the case, the component will report this to `home-assistant.log`. You can have a look at [the various component pages](/components/) for instructions on how to setup the components.
See the [logger](/components/logger/) component for instructions on how to define the level of logging you require for specific modules.
If you find any errors or want to expand the documentation, please [let us know](https://github.com/home-assistant/home-assistant.io/issues).
#### {% linkable_title Problems with dependencies %}
Almost all components have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in `home-assistant.log`.
The first step is trying to restart Home Assistant and see if the problem persists. If it does, look at the log to see what the error is. If you can't figure it out, please [report it](https://github.com/home-assistant/home-assistant/issues) so we can investigate what is going on.
#### {% linkable_title Problems with components %}
It can happen that some components either do not work right away or stop working after Home Assistant has been running for a while. If this happens to you, please [report it](https://github.com/home-assistant/home-assistant/issues) so that we can have a look.
#### {% linkable_title Multiple files %}
If you are using multiple files for your setup, make sure that the pointers are correct and the format of the files is valid.
```yaml
light: !include devices/lights.yaml
sensor: !include devices/sensors.yaml
```
Contents of `lights.yaml` (notice it does not contain `light: `):
```yaml
- platform: hyperion
host: 192.168.1.98
...
```
Contents of `sensors.yaml`:
```yaml
- platform: mqtt
name: "Room Humidity"
state_topic: "room/humidity"
- platform: mqtt
name: "Door Motion"
state_topic: "door/motion"
...
```
<p class='note'>
Whenever you report an issue, be aware that we are volunteers who do not have access to every single device in the world nor unlimited time to fix every problem out there.
</p>

78
source/getting-started/troubleshooting.markdown
View file

@ -1,78 +0,0 @@
---
layout: page
title: "Troubleshooting installation problems"
description: "Common installation problems and their solutions."
date: 2015-01-20 22:36
sidebar: true
comments: false
sharing: true
footer: true
---
It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems.
#### {% linkable_title pip3: command not found %}
This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/).
If you are able to successfully run `python3 --version` but not `pip3`, install Home Assistant by running the following command instead:
```bash
$ python3 -m pip install homeassistant
```
On a Debian system, you can also install python3 by `sudo apt-get install python3`, and pip3 by `sudo apt-get install python3-pip`.
#### {% linkable_title No module named pip %}
[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is omitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and running it with Python 3:
```bash
$ python3 get-pip.py
```
#### {% linkable_title libyaml is not found or a compiler error %}
On a Debian system, install the Python 3 YAML library by `sudo apt-get install python3-yaml`.
#### {% linkable_title distutils.errors.DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both %}
This is a known issue if you're on a Mac using Homebrew to install Python. Please follow [these instructions](https://github.com/Homebrew/brew/blob/master/docs/Homebrew-and-Python.md#note-on-pip-install---user) to resolve it.
#### {% linkable_title CentOS and Python 3 %}
To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated.
#### {% linkable_title No access to the frontend %}
In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and OSX machines may also have issues with this.
To fix this you will need to open your machine's firewall for TCP traffic over port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.
- [Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7)
- [Mac OSX instructions](https://support.apple.com/en-us/HT201642)
For systems with **firewalld** (Fedora, CentOS/RHEL, etc.):
```bash
$ sudo firewall-cmd --permanent --add-port=8123/tcp
$ sudo firewall-cmd --reload
```
For UFW systems (Ubuntu, Debian, Raspbian, etc.):
```bash
$ sudo ufw allow 8123/tcp
```
For `iptables` systems (was the default for older distributions):
```bash
$ iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
$ iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere
```
#### {% linkable_title After upgrading, your browser login gets stuck at the "loading data" step %}
After upgrading to a new version, you may notice your browser gets stuck at the "loading data" login screen. Close the window/tab and go into your browser settings and delete all the cookies for your URL. You can then log back in and it should work.
Android Chrome
chrome -> settings -> site settings -> storage -> search for your URL for home assistant-> "clear & reset"
### [&laquo; Back to Getting Started](/getting-started/)

48
source/getting-started/updating.markdown
View file

@ -1,48 +0,0 @@
---
layout: page
title: "Updating Home Assistant"
description: "Step to update Home Assistant."
date: 2016-05-04 10:00
sidebar: true
comments: false
sharing: true
footer: true
---
<p class='note warning'>
The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/getting-started/hassbian-common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/#upgrading), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv/#upgrading-home-assistant).
</p>
The default way to update Home Assistant to the latest release, when available, is:
```bash
$ pip3 install --upgrade homeassistant
```
After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon (if applicable)
<p class='note'>
To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/getting-started/installation-raspberry-pi-image/), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv)t.
</p>
[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant.
#### {% linkable_title Run a specific version %}
In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release:
```bash
$ pip3 install homeassistant==0.XX.X
```
#### {% linkable_title Run the development version %}
If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`.
<p class='note warning'>
The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption.
</p>
```bash
$ pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev
```

26
source/getting-started/use.markdown Normal file
View file

@ -0,0 +1,26 @@
---
layout: page
title: "Manage Home Assistant"
description: "Instructions about how to manage Home Assistant."
date: 2016-09-26 21:00
sidebar: true
comments: false
sharing: true
footer: true
---
If you are using Hassbian, browse to [http://hassbian.local:8123](http://hassbian.local:8123) to open the Home Assistant frontend.
To reload your configuration, [login](/docs/hassbian/common-tasks/#login-to-the-raspberry-pi) your Raspberry Pi
```bash
$ ssh pi@ip-address-of-pi
```
and [restart](/docs/hassbian/common-tasks/#startstoprestart-home-assistant) Home Assistant
```bash
$ sudo systemctl restart home-assistant@homeassistant.service
```
For tweaking your Home Assistant setup, take a look at the [documentation](/docs/), ask your questions in our [forum](https://community.home-assistant.io/), join us for a [chat](https://gitter.im/home-assistant/home-assistant), or report your [issues](https://github.com/home-assistant/home-assistant/issues).

63
source/getting-started/yaml.markdown
View file

@ -1,63 +0,0 @@
---
layout: page
title: "YAML"
description: "Details about YAML to configure Home Assistant."
date: 2015-03-23 12:50
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant uses the [YAML](http://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.
For each component that you want to use in Home Assistant, you add code in your `configuration.yaml` file to specify its settings.
The following example entry specifies that you want to use the [notify component](/components/notify) with the [pushbullet platform](/components/notify.pushbullet).
```yaml
notify:
platform: pushbullet
api_key: "o.1234abcd"
name: pushbullet
```
- A **component** provides the core logic for some functionality (like `notify` provides sending notifications).
- A **platform** makes the connection to a specific software or hardware platform (like `pushbullet` works with the service from pushbullet.com).
The basics of YAML syntax are block collections and mappings containing key-value pairs. Each item in a collection starts with a `-` while mappings have the format `key: value`. If you specify duplicate keys, the last value for a key is used.
Note that indentation is an important part of specifying relationships using YAML. Things that are indented are nested "inside" things that are one level higher. So in the above example, `platform: pushbullet` is a property of (nested inside) the `notify` component.
Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. Convention is to use 2 spaces for each level of indentation.
You can use [YAMLLint](http://www.yamllint.com/) to check if your YAML-syntax is correct before loading it into Home Assistant which will save you some time.
*Please pay attention on not putting in private data, as it is a 3rd-party website not maintained by Home Assistant.*
Text following a **#** are comments and are ignored by the system.
The next example shows an [input_select](/components/input_select) component that uses a block collection for the options values.
The other properties (like name) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.
```yaml
input_select:
threat:
name: Threat level
# A collection is used for options
options:
- 0
- 1
- 2
- 3
initial: 0
```
The following example shows nesting a collection of mappings in a mapping. In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors).
```yaml
sensor:
- platform: mqtt
state_topic: sensor/topic
- platform: mqtt
state_topic: sensor2/topic
```
### [Next step: Setting up the basics &raquo;](/getting-started/basic/)

33
source/getting-started/z-wave-controllers.markdown
View file

@ -1,33 +0,0 @@
---
layout: page
title: "Z-Wave Controllers"
description: "Extended instructions how to setup Z-Wave."
date: 2016-03-24 08:49 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Z-Wave is a popular home automation protocol that is not always straightforward to setup. This page will try to help you make sense of it all.
<p class='note'>
Upon first run, the `zwave` component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may expedite this process.
</p>
## {% linkable_title Supported Z-Wave USB Sticks & Hardware Modules %}
| Device | Works on Linux | Works on Windows | Works on OSX |
|-------------------------|----------------|------------------|--------------|
| Aeotec Z-Stick Series 2 | &#10003; | | |
| Aeotec Z-Stick Series 5 | &#10003; | | &#10003; |
| Pine64 Z-Wave Module | &#10003; | | |
| Razberry GPIO Module | &#10003; | | |
| ZWave.me UZB1 | &#10003; | | |
## {% linkable_title Stick Alternatives %}
The alternative to a stick is a hub that supports Z-Wave. Home Assistant supports the following hubs with Z-Wave support:
- [Vera](/components/vera/)
- [Wink](/components/wink/)

112
source/getting-started/z-wave-device-specific.markdown
View file

@ -1,112 +0,0 @@
---
layout: page
title: "Z-Wave Device Specific Settings"
description: "Extended instructions how to setup Z-Wave."
date: 2016-03-24 08:49 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
##### {% linkable_title Motion or alarm sensors %}
In order for Home Assistant to recognize the sensor properly, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`.
These devices will either show as a binary sensor or a sensor called `Alarm xxxx` and will report a numeric value. Test to see what value is what. Sometimes this is noted in the device manual.
As of version 0.30 you can set the settings of a Z-Wave device through the dev_service page of Home Assistant with the service: `zwave/set_config_parameter`.
The following parameters can be entered:
- **node_id** (*Required*): The node_id of the device that you are going to set a parameter to.
- **parameter** (*Required*): The index number of the parameter to be set. Refer to device manual or zwcfg_[home_id].xml
- **value** (*Required*): The value to set the parameter to. Refer to device manual or zwcfg_[home_id].xml
- **size** (*Optional*): The size of the value. It is normally not needed to specify this parameter, but in some cases it's needed. Check OZW.log for details on this.
You should check OZW.log to see if your new setting has been set
Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6:
```yaml
# Example entry in dev-service
{
"node_id": 42,
"parameter": 5,
"value": 2
}
```
##### {% linkable_title Locks and other secure devices %}
These devices require a network key to be set for the Z-Wave network before they are paired. This key is set in OpenZWave's `options.xml` which is located in OpenZWave's directory. This should also be the same directory as `config_path:` in your `configuration.yaml`. If it's not, make sure you have the same values in all the files you are using.
The option is commented out by default in `options.xml` and is a default key. Make your own unique key. The key is in Hexadecimals.
It is best to pair these devices in OpenZWave Control Panel or another Z-Wave tool that can show you logs while pairing. Home Assistant stores logs from Z-Wave in `OZW.log` in the Home Assistant config directory.
You should see communication from the node with lines starting with `info: NONCES` in `OZW.log` when the device is paired successfully with a secure connection. If you use OpenZWave Control Panel to pair, test the device before you save the configuration.
Make sure you copy the newly saved `zwcfg_[home_id].xml`into your Home Assistant configuration directory.
##### {% linkable_title Aeon Minimote %}
Here's a handy configuration for the Aeon Labs Minimote that defines all possible button presses. Put it into `automation.yaml`.
```yaml
- alias: Minimote Button 1 Pressed
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 1
- alias: Minimote Button 1 Held
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 2
- alias: Minimote Button 2 Pressed
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 3
- alias: Minimote Button 2 Held
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 4
- alias: Minimote Button 3 Pressed
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 5
- alias: Minimote Button 3 Held
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 6
- alias: Minimote Button 4 Pressed
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 7
- alias: Minimote Button 4 Held
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
scene_id: 8
```

30
source/getting-started/z-wave-settings.markdown
View file

@ -1,30 +0,0 @@
---
layout: page
title: "Z-Wave Settings"
description: "Extended instructions how to setup Z-Wave."
date: 2016-03-24 08:49 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
You may wish to modify the Z-Wave settings in your `ozw*.xml` file (stored in the `.homeassistant` configuration directory), or certain situations/devices may require it (i.e. Aeon Multisensor 6). To do this, utilize [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel). Alternatively, use [Domoticz](https://www.domoticz.com/), which incorporates the Open-Zwave Control Panel project into an easy to use Raspberry Pi image.
The reasoning for using these tools is that your Z-Wave controller stores the values and data that are used to control the network. The XML file in the `.homeassistant` configuration directory acts as a settings/values cache for the Z-Wave network, so modifying it directly won't change the network values. The [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel) writes values directly to the network and will provide you with an updated `.xml` file to overwrite in your `.homeassistant` configuration directory. This is the most foolproof way to make modifications to your Z-Wave devices.
It's totally normal for your Z-Wave stick (Aeon Aeotec Z-Stick Gen5 for example) to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. If you don't like this behaviour it can be turned off.
Use the following example commands from a terminal session on your Pi where your Z-Wave stick is connected.
Turn off "Disco lights":
```bash
$ echo -e -n "\x01\x08\x00\xF2\x51\x01\x00\x05\x01\x51" > /dev/serial/by-id/usb-0658_0200-if00
```
Turn on "Disco lights":
```bash
$ echo -e -n "\x01\x08\x00\xF2\x51\x01\x01\x05\x01\x50" > /dev/serial/by-id/usb-0658_0200-if00
```

267
source/getting-started/z-wave.markdown
View file

@ -1,267 +0,0 @@
---
layout: page
title: "Z-Wave"
description: "Instructions how to integrate your existing Z-Wave within Home Assistant."
date: 2016-02-27 19:59
sidebar: true
comments: false
sharing: true
footer: true
---
[Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick or module](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host.
There is currently support for climate, covers, lights, locks, sensors, switches and thermostats. All will be picked up automatically after configuring this platform.
### {% linkable_title Installation in Virtualenv (python-OpenZWave) %}
If you installed Home Assistant using a virtual environment then please read the instructions on [Installing python-OpenZWave in a virtualenv](https://home-assistant.io/getting-started/installation-virtualenv/#installing-python-openzwave-in-a-virtualenv).
### {% linkable_title Installation %}
To allow Home Assistant to talk to your Z-Wave USB stick you will have to compile the OpenZWave library and install the related [python-OpenZWave package](https://github.com/OpenZWave/python-openzwave). This can be done as follows. _(Note: The Home Assistant docker image and the All In One installer have support for Z-Wave already built-in!)_
Make sure you have the correct dependencies installed before running the script:
```bash
$ sudo apt-get install cython3 libudev-dev python3-sphinx python3-setuptools git
```
Make sure you have at least version 0.23 and at the most 0.24.1 of cython.
```bash
$ sudo pip3 install --upgrade cython==0.24.1
```
Then get the OpenZWave files and switch to the `python3` branch:
<p class='note warning'>Do not use root to build python-openzwave as it will surely fail.</p>
```bash
$ git clone https://github.com/OpenZWave/python-openzwave.git
$ cd python-openzwave
$ git checkout python3
$ PYTHON_EXEC=$(which python3) make build
$ sudo PYTHON_EXEC=$(which python3) make install
```
<p class='note'>
Instead of `make install`, you can alternatively build your own python-openzwave package which can be easily uninstalled:
</p>
```bash
$ sudo apt-get install -y checkinstall
$ sudo PYTHON_EXEC=$(which python3) checkinstall --pkgname python-openzwave --pkgversion 1.0 --provides python-openzwave
```
With this installation, your `config_path` needed below will resemble:
```bash
/usr/local/lib/python3.4/dist-packages/libopenzwave-0.3.0b8-py3.4-linux-x86_64.egg/config
```
If you followed along with setting up a virtual environment, your path will be:
```bash
/srv/homeassistant/python-openzwave/openzwave/config
```
### {% linkable_title Configuration %}
```yaml
# Example configuration.yaml entry
zwave:
usb_path: /dev/ttyUSB0
```
Configuration variables:
- **usb_path** (*Optional*): The port where your device is connected to your Home Assistant host.
- **config_path** (*Optional*): The path to the Python OpenZWave configuration files. Defaults to the folder `config` in your Python OpenZWave install directory.
- **autoheal** (*Optional*): Allows disabling auto Z-Wave heal at midnight. Defaults to True.
- **polling_interval** (*Optional*): The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems.
- **customize** (*Optional*): This attribute contains node-specific override values. See [Customizing devices and services](https://home-assistant.io/getting-started/customizing-devices/) for format:
- **polling_intensity** (*Optional*): Enables polling of a value and sets the frequency of polling (0=none, 1=every time through the list, 2=every other time, etc). If not specified then your device will not be polled.
- **ignored** (*Optional*): Ignore this entitiy completely. It won't be shown in the Web Interface and no events are generated for it.
- **refresh_value** (*Optional*): Enable refreshing of the node value. Only the light component uses this. Defaults to False.
- **delay** (*Optional*): Specify the delay for refreshing of node value. Only the light component uses this. Defaults to 2 seconds.
- **debug** (*Optional*): Print verbose z-wave info to log. Defaults to False.
To find the path of your Z-Wave USB stick or module, run:
```bash
$ ls /dev/ttyUSB*
```
Or, on some other systems (such as Raspberry Pi), use:
```bash
$ ls /dev/ttyACM*
# If `hass` runs with another user (e.g. *homeassistant* on Hassbian) give access to the stick with:
$ sudo usermod -a -G dialout homeassistant
```
Or, on some other systems (such as Pine 64), use:
```bash
$ ls /dev/ttyS*
```
Or, on macOS, use:
```bash
$ ls /dev/cu.usbmodem*
```
<p class='note'>
Depending on what's plugged into your USB ports, the name found above may change. You can lock in a name, such as `/dev/zwave`, by following [these instructions](http://hintshop.ludvig.co.nz/show/persistent-names-usb-serial-devices/).
</p>
### {% linkable_title Adding Devices %}
To add a Z-Wave device to your system, go to the Services menu and select the `zwave` domain, and select the `add-node` service. Then find your device's add button and press that as well.
### {% linkable_title Adding Security Devices %}
Security Z-Wave devices require a network key before being added to the network using the `zwave.add_node_secure` service. You must edit the `options.xml` file, located in your `python-openzwave config_path` to use a network key before adding these devices.
Edit your `options.xml` file:
```bash
<!-- <Option name="NetworkKey" value="0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F 0x10" /> -->
```
Uncomment the line:
```bash
<Option name="NetworkKey" value="0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10" />
```
You can replace these values with your own 16 byte network key. For more information on this process see the [OpenZwave](https://github.com/OpenZWave/open-zwave) wiki article [Adding Security Devices to OZW](https://github.com/OpenZWave/open-zwave/wiki/Adding-Security-Devices-to-OZW)
An easy script to generate a random key:
```bash
cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g'
```
### {% linkable_title Events %}
#### {% linkable_title zwave.network_complete %}
Home Assistant will trigger a event when the Z-Wave network is complete. Meaning all of the nodes on the network have been queried. This can take quite some time, depending on wakeup intervals on the battery powered devices on the network.
```yaml
- alias: Z-Wave network is complete
trigger:
platform: event
event_type: zwave.network_complete
```
#### {% linkable_title zwave.network_ready %}
Home Assistant will trigger a event when the Z-Wave network is ready for use. Between `zwave.network_start` and `zwave.network_ready` Home Assistant will feel sluggish when trying to send commands to Z-Wave nodes. This is because the controller is requesting information from all of the nodes on the network. When this is triggered all awake nodes have been queried and sleeping nodes will be queried when they awake.
```yaml
- alias: Z-Wave network is ready
trigger:
platform: event
event_type: zwave.network_ready
```
#### {% linkable_title zwave.network_start %}
Home Assistant will trigger a event when the Z-Wave network is set up to be started.
```yaml
- alias: Z-Wave network is starting
trigger:
platform: event
event_type: zwave.network_start
```
#### {% linkable_title zwave.network_stop %}
Home Assistant will trigger a event when the Z-Wave network stopping.
```yaml
- alias: Z-Wave network is stopping
trigger:
platform: event
event_type: zwave.network_stop
```
#### {% linkable_title zwave.node_event %}
Home Assistant will trigger a event when command_class_basic changes value on a node.
This can be virtually anything, so tests have to be made to determine what value equals what.
You can use this for automations.
Example:
```yaml
- alias: Minimote Button Pressed
trigger:
platform: event
event_type: zwave.node_event
event_data:
object_id: aeon_labs_minimote_1
basic_level: 255
```
The *object_id* and *basic_level* of all triggered events can be seen in the console output.
#### {% linkable_title zwave.scene_activated %}
Some devices can also trigger scene activation events, which can be used in automation scripts (for example the press of a button on a wall switch):
```yaml
# Example configuration.yaml automation entry
automation:
- alias: Turn on Desk light
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: zwaveme_zme_wallcs_secure_wall_controller_8
scene_id: 11
```
The *object_id* and *scene_id* of all triggered events can be seen in the console output.
### {% linkable_title Services %}
The `zwave` component exposes multiple services to help maintain the network.
| Service | Description |
| ------- | ----------- |
| add_node | Put the Z-Wave controller in inclusion mode. Allows one to add a new device to the Z-Wave network.|
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows one to add a new device with secure communications to the Z-Wave network. |
| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decides you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| change_association | Add or remove an association in the Z-Wave network |
| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
| print_config_parameter | Prints Z-wave node's config parameter value to the log.
| remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.|
| rename_node | Sets a node's name. Requires an `entity_id` and `name` field. |
| set_config_parameter | Let's the user set a config parameter to a node.|
| soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|
| start_network | Starts the Z-Wave network.|
| stop_network | Stops the Z-Wave network.|
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead".|
The `soft_reset` and `heal_network` commands can be used as part of an automation script to help keep a Z-Wave network running reliably as shown in the example below. By default, Home Assistant will run a `heal_network` at midnight. This is a configuration option for the `zwave` component, the option defaults to `true` but can be disabled by setting `autoheal` to false. Using the `soft_reset` function with some Z-Wave controllers can cause the Z-Wave network to hang. If you're having issues with your Z-Wave network try disabling this automation.
```yaml
# Example configuration.yaml automation entry
automation:
- alias: soft reset at 2:30am
trigger:
platform: time
after: '2:30:00'
action:
service: zwave.soft_reset
- alias: heal at 2:31am
trigger:
platform: time
after: '2:31:00'
action:
service: zwave.heal_network
```