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

Merge branch 'current' into next

Browse source
This commit is contained in:
Fabian Affolter 2017-08-10 23:34:55 +02:00
commit fa563cba7e
No known key found for this signature in database
GPG key ID: DDF3D6F44AAB1336
50 changed files with 284 additions and 152 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -92,7 +92,7 @@ Please enter password for encrypted keyring:
If you are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
</p>
### {% linkable_title Storing passwords in a keyring managed by your OS %}
### {% linkable_title Storing passwords securely in AWS %}
Using [Credstash](https://github.com/fugue/credstash) is an alternative way to `secrets.yaml`. They can be managed from the command line via the credstash script.

29
source/_docs/ecosystem/appdaemon.markdown
View file

@ -16,15 +16,15 @@ AppDaemon is a loosely coupled, multithreaded, sandboxed python execution enviro
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
- 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 five different places around your home. The code stays the same, you just dynamically add new instances of it in the config file.
- Dynamic - AppDaemon has been designed from the start to enable the user to make changes without requiring a restart of Home Assistant, thanks to its loose coupling. However, it is better than that - the user can make changes to code and AppDaemon will automatically reload the code, figure out which Apps were using it, and restart them to use the new code without 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. 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!
- 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.
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 whatsoever about what it is controlling, 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
@ -32,7 +32,7 @@ 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.
Let's 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 two 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
@ -74,9 +74,9 @@ class FlashyMotionLights(appapi.AppDaemon):
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.
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.
Now let's extend this with a somewhat artificial example to show something that is simple in AppDaemon but very difficult if not impossible using automations. Let's warn someone inside the house that there has been motion outside by flashing a lamp on and off ten 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 ten iterations.
```python
import homeassistant.appapi as appapi
@ -103,11 +103,8 @@ class MotionLights(appapi.AppDaemon):
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.
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.
For full installation instructions, see [README.md](https://github.com/home-assistant/appdaemon/blob/dev/README.rst) in the `AppDaemon` repository.
There is also full documentation for the API and associated configuration in [API.md](https://github.com/home-assistant/appdaemon/blob/dev/API.md).
In addition, Apps can write to `AppDaemon`'s log files, and there is a system of constraints that allows you to control when and under what circumstances Apps and callbacks are active to keep the logic clean and simple.
For full installation instructions, see the [AppDaemon Project Documentation pages](http://appdaemon.readthedocs.io/en/latest/).

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

@ -39,4 +39,4 @@ HADashboard is a modular, skinnable dashboard for [Home Assistant](https://home-
For full installation instructions see [DASHBOARD.md](https://github.com/home-assistant/appdaemon/blob/dev/DASHBOARD.md) in the AppDaemon Repository.
For full installation instructions see the HADashboard section in the [AppDaemon Project Documentation](http://appdaemon.readthedocs.io/en/latest/DASHBOARD/)

4
source/_docs/frontend/browsers.markdown
View file

@ -29,7 +29,7 @@ We would appreciate if you help to keep this page up-to-date and add feedback.
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Safari] | | works | |
| [Safari] | | works | Some problems with the Map. |
## {% linkable_title Linux %}
@ -60,7 +60,7 @@ We would appreciate if you help to keep this page up-to-date and add feedback.
| Browser | Release | State | Comments |
| :-------------------- |:---------------|:-----------|:-------------------------|
| [Safari] | | works | Can also be added to desktop |
| [Safari] | | works | Can also be added to desktop. Some problems with the Map. |
| [Chrome] | | works | |

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

@ -65,7 +65,7 @@ $ source /srv/homeassistant/bin/activate
$ hass
```
This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first.
This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first. If you want the log output to be colored, execute `hass --script check_config` first. This will install the `colorlog` module.
### {% linkable_title Check your configuration %}
Log in as the `pi` account and execute the following commands:

2
source/_docs/scripts.markdown
View file

@ -81,7 +81,7 @@ Wait until some things are complete. We support at the moment `wait_template` fo
```yaml
# wait until media player have stop the playing
wait_template: {% raw %}"{{ states.media_player.floor.states == 'stop' }}"{% endraw %}
wait_template: {% raw %}"{{ states.media_player.floor.state == 'stop' }}"{% endraw %}
```
```yaml

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

@ -47,7 +47,7 @@ You can use [templating] support to dynamically choose which service to call. Fo
```yaml
service_template: >
{% raw %}{% if states.sensor.temperature | float > 15 %}
{% raw %}{% if states.sensor.temperature.state | float > 15 %}
switch.turn_on
{% else %}
switch.turn_off

34
source/_docs/z-wave.markdown
View file

@ -12,7 +12,7 @@ redirect_from: /getting-started/z-wave/
[Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick or module](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host.
There is currently support for climate, covers, lights, locks, sensors, switches and thermostats. All will be picked up automatically after configuring this platform.
There is currently support for climate, covers, lights, locks, sensors, switches, and thermostats. All will be picked up automatically after configuring this platform.
### {% linkable_title Installation %}
@ -35,7 +35,7 @@ zwave:
Configuration variables:
- **usb_path** (*Optional*): The port where your device is connected to your Home Assistant host.
- **network_key** (*Optional*): The 16 byte network key in the form `"0x01,0x02..."` used in order to connect securely to compatible devices.
- **network_key** (*Optional*): The 16-byte network key in the form `"0x01,0x02..."` used in order to connect securely to compatible devices.
- **config_path** (*Optional*): The path to the Python OpenZWave configuration files. Defaults to the 'config' that is installed by python-openzwave
- **autoheal** (*Optional*): Allows disabling auto Z-Wave heal at midnight. Defaults to True.
- **polling_interval** (*Optional*): The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems.
@ -54,7 +54,7 @@ To find the path of your Z-Wave USB stick or module, run:
$ ls /dev/ttyUSB*
```
Or, if there is no result try to find detailed USB connection info with:
Or, if there is no result, try to find detailed USB connection info with:
```bash
$ dmesg | grep USB
```
@ -89,7 +89,7 @@ Depending on what's plugged into your USB ports, the name found above may change
To add a Z-Wave device to your system, go to the Z-Wave panel in the Home Assistant frontend and click the Add Node button in the Z-Wave Network Management card. This will place the controller in inclusion mode, after which you should activate your device to be included by following the instructions provided with the device.
<p class='note'>
Some Z-Wave controllers like Aeotec ZW090 Z-Stick Gen5 have ability to add devices to the network using their own contol buttons. This method should be avoided as it is prone to errors. Devices added to the Z-Wave network using this method may not function well.
Some Z-Wave controllers, like Aeotec ZW090 Z-Stick Gen5, have ability to add devices to the network using their own contol buttons. This method should be avoided as it is prone to errors. Devices added to the Z-Wave network using this method may not function well.
</p>
### {% linkable_title Adding Security Devices %}
@ -105,7 +105,7 @@ cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0
#### {% linkable_title zwave.network_complete %}
Home Assistant will trigger a event when the Z-Wave network is complete. Meaning all of the nodes on the network have been queried. This can take quite some time, depending on wakeup intervals on the battery powered devices on the network.
Home Assistant will trigger an event when the Z-Wave network is complete, meaning all of the nodes on the network have been queried. This can take quite some time, depending on wakeup intervals on the battery-powered devices on the network.
```yaml
- alias: Z-Wave network is complete
@ -116,7 +116,7 @@ Home Assistant will trigger a event when the Z-Wave network is complete. Meaning
#### {% linkable_title zwave.network_ready %}
Home Assistant will trigger a event when the Z-Wave network is ready for use. Between `zwave.network_start` and `zwave.network_ready` Home Assistant will feel sluggish when trying to send commands to Z-Wave nodes. This is because the controller is requesting information from all of the nodes on the network. When this is triggered all awake nodes have been queried and sleeping nodes will be queried when they awake.
Home Assistant will trigger an event when the Z-Wave network is ready for use. Between `zwave.network_start` and `zwave.network_ready` Home Assistant will feel sluggish when trying to send commands to Z-Wave nodes. This is because the controller is requesting information from all of the nodes on the network. When this is triggered, all awake nodes have been queried and sleeping nodes will be queried when they awake.
```yaml
- alias: Z-Wave network is ready
@ -127,7 +127,7 @@ Home Assistant will trigger a event when the Z-Wave network is ready for use. Be
#### {% linkable_title zwave.network_start %}
Home Assistant will trigger a event when the Z-Wave network is set up to be started.
Home Assistant will trigger an event when the Z-Wave network is set up to be started.
```yaml
- alias: Z-Wave network is starting
@ -138,7 +138,7 @@ Home Assistant will trigger a event when the Z-Wave network is set up to be star
#### {% linkable_title zwave.network_stop %}
Home Assistant will trigger a event when the Z-Wave network stopping.
Home Assistant will trigger an event when the Z-Wave network is stopping.
```yaml
- alias: Z-Wave network is stopping
@ -148,7 +148,7 @@ Home Assistant will trigger a event when the Z-Wave network stopping.
```
#### {% linkable_title zwave.node_event %}
Home Assistant will trigger a event when command_class_basic changes value on a node. This can be virtually anything, so tests have to be made to determine what value equals what. You can use this for automations.
Home Assistant will trigger an event when command_class_basic changes value on a node. This can be virtually anything, so tests have to be made to determine what value equals what. You can use this for automations.
Example:
@ -166,7 +166,7 @@ The *object_id* and *basic_level* of all triggered events can be seen in the con
#### {% linkable_title zwave.scene_activated %}
Some devices can also trigger scene activation events, which can be used in automation scripts (for example the press of a button on a wall switch):
Some devices can also trigger scene activation events, which can be used in automation scripts (for example, the press of a button on a wall switch):
```yaml
# Example configuration.yaml automation entry
@ -190,7 +190,7 @@ The `zwave` component exposes multiple services to help maintain the network.
| ------- | ----------- |
| add_node | Put the Z-Wave controller in inclusion mode. Allows one to add a new device to the Z-Wave network.|
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows one to add a new device with secure communications to the Z-Wave network. |
| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decides you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| change_association | Add or remove an association in the Z-Wave network |
| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
| print_config_parameter | Prints Z-Wave node's config parameter value to the log. |
@ -200,16 +200,16 @@ The `zwave` component exposes multiple services to help maintain the network.
| remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.|
| rename_node | Sets a node's name. Requires a `node_id` and `name` field. |
| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. |
| remove_failed_node | Remove a failed node from the network. The Node should be on the Controllers Failed Node List, otherwise this command will fail.|
| replace_failed_node | Replace a failed device with another. If the node is not in the controller's failed nodes list, or the node responds, this command will fail.|
| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail.|
| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail.|
| reset_node_meters | Reset a node's meter values. Only works if the node supports this. |
| set_config_parameter | Let's the user set a config parameter to a node. NOTE: Use string for list values. For all others use integer. |
| soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|
| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use string for list values. For all others use integer. |
| soft_reset | Tells the controller to do a "soft reset." This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|
| start_network | Starts the Z-Wave network.|
| stop_network | Stops the Z-Wave network.|
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead".|
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead."|
The `soft_reset` and `heal_network` commands can be used as part of an automation script to help keep a Z-Wave network running reliably as shown in the example below. By default, Home Assistant will run a `heal_network` at midnight. This is a configuration option for the `zwave` component, the option defaults to `true` but can be disabled by setting `autoheal` to false. Using the `soft_reset` function with some Z-Wave controllers can cause the Z-Wave network to hang. If you're having issues with your Z-Wave network try disabling this automation.
The `soft_reset` and `heal_network` commands can be used as part of an automation script to help keep a Z-Wave network running reliably as shown in the example below. By default, Home Assistant will run a `heal_network` at midnight. This is a configuration option for the `zwave` component. The option defaults to `true` but can be disabled by setting `autoheal` to false. Using the `soft_reset` function with some Z-Wave controllers can cause the Z-Wave network to hang. If you're having issues with your Z-Wave network, try disabling this automation.
```yaml
# Example configuration.yaml automation entry

18
source/_docs/z-wave/device-specific.markdown
View file

@ -56,7 +56,7 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 1
- alias: Minimote Button 1 Held
@ -64,7 +64,7 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 2
- alias: Minimote Button 2 Pressed
@ -72,7 +72,7 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 3
- alias: Minimote Button 2 Held
@ -80,7 +80,7 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 4
- alias: Minimote Button 3 Pressed
@ -88,7 +88,7 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 5
- alias: Minimote Button 3 Held
@ -96,15 +96,15 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 6
- alias: Minimote Button 4 Pressed
trigger:
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_data:
entity_id: zwave.aeon_labs_minimote_1
scene_id: 7
- alias: Minimote Button 4 Held
@ -112,6 +112,6 @@ Here's a handy configuration for the Aeon Labs Minimote that defines all possibl
platform: event
event_type: zwave.scene_activated
event_data:
object_id: aeon_labs_minimote_1
entity_id: zwave.aeon_labs_minimote_1
scene_id: 8
```