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

Merge branch 'current' into next

Browse source
This commit is contained in:
Fabian Affolter 2017-02-23 19:09:23 +01:00
commit 4edd1cf0ee
No known key found for this signature in database
GPG key ID: DDF3D6F44AAB1336
139 changed files with 1318 additions and 909 deletions
Download patch file Download diff file Expand all files Collapse all files

49
source/_docs/automation.markdown Normal file
View file

@ -0,0 +1,49 @@
---
layout: page
title: "Automating Home Assistant"
description: "Steps to help you get automation setup in Home Assistant."
date: 2015-09-19 09:40
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant offers a wide range of automation configurations. In this section, 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/#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
```
The example consists of three different parts: a [trigger](/docs/automation/trigger/), a [condition](/docs/automation/condition/) and an [action](/docs/automation/action/).
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.

70
source/_docs/automation/action.markdown Normal file
View file

@ -0,0 +1,70 @@
---
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
redirect_from: /getting-started/automation-action/
---
The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax](/docs/scripts/) 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](/components/scene/) which will allow you to define how you want your devices to be and have Home Assistant call the right services.
```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/_docs/automation/condition.markdown Normal file
View file

@ -0,0 +1,36 @@
---
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
redirect_from: /getting-started/automation-condition/
---
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](/docs/scripts/conditions/).
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
```

67
source/_docs/automation/examples.markdown Normal file
View file

@ -0,0 +1,67 @@
---
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
redirect_from: /getting-started/automation-examples/
---
Just some sample automation rules to get you started.
```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'
```

131
source/_docs/automation/templating.markdown Normal file
View file

@ -0,0 +1,131 @@
---
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
redirect_from: /getting-started/automation-templating/
---
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](/configuration/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]: /configuration/state_object/

150
source/_docs/automation/trigger.markdown Normal file
View file

@ -0,0 +1,150 @@
---
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
redirect_from: /getting-started/automation-trigger/
---
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"
```

26
source/_docs/automation/troubleshooting.markdown Normal file
View file

@ -0,0 +1,26 @@
---
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
redirect_from: /getting-started/automation-troubleshooting/
---
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/

19
source/_docs/autostart.markdown Normal file
View file

@ -0,0 +1,19 @@
---
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
redirect_from: /getting-started/autostart/
---
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.
- [systemd (Linux)](/docs/autostart/systemd/)
- [Upstart (Linux)](/docs/autostart/upstart/)
- [init.d (Linux)](/docs/autostart/init.d/)
- [macOS](/docs/autostart/macos/)
- [Synology NAS](/docs/autostart/synology/)

138
source/_docs/autostart/init.d.markdown Normal file
View file

@ -0,0 +1,138 @@
---
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
redirect_from: /getting-started/autostart-init.d/
---
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:
```bash
$ 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 %}
```bash
$ sudo update-rc.d hass-daemon defaults
```
### {% linkable_title 4. Install this service %}
```bash
$ 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 %}
```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
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
```

32
source/_docs/autostart/macos.markdown Normal file
View file

@ -0,0 +1,32 @@
---
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
redirect_from: /getting-started/autostart-macos/
---
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.
```

50
source/_docs/autostart/synology.markdown Normal file
View file

@ -0,0 +1,50 @@
---
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
redirect_from: /getting-started/autostart-synology/
---
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

108
source/_docs/autostart/systemd.markdown Normal file
View file

@ -0,0 +1,108 @@
---
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
redirect_from: /getting-started/autostart-systemd/
---
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@.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/_docs/autostart/upstart.markdown Normal file
View file

@ -0,0 +1,137 @@
---
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/_docs/backend.markdown Normal file
View file

@ -0,0 +1,17 @@
---
layout: page
title: "Backend of Home Assistant"
description: "Backend of Home Assistant."
date: 2017-02-14 12:50
sidebar: true
comments: false
sharing: true
footer: true
---
The frontend of Home Assistant is running with [Python 3](https://www.python.org/).
The [Architecture page](/developers/architecture/) show the details about the elements running in the background of Home Assistant.
To implement a new platform or component, please refer to the [Development documentation](/developers/development/).

126
source/_docs/backend/database.markdown Normal file
View file

@ -0,0 +1,126 @@
---
layout: page
title: "Database"
description: "Details about the database which Home Assistant is using."
date: 2016-10-10 10:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /details/database/
---
The default database that is used for Home Assistant is [SQLite](https://www.sqlite.org/) and is stored in your [configuration directory](/getting-started/configuration/), eg. `<path to config dir>/.homeassistant/home-assistant_v2.db`. You will need an installation of `sqlite3`, the command-line for SQLite database, or [DB Browser for SQLite](http://sqlitebrowser.org/) which provide an editor for executing SQL commands.
First load your database with `sqlite3`.
```bash
$ sqlite3 home-assistant_v2.db
SQLite version 3.13.0 2016-05-18 10:57:30
Enter ".help" for usage hints.
sqlite>
```
It helps to set some options to make the output better readable.
```bash
sqlite> .header on
sqlite> .mode column
```
You could also start `sqlite3` and attach the database later. Not sure what database you are working with? Check it, especially if you are going to delete data.
```bash
sqlite> .databases
seq name file
--- --------------- ----------------------------------------------------------
0 main /home/fab/.homeassistant/home-assistant_v2.db
```
### {% linkable_title Schema %}
Get all available tables from your current Home Assistant database.
```bash
sqlite> SELECT sql FROM sqlite_master;
-------------------------------------------------------------------------------------
CREATE TABLE events (
event_id INTEGER NOT NULL,
event_type VARCHAR(32),
event_data TEXT,
origin VARCHAR(32),
time_fired DATETIME,
created DATETIME,
PRIMARY KEY (event_id)
)
CREATE INDEX ix_events_event_type ON events (event_type)
CREATE TABLE recorder_runs (
run_id INTEGER NOT NULL,
start DATETIME,
"end" DATETIME,
closed_incorrect BOOLEAN,
created DATETIME,
PRIMARY KEY (run_id),
CHECK (closed_incorrect IN (0, 1))
)
CREATE TABLE states (
state_id INTEGER NOT NULL,
domain VARCHAR(64),
entity_id VARCHAR(64),
state VARCHAR(255),
attributes TEXT,
event_id INTEGER,
last_changed DATETIME,
last_updated DATETIME,
created DATETIME,
PRIMARY KEY (state_id),
FOREIGN KEY(event_id) REFERENCES events (event_id)
)
CREATE INDEX states__significant_changes ON states (domain, last_updated, entity_id)
CREATE INDEX states__state_changes ON states (last_changed, last_updated, entity_id)
CREATE TABLE sqlite_stat1(tbl,idx,stat)
```
To only show the details about the `states` table as we are using that one in the next examples.
```bash
sqlite> SELECT sql FROM sqlite_master WHERE type = 'table' AND tbl_name = 'states';
```
### {% linkable_title Query %}
The identification of the available columns in the table is done and we are now able to create a query. Let's list of your Top 10 entities.
```bash
sqlite> .width 30, 10,
sqlite> SELECT entity_id, COUNT(*) as count FROM states GROUP BY entity_id ORDER BY count DESC LIMIT 10;
entity_id count
------------------------------ ----------
sensor.cpu 28874
sun.sun 21238
sensor.time 18415
sensor.new_york 18393
cover.kitchen_cover 17811
switch.mystrom_switch 14101
sensor.internet_time 12963
sensor.solar_angle1 11397
sensor.solar_angle 10440
group.all_switches 8018
```
### {% linkable_title Delete %}
If you don't want to keep certain entities, you can delete them permanently.
```bash
sqlite> DELETE FROM states WHERE entity_id="sensor.cpu";
```
The `VACUUM` command cleans the your database.
```bash
sqlite> VACUUM;
```
For a more interactive way to work with the database or the create statistics, checkout our [Jupyther notebooks](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/).

52
source/_docs/backend/updater.markdown Normal file
View file

@ -0,0 +1,52 @@
---
layout: page
title: "Updater"
description: "Details what the updater component is reporting about your Home Assistant instance."
date: 2016-10-22 08:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /details/updater/
---
Starting with 0.31 the [updater component](/components/updater/) sends an optional report about Home Assistant instance.
We are only collecting this information to better understand our user base to provide better long term support and feature development.
| Name | Description | Example | Data Source |
|-----------------------|--------------------------------------------|------------------------------------|----------------|
| `arch` | CPU Architecture | `x86_64` | Local Instance |
| `distribution` | Linux Distribution name (only Linux) | `Ubuntu` | Local Instance |
| `docker` | True if running inside Docker | `false` | Local Instance |
| `first_seen_datetime` | First time instance ID was submitted | `2016-10-22T19:56:03.542Z` | Update Server |
| `geo_city` | GeoIP determined city | `Oakland` | Update Server |
| `geo_country_code` | GeoIP determined country code | `US` | Update Server |
| `geo_country_name` | GeoIP determined country name | `United States` | Update Server |
| `geo_latitude` | GeoIP determined latitude | `37.8047` | Update Server |
| `geo_longitude` | GeoIP determined longitude | `-122.2124` | Update Server |
| `geo_metro_code` | GeoIP determined metro code | `807` | Update Server |
| `geo_region_code` | GeoIP determined region code | `CA` | Update Server |
| `geo_region_name` | GeoIP determined region name | `California` | Update Server |
| `geo_time_zone` | GeoIP determined time zone | `America/Los_Angeles` | Update Server |
| `geo_zip_code` | GeoIP determined zip code | `94602` | Update Server |
| `last_seen_datetime` | Most recent time instance ID was submitted | `2016-10-22T19:56:03.542Z` | Update Server |
| `os_name` | Operating system name | `Darwin` | Local Instance |
| `os_version` | Operating system version | `10.12` | Local Instance |
| `python_version` | Python version | `3.5.2` | Local Instance |
| `timezone` | Timezone | `America/Los_Angeles` | Local Instance |
| `user_agent` | User agent used to submit analytics | `python-requests/2.11.1` | Local Instance |
| `uuid` | Unique identifier | `10321ee6094d4a2ebb5ed55c675d5f5e` | Local Instance |
| `version` | Home Assistant version | `0.31.0` | Local Instance |
| `virtualenv` | True if running inside virtualenv | `true` | Local Instance |
In addition to the above collected data, the server will also use your IP address to do a geographic IP address lookup to determine a general geographic area that your address is located in. To be extremely, extremely clear about this bit: __The Home Assistant updater does not: store your IP address in a database and also does not submit the location information from your `configuration.yaml`.__
Our tests showed that at best, we get 4 digits of accuracy on your IP address location which is a 5 mile radius of your actual IP location, assuming that it is even correct in the first place (geo IP lookups are very hit or miss).
The server also adds two timestamps to the data:
- the original date your instance UUID was first seen
- the timestamp of the last time we have seen your instance
There are currently no plans to publicly expose any of this information. If we did do such a thing in the future we would of course notify you in advance. It must also be stated that we will never sell or allow the use of this information for non-Home Assistant purposes.

35
source/_docs/configuration.markdown Normal file
View file

@ -0,0 +1,35 @@
---
layout: page
title: "Configuring Home Assistant"
description: "Configuring Home Assistant."
date: 2015-03-23 12:50
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.
The location of the folder differs between operating systems:
| OS | Path |
| -- | ---- |
| macOS | `~/.homeassistant` |
| Linux | `~/.homeassistant` |
| Windows | `%APPDATA%/.homeassistant` |
If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`.
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.
<p class='note'>
You will have to restart Home Assistant for changes to `configuration.yaml` to take effect.
</p>
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>

51
source/_docs/configuration/basic.markdown Normal file
View file

@ -0,0 +1,51 @@
---
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
redirect_from: /getting-started/basic/
---
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.

70
source/_docs/configuration/customizing-devices.markdown Normal file
View file

@ -0,0 +1,70 @@
---
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
redirect_from: /getting-started/customizing-devices/
---
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.
| `device_class` | Sets the class of the device, changing the device state and icon that is displayed on the UI (see below).
### {% linkable_title Device Class %}
Device class is currently supported by the following platforms:
* [Binary Sensor](/components/binary_sensor/)
* [Cover](/components/cover/)
### {% linkable_title Device Class %}
Device class is currently supported by the following platforms:
* [Binary Sensor](/components/binary_sensor/)
* [Cover](/components/cover/)
### {% 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>

70
source/_docs/configuration/devices.markdown Normal file
View file

@ -0,0 +1,70 @@
---
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
redirect_from: /getting-started/devices/
---
Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component](/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 (<img src='/images/screenshots/developer-tool-states-icon.png' alt='service developer tool icon' class="no-shadow" height="38" />).
```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](/components/group/) page.

85
source/_docs/configuration/events.markdown Normal file
View file

@ -0,0 +1,85 @@
---
layout: page
title: "Events"
description: "Describes all there is to know about events in Home Assistant."
date: 2016-03-12 12:00 -0800
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/events/
---
The core of Home Assistant is the event bus. The event bus allows any component to fire or listen for events. It is the core of everything. For example, any state change will be announced on the event bus as a `state_changed` event containing the previous and the new state of an entity.
Home Assistant contains a few built-in events that are used to coordinate between various components.
### {% linkable_title Event `homeassistant_start` %}
Event `homeassistant_start` is fired when all components from the configuration have been intitialized. This is the event that will start the timer firing off `time_changed` events.
### {% linkable_title Event `homeassistant_stop` %}
Event `homeassistant_stop` is fired when Home Assistant is shutting down. It should be used to close any open connection or release any resources.
### {% linkable_title Event `state_changed` %}
Event `state_changed` is fired when a state changes. Both `old_state` and `new_state` are state objects. [Documentation about state objects.](/topics/state_object/)
Field | Description
----- | -----------
`entity_id` | Entity ID of the changed entity. Example: `light.kitchen`
`old_state` | The previous state of the entity before it changed. This field is ommitted if the entity is new.
`new_state` | The new state of the entity. This field is ommitted if the entity is removed from the state machine.
### {% linkable_title Event `time_changed` %}
Event `time_changed` is fired every second by the timer and contains the current time.
Field | Description
----- | -----------
`now` | A [datetime object](https://docs.python.org/3.4/library/datetime.html#datetime.datetime) containing the current time in UTC.
### {% linkable_title Event `service_registered` %}
Event `service_registered` is fired when a new service has been registered within Home Assistant.
Field | Description
----- | -----------
`domain` | Domain of the service. Example: `light`.
`service` | The service to call. Example: `turn_on`
### {% linkable_title Event `call_service` %}
Event `call_service` is fired to call a service.
Field | Description
----- | -----------
`domain` | Domain of the service. Example: `light`.
`service` | The service to call. Example: `turn_on`
`service_data` | Dictionary with the service call parameters. Example: `{ 'brightness': 120 }`.
`service_call_id` | String with a unique call id. Example: `23123-4`.
### {% linkable_title Event `service_executed` %}
Event `service_executed` is fired by the service handler to indicate the service is done.
Field | Description
----- | -----------
`service_call_id` | String with the unique call id of the service call that was executed. Example: `23123-4`.
### {% linkable_title Event `platform_discovered` %}
Event `platform_discovered` is fired when a new platform has been discovered by the discovery component.
Field | Description
----- | -----------
`service` | The service that is discovered. Example: `zwave`.
`discovered` | Information that is discovered. Can be a dict, tuple etc. Example: `(192.168.1.10, 8889)`.
### {% linkable_title Event `component_loaded` %}
Event `component_loaded` is fired when a new component has been loaded and initialized.
Field | Description
----- | -----------
`component` | Domain of the component that has just been initialized. Example: `light`.

180
source/_docs/configuration/group_visibility.markdown Normal file
View file

@ -0,0 +1,180 @@
---
layout: page
title: "Group Visibility"
description: "Instructions how to change group visibility using automations."
date: 2016-10-29 13:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/group_visibility/
---
After filling Home Assistant with all your precious home automation devices, you usually end up with a cluttered interface and lots of groups that are not interesting in your current context. What if you just want to show groups that are interesting _now_ and hide the rest? That's when group visibility comes to play.
## {% linkable_title Changing visibility of a group %}
To change visibility of a group, use the service `group.set_visibility`, pass the group name as `entity_id` and use `visible` to decide wheter the group should be shown or hidden.
```yaml
service: group.set_visibility
entity_id: group.basement
data:
visible: False
```
<p class='note'>
If a sensor belongs to only one group and that group is hidden, the sensor will "jump" to the top of the web interface. Add the sensor to an additional (visible) group if you do not want this to happen.
</p>
## {% linkable_title Automations %}
First you should decide under which circumstances a group should be visible or not. Depending on the complexity, you might have to write two automations: one that hides the group and another that shows it.
In this example, the group `group.basement` is hidden when the sun sets and shown again when it rises:
```yaml
automation:
trigger:
platform: sun
event: sunset
action:
service: group.set_visibility
entity_id: group.basement
data:
visible: False
automation 2:
trigger:
platform: sun
event: sunrise
action:
service: group.set_visibility
entity_id: group.basement
data:
visible: True
```
## {% linkable_title Easier automations %}
One of the most common uses cases are to show groups during certain times of day, maybe commuting information during a work day morning or light switches when it is getting dark. The complexity of automations needed to make this happen will quickly get out of hand. So, one way to make the automations easier is to create a sensor that alters its state depending on time of day. One way of doing that is using a `command_line` sensor and a script:
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from datetime import time, datetime
def mk_occasion(name, start, end, days=None):
s = start.split(':')
e = end.split(':')
return {'name' : name,
'start': time(int(s[0]), int(s[1]), int(s[2])),
'end' : time(int(e[0]), int(e[1]), int(e[2])),
'days' : days}
# Matching is done from top to bottom
OCCASIONS = [
# More specific occasions
mk_occasion('work_morning', '06:00:00', '07:10:00', range(5)),
# General matching
mk_occasion('weekday', '00:00:00', '23:59:59', range(5)),
mk_occasion('weekend', '00:00:00', '23:59:59', [5, 6])
]
def get_current_occasion(occasion_list, default_occasion='normal'):
now = datetime.now()
for occasion in OCCASIONS:
if occasion['start'] <= now.time() <= occasion['end'] and \
(occasion['days'] is None or now.weekday() in occasion['days']):
return occasion['name']
return default_occasion
if __name__ == '__main__':
print(get_current_occasion(OCCASIONS))
```
This script will output "work_morning" from 06:00-07:10 during weekdays (monday-friday), "weekday" during all other time from monday-friday and "weekend" on saturdays and sundays. Adjust according to your needs. To create the sensor, just add it like this:
```yaml
sensor:
- platform: command_line
name: Occasion
command: "python3 occasion.py"
```
To simplify things, we create a Home Assistant script that changes the visibility of a group, but also verifies that an entity is in a specific state:
```yaml
script:
group_visibility:
sequence:
- service: group.set_visibility
data_template:
entity_id: '{% raw %}{{ entity_id }}{% endraw %}'
visible: '{% raw %}{{ is_state(cond, visible_state) }}{% endraw %}'
```
The last part is writing an automation that hides or shows the group:
```yaml
automation:
- alias: Work morning
trigger:
- platform: state
entity_id: sensor.occasion
- platform: event
event_type: homeassistant_start
action:
service: script.group_visibility
data:
entity_id: group.work_sensors
cond: sensor.occasion
visible_state: 'work_morning'
```
Our previously defined script will be called if `sensor.occasion` changes state OR when Home Assistant has started. The group `group.work_sensors` will be shown when `sensor.occasion` changes state to "work_morning" and hidden otherwise.
### {% linkable_title The complete example %}
```yaml
group:
default_view:
entities:
- group.work_sensors
# Only visible when it's time to go to work
work_sensors:
name: Time to go to work
entities:
- sensor.something1
- sensor.something2
sensor:
- platform: command_line
name: Occasion
command: "python3 occasion.py"
script:
group_visibility:
sequence:
- service: group.set_visibility
data_template:
entity_id: '{% raw %}{{ entity_id }}{% endraw %}'
visible: '{% raw %}{{ is_state(cond, visible_state) }}{% endraw %}'
automation:
- alias: Work morning
trigger:
- platform: state
entity_id: sensor.occasion
- platform: event
event_type: homeassistant_start
action:
service: script.group_visibility
data:
entity_id: group.work_sensors
cond: sensor.occasion
visible_state: 'work_morning'
```

92
source/_docs/configuration/packages.markdown Normal file
View file

@ -0,0 +1,92 @@
---
layout: page
title: "Packages"
description: "Describes all there is to know about configuration packages in Home Assistant."
date: 2017-01-10 20:00 +0200
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/packages/
---
Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/docs/configuration/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/docs/configuration/splitting_configuration).
Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as:
```yaml
homeassistant:
...
packages:
pack_1:
...package configuration here...
```
The package configuration can include: `switch`, `light`, `automation`, `groups` or the majority of the Home Assistant components.
It can be specified inline or in a seperate YAML file using `!include`.
Inline example, main `configuration.yaml`:
```yaml
homeassistant:
...
packages:
pack_1:
switch:
- platform: rest
...
light:
- platform: rpi
...
```
Include example, main `configuration.yaml`:
```yaml
homeassistant:
...
packages:
pack_1: !include my_package.yaml
```
The file `my_package.yaml` contains the "top-level" configuration:
```
switch:
- platform: rest
...
light:
- platform: rpi
...
```
There are some rules for packages that will be merged:
1. Component names may only use the basic form (e.g. `switch` and `switch 1` or `switch aa` is not accepted).
2. Platform based components (`light`, `switch`, etc) can always be merged.
3. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file.
For example if we have the following in the main config. You are not allowed to re-use "my_input" again for `input_boolean` in a package:
```yaml
input_boolean:
my_input:
```
4. Any component that is not a platform [2], or dictionaries with Entity ID keys [3] cannot be merged and can only occur once between all packages and the main configuration.
<p class='note tip'>
Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the component name.
</p>
### {% linkable_title Create a packages folder %}
One way to organise packages would be to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a YAML file. This entry in your `configuration.yaml` will load all packages:
```yaml
homeassistant:
packages: !include_dir_named packages
```
This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames.
See the documentation about [splitting the configuration](/docs/configuration/splitting_configuration/) for more information about `!include_dir_named` and other include statements that might be helpful.

35
source/_docs/configuration/platform_options.markdown Normal file
View file

@ -0,0 +1,35 @@
---
layout: page
title: "Entity component platform options"
description: "Shows how to customize polling interval for any component via configuration.yaml."
date: 2016-02-12 23:17 -0800
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/platform_options/
---
Any component that is based on the entity component allows various extra options to be set per platform.
### {% linkable_title Entity namespace %}
By setting an entity namespace, all entities will be prefixed with that namespace. That way `light.bathroom` can become `light.holiday_house_bathroom`.
```yaml
# Example configuration.yaml entry
light:
platform: hue
entity_namespace: holiday_house
```
### {% linkable_title Scan Interval %}
Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a `scan_interval` config key. In the example below we setup the Philips Hue lights but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds.
```yaml
# Example configuration.yaml entry to poll Hue lights every 10 seconds.
light:
platform: hue
scan_interval: 10
```

24
source/_docs/configuration/remote.markdown Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: "Remote access"
description: "Setting up remote access for Home Assistant."
date: 2015-03-23 12:50
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/basic/#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.
Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/) between your client and the Home Assistant instance.
For another way to access your Home Assistant frontend, check out [the instructions how to use Tor](/cookbook/tor_configuration/).

91
source/_docs/configuration/secrets.markdown Normal file
View file

@ -0,0 +1,91 @@
---
layout: page
title: "Storing secrets"
description: "Storing secrets outside of your configuration.yaml."
date: 2016-07-01 08:30
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/secrets/
---
The `configuration.yaml` file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. By using `!secrets` you can remove any private information from you configuration files. This separation can also help you to keep easier track of your passwords and API keys. As they are all stored at one place and no longer spread across the `configuration.yaml` file or even multiple yaml files if you [split up your configuration](/topics/splitting_configuration/).
### {% linkable_title Using secrets.yaml %}
The workflow for moving private information to `secrets.yaml` is very similar to the [splitting of the configuration](/topics/splitting_configuration/). Create a `secrets.yaml` file in your Home assistant configuration directory (The location of the folder differs between operating systems: on OS X and Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`).
The entries for password and API keys in the `configuration.yaml` file usually looks like the example below.
```yaml
http:
api_password: YOUR_PASSWORD
```
Those entries need to be replaced with `!secret` and a identifier.
```yaml
http:
api_password: !secret http_password
```
The `secrets.yaml` file contains the corresponding password assigned to the identifier.
```yaml
http_password: YOUR_PASSWORD
```
### {% linkable_title Debugging secrets %}
When you start splitting your configuration into multiple files, you might end up with configuration in sub folders. Secrets will be resolved in this order:
- A `secrets.yaml` located in the same folder as the yaml file referencing the secret,
- next, parent folders will be searched for a `secrets.yaml` file with the secret, stopping at the folder with the main `configuration.yaml`,
- lastly, `keyring` will be queried for the secret (more info below)
To see where secrets are being loaded from you can either add an option to your `secrets.yaml` file or use the `check_config` script.
*Option 1*: Print where secrets are retrieved from to the Home Assistant log by adding the following to `secrets.yaml`:
```yaml
logger: debug
```
This will not print the actual secret's value to the log.
*Option 2*: View where secrets are retrieved from and the contents of all `secrets.yaml` files used, you can use the `check_config` script from the command line:
```bash
hass --script check_config --secrets
```
This will print all your secrets
### {% linkable_title Storing passwords in a keyring managed by your OS %}
Using [Keyring](http://pythonhosted.org/keyring/) is an alternative way to `secrets.yaml`. They can be managed from the command line via the keyring script.
```bash
$ hass --script keyring --help
```
To store a password in keyring, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your keyring.
```bash
$ hass --script keyring set http_password
```
If you launch Home Assistant now, you will be prompted for the keyring password to unlock your keyring.
```bash
$ hass
Config directory: /home/fab/.homeassistant
Please enter password for encrypted keyring:
```
<p class='note warning'>
If your are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
</p>

30
source/_docs/configuration/securing.markdown Normal file
View file

@ -0,0 +1,30 @@
---
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
redirect_from: /getting-started/securing/
---
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/)

443
source/_docs/configuration/splitting_configuration.markdown Normal file
View file

@ -0,0 +1,443 @@
---
layout: page
title: "Splitting up the configuration"
description: "Splitting the configuration.yaml into several files."
date: 2016-03-25 23:30
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/yaml/
---
So you've been using Home Assistant for a while now and your [configuration.yaml file brings people to tears](https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/) or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: humanly readable) pieces.
First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](https://home-assistant.io/cookbook/#example-configurationyaml).
As commenting code doesn't always happen, please read on for the details.
Now despite the logical assumption that the `configuration.yaml` will be replaced by this process it will in fact remain, albeit in a much less cluttered form.
In this lighter version we will still need what could be called the core snippet:
```yaml
homeassistant:
# Name of the location where Home Assistant is running
name: My Home Assistant Instance
# Location required to calculate the time the sun rises and sets
latitude: 37
longitude: -121
# 'metric' for Metric, 'imperial' for Imperial
unit_system: imperial
# Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
time_zone: America/Los_Angeles
customize: !include customize.yaml
```
Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under `customize:`.
`!include filename.yaml` is the statement that tells Home Assistant to insert the contents of `filename.yaml` at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.
Now before we start splitting out the different components, let's look at the other components (in our example) that will stay in the base file:
```yaml
history:
frontend:
logbook:
http:
api_password: ImNotTelling!
ifttt:
key: [nope]
wink:
access_token: [wouldn't you]
refresh_token: [like to know]
zwave:
usb_path: /dev/ttyUSB0
config_path: /usr/local/share/python-openzwave/config
polling_interval: 10000
mqtt:
broker: 127.0.0.1
```
As with the core snippet, indentation makes a difference. The component headers (`mqtt:`) should be fully left aligned (aka no indent), and the parameters (`broker:`) should be indented two (2) spaces.
While some of these components can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact. (Look at the `zigbee:` entry above and the b entry further down)
Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following:
```text
automation.yaml
zones.yaml
sensors.yaml
switches.yaml
device_tracker.yaml
customize.yaml
```
`automation.yaml` will hold all the automation component details. `zones.yaml` will hold the zone component details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of.
Inside the base configuration file add the following entries:
```yaml
automation: !include automation.yaml
zone: !include zones.yaml
sensor: !include sensors.yaml
switch: !include switches.yaml
device_tracker: !include device_tracker.yaml
```
Note that there can only be one `!include:` for each component so chaining them isn't going to work. If that sounds like greek, don't worry about it.
Alright, so we've got the single components and the include statements in the base file, what goes in those extra files?
Let's look at the `device_tracker.yaml` file from our example:
```yaml
- platform: owntracks
- platform: nmap_tracker
hosts: 192.168.2.0/24
home_interval: 3
track_new_devices: yes
interval_seconds: 40
consider_home: 120
```
This small example illustrates how the "split" files work. In this case, we start with a "comment block" identifying the file followed by two (2) device tracker entries (`owntracks` and `nmap`). These files follow ["style 1"](/getting-started/devices/#style-2-list-each-device-separately) that is to say a fully left aligned leading entry (`- platform: owntracks`) followed by the parameter entries indented two (2) spaces.
This (large) sensor configuration gives us another example:
```yaml
### sensors.yaml
### METEOBRIDGE #############################################
- platform: tcp
name: 'Outdoor Temp (Meteobridge)'
host: 192.168.2.82
timeout: 6
payload: "Content-type: text/xml; charset=UTF-8\n\n"
value_template: "{% raw %}{{value.split (' ')[2]}}{% endraw %}"
unit: C
- platform: tcp
name: 'Outdoor Humidity (Meteobridge)'
host: 192.168.2.82
port: 5556
timeout: 6
payload: "Content-type: text/xml; charset=UTF-8\n\n"
value_template: "{% raw %}{{value.split (' ')[3]}}{% endraw %}"
unit: Percent
#### STEAM FRIENDS ##################################
- platform: steam_online
api_key: [not telling]
accounts:
- 76561198012067051
#### TIME/DATE ##################################
- platform: time_date
display_options:
- 'time'
- 'date'
- platform: worldclock
time_zone: Etc/UTC
name: 'UTC'
- platform: worldclock
time_zone: America/New_York
name: 'Ann Arbor'
```
You'll notice that this example includes a secondary parameter section (under the steam section) as well as a better example of the way comments can be used to break down files into sections.
That about wraps it up.
If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to the [Gitter Chatroom](https://gitter.im/balloob/home-assistant) and ask away.
### {% linkable_title Debugging multiple configuration files %}
If you have many configuration files, the `check_config` script allows you to see how Home Assistant interprets them:
- Listing all loaded files: `hass --script check_config --files`
- Viewing a component's config: `hass --script check_config --info light`
- Or all components' config: `hass --script check_config --info all`
You can get help from the command line using: `hass --script check_config --help`
### {% linkable_title Advanced Usage %}
We offer four advanced options to include whole directories at once.
- `!include_dir_list` will return the content of a directory as a list with each file content being an entry in the list.
- `!include_dir_named` will return the content of a directory as a dictionary which maps filename => content of file.
- `!include_dir_merge_list` will return the content of a directory as a list by merging all files (which should contain a list) into 1 big list.
- `!include_dir_merge_named` will return the content of a directory as a dictionary by loading each file and merging it into 1 big dictionary.
These work recursively. As an example using `!include_dir_* automation`, will include all 6 files shown below:
```bash
.
└── .homeassistant
├── automation
│   ├── lights
│   │   ├── turn_light_off_bedroom.yaml
│   │   ├── turn_light_off_lounge.yaml
│   │   ├── turn_light_on_bedroom.yaml
│   │   └── turn_light_on_lounge.yaml
│   ├── say_hello.yaml
│   └── sensors
│   └── react.yaml
└── configuration.yaml (not included)
```
#### {% linkable_title Example: `!include_dir_list` %}
`configuration.yaml`
```yaml
automation:
- alias: Automation 1
trigger:
platform: state
entity_id: device_tracker.iphone
to: 'home'
action:
service: light.turn_on
entity_id: light.entryway
- alias: Automation 2
trigger:
platform: state
entity_id: device_tracker.iphone
from: 'home'
action:
service: light.turn_off
entity_id: light.entryway
```
can be turned into:
`configuration.yaml`
```yaml
automation: !include_dir_list automation/presence/
```
`automation/presence/automation1.yaml`
```yaml
alias: Automation 1
trigger:
platform: state
entity_id: device_tracker.iphone
to: 'home'
action:
service: light.turn_on
entity_id: light.entryway
```
`automation/presence/automation2.yaml`
```yaml
alias: Automation 2
trigger:
platform: state
entity_id: device_tracker.iphone
from: 'home'
action:
service: light.turn_off
entity_id: light.entryway
```
It is important to note that each file must contain only **one** entry when using `!include_dir_list`.
#### {% linkable_title Example: `!include_dir_named` %}
`configuration.yaml`
```yaml
{% raw %}
alexa:
intents:
LocateIntent:
action:
service: notify.pushover
data:
message: Your location has been queried via Alexa.
speech:
type: plaintext
text: >
{%- for state in states.device_tracker -%}
{%- if state.name.lower() == User.lower() -%}
{{ state.name }} is at {{ state.state }}
{%- endif -%}
{%- else -%}
I am sorry. Pootie! I do not know where {{User}} is.
{%- endfor -%}
WhereAreWeIntent:
speech:
type: plaintext
text: >
{%- if is_state('device_tracker.iphone', 'home') -%}
iPhone is home.
{%- else -%}
iPhone is not home.
{% endif %}{% endraw %}
```
can be turned into:
`configuration.yaml`
```yaml
alexa:
intents: !include_dir_named alexa/
```
`alexa/LocateIntent.yaml`
```yaml
{% raw %}
action:
service: notify.pushover
data:
message: Your location has been queried via Alexa.
speech:
type: plaintext
text: >
{%- for state in states.device_tracker -%}
{%- if state.name.lower() == User.lower() -%}
{{ state.name }} is at {{ state.state }}
{%- endif -%}
{%- else -%}
I am sorry. Pootie! I do not know where {{User}} is.
{%- endfor -%}{% endraw %}
```
`alexa/WhereAreWeIntent.yaml`
```yaml
{% raw %}
speech:
type: plaintext
text: >
{%- if is_state('device_tracker.iphone', 'home') -%}
iPhone is home.
{%- else -%}
iPhone is not home.
{% endif %}{% endraw %}
```
#### {% linkable_title Example: `!include_dir_merge_list` %}
`configuration.yaml`
```yaml
automation:
- alias: Automation 1
trigger:
platform: state
entity_id: device_tracker.iphone
to: 'home'
action:
service: light.turn_on
entity_id: light.entryway
- alias: Automation 2
trigger:
platform: state
entity_id: device_tracker.iphone
from: 'home'
action:
service: light.turn_off
entity_id: light.entryway
```
can be turned into:
`configuration.yaml`
```yaml
automation: !include_dir_merge_list automation/
```
`automation/presence.yaml`
```yaml
- alias: Automation 1
trigger:
platform: state
entity_id: device_tracker.iphone
to: 'home'
action:
service: light.turn_on
entity_id: light.entryway
- alias: Automation 2
trigger:
platform: state
entity_id: device_tracker.iphone
from: 'home'
action:
service: light.turn_off
entity_id: light.entryway
```
It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen [-]). Each file may contain one or more entries.
#### {% linkable_title Example: `!include_dir_merge_named` %}
`configuration.yaml`
```yaml
group:
bedroom:
name: Bedroom
entities:
- light.bedroom_lamp
- light.bedroom_overhead
hallway:
name: Hallway
entities:
- light.hallway
- thermostat.home
front_yard:
name: Front Yard
entities:
- light.front_porch
- light.security
- light.pathway
- sensor.mailbox
- camera.front_porch
```
can be turned into:
`configuration.yaml`
```yaml
group: !include_dir_merge_named group/
```
`group/interior.yaml`
```yaml
bedroom:
name: Bedroom
entities:
- light.bedroom_lamp
- light.bedroom_overhead
hallway:
name: Hallway
entities:
- light.hallway
- thermostat.home
```
`group/exterior.yaml`
```yaml
front_yard:
name: Front Yard
entities:
- light.front_porch
- light.security
- light.pathway
- sensor.mailbox
- camera.front_porch
```

43
source/_docs/configuration/state_object.markdown Normal file
View file

@ -0,0 +1,43 @@
---
layout: page
title: "State Objects"
description: "Describes all there is to know about state objects in Home Assistant."
date: 2016-03-12 12:00 -0800
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/state_object/
---
Your devices are represented in Home Assistant as entities. The entities will write their current state to the state machine for other entities/templates/frontend to access. States are a current representation of the entity.
If you overwrite a state via the states dev tool or the API, it will not impact the actual device. If the device state is being polled, it will overwrite the state in the state machine the next polling.
All states will always have an entity id, a state and a timestamp when last updated and last changed.
Field | Description
----- | -----------
`state.state` | String representation of the current state of the entity. Example `off`
`state.entity_id` | Entity ID. Format: `<domain>.<object_id>`. Example: `light.kitchen`.
`state.domain` | Domain of the entity. Example: `light`.
`state.object_id` | Object ID of entity. Example: `kitchen`.
`state.name` | Name of the entity. Based on `friendly_name` attribute with fall back to object ID. Example: `Kitchen Ceiling`.
`state.last_updated` | Time the state was written to the state machine. Note that writing the exact same state including attributes will not result in this field being updated. Example: `14:10:03 13-03-2016`.
`state.last_changed` | Time the state changed. This is not updated when there are only updated attributes. Example: `14:10:03 13-03-2016`.
`state.attributes` | A dictionary with extra attributes related to the current state.
The attributes of an entity are optional. There are a few attributes that are used by Home Assistant for representing the entity in a specific way. Each component will also have it's own attributes to represent extra state data about the entity. For example, the light component has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state.
When using templates, attributes will be available by their name. For example `state.attributes.assumed_state`.
Attribute | Description
--------- | -----------
`friendly_name` | Name of the entity. Example: `Kitchen Ceiling`.
`icon` | Icon to use for the entity in the frontend. Example: `mdi:home`.
`hidden` | Boolean if the entity should not be shown in the frontend. Example: `true`.
`entity_picture` | Url to a picture that should be used instead of showing the domain icon. Example: `http://example.com/picture.jpg`.
`assumed_state` | Boolean if the current state is an assumption. [More info](https://home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) Example: `True`.
`unit_of_measurement` | The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: `°C`.
When an attribute contains spaces, you can retrieve it like this: `states.sensor.livingroom.attributes["Battery numeric"]`.

214
source/_docs/configuration/templating.markdown Normal file
View file

@ -0,0 +1,214 @@
---
layout: page
title: "Templating"
description: "Instructions how to use the templating feature of Home Assistant."
date: 2015-12-12 12:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /topics/templating/
---
This is an advanced feature of Home Assistant. You'll need a basic understanding of the following things:
- [Home Assistant architecture], especially states.
- [State object]
[Home Assistant architecture]: /developers/architecture/
[State object]: /topics/state_object/
Templating is a powerful feature in Home Assistant that allows the user control over information that is going into and out of the system. It is used for:
- Formatting outgoing messages in, for example, the [notify] and [alexa] components.
- Process incoming data from sources that provide raw data, like [MQTT], [REST sensor], or the [command line sensor].
- [Advanced Automation templating]auto-template]
[notify]: /components/notify/
[alexa]: /components/alexa/
[MQTT]: /components/mqtt/
[REST sensor]: /components/sensor.rest/
[command line sensor]: /components/sensor.command_line/
[auto-template]: /getting-started/automation-templating/
## {% linkable_title Building templates %}
Templating in Home Assistant is powered by the [Jinja2](http://jinja.pocoo.org/) templating engine. This means that we are using their syntax and make some custom Home Assistant variables available to templates during rendering. We will not go over the basics of the syntax, as Jinja2 does a lot better job at this in their [Jinja2 documentation](http://jinja.pocoo.org/docs/dev/templates/).
<p class='note'>
The frontend has a template editor developer tool to help develop and debug templates.
</p>
Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates:
```yaml
script:
msg_who_is_home:
sequence:
- service: notify.notify
message: >
{% raw %}{% if is_state('device_tracker.paulus', 'home') %}
Ha, Paulus is home!
{% else %}
Paulus is at {{ states('device_tracker.paulus') }}.
{% endif %}{% endraw %}
```
[Jinja2](http://jinja.pocoo.org/) supports a width variety of operations:
- [Mathematical operation](http://jinja.pocoo.org/docs/dev/templates/#math)
- [Comparisons](http://jinja.pocoo.org/docs/dev/templates/#comparisons)
- [Logic](http://jinja.pocoo.org/docs/dev/templates/#logic)
## {% linkable_title Home Assistant template extensions %}
Home Assistant adds extensions to allow templates to access all of the current states:
- Iterating `states` will yield each state sorted alphabetically by entity ID.
- Iterating `states.domain` will yield each state of that domain sorted alphabetically by entity ID.
- `states.sensor.temperature` returns the state object for `sensor.temperature`.
- `states('device_tracker.paulus')` will return the state string (not the object) of the given entity or `unknown` if it doesn't exist.
- `is_state('device_tracker.paulus', 'home')` will test if the given entity is specified state.
- `is_state_attr('device_tracker.paulus', 'battery', 40)` will test if the given entity is specified state.
- `now()` will be rendered as current time in your time zone.
- `utcnow()` will be rendered as UTC time.
- `as_timestamp` will convert datetime object or string to UNIX timestamp
- `distance()` will measure the distance in meters between home, entity, coordinates.
- `closest()` will find the closest entity.
- `relative_time(timestamp)` will format the date time as relative time vs now (ie 7 seconds)
- `float` will format the output as float.
- `strptime(string, format)` will parse a string to a datetime based on a [format][strp-format].
- Filter `round(x)` will convert the input to a number and round it to `x` decimals.
- Filter `timestamp_local` will convert an UNIX timestamp to local time/data.
- Filter `timestamp_utc` will convert an UNIX timestamp to UTC time/data.
- Filter `timestamp_custom(format_string, local_boolean)` will convert an UNIX timestamp to a custom format, the use of a local timestamp is default, supporting [Python format options](https://docs.python.org/3/library/time.html#time.strftime).
- Filter `max` will obtain the larget item in a sequence.
- Filter `min` will obtain the smallest item in a sequence.
[strp-format]: https://docs.python.org/3.4/library/datetime.html#strftime-and-strptime-behavior
## {% linkable_title Examples %}
### {% linkable_title States %}
The next two statements result in same value if state exists. The second one will result in an error if state does not exist.
```text
{% raw %}{{ states('device_tracker.paulus') }}
{{ states.device_tracker.paulus.state }}{% endraw %}
```
### {% linkable_title Attributes %}
Print an attribute if state is defined
```text
{% raw %}{% if states.device_tracker.paulus %}
{{ states.device_tracker.paulus.attributes.battery }}
{% else %}
??
{% endif %}{% endraw %}
```
### {% linkable_title Sensor states %}
Print out a list of all the sensor states.
```text
{% raw %}{% for state in states.sensor %}
{{ state.entity_id }}={{ state.state }},
{% endfor %}
{% if is_state('device_tracker.paulus', 'home') %}
Ha, Paulus is home!
{% else %}
Paulus is at {{ states('device_tracker.paulus') }}.
{% endif %}
{{ states.sensor.temperature | float + 1 }}
{{ (states.sensor.temperature | float * 10) | round(2) }}
{% if states('sensor.temperature') | float > 20 %}
It is warm!
{%endif %}
{{ as_timestamp(states.binary_sensor.garage_door.last_changed) }}
{{ as_timestamp(now()) - as_timestamp(states.binary_sensor.garage_door.last_changed) }}{% endraw %}
```
### {% linkable_title Distance examples %}
If only 1 location is passed in, Home Assistant will measure the distance from home.
```text
{% raw %}Using Lat Lng coordinates: {{ distance(123.45, 123.45) }}
Using State: {{ distance(states.device_tracker.paulus) }}
These can also be combined in any combination:
{{ distance(123.45, 123.45, 'device_tracker.paulus') }}
{{ distance('device_tracker.anne_therese', 'device_tracker.paulus') }}{% endraw %}
```
### {% linkable_title Closest examples %}
Find entities closest to the Home Assistant location:
```text
{% raw %}Query all entities: {{ closest(states) }}
Query all entities of a specific domain: {{ closest('states.device_tracker') }}
Query all entities in group.children: {{ closest('group.children') }}
Query all entities in group.children: {{ closest(states.group.children) }}{% endraw %}
```
Find entities closest to a coordinate or another entity. All previous arguments still apply for 2nd argument.
```text
{% raw %}Closest to a coordinate: {{ closest(23.456, 23.456, 'group.children') }}
Closest to an entity: {{ closest('zone.school', 'group.children') }}
Closest to an entity: {{ closest(states.zone.school, 'group.children') }}{% endraw %}
```
### {% linkable_title Combined %}
Since closest returns a state, we can combine it with distance too.
```text
{% raw %}{{ closest(states).name }} is {{ distance(closest(states)) }} meters away.{% endraw %}
```
## {% linkable_title Processing incoming data %}
The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data you care about. This will work only for platforms and components that mentioned support for this in their documentation.
It depends per component or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:
| Variable | Description |
| ------------ | -------------------------------------- |
| `value` | The incoming value. |
| `value_json` | The incoming value parsed as JSON. |
```text
# Incoming value:
{"primes": [2, 3, 5, 7, 11, 13]}
# Extract third prime number
{% raw %}{{ value_json.primes[2] }}{% endraw %}
# Format output
{% raw %}{{ "%+.1f" | value_json }}{% endraw %}
# Math
{% raw %}{{ value_json | float * 1024 }}{% endraw %}
{% raw %}{{ float(value_json) * (2**10) }}{% endraw %}
# Timestamps
{% raw %}{{ value_json.tst | timestamp_local }}{% endraw %}
{% raw %}{{ value_json.tst | timestamp_utc }}{% endraw %}
{% raw %}{{ value_json.tst | timestamp_custom('%Y' True) }}{% endraw %}
# Square bracket notation
{% raw %}{{ value_json["001"] }}{% endraw %}
```

89
source/_docs/configuration/troubleshooting.markdown Normal file
View file

@ -0,0 +1,89 @@
---
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
redirect_from: /getting-started/troubleshooting-configuration/
---
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>

63
source/_docs/configuration/yaml.markdown Normal file
View file

@ -0,0 +1,63 @@
---
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
redirect_from: /getting-started/yaml/
---
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
```

14
source/_docs/ecosystem.markdowm Normal file
View file

@ -0,0 +1,14 @@
---
layout: page
title: "Ecosystem"
description: "External tools for Home Assistant"
date: 2016-10-26 00:46
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/
---
Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems.

13
source/_docs/ecosystem/appdaemon.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "AppDaemon"
description: "AppDaemon is a loosely coupled, multithreaded, sandboxed Python execution environment for writing automation apps for Home Assistant"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/
---
AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant.

2108
source/_docs/ecosystem/appdaemon/api.markdown Executable file
View file

File diff suppressed because it is too large Load diff

79
source/_docs/ecosystem/appdaemon/configuration.markdown Normal file
View file

@ -0,0 +1,79 @@
---
layout: page
title: "Configuration"
description: "AppDaemon Configuration"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/configuration/
---
When you have appdaemon installed by either method, copy the `conf/appdaemon.cfg.example` file to `conf/appdaemon.cfg`, then edit the `[AppDaemon]` section to reflect your environment:
```
[AppDaemon]
ha_url = <some_url>
ha_key = <some key>
logfile = STDOUT
errorfile = STDERR
app_dir = <Path to appdaemon dir>/conf/apps
threads = 10
latitude = <latitude>
longitude = <longitude>
elevation = <elevation
timezone = <timezone>
cert_path = <path/to/root/CA/cert>
# Apps
[hello_world]
module = hello
class = HelloWorld
```
- `ha_url` is a reference to your home assistant installation and must include the correct port number and scheme (`http://` or `https://` as appropriate)
- `ha_key` should be set to your key if you have one, otherwise it can be removed.
- `logfile` (optional) is the path to where you want `AppDaemon` to keep its main log. When run from the command line this is not used - log messages come out on the terminal. When running as a daemon this is where the log information will go. In the example above I created a directory specifically for AppDaemon to run from, although there is no reason you can't keep it in the `appdaemon` directory of the cloned repository. If `logfile = STDOUT`, output will be sent to stdout instead of stderr when running in the foreground, if not specified, output will be sent to STDOUT.
- `errorfile` (optional) is the name of the logfile for errors - this will usually be errors during compilation and execution of the apps. If `errorfile = STDERR` errors will be sent to stderr instead of a file, if not specified, output will be sent to STDERR.
- `app_dir` (optional) is the directory the apps are placed in. If not specified, AppDaemon will look first in `~/.homeassistant` then `/etc/appdaemon` for a subdirectory named `apps`
- `threads` - the number of dedicated worker threads to create for running the apps. Note, this will bear no resembelance to the number of apps you have, the threads are re-used and only active for as long as required to tun a particular callback or initialization, leave this set to 10 unless you experience thread starvation
- `latitude`, `longitude`, `elevation`, `timezone` - should all be copied from your home assistant configuration file
- `cert_path` (optional) - path to root CA cert directory - use only if you are using self signed certs.
The `#Apps` section is the configuration for the Hello World program and should be left in place for initial testing but can be removed later if desired, as other Apps are added, App configuration is described in the [API doc](API.md).
## {% linkable_title Docker %}
For Docker Configuration you need to take a couple of extra things into consideration.
Our Docker image is designed to load your configuration and apps from a volume at `/conf` so that you can manage them in your own git repository, or place them anywhere else on the system and map them using the Docker command line.
For example, if you have a local repository in `/Users/foo/ha-config` containing the following files:
```bash
$ git ls-files
configuration.yaml
customize.yaml
known_devices.yaml
appdaemon.cfg
apps
apps/magic.py
```
You will need to modify the `appdaemon.cfg` file to point to these apps in `/conf/apps`:
```
[AppDaemon]
ha_url = <some_url>
ha_key = <some key>
logfile = STDOUT
errorfile = STDERR
app_dir = /conf/apps
threads = 10
latitude = <latitude>
longitude = <longitude>
elevation = <elevation
timezone = <timezone>
```
You can run Docker and point the conf volume to that directory.

13
source/_docs/ecosystem/appdaemon/example_apps.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Example Apps"
description: "AppDaemon Example Apps"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/example_apps/
---
There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them.

45
source/_docs/ecosystem/appdaemon/installation.markdown Normal file
View file

@ -0,0 +1,45 @@
---
layout: page
title: "Installation"
description: "AppDaemon Installation"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/installation/
---
Installation is either by `pip3` or Docker.
## {% linkable_title Clone the Repository %}
For either method you will need to clone the **AppDaemon** repository to the current local directory on your machine.
``` bash
$ git clone https://github.com/acockburn/appdaemon.git
```
Change your working directory to the repository root. Moving forward, we will be working from this directory.
``` bash
$ cd appdaemon
```
## {% linkable_title Install using Docker %}
To build the Docker image run the following:
``` bash
$ docker build -t appdaemon .
```
(Note the period at the end of the above command)
## {% linkable_title Install using `pip3` %}
Before running `AppDaemon` you will need to install the package:
```bash
$ sudo pip3 install .
```

13
source/_docs/ecosystem/appdaemon/operation.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Operation"
description: "Operation"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/tutorial/
---
Since `AppDaemon` under the covers uses the exact same APIs as the frontend UI, you typically see it react at about the same time to a given event. Calling back to Home Assistant is also pretty fast especially if they are running on the same machine. In action, observed latency above the built in automation component is usually sub-second.

13
source/_docs/ecosystem/appdaemon/reboot.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Starting at Reboot"
description: "Starting at Reboot"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/reboot/
---
To run `AppDaemon` at reboot, I have provided a sample init script in the `./scripts` directory. These have been tested on a Raspberry PI - your mileage may vary on other systems. There is also a sample Systemd script.

95
source/_docs/ecosystem/appdaemon/running.markdown Executable file
View file

@ -0,0 +1,95 @@
---
layout: page
title: "Running AppDaemon"
description: "Running AppDaemon"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/running/
---
As configured, `AppDaemon` comes with a single HelloWorld App that will send a greeting to the logfile to show that everything is working correctly.
## {% linkable_title Docker %}
Assuming you have set the config up as described above for Docker, you can run it with the command:
```bash
$ docker run -d -v <Path to Config>/conf:/conf --name appdaemon appdaemon:latest
```
In the example above you would use:
```bash
$ docker run -d -v /Users/foo/ha-config:/conf --name appdaemon appdaemon:latest
```
Where you place the `conf` and `conf/apps` directory is up to you - it can be in downloaded repostory, or anywhere else on the host, as long as you use the correct mapping in the `docker run` command.
You can inspect the logs as follows:
```bash
$ docker logs appdaemon
2016-08-22 10:08:16,575 INFO Got initial state
2016-08-22 10:08:16,576 INFO Loading Module: /export/hass/appdaemon_test/conf/apps/hello.py
2016-08-22 10:08:16,578 INFO Loading Object hello_world using class HelloWorld from module hello
2016-08-22 10:08:16,580 INFO Hello from AppDaemon
2016-08-22 10:08:16,584 INFO You are now ready to run Apps!
```
Note that for Docker, the error and regular logs are combined.
## {% linkable_title `pip3` %}
You can then run AppDaemon from the command line as follows:
```bash
$ appdaemon -c conf/appdaemon.cfg
```
If all is well, you should see something like the following:
```
$ appdaemon -c conf/appdaemon.cfg
2016-08-22 10:08:16,575 INFO Got initial state
2016-08-22 10:08:16,576 INFO Loading Module: /export/hass/appdaemon_test/conf/apps/hello.py
2016-08-22 10:08:16,578 INFO Loading Object hello_world using class HelloWorld from module hello
2016-08-22 10:08:16,580 INFO Hello from AppDaemon
2016-08-22 10:08:16,584 INFO You are now ready to run Apps!
```
## {% linkable_title AppDaemon arguments %}
```
usage: appdaemon [-h] [-c CONFIG] [-p PIDFILE] [-t TICK] [-s STARTTIME]
[-e ENDTIME] [-i INTERVAL]
[-D {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-v] [-d]
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
full path to config file
-p PIDFILE, --pidfile PIDFILE
full path to PID File
-t TICK, --tick TICK time in seconds that a tick in the schedular lasts
-s STARTTIME, --starttime STARTTIME
start time for scheduler <YYYY-MM-DD HH:MM:SS>
-e ENDTIME, --endtime ENDTIME
end time for scheduler <YYYY-MM-DD HH:MM:SS>
-i INTERVAL, --interval INTERVAL
multiplier for scheduler tick
-D {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --debug {DEBUG,INFO,WARNING,ERROR,CRITICAL}
debug level
-v, --version show program's version number and exit
-d, --daemon run as a background process
```
-c is the path to the configuration file. If not specified, AppDaemon will look for a file named `appdaemon.cfg` first in `~/.homeassistant` then in `/etc/appdaemon`. If the file is not specified and it is not found in either location, AppDaemon will raise an exception.
-d and -p are used by the init file to start the process as a daemon and are not required if running from the command line.
-D can be used to increase the debug level for internal AppDaemon operations as well as apps using the logging function.
The -s, -i, -t and -s options are for the Time Travel feature and should only be used for testing. They are described in more detail in the API documentation.

128
source/_docs/ecosystem/appdaemon/tutorial.markdown Executable file
View file

@ -0,0 +1,128 @@
---
layout: page
title: "AppDaemon Tutorial"
description: "AppDaemon Tutorial"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/tutorial/
---
## {% linkable_title Another Take on Automation %}
If you haven't yet read Paulus' excellent Blog entry on [Perfect Home Automation](https://home-assistant.io/blog/2016/01/19/perfect-home-automation/) I would encourage you to take a look. As a veteran of several Home Automation systems with varying degrees success, it was this article more than anything else that convinced me that Home Assistant had the right philosophy behind it and was on the right track. One of the most important points made is that being able to control your lights from your phone, 9 times out of 10 is harder than using a lightswitch - where Home Automation really comes into its own is when you start removing the need to use a phone or the switch - the "Automation" in Home Automation. A surprisingly large number of systems out there miss this essential point and have limited abilities to automate anything which is why a robust and open system such as Home Assistant is such an important part of the equation in bring this all together in the vast and chaotic ecosystem that is the "Internet of Things".
So given the importance of Automation, what should Automation allow us to do? I am a pragmatist at heart so I judge individual systems by the ease of accomplishing a few basic but representative tasks:
- Can the system respond to presence or absence of people?
- Can I turn a light on at Sunset +/- a certain amount of time?
- Can I arrive home in light or dark and have the lights figure out if they should be on or off?
- As I build my system out, can I get the individual pieces to co-operate and use and re-use (potentially complex) logic to make sure everything works smoothly?
- Is it open and expandable?
- Does it run locally without any reliance on the cloud?
In my opinion, Home Assistant accomplishes the majority of these very well with a combination of Automations, Scripts and Templates, and it's Restful API.
So why `AppDaemon`? AppDaemon is not meant to replace Home Assistant Automations and Scripts, rather complement them. For a lot of things, automations work well and can be very succinct. However, there is a class of more complex automations for which they become harder to use, and appdeamon then comes into its own. It brings quite a few things to the table:
- New paradigm - some problems require a procedural and/or iterative approach, and `AppDaemon` Apps are a much more natural fit for this. Recent enhancements to Home Assistant scripts and templates have made huge strides, but for the most complex scenarios, Apps can do things that Automations can't
- Ease of use - AppDaemon's API is full of helper functions that make programming as easy and natural as possible. The functions and their operation are as "Pythonic" as possible, experienced Python programmers should feel right at home.
- Reuse - write a piece of code once and instantiate it as an app as many times as you need with different parameters e.g. a motion light program that you can use in 5 different places around your home. The code stays the same, you just dynamically add new instances of it in the config file
- Dynamic - AppDaemon has been designed from the start to enable the user to make changes without requiring a restart of Home Assistant, thanks to it's loose coupling. However, it is better than that - the user can make changes to code and AppDaemon will automatically reload the code, figure out which Apps were using it and restart them to use the new code with out the need to restart `AppDaemon` itself. It is also possible to change parameters for an individual or multiple apps and have them picked up dynamically, and for a final trick, removing or adding apps is also picked up dynamically. Testing cycles become a lot more efficient as a result.
- Complex logic - Python's If/Else constructs are clearer and easier to code for arbitrarily complex nested logic
- Durable variables and state - variables can be kept between events to keep track of things like the number of times a motion sensor has been activated, or how long it has been since a door opened
- All the power of Python - use any of Python's libraries, create your own modules, share variables, refactor and re-use code, create a single app to do everything, or multiple apps for individual tasks - nothing is off limits!
It is in fact a testament to Home Assistant's open nature that a component like `AppDaemon` can be integrated so neatly and closely that it acts in all ways like an extension of the system, not a second class citizen. Part of the strength of Home Assistant's underlying design is that it makes no assumptions whatever about what it is controlling or reacting to, or reporting state on. This is made achievable in part by the great flexibility of Python as a programming environment for Home Assistant, and carrying that forward has enabled me to use the same philosophy for `AppDaemon` - it took surprisingly little code to be able to respond to basic events and call services in a completely open ended manner - the bulk of the work after that was adding additonal functions to make things that were already possible easier.
## {% linkable_title How it Works %}
The best way to show what AppDaemon does is through a few simple examples.
### {% linkable_title Sunrise/Sunset Lighting %}
Lets start with a simple App to turn a light on every night at sunset and off every morning at sunrise. Every App when first started will have its `initialize()` function called which gives it a chance to register a callback for AppDaemons's scheduler for a specific time. In this case we are using `run_at_sunrise()` and `run_at_sunset()` to register 2 separate callbacks. The argument `0` is the number of seconds offset from sunrise or sunset and can be negative or positive. For complex intervals it can be convenient to use Python's `datetime.timedelta` class for calculations. When sunrise or sunset occurs, the appropriate callback function, `sunrise_cb()` or `sunset_cb()` is called which then makes a call to Home Assistant to turn the porch light on or off by activating a scene. The variables `args["on_scene"]` and `args["off_scene"]` are passed through from the configuration of this particular App, and the same code could be reused to activate completely different scenes in a different version of the App.
```python
import homeassistant.appapi as appapi
class OutsideLights(appapi.AppDaemon):
def initialize(self):
self.run_at_sunrise(self.sunrise_cb, 0)
self.run_at_sunset(self.sunset_cb, 0)
def sunrise_cb(self, kwargs):
self.turn_on(self.args["off_scene"])
def sunset_cb(self, kwargs):
self.turn_on(self.args["on_scene"])
```
This is also fairly easy to achieve with Home Assistant automations, but we are just getting started.
### Motion Light
Our next example is to turn on a light when motion is detected and it is dark, and turn it off after a period of time. This time, the `initialize()` function registers a callback on a state change (of the motion sensor) rather than a specific time. We tell AppDaemon that we are only interested in state changesd where the motion detector comes on by adding an additional parameter to the callback registration - `new = "on"`. When the motion is detected, the callack function `motion()` is called, and we check whether or not the sun has set using a built-in convenience function: `sun_down()`. Next, we turn the light on with `turn_on()`, then set a timer using `run_in()` to turn the light off after 60 seconds, which is another call to the scheduler to execute in a set time from now, which results in `AppDaemon` calling `light_off()` 60 seconds later using the `turn_off()` call to actually turn the light off. This is still pretty simple in code terms:
```python
import homeassistant.appapi as appapi
class FlashyMotionLights(appapi.AppDaemon):
def initialize(self):
self.listen_state(self.motion, "binary_sensor.drive", new = "on")
def motion(self, entity, attribute, old, new, kwargs):
if self.sun_down():
self.turn_on("light.drive")
self.run_in(self.light_off, 60)
def light_off(self, kwargs):
self.turn_off("light.drive")
```
This is starting to get a little more complex in Home Assistant automations requiring an Automation rule and two separate scripts.
Now lets extend this with a somewhat artificial example to show something that is simple in AppDaemon but very difficult if not impossible using automations. Lets warn someone inside the house that there has been motion outside by flashing a lamp on and off 10 times. We are reacting to the motion as before by turning on the light and setting a timer to turn it off again, but in addition, we set a 1 second timer to run `flash_warning()` which when called, toggles the inside light and sets another timer to call itself a second later. To avoid re-triggering forever, it keeps a count of how many times it has been activated and bales out after 10 iterations.
```python
import homeassistant.appapi as appapi
class MotionLights(appapi.AppDaemon):
def initialize(self):
self.listen_state(self.motion, "binary_sensor.drive", new = "on")
def motion(self, entity, attribute, old, new, kwargs):
if self.self.sun_down():
self.turn_on("light.drive")
self.run_in(self.light_off, 60)
self.flashcount = 0
self.run_in(self.flash_warning, 1)
def light_off(self, kwargs):
self.turn_off("light.drive")
def flash_warning(self, kwargs):
self.toggle("light.living_room")
self.flashcount += 1
if self.flashcount < 10:
self.run_in(self.flash_warning, 1)
```
Of course if I wanted to make this App or its predecessor reusable I would have provide parameters for the sensor, the light to activate on motion, the warning light and even the number of flashes and delay between flashes.
In addition, Apps can write to `AppDaemon`'s logfiles, and there is a system of constraints that allows yout to control when and under what circumstances Apps and callbacks are active to keep the logic clean and simple.
I have spent the last few weeks moving all of my (fairly complex) automations over to `APPDaemon` and so far it is working very reliably.
Some people will maybe look at all of this and say "what use is this, I can already do all of this", and that is fine, as I said this is an alternative not a replacement, but I am hopeful that for some users this will seem a more natural, powerful and nimble way of building potentially very complex automations.
If this has whet your appetite, feel free to give it a try.
Happy Automating!

26
source/_docs/ecosystem/appdaemon/updating.markdown Normal file
View file

@ -0,0 +1,26 @@
---
layout: page
title: "Updating AppDaemon"
description: "Updating AppDaemon"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/updating/
---
To update AppDaemon after I have released new code, just run the following command to update your copy:
```bash
$ git pull origin
```
If you are using pip3 for the install do this:
```bash
$ sudo pip3 uninstall appdaemon
$ sudo pip3 install .
```
If you are using docker, rerun the steps to create a new docker image.

22
source/_docs/ecosystem/appdaemon/windows.markdown Executable file
View file

@ -0,0 +1,22 @@
---
layout: page
title: "Windows Support"
description: "Windows Support"
release_date: 2016-11-27 08:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/appdaemon/windows/
---
AppDaemon runs under windows and has been tested with the official 3.5.2 release of Python. There are a couple of caveats however:
- The `-d` or `--daemonize` option is not supported owing to limitations in the Windows implementation of Python.
- Some internal diagnostics are disabled. This is not user visible but may hamper troubleshooting of internal issues if any crop up
AppDaemon can be installed exactly as per the instructions for every other version using pip3.
## {% linkable_title Windows Under the Linux Subsystem %}
Windows 10 now supports a full Linux bash environment that is capable of running Python. This is essentially an Ubuntu distribution and works extremely well. It is possible to run AppDaemon in exactly the same way as for Linux distributions, and none of the above Windows Caveats apply to this version. This is the reccomended way to run AppDaemon in a Windows 10 and later environment.

21
source/_docs/ecosystem/hadashboard.markdown Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
title: "HADashboard"
description: "HADashboard is a dashboard for Home Assistant that is intended to be wall mounted, and is optimized for distance viewing."
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/
---
HADashboard is a dashboard for [Home Assistant](https://home-assistant.io/) that is intended to be wall mounted, and is optimized for distance viewing.
<p class='img'>
<img src='/images/hadashboard/dash.png' />
Sample Dashboard
</p>
HADashboard was originally created by the excellent work of [FlorianZ](https://github.com/FlorianZ/hadashboard) for use with the SmartThings Home Automation system, with notable contributions from the [SmartThings Community](https://community.smartthings.com/t/home-automation-dashboard/4926). I would also like to acknowledge contributions made by [zipriddy](https://github.com/zpriddy/SmartThings_PyDash). This is my port of hadashboard to Home Assistant.

275
source/_docs/ecosystem/hadashboard/dash_config.markdown Executable file
View file

@ -0,0 +1,275 @@
---
layout: page
title: "Dashboard Configuration"
description: "Dashboard Configuration"
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/dash_config/
---
(All installations)
Hadashboard is a Dashing application, so make sure to read all the instructions on http://dashing.io to learn how to add widgets to your dashboard, as well as how to create new widgets.
Make a copy of `dashboards/example.erb` and call it `main.erb`, then edit this file to reference the items you want to display and control and to get the layout that you want. Leave the original `example.erb` intact and unchanged so that you don't run into problems when trying to update using the git commands mentioned later in "Updating the Dashboard".
The basic anatomy of a widget is this:
``` html
<li data-row="" data-col="1" data-sizex="1" data-sizey="1">
<div data-id="office" data-view="Hadimmer" data-title="Office Lamp"></div>
</li>
```
- **data-row**, **data-col**: The position of the widget in the grid.
- **data-sizex**, **data-sizey**: The size of the widget in terms of grid tile.
- **data-id**: The homeassitant entity id without the entity type (e.g. `light.office` becomes `office`).
- **data-view**: The type of widget to be used (Haswitch, Hadimmer, Hatemp etc.)
- **data-icon**: The icon displayed on the tile. See http://fontawesome.io for an icon cheatsheet.
- **data-title**: The title to be displayed on the tile.
- ***data-bgcolor*** (optional) - the background color of the widget.
Note that although it is legal in XML terms to split the inner `<div>` like this:
``` html
<li data-row="" data-col="1" data-sizex="1" data-sizey="1">
<div data-id="office"
data-view="Hadimmer"
data-title="Office Lamp">
</div>
</li>
```
This may break `hapush`'s parsing of the file, so keep to the line format first presented.
Please, refer to the Dashing website for instructions on how to change the grid and tile size, as well as more general instructions about widgets, their properties, and how to create new widgets.
## {% linkable_title Supported Widgets %}
At this time I have provided support for the following Home Assistant entity types.
- switch: Widget type **Haswitch**
- lock: Widget type **Halock**
- devicetracker: Widget type **Hadevicetracker**
- light: Widget type **Hadimmer**
- cover: Widget type **Hacover**
- input_boolean: Widget type **Hainputboolean**
- scene: Widget type **Hascene**
- **data-ontime** (optional): The amount of time the scene icon lights up when pressed, in milliseconds, default 1000.
### {% linkable_title script %}
Widget type ***Hascript***
**data-ontime** (optional): The amount of time the scene icon lights up when pressed, in milliseconds, default 1000.
### {% linkable_title mode %}
The `Hamode` widget alows you to run a script on activation and to link it with a specified `input_select` so the button will be highlighted for certain values of that input select. The usecase for this is that I maintain an `input_select` as a flag for the state of the house to simplify other automations. I use scripts to switch between the states, and this feature provides feedback as to the current state by lighting up the appropriate mode button.
A `Hamode` widget using this feature will look like this:
```html
<li data-row="5" data-col="3" data-sizex="2" data-sizey="1">
<div data-id="day" data-view="Hamode" data-title="Good Day" data-icon="sun-o" data-changemode="Day" data-input="house_mode"></div>
</li>
```
- **data-changemode**: The value of the `input_select` for which this script button will light up
- **data-input**: The `input_select` entity to use (minus the leading entity type)
### {% linkable_title input_select (read only) %}
Widget type **Hainputselect**
### {% linkable_title sensor %}
Widget type **Hasensor**
Text based output of the value of a particular sensor.
The Hasensor widget supports an additional paramater `data-unit`. This allows you to set the unit to whatever you want: Centigrade, %, lux or whatever you need for the sensor in question. For a temperature sensor you will need to explicitly include the degree symbol like this:
```html
data-unit="&deg;F"
```
If omitted, no units will be shown.
### {% linkable_title sensor %}
Widget type **Hameter**
An alternative to the text based `Hasensor` that works for numeric values only.
The Hameter widget supports an additional paramater `data-unit`. This allows you to set the unit to whatever you want: Centigrade, %, lux or whatever you need for the sensor in question. For a temperature sensor you will need to explicitly include the degree symbol like this:
```html
data-unit="&deg;F"
```
If omitted, no units will be shown.
### {% linkable_title binary_sensor %}
Widget type **Habinary**
An icon-based option for generic binary sensors. Useful for things like door contact sensors. In addition to the standard widget parameters, Habinary supports two additional parameters:
- **data-iconon**: the icon to display when the sensor state is "on"
- **data-iconoff**: the icon to display when the sensor state if "off"
If no icons are specified, the widget defaults to a flat gray line for "off" and a green bullseye for "on".
### {% linkable_title group %}
Widget type **Hagroup**.
The Hagroup widget uses the homeassistant/turn_on and homeassistant/turn_off API call, so certain functionality will be lost. For example, you will not be able to use control groups of locks or dim lights.
## {% linkable_title Alarm Control Panel %}
These widgets allow the user to create a working control panel that can be used to control the Manual Alarm Control Panel component (https://home-assistant.io/components/alarm_control_panel.manual). The example dashboard contains an arrangement similar to this:
<p class='img'>
<img src='/images/hadashboard/alarm_panel.png' />
The Alarm Panel
</p>
Widget type **Haalarmstatus**
The Haalarmstatus widget displays the current status of the alarm_control_panel entity. It will also display the code as it is being entered by the user.
The data-id must be the same as the alarm_control_panel entity_id in Home Assistant.
Widget type **Haalarmdigit**
The Haalarmdigit widget is used to create the numeric keypad for entering alarm codes.
`data-digit` holds the numeric value you wish to enter. The special value of "-" creates a 'clear' button which will wipe the code and return the Haalarmstatus widget display back to the current alarm state.
`data-alarmentity` holds the data-id of the Haalarmstatus widget, so that the status widget can be correctly updated. It is mandatory for a 'clear' type digit and optional for normal numeric buttons.
Widget type **Haalarmaction**
The Haalarmaction widget creates the arm/disarm/trigger buttons. Bear in mind that alarm triggering does not require a code, so you may not want to put this button near the other buttons in case it is pressed accidentally.
data-action must contain one of the following: arm_home/arm_away/trigger/disarm.
### {% linkable_title weather (requires DarkSky) %}
Widget type **Haweather**.
In order to use the weather widget you must configure the [DarkSky component](/components/sensor.darksky/), and ensure that you configure at least the following monitored conditions in your Home Assistant sensor configuration:
- temperature
- humidity
- precip_probability
- precip_intensity
- wind_speed
- pressure
- wind_bearing
- apparent_temperature
- icon
The `data-id` of the Haweather widget must be set to `weather` or the widget will not work.
The Hatemp widget supports an additional paramater `data-unit`. This allows you to set the unit to whatever you want: Centigrade, Fahrenheit or even Kelvin if you prefer. You will need to explicitly include the degree symbol like this:
```html
data-unit="&deg;F"
```
If omitted, no units will be shown.
### {% linkable_title News %}
Widget type ***News*** (contributed by [KRiS](https://community.home-assistant.io/users/kris/activity))
This is an RSS widget that can be used for displaying travel information, news etc. on the dashboard. The RSS feed will update every 60 minutes. To configure this, first it is necessary to add your desired feeds in `homeassistant/lib/ha_conf.rb` in the `$news_feeds` section. By default it comes with 2 sample feeds:
```ruby
$news_feeds = {
"Traffic" => "http://api.sr.se/api/rss/traffic/2863",
"News" => "http://feeds.bbci.co.uk/news/rss.xml",
}
```
You can add as many as you want. The important point is that the key value (e.g. "Traffic" or "News" in the example above is used to tie the feed to your widget in the dashboard file. Here is an example of the Traffic widget that displays the first feed in the list:
```html
<li data-row="3" data-col="2" data-sizex="2" data-sizey="2">
<div data-id="Traffic" data-view="News" data-title="Traffic" data-interval="30" data-bgcolor="#643EBF">
</li>
```
The value of thee `data-id` tag must match the key value in the `$news_feeds` configuration.
- **data-interval** (optional): The time in seconds that each entry in the RSS feed is displayed before the next one is shown, default is 30 seconds.
**The follwing widget types have been deprecated in favor of the more flexible `Hasensor` and `Hameter` widgets. They will be removed in a future release.**
### {% linkable_title sensor (humidity) %}
Widget type **Hahumidity**.
### {% linkable_title sensor (humidity) %}
Widget type **Hahumiditymeter** (contributed by [Shiv Chanders](https://community.home-assistant.io/users/chanders/activity))
This is an alternative to the the text based humidity widget above, it display the humidity as an animated meter from 0 to 100%.
### {% linkable_title sensor (luminance) %}
Widget type **Halux**.
### {% linkable_title sensor (temperature) %}
Widget type **Hatemp**.
The Hatemp widget supports an additional paramater `data-unit`. This allows you to set the unit to whatever you want: Centigrade, Fahrenheit or even Kelvin if you prefer. You will need to explicitly include the degree symbol like this:
```html
data-unit="&deg;F"
```
If omitted, no units will be shown.
## {% linkable_title Customizing CSS styles %}
If you want to customize the styles of your dashboard and widgets, there are two options:
1. You can edit the application.scss file (and the individual widget .scss files) directly (not recommended; if you pull down updates from the master repository, your changes might conflict/be overwritten)
1. __Create override files (recommended)__
1. Create a couple of additional files in the _assets/stylesheets_ directory: `_application_custom.scss` and `_variables_custom.scss`.
1. Open `application.scss` and go to the bottom of the file. Uncomment the @import line.
1. Open `_variables.scss` and go to the bottom of the file. Uncomment the @import line.
1. Write your own SASS styles in `_application_custom.scss` (for general style customization) and `_variables_custom.scss` (for colors). You can customize those files without worrying about your changes getting overwritten if you pull down an update. The most you may have to do, if you update, will be to uncomment the @import lines again from steps 2 and 3.
__Note: The `_variables.scss` file (and your customizations from `_variables_custom.scss`) get imported into nearly every widget's SCSS file, so it is a best practice to define varaibles for colors in `_variables.scss` or `_variables_custom.scss` and reference those variables in the widget SCSS.__
## {% linkable_title Changes and Restarting %}
When you make changes to a dashboard, Dashing and `hapush` will both automatically reload and apply the changes without a need to restart.
Note: The first time you start Dashing, it can take up to a minute for the initial compilation of the pages to occur. You might get a timeout from your browser. If this occurs, be patient and reload. Subsequent reloads will be a lot quicker.
## {% linkable_title Multiple Pages %}
It is possible to have multiple pages within a dashboard. To do this, you can add an arbitary number of gridster divisions (you need at least one).
```html
<div class="gridster"> <!-- Main Panel - PAGE 1 -->
<some widgets>
</div
<div class="gridster"> <!-- More Stuff - PAGE 2 -->
<more widgets>
</div
```
The divisions are implicitly numbered from 1 so it is a good idea to comment them. You can then add a widget to switch between pages like so:
```html
<li data-row="1" data-col="1" data-sizex="1" data-sizey="1">
<div data-id="cpage1" data-view="ChangePage" data-icon="cogs" data-title="Upstairs" data-page="3" data-stagger="false" data-fasttransition="true" data-event-click="onClick"></div>
</li>
```
- ***data-page*** : The name of the page to switch to
## {% linkable_title Multiple Dashboards %}
You can also have multiple dashboards, by simply adding a new .erb file to the dashboards directory and navigating to the dashboards via `http://<IP address>:3030/dashboard-file-name-without-extension`
For example, if you want to deploy multiple devices, you could have one dashboard per room and still only use one hadashboard app installation.

95
source/_docs/ecosystem/hadashboard/hapush.markdown Executable file
View file

@ -0,0 +1,95 @@
---
layout: page
title: "HAPush"
description: "HAPush"
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/hapush/
---
# Installing hapush (Manual install only)
This is not necessary if you are using Docker as it is already installed.
When you have the dashboard correctly displaying and interacting with Home Assistant you are ready to install the final component - `hapush`. Without `hapush` the dashboard would not respond to events that happen outside of the hadashboard system. For instance, if someone uses the Home Assistant interface to turn on a light, or even another App or physical switch, there is no way for the Dashboard to reflect this change. This is where `hapush` comes in.
`hapush` is a python daemon that listens to Home Assistant's Event Stream and pushes changes back to the dashboard to update it in real time. You may want to create a [Virtual Environment](https://docs.python.org/3/library/venv.html) for hapush - at the time of writing there is a conflict in the Event Source versions in use between HA and hapush.
Before running `hapush` you will need to add some python prerequisites:
```bash
$ sudo pip3 install daemonize
$ sudo pip3 install sseclient
$ sudo pip3 install configobj
```
Some users are reporting errors with `InsecureRequestWarning`:
```
Traceback (most recent call last):
File "./hapush.py", line 21, in <module>
from requests.packages.urllib3.exceptions import InsecureRequestWarning
ImportError: cannot import name 'InsecureRequestWarning'
```
This can be fixed with:
```bash
$ sudo pip3 install --upgrade requests
```
## {% linkable_title Configuring hapush (all installation methods) %}
When you have all the prereqs in place, copy the hapush.cfg.example file to hapush.cfg then edit it to reflect your environment:
```
ha_url = "http://192.168.1.10:8123"
ha_key = api_key
dash_host = "192.168.1.10:3030"
dash_dir = "/srv/hass/src/hadashboard/dashboards"
logfile = "/etc/hapush/hapush.log"
```
- `ha_url` is a reference to your home assistant installation and must include the correct port number and scheme (`http://` or `https://` as appropriate)
- `ha_key` should be set to your key if you have one, otherwise it can be removed.
- `dash_host` should be set to the IP address and port of the host you are running Dashing on (no http or https) - this should be the same machine as you are running `hapush` on.
- `dash_dir` is the path on the machine that stores your dashboards. This will be the subdirectory `dashboards` relative to the path you cloned `hadashboard` to. For Docker installs this should be set to `/app/dashboards`
- `logfile` is the path to where you want `hapush` to keep its logs. When run from the command line this is not used - log messages come out on the terminal. When running as a daemon this is where the log information will go. In the example above I created a directory specifically for hapush to run from, although there is no reason you can't keep it in the `hapush` subdirectory of the cloned repository. For Docker installs this should be set to `/app/hapush/hapush.log`
## {% linkable_title Running hapush %}
For a manual installation you can then run hapush from the command line as follows:
```bash
$ ./hapush.py hapush.cfg
```
For docker installs, hapush will be started automatically when you run the startup command.
If all is well, you should start to see `hapush` responding to events as they occur. For a docker installation you should see these messages in `hapush/hapush.log`.
```bash
2016-06-19 10:05:59,693 INFO Reading dashboard: /srv/hass/src/hadashboard/dashboards/main.erb
2016-06-19 10:06:12,362 INFO switch.wendy_bedside -> state = on, brightness = 50
2016-06-19 10:06:13,334 INFO switch.andrew_bedside -> state = on, brightness = 50
2016-06-19 10:06:13,910 INFO script.night -> Night
2016-06-19 10:06:13,935 INFO script.night_quiet -> Night
2016-06-19 10:06:13,959 INFO script.day -> Night
2016-06-19 10:06:13,984 INFO script.evening -> Night
2016-06-19 10:06:14,008 INFO input_select.house_mode -> Night
2016-06-19 10:06:14,038 INFO script.morning -> Night
2016-06-19 10:06:21,624 INFO script.night -> Day
2016-06-19 10:06:21,649 INFO script.night_quiet -> Day
2016-06-19 10:06:21,674 INFO script.day -> Day
2016-06-19 10:06:21,698 INFO script.evening -> Day
2016-06-19 10:06:21,724 INFO input_select.house_mode -> Day
2016-06-19 10:06:21,748 INFO script.morning -> Day
2016-06-19 10:06:31,084 INFO switch.andrew_bedside -> state = off, brightness = 30
2016-06-19 10:06:32,501 INFO switch.wendy_bedside -> state = off, brightness = 30
2016-06-19 10:06:52,280 INFO sensor.side_multisensor_luminance_25 -> 871.0
2016-06-19 10:07:50,574 INFO sensor.side_temp_corrected -> 70.7
2016-06-19 10:07:51,478 INFO sensor.side_multisensor_relative_humidity_25 -> 52.0
```

152
source/_docs/ecosystem/hadashboard/installation.markdown Executable file
View file

@ -0,0 +1,152 @@
---
layout: page
title: "Installation"
description: "Installation"
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/installation/
---
Installation can be performed using Docker (Contributed by [marijngiesen](https://github.com/marijngiesen)) or manually if Docker doesn't work for you. We also have a Raspberry PI version of Docker contributed by [snizzleorg](https://community.home-assistant.io/users/snizzleorg/activity)
## {% linkable_title Using Docker (Non Raspian) %}
Assuming you already have Docker installed, installation is fairly easy.
### {% linkable_title Clone the Repository %}
Clone the **hadashboard** repository to the current local directory on your machine.
``` bash
$ git clone https://github.com/home-assistant/hadashboard.git
```
Change your working directory to the repository root. Moving forward, we will be working from this directory.
``` bash
$ cd hadashboard
```
### {% linkable_title Build the docker image %}
```bash
$ docker build -t hadashboard .
```
When the build completes, you can run the dashboard with the following command for unix based systems:
```bash
$ docker run --name="hadashboard" -d -v <path_to_hadashboard>/dashboards:/app/dashboards -v <path_to_hadashboard>/lib/ha_conf.rb:/app/lib/ha_conf.rb -v <path_to_hadashboard>/hapush:/app/hapush --net=host hadashboard
```
If you are running docker on windows you should not use the `--net` command and explicitly specify the port, aslo for security reason `--net=host` should not be used so the following can also be used in unix. This will also set the process to start when the docker process starts so you do not have to worry about reboots. To map the volumes make sure you have ticked the shred drives in the settings. In this example I am using `c:\hadashboard` as the location where the git clone was done and mapping to port 3030 on the host.
```powershell
docker run --restart=always --name="hadashboard" -p 3030:3030 -d -v C:/hadashboard/dashboards:/app/dashboards -v C:/hadashboard/lib/ha_conf.rb:/app/lib/ha_conf.rb -v C:/hadashboard/hapush:/app/hapush hadashboard
```
This will use all of the same configuration files as specified below in the configuration sections, although you will need to make a few changes to the `hapush` configuration to match the docker's filesystem, detailed below.
By default, the docker instance should pick up your timezone but if you want to explicitly set it you can add an environment variable for your specific zone as follows:
```bash
-e "TZ=Europe/Amsterdam"
```
### {% linkable_title Docker on Raspberry Pi %}
Raspberry pi needs to use a different docker build file so the build command is slightly different:
```bash
$ docker build -f Docker-raspi/Dockerfile -t hadashboard .
```
Apart from that the other steps are identical.
*Note - this is pretty slow even on a PI3, be prepared for it to take an hour or two to build all of the extensions and install everything*
## {% linkable_title Manual Installation %}
### {% linkable_title Clone the Repository %}
Clone the **hadashboard** repository to the current local directory on your machine.
``` bash
$ git clone https://github.com/home-assistant/hadashboard.git
```
Change your working directory to the repository root. Moving forward, we will be working from this directory.
``` bash
$ cd hadashboard
```
### {% linkable_title 2. Install Dashing and prereqs %}
Essentially, you want to make sure that you have Ruby installed on your local machine. Then, install the Dashing gem:
``` bash
$ gem install dashing
```
From your repository root, make sure that all dependencies are available.
Note: on some systems you may also need to install bundler:
```bash
$ gem install bundler
```
When installed run it:
``` bash
$ bundle
```
Bundle will now install all the ruby prereqs for running dashing.
Note: Prereqs will vary across different machines. So far users have reported requirements for some additional installs to allow the bundle to complete succesfully:
- ruby-dev - `sudo apt-get install ruby-dev`
- node-js - `sudo apt-get install nodejs`
- libsqlite3-dev - `sudo apt-get install libsqlite3-dev`
- execjs gem - `gem install execjs`
You will need to research what works on your particular architecture and also bear in mind that version numbers may change over time.
Note: This is currently running on various versions of Ruby and there are no strong dependencies however your mileage may vary.
## {% linkable_title Updating configuration (Manual and Docker) %}
Next, in the `./lib` directory, copy the ha_conf.rb.example file to ha_conf.rb and edit its settings to reflect your installation, pointing to the machine Home Assistant is running on and adding your api_key.
```ruby
$ha_url = "http://192.168.1.10:8123"
$ha_apikey = "your key"
```
- `$ha_url` is a reference to your home assistant installation and must include the correct port number and scheme (`http://` or `https://` as appropriate)
- `$ha_apikey` should be set to your key if you have one, otherwise it can remain blank.
The file also contains example newsfeeds for the News widget:
```ruby
$news_feeds = {
"Traffic" => "http://api.sr.se/api/rss/traffic/2863",
"News" => "http://feeds.bbci.co.uk/news/rss.xml",
}
```
You can leave these alone for now or if you prefer customize them as described in the News widget section.
When you are done, you can start a local webserver like this or if you are on docker it should start when you start the container.
```bash
$ dashing start
```
Point your browser to **http://localhost:3030** to access the hadashboard on your local machine, and you should see the supplied default dashboard. If you want to access it remotely ensure you have opened any required firewall rules.
If the page never finishes loading and shows up all white, edit the dashboard config to match your own setup, instructions in the next step.

17
source/_docs/ecosystem/hadashboard/reboot.markdown Executable file
View file

@ -0,0 +1,17 @@
---
layout: page
title: "Reboot"
description: "Reboot"
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/reboot/
---
To run Dashing and `hapush` at reboot, I have provided sample init scripts in the `./init` directory. These have been tested on a Raspberry Pi - your mileage may vary on other systems.
Instructions for automatically starting a docker install can be found [here](https://docs.docker.com/engine/admin/host_integration/).
For docker you may also want to use docker-compose - there is a sample compose file in the `./init` directory.

25
source/_docs/ecosystem/hadashboard/updating.markdown Executable file
View file

@ -0,0 +1,25 @@
---
layout: page
title: "Updating HADashboard"
description: "Updating HADashboard"
release_date: 2016-11-13 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/hadashboard/updating/
---
To update the dashboard after new code has been released, just run the following command to update your copy:
```bash
$ git pull origin
```
For some releases you may also need to rerun the bundle command:
``` bash
$ bundle
```
For docker users, you will also need to rerun the docker build process.

67
source/_docs/ecosystem/ios.markdown Normal file
View file

@ -0,0 +1,67 @@
---
layout: page
title: "iOS"
description: "Documentation about the Home Assistant iOS app."
release_date: 2016-10-24 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/
---
The Home Assistant for iOS app offers a companion app for iOS which is deeply integrated into both Home Assistant and iOS. Its basic features include:
* Advanced push notifications
* Location tracking
* Basic control of all Home Assistant entities
* Integration with third party apps
<p class='note warning'>
Currently, the app is only available via a closed beta. It will be on the App Store within the next few weeks.
</p>
<p class='img'>
<img src='/images/ios/control1.png' width='310' height='552' />
An example of a Home Assistant group as seen in the iOS app.
</p>
## Basic requirements
* iOS device running at least iOS 9, but iOS 10 is greatly preferred.
* Home Assistant 0.31.1 or higher for push notification support.
* SSL is strongly recommended. Self-signed SSL certificates will not work due to Apple's limitations.
The `ios` component is the companion component for the Home Assistant iOS app. While not required, adding the `ios` component to your setup will greatly enhance the iOS app with new notification, location and sensor functions not possible with a standalone app.
Loading the `ios` component will also load the [`device_tracker`][device-tracker], [`zeroconf`][zeroconf] and [`notify`][notify] platforms.
## {% linkable_title Setup %}
### Automated Setup
The `ios` component will automatically be loaded under the following circumstances:
1. The [`discovery`][discovery] component is enabled.
2. You have just installed the app and are at the getting started screen.
Automated discovery and component loaded can only happen at first install of the app. You may need to wait a few minutes for the iOS component to load as the `discovery` component only scans the network every 5 minutes.
### Manual Setup
You may also manually load the `ios` component by adding the following to your configuration:
```yaml
# Example configuration.yaml entry
ios:
```
Configuration variables:
- **push** (*Optional*): Push notification configuration. See the [iOS `notify` platform][ios-notify] for more information.
[discovery]: /components/discovery
[device-tracker]: /components/device_tracker
[zeroconf]: /components/zeroconf
[notify]: /components/notify
[ios-notify]: /ecosystem/ios/notifications/

12
source/_docs/ecosystem/ios/devices_file.markdown Normal file
View file

@ -0,0 +1,12 @@
---
layout: page
title: "ios.conf"
description: "Describes the contents and purpose of ios.conf"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
The `ios.conf` file contains the most recent state of all registered iOS devices. Deleting this file will not disable the devices and the file will be recreated the next time a new device is connected or an existing one reconnects.

26
source/_docs/ecosystem/ios/integration.markdown Normal file
View file

@ -0,0 +1,26 @@
---
layout: page
title: "Integration"
description: "Examples of how Home Assistant for iOS can be integrated with other apps"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/integration/
---
Home Assistant for iOS supports opening from other apps via URL.
Query parameters are passed as a dictionary in the call.
## Call service
Example: `homeassistant://call_service/device_tracker.see?entity_id=device_tracker.entity`
## Fire event
Example `homeassistant://fire_event/custom_event?entity_id=device_tracker.entity`
## Send one shot location
Example: `homeassistant://send_location/`

37
source/_docs/ecosystem/ios/location.markdown Normal file
View file

@ -0,0 +1,37 @@
---
layout: page
title: "Location"
description: "Documentation about the location tracking abilities in Home Assistant for iOS"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/location/
---
## {% linkable_title Location tracking when outside a Home Assistant zone %}
Home Assistant for iOS receives _significant location updates_ from iOS. Whenever an update is received, it is sent to Home Assistant. Roughly, an update is received everytime that your device transfers to a new cellular tower, a significant amount of time has passed (usually a couple hours) or a connection state changes and the system notices your location recently changed.
Apple [defines][apple-location-programming-guide] significant significant-change location updates as:
> The significant-change location service delivers updates only when there has been a significant change in the device’s location, such as 500 meters or more.
They also say in the [Energy Efficiency Guide][apple-energy-guide]:
> Significant-change location updates wake the system and your app once every 15 minutes, at minimum, even if no location changes have occurred.
Finally, I think this answer from [Stack Overflow][stackoverflow] says it best:
> The significant location change is the least accurate of all the location monitoring types. It only gets its updates when there is a cell tower transition or change. This can mean a varying level of accuracy and updates based on where the user is. City area, more updates with more towers. Out of town, interstate, fewer towers and changes.
What's the real story on significant-change location updates? Who knows, because Apple keeps it private.
## {% linkable_title Location tracking in Home Assistant zones %}
At launch, Home Assistant for iOS sets up geofences for all zones in your Home Assistant configuration. Enter and exit notifications are sent to Home Assistant.
[apple-energy-guide]: https://developer.apple.com/library/content/documentation/Performance/Conceptual/EnergyGuide-iOS/LocationBestPractices.html#//apple_ref/doc/uid/TP40015243-CH24-SW4
[apple-location-programming-guide]: https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/LocationAwarenessPG/CoreLocation/CoreLocation.html#//apple_ref/doc/uid/TP40009497-CH2-SW9
[stackoverflow]: http://stackoverflow.com/a/13331625/486182

15
source/_docs/ecosystem/ios/notifications.markdown Normal file
View file

@ -0,0 +1,15 @@
---
layout: page
title: "Notifications Introduction"
description: "Getting started with iOS notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/
---
The `ios` notify platform enables sending push notifications to the Home Assistant iOS app.
The 'ios' component will automatically load the notify serivce. No extra configuration is needed or supported.

143
source/_docs/ecosystem/ios/notifications/actions.markdown Normal file
View file

@ -0,0 +1,143 @@
---
layout: page
title: "Actionable notifications"
description: "Making push notifications a two way system"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/actions/
---
Actionable notifications allow you to attach 1-4 custom buttons to a notification. When one of the actions is selected Home Assistant will be notified which action was chosen. This allows you to build complex automations.
Examples of actionable notifications:
- A notification is sent whenever motion is detected in your home while you are away or asleep. You can add an action to Sound Alarm. When tapped, Home Assistant is notified that the `sound_alarm` action was selected. You can add an automation to sound the burglar alarm whenever this event is seen.
- Someone rings your front door bell. You can send an action to lock or unlock your front door. When tapped, a notification is sent back to Home Assistant upon which you can build automations.
- Send a notification whenever your garage door opens with actions to open and close the garage.
<p class='img'>
<img src='/images/ios/actions.png' />
Actionable notifications allow the user to send a command back to Home Assistant.
</p>
## {% linkable_title Overview of how actionable notifications work %}
In advance of sending a notification:
1. Define a notification category in your Home Assistant configuration which contain 1-4 actions.
2. At launch iOS app requests notification categories from Home Assistant (can also be done manually in notification settings).
When sending a notification:
1. Send a notification with `data.push.category` set to a pre-defined notification category identifer.
2. Push notification delivered to device
3. User opens notification.
3. Action tapped
4. Identifier of action sent back to HA as the `actionName` property of the event `ios.notification_action_fired`, along with other metadata such as the device and category name.
<p class='img'>
<img src='/images/ios/NotificationActionFlow.png' />
How the iOS device and Home Assistant work together to enable actionable notifications.
</p>
## {% linkable_title Definitions %}
- Category - A category represents a type of notification that the app might receive. Think of it as a unique group of actions. A categories parameters include:
- Action - An action consists of a button title and the information that iOS needs to notify the app when the action is selected. You create separate action objects for distinct action your app supports. An actions parameters include:
## {% linkable_title Category parameters %}
- **name** (*Required*): A friendly name for this category.
- **identifier** (*Required*): A unique identifier for the category. Must be uppercase and have no special characters or spaces.
- **action** (*Required*): A list of actions.
## {% linkable_title Action parameters %}
- **identifier** (*Required*): A unique identifier for this action. Must be uppercase and have no special characters or spaces. Only needs to be unique to the category, not unique globally.
- **title** (*Required*): The text to display on the button. Keep it short.
- **activationMode** (*Optional*): The mode in which to run the app when the action is performed. Setting this to `foreground` will make the app open after selecting. Default value is `background`.
- **authenticationRequired** (*Optional*): If a truthy value (`true`, `True`, `yes`, etc.) the user must unlock the device before the action is performed.
- **destructive** (*Optional*): When the value of this property is a truthy value, the system displays the corresponding button differently to indicate that the action is destructive (text color is red).
- **behavior** (*Optional*): When `textInput` the system provides a way for the user to enter a text response to be included with the notification. The entered text will be sent back to Home Assistant. Default value is `default`.
- **textInputButtonTitle** (*Optional*): The button label. *Required* if `behavior` is `textInput`.
- **textInputPlaceholder** (*Optional*): The placeholder text to show in the text input field. Only used if `behavior` is `textInput` and the device runs iOS 10.
Here's a fully built example configuration:
```yaml
ios:
push:
categories:
- name: Alarm
identifier: 'ALARM'
actions:
- identifier: 'SOUND_ALARM'
title: 'Sound Alarm'
activationMode: 'background'
authenticationRequired: yes
destructive: yes
behavior: 'default'
- identifier: 'SILENCE_ALARM'
title: 'Silence Alarm'
activationMode: 'background'
authenticationRequired: yes
destructive: no
behavior: 'textInput'
textInputButtonTitle: 'Silencio!'
textInputPlaceholder: 'Placeholder'
```
## {% linkable_title Building automations for notification actions %}
Here is an example automation to send a notification with a category in the payload:
```yaml
automation:
- alias: Notify iOS app
trigger:
...
action:
service: notify.ios_robbies_iphone_7_plus
data:
message: "Something happened at home!"
data:
push:
badge: 5
sound: <SOUND FILE HERE>
category: "ALARM" # Needs to match the top level identifier you used in the ios configuration
action_data: # Anything passed in action_data will get echoed back to Home Assistant.
entity_id: light.test
my_custom_data: foo_bar
```
When an action is selected an event named `ios.notification_action_fired` will be emitted on the Home Assistant event bus. Below is an example payload.
```json
{
"sourceDeviceName": "Robbie's iPhone 7 Plus",
"sourceDeviceID": "robbies_iphone_7_plus",
"actionName": "SOUND_ALARM",
"sourceDevicePushId": "ab9f02fe-6ac6-47b8-adeb-5dd87b489156",
"textInput": "",
"actionData": {}
}
```
Here's an example automation for the given payload:
```yaml
automation:
- alias: Sound the alarm
trigger:
platform: event
event_type: ios.notification_action_fired
event_data:
actionName: SOUND_ALARM
action:
...
```
Notes:
* `textInput` will only exist if `behavior` was set to `textInput`.
* `actionData` is a dictionary with parameters passed in the `action_data` dictionary of the `push` dictionary in the original notification.

16
source/_docs/ecosystem/ios/notifications/architecture.markdown Normal file
View file

@ -0,0 +1,16 @@
---
layout: page
title: "Architecture"
description: "The push notification system layout"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/architecture/
---
<p class='img'>
<img src='/images/ios/PushNotificationLayout.png' />
The push notification infrastructure layout
</p>

77
source/_docs/ecosystem/ios/notifications/attachments.markdown Normal file
View file

@ -0,0 +1,77 @@
---
layout: page
title: "Notification attachments"
description: "Adding attachments to iOS push notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/attachments/
---
iOS 10 adds _attachments_ to notifications. An attachment is an image, video, or audio file which is downloaded to the device when a notification is received and shown alongside the notification. A thumbnail is shown when the notification is not expanded. The full size attachment is shown when the notification is expanded.
<p class="note">
To expand a notification on 3D Touch devices simply force touch any notification. On non-3D Touch devices swipe and tap the "View" button.
</p>
```yaml
- alias: Notify iOS app
trigger:
...
action:
service: notify.ios_robbies_iphone_7_plus
data:
message: "Something happened at home!""
data:
attachment:
url: https://67.media.tumblr.com/ab04c028a5244377a0ab96e73915e584/tumblr_nfn3ztLjxk1tq4of6o1_400.gif
content-type: gif
hide-thumbnail: false
```
Notes:
* The thumbnail of the notification will be the media at the `url`.
* The notification content is the media at the `url`.
* Attachment can be used with custom push notification categories.
## Example
<p class='img'>
<img src='/images/ios/attachment.png' />
An unexpanded push notification with an attachment.
</p>
<p class='img'>
<img src='/images/ios/expanded_attachment.png' />
The same notification but expanded to show the full size attachment
</p>
## Supported media types
If the attachment does not appear please ensure it is in one of the following formats:
### Audio attachments
Maximum file size: 5 MB
Allowed Formats: AIFF, WAV, MP3, MPEG4 Audio
### Image attachments
Maximum file size: 10 MB
Allowed Formats: JPEG, GIF, PNG
### Video attachments
Maximum file size: 50 MB
Allowed Formats: MPEG, MPEG2, MPEG4, AVI
## Configuration
- **url** (*Required*): The URL of content to use as the attachment. This URL _must_ be accessible from the Internet, or the receiving device must be on the same network as the hosted content.
- **content-type** (*Optional*): By default, the extension of the URL will be checked to determine the filetype. If there is no extension/it can't be determined you can manually provide a file extension.
- **hide-thumbnail** (*Optional*): If set to `true` the thumbnail will not show on the notification. The content will only be viewable by expanding.

59
source/_docs/ecosystem/ios/notifications/basic.markdown Normal file
View file

@ -0,0 +1,59 @@
---
layout: page
title: "Basic Notifications"
description: "Basic notes about iOS notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/basic/
---
The iOS notify platform accepts the standard `title`, `message` and `target` parameters. The iOS notify platform supports targets as services. Assuming that you did not set a `name` when configuring the platform you should find all your registered and notification-enabled iOS devices available as notify targets as services with names prefixed "notify.ios_" and then the device name you entered at setup.
Notes:
* `title` only displays on Apple Watch and iOS 10 devices.
* `target` can be used to specific a single device using its PushID, found in `ios.conf`. The preferred way of providing a target is through a target specific notify service.
<p class='img'>
<img src='/images/ios/example.png' />
A push notification showing all of the basic options `title` and `message` as well as `subtitle` and [actions](/ecosystem/ios/notifications/actions/).
</p>
### {% linkable_title Enhancing basic notifications %}
#### Badge
You can set the icon badge in the payload:
```yaml
automation:
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "Something happened at home!"
data:
push:
badge: 5
```
#### Subtitle
iOS 10 supports a subtitle in addition to the title:
```yaml
automation
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "Something happened at home!"
data:
subtitle: "Subtitle goes here"
```

62
source/_docs/ecosystem/ios/notifications/content_extensions.markdown Normal file
View file

@ -0,0 +1,62 @@
---
layout: page
title: "Dynamic content"
description: "Extend your notifications with dynamic content"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/content_extensions/
---
With the new Content Extension feature found in iOS 10, dynamic content can now be displayed as part of a notification without opening an app.
# Map
Will show a map with a red tipped pin at the coordinates given.
The map will be centered at the coordinates given.
```yaml
service: notify.iOSApp
data:
message: Something happened at home!
data:
push:
category: map
action_data:
latitude: 40.785091
longitude: -73.968285
```
<p class='img'>
<img src='/images/ios/map.png' />
An example of the map dynamic content.
</p>
# Camera Stream
The notification thumbnail will be a still image from the camera.
The notification content is a real time MJPEG stream of a camera (assuming the camera supports it).
You can use the attachment parameters `content-type` and `hide-thumbnail` with camera.
You can view an example [here](https://www.youtube.com/watch?v=LmYwpxPKW0g).
```yaml
service: notify.iOSApp
data:
message: Motion detected in the Living Room
data:
push:
category: camera
entity_id: camera.demo_camera
```
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/LmYwpxPKW0g" frameborder="0" allowfullscreen></iframe>
</div>
# Combining with actionable notifications
As you can see the `category` key is used to tell the device what kind of content extension to use. You can use the same category identifiers in your own custom [actions](/ecosystem/ios/notifications/actions/) to add actions to the content extension.

23
source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown Normal file
View file

@ -0,0 +1,23 @@
---
layout: page
title: "Privacy, rate limiting and security"
description: "Notes about important topics relating to push notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/privacy_security_rate_limits/
---
## {% linkable_title Privacy %}
No notification content is stored on remote servers. Only the required push registration data and a simple counter of the total number of push notifications sent per day per device (for rate limiting purposes) is kept.
## {% linkable_title Rate limiting %}
Currently, you are allowed to send a maximum of 150 push notifications per day per device. This is to ensure that the service remains cheap to maintain. In the future we may add support for upgrading to allow more notifications. The rate limit resets at midnight UTC daily. When a notification is sent your current rate limits (including sent notifications and notifications remaining for the day) will be output to your Home Assistant logs. If an error occurs while sending a notification your rate limit will not be affected.
## {% linkable_title Security %}
All traffic between your Home Assistant instance, the push infrastructure, and Apple, is encrypted with SSL.

31
source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown Normal file
View file

@ -0,0 +1,31 @@
---
layout: page
title: "Requesting location updates"
description: "Ask the device to send a location update remotely"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/requesting_location_updates/
---
<p class="note warning">
**Do not rely on this functionality due to the time limits mentioned below.**
</p>
You can force a device to attempt to report its location by sending a special notification.
```yaml
automation
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: "request_location_update"
```
Assuming the device receives the notification, it will attempt to get a location update within 5 seconds and report it to Home Assistant. This is a little bit hit or miss since Apple imposes a maximum time allowed for the app to work with the notification and location updates sometimes take longer than usual due to factors such as waiting for GPS acquisition.

185
source/_docs/ecosystem/ios/notifications/sounds.markdown Normal file
View file

@ -0,0 +1,185 @@
---
layout: page
title: "Notification Sounds"
description: "Adding sounds to notifications"
date: 2016-10-25 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/ios/notifications/sounds/
---
Adding a custom sound to a notification allows you to easily identify the notification without even looking at your device. Home Assistant for iOS comes with some notification sounds pre-installed but you can also upload your own.
Here is an example notification that uses one of the pre-installed sounds.
```yaml
- alias: Notify iOS app
trigger:
...
action:
service: notify.iOSApp
data:
message: “Something happened at home!”
data:
push:
sound: "US-EN-Morgan-Freeman-Roommate-Is-Arriving.wav"
```
Notes:
* You must use the full filename in the payload (including extension).
## {% linkable_title Custom push notification sounds %}
The app allows you to use your own custom sounds in push notifications. The sounds must be formatted following [Apple's requirements][sound-requirements]. You set the filename of the sound in the notification payload. To add sounds:
1. Connect the device to a PC or Mac running the latest version of iTunes.
2. Go to the device in iTunes.
3. Select "Apps" on the left sidebar.
4. Scroll down until you see the section labeled "File Sharing".
5. Select HomeAssistant.
6. Drag and drop properly formatted sounds.
7. Click Sync in the lower right.
8. Once sync is complete, disconnect the device from the computer.
9. On your iOS device, open the Home Assistant app.
10. Go to Settings -> Notification Settings.
11. Select "Import sounds from iTunes".
Assuming that you correctly formatted the sounds they are now available to use in push notifications.
Notes:
* **Please note that due to a bug in iOS 10 you may need to restart your entire device before notification sounds can be played. This should hopefully be fixed by Apple soon.**
* Uploading a file with the same name as an existing one will overwrite the original.
* You can view what sounds are installed on each device by inspecting the `ios.conf` file in your configuration directory. They are listed in the `pushSounds` array.
### {% linkable_title Preinstalled notification sounds %}
```
US-EN-Alexa-Back-Door-Opened.wav
US-EN-Alexa-Back-Door-Unlocked.wav
US-EN-Alexa-Basement-Door-Opened.wav
US-EN-Alexa-Basement-Door-Unlocked.wav
US-EN-Alexa-Boyfriend-Is-Arriving.wav
US-EN-Alexa-Daughter-Is-Arriving.wav
US-EN-Alexa-Front-Door-Opened.wav
US-EN-Alexa-Front-Door-Unlocked.wav
US-EN-Alexa-Garage-Door-Opened.wav
US-EN-Alexa-Girlfriend-Is-Arriving.wav
US-EN-Alexa-Good-Morning.wav
US-EN-Alexa-Good-Night.wav
US-EN-Alexa-Husband-Is-Arriving.wav
US-EN-Alexa-Mail-Has-Arrived.wav
US-EN-Alexa-Motion-At-Back-Door.wav
US-EN-Alexa-Motion-At-Front-Door.wav
US-EN-Alexa-Motion-Detected-Generic.wav
US-EN-Alexa-Motion-In-Back-Yard.wav
US-EN-Alexa-Motion-In-Basement.wav
US-EN-Alexa-Motion-In-Front-Yard.wav
US-EN-Alexa-Motion-In-Garage.wav
US-EN-Alexa-Patio-Door-Opened.wav
US-EN-Alexa-Patio-Door-Unlocked.wav
US-EN-Alexa-Smoke-Detected-Generic.wav
US-EN-Alexa-Smoke-Detected-In-Basement.wav
US-EN-Alexa-Smoke-Detected-In-Garage.wav
US-EN-Alexa-Smoke-Detected-In-Kitchen.wav
US-EN-Alexa-Son-Is-Arriving.wav
US-EN-Alexa-Water-Detected-Generic.wav
US-EN-Alexa-Water-Detected-In-Basement.wav
US-EN-Alexa-Water-Detected-In-Garage.wav
US-EN-Alexa-Water-Detected-In-Kitchen.wav
US-EN-Alexa-Welcome-Home.wav
US-EN-Alexa-Wife-Is-Arriving.wav
US-EN-Daisy-Back-Door-Motion.wav
US-EN-Daisy-Back-Door-Open.wav
US-EN-Daisy-Front-Door-Motion.wav
US-EN-Daisy-Front-Door-Open.wav
US-EN-Daisy-Front-Window-Open.wav
US-EN-Daisy-Garage-Door-Open.wav
US-EN-Daisy-Guest-Bath-Leak.wav
US-EN-Daisy-Kitchen-Sink-Leak.wav
US-EN-Daisy-Kitchen-Window-Open.wav
US-EN-Daisy-Laundry-Room-Leak.wav
US-EN-Daisy-Master-Bath-Leak.wav
US-EN-Daisy-Master-Bedroom-Window-Open.wav
US-EN-Daisy-Office-Window-Open.wav
US-EN-Daisy-Refrigerator-Leak.wav
US-EN-Daisy-Water-Heater-Leak.wav
US-EN-Morgan-Freeman-Back-Door-Closed.wav
US-EN-Morgan-Freeman-Back-Door-Locked.wav
US-EN-Morgan-Freeman-Back-Door-Opened.wav
US-EN-Morgan-Freeman-Back-Door-Unlocked.wav
US-EN-Morgan-Freeman-Basement-Door-Closed.wav
US-EN-Morgan-Freeman-Basement-Door-Locked.wav
US-EN-Morgan-Freeman-Basement-Door-Opened.wav
US-EN-Morgan-Freeman-Basement-Door-Unlocked.wav
US-EN-Morgan-Freeman-Boss-Is-Arriving.wav
US-EN-Morgan-Freeman-Boyfriend-Is-Arriving.wav
US-EN-Morgan-Freeman-Cleaning-Supplies-Closet-Opened.wav
US-EN-Morgan-Freeman-Coworker-Is-Arriving.wav
US-EN-Morgan-Freeman-Daughter-Is-Arriving.wav
US-EN-Morgan-Freeman-Friend-Is-Arriving.wav
US-EN-Morgan-Freeman-Front-Door-Closed.wav
US-EN-Morgan-Freeman-Front-Door-Locked.wav
US-EN-Morgan-Freeman-Front-Door-Opened.wav
US-EN-Morgan-Freeman-Front-Door-Unlocked.wav
US-EN-Morgan-Freeman-Garage-Door-Closed.wav
US-EN-Morgan-Freeman-Garage-Door-Opened.wav
US-EN-Morgan-Freeman-Girlfriend-Is-Arriving.wav
US-EN-Morgan-Freeman-Good-Morning.wav
US-EN-Morgan-Freeman-Good-Night.wav
US-EN-Morgan-Freeman-Liquor-Cabinet-Opened.wav
US-EN-Morgan-Freeman-Motion-Detected.wav
US-EN-Morgan-Freeman-Motion-In-Basement.wav
US-EN-Morgan-Freeman-Motion-In-Bedroom.wav
US-EN-Morgan-Freeman-Motion-In-Game-Room.wav
US-EN-Morgan-Freeman-Motion-In-Garage.wav
US-EN-Morgan-Freeman-Motion-In-Kitchen.wav
US-EN-Morgan-Freeman-Motion-In-Living-Room.wav
US-EN-Morgan-Freeman-Motion-In-Theater.wav
US-EN-Morgan-Freeman-Motion-In-Wine-Cellar.wav
US-EN-Morgan-Freeman-Patio-Door-Closed.wav
US-EN-Morgan-Freeman-Patio-Door-Locked.wav
US-EN-Morgan-Freeman-Patio-Door-Opened.wav
US-EN-Morgan-Freeman-Patio-Door-Unlocked.wav
US-EN-Morgan-Freeman-Roommate-Is-Arriving.wav
US-EN-Morgan-Freeman-Searching-For-Car-Keys.wav
US-EN-Morgan-Freeman-Setting-The-Mood.wav
US-EN-Morgan-Freeman-Smartthings-Detected-A-Flood.wav
US-EN-Morgan-Freeman-Smartthings-Detected-Carbon-Monoxide.wav
US-EN-Morgan-Freeman-Smartthings-Detected-Smoke.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Basement.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Garage.wav
US-EN-Morgan-Freeman-Smoke-Detected-In-Kitchen.wav
US-EN-Morgan-Freeman-Someone-Is-Arriving.wav
US-EN-Morgan-Freeman-Son-Is-Arriving.wav
US-EN-Morgan-Freeman-Starting-Movie-Mode.wav
US-EN-Morgan-Freeman-Starting-Party-Mode.wav
US-EN-Morgan-Freeman-Starting-Romance-Mode.wav
US-EN-Morgan-Freeman-Turning-Off-All-The-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Air-Conditioner.wav
US-EN-Morgan-Freeman-Turning-Off-The-Bar-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Chandelier.wav
US-EN-Morgan-Freeman-Turning-Off-The-Family-Room-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Hallway-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Kitchen-Light.wav
US-EN-Morgan-Freeman-Turning-Off-The-Light.wav
US-EN-Morgan-Freeman-Turning-Off-The-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-Mood-Lights.wav
US-EN-Morgan-Freeman-Turning-Off-The-TV.wav
US-EN-Morgan-Freeman-Turning-On-The-Air-Conditioner.wav
US-EN-Morgan-Freeman-Turning-On-The-Bar-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Chandelier.wav
US-EN-Morgan-Freeman-Turning-On-The-Family-Room-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Hallway-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Kitchen-Light.wav
US-EN-Morgan-Freeman-Turning-On-The-Light.wav
US-EN-Morgan-Freeman-Turning-On-The-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-Mood-Lights.wav
US-EN-Morgan-Freeman-Turning-On-The-TV.wav
US-EN-Morgan-Freeman-Vacate-The-Premises.wav
US-EN-Morgan-Freeman-Water-Detected-In-Basement.wav
US-EN-Morgan-Freeman-Water-Detected-In-Garage.wav
US-EN-Morgan-Freeman-Water-Detected-In-Kitchen.wav
US-EN-Morgan-Freeman-Welcome-Home.wav
US-EN-Morgan-Freeman-Wife-Is-Arriving.wav
```

134
source/_docs/ecosystem/nginx.markdown Normal file
View file

@ -0,0 +1,134 @@
---
layout: page
title: "NGINX"
description: "Documentation about setting up Home Assistant with NGINX."
release_date: 2016-12-02 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/nginx/
---
Using nginx as a proxy for Home Assistant allows you to serve Home Assistant securely over standard ports. This configuration file and instructions will walk you through setting up Home Assistant over a secure connection.
### {% linkable_title 1. Get a domain name forwarded to your IP %}
Chances are, you have a dynamic IP Address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
### {% linkable_title 2 Install nginx on your server %}
This will vary depending on your OS. Check out Google for this. After installing, ensure that nginx is not running.
### {% linkable_title 3. Obtain an SSL certificate %}
There are two ways of obtaining an SSL certificate.
#### {% linkable_title Using Let's Encrypt %}
If you purchased your own domain, you can use https://letsencrypt.org/ to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command.
```
./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
```
Instead of example.com, use your domain. You will need to renew this certificate every 90 days.
#### {% linkable_title Using openssl %}
If you do not own your own domain, you may generate a self-signed certificate. This will not work with IFTTT, but it will encrypt all of your Home Assistant traffic.
```
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 9999
sudo cp key.pem cert.pem /etc/nginx/ssl
sudo chmod 600 /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
sudo chown root:root /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
```
### {% linkable_title 4. Create dhparams file %}
As a fair warning, this file will take a while to generate.
```
cd /etc/nginx/ssl
sudo openssl dhparam -out dhparams.pem 2048
```
### {% linkable_title 5. Install configuration file in nginx. %}
Create a new file `/etc/nginx/sites-available/hass` and copy the configuration file at the bottom of the page into it.
### {% linkable_title 6. Enable the Home Assistant configuration. %}
```
cd /etc/nginx/sites-enabled
sudo unlink default
sudo ln ../sites-available/hass default
```
### {% linkable_title 7. Start NGINX. %}
Double check this configuration to ensure all settings are correct and start nginx.
### {% linkable_title 8. Port forwarding. %}
Forward ports 443 and 80 to your server on your router. Do not forward port 8123.
### {% linkable_title NGINX Config %}
```
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
# Update this line to be your domain
server_name example.com;
# These shouldn't need to be changed
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
return 301 https://$host$request_uri;
}
server {
# Update this line to be your domain
server_name example.com;
# Ensure these lines point to your SSL certificate and key
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# Use these lines instead if you created a self-signed certificate
# ssl_certificate /etc/nginx/ssl/cert.pem;
# ssl_certificate_key /etc/nginx/ssl/key.pem;
# Ensure this line points to your dhparams file
ssl_dhparam /etc/nginx/ssl/dhparams.pem;
# These shouldn't need to be changed
listen 443 default_server;
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
ssl on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
proxy_buffering off;
location / {
proxy_pass http://localhost:8123;
proxy_set_header Host $host;
proxy_redirect http:// https://;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
}
```

21
source/_docs/ecosystem/notebooks.markdown Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
title: "Jupyter Notebooks"
description: "Jupyter Notebooks to interact offline and online with Home Assistant."
release_date: 2016-11-13 15:00:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/
---
The [Jupyter Notebooks](http://jupyter.org/) allows you to create and share documents that contain live code, equations, visualizations, and explanatory text directly in your browser. The web application what is formerly known as the IPython Notebook supports over 40 programming languages.
Visit [https://try.jupyter.org/](https://try.jupyter.org/) to get a preview before you install it locally.
<p class='img'>
<img src='{{site_root}}/images/screenshots/jupyter-new.png' />
</p>
[nbviewer](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/tree/master/) is rendering our notebooks online. GitHub is creating a preview as well.

13
source/_docs/ecosystem/notebooks/api.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Home Assistant Python API"
description: "Basic example how to work with the Home Assistant Python API in a Jupyter notebook."
date: 2016-07-23 09:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/api/
---
The [Python API](/developers/python_api/) allows one to create [interactive notebooks](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/home-assistant-python-api.ipynb).

13
source/_docs/ecosystem/notebooks/database.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Database"
description: "Basic example how to work with stored Home Assistant information in a Jupyter notebook."
date: 2016-07-23 09:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/database/
---
The [Database example](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/database-examples.ipynb) shows you the details about how you can work with stored values.

13
source/_docs/ecosystem/notebooks/graph.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Graph"
description: "Basic example how to create a graph with a Jupyter notebook."
date: 2016-07-23 09:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/graph/
---
For graphing this [Jupyter notebook](ha_external_link: http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/graph-single-sensor.ipynb) should get you started.

51
source/_docs/ecosystem/notebooks/installation.markdown Normal file
View file

@ -0,0 +1,51 @@
---
layout: page
title: "Installation"
description: "Setup and first steps for Jupyter Notebooks and Home Assistant."
date: 2016-07-23 09:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/installation/
---
To run Jupyter Notebooks locally, an installation of [Jupyter](http://jupyter.org/) is needed. Consider to run Jupyter in a [virtualenv](/getting-started/installation-virtualenv/).
```bash
$ pip3 install jupyter matplotlib
```
<p class='note warning'>
Certain notebooks hosted in the [Home Assistant notebooks repository](https://github.com/home-assistant/home-assistant-notebooks) require access to a running Home Assistant instance or parts of a Home Assistant installation. If you want to run those notebooks, install Home Assistant with `$ pip3 install homeassistant` as well.
</p>
Now you are able to start the application.
```bash
$ jupyter notebook
[I 17:22:18.081 NotebookApp] Writing notebook server cookie secret to /run/user/1000/jupyter/notebook_cookie_secret
[I 17:22:18.921 NotebookApp] Serving notebooks from local directory: /home/fabaff/home-assistant
[I 17:22:18.921 NotebookApp] 0 active kernels
[I 17:22:18.921 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/
[I 17:22:18.922 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
```
Open [http://localhost:8888/](http://localhost:8888/) in your browser. Press "New" -> "Python3" to open a new notebook.
<p class='img'>
<img src='{{site_root}}/images/screenshots/jupyter-new.png' />
</p>
You will get an empty notebook with one cell. Cells can contain code or text. To get the output of a cell you need to execute them with "Cell" -> "Run Cells" from the menu or by pressing the icon.
<p class='img'>
<img src='{{site_root}}/images/screenshots/jupyter-notebook.png' />
</p>
The downloadable version of this notebook is available in the [Home Assistant notebooks repository](https://github.com/home-assistant/home-assistant-notebooks/blob/master/first-notebook.ipynb).
As you can see is the workflow very similar to working directly with a Python shell. One advantage is that you can go back and forth as you please and save your work.

13
source/_docs/ecosystem/notebooks/stats.markdown Normal file
View file

@ -0,0 +1,13 @@
---
layout: page
title: "Statistics"
description: "Basic example how to create basic statistics with a Jupyter notebook."
date: 2016-10-03 09:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/notebooks/stats/
---
The [Statistics notebook](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/database-statistics.ipynb) gets you started if you want to create statistical analysis of your data.

170
source/_docs/ecosystem/scenegen.markdown Normal file
View file

@ -0,0 +1,170 @@
---
layout: page
title: "SceneGen"
description: "Scenegen is a scene generation tool for Home Assistant"
release_date: 2016-10-30 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/scenegen/
---
Scenegen is a scene generation tool for [Home Assistant](https://home-assistant.io/) home automation software. It creates scenes by example, by reading the current states of devices and outputting a corresponding scene. Scenegen is written in python using Home Assistant's RESTFul API so can be run from anywhere. It currently supports lights and switches only.
## {% linkable_title Installation %}
### {% linkable_title Clone the Repository %}
Clone the [**scenegen**](https://github.com/home-assistant/scenegen) repository to the current local directory on your machine.
``` bash
$ git clone https://github.com/home-assistant/scenegen.git
```
Change your working directory to the repository root. Moving forward, we will be working from this directory.
``` bash
$ cd scenegen
```
## {% linkable_title Install Prerequisites %}
Before running `SceneGen` you will need to add some python prerequisites:
```bash
$ sudo pip3 install configparser
```
You should now be ready to run `scenegen`
## {% linkable_title Basic Operation %}
```
usage: scenegen [-h] [-k KEY] [-s SCENENAME] [-m MAPFILE] [-f FILTER]
[-c {xy_color,rgb_color,color_temp,color_name}] [-t TYPES]
url
positional arguments:
url url for Home Assistant instance
optional arguments:
-h, --help show this help message and exit
-k KEY, --key KEY API Key of Home Assistant instance
-s SCENENAME, --scenename SCENENAME
Name of scene to generate
-m MAPFILE, --mapfile MAPFILE
Name of mapfile to enable device filtering
-f FILTER, --filter FILTER
Comma separated list of device collections as defined
in mapfile
-c {xy_color,rgb_color,color_temp,color_name}, --colortype {xy_color,rgb_color,color_temp,color_name}
color type to use
-t TYPES, --types TYPES
list of device types to include
```
For basic operation just supply the url and optionally the api key (using the --key option) on the command line and scenegen will output a list of all lights and switches with their attributes. Optionally use the `--scenename` flag to explicitly set the scenename.
```
$ ./scenegen.py https://<some url> -k <some api key>
name: My New Scene
entities:
light.bedroom:
state: on
brightness: 28
light.kitchen:
state: off
light.living_room:
state: off
light.bedside:
state: on
brightness: 125
color_temp: 412
light.office_level_29:
state: on
brightness: 28
```
This output can be cut and pasted into your configuration.yaml file as required (ensuring correct indentatation of course).
Scenegen supports all documented effects for lights including transitions and flash effects, however generally it is easier to run scenegen to get the basic setup and add any effects manually later.
Note that depending on the type of light there may be a delay in actually setting up its parameters and Home Assistant actually recieving that state. For instance, if you set a scene up with the Hue App, Home Assistant won't see those changes for up to 10 seconds. Turning on a ZWave light might not be seen for an entire poll interval. For this reason, its good practice to wait for a while after the scene is setup before running scenegen. Alternatively, perform all setup using the Home Assistant frontend and it will instantly have the required state for capture.
## {% linkable_title Advanced Usage %}
For a more advanced way to use the output try the following. In configuration.yaml add the following line:
```
scene: !include_dir_list scenes
```
This will tell home assistant to look in the subdirectory `scenes` for yaml files containing scene information. Each file will be named for the scene it will create and should contain information formatted as above. Then simply run Scenegen and redirect its output to the scenes subdirectory:
```
$ ./scenegen.py https://<some url> -k <some api key> > scenes/my_new_scene.yaml
```
This will create a new scene called `my_new_scene` which will automatically be picked up by Home Assistant on the next restart.
## {% linkable_title Colors %}
Scenegen allows colors to be captured, and in fact Home Assistant light entities store up to 4 different ways of specifying the colors. This is redundant for creating scenes so Scenegen picks 1 and goes with it. The default is `color_temp` but you can change this with the `--colortype` flag, supported options are `xy_color`, `rgb_color`, `color_temp` and `color_name`.
## {% linkable_title Types %}
By default, Scenegen will list all lights and switches. To restrict the device type use the `--types` option and supply a comma separated list (no spaces) of types to output. e.g.:
```
./scenegen.py https://<some url> -k <some api key> --types light,switch
```
or:
```
./scenegen.py https://<some url> -k <some api key> --types light
```
This will make more sense as and when more types are added.
## {% linkable_title Maps and Filters %}
Maps allow you to specify and label various subsets of devices that you want to work on together. A mapfile is specified using the `--mapfile` option and is a `.ini` style file consisting of section headers and entries. The section headers specify a region or zone or otherwise organized selection of entities you want to filter on, and it is mandatory to have at least one. If you create a map file like this:
```
[entities]
light.living_room:
light.dining_room:
```
The trailing colons are necessary to prevent parsing errors for including just keys, as opposed to key=value so just go with it - it reminds us of YAML ;)
If you run scenegen with the `--mapfile` argument pointing to that file you will only get output for the listed entities (the name of the section is irrelevant if not using the `--filter` option). A more complex mapfile might look like this:
```
[Outside]
light.porch:
switch.path_lights:
[Living Room]
light.living_room_front:
light.living_room_back:
[Bedroom]
light.bedside:
```
Again, if you run with that map file it will output all of the entities listed, however you now have the possibility of restricting output devices based on the sections they are in, using the `--filter` option and supplying a comma separated list of sections you want to include, for instance:
```
./scenegen.py https://<some url> -k <some api key> --mapfile map.cfg --filter "Outside,Living Room"
```
The intended use of the mapfile and filter is that you create a map of all your devices and organize them into zones that you are interested in creating scenes for and use the filter to limit output to that zone. For instance you might want to create 3 or 4 scenes for your living room, and once the map is set up you can easily do so without the addition of unwanted devices.
## {% linkable_title Updating SceneGen %}
To update SceneGen after a new version is released, just run the following command to update your copy:
```bash
$ git pull
```

25
source/_docs/ecosystem/synology.markdown Normal file
View file

@ -0,0 +1,25 @@
---
layout: page
title: "Synology"
description: "Instructions how to get Home Assistant up and running on Synology"
release_date: 2016-12-07 15:00:00 -0500
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /ecosystem/synology/
---
Synology NAS are the perfect companion to running Home Assistant.
### {% linkable_title HTTP Configuration %}
Synology will require some extra configuration to get the Home Assistant frontend working.
- Copy the Home Assistant specific Reverse Proxy settings from the existing `/etc/nginx/app.d/server.ReverseProxy.conf` to `/usr/local/etc/nginx/conf.d/http.HomeAssistant.conf`
- Include these lines in the location declaration:
```
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

21
source/_docs/frontend.markdown Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
title: "Frontend of Home Assistant"
description: "Frontend of Home Assistant."
date: 2017-02-13 12:50
sidebar: true
comments: false
sharing: true
footer: true
---
The frontend of Home Assistant is built with [Polymer](https://www.polymer-project.org/).
<p class='img'>
<img src='{{site_root}}/images/screenshots/ui2015.png' />
</p>
The [User Interface section](/cookbook/#user-interface) can give you some starting points to expand the frontend.
If you want to work on the frontend, please refer to the [Frontend Development documentation](/developers/frontend/).

83
source/_docs/frontend/browsers.markdown Normal file
View file

@ -0,0 +1,83 @@
---
layout: page
title: "Browsers"
description: "Browser Compatibility List"
date: 2016-06-25 08:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/browsers/
---
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/

33
source/_docs/frontend/mobile.markdown Normal file
View file

@ -0,0 +1,33 @@
---
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/mobile/
---
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

39
source/_docs/frontend/webserver.markdown Normal file
View file

@ -0,0 +1,39 @@
---
layout: page
title: "Web server fingerprint"
description: "Use nmap to scan your Home Assistant instance."
date: 2016-10-06 08:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /details/webserver/
---
It was only a matter of time till the first queries for tools like [https://www.shodan.io](https://www.shodan.io/search?query=Home+Assistant) to search for Home Assistant instances showed up.
To get an idea about how your Home Assistant instance looks like for network scanner, you can use `nmap`. The `nmap` tool is already available if you are using the [nmap device tracker](/components/device_tracker/).
```yaml
$ nmap -sV -p 8123 --script=http-title,http-headers 192.168.1.3
Starting Nmap 7.12 ( https://nmap.org ) at 2016-10-06 10:01 CEST
Nmap scan report for 192.168.1.3 (192.168.1.3)
Host is up (0.00011s latency).
PORT STATE SERVICE VERSION
8123/tcp open http CherryPy wsgiserver
| http-headers:
| Content-Type: text/html; charset=utf-8
| Content-Length: 4309
| Connection: close
| Date: Thu, 06 Oct 2016 08:01:31 GMT
| Server: Home Assistant
|
|_ (Request type: GET)
|_http-server-header: Home Assistant
|_http-title: Home Assistant
Service detection performed. Please report any incorrect results at https://nmap.org/submit/ .
Nmap done: 1 IP address (1 host up) scanned in 6.70 seconds
```

23
source/_docs/hassbian.markdown Normal file
View file

@ -0,0 +1,23 @@
---
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
redirect_from: /getting-started/hassbian/
---
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]: /docs/hassbian/installation/
[customize]: /docs/hassbian/customization/
[common]: /docs/hassbian/common-tasks/
[integrations]: /docs/hassbian/integrations/

130
source/_docs/hassbian/common-tasks.markdown Normal file
View file

@ -0,0 +1,130 @@
---
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
redirect_from: /getting-started/hassbian-common-tasks/
---
### {% 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

23
source/_docs/hassbian/customization.markdown Normal file
View file

@ -0,0 +1,23 @@
---
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
redirect_from: /getting-started/hassbian-customization/
---
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/

37
source/_docs/hassbian/installation.markdown Normal file
View file

@ -0,0 +1,37 @@
---
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] (359 MB)
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`
[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

101
source/_docs/hassbian/integrations.markdown Normal file
View file

@ -0,0 +1,101 @@
---
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
redirect_from: /getting-started/hassbian-installation/
---
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.

30
source/_docs/hassbian/upgrading.markdown Normal file
View file

@ -0,0 +1,30 @@
---
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
redirect_from: /getting-started/hassbian-upgrading/
---
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
```

18
source/_docs/installation.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Installation of Home Assistant"
description: "Instructions how to install Home Assistant to launch on start."
date: 2017-02-15 08:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/installation/
---
Home Assistant provides multiple ways to be installed. If you are a Raspberry Pi owner then the [Hassbian](/docs/hassbian/) is an easy and simple way to run home Assistant.
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**.
It may be needed that you install additional library depending on the platforms/components you want to use.

38
source/_docs/installation/docker.markdown Normal file
View file

@ -0,0 +1,38 @@
---
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
redirect_from: /getting-started/installation-docker/
---
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:
### {% linkable_title Linux %}
```bash
$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
```
### {% linkable_title macOS %}
When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "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).
```bash
$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant
```
### {% linkable_title Restart %}
This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
If you change the configuration 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`

32
source/_docs/installation/python.markdown Normal file
View file

@ -0,0 +1,32 @@
---
layout: page
title: "Installation on your computer"
description: "Installation of Home Assistant on your computer."
date: 2014-12-18 22:57
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /getting-started/installation-python/
---
Once Python is 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 instructions](/docs/installation/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)
- [macOS](https://www.youtube.com/watch?v=hej6ipN86ls)
- [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0)

115
source/_docs/installation/raspberry-pi-all-in-one.markdown Normal file
View file

@ -0,0 +1,115 @@
---
layout: page
title: "Raspberry Pi All-In-One Installer"
date: 2016-05-12 01:39
comments: false
sharing: true
footer: true
redirect_from: /getting-started/installation-raspberry-pi-all-in-one/
---
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 -`.

77
source/_docs/installation/raspberry-pi.markdown Normal file
View file

@ -0,0 +1,77 @@
---
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
redirect_from: /getting-started/installation-raspberry-pi/
---
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](/docs/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).

228
source/_docs/installation/synology.markdown Normal file
View file

@ -0,0 +1,228 @@
---
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
redirect_from: /getting-started/installation-synology/
---
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
```

77
source/_docs/installation/troubleshooting.markdown Normal file
View file

@ -0,0 +1,77 @@
---
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
redirect_from: /getting-started/troubleshooting/
---
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 macOS machines may also have issues with this.
To fix this you will need to open your machine's firewall for TCP traffic to 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)
- [macOS 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"

49
source/_docs/installation/updating.markdown Normal file
View file

@ -0,0 +1,49 @@
---
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
redirect_from: /getting-started/hassbian-upgrading/
---
<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](/docs/hassbian/common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/#upgrading), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/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](/docs/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](/docs/hassbian/installation/), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv).
</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
```

89
source/_docs/installation/vagrant.markdown Normal file
View file

@ -0,0 +1,89 @@
---
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
redirect_from: /getting-started/installation-vagrant/
---
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 [Configuration section](/docs/configuration/) in the docmentation 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`

133
source/_docs/installation/virtualenv.markdown Normal file
View file

@ -0,0 +1,133 @@
---
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
redirect_from: /getting-started/installation-virtualenv/
---
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/_docs/mqtt.markdown Normal file
View file

@ -0,0 +1,33 @@
---
layout: page
title: "MQTT"
description: "Details about the MQTT support of Home Assistant."
date: 2017-02-15 08:00
sidebar: true
comments: false
sharing: true
footer: true
---
MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/docs/mqtt/broker#embedded-broker):
```yaml
# Example configuration.yaml entry
mqtt:
```
For other setup methods, please refer to the [MQTT broker](/docs/mqtt/broker) documentation.
## {% linkable_title Additional features %}
- [Certificate](/docs/mqtt/certificate/)
- [Discovery](/docs/mqtt/discovery/)
- [Publish service](/docs/mqtt/service/)
- [Birth and last will messages](/docs/mqtt/birth_will/)
- [Testing your setup](/docs/mqtt/testing/)
- [Logging](/docs/mqtt/logging/)
- [Processing JSON](/docs/mqtt/processing_json/)
See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component.

40
source/_docs/mqtt/birth_will.markdown Normal file
View file

@ -0,0 +1,40 @@
---
layout: page
title: "MQTT Birth and Last will"
description: "Instructions how to setup MQTT birth and last will messages within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
---
MQTT support so-called Birth and Last Will and Testament (LWT) messages. The former is used to sned a message after the service has started. the latter is here to notify other clients about an ungracefully disconnected client or alike.
To integrate MQTT Birth and Last Will messages into Home Assistant, add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
mqtt:
birth_message:
topic: 'hass/status'
payload: 'online'
will_message:
topic: 'hass/status'
payload: 'offline'
```
Configuration variables:
- **birth_message** (*Optional*):
- **topic** (*Required*): The MQTT topic to publish the message.
- **payload** (*Required*): The message content.
- **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
- **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.
- **will_message** (*Optional*):
- **topic** (*Required*): The MQTT topic to publish the message.
- **payload** (*Required*): The message content.
- **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
- **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.

126
source/_docs/mqtt/broker.markdown Normal file
View file

@ -0,0 +1,126 @@
---
layout: page
title: "MQTT Brokers"
description: "Instructions how to setup MQTT brokers for Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
redirect_from: /components/mqtt/#picking-a-broker
---
The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy.
### {% linkable_title Embedded broker %}
Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Assistant connects to it. Embedded broker default configuration:
| Setting | Value |
| ------- | ----- |
| Host | localhost
| Port | 1883
| Protocol | 3.1.1
| User | homeassistant
| Password | Your API [password](/components/http/)
| Websocket port | 8080
```yaml
# Example configuration.yaml entry
mqtt:
```
<p class='note'>
This broker does not currently work with OwnTracks because of a protocol version issue.
</p>
If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration.
```yaml
# Example configuration.yaml entry
mqtt:
embedded:
# Your HBMQTT config here. Example at:
# http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration
```
### {% linkable_title Run your own %}
This is the most private option but requires a bit more work. There are multiple free and open-source brokers to pick from: eg. [Mosquitto](http://mosquitto.org/), [EMQ](http://emqtt.io/), or [Mosca](http://www.mosca.io/).
```yaml
# Example configuration.yaml entry
mqtt:
broker: 192.168.1.100
port: 1883
client_id: home-assistant-1
keepalive: 60
username: USERNAME
password: PASSWORD
protocol: 3.1
```
Configuration variables:
- **broker** (*Optional*): The IP address or hostname of your MQTT broker, e.g. 192.168.1.32.
- **port** (*Optional*): The network port to connect to. Default is 1883.
- **client_id** (*Optional*): The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one.
- **keepalive** (*Optional*): The time in seconds between sending keep alive messages for this client. Default is 60.
- **username** (*Optional*): The username to use with your MQTT broker.
- **password** (*Optional*): The corresponding password for the username to use with your MQTT broker.
- **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.1.
<p class='note warning'>
There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue.
</p>
<p class='note'>
If you are running a mosquitto instance on a different server with proper SSL encryption using a service like letsencrypt you may have to set the certificate to the operating systems own `.crt` certificates file. In the instance of ubuntu this would be `certificate: /etc/ssl/certs/ca-certificates.crt`
</p>
### {% linkable_title Public broker %}
The Mosquitto project runs a [public broker](http://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices or controlling your home.
```yaml
mqtt:
broker: test.mosquitto.org
port: 1883 or 8883
# Optional, replace port 1883 with following if you want encryption
# (doesn't really matter because broker is public)
port: 8883
# Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt
certificate: /home/paulus/downloads/mosquitto.org.crt
```
### {% linkable_title CloudMQTT %}
[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free for up to 10 connected devices. This is enough to get started with for example [OwnTracks](/components/device_tracker.owntracks/) and give you a taste of what is possible.
<p class='note'>
Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks.
</p>
1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed)
2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create)
(Cute Cat is the free plan)
3. From the control panel, click on the _Details_ button.
4. Create unique users for Home Assistant and each phone to connect<br>(CloudMQTT does not allow two connections from the same user)
1. Under manage users, fill in username, password and click add
2. Under ACLs, select user, topic `#`, check 'read access' and 'write access'
5. Copy the instance info to your configuration.yaml:
```yaml
mqtt:
broker: CLOUTMQTT_SERVER
port: CLOUDMQTT_PORT
username: CLOUDMQTT_USER
password: CLOUDMQTT_PASSWORD
```
<p class='note'>
Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20000-30000).
</p>

28
source/_docs/mqtt/certificate.markdown Normal file
View file

@ -0,0 +1,28 @@
---
layout: page
title: "MQTT Certificate"
description: "Instructions how to setup MQTT with a certificate in Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
---
Using certificates will give you an additional layer of security for your MQTT communication.
To integrate MQTT with certificate into Home Assistant, add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
mqtt:
certificate: /home/paulus/dev/addtrustexternalcaroot.crt
```
Configuration variables:
- **certificate** (*Optional*): The certificate authority certificate file that is to be treated as trusted by this client. This file should contain the root certificate of the certificate authority that signed your broker's certificate, but may contain multiple certificates. Example: `/home/user/identrust-root.pem`
- **client_key** (*Optional*): Client key, eg. `/home/user/owntracks/cookie.key`.
- **client_cert** (*Optional*): Client certificate, eg. `/home/user/owntracks/cookie.crt`.

59
source/_docs/mqtt/discovery.markdown Normal file
View file

@ -0,0 +1,59 @@
---
layout: page
title: "MQTT Discovery"
description: "Instructions how to setup MQTT Discovery within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
redirect_from: /components/mqtt/#discovery
---
The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment.
To enable MQTT discovery, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
mqtt:
discovery: true
discovery_prefix: homeassistant
```
Configuration variables:
- **discovery** (*Optional*): If the MQTT discovery should be enabled or not. Defaults to `False`.
- **discovery_prefix** (*Optional*): The prefix for the discovery topic. Defaults to `homeassistant`.
The discovery topic need to follow a specific format:
```text
<discovery_prefix>/<component>/<object_id>/<>
```
- `<component>`: One of the supported components, eg. `binary_sensor`.
- `<object_id>`: The ID of the device. This will become the `entity_id` in Home Assistant.
- `<config>`: The topic `config` or `state` which defines the current action.
The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values.
### {% linkable_title Example %}
A motion detection device which can be represented by a [binary sensor](/components/binary_sensor.mqtt/) for your garden would sent its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the State topic will update the state in Home Assistant.
- Configuration topic: `homeassistant/binary_sensor/garden/config`
- State topic: `homeassistant/binary_sensor/garden/state`
- Payload: `{"name": "garden", "sensor_class": "motion"}`
To create a new sensor manually. For more details please refer to the [MQTT testing section](/component/mqtt_testing).
```bash
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "sensor_class": "motion"}'
```
Update the state.
```bash
$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON
```

23
source/_docs/mqtt/logging.markdown Normal file
View file

@ -0,0 +1,23 @@
---
layout: page
title: "MQTT Logging"
description: "Instructions how to setup MQTT Logging within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
redirect_from: /components/mqtt/#logging
---
The [logger](/components/logger/) component allow the logging of received MQTT messages.
```yaml
# Example configuration.yaml entry
logger:
default: warning
logs:
homeassistant.components.device_tracker.mqtt: debug
```

37
source/_docs/mqtt/processing_json.markdown Normal file
View file

@ -0,0 +1,37 @@
---
layout: page
title: "Processing JSON"
description: "Instructions how to process the MQTT payload."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
redirect_from: /components/mqtt/#processing-json
---
The MQTT [switch](/components/switch.mqtt/) and [sensor](/components/sensor.mqtt/) platforms support processing JSON over MQTT messages and parsing them using JSONPath. JSONPath allows you to specify where in the JSON the value resides that you want to use. The following examples will always return the value `100`.
| JSONPath query | JSON |
| -------------- | ---- |
| `somekey` | `{ 'somekey': 100 }`
| `somekey[0]` | `{ 'somekey': [100] }`
| `somekey[0].value` | `{ 'somekey': [ { value: 100 } ] }`
To use this, add the following key to your `configuration.yaml`:
```yaml
switch:
platform: mqtt
state_format: 'json:somekey[0].value'
```
It is also possible to extract JSON values by using a value template:
```yaml
switch:
platform: mqtt
value_template: '{% raw %}{{ value_json.somekey[0].value }}{% endraw %}'
```
More information about the full JSONPath syntax can be found [in their documentation](https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax).

29
source/_docs/mqtt/service.markdown Normal file
View file

@ -0,0 +1,29 @@
---
layout: page
title: "MQTT Publish service"
description: "Instructions how to setup the MQTT Publish service within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: mqtt.png
redirect_from: /components/mqtt/#publish-service
---
The MQTT component will register the service `publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload.
```json
{
"topic": "home-assistant/light/1/command",
"payload": "on"
}
```
```json
{
"topic": "home-assistant/light/1/state",
"payload_template": "{% raw %}{{ states('device_tracker.paulus') }}{% endraw %}"
}
```

Some files were not shown because too many files have changed in this diff Show more