Add AppDaemon docs to ecosystem (#1589)

source/_ecosystem/appdaemon.markdown

@@ -0,0 +1,14 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant.

source/_ecosystem/appdaemon/configuration.markdown

@@ -0,0 +1,80 @@
+---
+layout: page
+title: "Configuration"
+description: "AppDaemon Configuration"
+release_date: 2016-11-27 08:00:00 -0500
+sidebar: true
+comments: false
+sharing: true
+footer: true
+regenerate: true
+hide_github_edit: true
+---
+
+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).
+
+## 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.

source/_ecosystem/appdaemon/example_apps.markdown

@@ -0,0 +1,14 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them.

source/_ecosystem/appdaemon/installation.markdown

@@ -0,0 +1,46 @@
+---
+layout: page
+title: "Installation"
+description: "AppDaemon Installation"
+release_date: 2016-11-27 08:00:00 -0500
+sidebar: true
+comments: false
+sharing: true
+footer: true
+regenerate: true
+hide_github_edit: true
+---
+
+Installation is either by pip3 or Docker.
+
+## 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
+```
+
+## 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)
+
+## Install Using PIP3
+
+Before running `AppDaemon` you will need to install the package:
+
+```bash
+$ sudo pip3 install .
+```

source/_ecosystem/appdaemon/operation.markdown

@@ -0,0 +1,14 @@
+---
+layout: page
+title: "Operation"
+description: "Operation"
+release_date: 2016-11-27 08:00:00 -0500
+sidebar: true
+comments: false
+sharing: true
+footer: true
+regenerate: true
+hide_github_edit: true
+---
+
+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.

source/_ecosystem/appdaemon/reboot.markdown

@@ -0,0 +1,14 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+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.

source/_ecosystem/appdaemon/running.markdown

@@ -0,0 +1,96 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+As configured, AppDaemon comes with a single HelloWorld App that will send a greeting to the logfile to show that everything is working correctly.
+
+## 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.
+
+## 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!
+```
+
+## 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. 

source/_ecosystem/appdaemon/tutorial.markdown

@@ -0,0 +1,130 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+## 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.
+
+## How it Works
+
+The best way to show what AppDaemon does is through a few simple examples.
+
+### 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!
+
+

source/_ecosystem/appdaemon/updating.markdown

@@ -0,0 +1,27 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+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.

source/_ecosystem/appdaemon/windows.markdown

@@ -0,0 +1,23 @@
+---
+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
+regenerate: true
+hide_github_edit: true
+---
+
+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.
+
+## 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.

source/_includes/asides/ecosystem_appdaemon_navigation.html

@@ -0,0 +1,19 @@
+<section class="aside-module grid__item one-whole lap-one-half">
+
+  <div class="section">
+    <h1 class="title delta">AppDaemon</h1>
+    <ul class="divided sidebar-menu">
+      <li>{% active_link /ecosystem/appdaemon/ General %}</li>
+      <li>{% active_link /ecosystem/appdaemon/installation/ Installation %}</li>
+      <li>{% active_link /ecosystem/appdaemon/configuration/ AppDaemon Configuration %}</li>
+      <li>{% active_link /ecosystem/appdaemon/example_apps/ Example Apps %}</li>
+      <li>{% active_link /ecosystem/appdaemon/running/ Running AppDaemon %}</li>
+      <li>{% active_link /ecosystem/appdaemon/reboot/ Starting AppDaemon at Reboot %}</li>
+      <li>{% active_link /ecosystem/appdaemon/operation/ AppDaemon Operation %}</li>
+      <li>{% active_link /ecosystem/appdaemon/windows/ AppDaemon on Windows %}</li>
+      <li>{% active_link /ecosystem/appdaemon/updating/ Updating AppDaemon %}</li>
+      <li>{% active_link /ecosystem/appdaemon/tutorial/ AppDaemon Tutorial %}</li>
+      <li>{% active_link /ecosystem/appdaemon/api/ AppDaemon API Reference %}</li>
+    </ul>
+  </div>
+</section>

source/_includes/asides/ecosystem_navigation.html

@@ -3,6 +3,8 @@
   {% include asides/ecosystem_ios_navigation.html | compact_newlines %}
 {% elsif url_parts[2] == "hadashboard" %}
   {% include asides/ecosystem_hadashboard_navigation.html | compact_newlines %}
+{% elsif url_parts[2] == "appdaemon" %}
+  {% include asides/ecosystem_appdaemon_navigation.html | compact_newlines %}
 {% comment %}
 {% elsif url_parts[2] == "cookbook" %}
   {% include asides/cookbook_navigation.html | compact_newlines %}