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

Re-organisation Documentation and Getting started (#2055)

Browse source 
* Split MQTT documentation

* Add more details

* Move content to /docs

* Enable sidebar

* Move content to /docs

* Enable sidebar

* Move content

* Update links

* Remove wizard stuff

* Enable sidebar

* Minor changes

* Move MQTT parts to /docs

* update links

* Update links and sync content

* Fix link

* Enable sidebar

* Remove navigation

* Remove navigation and other minor updates

* Update links

* Add overview page

* Make title linkable

* Update

* Plit content

* Update links

* Rearrange content

* New getting-started section

* Add icons for docs

* Update for new structure

* Update for new structure

* Add docs navigation

* Add docs overview page

* Remove ecosystem navigation

* Add docs and remove other collections

* Move ecosystem to docs

* Remove duplicate files

* Re-add ecosystem overview

* Move to ecosystem

* Fix permission

* Update navigation

* Remove collection

* Move overview to right folder

* Move mqtt to upper level

* Move notebook to ecosystem

* Remove un-used files

* Add one more rectangle for iOS

* Move two parts back from docs and rename Run step

* Remove colon

* update getting-started section

* Add redirect

* Update

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

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";
```