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:
Paulus Schoutsen 2018-03-23 14:07:56 -07:00
commit 772fb32af9
791 changed files with 1385 additions and 1251 deletions
Download patch file Download diff file Expand all files Collapse all files

2
source/_docs/asterisk_mbox.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Asterisk Voicemail Server Installation"
description: "Instructions how to integrate your existing Asterisk voicemail within Home Assistant."
description: "Instructions on how to integrate your existing Asterisk voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false

6
source/_docs/automation.markdown
View file

@ -47,14 +47,12 @@ State changes can be used as the source of triggers and the current state can be
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.
<p class='note'>
As of version 0.42 you have to set an initial state in your automations in order for Home Assistant to restore them upon restart.
You have to set an initial state in your automations in order for Home Assistant to enable them upon restart.
```text
automation:
- alias: Automation Name
initial_state: True
trigger:
...
```
</p>

1
source/_docs/automation/condition.markdown
View file

@ -17,6 +17,7 @@ The available conditions for an automation are the same as for the script syntax
Example of using condition:
```yaml
automation:
- alias: 'Enciende Despacho'
trigger:
platform: state

16
source/_docs/automation/editor.markdown
View file

@ -9,7 +9,7 @@ sharing: true
footer: true
---
In Home Assistant 0.45 we introduced the first version of our automation editor. If you just created a new configuration with Home Assistant then you're all set! Go to the UI and enjoy.
In Home Assistant 0.45 we introduced the first version of our automation editor. If you just created a new configuration with Home Assistant, then you're all set! Go to the UI and enjoy.
From the UI choose **Configuration** which is located in the sidebar, then click on **Automation** to go to the automation editor. Press the **+** sign in the lower right corner to get started. This example is based on the manual steps described in the [Getting started section](/getting-started/automation/) for a [`random` sensor](/components/sensor.random/).
@ -19,7 +19,7 @@ Choose a meaningful name for your automation rules.
<img src='{{site_root}}/images/docs/automation-editor/new-automation.png' />
</p>
If the value of the sensor is greater than 10 then the automation rule should apply.
If the value of the sensor is greater than 10, then the automation rule should apply.
<p class='img'>
<img src='{{site_root}}/images/docs/automation-editor/new-trigger.png' />
@ -39,18 +39,20 @@ As "Service Data" we want a simple text that is shown as part of the notificatio
}
```
Don't forget to save your new automation rule. In order for your saved automation rule to come into effect you will need to go to the **Configuration** page and click on **Reload Automation**.
Don't forget to save your new automation rule. For your saved automation rule to come into effect, you will need to go to the **Configuration** page and click on **Reload Automation**.
## {% linkable_title Updating your configuration to use the editor %}
First check that you have activated the configuration editor.
First, check that you have activated the configuration editor.
```yaml
# Activate the configuration editor
config:
```
The automation editor reads and writes to the file `automations.yaml` in your [configuration](/docs/configuration/) folder. Make sure that you have set up the automation component to read from it:
The automation editor reads and writes to the file `automations.yaml` in the root of your [configuration](/docs/configuration/) folder.
Currently, both the name of this file and its location are fixed.
Make sure that you have set up the automation component to read from it:
```yaml
# Configuration.yaml example
@ -65,7 +67,7 @@ automation old:
platform: ...
```
You can use the `automation:` and `automation old:` sections in the same time:
You can use the `automation:` and `automation old:` sections at the same time:
- `automation old:` to keep your manual designed automations
- `automation:` to save the automation created by the online editor
@ -77,7 +79,7 @@ automation old: !include_dir_merge_list automations
## {% linkable_title Migrating your automations to `automations.yaml` %}
If you want to migrate your old automations to use the editor, you'll have to copy them to `automations.yaml`. Make sure that `automations.yaml` remains a list! For each automation that you copy over you'll have to add an `id`. This can be any string as long as it's unique.
If you want to migrate your old automations to use the editor, you'll have to copy them to `automations.yaml`. Make sure that `automations.yaml` remains a list! For each automation that you copy over, you'll have to add an `id`. This can be any string as long as it's unique.
For example, the below automation will be triggered when the sun goes from below the horizon to above the horizon. Then, if the temperature is between 17 and 25 degrees, a light will be turned on.

9
source/_docs/automation/examples.markdown
View file

@ -38,6 +38,7 @@ automation:
after: '16:00:00'
before: '23:00:00'
action:
# With a single service call, we don't need a '-' before service - though you can if you want to
service: homeassistant.turn_on
entity_id: group.living_room
@ -76,9 +77,9 @@ automation:
event_data:
entity_id: binary_sensor.cube_158d000103a3de
action:
- service_template: notify.pushover
data_template:
title: "Cube event detected"
message: "Cube has triggered this event: {{ trigger.event }}"
service_template: notify.pushover
data_template:
title: "Cube event detected"
message: "Cube has triggered this event: {{ trigger.event }}"
```
{% endraw %}

5
source/_docs/automation/trigger.markdown
View file

@ -78,7 +78,8 @@ automation:
<p class='note'>
Listing above and below together means the numeric_state has to be between the two values.
In the example above, a numeric_state that is 17.1-24.9 would fire this trigger.
In the example above, a numeric_state that goes to 17.1-24.9 (from 17 or below, or 25 or above)
would fire this trigger.
</p>
### {% linkable_title State trigger %}
@ -182,7 +183,7 @@ automation 3:
### {% 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/).
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. This includes [GPS Logger](/components/device_tracker.gpslogger/), the [OwnTracks platform](/components/device_tracker.owntracks/), and the [iCloud platform](/components/device_tracker.icloud/).
```yaml
automation:

2
source/_docs/autostart.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart Home Assistant"
description: "Instructions how to setup Home Assistant to launch on start."
description: "Instructions on how to setup Home Assistant to launch on start."
date: 2015-9-1 22:57
sidebar: true
comments: false

2
source/_docs/autostart/macos.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart on macOS"
description: "Instructions how to setup Home Assistant to launch on Apple macOS."
description: "Instructions on how to setup Home Assistant to launch on Apple macOS."
date: 2015-9-1 22:57
sidebar: true
comments: false

2
source/_docs/autostart/synology.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart on Synology NAS boot"
description: "Instructions how to setup Home Assistant to launch on boot on Synology NAS."
description: "Instructions on how to setup Home Assistant to launch on boot on Synology NAS."
date: 2015-9-1 22:57
sidebar: true
comments: false

2
source/_docs/autostart/systemd.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart using systemd"
description: "Instructions how to setup Home Assistant to launch on boot using systemd."
description: "Instructions on how to setup Home Assistant to launch on boot using systemd."
date: 2015-9-1 22:57
sidebar: true
comments: false

2
source/_docs/autostart/upstart.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Autostart using Upstart"
description: "Instructions how to setup Home Assistant to launch on boot using Upstart."
description: "Instructions on how to setup Home Assistant to launch on boot using Upstart."
date: 2015-9-1 22:57
sidebar: true
comments: false

2
source/_docs/configuration/group_visibility.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Group Visibility"
description: "Instructions how to change group visibility using automations."
description: "Instructions on how to change group visibility using automations."
date: 2016-10-29 13:00
sidebar: true
comments: false

2
source/_docs/configuration/packages.markdown
View file

@ -63,7 +63,7 @@ light:
There are some rules for packages that will be merged:
1. Component names may only use the basic form (e.g. `switch`, but not `switch 1` or `switch aa`).
1. Component names may only use the basic form (e.g., `switch`, but not `switch 1` or `switch aa`).
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.

2
source/_docs/configuration/securing.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Securing"
description: "Instructions how to secure your Home Assistant installation."
description: "Instructions on how to secure your Home Assistant installation."
date: 2016-10-06 06:00
sidebar: true
comments: false

2
source/_docs/configuration/templating.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Templating"
description: "Instructions how to use the templating feature of Home Assistant."
description: "Instructions on how to use the templating feature of Home Assistant."
date: 2015-12-12 12:00
sidebar: true
comments: false

54
source/_docs/ecosystem/appdaemon/api.markdown
View file

@ -39,7 +39,7 @@ There are several circumstances under which `initialize()` might be called:
- Following a change in the status of Daylight Savings Time
- Following a restart of Home Assistant
In every case, the App is responsible for recreating any state it might need as if it were the first time it was ever started. If `initialize()` is called, the app can safely assume that it is either being loaded for the first time, or that all callbacks and timers have been canceled. In either case, the APP will need to recreate them. Depending upon the application it may be desirable for the App to establish state such as whether or not a particular light is on, within the `initialize()` function to ensure that everything is as expected or to make immediate remedial action (e.g. turn off a light that might have been left on by mistake when the app was restarted).
In every case, the App is responsible for recreating any state it might need as if it were the first time it was ever started. If `initialize()` is called, the app can safely assume that it is either being loaded for the first time, or that all callbacks and timers have been canceled. In either case, the APP will need to recreate them. Depending upon the application it may be desirable for the App to establish state such as whether or not a particular light is on, within the `initialize()` function to ensure that everything is as expected or to make immediate remedial action (e.g., turn off a light that might have been left on by mistake when the app was restarted).
After the `initialize()` function is in place, the rest of the app consists of functions that are called by the various callback mechanisms, and any additional functions the user wants to add as part of the program logic. Apps are able to subscribe to 2 main classes of events:
@ -150,7 +150,7 @@ light = light.garage
## {% linkable_title Callback Constraints %}
Callback constraints are a feature of AppDaemon that removes the need for repetition of some common coding checks. Many Apps will wish to process their callbacks only when certain conditions are met, e.g. someone is home, and it's after sunset. These kinds of conditions crop up a lot, and use of callback constraints can significantly simplify the logic required within callbacks.
Callback constraints are a feature of AppDaemon that removes the need for repetition of some common coding checks. Many Apps will wish to process their callbacks only when certain conditions are met, e.g., someone is home, and it's after sunset. These kinds of conditions crop up a lot, and use of callback constraints can significantly simplify the logic required within callbacks.
Put simply, callback constraints are one or more conditions on callback execution that can be applied to an individual App. An App's callbacks will only be executed if all of the constraints are met. If a constraint is absent it will not be checked for.
@ -194,7 +194,7 @@ constrain_input_boolean = input_boolean.enable_motion_detection,off
```
### {% linkable_title input_select %}
The input_select constraint prevents callbacks unless the specified input_select is set to one or more of the nominated (comma separated) values. This is useful to allow certain Apps to be turned on and off according to some flag, e.g. a house mode flag.
The input_select constraint prevents callbacks unless the specified input_select is set to one or more of the nominated (comma separated) values. This is useful to allow certain Apps to be turned on and off according to some flag, e.g., a house mode flag.
```ini
# Single value
@ -272,7 +272,7 @@ Any other attributes such as brightness for a lamp will only be present if the e
Also bear in mind that some attributes such as brightness for a light, will not be present when the light is off.
In most cases, the attribute `state` has the most important value in it, e.g. for a light or switch this will be `on` or `off`, for a sensor it will be the value of that sensor. Many of the AppDaemon API calls and callbacks will implicitly return the value of state unless told to do otherwise.
In most cases, the attribute `state` has the most important value in it, e.g., for a light or switch this will be `on` or `off`, for a sensor it will be the value of that sensor. Many of the AppDaemon API calls and callbacks will implicitly return the value of state unless told to do otherwise.
### {% linkable_title get_state() %}
@ -294,9 +294,9 @@ All parameters are optional, and if `get_state()` is called with no parameters i
##### {% linkable_title entity %}
This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `get_state()` will return a dictionary of all devices of that type, indexed by the entity_id, containing all the state for each entity.
This is the name of an entity or device type. If just a device type is provided, e.g., `light` or `binary_sensor`, `get_state()` will return a dictionary of all devices of that type, indexed by the entity_id, containing all the state for each entity.
If a fully qualified `entity_id` is provided, `get_state()` will return the state attribute for that entity, e.g. `on` or `off` for a light.
If a fully qualified `entity_id` is provided, `get_state()` will return the state attribute for that entity, e.g., `on` or `off` for a light.
##### {% linkable_title attribute %}
@ -345,11 +345,11 @@ set_state(entity_id, **kwargs)
##### {% linkable_title entity_id %}
Entity id for which the state is to be set, e.g. `light.office_1`.
Entity id for which the state is to be set, e.g., `light.office_1`.
##### {% linkable_title values %}
A list of keyword values to be changed or added to the entities state. e.g. `state = "off"`. Note that any optional attributes such as colors for bulbs etc, need to reside in a dictionary called `attributes`; see the example.
A list of keyword values to be changed or added to the entities state. e.g., `state = "off"`. Note that any optional attributes such as colors for bulbs etc, need to reside in a dictionary called `attributes`; see the example.
#### {% linkable_title Examples %}
@ -461,7 +461,7 @@ handle = listen_state(callback, entity = None, **kwargs)
#### {% linkable_title Returns %}
A unique identifier that can be used to cancel the callback if required. Since variables created within object methods are local to the function they are created in, and in all likelihood the cancellation will be invoked later in a different function, it is recommended that handles are stored in the object namespace, e.g. `self.handle`.
A unique identifier that can be used to cancel the callback if required. Since variables created within object methods are local to the function they are created in, and in all likelihood the cancellation will be invoked later in a different function, it is recommended that handles are stored in the object namespace, e.g., `self.handle`.
#### {% linkable_title Parameters %}
@ -473,9 +473,9 @@ Function to be invoked when the requested state change occurs. It must conform t
##### {% linkable_title entity %}
This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `listen_state()` will subscribe to state changes of all devices of that type. If a fully qualified `entity_id` is provided, `listen_state()` will listen for state changes for just that entity.
This is the name of an entity or device type. If just a device type is provided, e.g., `light` or `binary_sensor`, `listen_state()` will subscribe to state changes of all devices of that type. If a fully qualified `entity_id` is provided, `listen_state()` will listen for state changes for just that entity.
When called, AppDaemon will supply the callback function, in old and new, with the state attribute for that entity, e.g. `on` or `off` for a light.
When called, AppDaemon will supply the callback function, in old and new, with the state attribute for that entity, e.g., `on` or `off` for a light.
##### {% linkable_title attribute (optional) %}
@ -949,11 +949,11 @@ All of the scheduler calls above support 2 additional optional arguments, `rando
For example:
```python
# Run a callback in 2 minutes minus a random number of seconds between 0 and 60, e.g. run between 60 and 120 seconds from now
# Run a callback in 2 minutes minus a random number of seconds between 0 and 60, e.g., run between 60 and 120 seconds from now
self.handle = self.run_in(callback, 120, random_start = -60, **kwargs)
# Run a callback in 2 minutes plus a random number of seconds between 0 and 60, e.g. run between 120 and 180 seconds from now
# Run a callback in 2 minutes plus a random number of seconds between 0 and 60, e.g., run between 120 and 180 seconds from now
self.handle = self.run_in(callback, 120, random_end = 60, **kwargs)
# Run a callback in 2 minutes plus or minus a random number of seconds between 0 and 60, e.g. run between 60 and 180 seconds from now
# Run a callback in 2 minutes plus or minus a random number of seconds between 0 and 60, e.g., run between 60 and 180 seconds from now
self.handle = self.run_in(callback, 120, random_start = -60, random_end = 60, **kwargs)
```
@ -1150,11 +1150,11 @@ None
##### {% linkable_title service %}
The service name, e.g. `light.turn_on`.
The service name, e.g., `light.turn_on`.
##### {% linkable_title \*\*kwargs %}
Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g. `entity_id = light.office_1`. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an `entity_id` however, so use of the above example is very common with this call.
Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g., `entity_id = light.office_1`. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an `entity_id` however, so use of the above example is very common with this call.
#### {% linkable_title Examples %}
@ -1187,7 +1187,7 @@ None
##### {% linkable_title entity_id %}
Fully qualified entity_id of the thing to be turned on, e.g. `light.office_lamp` or ```scene.downstairs_on```
Fully qualified entity_id of the thing to be turned on, e.g., `light.office_lamp` or ```scene.downstairs_on```
##### {% linkable_title \*\*kwargs %}
@ -1219,7 +1219,7 @@ None
##### {% linkable_title entity_id %}
Fully qualified entity_id of the thing to be turned off, e.g. `light.office_lamp` or `scene.downstairs_on`.
Fully qualified entity_id of the thing to be turned off, e.g., `light.office_lamp` or `scene.downstairs_on`.
#### {% linkable_title Examples %}
@ -1246,7 +1246,7 @@ None
##### {% linkable_title entity_id %}
Fully qualified entity_id of the thing to be toggled, e.g. `light.office_lamp` or `scene.downstairs_on`.
Fully qualified entity_id of the thing to be toggled, e.g., `light.office_lamp` or `scene.downstairs_on`.
#### {% linkable_title Examples %}
@ -1273,7 +1273,7 @@ None
##### {% linkable_title entity_id %}
Fully qualified entity_id of the input_number to be changed, e.g. `input_number.alarm_hour`.
Fully qualified entity_id of the input_number to be changed, e.g., `input_number.alarm_hour`.
##### {% linkable_title value %}
@ -1303,7 +1303,7 @@ None
##### {% linkable_title entity_id %}
Fully qualified entity_id of the input_select to be changed, e.g. `input_select.mode`.
Fully qualified entity_id of the input_select to be changed, e.g., `input_select.mode`.
##### {% linkable_title value %}
@ -1385,7 +1385,7 @@ A standard Python object reference.
#### {% linkable_title event_name %}
Name of the event that was called, e.g. `call_service`.
Name of the event that was called, e.g., `call_service`.
#### {% linkable_title data %}
@ -1528,7 +1528,7 @@ def service(self, event_name, data):
#### {% linkable_title event_name %}
The name of the event that caused the callback, e.g. `"MODE_CHANGE"` or `call_service`.
The name of the event that caused the callback, e.g., `"MODE_CHANGE"` or `call_service`.
#### {% linkable_title data %}
@ -1617,7 +1617,7 @@ A string representing the location of the tracker.
##### {% linkable_title tracker_id %}
Fully qualified entity_id of the device tracker to query, e.g. `device_tracker.andrew`.
Fully qualified entity_id of the device tracker to query, e.g., `device_tracker.andrew`.
#### {% linkable_title Examples %}
@ -1871,7 +1871,7 @@ self.log("{} ({}) is {}".format(tracker, self.friendly_name(tracker), self.get_
### {% linkable_title split_entity() %}
`split_entity()` will take a fully qualified entity id of the form `light.hall_light` and split it into 2 values, the device and the entity, e.g. `light` and `hall_light`.
`split_entity()` will take a fully qualified entity id of the form `light.hall_light` and split it into 2 values, the device and the entity, e.g., `light` and `hall_light`.
#### {% linkable_title Synopsis %}
@ -1925,7 +1925,7 @@ MyApp.turn_light_on()
### {% linkable_title split_device_list() %}
`split_device_list()` will take a comma separated list of device types (or anything else for that matter) and return them as an iterable list. This is intended to assist in use cases where the App takes a list of entities from an argument, e.g. a list of sensors to monitor. If only one entry is provided, an iterable list will still be returned to avoid the need for special processing.
`split_device_list()` will take a comma separated list of device types (or anything else for that matter) and return them as an iterable list. This is intended to assist in use cases where the App takes a list of entities from an argument, e.g., a list of sensors to monitor. If only one entry is provided, an iterable list will still be returned to avoid the need for special processing.
#### {% linkable_title Synopsis %}
@ -1941,7 +1941,7 @@ A list of split devices with 1 or more entries.
```python
for sensor in self.split_device_list(self.args["sensors"]):
do something for each sensor, e.g. make a state subscription
do something for each sensor, e.g., make a state subscription
```

2
source/_docs/ecosystem/appdaemon/tutorial.markdown
View file

@ -29,7 +29,7 @@ So why `AppDaemon`? AppDaemon is not meant to replace Home Assistant Automations
- 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
- 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 its 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

2
source/_docs/ecosystem/backup/backup_dropbox.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Configuration Backup to Dropbox"
description: "Instructions how backup your Home Assistant configuration to Dropbox"
description: "Instructions on how backup your Home Assistant configuration to Dropbox"
date: 2017-04-24 18:00
sidebar: true
comments: false

4
source/_docs/ecosystem/backup/backup_github.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Configuration Backup to GitHub"
description: "Instructions how backup your Home Assistant configuration to GitHub"
description: "Instructions on how backup your Home Assistant configuration to GitHub"
date: 2017-01-05 18:00
sidebar: true
comments: false
@ -35,7 +35,7 @@ Some best practices to consider before putting your configuration on GitHub:
### {% linkable_title Step 1: Installing and Initializing Git %}
In order to put your configuration on GitHub, you must install the git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubunutu, or any Debian-based system):
In order to put your configuration on GitHub, you must install the git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubunutu, or any Debian-based system) *note: this isn't required in Hass.io, it's included as default so proceed to step 2*:
```bash
$ sudo apt-get update

2
source/_docs/ecosystem/backup/backup_usb.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Configuration Backup to USB drive"
description: "Instructions how backup your Home Assistant configuration to USB drive"
description: "Instructions on how backup your Home Assistant configuration to USB drive"
date: 2017-04-29 08:00
sidebar: true
comments: false

130
source/_docs/ecosystem/certificates/lets_encrypt.markdown
View file

@ -10,7 +10,7 @@ footer: true
---
<p class='note'>
If you are using Hass.io, do not use this guide. Instead, use the [DuckDNS add-on](/addons/duckdns/) to automatically maintain a subdomain including HTTPS certificates via Let's Encrypt.
If you are using Hass.io or Hassbian, do not use this guide. Instead, use the [DuckDNS add-on](/addons/duckdns/) for Hass.io or the [DuckDNS suite](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/duckdns.md) for Hassbian to automatically maintain a subdomain including HTTPS certificates via Let's Encrypt.
</p>
<p class=' note warning'>
@ -29,9 +29,9 @@ This guide was added by mf_social on 16/03/2017 and was valid at the time of wri
* If you are not using Home Assistant on a Debian/Raspian/Hassbian system you will be able to convert any of the terminology I use in to the correct syntax for your system.
* You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is innacurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols.
* Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides.
Steps we will take:
- 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
- 1 - Set your device to have a static IP address
- 2 - Set up port forwarding without TLS/SSL and test connection
@ -42,48 +42,48 @@ Steps we will take:
- 7 - Set up a sensor to monitor the expiry date of the certificate
- 8 - Set up an automatic renewal of the TLS/SSL certificate
- 9 - Set up an alert to warn us if something went wrong
### {% linkable_title 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding %}
An IP address is a bit like a phone number. When you access your Home Assistant instance you type something similar to 192.168.0.200:8123 in to your address bar of your browser. The bit before the colon is the IP address (in this case 192.168.0.200) and the bit after is the port number (in this case 8123). When you SSH in to the device running Home Assistant you will use the same IP address, and you will use port 22. You may not be aware that you are using port 22, but if you are using Putty look in the box next to where you type the IP address, you will see that it has already selected port 22 for you.
So, if an IP address is like a phone number, a port number is like an extension number. An analogy would be if you phone your local doctors on 192-1680-200 and the receptionist answers, you ask to speak to Dr. Smith and she will put you through to extension 8123, which is the phone Dr. Smith is sitting at. The doctors surgery is the device your Home Assistant is running on, Dr. Smith is your Home Assistant. Thusly, your Home Assistant instance is 'waiting for your call' on port 8123, at the device IP 192.168.0.200 .
Now, to speak to the outside world your connection goes through a router. Your router will have two IP addresses. One is the internal network number, most likely 192.168.0.1 in my example, and an external IP address that incoming traffic is sent to. In the example of calling the doctors, the external IP is your telephone number's area code.
So, when we want to connect to our Home Assistant instance from outside our network we will need to call the correct extension number, at the correct phone number, in the correct area code.
We will be looking for a system to run like this (in this example I will pretend our external IP is 12.12.12.12):
```text
Outside world -> 12.12.12.12:8123 -> your router -> 192.168.0.200:8123
```
Sounds simple? It really is except for two small, but easy to overcome, complications:
* IP addresses are often dynamically allocated, so they can change.
* Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go.
To get around the issue of changing IP addresses we must remember that there are two IP addresses affected. Your external one (which we will 'call' to get on to your network from the internet) and your internal one (192.168.0.200 in the example I am currently using).
So, we can use a static IP to ensure that whenever our device running Home Assistant connects to our router it always uses the same address. This way our internal IP never changes. This is covered in step 1 below.
We then have no control over our external IP, as our Service Provider will give us a new one at random intervals. To fix this we will use a service called DuckDNS which will give us a name for our connection (something like examplehome.duckdns.org) and behind the scenes will continue to update your external IP. So no matter how many times the IP address changes, typing examplehome.duckdns.org in to our browser will convert to the correct, up-to-date, IP address. This is covered in step 3 below.
To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 12:12:12:12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TSL/SSL certificate our incoming call will be requesting port 443 (because that is the SSL port, like the SSH port is always 22), but our port forwarding rule will forward this to our HA instance on port 8123. When this guide is completed we will run something like this:
```text
Outside world -> https://examplehome.duckdns.org -> 12.12.12.12:443 -> your router -> 192.168.0.200:8123
```
So, let's make it happen...
### {% linkable_title 1 - Set your device to have a static IP address %}
Whenever a device is connected to a network it has an IP address. This IP address is often dynamically assigned to the device on connection. This means there are occasions where the IP address you use to access Home Assistant, or SSH in to the device running Home Assistant, may change. Setting a static IP address means that the device will always be on the same address.
SSH in to your system running Home Assistant and login.
Type the following command to list your network interfaces:
```bash
$ ifconfig
```
@ -94,17 +94,17 @@ You will receive an output similar to the image below:
<img src='/images/screenshots/ip-set.jpg' />
Screenshot
</p>
Make a note of the interface name and the IP address you are currently on. In the picture it is the wireless connection that is highlighted, but with your setup it may be the wired one (eth0 or similar), make sure you get the correct information.
Then type the following command to open the text file that controls your network connection:
```bash
```bash
$ sudo nano /etc/dhcpcd.conf
```
At the bottom of the file add the following lines:
```text
interface wlan0 <----- or the interface you just wrote down.
@ -195,13 +195,17 @@ In the domains section pick a name for your subdomain, this can be anything you
The URL you will be using later to access your Home Assistant instance from outside will be the subdomain you picked, followed by duckdns.org . For our example we will say our URL is examplehome.duckdns.org
On the top left of duckdns.org select the install option. Then pick your operating system from the list. In our example we will use a Raspberry Pi. In the dropdown box select the URL you just created.
Set up Home Assistant to keep your DuckDNS URL and external IP address in sync. In your `configuration.yaml` file add the following:
Duckdns.org will now generate personalised instructions for you to follow so that your device can update their website every time your IP address changes. Carefully follow the instructions given on duckdns.org to set up your device.
```yaml
duckdns:
domain: examplehome
access_token: abcdefgh-1234-abcd-1234-abcdefgh
```
At the end of the instructions DuckDNS will suggest you set up port forwarding. No need, we have already done this in step 2.
The access token is available on your DuckDNS page. Restart Home Assistant after the change.
What you have now done is set up DuckDNS so that whenever you type examplehome.duckdns.org in to your browser it will convert that to your router's external IP address. Your external IP address will always be up to date because your device running Home Assistant will update DuckDNS every time it changes.
What you have now done is set up DuckDNS so that whenever you type examplehome.duckdns.org in to your browser it will convert that to your router's external IP address. Your external IP address will always be up to date because Homeassistant will update DuckDNS every time it changes.
Now type your new URL in to your address bar on your browser with port 8123 on the end:
@ -251,7 +255,7 @@ $ sudo adduser hass sudo
If you did not already log in as the user that currently runs Home Assistant, change to that user (usually `hass` or `homeassistant` - you may have used a command similar to this in the past):
```bash
$ sudo su -s /bin/bash hass
$ sudo su -s /bin/bash hass
```
Make sure you are in the home directory for the Home Assistant user:
@ -272,7 +276,7 @@ $ chmod a+x certbot-auto
You might need to stop Home Assistant before continuing with the next step. You can do this via the Web-UI or use the following command if you are running on Hassbian:
```text
$ sudo systemctl stop home-assistant@homeassistant.service
$ sudo systemctl stop home-assistant@homeassistant.service
```
You can restart Home Assistant after the next step using the same command and replacing `stop` with `start`.
@ -336,7 +340,7 @@ http:
ssl_key: /etc/letsencrypt/live/examplehome.duckdns.org/privkey.pem
base_url: examplehome.duckdns.org
```
You may wish to set up other options for the [http](https://home-assistant.io/components/http/) component at this point, these extra options are beyond the scope of this guide.
Save the changes to configuration.yaml. Restart Home Assistant.
@ -363,7 +367,7 @@ https://YOUR-HA-IP:8123
Some cases such as this are where your router does not allow 'loopback' or where there is a problem with incoming connections due to technical failure. In these cases you can still use your internal connection and safely ignore the warnings.
If you were previously using a webapp on your phone/tablet to access your Home Assistant you should delete the old one and create a new one with the new address. The old one will no longer work as it is not keyed to your new, secure URL. Instructions for creating your new webapp can be found here:
If you were previously using a webapp on your phone/tablet to access your Home Assistant you should delete the old one and create a new one with the new address. The old one will no longer work as it is not keyed to your new, secure URL. Instructions for creating your new webapp can be found here:
```text
https://home-assistant.io/docs/frontend/mobile/
@ -387,11 +391,11 @@ You are now part of one of two groups:
* If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard http challenge, as performed above.
* If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal.
Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8!
Let's Encrypt certificates only last for 90 days. When they have less than 30 days left they can be renewed. Renewal is a simple process.
Move on to step 7 to see how to monitor your certificates expiry date, and be ready to renew your certificate when the time comes.
### {% linkable_title 7 - Set up a sensor to monitor the expiry date of the certificate %}
@ -402,9 +406,9 @@ Setting a sensor to read the number of days left on your TLS/SSL certificate bef
* You can set automations based on the number of days left
* You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry.
* If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually.
If you do not wish to set up a sensor you can skip straight to step 8 to learn how to update your certificates.
The sensor will rely on a command line program that needs to be installed on your device running Home Assistant. SSH in to the device and run the following commands:
```bash
@ -442,33 +446,33 @@ If you are a ONE-RULE person (from step 6), you can automatically renew your cer
If you are a TWO-RULE person (from step 6), you can automatically renew your certificate using a `http-01` challenge and port 80.
There are a number of options for automating the renewal process:
#### Option 1:
Your certificate can be renewed as a 'cron job' - cron jobs are background tasks run by the computer at specified intervals (and are totally independent of Home Assistant). Defining cron is outside of the scope of this guide but you will have had dealings with `crontab` when setting up DuckDNS in step 3
To set a cron job to run the script at regular intervals:
* SSH in to your device running Home Assistant.
* Change to your Home Assistant user (command similar to):
```bash
$ sudo su -s /bin/bash hass
```
* Open the crontab:
```bash
$ crontab -e
```
* If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
* If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"
```
@ -478,17 +482,17 @@ $ crontab -e
3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete.
* Save the file and exit
#### Option 2:
You can set an automation in Home Assistant to run the certbot renewal script.
Add the following sections to your configuration.yaml if you are a TWO-RULE person
```yaml
shell_command:
```yaml
shell_command:
renew_ssl: ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
automation:
- alias: 'Auto Renew SSL Cert'
trigger:
@ -502,34 +506,34 @@ If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/c
#### Option 3:
You can manually update the certificate when your certificate is less than 30 days to expiry.
To manually update:
To manually update:
* SSH in to your device running Home Assistant.
* Change to your Home Assistant user (command similar to):
```bash
$ su - s /bin/bash hass
```
* Change to your certbot folder
```bash
$ cd ~/certbot/
```
* Run the renewal command
```bash
$ ./certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
* If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
So, now were all set up. We have our secured, remotely accessible Home Assistant instance and we're on track for keeping our certificates up to date. But what if something goes wrong? What if the automation didn't fire? What if the cron job forgot to run? What if the dog ate my homework? Read on to set up an alert so you can be notified in plenty of time if you need to step in and sort out any failures.
### {% linkable_title 9 - Set up an alert to warn us if something went wrong. %}
We set up our automatic renewal of our certificates and whatever method we used the certificate should be renewed on or around 30 days before it expires. But what if a week later it still hasn't been? This alert will go off if the expiry time on the certificate gets down to 21 days. This will give you 3 weeks to fix the problem, get your new certificate installed and get another 90 days of secure Home Assistant connections in play.
In your `configuration.yaml` add the following automation, adding your preferred notification platform where appropriate:
@ -546,7 +550,7 @@ automation:
data:
message: 'Warning - SSL certificate expires in 21 days and has not been automatically renewed'
```
If you receive this warning notification, follow the steps for a manual update from step 8. Any error messages received at that point can be googled and resolved. If the manual update goes without a hitch there may be something wrong with your chosen method for automatic updates, and you can start troubleshooting from there.
So, that's it. We've taken a Home Assistant instance that was only reachable on the local network, made it accessible from the internet, secured it, and set up a system to ensure that it always stays secure. Well done, go and treat yourself to a cookie!

8
source/_docs/ecosystem/hass-configurator.markdown
View file

@ -47,7 +47,7 @@ There are no dependencies on Python modules that are not part of the standard li
### {% linkable_title Configuration %}
Near the top of the `configurator.py`-file you will find some global variables you can change to customize the configurator. If you are unfamiliar with Python: when setting variables of the type _string_, you have to write that within quotation marks. The default settings are fine for just checking out the configurator quickly. With more customized setups you should change some settings though.
To keep your settings across updates it is also possible to save settings in an external file. In that case copy [settings.conf](https://github.com/danielperna84/hass-configurator/blob/master/settings.conf) wherever you like and append the full path to the file to the command when starting the configurator. E.g. `sudo .configurator.py /home/homeassistant/.homeassistant/mysettings.conf`. This file is in JSON format. So make sure it has a valid syntax (you can set the editor to JSON to get syntax highlighting for the settings). The major difference to the settings in the py-file is, that `None` becomes `null`.
To keep your settings across updates it is also possible to save settings in an external file. In that case copy [settings.conf](https://github.com/danielperna84/hass-configurator/blob/master/settings.conf) wherever you like and append the full path to the file to the command when starting the configurator. e.g., `sudo .configurator.py /home/homeassistant/.homeassistant/mysettings.conf`. This file is in JSON format. So make sure it has a valid syntax (you can set the editor to JSON to get syntax highlighting for the settings). The major difference to the settings in the py-file is, that `None` becomes `null`.
#### LISTENIP (string)
The IP the service is listening on. By default it is binding to `0.0.0.0`, which is every interface on the system.
@ -66,11 +66,11 @@ Set credentials in the form of `"username:password"` if authentication should be
#### ALLOWED_NETWORKS (list)
Limit access to the configurator by adding allowed IP addresses / networks to the list, e.g `ALLOWED_NETWORKS = ["192.168.0.0/24", "172.16.47.23"]`
#### BANNED_IPS (list)
List of statically banned IP addresses, e.g. `BANNED_IPS = ["1.1.1.1", "2.2.2.2"]`
List of statically banned IP addresses, e.g., `BANNED_IPS = ["1.1.1.1", "2.2.2.2"]`
#### BANLIMIT (integer)
Ban IPs after `n` failed login attempts. Restart the service to reset banning. The default of `0` disables this feature. `CREDENTIALS` has to be set for this to work.
#### IGNORE_PATTERN (list)
Files and folders to ignore in the UI, e.g. `IGNORE_PATTERN = [".*", "*.log", "__pycache__"]`.
Files and folders to ignore in the UI, e.g., `IGNORE_PATTERN = [".*", "*.log", "__pycache__"]`.
#### DIRSFIRST (bool)
If set to `True`, directories will be displayed at the top of the filebrowser.
#### GIT (bool)
@ -81,7 +81,7 @@ __Note regarding `ALLOWED_NETWORKS`, `BANNED_IPS` and `BANLIMIT`__:
The way this is implemented works in the following order:
1. (Only if `CREDENTIALS` is set) Check credentials
- Failure: Retry `BANLIMIT` times, after that return error 420 (unless you try again without any authentication headers set, e.g. private tab of your browser)
- Failure: Retry `BANLIMIT` times, after that return error 420 (unless you try again without any authentication headers set, e.g., private tab of your browser)
- Success: Continue
2. Check if client IP address is in `BANNED_IPS`
- Yes: Return error 420

2
source/_docs/ecosystem/synology.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Synology"
description: "Instructions how to get Home Assistant up and running on Synology"
description: "Instructions on how to get Home Assistant up and running on Synology"
release_date: 2016-12-07 15:00:00 -0500
sidebar: true
comments: false

2
source/_docs/installation.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Installation of Home Assistant"
description: "Instructions how to install Home Assistant to launch on start."
description: "Instructions on how to install Home Assistant to launch on start."
date: 2017-02-15 08:00
sidebar: true
comments: false

2
source/_docs/installation/docker.markdown
View file

@ -51,7 +51,7 @@ The steps would be:
* Wait for some time until your NAS has pulled the image
* Move to the "Image"-section of the Docker-app
* Click on "Launch"
* Choose a container-name you want (e.g. "homeassistant")
* Choose a container-name you want (e.g., "homeassistant")
* Click on "Advanced Settings"
* Set "Enable auto-restart" if you like
* Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount point" has to be "/config", so that Home Assistant will use it for the configs and logs.

4
source/_docs/installation/hassbian.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Hassbian"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
description: "Instructions to flash the Home Assistant Hassbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -10,7 +10,7 @@ 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.
Hassbian is our customized operating system for the Raspberry Pi Zero, 2,3 and 3B+. It is one of the easiest ways of installing Home Assistant.
- [Install Hassbian][install]
- [Customize your installation][customize]

16
source/_docs/installation/hassbian/common-tasks.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Common tasks on Hassbian"
description: "Instructions how to do common tasks on Hassbian."
description: "Instructions on how to do common tasks on Hassbian."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -11,7 +11,7 @@ redirect_from: /docs/hassbian/common-tasks/
---
### {% linkable_title Login to the Raspberry Pi %}
To login to your Raspberry Pi running HASSbian you're 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].
To login to your Raspberry Pi running Hassbian you're 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.
@ -28,22 +28,22 @@ Optionally, starting with Windows 10 anniversary update, you can use the built-i
Log in as the `pi` account and execute the following commands:
```bash
$ sudo systemctl stop home-assistant@homeassistant.service
$ 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`.
To get the current state of the `homeassistant.service` replace `stop` with `status`.
### {% linkable_title Update Home Assistant %}
<p class='note'>
You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade home-assistant`
You can use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade homeassistant`
</p>
Log in as the `pi` account and execute the following commands:
```bash
$ sudo systemctl stop home-assistant@homeassistant.service
$ sudo systemctl stop home-assistant@homeassistant.service
$ sudo su -s /bin/bash homeassistant
$ source /srv/homeassistant/bin/activate
$ pip3 install --upgrade homeassistant
@ -53,12 +53,12 @@ $ sudo systemctl start home-assistant@homeassistant.service
This will in order do the following:
- Stop the Home Assistant service running on HASSbian
- 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.
- Start the Home Assistant service.
### {% linkable_title Manually launch Home Assistant %}
Log in as the `pi` account and execute the following commands:

44
source/_docs/installation/hassbian/customization.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Customization"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
description: "Instructions to flash the Home Assistant Hassbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -10,26 +10,34 @@ footer: true
redirect_from: /docs/hassbian/customization/
---
To allow you to customize your installation further, we have included a tool called `hassbian-config`. This tool comes with a set of packages that can easily be installed or upgraded for easier customization of your Home Assistant installation.
The tool is available by running `hassbian-config`.
To allow you to customize your installation further, we have included a tool called `hassbian-config`. This tool comes with a set of suites that can easily be installed or upgraded for easier customization of your Home Assistant installation.
The tool is available by running `hassbian-config`.
### Install scripts
To view the available packages run `hassbian-config show` and `sudo hassbian-config install PACKAGENAME`.
- Install Hue. Configures the Python executable to allow usage of low numbered ports for use with Emulated Hue component that's used with Amazon Echo, Google Home and Mycroft.ai.
- Install MariaDB. This script installs MariaDB and it's dependencies for use with the recorder component in Home Assistant. No database or database user is created during this setup and will need to be created manually.
- Install Mosquitto MQTT server. Installs the latest Mosquitto package and client tools from the Mosquitto projects official repository. Now includes websocket support.
- Install Libcec. Adds local [HDMI CEC support][cec]. *This scipt is currently brooken upstream since it currently doesn't build properly for Python >3.4*
- 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 Tradfri. Installs dependencies for using IKEA Trådfri.
- Install Duck DNS auto renewal. This script adds a cron job to auto update the WAN IP address for the defined domain. Before running this script you should already have an Duck DNS account. During the installation you will be asked to supply your domain name and the token for your account.
- Install a web terminal for easy access to ssh in any web browser. This script installs a web terminal called 'shellinabox' on your system that gives you SSH access in your web browser.
To view the available suites run `hassbian-config show` or have a look at the [hassbian-scripts repository][hassbian-repo].
These are some of the available suites:
- [AppDaemon](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/appdaemon.md)
- [Duck DNS](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/duckdns.md) _This can also be configured to generate Let's Encrypt SSL certificates_
- [Homebridge](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/homebridge.md)
- [Mosquitto](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/mosquitto.md)
- [Samba](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/samba.md)
- [Webterminal](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/webterminal.md)
- Various database engines.
- [MariaDB](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/mariadb.md)
- [PostgreSQL](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/postgresql.md)
- [MS SQL](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/mssql.md)
#### Upgrade scripts
To view the available packages run `hassbian-config show` and `sudo hassbian-config upgrade PACKAGENAME`.
- Upgrade your Home Assistant installation.
- Upgrade your HASSbian installation.
- Upgrade HASSbian-scripts.
- Upgrade HASSbian-scripts from dev branch.
To install any of them simply run `sudo hassbian-config install SUITE`.
### Upgrade scripts
To view the available suites run `hassbian-config show` or have a look at the [hassbian-scripts repository][hassbian-repo].
These are some of the available suites:
- [AppDaemon](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/appdaemon.md)
- [Hassbian](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/hassbian.md)
- [Home Assistant](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/homeassistant.md)
- [hassbian-config (hassbian-sctipts)](https://github.com/home-assistant/hassbian-scripts/blob/master/docs/hassbian_config.md)
To upgrade any of them simply run `sudo hassbian-config upgrade SUITE`.
For more information about this tool have a look at the [hassbian-scripts repository][hassbian-repo].

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

@ -1,7 +1,7 @@
---
layout: page
title: "Installing Hassbian"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
description: "Instructions to flash the Home Assistant Hassbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -10,22 +10,23 @@ footer: true
redirect_from: /docs/hassbian/installation/
---
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).
One of the easiest ways to install Home Assistant on your Raspberry Pi Zero, 2 ,3 and 3B+ 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 image][image-download]
2. Use [Etcher][etcher] to flash the image to your SD card
3. Ensure your Raspberry Pi has wired access to the internet for the entire process or configure your wireless network settings **before proceeding to step 4**.
4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.
3. Ensure your Raspberry Pi has wired access to the internet for the entire process or configure your [wireless network settings](#wireless-network) **before proceeding to step 4**.
4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 10 minutes.
<p class='note'>
Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/help/faqs/#powerReqs) with your Pi. Mobile chargers may not be suitable, since some are designed to only provide the full power with that manufacturer's handsets.
</p>
These instructions are also available as a [video](https://www.youtube.com/watch?v=iIz6XqDwHEk). Additional information is available in this [video](https://www.youtube.com/watch?v=tCGlQSsQ-Mc).
These instructions are also available as a [video](https://www.youtube.com/watch?v=iIz6XqDwHEk).
Additional information is available in this [video](https://www.youtube.com/watch?v=tCGlQSsQ-Mc).
After initial boot an installer will run in the background and takes around 15 minutes to complete, after it has finished, you will be prompted to login: `hassbian login:`. Installation is complete at this point. The default username is `pi` and the password is `raspberry`.
After initial boot an installer will run in the background, this will download and install the newest version of [hassbian-config](https://github.com/home-assistant/hassbian-scripts) and Home-Assistant, this takes around 10 minutes to complete, after it has finished, you will be prompted to login: `hassbian login:`. Installation is complete at this point. The default username is `pi` and the password is `raspberry`.
Open a browser on a device that's connected to the same WiFi network as your Raspberry Pi and point it to Home Assistant 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/`.
Open a browser on a device that's connected to the same network as your Raspberry Pi and point it to Home Assistant 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/`.
If you find that the web page is not reachable after 30 minutes or so, check that you have files in `/home/homeassistant/.homeassistant/`, if there are no files in this location then run the installer manually using this command: `sudo systemctl start install_homeassistant.service`.
@ -35,7 +36,7 @@ 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).
- SSH server is enabled.
- A tool called [`hassbian-config`](https://github.com/home-assistant/hassbian-scripts#hassbian-config-hassbian-config).
- A tool called [`hassbian-config`](https://github.com/home-assistant/hassbian-scripts#hassbian-scripts).
### {% linkable_title Wireless Network %}
@ -63,4 +64,3 @@ You may need to adjust the country code depending upon where you are. A list of
[etcher]: https://etcher.io/
[http://hassbian.local:8123]: http://hassbian.local:8123
[wifi-setup]: https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md

7
source/_docs/installation/hassbian/upgrading.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Upgrading Hassbian"
description: "Instructions how to upgrade Hassbian to the latest version."
description: "Instructions on how to upgrade Hassbian to the latest version."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -10,7 +10,7 @@ footer: true
redirect_from: /docs/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.
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
@ -18,10 +18,9 @@ $ sudo apt-get update
$ sudo apt-get -y upgrade
```
#### {% linkable_title Updating Home Assistant %}
<p class='note'>
You can also use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade home-assistant`
You can use `hassbian-config` to automate the process by running `sudo hassbian-config upgrade homeassistant`
</p>
To update the Home Assistant installation execute the following command as the `pi` user.

2
source/_docs/installation/synology.markdown
View file

@ -69,7 +69,7 @@ Create homeassistant config directory & switch to it
# chmod 755 /volume1/homeassistant
# cd /volume1/homeassistant
```
Hint: alternatively you can also create a "Shared Folder" via Synology WebUI (e.g. via "File Station") - this has the advantage that the folder is visible via "File Station".
Hint: alternatively you can also create a "Shared Folder" via Synology WebUI (e.g., via "File Station") - this has the advantage that the folder is visible via "File Station".
Create hass-daemon file using the following code (edit the variables in uppercase if necessary)

6
source/_docs/installation/updating.markdown
View file

@ -11,7 +11,7 @@ redirect_from: /getting-started/updating/
---
<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 [Hass.io](/hassio/), [HASSbian](/docs/hassbian/common-tasks/#update-home-assistant), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant).
The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [Hass.io](/hassio/), [Hassbian](/docs/installation/hassbian/common-tasks/#update-home-assistant), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant).
</p>
Check what's new in the latest version and potentially impacts your system in [Home Assistant release notes](https://github.com/home-assistant/home-assistant/releases). It is good practice to review these release notes and pay close attention to the **Breaking Changes** that are listed there. If you haven't done an update for a while, you should also check previous release notes as they can also contain relevant **Breaking Changes**. **Breaking Changes** may require configuration updates for your components. If you missed this and Home Assistant refuses to start, check `<config-dir>/home-assistant.log` for details about broken components.
@ -25,7 +25,7 @@ $ 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). Startup can take considerable amount of time (i.e. minutes) depending on your device. This is because all requirements are updated as well.
<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 [Hass.io](/hassio/), [HASSbian](/docs/hassbian/installation/), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv).
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 [Hass.io](/hassio/), [Hassbian](/docs/hassbian/installation/), [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.
@ -40,7 +40,7 @@ $ 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`.
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.

2
source/_docs/mqtt/birth_will.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Birth and Last will"
description: "Instructions how to setup MQTT birth and last will messages within Home Assistant."
description: "Instructions on how to setup MQTT birth and last will messages within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false

6
source/_docs/mqtt/broker.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Brokers"
description: "Instructions how to setup MQTT brokers for Home Assistant."
description: "Instructions on how to setup MQTT brokers for Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false
@ -62,7 +62,7 @@ mqtt:
{% configuration %}
broker:
required: false
description: The IP address or hostname of your MQTT broker, e.g. 192.168.1.32.
description: The IP address or hostname of your MQTT broker, e.g., 192.168.1.32.
type: string
port:
required: false
@ -109,7 +109,7 @@ If you get this error `AttributeError: module 'ssl' has no attribute 'PROTOCOL_T
</p>
<p class='note'>
If you are running a Mosquitto instance on the same server as Home Assistant then you must ensure that the Mosquitto service starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) then you should edit the file /etc/systemd/system/home-assistant@homeassistant.service as root (e.g. sudo nano /etc/systemd/system/home-assistant@homeassistant.service) and add the mosquitto service:
If you are running a Mosquitto instance on the same server as Home Assistant then you must ensure that the Mosquitto service starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) then you should edit the file /etc/systemd/system/home-assistant@homeassistant.service as root (e.g., sudo nano /etc/systemd/system/home-assistant@homeassistant.service) and add the mosquitto service:
```
[Unit]
Description=Home Assistant

2
source/_docs/mqtt/certificate.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Certificate"
description: "Instructions how to setup MQTT with a certificate in Home Assistant."
description: "Instructions on how to setup MQTT with a certificate in Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false

2
source/_docs/mqtt/discovery.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Discovery"
description: "Instructions how to setup MQTT Discovery within Home Assistant."
description: "Instructions on how to setup MQTT Discovery within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false

2
source/_docs/mqtt/logging.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Logging"
description: "Instructions how to setup MQTT Logging within Home Assistant."
description: "Instructions on how to setup MQTT Logging within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false

2
source/_docs/mqtt/processing_json.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Processing JSON"
description: "Instructions how to process the MQTT payload."
description: "Instructions on how to process the MQTT payload."
date: 2015-08-07 18:00
sidebar: true
comments: false

2
source/_docs/mqtt/service.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Publish service"
description: "Instructions how to setup the MQTT Publish service within Home Assistant."
description: "Instructions on how to setup the MQTT Publish service within Home Assistant."
date: 2015-08-07 18:00
sidebar: true
comments: false

2
source/_docs/mqtt/testing.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Testing"
description: "Instructions how to test your MQTT setup."
description: "Instructions on how to test your MQTT setup."
date: 2015-08-07 18:00
sidebar: true
comments: false

94
source/_docs/scripts.markdown
View file

@ -21,7 +21,8 @@ script:
sequence:
# This is written using the Script Syntax
- service: light.turn_on
entity_id: light.ceiling
data:
entity_id: light.ceiling
- service: notify.notify
data:
message: 'Turned on the ceiling light!'
@ -32,11 +33,11 @@ script:
The most important one is the action to call a service. This can be done in various ways. For all the different possibilities, have a look at the [service calls page].
```yaml
alias: Bedroom lights on
service: light.turn_on
data:
entity_id: group.bedroom
brightness: 100
- alias: Bedroom lights on
service: light.turn_on
data:
entity_id: group.bedroom
brightness: 100
```
### {% linkable_title Test a Condition %}
@ -44,9 +45,9 @@ data:
While executing a script you can add a condition to stop further execution. When a condition does not return `true`, the script will finish. There are many different conditions which are documented at the [conditions page].
```yaml
condition: state
entity_id: device_tracker.paulus
state: 'home'
- condition: state
entity_id: device_tracker.paulus
state: 'home'
```
### {% linkable_title Delay %}
@ -55,46 +56,53 @@ Delays are useful for temporarily suspending your script and start it at a later
```yaml
# Waits 1 hour
delay: 01:00
- delay: '01:00'
```
```yaml
# Waits 1 minute, 30 seconds
delay: 00:01:30
- delay: '00:01:30'
```
```yaml
# Waits 1 minute
delay:
# supports milliseconds, seconds, minutes, hours, days
minutes: 1
- delay:
# supports milliseconds, seconds, minutes, hours, days
minutes: 1
```
{% raw %}
```yaml
# Waits however many minutes input_number.minute_delay is set to
# Valid formats include HH:MM and HH:MM:SS
delay: {% raw %}'00:{{ states.input_number.minute_delay.state | int }}:00'{% endraw %}
- delay: "00:{{ states('input_number.minute_delay')|int }}:00"
```
{% endraw %}
### {% linkable_title Wait %}
Wait until some things are complete. We support at the moment `wait_template` for waiting until a condition is `true`, see also on [Template-Trigger](/docs/automation/trigger/#template-trigger). It is possible to set a timeout after which the script will abort its execution if the condition is not satisfied. Timeout has the same syntax as `delay`.
{% raw %}
```yaml
# wait until media player have stop the playing
wait_template: {% raw %}"{{ states.media_player.floor.state == 'stop' }}"{% endraw %}
- wait_template: "{{ is_state('media_player.floor', 'stop') }}"
```
{% endraw %}
{% raw %}
```yaml
# wait until a valve is < 10 or abort after 1 minutes.
wait_template: {% raw %}"{{ states.climate.kitchen.attributes.valve < 10 }}"{% endraw %}
timeout: 00:01:00
# wait until a valve is < 10 or abort after 1 minute.
- wait_template: "{{ states.climate.kitchen.attributes.valve|int < 10 }}"
timeout: '00:01:00'
```
{% endraw %}
When using `wait_template` within an automation `trigger.entity_id` is supported for `state`, `numeric_state` and `template` triggers, see also [Available-Trigger-Data](/docs/automation/templating/#available-trigger-data).
{% raw %}
```yaml
wait_template: "{{ is_state(trigger.entity_id, 'on') }}"
- wait_template: "{{ is_state('trigger.entity_id', 'on') }}"
```
{% endraw %}
@ -102,13 +110,13 @@ It is also possible to use dummy variables, e.g., in scripts, when using `wait_t
{% raw %}
```yaml
# Service call, e.g. from an automation.
service: script.do_something
data_template:
dummy: "{{ input_boolean.switch }}"
# Service call, e.g., from an automation.
- service: script.do_something
data_template:
dummy: input_boolean.switch
# Inside the script
wait_template: "{{ is_state(dummy, 'off') }}"
- wait_template: "{{ is_state(dummy, 'off') }}"
```
{% endraw %}
@ -117,12 +125,12 @@ wait_template: "{{ is_state(dummy, 'off') }}"
This action allows you to fire an event. Events can be used for many things. It could trigger an automation or indicate to another component that something is happening. For instance, in the below example it is used to create an entry in the logbook.
```yaml
event: LOGBOOK_ENTRY
event_data:
name: Paulus
message: is waking up
entity_id: device_tracker.paulus
domain: light
- event: LOGBOOK_ENTRY
event_data:
name: Paulus
message: is waking up
entity_id: device_tracker.paulus
domain: light
```
You can also use event_data_template to fire an event with custom data. This could be used to pass data to another script awaiting
@ -130,10 +138,10 @@ an event trigger.
{% raw %}
```yaml
event: MY_EVENT
event_data_template:
name: myEvent
customData: "{{ myCustomVariable }}"
- event: MY_EVENT
event_data_template:
name: myEvent
customData: "{{ myCustomVariable }}"
```
{% endraw %}
@ -145,13 +153,13 @@ The following automation shows how to raise a custom event called `event_light_s
```yaml
- alias: Fire Event
trigger:
platform: state
entity_id: switch.kitchen
to: 'on'
- platform: state
entity_id: switch.kitchen
to: 'on'
action:
event: event_light_state_changed
event_data:
state: "on"
- event: event_light_state_changed
event_data:
state: 'on'
```
{% endraw %}
@ -161,8 +169,8 @@ The following automation shows how to capture the custom event `event_light_stat
```yaml
- alias: Capture Event
trigger:
platform: event
event_type: event_light_state_changed
- platform: event
event_type: event_light_state_changed
action:
- service: notify.notify
data_template:

4
source/_docs/scripts/conditions.markdown
View file

@ -119,13 +119,13 @@ condition:
The sun condition can test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger][sun_trigger].
[sun_trigger]: /getting-started/automation-trigger/#sun-trigger
[sun_trigger]: /docs/automation/trigger/#sun-trigger
```yaml
condition:
condition: sun
after: sunset
# Optional offset value
# Optional offset value - in this case it must from -1 hours relative to sunset, or after
after_offset: "-1:00:00"
```

2
source/_docs/scripts/service-calls.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Service Calls"
description: "Instructions how to call services in Home Assistant."
description: "Instructions on how to call services in Home Assistant."
date: 2016-03-12 12:00 -0800
sidebar: true
comments: false

2
source/_docs/z-wave/installation.markdown
View file

@ -135,7 +135,7 @@ Or, if there is no result, try to find detailed USB connection info with:
$ dmesg | grep USB
```
If Home Assistant (`hass`) runs with another user (e.g. *homeassistant* on Hassbian) give access to the stick with:
If Home Assistant (`hass`) runs with another user (e.g., *homeassistant* on Hassbian) give access to the stick with:
```bash
$ sudo usermod -a -G dialout homeassistant

2
source/_docs/z-wave/services.markdown
View file

@ -29,7 +29,7 @@ The `zwave` component exposes multiple services to help maintain the network. Al
| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail. |
| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail. |
| reset_node_meters | Reset a node's meter values. Only works if the node supports this. |
| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g. `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g. `"value": 1`). |
| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g., `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g., `"value": 1`). |
| soft_reset | Tells the controller to do a "soft reset." This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command. |
| start_network | Starts the Z-Wave network. |
| stop_network | Stops the Z-Wave network. |