From 4385785fac6e82bf453ceffed4364e7334c4e047 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sun, 12 Feb 2017 18:34:07 +0100 Subject: [PATCH 01/51] Split MQTT documentation --- source/_components/mqtt.markdown | 290 +----------------- source/_components/mqtt_birth_will.markdown | 40 +++ source/_components/mqtt_broker.markdown | 125 ++++++++ source/_components/mqtt_certificate.markdown | 28 ++ source/_components/mqtt_discovery.markdown | 29 ++ source/_components/mqtt_logging.markdown | 22 ++ .../_components/mqtt_processing_json.markdown | 36 +++ source/_components/mqtt_service.markdown | 28 ++ source/_components/mqtt_testing.markdown | 59 ++++ 9 files changed, 380 insertions(+), 277 deletions(-) create mode 100644 source/_components/mqtt_birth_will.markdown create mode 100644 source/_components/mqtt_broker.markdown create mode 100644 source/_components/mqtt_certificate.markdown create mode 100644 source/_components/mqtt_discovery.markdown create mode 100644 source/_components/mqtt_logging.markdown create mode 100644 source/_components/mqtt_processing_json.markdown create mode 100644 source/_components/mqtt_service.markdown create mode 100644 source/_components/mqtt_testing.markdown diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index f0d6cdb249f2..e4e3c9549be4 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -16,295 +16,31 @@ ha_iot_class: depends MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. -To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file: +Your first step to get MQTT and Home Assistant working is the choose a [broker](/components/mqtt_broker). -```yaml -# Example configuration.yaml entry -mqtt: - broker: IP_ADDRESS_BROKER - port: 1883 - client_id: home-assistant-1 - keepalive: 60 - username: USERNAME - password: PASSWORD - certificate: /home/paulus/dev/addtrustexternalcaroot.crt - protocol: 3.1 - discovery: "discovery/#" - birth_message: - topic: 'hass/status' - payload: 'online' - qos: 1 - retain: true - will_message: - topic: 'hass/status' - payload: 'offline' - qos: 1 - retain: true -``` - -Configuration variables: - -- **broker** (*Required*): The IP address or hostname of your MQTT broker, e.g. 192.168.1.32. -- **port** (*Optional*): The network port to connect to. Default is 1883. -- **client_id** (*Optional*): The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one. -- **keepalive** (*Optional*): The time in seconds between sending keep alive messages for this client. Default is 60. -- **username** (*Optional*): The username to use with your MQTT broker. -- **password** (*Optional*): The corresponding password for the username to use with your MQTT broker. -- **certificate** (*Optional*): The certificate authority certificate file that is to be treated as trusted by this client. This file should contain the root certificate of the certificate authority that signed your broker's certificate, but may contain multiple certificates. Example: `/home/user/identrust-root.pem` -- **client_key** (*Optional*): Client key (example: `/home/user/owntracks/cookie.key`) -- **client_cert** (*Optional*): Client certificate (example: `/home/user/owntracks/cookie.crt`) -- **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1. -- **discovery** (*Optional*): The MQTT topic subscribed to use for discovery of MQTT devices. -- **birth_message** (*Optional*): - - **topic** (*Required*): The MQTT topic to publish the message. - - **payload** (*Required*): The message content. - - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0. - - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`. -- **will_message** (*Optional*): - - **topic** (*Required*): The MQTT topic to publish the message. - - **payload** (*Required*): The message content. - - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0. - - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`. - -## {% linkable_title Picking a broker %} - -The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy. - -### {% linkable_title Embedded broker %} - -Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Assistant connects to it. Embedded broker default configuration: - -| Setting | Value | -| ------- | ----- | -| Host | localhost -| Port | 1883 -| Protocol | 3.1.1 -| User | homeassistant -| Password | Your API [password](/components/http/) -| Websocket port | 8080 +To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/components/mqtt_broker#embedded-broker): ```yaml # Example configuration.yaml entry mqtt: ``` -

-This broker does not currently work with OwnTracks because of a protocol version issue. -

- -If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration. - -```yaml -# Example configuration.yaml entry -mqtt: - embedded: - # Your HBMQTT config here. Example at: - # http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration -``` - -### {% linkable_title Run your own %} - -This is the most private option but requires a bit more work. There are two free and open-source brokers to pick from: [Mosquitto](http://mosquitto.org/) and [Mosca](http://www.mosca.io/). +To connect to your [own MQTT broker](/components/mqtt_broker#run-your-own): ```yaml # Example configuration.yaml entry mqtt: - broker: 192.168.1.100 - port: 1883 - client_id: home-assistant-1 - keepalive: 60 - username: USERNAME - password: PASSWORD -``` - -

-There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue. -

- -

-If you are running a mosquitto instance on a different server with proper SSL encryption using a service like letsencrypt you may have to set the certificate to the operating systems own `.crt` certificates file. In the instance of ubuntu this would be `certificate: /etc/ssl/certs/ca-certificates.crt` -

- -### {% linkable_title Public broker %} - -The Mosquitto project runs a [public broker](http://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices. - -```yaml -mqtt: - broker: test.mosquitto.org - port: 1883 - - # Optional, replace port 1883 with following if you want encryption - # (doesn't really matter because broker is public) - port: 8883 - # Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt - certificate: /home/paulus/downloads/mosquitto.org.crt -``` - -### {% linkable_title CloudMQTT %} - -[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free for up to 10 connected devices. This is enough to get started with for example [OwnTracks](/components/device_tracker.owntracks/) and give you a taste of what is possible. - -

-Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks. -

- - 1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed) - 2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create) - (Cute Cat is the free plan) - 3. From the control panel, click on the _Details_ button. - 4. Create unique users for Home Assistant and each phone to connect
(CloudMQTT does not allow two - connections from the same user) - 1. Under manage users, fill in username, password and click add - 2. Under ACLs, select user, topic `#`, check 'read access' and 'write access' - 5. Copy the instance info to your configuration.yaml: - -```yaml -mqtt: - broker: - port: - username: - password: -``` - -

-Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20 000 - 30 000). -

- -## {% linkable_title Building on top of MQTT %} - - - [MQTT Alarm control panel](/components/alarm_control_panel.mqtt/) - - [MQTT Binary sensor](/components/binary_sensor.mqtt/) - - [MQTT Sensor](/components/sensor.mqtt/) - - [MQTT Switch](/components/switch.mqtt/) - - [MQTT Light](/components/light.mqtt/) - - [MQTT Lock](/components/lock.mqtt/) - - [MQTT Device Tracker](/components/device_tracker.mqtt/) - - [OwnTracks Device Tracker](/components/device_tracker.owntracks/) - - [MQTT automation rule](/getting-started/automation-trigger/#mqtt-trigger) - - - Integrating it into own component. See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to do this. - -## {% linkable_title Publish service %} - -The MQTT component will register the service `publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload. - -```json -{ - "topic": "home-assistant/light/1/command", - "payload": "on" -} -``` - -```json -{ - "topic": "home-assistant/light/1/state", - "payload_template": "{% raw %}{{ states('device_tracker.paulus') }}{% endraw %}" -} -``` - -## {% linkable_title Discovery %} - -The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment. - -To enable MQTT discovery, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -mqtt: - discovery: true - # Optional - discovery_prefix: homeassistant -``` - -A motion detection device for your garden would sent its configuration as JSON payload `{"name": "garden", "sensor_class": "motion"}` to the topic `homeassistant/binary_sensor/garden/config`. After the first message to `config`, then the MQTT messages sent to `state`, eg. `homeassistant/binary_sensor/garden/state`, will update the state in Home Assistant. - -## {% linkable_title Logging %} - -The [logger](/components/logger/) component allow the logging of received MQTT messages. - -```yaml -# Example configuration.yaml entry -logger: - default: warning - logs: - homeassistant.components.device_tracker.mqtt: debug -``` - -## {% linkable_title Testing your setup %} - -The `mosquitto` broker package ships commandline tools to send and receive MQTT messages. As an alternative have a look at [hbmqtt_pub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_pub.html) and [hbmqtt_sub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_sub.html) which are provided by HBMQTT. For sending test messages to a broker running on localhost check the example below: - -```bash -$ mosquitto_pub -h 127.0.0.1 -t home-assistant/switch/1/on -m "Switch is ON" -``` - -If you are using the embedded MQTT broker, the command looks a little different because you need to add the MQTT protocol version. - -```bash -$ mosquitto_pub -V mqttv311 -t "hello" -m world -``` - -or if you are using a API password: - -```bash -$ mosquitto_pub -V mqttv311 -u homeassistant -P -t "hello" -m world -``` - -Another way to send MQTT messages by hand is to use the "Developer Tools" in the Frontend. Choose "Call Service" and then `mqtt/mqtt_send` under "Available Services". Enter something similar to the example below into the "Service Data" field. - -```json -{ - "topic":"home-assistant/switch/1/on", - "payload":"Switch is ON" -} -``` - -The message should appear on the bus: - -```bash -... [homeassistant] Bus:Handling -``` - -For reading all messages sent on the topic `home-assistant` to a broker running on localhost: - -```bash -$ mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#" -``` - -For the embedded MQTT broker the command looks like: - -```bash -$ mosquitto_sub -v -V mqttv311 -t "#" -``` - -Add the username `homeassistant` and your API password if needed. - -## {% linkable_title Processing JSON %} - -The MQTT switch and sensor platforms support processing JSON over MQTT messages and parsing them using JSONPath. JSONPath allows you to specify where in the JSON the value resides that you want to use. The following examples will always return the value `100`. - -| JSONPath query | JSON | -| -------------- | ---- | -| `somekey` | `{ 'somekey': 100 }` -| `somekey[0]` | `{ 'somekey': [100] }` -| `somekey[0].value` | `{ 'somekey': [ { value: 100 } ] }` - -To use this, add the following key to your `configuration.yaml`: - -```yaml -switch: - platform: mqtt - state_format: 'json:somekey[0].value' + broker: IP_ADDRESS_BROKER ``` -It is also possible to extract JSON values by using a value template: -```yaml -switch: - platform: mqtt - value_template: '{% raw %}{{ value_json.somekey[0].value }}{% endraw %}' -``` +## {% linkable_title Additional features %} -More information about the full JSONPath syntax can be found [here][JSONPath syntax]. +- [Certificate](/components/mqtt_certificate/) +- [Discovery](/components/mqtt_discovery/) +- [Publish service](/components/mqtt_service/) +- [Birth and last will messages](/components/mqtt_birth_will) +- [Testing your setup](/components/mqtt_testing/) +- [Logging](/components/mqtt_logging/) +- [Processing JSON](/components/mqtt_processing_json/) -[JSONPath syntax]: https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax +See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component. diff --git a/source/_components/mqtt_birth_will.markdown b/source/_components/mqtt_birth_will.markdown new file mode 100644 index 000000000000..a3caf2c466fb --- /dev/null +++ b/source/_components/mqtt_birth_will.markdown @@ -0,0 +1,40 @@ +--- +layout: page +title: "MQTT Birth and Last will" +description: "Instructions how to setup MQTT birth and last will messages within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +MQTT support so-called Birth and Last Will and Testament (LWT) messages. The former is used to sned a message after the service has started. the latter is here to notify other clients about an ungracefully disconnected client or alike. + +To integrate MQTT Birth and Last Will messages into Home Assistant, add the following section to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +mqtt: + birth_message: + topic: 'hass/status' + payload: 'online' + will_message: + topic: 'hass/status' + payload: 'offline' +``` + +Configuration variables: + +- **birth_message** (*Optional*): + - **topic** (*Required*): The MQTT topic to publish the message. + - **payload** (*Required*): The message content. + - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0. + - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`. +- **will_message** (*Optional*): + - **topic** (*Required*): The MQTT topic to publish the message. + - **payload** (*Required*): The message content. + - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0. + - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`. + diff --git a/source/_components/mqtt_broker.markdown b/source/_components/mqtt_broker.markdown new file mode 100644 index 000000000000..70ef71272cad --- /dev/null +++ b/source/_components/mqtt_broker.markdown @@ -0,0 +1,125 @@ +--- +layout: page +title: "MQTT Brokers" +description: "Instructions how to setup MQTT brokers for Home Assistant." +date: 2015-08-07 18:00 +sidebar: False +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy. + +### {% linkable_title Embedded broker %} + +Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Assistant connects to it. Embedded broker default configuration: + +| Setting | Value | +| ------- | ----- | +| Host | localhost +| Port | 1883 +| Protocol | 3.1.1 +| User | homeassistant +| Password | Your API [password](/components/http/) +| Websocket port | 8080 + +```yaml +# Example configuration.yaml entry +mqtt: +``` + +

+This broker does not currently work with OwnTracks because of a protocol version issue. +

+ +If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration. + +```yaml +# Example configuration.yaml entry +mqtt: + embedded: + # Your HBMQTT config here. Example at: + # http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration +``` + +### {% linkable_title Run your own %} + +This is the most private option but requires a bit more work. There are multiple free and open-source brokers to pick from: eg. [Mosquitto](http://mosquitto.org/), [EMQ](http://emqtt.io/), or [Mosca](http://www.mosca.io/). + +```yaml +# Example configuration.yaml entry +mqtt: + broker: 192.168.1.100 + port: 1883 + client_id: home-assistant-1 + keepalive: 60 + username: USERNAME + password: PASSWORD + protocol: 3.1 +``` + +Configuration variables: + +- **broker** (*Optional*): The IP address or hostname of your MQTT broker, e.g. 192.168.1.32. +- **port** (*Optional*): The network port to connect to. Default is 1883. +- **client_id** (*Optional*): The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one. +- **keepalive** (*Optional*): The time in seconds between sending keep alive messages for this client. Default is 60. +- **username** (*Optional*): The username to use with your MQTT broker. +- **password** (*Optional*): The corresponding password for the username to use with your MQTT broker. +- **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.1. + +

+There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue. +

+ +

+If you are running a mosquitto instance on a different server with proper SSL encryption using a service like letsencrypt you may have to set the certificate to the operating systems own `.crt` certificates file. In the instance of ubuntu this would be `certificate: /etc/ssl/certs/ca-certificates.crt` +

+ +### {% linkable_title Public broker %} + +The Mosquitto project runs a [public broker](http://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices or controlling your home. + +```yaml +mqtt: + broker: test.mosquitto.org + port: 1883 or 8883 + + # Optional, replace port 1883 with following if you want encryption + # (doesn't really matter because broker is public) + port: 8883 + # Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt + certificate: /home/paulus/downloads/mosquitto.org.crt +``` + +### {% linkable_title CloudMQTT %} + +[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free for up to 10 connected devices. This is enough to get started with for example [OwnTracks](/components/device_tracker.owntracks/) and give you a taste of what is possible. + +

+Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks. +

+ + 1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed) + 2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create) + (Cute Cat is the free plan) + 3. From the control panel, click on the _Details_ button. + 4. Create unique users for Home Assistant and each phone to connect
(CloudMQTT does not allow two connections from the same user) + 1. Under manage users, fill in username, password and click add + 2. Under ACLs, select user, topic `#`, check 'read access' and 'write access' + 5. Copy the instance info to your configuration.yaml: + +```yaml +mqtt: + broker: CLOUTMQTT_SERVER + port: CLOUDMQTT_PORT + username: CLOUDMQTT_USER + password: CLOUDMQTT_PASSWORD +``` + +

+Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20000-30000). +

+ diff --git a/source/_components/mqtt_certificate.markdown b/source/_components/mqtt_certificate.markdown new file mode 100644 index 000000000000..71374bc85c10 --- /dev/null +++ b/source/_components/mqtt_certificate.markdown @@ -0,0 +1,28 @@ +--- +layout: page +title: "MQTT Certificate" +description: "Instructions how to setup MQTT with a certificate in Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +Using certificates will give you an additional layer of security for your MQTT communication. + +To integrate MQTT with certificate into Home Assistant, add the following section to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +mqtt: + certificate: /home/paulus/dev/addtrustexternalcaroot.crt +``` + +Configuration variables: + +- **certificate** (*Optional*): The certificate authority certificate file that is to be treated as trusted by this client. This file should contain the root certificate of the certificate authority that signed your broker's certificate, but may contain multiple certificates. Example: `/home/user/identrust-root.pem` +- **client_key** (*Optional*): Client key, eg. `/home/user/owntracks/cookie.key`. +- **client_cert** (*Optional*): Client certificate, eg. `/home/user/owntracks/cookie.crt`. + diff --git a/source/_components/mqtt_discovery.markdown b/source/_components/mqtt_discovery.markdown new file mode 100644 index 000000000000..b27e0e0c35c3 --- /dev/null +++ b/source/_components/mqtt_discovery.markdown @@ -0,0 +1,29 @@ +--- +layout: page +title: "MQTT Discovery" +description: "Instructions how to setup MQTT Discovery within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment. + +To enable MQTT discovery, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +mqtt: + discovery: true + discovery_prefix: homeassistant +``` +Configuration variables: + +- **discovery** (*Optional*): If the MQTT discovery should be enabled or not. Defaults to `False`. +- **discovery_prefix** (*Optional*): The prefix for the discovery topic. Defaults to `homeassistant`. + +A motion detection device for your garden would sent its configuration as JSON payload `{"name": "garden", "sensor_class": "motion"}` to the topic `homeassistant/binary_sensor/garden/config`. After the first message to `config`, then the MQTT messages sent to `state`, eg. `homeassistant/binary_sensor/garden/state`, will update the state in Home Assistant. + diff --git a/source/_components/mqtt_logging.markdown b/source/_components/mqtt_logging.markdown new file mode 100644 index 000000000000..a7fd1adfdf85 --- /dev/null +++ b/source/_components/mqtt_logging.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "MQTT Logging" +description: "Instructions how to setup MQTT Logging within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The [logger](/components/logger/) component allow the logging of received MQTT messages. + +```yaml +# Example configuration.yaml entry +logger: + default: warning + logs: + homeassistant.components.device_tracker.mqtt: debug +``` + diff --git a/source/_components/mqtt_processing_json.markdown b/source/_components/mqtt_processing_json.markdown new file mode 100644 index 000000000000..552dd0816763 --- /dev/null +++ b/source/_components/mqtt_processing_json.markdown @@ -0,0 +1,36 @@ +--- +layout: page +title: "Processing JSON" +description: "Instructions how to process the MQTT payload." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The MQTT [switch](/components/switch.mqtt/) and [sensor](/components/sensor.mqtt/) platforms support processing JSON over MQTT messages and parsing them using JSONPath. JSONPath allows you to specify where in the JSON the value resides that you want to use. The following examples will always return the value `100`. + +| JSONPath query | JSON | +| -------------- | ---- | +| `somekey` | `{ 'somekey': 100 }` +| `somekey[0]` | `{ 'somekey': [100] }` +| `somekey[0].value` | `{ 'somekey': [ { value: 100 } ] }` + +To use this, add the following key to your `configuration.yaml`: + +```yaml +switch: + platform: mqtt + state_format: 'json:somekey[0].value' +``` +It is also possible to extract JSON values by using a value template: + +```yaml +switch: + platform: mqtt + value_template: '{% raw %}{{ value_json.somekey[0].value }}{% endraw %}' +``` + +More information about the full JSONPath syntax can be found [in their documentation](https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax). diff --git a/source/_components/mqtt_service.markdown b/source/_components/mqtt_service.markdown new file mode 100644 index 000000000000..d751856fe4c6 --- /dev/null +++ b/source/_components/mqtt_service.markdown @@ -0,0 +1,28 @@ +--- +layout: page +title: "MQTT Publish service" +description: "Instructions how to setup the MQTT Publish service within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The MQTT component will register the service `publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload. + +```json +{ + "topic": "home-assistant/light/1/command", + "payload": "on" +} +``` + +```json +{ + "topic": "home-assistant/light/1/state", + "payload_template": "{% raw %}{{ states('device_tracker.paulus') }}{% endraw %}" +} +``` + diff --git a/source/_components/mqtt_testing.markdown b/source/_components/mqtt_testing.markdown new file mode 100644 index 000000000000..f71ac52e2f16 --- /dev/null +++ b/source/_components/mqtt_testing.markdown @@ -0,0 +1,59 @@ +--- +layout: page +title: "MQTT Testing" +description: "Instructions how to test your MQTT setup." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +--- + +The `mosquitto` broker package ships commandline tools (often as `*-clients` package) to send and receive MQTT messages. As an alternative have a look at [hbmqtt_pub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_pub.html) and [hbmqtt_sub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_sub.html) which are provided by HBMQTT. For sending test messages to a broker running on localhost check the example below: + +```bash +$ mosquitto_pub -h 127.0.0.1 -t home-assistant/switch/1/on -m "Switch is ON" +``` + +If you are using the embedded MQTT broker, the command looks a little different because you need to add the MQTT protocol version. + +```bash +$ mosquitto_pub -V mqttv311 -t "hello" -m world +``` + +or if you are using a API password: + +```bash +$ mosquitto_pub -V mqttv311 -u homeassistant -P -t "hello" -m world +``` + +Another way to send MQTT messages by hand is to use the "Developer Tools" in the Frontend. Choose "Call Service" and then `mqtt/mqtt_send` under "Available Services". Enter something similar to the example below into the "Service Data" field. + +```json +{ + "topic":"home-assistant/switch/1/on", + "payload":"Switch is ON" +} +``` + +The message should appear on the bus: + +```bash +... [homeassistant] Bus:Handling +``` + +For reading all messages sent on the topic `home-assistant` to a broker running on localhost: + +```bash +$ mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#" +``` + +For the embedded MQTT broker the command looks like: + +```bash +$ mosquitto_sub -v -V mqttv311 -t "#" +``` + +Add the username `homeassistant` and your API password if needed. + From 416eecbc6b18d5519c178cf1790bd21540d088db Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 13 Feb 2017 16:57:15 +0100 Subject: [PATCH 02/51] Add more details --- source/_components/mqtt_discovery.markdown | 31 +++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/source/_components/mqtt_discovery.markdown b/source/_components/mqtt_discovery.markdown index b27e0e0c35c3..509ee420c9f6 100644 --- a/source/_components/mqtt_discovery.markdown +++ b/source/_components/mqtt_discovery.markdown @@ -25,5 +25,34 @@ Configuration variables: - **discovery** (*Optional*): If the MQTT discovery should be enabled or not. Defaults to `False`. - **discovery_prefix** (*Optional*): The prefix for the discovery topic. Defaults to `homeassistant`. -A motion detection device for your garden would sent its configuration as JSON payload `{"name": "garden", "sensor_class": "motion"}` to the topic `homeassistant/binary_sensor/garden/config`. After the first message to `config`, then the MQTT messages sent to `state`, eg. `homeassistant/binary_sensor/garden/state`, will update the state in Home Assistant. +The discovery topic need to follow a specific format: + +```text +///<> +``` + +- ``: One of the supported components, eg. `binary_sensor`. +- ``: The ID of the device. This will become the `entity_id` in Home Assistant. +- ``: The topic `config` or `state` which defines the current action. + +The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. + +### {% linkable_title Example %} + +A motion detection device which can be represented by a [binary sensor](/components/binary_sensor.mqtt/) for your garden would sent its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the State topic will update the state in Home Assistant. + +- Configuration topic: `homeassistant/binary_sensor/garden/config` +- State topic: `homeassistant/binary_sensor/garden/state` +- Payload: `{"name": "garden", "sensor_class": "motion"}` + +To create a new sensor manually. For more details please refer to the [MQTT testing section](/component/mqtt_testing). + +```bash +$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "sensor_class": "motion"}' +``` +Update the state. + +```bash +$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON +``` From 78683e654594295f7e2f0e68fb2a21e10ee36f9d Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:03:06 +0100 Subject: [PATCH 03/51] Move content to /docs --- source/{getting-started => _docs}/automation.markdown | 0 .../automation/action.markdown} | 0 .../automation/condition.markdown} | 0 .../automation/create-first.markdown} | 0 .../automation/examples.markdown} | 0 .../automation/templating.markdown} | 0 .../automation/trigger.markdown} | 0 .../automation/troubleshooting.markdown} | 0 source/{getting-started => _docs}/autostart.markdown | 0 .../autostart-init.d.markdown => _docs/autostart/init.d.markdown} | 0 .../autostart-macos.markdown => _docs/autostart/macos.markdown} | 0 .../autostart/synology.markdown} | 0 .../autostart/systemd.markdown} | 0 .../autostart/upstart.markdown} | 0 source/{_details => _docs/backend}/database.markdown | 0 source/{_details => _docs/backend}/updater.markdown | 0 source/{getting-started => _docs}/configuration.markdown | 0 source/{getting-started => _docs/configuration}/basic.markdown | 0 .../configuration}/customizing-devices.markdown | 0 source/{getting-started => _docs/configuration}/devices.markdown | 0 .../configuration}/presence-detection.markdown | 0 source/{getting-started => _docs/configuration}/securing.markdown | 0 .../configuration/troubleshooting.markdown} | 0 source/{getting-started => _docs/configuration}/yaml.markdown | 0 source/{getting-started => _docs/frontend}/browsers.markdown | 0 source/{getting-started => _docs/frontend}/mobile.markdown | 0 source/{_details => _docs/frontend}/webserver.markdown | 0 source/{getting-started => _docs}/hassbian.markdown | 0 .../hassbian/common-tasks.markdown} | 0 .../hassbian/customization.markdown} | 0 .../hassbian/installation.markdown} | 0 .../hassbian/integrations.markdown} | 0 .../hassbian/upgrading.markdown} | 0 .../installation/docker.markdown} | 0 .../installation/python.markdown} | 0 .../installation/raspberry-pi-all-in-one.markdown} | 0 .../installation/raspberry-pi.markdown} | 0 .../installation/synology.markdown} | 0 .../installation}/troubleshooting.markdown | 0 source/{getting-started => _docs/installation}/updating.markdown | 0 .../installation/vagrant.markdown} | 0 .../installation/virtualenv.markdown} | 0 source/{getting-started => _docs}/scripts.markdown | 0 .../scripts/conditions.markdown} | 0 .../scripts/service-calls.markdown} | 0 source/{getting-started => _docs}/z-wave.markdown | 0 .../z-wave/controllers.markdown} | 0 .../z-wave/device-specific.markdown} | 0 .../z-wave-settings.markdown => _docs/z-wave/settings.markdown} | 0 49 files changed, 0 insertions(+), 0 deletions(-) rename source/{getting-started => _docs}/automation.markdown (100%) rename source/{getting-started/automation-action.markdown => _docs/automation/action.markdown} (100%) rename source/{getting-started/automation-condition.markdown => _docs/automation/condition.markdown} (100%) rename source/{getting-started/automation-create-first.markdown => _docs/automation/create-first.markdown} (100%) rename source/{getting-started/automation-examples.markdown => _docs/automation/examples.markdown} (100%) rename source/{getting-started/automation-templating.markdown => _docs/automation/templating.markdown} (100%) rename source/{getting-started/automation-trigger.markdown => _docs/automation/trigger.markdown} (100%) rename source/{getting-started/automation-troubleshooting.markdown => _docs/automation/troubleshooting.markdown} (100%) rename source/{getting-started => _docs}/autostart.markdown (100%) rename source/{getting-started/autostart-init.d.markdown => _docs/autostart/init.d.markdown} (100%) rename source/{getting-started/autostart-macos.markdown => _docs/autostart/macos.markdown} (100%) rename source/{getting-started/autostart-synology.markdown => _docs/autostart/synology.markdown} (100%) rename source/{getting-started/autostart-systemd.markdown => _docs/autostart/systemd.markdown} (100%) rename source/{getting-started/autostart-upstart.markdown => _docs/autostart/upstart.markdown} (100%) rename source/{_details => _docs/backend}/database.markdown (100%) rename source/{_details => _docs/backend}/updater.markdown (100%) rename source/{getting-started => _docs}/configuration.markdown (100%) rename source/{getting-started => _docs/configuration}/basic.markdown (100%) rename source/{getting-started => _docs/configuration}/customizing-devices.markdown (100%) rename source/{getting-started => _docs/configuration}/devices.markdown (100%) rename source/{getting-started => _docs/configuration}/presence-detection.markdown (100%) rename source/{getting-started => _docs/configuration}/securing.markdown (100%) rename source/{getting-started/troubleshooting-configuration.markdown => _docs/configuration/troubleshooting.markdown} (100%) rename source/{getting-started => _docs/configuration}/yaml.markdown (100%) rename source/{getting-started => _docs/frontend}/browsers.markdown (100%) rename source/{getting-started => _docs/frontend}/mobile.markdown (100%) rename source/{_details => _docs/frontend}/webserver.markdown (100%) rename source/{getting-started => _docs}/hassbian.markdown (100%) rename source/{getting-started/hassbian-common-tasks.markdown => _docs/hassbian/common-tasks.markdown} (100%) rename source/{getting-started/hassbian-customization.markdown => _docs/hassbian/customization.markdown} (100%) rename source/{getting-started/hassbian-installation.markdown => _docs/hassbian/installation.markdown} (100%) rename source/{getting-started/hassbian-integrations.markdown => _docs/hassbian/integrations.markdown} (100%) rename source/{getting-started/hassbian-upgrading.markdown => _docs/hassbian/upgrading.markdown} (100%) rename source/{getting-started/installation-docker.markdown => _docs/installation/docker.markdown} (100%) rename source/{getting-started/installation-python.markdown => _docs/installation/python.markdown} (100%) rename source/{getting-started/installation-raspberry-pi-all-in-one.markdown => _docs/installation/raspberry-pi-all-in-one.markdown} (100%) rename source/{getting-started/installation-raspberry-pi.markdown => _docs/installation/raspberry-pi.markdown} (100%) rename source/{getting-started/installation-synology.markdown => _docs/installation/synology.markdown} (100%) rename source/{getting-started => _docs/installation}/troubleshooting.markdown (100%) rename source/{getting-started => _docs/installation}/updating.markdown (100%) rename source/{getting-started/installation-vagrant.markdown => _docs/installation/vagrant.markdown} (100%) rename source/{getting-started/installation-virtualenv.markdown => _docs/installation/virtualenv.markdown} (100%) rename source/{getting-started => _docs}/scripts.markdown (100%) rename source/{getting-started/scripts-conditions.markdown => _docs/scripts/conditions.markdown} (100%) rename source/{getting-started/scripts-service-calls.markdown => _docs/scripts/service-calls.markdown} (100%) rename source/{getting-started => _docs}/z-wave.markdown (100%) rename source/{getting-started/z-wave-controllers.markdown => _docs/z-wave/controllers.markdown} (100%) rename source/{getting-started/z-wave-device-specific.markdown => _docs/z-wave/device-specific.markdown} (100%) rename source/{getting-started/z-wave-settings.markdown => _docs/z-wave/settings.markdown} (100%) diff --git a/source/getting-started/automation.markdown b/source/_docs/automation.markdown similarity index 100% rename from source/getting-started/automation.markdown rename to source/_docs/automation.markdown diff --git a/source/getting-started/automation-action.markdown b/source/_docs/automation/action.markdown similarity index 100% rename from source/getting-started/automation-action.markdown rename to source/_docs/automation/action.markdown diff --git a/source/getting-started/automation-condition.markdown b/source/_docs/automation/condition.markdown similarity index 100% rename from source/getting-started/automation-condition.markdown rename to source/_docs/automation/condition.markdown diff --git a/source/getting-started/automation-create-first.markdown b/source/_docs/automation/create-first.markdown similarity index 100% rename from source/getting-started/automation-create-first.markdown rename to source/_docs/automation/create-first.markdown diff --git a/source/getting-started/automation-examples.markdown b/source/_docs/automation/examples.markdown similarity index 100% rename from source/getting-started/automation-examples.markdown rename to source/_docs/automation/examples.markdown diff --git a/source/getting-started/automation-templating.markdown b/source/_docs/automation/templating.markdown similarity index 100% rename from source/getting-started/automation-templating.markdown rename to source/_docs/automation/templating.markdown diff --git a/source/getting-started/automation-trigger.markdown b/source/_docs/automation/trigger.markdown similarity index 100% rename from source/getting-started/automation-trigger.markdown rename to source/_docs/automation/trigger.markdown diff --git a/source/getting-started/automation-troubleshooting.markdown b/source/_docs/automation/troubleshooting.markdown similarity index 100% rename from source/getting-started/automation-troubleshooting.markdown rename to source/_docs/automation/troubleshooting.markdown diff --git a/source/getting-started/autostart.markdown b/source/_docs/autostart.markdown similarity index 100% rename from source/getting-started/autostart.markdown rename to source/_docs/autostart.markdown diff --git a/source/getting-started/autostart-init.d.markdown b/source/_docs/autostart/init.d.markdown similarity index 100% rename from source/getting-started/autostart-init.d.markdown rename to source/_docs/autostart/init.d.markdown diff --git a/source/getting-started/autostart-macos.markdown b/source/_docs/autostart/macos.markdown similarity index 100% rename from source/getting-started/autostart-macos.markdown rename to source/_docs/autostart/macos.markdown diff --git a/source/getting-started/autostart-synology.markdown b/source/_docs/autostart/synology.markdown similarity index 100% rename from source/getting-started/autostart-synology.markdown rename to source/_docs/autostart/synology.markdown diff --git a/source/getting-started/autostart-systemd.markdown b/source/_docs/autostart/systemd.markdown similarity index 100% rename from source/getting-started/autostart-systemd.markdown rename to source/_docs/autostart/systemd.markdown diff --git a/source/getting-started/autostart-upstart.markdown b/source/_docs/autostart/upstart.markdown similarity index 100% rename from source/getting-started/autostart-upstart.markdown rename to source/_docs/autostart/upstart.markdown diff --git a/source/_details/database.markdown b/source/_docs/backend/database.markdown similarity index 100% rename from source/_details/database.markdown rename to source/_docs/backend/database.markdown diff --git a/source/_details/updater.markdown b/source/_docs/backend/updater.markdown similarity index 100% rename from source/_details/updater.markdown rename to source/_docs/backend/updater.markdown diff --git a/source/getting-started/configuration.markdown b/source/_docs/configuration.markdown similarity index 100% rename from source/getting-started/configuration.markdown rename to source/_docs/configuration.markdown diff --git a/source/getting-started/basic.markdown b/source/_docs/configuration/basic.markdown similarity index 100% rename from source/getting-started/basic.markdown rename to source/_docs/configuration/basic.markdown diff --git a/source/getting-started/customizing-devices.markdown b/source/_docs/configuration/customizing-devices.markdown similarity index 100% rename from source/getting-started/customizing-devices.markdown rename to source/_docs/configuration/customizing-devices.markdown diff --git a/source/getting-started/devices.markdown b/source/_docs/configuration/devices.markdown similarity index 100% rename from source/getting-started/devices.markdown rename to source/_docs/configuration/devices.markdown diff --git a/source/getting-started/presence-detection.markdown b/source/_docs/configuration/presence-detection.markdown similarity index 100% rename from source/getting-started/presence-detection.markdown rename to source/_docs/configuration/presence-detection.markdown diff --git a/source/getting-started/securing.markdown b/source/_docs/configuration/securing.markdown similarity index 100% rename from source/getting-started/securing.markdown rename to source/_docs/configuration/securing.markdown diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/_docs/configuration/troubleshooting.markdown similarity index 100% rename from source/getting-started/troubleshooting-configuration.markdown rename to source/_docs/configuration/troubleshooting.markdown diff --git a/source/getting-started/yaml.markdown b/source/_docs/configuration/yaml.markdown similarity index 100% rename from source/getting-started/yaml.markdown rename to source/_docs/configuration/yaml.markdown diff --git a/source/getting-started/browsers.markdown b/source/_docs/frontend/browsers.markdown similarity index 100% rename from source/getting-started/browsers.markdown rename to source/_docs/frontend/browsers.markdown diff --git a/source/getting-started/mobile.markdown b/source/_docs/frontend/mobile.markdown similarity index 100% rename from source/getting-started/mobile.markdown rename to source/_docs/frontend/mobile.markdown diff --git a/source/_details/webserver.markdown b/source/_docs/frontend/webserver.markdown similarity index 100% rename from source/_details/webserver.markdown rename to source/_docs/frontend/webserver.markdown diff --git a/source/getting-started/hassbian.markdown b/source/_docs/hassbian.markdown similarity index 100% rename from source/getting-started/hassbian.markdown rename to source/_docs/hassbian.markdown diff --git a/source/getting-started/hassbian-common-tasks.markdown b/source/_docs/hassbian/common-tasks.markdown similarity index 100% rename from source/getting-started/hassbian-common-tasks.markdown rename to source/_docs/hassbian/common-tasks.markdown diff --git a/source/getting-started/hassbian-customization.markdown b/source/_docs/hassbian/customization.markdown similarity index 100% rename from source/getting-started/hassbian-customization.markdown rename to source/_docs/hassbian/customization.markdown diff --git a/source/getting-started/hassbian-installation.markdown b/source/_docs/hassbian/installation.markdown similarity index 100% rename from source/getting-started/hassbian-installation.markdown rename to source/_docs/hassbian/installation.markdown diff --git a/source/getting-started/hassbian-integrations.markdown b/source/_docs/hassbian/integrations.markdown similarity index 100% rename from source/getting-started/hassbian-integrations.markdown rename to source/_docs/hassbian/integrations.markdown diff --git a/source/getting-started/hassbian-upgrading.markdown b/source/_docs/hassbian/upgrading.markdown similarity index 100% rename from source/getting-started/hassbian-upgrading.markdown rename to source/_docs/hassbian/upgrading.markdown diff --git a/source/getting-started/installation-docker.markdown b/source/_docs/installation/docker.markdown similarity index 100% rename from source/getting-started/installation-docker.markdown rename to source/_docs/installation/docker.markdown diff --git a/source/getting-started/installation-python.markdown b/source/_docs/installation/python.markdown similarity index 100% rename from source/getting-started/installation-python.markdown rename to source/_docs/installation/python.markdown diff --git a/source/getting-started/installation-raspberry-pi-all-in-one.markdown b/source/_docs/installation/raspberry-pi-all-in-one.markdown similarity index 100% rename from source/getting-started/installation-raspberry-pi-all-in-one.markdown rename to source/_docs/installation/raspberry-pi-all-in-one.markdown diff --git a/source/getting-started/installation-raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown similarity index 100% rename from source/getting-started/installation-raspberry-pi.markdown rename to source/_docs/installation/raspberry-pi.markdown diff --git a/source/getting-started/installation-synology.markdown b/source/_docs/installation/synology.markdown similarity index 100% rename from source/getting-started/installation-synology.markdown rename to source/_docs/installation/synology.markdown diff --git a/source/getting-started/troubleshooting.markdown b/source/_docs/installation/troubleshooting.markdown similarity index 100% rename from source/getting-started/troubleshooting.markdown rename to source/_docs/installation/troubleshooting.markdown diff --git a/source/getting-started/updating.markdown b/source/_docs/installation/updating.markdown similarity index 100% rename from source/getting-started/updating.markdown rename to source/_docs/installation/updating.markdown diff --git a/source/getting-started/installation-vagrant.markdown b/source/_docs/installation/vagrant.markdown similarity index 100% rename from source/getting-started/installation-vagrant.markdown rename to source/_docs/installation/vagrant.markdown diff --git a/source/getting-started/installation-virtualenv.markdown b/source/_docs/installation/virtualenv.markdown similarity index 100% rename from source/getting-started/installation-virtualenv.markdown rename to source/_docs/installation/virtualenv.markdown diff --git a/source/getting-started/scripts.markdown b/source/_docs/scripts.markdown similarity index 100% rename from source/getting-started/scripts.markdown rename to source/_docs/scripts.markdown diff --git a/source/getting-started/scripts-conditions.markdown b/source/_docs/scripts/conditions.markdown similarity index 100% rename from source/getting-started/scripts-conditions.markdown rename to source/_docs/scripts/conditions.markdown diff --git a/source/getting-started/scripts-service-calls.markdown b/source/_docs/scripts/service-calls.markdown similarity index 100% rename from source/getting-started/scripts-service-calls.markdown rename to source/_docs/scripts/service-calls.markdown diff --git a/source/getting-started/z-wave.markdown b/source/_docs/z-wave.markdown similarity index 100% rename from source/getting-started/z-wave.markdown rename to source/_docs/z-wave.markdown diff --git a/source/getting-started/z-wave-controllers.markdown b/source/_docs/z-wave/controllers.markdown similarity index 100% rename from source/getting-started/z-wave-controllers.markdown rename to source/_docs/z-wave/controllers.markdown diff --git a/source/getting-started/z-wave-device-specific.markdown b/source/_docs/z-wave/device-specific.markdown similarity index 100% rename from source/getting-started/z-wave-device-specific.markdown rename to source/_docs/z-wave/device-specific.markdown diff --git a/source/getting-started/z-wave-settings.markdown b/source/_docs/z-wave/settings.markdown similarity index 100% rename from source/getting-started/z-wave-settings.markdown rename to source/_docs/z-wave/settings.markdown From dfa0e8f049c8affc45d2cf24b9debffb56809812 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:03:37 +0100 Subject: [PATCH 04/51] Enable sidebar --- source/_docs/backend/database.markdown | 2 +- source/_docs/backend/updater.markdown | 2 +- source/_docs/frontend/webserver.markdown | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_docs/backend/database.markdown b/source/_docs/backend/database.markdown index a4c7ec00acb0..653be34c40a9 100644 --- a/source/_docs/backend/database.markdown +++ b/source/_docs/backend/database.markdown @@ -3,7 +3,7 @@ layout: page title: "Database" description: "Details about the database which Home Assistant is using." date: 2016-10-10 10:00 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/backend/updater.markdown b/source/_docs/backend/updater.markdown index ccf13eb8116d..d2c15d531fb0 100644 --- a/source/_docs/backend/updater.markdown +++ b/source/_docs/backend/updater.markdown @@ -3,7 +3,7 @@ layout: page title: "Updater" description: "Details what the updater component is reporting about your Home Assistant instance." date: 2016-10-22 08:00 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/frontend/webserver.markdown b/source/_docs/frontend/webserver.markdown index f9e2f4e00312..cf8cd77df05d 100644 --- a/source/_docs/frontend/webserver.markdown +++ b/source/_docs/frontend/webserver.markdown @@ -3,7 +3,7 @@ layout: page title: "Web server" description: "Use nmap to scan your Home Assistant instance." date: 2016-10-06 08:00 -sidebar: false +sidebar: true comments: false sharing: true footer: true From 3d28d68f733426d54867742e7ec9a1e2ec37fb30 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:20:39 +0100 Subject: [PATCH 05/51] Move content to /docs --- .../configuration}/packages.markdown | 0 .../configuration}/secrets.markdown | 0 .../splitting_configuration.markdown | 0 .../configuration}/templating.markdown | 0 source/{_topics => _docs}/events.markdown | 0 .../group_visibility.markdown | 0 .../platform_options.markdown | 0 .../{_topics => _docs}/state_object.markdown | 0 source/{_ecosystem => }/appdaemon.markdown | 0 .../{_ecosystem => }/appdaemon/api.markdown | 0 .../appdaemon/configuration.markdown | 0 .../appdaemon/example_apps.markdown | 0 .../appdaemon/installation.markdown | 0 .../appdaemon/operation.markdown | 0 .../appdaemon/reboot.markdown | 0 .../appdaemon/running.markdown | 0 .../appdaemon/tutorial.markdown | 0 .../appdaemon/updating.markdown | 0 .../appdaemon/windows.markdown | 0 source/details/index.markdown | 20 ------------------- source/ecosystem/index.markdown | 13 ------------ source/{_ecosystem => }/hadashboard.markdown | 0 .../hadashboard/dash_config.markdown | 0 .../hadashboard/hapush.markdown | 0 .../hadashboard/installation.markdown | 0 .../hadashboard/reboot.markdown | 0 .../hadashboard/updating.markdown | 0 source/{_ecosystem => }/ios.markdown | 0 .../ios/devices_file.markdown | 0 source/{_ecosystem => }/ios/features.markdown | 0 .../{_ecosystem => }/ios/integration.markdown | 0 source/{_ecosystem => }/ios/location.markdown | 0 .../ios/notifications.markdown | 0 .../ios/notifications/actions.markdown | 0 .../ios/notifications/architecture.markdown | 0 .../ios/notifications/attachments.markdown | 0 .../ios/notifications/basic.markdown | 0 .../notifications/content_extensions.markdown | 0 .../privacy_security_rate_limits.markdown | 0 .../requesting_location_updates.markdown | 0 .../ios/notifications/sounds.markdown | 0 .../ios/requirements.markdown | 0 source/{_ecosystem => }/nginx.markdown | 0 source/{_ecosystem => }/notebooks.markdown | 0 .../{_ecosystem => }/notebooks/api.markdown | 0 .../notebooks/database.markdown | 0 .../{_ecosystem => }/notebooks/graph.markdown | 0 .../notebooks/installation.markdown | 0 .../{_ecosystem => }/notebooks/stats.markdown | 0 source/{_ecosystem => }/scenegen.markdown | 0 source/{_ecosystem => }/synology.markdown | 0 source/topics/index.markdown | 20 ------------------- 52 files changed, 53 deletions(-) rename source/{_topics => _docs/configuration}/packages.markdown (100%) rename source/{_topics => _docs/configuration}/secrets.markdown (100%) rename source/{_topics => _docs/configuration}/splitting_configuration.markdown (100%) rename source/{_topics => _docs/configuration}/templating.markdown (100%) rename source/{_topics => _docs}/events.markdown (100%) rename source/{_topics => _docs}/group_visibility.markdown (100%) rename source/{_topics => _docs}/platform_options.markdown (100%) rename source/{_topics => _docs}/state_object.markdown (100%) rename source/{_ecosystem => }/appdaemon.markdown (100%) rename source/{_ecosystem => }/appdaemon/api.markdown (100%) rename source/{_ecosystem => }/appdaemon/configuration.markdown (100%) rename source/{_ecosystem => }/appdaemon/example_apps.markdown (100%) rename source/{_ecosystem => }/appdaemon/installation.markdown (100%) rename source/{_ecosystem => }/appdaemon/operation.markdown (100%) rename source/{_ecosystem => }/appdaemon/reboot.markdown (100%) rename source/{_ecosystem => }/appdaemon/running.markdown (100%) rename source/{_ecosystem => }/appdaemon/tutorial.markdown (100%) rename source/{_ecosystem => }/appdaemon/updating.markdown (100%) rename source/{_ecosystem => }/appdaemon/windows.markdown (100%) delete mode 100644 source/details/index.markdown delete mode 100644 source/ecosystem/index.markdown rename source/{_ecosystem => }/hadashboard.markdown (100%) rename source/{_ecosystem => }/hadashboard/dash_config.markdown (100%) rename source/{_ecosystem => }/hadashboard/hapush.markdown (100%) rename source/{_ecosystem => }/hadashboard/installation.markdown (100%) rename source/{_ecosystem => }/hadashboard/reboot.markdown (100%) rename source/{_ecosystem => }/hadashboard/updating.markdown (100%) rename source/{_ecosystem => }/ios.markdown (100%) rename source/{_ecosystem => }/ios/devices_file.markdown (100%) rename source/{_ecosystem => }/ios/features.markdown (100%) rename source/{_ecosystem => }/ios/integration.markdown (100%) rename source/{_ecosystem => }/ios/location.markdown (100%) rename source/{_ecosystem => }/ios/notifications.markdown (100%) rename source/{_ecosystem => }/ios/notifications/actions.markdown (100%) rename source/{_ecosystem => }/ios/notifications/architecture.markdown (100%) rename source/{_ecosystem => }/ios/notifications/attachments.markdown (100%) rename source/{_ecosystem => }/ios/notifications/basic.markdown (100%) rename source/{_ecosystem => }/ios/notifications/content_extensions.markdown (100%) rename source/{_ecosystem => }/ios/notifications/privacy_security_rate_limits.markdown (100%) rename source/{_ecosystem => }/ios/notifications/requesting_location_updates.markdown (100%) rename source/{_ecosystem => }/ios/notifications/sounds.markdown (100%) rename source/{_ecosystem => }/ios/requirements.markdown (100%) rename source/{_ecosystem => }/nginx.markdown (100%) rename source/{_ecosystem => }/notebooks.markdown (100%) rename source/{_ecosystem => }/notebooks/api.markdown (100%) rename source/{_ecosystem => }/notebooks/database.markdown (100%) rename source/{_ecosystem => }/notebooks/graph.markdown (100%) rename source/{_ecosystem => }/notebooks/installation.markdown (100%) rename source/{_ecosystem => }/notebooks/stats.markdown (100%) rename source/{_ecosystem => }/scenegen.markdown (100%) rename source/{_ecosystem => }/synology.markdown (100%) delete mode 100644 source/topics/index.markdown diff --git a/source/_topics/packages.markdown b/source/_docs/configuration/packages.markdown similarity index 100% rename from source/_topics/packages.markdown rename to source/_docs/configuration/packages.markdown diff --git a/source/_topics/secrets.markdown b/source/_docs/configuration/secrets.markdown similarity index 100% rename from source/_topics/secrets.markdown rename to source/_docs/configuration/secrets.markdown diff --git a/source/_topics/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown similarity index 100% rename from source/_topics/splitting_configuration.markdown rename to source/_docs/configuration/splitting_configuration.markdown diff --git a/source/_topics/templating.markdown b/source/_docs/configuration/templating.markdown similarity index 100% rename from source/_topics/templating.markdown rename to source/_docs/configuration/templating.markdown diff --git a/source/_topics/events.markdown b/source/_docs/events.markdown similarity index 100% rename from source/_topics/events.markdown rename to source/_docs/events.markdown diff --git a/source/_topics/group_visibility.markdown b/source/_docs/group_visibility.markdown similarity index 100% rename from source/_topics/group_visibility.markdown rename to source/_docs/group_visibility.markdown diff --git a/source/_topics/platform_options.markdown b/source/_docs/platform_options.markdown similarity index 100% rename from source/_topics/platform_options.markdown rename to source/_docs/platform_options.markdown diff --git a/source/_topics/state_object.markdown b/source/_docs/state_object.markdown similarity index 100% rename from source/_topics/state_object.markdown rename to source/_docs/state_object.markdown diff --git a/source/_ecosystem/appdaemon.markdown b/source/appdaemon.markdown similarity index 100% rename from source/_ecosystem/appdaemon.markdown rename to source/appdaemon.markdown diff --git a/source/_ecosystem/appdaemon/api.markdown b/source/appdaemon/api.markdown similarity index 100% rename from source/_ecosystem/appdaemon/api.markdown rename to source/appdaemon/api.markdown diff --git a/source/_ecosystem/appdaemon/configuration.markdown b/source/appdaemon/configuration.markdown similarity index 100% rename from source/_ecosystem/appdaemon/configuration.markdown rename to source/appdaemon/configuration.markdown diff --git a/source/_ecosystem/appdaemon/example_apps.markdown b/source/appdaemon/example_apps.markdown similarity index 100% rename from source/_ecosystem/appdaemon/example_apps.markdown rename to source/appdaemon/example_apps.markdown diff --git a/source/_ecosystem/appdaemon/installation.markdown b/source/appdaemon/installation.markdown similarity index 100% rename from source/_ecosystem/appdaemon/installation.markdown rename to source/appdaemon/installation.markdown diff --git a/source/_ecosystem/appdaemon/operation.markdown b/source/appdaemon/operation.markdown similarity index 100% rename from source/_ecosystem/appdaemon/operation.markdown rename to source/appdaemon/operation.markdown diff --git a/source/_ecosystem/appdaemon/reboot.markdown b/source/appdaemon/reboot.markdown similarity index 100% rename from source/_ecosystem/appdaemon/reboot.markdown rename to source/appdaemon/reboot.markdown diff --git a/source/_ecosystem/appdaemon/running.markdown b/source/appdaemon/running.markdown similarity index 100% rename from source/_ecosystem/appdaemon/running.markdown rename to source/appdaemon/running.markdown diff --git a/source/_ecosystem/appdaemon/tutorial.markdown b/source/appdaemon/tutorial.markdown similarity index 100% rename from source/_ecosystem/appdaemon/tutorial.markdown rename to source/appdaemon/tutorial.markdown diff --git a/source/_ecosystem/appdaemon/updating.markdown b/source/appdaemon/updating.markdown similarity index 100% rename from source/_ecosystem/appdaemon/updating.markdown rename to source/appdaemon/updating.markdown diff --git a/source/_ecosystem/appdaemon/windows.markdown b/source/appdaemon/windows.markdown similarity index 100% rename from source/_ecosystem/appdaemon/windows.markdown rename to source/appdaemon/windows.markdown diff --git a/source/details/index.markdown b/source/details/index.markdown deleted file mode 100644 index ff2fccd135e3..000000000000 --- a/source/details/index.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: page -title: "Details Topics" -description: "Details about Home Assistant." -date: 2016-10-20 12:00 -0800 -sidebar: false -comments: false -sharing: true -footer: true -regenerate: true -hide_github_edit: true ---- - -This page is a collection of further details about Home Assistant. - -{% assign details = site.details | sort: 'title' %} - -{% for detail in details %} -* [{{detail.title}}]({{detail.url}}) -{% endfor %} diff --git a/source/ecosystem/index.markdown b/source/ecosystem/index.markdown deleted file mode 100644 index 0af82796dab7..000000000000 --- a/source/ecosystem/index.markdown +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: page -title: "Ecosystem" -description: "External tools for Home Assistant" -date: 2016-10-26 00:46 -sidebar: true -comments: false -sharing: true -footer: true -hide_github_edit: true ---- - -Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems. Use the sidebar to discover documentation for projects. diff --git a/source/_ecosystem/hadashboard.markdown b/source/hadashboard.markdown similarity index 100% rename from source/_ecosystem/hadashboard.markdown rename to source/hadashboard.markdown diff --git a/source/_ecosystem/hadashboard/dash_config.markdown b/source/hadashboard/dash_config.markdown similarity index 100% rename from source/_ecosystem/hadashboard/dash_config.markdown rename to source/hadashboard/dash_config.markdown diff --git a/source/_ecosystem/hadashboard/hapush.markdown b/source/hadashboard/hapush.markdown similarity index 100% rename from source/_ecosystem/hadashboard/hapush.markdown rename to source/hadashboard/hapush.markdown diff --git a/source/_ecosystem/hadashboard/installation.markdown b/source/hadashboard/installation.markdown similarity index 100% rename from source/_ecosystem/hadashboard/installation.markdown rename to source/hadashboard/installation.markdown diff --git a/source/_ecosystem/hadashboard/reboot.markdown b/source/hadashboard/reboot.markdown similarity index 100% rename from source/_ecosystem/hadashboard/reboot.markdown rename to source/hadashboard/reboot.markdown diff --git a/source/_ecosystem/hadashboard/updating.markdown b/source/hadashboard/updating.markdown similarity index 100% rename from source/_ecosystem/hadashboard/updating.markdown rename to source/hadashboard/updating.markdown diff --git a/source/_ecosystem/ios.markdown b/source/ios.markdown similarity index 100% rename from source/_ecosystem/ios.markdown rename to source/ios.markdown diff --git a/source/_ecosystem/ios/devices_file.markdown b/source/ios/devices_file.markdown similarity index 100% rename from source/_ecosystem/ios/devices_file.markdown rename to source/ios/devices_file.markdown diff --git a/source/_ecosystem/ios/features.markdown b/source/ios/features.markdown similarity index 100% rename from source/_ecosystem/ios/features.markdown rename to source/ios/features.markdown diff --git a/source/_ecosystem/ios/integration.markdown b/source/ios/integration.markdown similarity index 100% rename from source/_ecosystem/ios/integration.markdown rename to source/ios/integration.markdown diff --git a/source/_ecosystem/ios/location.markdown b/source/ios/location.markdown similarity index 100% rename from source/_ecosystem/ios/location.markdown rename to source/ios/location.markdown diff --git a/source/_ecosystem/ios/notifications.markdown b/source/ios/notifications.markdown similarity index 100% rename from source/_ecosystem/ios/notifications.markdown rename to source/ios/notifications.markdown diff --git a/source/_ecosystem/ios/notifications/actions.markdown b/source/ios/notifications/actions.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/actions.markdown rename to source/ios/notifications/actions.markdown diff --git a/source/_ecosystem/ios/notifications/architecture.markdown b/source/ios/notifications/architecture.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/architecture.markdown rename to source/ios/notifications/architecture.markdown diff --git a/source/_ecosystem/ios/notifications/attachments.markdown b/source/ios/notifications/attachments.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/attachments.markdown rename to source/ios/notifications/attachments.markdown diff --git a/source/_ecosystem/ios/notifications/basic.markdown b/source/ios/notifications/basic.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/basic.markdown rename to source/ios/notifications/basic.markdown diff --git a/source/_ecosystem/ios/notifications/content_extensions.markdown b/source/ios/notifications/content_extensions.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/content_extensions.markdown rename to source/ios/notifications/content_extensions.markdown diff --git a/source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown b/source/ios/notifications/privacy_security_rate_limits.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown rename to source/ios/notifications/privacy_security_rate_limits.markdown diff --git a/source/_ecosystem/ios/notifications/requesting_location_updates.markdown b/source/ios/notifications/requesting_location_updates.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/requesting_location_updates.markdown rename to source/ios/notifications/requesting_location_updates.markdown diff --git a/source/_ecosystem/ios/notifications/sounds.markdown b/source/ios/notifications/sounds.markdown similarity index 100% rename from source/_ecosystem/ios/notifications/sounds.markdown rename to source/ios/notifications/sounds.markdown diff --git a/source/_ecosystem/ios/requirements.markdown b/source/ios/requirements.markdown similarity index 100% rename from source/_ecosystem/ios/requirements.markdown rename to source/ios/requirements.markdown diff --git a/source/_ecosystem/nginx.markdown b/source/nginx.markdown similarity index 100% rename from source/_ecosystem/nginx.markdown rename to source/nginx.markdown diff --git a/source/_ecosystem/notebooks.markdown b/source/notebooks.markdown similarity index 100% rename from source/_ecosystem/notebooks.markdown rename to source/notebooks.markdown diff --git a/source/_ecosystem/notebooks/api.markdown b/source/notebooks/api.markdown similarity index 100% rename from source/_ecosystem/notebooks/api.markdown rename to source/notebooks/api.markdown diff --git a/source/_ecosystem/notebooks/database.markdown b/source/notebooks/database.markdown similarity index 100% rename from source/_ecosystem/notebooks/database.markdown rename to source/notebooks/database.markdown diff --git a/source/_ecosystem/notebooks/graph.markdown b/source/notebooks/graph.markdown similarity index 100% rename from source/_ecosystem/notebooks/graph.markdown rename to source/notebooks/graph.markdown diff --git a/source/_ecosystem/notebooks/installation.markdown b/source/notebooks/installation.markdown similarity index 100% rename from source/_ecosystem/notebooks/installation.markdown rename to source/notebooks/installation.markdown diff --git a/source/_ecosystem/notebooks/stats.markdown b/source/notebooks/stats.markdown similarity index 100% rename from source/_ecosystem/notebooks/stats.markdown rename to source/notebooks/stats.markdown diff --git a/source/_ecosystem/scenegen.markdown b/source/scenegen.markdown similarity index 100% rename from source/_ecosystem/scenegen.markdown rename to source/scenegen.markdown diff --git a/source/_ecosystem/synology.markdown b/source/synology.markdown similarity index 100% rename from source/_ecosystem/synology.markdown rename to source/synology.markdown diff --git a/source/topics/index.markdown b/source/topics/index.markdown deleted file mode 100644 index 421b32150415..000000000000 --- a/source/topics/index.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: page -title: "Advanced Topics" -description: "Documentation about the more advanced features in Home Assistant." -date: 2016-03-12 12:00 -0800 -sidebar: false -comments: false -sharing: true -footer: true -regenerate: true -hide_github_edit: true ---- - -Home Assistant is built from many small building blocks that together offer a powerful and customizable system. This page is a collection of the more advanced topics. - -{% assign topics = site.topics | sort: 'title' %} - -{% for topic in topics %} -* [{{topic.title}}]({{topic.url}}) -{% endfor %} From 015a28ce571ef74bf7bcd5b18e41f8a2e961b015 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:21:13 +0100 Subject: [PATCH 06/51] Enable sidebar --- source/_docs/configuration/packages.markdown | 2 +- source/_docs/configuration/secrets.markdown | 2 +- source/_docs/configuration/splitting_configuration.markdown | 2 +- source/_docs/configuration/templating.markdown | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown index 369ba6d3443a..e93886efbd85 100644 --- a/source/_docs/configuration/packages.markdown +++ b/source/_docs/configuration/packages.markdown @@ -3,7 +3,7 @@ layout: page title: "Packages" description: "Describes all there is to know about configuration packages in Home Assistant." date: 2017-01-10 20:00 +0200 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index 60129c98ab59..325987909710 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -3,7 +3,7 @@ layout: page title: "Storing secrets" description: "Storing secrets outside of your configuration.yaml." date: 2016-07-01 08:30 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown index 5a0d63ac791c..396a08b76b79 100644 --- a/source/_docs/configuration/splitting_configuration.markdown +++ b/source/_docs/configuration/splitting_configuration.markdown @@ -3,7 +3,7 @@ layout: page title: "Splitting up the configuration" description: "Splitting the configuration.yaml into several files." date: 2016-03-25 23:30 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index e2f06762bdd6..a83aee8c3fd5 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -3,7 +3,7 @@ layout: page title: "Templating" description: "Instructions how to use the templating feature of Home Assistant." date: 2015-12-12 12:00 -sidebar: false +sidebar: true comments: false sharing: true footer: true From 9001808a3937e830ec3cb0de38b43326794823d4 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:41:29 +0100 Subject: [PATCH 07/51] Move content --- source/_docs/{ => configuration}/events.markdown | 0 source/_docs/{ => configuration}/group_visibility.markdown | 0 source/_docs/{ => configuration}/platform_options.markdown | 0 source/_docs/{ => configuration}/state_object.markdown | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename source/_docs/{ => configuration}/events.markdown (100%) rename source/_docs/{ => configuration}/group_visibility.markdown (100%) rename source/_docs/{ => configuration}/platform_options.markdown (100%) rename source/_docs/{ => configuration}/state_object.markdown (100%) diff --git a/source/_docs/events.markdown b/source/_docs/configuration/events.markdown similarity index 100% rename from source/_docs/events.markdown rename to source/_docs/configuration/events.markdown diff --git a/source/_docs/group_visibility.markdown b/source/_docs/configuration/group_visibility.markdown similarity index 100% rename from source/_docs/group_visibility.markdown rename to source/_docs/configuration/group_visibility.markdown diff --git a/source/_docs/platform_options.markdown b/source/_docs/configuration/platform_options.markdown similarity index 100% rename from source/_docs/platform_options.markdown rename to source/_docs/configuration/platform_options.markdown diff --git a/source/_docs/state_object.markdown b/source/_docs/configuration/state_object.markdown similarity index 100% rename from source/_docs/state_object.markdown rename to source/_docs/configuration/state_object.markdown From 81e1a8b201a0c24bca67a2ec828275b1c66f5836 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:44:00 +0100 Subject: [PATCH 08/51] Update links --- source/_docs/hassbian.markdown | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_docs/hassbian.markdown b/source/_docs/hassbian.markdown index 969eaad57c38..d4033ea3f5b8 100644 --- a/source/_docs/hassbian.markdown +++ b/source/_docs/hassbian.markdown @@ -16,7 +16,7 @@ Hassbian is our customized operating system for the Raspberry Pi 3. It is the ea - [Pi specific integrations][integrations] - [Learn how to perform common tasks][common] -[install]: /getting-started/hassbian-installation/ -[customize]: /getting-started/hassbian-customization/ -[common]: /getting-started/hassbian-common-tasks/ -[integrations]: /getting-started/hassbian-integrations/ +[install]: /docs/hassbian-installation/ +[customize]: /docs/hassbian/customization/ +[common]: /docs/hassbian/common-tasks/ +[integrations]: /docs/hassbian/integrations/ From f854f43c268388f5215af5a1b6253e503cc208c6 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:44:25 +0100 Subject: [PATCH 09/51] Remove wizard stuff --- source/_docs/installation/docker.markdown | 11 ------ source/_docs/installation/python.markdown | 25 +----------- .../raspberry-pi-all-in-one.markdown | 6 +-- .../_docs/installation/raspberry-pi.markdown | 39 +++++++------------ source/_docs/installation/synology.markdown | 17 -------- source/_docs/installation/vagrant.markdown | 12 ------ 6 files changed, 19 insertions(+), 91 deletions(-) diff --git a/source/_docs/installation/docker.markdown b/source/_docs/installation/docker.markdown index d1c5221b7e64..0823ca99163f 100644 --- a/source/_docs/installation/docker.markdown +++ b/source/_docs/installation/docker.markdown @@ -29,14 +29,3 @@ To do that you have 2 options. 1. You can go to the service developer tool icon service developer tools, select the service `homeassistant/restart` and click "Call Service". 2. Or you can restart it from an terminal by running `docker restart home-assistant` -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. - - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant. - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting. - -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/_docs/installation/python.markdown b/source/_docs/installation/python.markdown index d4ea0f5f3626..32bf1f9301a6 100644 --- a/source/_docs/installation/python.markdown +++ b/source/_docs/installation/python.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Installing and running Home Assistant on your local machine is easy. The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least Python 3.5 and for other operating systems at least Python 3.4.2. +Installing and running Home Assistant on your local machine is easy. The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least **Python 3.5** and for other operating systems at least **Python 3.4.2**. Once installed, execute the following code in a console: @@ -23,7 +23,7 @@ Running these commands will: - Install Home Assistant - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123) -If you're running a Linux-based platform, we suggest you follow the [VirtualEnv Linux instructions][virtualenv] to avoid using root. +If you're running a Linux-based platform, we suggest you follow the [VirtualEnv Linux instructions][/docs/installation/virtualenv/] to avoid using root. Video tutorials of this process for various operating systems are available here: @@ -31,24 +31,3 @@ Video tutorials of this process for various operating systems are available here - [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls) - [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0) -### {% linkable_title Updating %} - -To update Home Assistant to the latest release check the [Updating section](/getting-started/updating/). - -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions - - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting - -### {% linkable_title What's next? %} - -To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo). - -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) - -[virtualenv]: /getting-started/installation-virtualenv/ diff --git a/source/_docs/installation/raspberry-pi-all-in-one.markdown b/source/_docs/installation/raspberry-pi-all-in-one.markdown index 0f5ec4ca1ff6..f2655a4909ee 100644 --- a/source/_docs/installation/raspberry-pi-all-in-one.markdown +++ b/source/_docs/installation/raspberry-pi-all-in-one.markdown @@ -96,16 +96,16 @@ To launch the OZWCP web application: * Specify your zwave controller, for example `/dev/ttyACM0` and hit initialize

- If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/` +If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/`

- Don't check the USB box regardless of using a USB based device. +Don't check the USB box regardless of using a USB based device.

### {% linkable_title Using the GPIOs %} -The (**homeassistant**)user is added to the GPIO group as part of the install now. +The (**homeassistant**) user is added to the GPIO group as part of the install now. ### {% linkable_title WinSCP %} diff --git a/source/_docs/installation/raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown index 5c58622a791f..8447f5f2e163 100644 --- a/source/_docs/installation/raspberry-pi.markdown +++ b/source/_docs/installation/raspberry-pi.markdown @@ -9,38 +9,43 @@ sharing: true footer: true --- -This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). -The installation will be installed in a [Virtual Environment](/getting-started/installation-virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite. +This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite. + +Connect to the Raspberry Pi over SSH. Default password is `raspberry`. +You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/). -Connect to the Raspberry Pi over ssh. Default password is `raspberry`. -You will need to enable ssh access. The raspberry pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/). ```bash $ ssh pi@ipadress ``` Changing the default password is encouraged. + ```bash $ passwd ``` Update the system. + ```bash $ sudo apt-get update $ sudo apt-get upgrade -y ``` Install the dependencies. + ```bash $ sudo apt-get install python3 python3-venv python3-pip ``` -Add an account for Home Assistant called `homeassistant`. +Add an account for Home Assistant called `homeassistant`. Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory. + ```bash $ sudo useradd -rm homeassistant ``` Next we will create a directory for the installation of Home Assistant and change the owner to the `homeassistant` account. + ```bash $ cd /srv $ sudo mkdir homeassistant @@ -48,6 +53,7 @@ $ sudo chown homeassistant:homeassistant homeassistant ``` Next up is to create and change to a virtual environment for Home Assistant. This will be done as the `homeassistant` account. + ```bash $ sudo su -s /bin/bash homeassistant $ cd /srv/homeassistant @@ -55,33 +61,16 @@ $ python3 -m venv . $ source bin/activate ``` Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant. + ```bash (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant ``` Start Home Assistant for the first time. This will complete the installation, create the `.homeasssistant` configuration directory in the `/home/homeassistant` directory and install any basic dependencies. + ```bash (homeassistant) $ hass ``` -You can now reach your installation on your raspberry pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123). - -For instruction on how to configure Home Assistant continue on with [Configuring Home Assistant](/getting-started/configuration/). - -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. - - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant. - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting. - -### {% linkable_title What's next %} - -If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-systemd/). - -To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo). +You can now reach your installation on your Raspberry Pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123). -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/_docs/installation/synology.markdown b/source/_docs/installation/synology.markdown index 114d3629055e..073bda4ee15b 100644 --- a/source/_docs/installation/synology.markdown +++ b/source/_docs/installation/synology.markdown @@ -225,20 +225,3 @@ $ sudo /volume1/homeassistant/hass-daemon restart $ /volume1/@appstore/py3k/usr/local/bin/python3 -m pip install --upgrade homeassistant ``` -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. - - [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant. - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting. - -### {% linkable_title What's next %} - -If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-synology/). - -To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo). - -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/_docs/installation/vagrant.markdown b/source/_docs/installation/vagrant.markdown index e17b06efe72b..c5251f5c6614 100644 --- a/source/_docs/installation/vagrant.markdown +++ b/source/_docs/installation/vagrant.markdown @@ -86,15 +86,3 @@ $ rm setup_done ; vagrant destroy -f You can now recreate a completely new Vagrant host with `vagrant up` - -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. - - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant. - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting. - -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) From a03037c503cfe2236d4b342525acb32d460f5d65 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 09:47:40 +0100 Subject: [PATCH 10/51] Enable sidebar --- source/_docs/configuration/events.markdown | 2 +- source/_docs/configuration/group_visibility.markdown | 2 +- source/_docs/configuration/platform_options.markdown | 2 +- source/_docs/configuration/state_object.markdown | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_docs/configuration/events.markdown b/source/_docs/configuration/events.markdown index f3d5d8b4e7f1..c5ecaeb5a253 100644 --- a/source/_docs/configuration/events.markdown +++ b/source/_docs/configuration/events.markdown @@ -3,7 +3,7 @@ layout: page title: "Events" description: "Describes all there is to know about events in Home Assistant." date: 2016-03-12 12:00 -0800 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/group_visibility.markdown b/source/_docs/configuration/group_visibility.markdown index a312ced75885..2a325fc8d3f0 100644 --- a/source/_docs/configuration/group_visibility.markdown +++ b/source/_docs/configuration/group_visibility.markdown @@ -3,7 +3,7 @@ layout: page title: "Group Visibility" description: "Instructions how to change group visibility using automations." date: 2016-10-29 13:00 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/platform_options.markdown b/source/_docs/configuration/platform_options.markdown index f8cd217c687c..eb8f1300c22e 100644 --- a/source/_docs/configuration/platform_options.markdown +++ b/source/_docs/configuration/platform_options.markdown @@ -3,7 +3,7 @@ layout: page title: "Entity component platform options" description: "Shows how to customize polling interval for any component via configuration.yaml." date: 2016-02-12 23:17 -0800 -sidebar: false +sidebar: true comments: false sharing: true footer: true diff --git a/source/_docs/configuration/state_object.markdown b/source/_docs/configuration/state_object.markdown index ca4f6827bfa6..d7c3d78aeb75 100644 --- a/source/_docs/configuration/state_object.markdown +++ b/source/_docs/configuration/state_object.markdown @@ -3,7 +3,7 @@ layout: page title: "State Objects" description: "Describes all there is to know about state objects in Home Assistant." date: 2016-03-12 12:00 -0800 -sidebar: false +sidebar: true comments: false sharing: true footer: true From a6957e21616046c99fb84dc5b880e34d9b812b87 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:01:39 +0100 Subject: [PATCH 11/51] Minor changes --- source/_components/zwave.markdown | 9 +++++++-- source/_docs/z-wave.markdown | 1 - 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/source/_components/zwave.markdown b/source/_components/zwave.markdown index 5615187a21f9..dd7ba38a0ce0 100644 --- a/source/_components/zwave.markdown +++ b/source/_components/zwave.markdown @@ -12,6 +12,11 @@ ha_category: Hub featured: true --- -Please see the [getting started section] for in-depth documentation on how to use the Z-Wave component. +The [Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Please see the [Z-Wave getting started section](/docs/z-wave/) for in-depth documentation on how to use and setup the Z-Wave component. -[getting started section]: /getting-started/z-wave/ +If you have setup the requirements, then add the following entry `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +zwave: +``` diff --git a/source/_docs/z-wave.markdown b/source/_docs/z-wave.markdown index 9e085b17da72..8e5786e754b1 100644 --- a/source/_docs/z-wave.markdown +++ b/source/_docs/z-wave.markdown @@ -65,7 +65,6 @@ If you followed along with setting up a virtual environment, your path will be: /srv/homeassistant/python-openzwave/openzwave/config ``` - ### {% linkable_title Configuration %} ```yaml From 69fe8cb1ee4f4f0f247c6e08542810d2be8bdd88 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:01:51 +0100 Subject: [PATCH 12/51] Move MQTT parts to /docs --- .../mqtt_birth_will.markdown => _docs/mqtt/birth_will.markdown} | 0 .../mqtt_broker.markdown => _docs/mqtt/broker.markdown} | 0 .../mqtt_certificate.markdown => _docs/mqtt/certificate.markdown} | 0 .../mqtt_discovery.markdown => _docs/mqtt/discovery.markdown} | 0 .../mqtt_logging.markdown => _docs/mqtt/logging.markdown} | 0 .../mqtt/processing_json.markdown} | 0 .../mqtt_service.markdown => _docs/mqtt/service.markdown} | 0 .../mqtt_testing.markdown => _docs/mqtt/testing.markdown} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename source/{_components/mqtt_birth_will.markdown => _docs/mqtt/birth_will.markdown} (100%) rename source/{_components/mqtt_broker.markdown => _docs/mqtt/broker.markdown} (100%) rename source/{_components/mqtt_certificate.markdown => _docs/mqtt/certificate.markdown} (100%) rename source/{_components/mqtt_discovery.markdown => _docs/mqtt/discovery.markdown} (100%) rename source/{_components/mqtt_logging.markdown => _docs/mqtt/logging.markdown} (100%) rename source/{_components/mqtt_processing_json.markdown => _docs/mqtt/processing_json.markdown} (100%) rename source/{_components/mqtt_service.markdown => _docs/mqtt/service.markdown} (100%) rename source/{_components/mqtt_testing.markdown => _docs/mqtt/testing.markdown} (100%) diff --git a/source/_components/mqtt_birth_will.markdown b/source/_docs/mqtt/birth_will.markdown similarity index 100% rename from source/_components/mqtt_birth_will.markdown rename to source/_docs/mqtt/birth_will.markdown diff --git a/source/_components/mqtt_broker.markdown b/source/_docs/mqtt/broker.markdown similarity index 100% rename from source/_components/mqtt_broker.markdown rename to source/_docs/mqtt/broker.markdown diff --git a/source/_components/mqtt_certificate.markdown b/source/_docs/mqtt/certificate.markdown similarity index 100% rename from source/_components/mqtt_certificate.markdown rename to source/_docs/mqtt/certificate.markdown diff --git a/source/_components/mqtt_discovery.markdown b/source/_docs/mqtt/discovery.markdown similarity index 100% rename from source/_components/mqtt_discovery.markdown rename to source/_docs/mqtt/discovery.markdown diff --git a/source/_components/mqtt_logging.markdown b/source/_docs/mqtt/logging.markdown similarity index 100% rename from source/_components/mqtt_logging.markdown rename to source/_docs/mqtt/logging.markdown diff --git a/source/_components/mqtt_processing_json.markdown b/source/_docs/mqtt/processing_json.markdown similarity index 100% rename from source/_components/mqtt_processing_json.markdown rename to source/_docs/mqtt/processing_json.markdown diff --git a/source/_components/mqtt_service.markdown b/source/_docs/mqtt/service.markdown similarity index 100% rename from source/_components/mqtt_service.markdown rename to source/_docs/mqtt/service.markdown diff --git a/source/_components/mqtt_testing.markdown b/source/_docs/mqtt/testing.markdown similarity index 100% rename from source/_components/mqtt_testing.markdown rename to source/_docs/mqtt/testing.markdown From feac838bb1aa63d477c4ef8c6fdd0aca2f640074 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:02:25 +0100 Subject: [PATCH 13/51] update links --- source/_components/mqtt.markdown | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index e4e3c9549be4..84d65da90d34 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -16,7 +16,7 @@ ha_iot_class: depends MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. -Your first step to get MQTT and Home Assistant working is the choose a [broker](/components/mqtt_broker). +Your first step to get MQTT and Home Assistant working is the choose a [broker](/docs/mqtt/broker). To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/components/mqtt_broker#embedded-broker): @@ -35,12 +35,12 @@ mqtt: ## {% linkable_title Additional features %} -- [Certificate](/components/mqtt_certificate/) -- [Discovery](/components/mqtt_discovery/) -- [Publish service](/components/mqtt_service/) -- [Birth and last will messages](/components/mqtt_birth_will) -- [Testing your setup](/components/mqtt_testing/) -- [Logging](/components/mqtt_logging/) -- [Processing JSON](/components/mqtt_processing_json/) +- [Certificate](/docs/mqtt/certificate/) +- [Discovery](/docs/mqtt/discovery/) +- [Publish service](/docs/mqtt/service/) +- [Birth and last will messages](/docs/mqtt/birth_will) +- [Testing your setup](/docs/mqtt/testing/) +- [Logging](/docs/mqtt/logging/) +- [Processing JSON](/docs/mqtt/processing_json/) See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component. From ec4c091e2453817b16df59e8fc17cb896a6ac8f6 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:08:15 +0100 Subject: [PATCH 14/51] Update links and sync content --- source/_components/mqtt.markdown | 5 ++--- source/_docs/mqtt.markdown | 33 ++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 source/_docs/mqtt.markdown diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index 84d65da90d34..31287d3128bb 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -18,14 +18,14 @@ MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things Your first step to get MQTT and Home Assistant working is the choose a [broker](/docs/mqtt/broker). -To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/components/mqtt_broker#embedded-broker): +To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/docs/mqtt/broker#embedded-broker): ```yaml # Example configuration.yaml entry mqtt: ``` -To connect to your [own MQTT broker](/components/mqtt_broker#run-your-own): +To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own): ```yaml # Example configuration.yaml entry @@ -43,4 +43,3 @@ mqtt: - [Logging](/docs/mqtt/logging/) - [Processing JSON](/docs/mqtt/processing_json/) -See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component. diff --git a/source/_docs/mqtt.markdown b/source/_docs/mqtt.markdown new file mode 100644 index 000000000000..630d50eca65f --- /dev/null +++ b/source/_docs/mqtt.markdown @@ -0,0 +1,33 @@ +--- +layout: page +title: "MQTT" +description: "Details about the MQTT support of Home Assistant." +date: 2017-02-15 08:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport. + +To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/docs/mqtt/broker#embedded-broker): + +```yaml +# Example configuration.yaml entry +mqtt: +``` + +For other setup methods, please refer to the [MQTT broker](/docs/mqtt/broker) documentation. + +## {% linkable_title Additional features %} + +- [Certificate](/docs/mqtt/certificate/) +- [Discovery](/docs/mqtt/discovery/) +- [Publish service](/docs/mqtt/service/) +- [Birth and last will messages](/docs/mqtt/birth_will) +- [Testing your setup](/docs/mqtt/testing/) +- [Logging](/docs/mqtt/logging/) +- [Processing JSON](/docs/mqtt/processing_json/) + +See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component. From e44111e102a93564d3b40ca2ae77f62c9e90f8ec Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:15:01 +0100 Subject: [PATCH 15/51] Fix link --- source/_components/mqtt.markdown | 2 +- source/_docs/mqtt.markdown | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index 31287d3128bb..e4d77f8121e4 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -38,7 +38,7 @@ mqtt: - [Certificate](/docs/mqtt/certificate/) - [Discovery](/docs/mqtt/discovery/) - [Publish service](/docs/mqtt/service/) -- [Birth and last will messages](/docs/mqtt/birth_will) +- [Birth and last will messages](/docs/mqtt/birth_will/) - [Testing your setup](/docs/mqtt/testing/) - [Logging](/docs/mqtt/logging/) - [Processing JSON](/docs/mqtt/processing_json/) diff --git a/source/_docs/mqtt.markdown b/source/_docs/mqtt.markdown index 630d50eca65f..072561f99122 100644 --- a/source/_docs/mqtt.markdown +++ b/source/_docs/mqtt.markdown @@ -25,7 +25,7 @@ For other setup methods, please refer to the [MQTT broker](/docs/mqtt/broker) do - [Certificate](/docs/mqtt/certificate/) - [Discovery](/docs/mqtt/discovery/) - [Publish service](/docs/mqtt/service/) -- [Birth and last will messages](/docs/mqtt/birth_will) +- [Birth and last will messages](/docs/mqtt/birth_will/) - [Testing your setup](/docs/mqtt/testing/) - [Logging](/docs/mqtt/logging/) - [Processing JSON](/docs/mqtt/processing_json/) From 895bacbd4238fa607dce50edf0ab4baec78eec90 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:19:37 +0100 Subject: [PATCH 16/51] Enable sidebar --- source/_docs/mqtt/broker.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_docs/mqtt/broker.markdown b/source/_docs/mqtt/broker.markdown index 70ef71272cad..2c84c8b05462 100644 --- a/source/_docs/mqtt/broker.markdown +++ b/source/_docs/mqtt/broker.markdown @@ -3,7 +3,7 @@ layout: page title: "MQTT Brokers" description: "Instructions how to setup MQTT brokers for Home Assistant." date: 2015-08-07 18:00 -sidebar: False +sidebar: true comments: false sharing: true footer: true From d8ab0a1ff5c8a21ec05fdad388a9ed84cd84a88d Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:23:37 +0100 Subject: [PATCH 17/51] Remove navigation --- source/_docs/hassbian/installation.markdown | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/source/_docs/hassbian/installation.markdown b/source/_docs/hassbian/installation.markdown index 6ed77c596424..7d09be5914dc 100644 --- a/source/_docs/hassbian/installation.markdown +++ b/source/_docs/hassbian/installation.markdown @@ -12,7 +12,7 @@ redirect_from: /getting-started/installation-raspberry-pi-image/ The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~10 minutes). - 1. [Download the Hassbian 1.1 image][image-download] (359MB) + 1. [Download the Hassbian 1.1 image][image-download] (359 MB) 2. Use [Etcher][etcher] to flash the image to your SD card 3. Ensure your Raspberry Pi has access to the internet. 4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes. @@ -32,20 +32,6 @@ The following extras are included on the image: - Home Assistant will be started as a service run by the user `homeassistant` - The configuration is located at `/home/homeassistant/.homeassistant` - -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. - -In addition to this site, check out these sources for additional help: - - - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. - - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant. - - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting. - -### [Learn how to configure Home Assistant »](/getting-started/configuration/) -### [Learn common tasks in Hassbian »](/getting-started/hassbian-common-tasks/) - [image-download]: https://github.com/home-assistant/pi-gen/releases/download/v1.1/image_2017-02-03-HASSbian.zip [etcher]: https://etcher.io/ [http://hassbian.local:8123]: http://hassbian.local:8123 From ac8d46d47446effe996e4db79b183da824ed22f4 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:46:29 +0100 Subject: [PATCH 18/51] Remove navigation and other minor updates --- source/_docs/installation/troubleshooting.markdown | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/source/_docs/installation/troubleshooting.markdown b/source/_docs/installation/troubleshooting.markdown index 2f1bfcbeb3d0..e049f2ee3e47 100644 --- a/source/_docs/installation/troubleshooting.markdown +++ b/source/_docs/installation/troubleshooting.markdown @@ -41,12 +41,12 @@ This is a known issue if you're on a Mac using Homebrew to install Python. Pleas To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated. #### {% linkable_title No access to the frontend %} -In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and OSX machines may also have issues with this. +In newer Linux distributions (at least Fedora > 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and macOS machines may also have issues with this. -To fix this you will need to open your machine's firewall for TCP traffic over port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here. +To fix this you will need to open your machine's firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here. - [Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7) -- [Mac OSX instructions](https://support.apple.com/en-us/HT201642) +- [macOS instructions](https://support.apple.com/en-us/HT201642) For systems with **firewalld** (Fedora, CentOS/RHEL, etc.): @@ -74,5 +74,3 @@ After upgrading to a new version, you may notice your browser gets stuck at the Android Chrome chrome -> settings -> site settings -> storage -> search for your URL for home assistant-> "clear & reset" - -### [« Back to Getting Started](/getting-started/) From f761fd5f989ad40ec9843ac2719c08dab3d26dd2 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 10:49:45 +0100 Subject: [PATCH 19/51] Update links --- source/_docs/installation/updating.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_docs/installation/updating.markdown b/source/_docs/installation/updating.markdown index a9bf836b894c..06546d3d2e17 100644 --- a/source/_docs/installation/updating.markdown +++ b/source/_docs/installation/updating.markdown @@ -10,7 +10,7 @@ footer: true ---

-The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/getting-started/hassbian-common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/#upgrading), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv/#upgrading-home-assistant). +The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/docs/hassbian/common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/#upgrading), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant).

The default way to update Home Assistant to the latest release, when available, is: @@ -19,10 +19,10 @@ The default way to update Home Assistant to the latest release, when available, $ pip3 install --upgrade homeassistant ``` -After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon (if applicable) +After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/docs/autostart/) daemon (if applicable)

- To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/getting-started/installation-raspberry-pi-image/), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv)t. + To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/docs/hassbian/installation/), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv).

[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant. From de8c9a6c6c01997a22752037e6df852c03e48f12 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 11:35:42 +0100 Subject: [PATCH 20/51] Add overview page --- source/_docs/frontend.markdown | 21 +++++++++++++++++++++ source/_docs/installation.markdown | 12 ++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 source/_docs/frontend.markdown create mode 100644 source/_docs/installation.markdown diff --git a/source/_docs/frontend.markdown b/source/_docs/frontend.markdown new file mode 100644 index 000000000000..2ff5353ac4b6 --- /dev/null +++ b/source/_docs/frontend.markdown @@ -0,0 +1,21 @@ +--- +layout: page +title: "Frontend of Home Assistant" +description: "Frontend of Home Assistant." +date: 2017-03-23 12:50 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The frontend of Home Assistant is built with [Polymer](https://www.polymer-project.org/). + +

+ +

+ +The [User Interface section](/cookbook/#user-interface) can give you some starting points to expand the frontend. + +If you want to work on the frontend, please refer to the [Frontend Development documentation](/developers/frontend/). + diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown new file mode 100644 index 000000000000..ee1d0290ffcb --- /dev/null +++ b/source/_docs/installation.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Installation of Home Assistant" +description: "Instructions how to install Home Assistant to launch on start." +date: 2017-02-15 08:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant provides multiple ways to be installed. From 8bc90c74d76b2ec709d86430c6c03b33e52195ab Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 11:36:22 +0100 Subject: [PATCH 21/51] Make title linkable --- source/_docs/scenegen.markdown | 169 +++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 source/_docs/scenegen.markdown diff --git a/source/_docs/scenegen.markdown b/source/_docs/scenegen.markdown new file mode 100644 index 000000000000..dc62e1621a37 --- /dev/null +++ b/source/_docs/scenegen.markdown @@ -0,0 +1,169 @@ +--- +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 +--- + +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:// -k +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:// -k > 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:// -k --types light,switch +``` + +or: + +``` +./scenegen.py https:// -k --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:// -k --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 +``` + From df63b067d56ea8ae6458d3be55b43647b64aa1d0 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 11:59:04 +0100 Subject: [PATCH 22/51] Update --- source/_docs/installation.markdown | 7 ++++++- source/_docs/installation/python.markdown | 10 ++++------ 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown index ee1d0290ffcb..b85b2ebf9c60 100644 --- a/source/_docs/installation.markdown +++ b/source/_docs/installation.markdown @@ -9,4 +9,9 @@ sharing: true footer: true --- -Home Assistant provides multiple ways to be installed. +Home Assistant provides multiple ways to be installed. If you are a Raspberry Pi owner then the [Hassbian](/docs/hassbian/) is an easy and simple way to run home Assistant. + +The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least **Python 3.5** and for other operating systems at least **Python 3.4.2**. + +It may be needed that you install additional library depending on the platforms/components you want to use. + diff --git a/source/_docs/installation/python.markdown b/source/_docs/installation/python.markdown index 32bf1f9301a6..022fdd0b43b8 100644 --- a/source/_docs/installation/python.markdown +++ b/source/_docs/installation/python.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Installation on your computer" -description: "Step by step guide to install Home Assistant on your computer." +description: "Installation of Home Assistant on your computer." date: 2014-12-18 22:57 sidebar: true comments: false @@ -9,9 +9,7 @@ sharing: true footer: true --- -Installing and running Home Assistant on your local machine is easy. The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least **Python 3.5** and for other operating systems at least **Python 3.4.2**. - -Once installed, execute the following code in a console: +Once Python is installed, execute the following code in a console: ```bash $ pip3 install homeassistant @@ -23,11 +21,11 @@ Running these commands will: - Install Home Assistant - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123) -If you're running a Linux-based platform, we suggest you follow the [VirtualEnv Linux instructions][/docs/installation/virtualenv/] to avoid using root. +If you're running a Linux-based platform, we suggest you follow the [VirtualEnv instructions][/docs/installation/virtualenv/] to avoid using `root`. Video tutorials of this process for various operating systems are available here: - [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY) - - [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls) + - [macOS](https://www.youtube.com/watch?v=hej6ipN86ls) - [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0) From a61bf8f88eea4a7357a7c9731830766f6331a27a Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Wed, 15 Feb 2017 13:09:48 +0100 Subject: [PATCH 23/51] Plit content --- source/_docs/configuration/remote.markdown | 23 ++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 source/_docs/configuration/remote.markdown diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown new file mode 100644 index 000000000000..7f89ccaab288 --- /dev/null +++ b/source/_docs/configuration/remote.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "Remote access" +description: "Setting up remote access for Home Assistant." +date: 2015-03-23 12:50 +sidebar: true +comments: false +sharing: true +footer: true +--- + +If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible. + +The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching ` port forwarding instructions`. + +A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/). + +Remember: Just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post. + +Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/) between your client and the Home Assistant instance. + +For another way to access your Home Assistant frontend, check out [the instructions how to use Tor](/cookbook/tor_configuration/). + From 37a37d60d78c0e5856204d4d19887ac2730e90bd Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 08:14:01 +0100 Subject: [PATCH 24/51] Update links --- source/_docs/configuration/packages.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown index e93886efbd85..dc2dae1482c1 100644 --- a/source/_docs/configuration/packages.markdown +++ b/source/_docs/configuration/packages.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration). +Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/docs/configuration/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/docs/configuration/splitting_configuration). Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as: @@ -88,4 +88,4 @@ homeassistant: ``` This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames. -See the documentation about [splitting the configuration](/topics/splitting_configuration/) for more information about `!include_dir_named` and other include statements that might be helpful. +See the documentation about [splitting the configuration](/docs/configuration/splitting_configuration/) for more information about `!include_dir_named` and other include statements that might be helpful. From 7e41189e8cc53e6b2be6b36645a701b22ecc74de Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 08:14:58 +0100 Subject: [PATCH 25/51] Rearrange content --- source/_docs/frontend.markdown | 2 +- source/_docs/frontend/webserver.markdown | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_docs/frontend.markdown b/source/_docs/frontend.markdown index 2ff5353ac4b6..4c6d26dcabf1 100644 --- a/source/_docs/frontend.markdown +++ b/source/_docs/frontend.markdown @@ -2,7 +2,7 @@ layout: page title: "Frontend of Home Assistant" description: "Frontend of Home Assistant." -date: 2017-03-23 12:50 +date: 2017-02-13 12:50 sidebar: true comments: false sharing: true diff --git a/source/_docs/frontend/webserver.markdown b/source/_docs/frontend/webserver.markdown index cf8cd77df05d..2fc3d17b3f12 100644 --- a/source/_docs/frontend/webserver.markdown +++ b/source/_docs/frontend/webserver.markdown @@ -1,6 +1,6 @@ --- layout: page -title: "Web server" +title: "Web server fingerprint" description: "Use nmap to scan your Home Assistant instance." date: 2016-10-06 08:00 sidebar: true From 36d9d6fb98aaa1d0d0b844abb519ef689e72f9e1 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 08:57:21 +0100 Subject: [PATCH 26/51] New getting-started section --- .../asides/getting_started_navigation.html | 73 +------------------ source/getting-started/automation.markdown | 31 ++++++++ source/getting-started/configuration.markdown | 27 +++++++ source/getting-started/index.markdown | 18 ++--- 4 files changed, 67 insertions(+), 82 deletions(-) create mode 100644 source/getting-started/automation.markdown create mode 100644 source/getting-started/configuration.markdown diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index d43017616593..af6b13736c6a 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -4,75 +4,10 @@

Getting Started Guide

    -
  • - {% active_link /getting-started/ Installation %} -
      -
    • {% active_link /getting-started/installation-python/ Python %}
      • -
    • {% active_link /getting-started/updating/ Updating %}
      • -
    • {% active_link /getting-started/troubleshooting/ Troubleshooting %}
      • -
    -
    • -
  • - {% active_link /getting-started/hassbian/ Hassbian %} -
      -
    • {% active_link /getting-started/hassbian-installation/ Installation %}
      • -
    • {% active_link /getting-started/hassbian-customization/ Customization %}
      • -
    • {% active_link /getting-started/hassbian-common-tasks/ Common tasks %}
      • -
    • {% active_link /getting-started/hassbian-integrations/ Integrations %}
      • -
    • {% active_link /getting-started/hassbian-upgrading/ Upgrading %}
      • -
    -
    • -
  • - {% active_link /getting-started/configuration/ Configuration %} -
      -
    • {% active_link /getting-started/yaml/ YAML %}
      • -
    • {% active_link /getting-started/basic/ Basic information %}
      • -
    • {% active_link /getting-started/devices/ Setting up devices %}
      • -
    • {% active_link /getting-started/customizing-devices/ Customizing devices and services %}
      • -
    • {% active_link /getting-started/presence-detection/ Presence Detection %}
      • -
    • {% active_link /getting-started/troubleshooting-configuration/ Troubleshooting %}
      • -
    • {% active_link /getting-started/securing/ Security Check Points %}
      • -
    -
    • -
  • - {% active_link /getting-started/automation/ Automation %} -
      -
    • {% active_link /getting-started/automation-create-first/ Tutorial %}
      • -
    • {% active_link /getting-started/automation-trigger/ Triggers %}
      • -
    • {% active_link /getting-started/automation-condition/ Conditions %}
      • -
    • {% active_link /getting-started/automation-action/ Actions %}
      • -
    • {% active_link /getting-started/automation-templating/ Templates %}
      • -
    -
    • -
  • - {% active_link /getting-started/scripts/ Scripts %} -
      -
    • {% active_link /getting-started/scripts-service-calls/ Service Calls %}
      • -
    • {% active_link /getting-started/scripts-conditions/ Conditions %}
      • -
    -
    • -
  • - {% active_link /getting-started/z-wave/ Z-Wave %} -
      -
    • {% active_link /getting-started/z-wave-controllers/ Controllers %}
      • -
    • {% active_link /getting-started/z-wave-settings/ Modifying Settings %}
      • -
    • {% active_link /getting-started/z-wave-device-specific/ Device Specific %}
      • -
    -
    • -
  • - {% active_link /getting-started/autostart/ Autostart %} -
      -
    • {% active_link /getting-started/autostart-systemd/ Linux - systemd %}
      • -
    • {% active_link /getting-started/autostart-upstart/ Linux - Upstart %}
      • -
    • {% active_link /getting-started/autostart-init.d/ Linux - init.d %}
      • -
    • {% active_link /getting-started/autostart-macos/ macOS %}
      • -
    • {% active_link /getting-started/autostart-synology/ Synology NAS %}
      • -
    -
    • -
  • {% active_link {{site_root}}/topics/ Advanced Topics %}
    • -
  • {% active_link {{site_root}}/details/ Details %}
    • -
  • {% active_link /getting-started/mobile/ Add to Android/iOS Homescreen %}
    • -
  • {% active_link /getting-started/browsers/ Browser Compatibility List %}
    • +
  • {% active_link /getting-started/ Installation %} +
  • {% active_link /getting-started/configuration/ Configuration %}
    • +
  • {% active_link /getting-started/automation/ Automation %}
    • +
  • {% active_link /getting-started/run/ Run it! %}
diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown new file mode 100644 index 000000000000..a4ea79f91c3f --- /dev/null +++ b/source/getting-started/automation.markdown @@ -0,0 +1,31 @@ +--- +layout: page +title: "Automating Home Assistant" +description: "Instructions to get started with Automation using Home Assistant." +date: 2016-09-26 21:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +When your devices are set up, it's time to put the cherry on the pie: **automation**. Home Assistant offers [a few built-in automations](/components/#automation) – but you'll be using the automation component to set up your own rules, for the most part. + +If you added a random sensor in the previous step then you can use that sensor for your very first automation: + +```yaml +automation: + - alias: Check sensor value and show notification + trigger: + platform: numeric_state + entity_id: sensor.random + above: 10 + action: + service: persistent_notification.create + data: + message: "Sensor value greater than 10" +``` + +For further details about automation, please take a look at the [automation tutorial](/docs/automation/tutorial/) to get started with full-speed or the [automation documentation](/docs/automation/). + +### [Next step: Run Home Assistant »](/getting-started/run/) diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown new file mode 100644 index 000000000000..579435241f70 --- /dev/null +++ b/source/getting-started/configuration.markdown @@ -0,0 +1,27 @@ +--- +layout: page +title: "Configure Home Assistant" +description: "Instructions to get Home Assistant configured." +date: 2016-09-26 21:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +When launched for the first time, Home Assistant will write a default configuration file, called `configuration.yaml`, enabling the web interface and [device discovery](/components/discovery/). It can take up to a minute for your devices to be discovered and appear in the user interface. + +The `configuration.yaml` is written in [YAML](/docs/configuration/yaml/), stored in [`.homeassistant`](/docs/configuration/), and can be modified with a text editor. + +See the [components overview page](/components/) to find sample entries for your devices and services. For a sensor that is showing [random values](/components/sensor.random/), the entry would looks like the sample below: + +```yaml +sensor: + - platform: random +``` + +The [Setting up devices part](/docs/configuration/devices/) of the documentation additional details about adding device and services and [customizization](docs/configuration/customizing-devices/). + +For further details about configuration, please take a look at the [configuration documentation](/docs/configuration/). + +### [Next step: Automate Home Assistant »](/getting-started/automation/) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index fd1e441c5a56..35f028591503 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -12,13 +12,13 @@ footer: true You will need to install Home Assistant before we can get started. You can install Home Assistant on your computer or you can turn a Raspberry Pi into a dedicated Home Assistant hub.
- +
Install Hassbian on your Raspberry Pi 3
 - +
@@ -26,16 +26,8 @@ You will need to install Home Assistant before we can get started. You can insta
-### {% linkable_title Alternative methods %} +For alternative installation methods please take a look at the [installation documentation](/docs/installation/). -For advanced users we have several alternative guides for installing Home Assistant. +If you run into any issues, please see [the troubleshooting page](/docs/installation/troubleshooting/) or [communication channels](/help/). It contains solutions to many commonly encountered issues. -- [Docker](/getting-started/installation-docker/) -- [Manual Raspberry Pi installation](/getting-started/installation-raspberry-pi/) (requires existing Raspbian installation) -- [Raspberry Pi All-In-One Installer Script](/getting-started/installation-raspberry-pi-all-in-one/) (requires existing Raspbian installation) -- [Vagrant](/getting-started/installation-vagrant/) -- [Synology NAS](/getting-started/installation-synology/) -- [Virtualenv Linux](/getting-started/installation-virtualenv/) - -[rpi]: /getting-started/installation-raspberry-pi-image/ -[python]: /getting-started/installation-python/ +### [Next step: Configuring Home Assistant »](/getting-started/configuration/) From 6e819e6a6b8e8a67faa924c9b80664e36827631d Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 08:58:27 +0100 Subject: [PATCH 27/51] Add icons for docs --- source/images/supported_brands/pencil.png | Bin 0 -> 352 bytes source/images/supported_brands/view-dashboard.png | Bin 0 -> 231 bytes 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 source/images/supported_brands/pencil.png create mode 100644 source/images/supported_brands/view-dashboard.png diff --git a/source/images/supported_brands/pencil.png b/source/images/supported_brands/pencil.png new file mode 100644 index 0000000000000000000000000000000000000000..0d17c08ee46767839a18fef1b60b7c7039983308 GIT binary patch literal 352 zcmeAS@N?(olHy`uVBq!ia0vp^1|ZDA1|-9oezpTCwj^(N7a$D;Kb?2i11Zh|kH}&m z?E%JaC$sH9f@KAc=|CE+pW)oQo^T-NwWo_?NXEUlHxBYPIS9BtoF38M_2tmPv^_T( zOfNL|UT9x)i%C4c%3yYZ!<|@Vkbr` z%w6l^^YE<8l>={?@3|cL$PFYk4Hr#qJ9gC}SisQZu<}1Xn}*snm*uSTj+TOr-^-mu z?7wdF?0nI<)~&|t25Dk6rJZ6+f>$ zZvBt{N1Rl=<-L!mAG@Ca{OsdFExFefTpt~|_o+CD+L=4Z+NnFJ+L=1&+Nmli{5k$+ jI>XnB`RAWUr|I{s+i>Ph)r=`XZ!>th`njxgN@xNA_E(Pu literal 0 HcmV?d00001 diff --git a/source/images/supported_brands/view-dashboard.png b/source/images/supported_brands/view-dashboard.png new file mode 100644 index 0000000000000000000000000000000000000000..33c23e2e51591b19f29b793145445d40582295cf GIT binary patch literal 231 zcmeAS@N?(olHy`uVBq!ia0vp^1|ZDA1|-9oezpTCwj^(N7a$D;Kb?2i11Zh|kH}&m z?E%JaC$sH9f@KAc=|CE+pW)oQo^T+i$kW9!B;(%O>yBIv20W}6<3IijzsAgQcSf4d zx!YV5H!ev~@?2tAStfdZ-Mr~4maF!Am@{XvUEo0sPYX0|VTkNn3ie>o)_Uf*H- z&(8B>(M>*`o!eLE)-$nPNVDGX Date: Thu, 16 Feb 2017 08:59:07 +0100 Subject: [PATCH 28/51] Update for new structure --- source/_docs/automation.markdown | 7 +- source/_docs/automation/tutorial.markdown | 113 ++++++++++++++++++++++ 2 files changed, 114 insertions(+), 6 deletions(-) create mode 100644 source/_docs/automation/tutorial.markdown diff --git a/source/_docs/automation.markdown b/source/_docs/automation.markdown index 660b6772a8e6..5c5497b0a132 100644 --- a/source/_docs/automation.markdown +++ b/source/_docs/automation.markdown @@ -9,11 +9,7 @@ sharing: true footer: true --- -When all your devices are set up, it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) – but you'll be using the automation component to set up your own rules, for the most part. - -Home Assistant offers a wide range of automation configurations. In the next few pages, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][cookbook-config]. - -[cookbook-config]: /cookbook/#example-configurationyaml +Home Assistant offers a wide range of automation configurations. In the next few pages, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][/cookbook/#example-configurationyaml]. ### {% linkable_title Automation basics %} @@ -51,4 +47,3 @@ State changes can be used as the source of triggers and the current state can be Actions are all about calling services. To explore the available services open the Services developer tool. Services allow to change anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. -### [Next step: Your First Automation »](/getting-started/automation-create-first/) diff --git a/source/_docs/automation/tutorial.markdown b/source/_docs/automation/tutorial.markdown new file mode 100644 index 000000000000..06276c9dcfbb --- /dev/null +++ b/source/_docs/automation/tutorial.markdown @@ -0,0 +1,113 @@ +--- +layout: page +title: "Your First Automation" +description: "Step by step guiding through making your first automation." +date: 2016-04-24 08:30 +0100 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets** + +In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. + +```yaml +# Example configuration.yaml entry +automation: + alias: Turn on light when sun sets + initial_state: True + hide_entity: False + trigger: + platform: sun + event: sunset + action: + service: light.turn_on +``` + +Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when Home Assistant starts set `initial_state:` to `False`. + +After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home. + +```yaml +# Example configuration.yaml entry +automation: + alias: Turn on light when sun sets + trigger: + platform: sun + event: sunset + offset: "-01:00:00" + condition: + condition: state + entity_id: group.all_devices + state: 'home' + action: + service: light.turn_on +``` + +Now you're happy and all is good. You start to like this automation business and buy some more lights, this time you put them in the bedroom. But what you now realize is that when the sun is setting, the lights in the bedroom are also being turned on! Time to tweak the automation to only turn on the living room lights. + +The first thing you do is to look at the entities in the developer tools (second icon) in the app. You see the names of your lights and you write them down: `light.table_lamp`, `light.bedroom`, `light.ceiling`. + +Instead of hard coding the entity IDs of the lights in the automation rule, we will set up a group. This will allow us to see the living room separate in the app and be able to address it from automation rules. + +So we tweak the config to add the group and have the automation rule only turn on the group. + +```yaml +# Example configuration.yaml entry +group: + living_room: + - light.table_lamp + - light.ceiling + +automation: + alias: Turn on light when sun sets + trigger: + platform: sun + event: sunset + offset: "-01:00:00" + condition: + condition: state + entity_id: group.all_devices + state: 'home' + action: + service: light.turn_on + entity_id: group.living_room +``` + +Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights! + +We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. + +```yaml +# Example configuration.yaml entry +group: + living_room: + - light.table_lamp + - light.ceiling + - switch.christmas_lights + +automation: + alias: Turn on light when sun sets + hide_entity: True + trigger: + platform: sun + event: sunset + offset: "-01:00:00" + condition: + condition: state + entity_id: group.all_devices + state: 'home' + action: + service: homeassistant.turn_on + entity_id: group.living_room +``` + +### {% linkable_title Learn more %} + + - [Triggers](/docs/automation/trigger/) + - [Conditions](/docs/automation/condition/) + - [Actions](/docs/automation/action/) + - [Templating](/docs/automation/templating/) (advanced) + From 5e2360c07f4f6a70ee13ddbe2ac32ba51818a105 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 08:59:56 +0100 Subject: [PATCH 29/51] Update for new structure --- source/_docs/configuration.markdown | 1 - source/_docs/configuration/basic.markdown | 16 ------ .../customizing-devices.markdown | 55 ++++++++++++++++++- source/_docs/configuration/devices.markdown | 7 +-- .../configuration/presence-detection.markdown | 4 +- source/_docs/configuration/yaml.markdown | 1 - 6 files changed, 58 insertions(+), 26 deletions(-) diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index ee68ebb88b2a..0b7a7138ca51 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -33,4 +33,3 @@ If you run into trouble while configuring Home Assistant, have a look at the [co Test any changes to your configuration files from the command line with `hass --script check_config`. This script allows you to test changes without the need to restart Home Assistant.

-### [Next step: Get familiar with YAML »](/getting-started/yaml/) diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index f8cb5b33cc6b..21cfcbeee7c2 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -48,19 +48,3 @@ If you decide to expose your Home Assistant instance to the internet and forget See the [HTTP component documentation](/components/http/) for more options, such as the use of HTTPS encryption. -### {% linkable_title Setting up your phone or tablet %} - -Home Assistant runs as a self-hosted web application and can be pinned to your home screen (with the new W3C standard). If you're on Android, follow [the visual guide]({{site_root}}/getting-started/android/). For other devices, open Home Assistant on your mobile browser and tap the "Add to Home Screen" (or similar) option. -### {% linkable_title Remote access %} - -If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible. - -The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching ` port forwarding instructions`. - -A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/). - -Remember: just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post. - -If you want the very best security, check out [the instructions how to use Tor to access your home](/cookbook/tor_configuration/). - -### [Next step: Setting up devices »](/getting-started/devices/) diff --git a/source/_docs/configuration/customizing-devices.markdown b/source/_docs/configuration/customizing-devices.markdown index 1fb92f1b2a74..15cc891f9985 100644 --- a/source/_docs/configuration/customizing-devices.markdown +++ b/source/_docs/configuration/customizing-devices.markdown @@ -45,6 +45,60 @@ homeassistant: | `assumed_state` | For switches with an assumed state two buttons are shown (turn off, turn on) instead of a switch. By setting `assumed_state` to `false` you will get the default switch icon. | `sensor_class` | Sets the [class of the sensor](/components/binary_sensor/), changing the device state and icon that is displayed on the UI (see below). +### {% linkable_title Advanced example %} + +You can also specify attributes for all devices in a domain, use wildcards, use several entity IDs as a list or comma separated list. + +```yaml +homeassistant: + customize: + - entity_id: sensor + icon: mdi:kettle # Give all sensor the kettle icon + - entity_id: light.family* + hidden: true # Hide all lights that have an ID starting with 'family' + - entity_id: switch.wemo_switch_1,switch.wemo_switch_2,switch.wemo_switch_3 + entity_picture: /local/toaster.jpg # Set picture on multiple devices +``` + +Either `entity_id` must be present in each customization block. + +### {% linkable_title Older format %} + +In the previous version of customize format the keys were the IDs: + +```yaml +homeassistant: + name: Home + unit_system: metric + # etc + + customize: + # Only the 'entity_id' is required. All other options are optional. + sensor.living_room_motion: + hidden: true + thermostat.family_roomfamily_room: + entity_picture: https://example.com/images/nest.jpg + friendly_name: Nest + switch.wemo_switch_1: + friendly_name: Toaster + entity_picture: /local/toaster.jpg + switch.wemo_switch_2: + friendly_name: Kitchen kettle + icon: mdi:kettle + - entity_id: switch.rfxtrx_switch: + assumed_state: false +``` +This format doesn't support comma-separated IDs, wildcards or domain matching. + +The formats can't be mixed +```yaml + # NOT A VALID CONFIGURATION + customize: + sensor.living_room_motion: + hidden: true + - entity_id: thermostat.family_roomfamily_room + friendly_name: Nest +``` ### {% linkable_title Reloading customize %} @@ -54,4 +108,3 @@ Home Assistant offers a service to reload the core configuration while Home Assi New customize information will be applied the next time the state of the entity gets updated.

-### [Next step: Setting up presence detection »](/getting-started/presence-detection/) diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown index a7eb3e82eff1..2a1f912e929b 100644 --- a/source/_docs/configuration/devices.markdown +++ b/source/_docs/configuration/devices.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component]({{site_root}}/components/discovery/) enabled (the default setting). +Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component](/components/discovery/) enabled (the default setting). See the [components overview page](/components/) to find installation instructions for your devices and services. If you can't find support for your favorite device or service, [consider adding support](/developers/add_new_platform/). @@ -53,7 +53,7 @@ camera 2: ### {% linkable_title Grouping devices %} -Once you have several devices set up, it is time to organize them into groups. +Once you have several devices set up, it is time to organize them into groups. Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the Set State page in the Developer Tools (![<>](https://cdn.rawgit.com/Templarian/MaterialDesign/master/icons/svg/code-tags.svg)). ```yaml @@ -65,6 +65,5 @@ group: - media_player.nexus_player ``` -For more details please check the [Group](https://home-assistant.io/components/group/) page. +For more details please check the [Group](/components/group/) page. -### [Next step: Customizing devices and services »](/getting-started/customizing-devices/) diff --git a/source/_docs/configuration/presence-detection.markdown b/source/_docs/configuration/presence-detection.markdown index 38cd1e5f143e..63050fdf19ad 100644 --- a/source/_docs/configuration/presence-detection.markdown +++ b/source/_docs/configuration/presence-detection.markdown @@ -2,7 +2,7 @@ layout: page title: "Setting up presence detection" description: "Instructions how to setup presence detection within Home Assistant." -date: 2015-10-4 12:08 +date: 2015-10-04 12:08 sidebar: true comments: false sharing: true @@ -41,8 +41,6 @@ OwnTracks communicates directly with your MQTT broker; no data will pass through Home Assistant will know the location of your device if you are using OwnTracks. By [setting up zones][zone] you will be able to add names to the locations of your devices. This way you can easily spot on the state page where the people in your house are and use it as [triggers][trigger] and [conditions][condition] for automation. -### [Next step: Setting up automation »](/getting-started/automation/) - [routers]: /components/#presence-detection [nmap]: /components/device_tracker.nmap_tracker/ [ha-owntracks]: /components/device_tracker.owntracks/ diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index 7a5fb2cb7dba..cce574cddecb 100644 --- a/source/_docs/configuration/yaml.markdown +++ b/source/_docs/configuration/yaml.markdown @@ -60,4 +60,3 @@ sensor: state_topic: sensor2/topic ``` -### [Next step: Setting up the basics »](/getting-started/basic/) From 623f1290c9daad2fcc79a40ee964a3235ebd512d Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 09:18:16 +0100 Subject: [PATCH 30/51] Add docs navigation --- source/_includes/asides/docs_navigation.html | 187 +++++++++++++++++++ source/_includes/custom/navigation.html | 2 +- source/_includes/site/sidebar.html | 4 +- 3 files changed, 190 insertions(+), 3 deletions(-) create mode 100644 source/_includes/asides/docs_navigation.html diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html new file mode 100644 index 000000000000..62661e4d2e3e --- /dev/null +++ b/source/_includes/asides/docs_navigation.html @@ -0,0 +1,187 @@ + +
+ {% include edit_github.html %} + +
+

Topics

+
    +
  • + {% active_link /docs/installation/ Installation %} +
      +
    • {% active_link /docs/installation/python/ Python %}
      • +
    • {% active_link /docs/installation/virtualenv/ Python Virtual Env %}
      • +
    • {% active_link /docs/installation/docker/ Docker %}
      • +
    • {% active_link /docs/installation/raspberry-pi/ Raspberry Pi %}
      • +
    • {% active_link /docs/installation/raspberry-pi-all-in-one/ Raspberrry Pi All-in-One %}
      • +
    • {% active_link /docs/installation/vagrant/ Vagrant %}
      • +
    • {% active_link /docs/installation/synology/ Synology %}
      • +
    • {% active_link /docs/installation/updating/ Updating %}
      • +
    • {% active_link /docs/installation/troubleshooting/ Troubleshooting %}
      • +
    +
    • +
  • + {% active_link /docs/hassbian/ Hassbian %} +
      +
    • {% active_link /docs/hassbian/installation/ Installation %}
      • +
    • {% active_link /docs/hassbian/customization/ Customization %}
      • +
    • {% active_link /docs/hassbian/common-tasks/ Common tasks %}
      • +
    • {% active_link /docs/hassbian/integrations/ Integrations %}
      • +
    • {% active_link /docs/hassbian/upgrading/ Upgrading %}
      • +
    +
    • +
  • + {% active_link /docs/configuration/ Configuration %} +
      +
    • {% active_link /docs/configuration/yaml/ YAML %}
      • +
    • {% active_link /docs/configuration/basic/ Basic information %}
      • +
    • {% active_link /docs/configuration/devices/ Setting up devices %}
      • +
    • {% active_link /docs/configuration/customizing-devices/ Customizing devices and services %}
      • +
    • {% active_link /docs/configuration/presence-detection/ Presence Detection %}
      • +
    • {% active_link /docs/configuration/troubleshooting/ Troubleshooting %}
      • +
    • {% active_link /docs/configuration/securing/ Security Check Points %}
      • +
    +
    • +
  • + Advanced Configuration +
      +
    • {% active_link /docs/configuration/remote/ Remote access %}
      • +
    • {% active_link /docs/configuration/packages/ Packages %}
      • +
    • {% active_link /docs/configuration/splitting_configuration/ Splitting up the configuration %}
      • +
    • {% active_link /docs/configuration/secrets/ Storing Secrets %}
      • +
    • {% active_link /docs/configuration/templating/ Templating %}
      • +
    • {% active_link /docs/configuration/group_visibility/ Group Visibility %}
      • +
    • {% active_link /docs/configuration/events/ Events %}
      • +
    • {% active_link /docs/configuration/state_object/ State Objects %}
      • +
    • {% active_link /docs/configuration/platform_options/ Entity component platform options %}
      • +
    +
    • +
  • + {% active_link /docs/automation/ Automation %} +
      +
    • {% active_link /docs/automation/tutorial/ Tutorial %}
      • +
    • {% active_link /docs/automation/trigger/ Triggers %}
      • +
    • {% active_link /docs/automation/condition/ Conditions %}
      • +
    • {% active_link /docs/automation/action/ Actions %}
      • +
    • {% active_link /docs/automation/templating/ Templates %}
      • +
    +
    • +
  • + {% active_link /docs/frontend/ Frontend %} +
      +
    • {% active_link /docs/frontend/mobile/ Android/iOS Homescreen %}
      • +
    • {% active_link /docs/frontend/webserver/ Web server fingerprint %}
      • +
    • {% active_link /docs/frontend/browsers/ Browser Compatibility List %}
      • +
    +
    • +
  • + {% active_link /docs/backend/ Backend %} +
      +
    • {% active_link /docs/backend/database/ Database %}
      • +
    • {% active_link /docs/backend/updater/ Updater %}
      • +
    • {% active_link /developers/api/ API %}
      • +
    +
    • +
  • + {% active_link /docs/scripts/ Scripts %} +
      +
    • {% active_link /docs/scripts/service-calls/ Service Calls %}
      • +
    • {% active_link /docs/scripts/conditions/ Conditions %}
      • +
    +
    • +
  • + {% active_link /docs/z-wave/ Z-Wave %} +
      +
    • {% active_link /docs/z-wave/controllers/ Controllers %}
      • +
    • {% active_link /docs/z-wave/settings/ Modifying Settings %}
      • +
    • {% active_link /docs/z-wave/device-specific/ Device Specific %}
      • +
    +
    • +
  • + {% active_link /docs/mqtt/ MQTT %} +
      +
    • {% active_link /docs/mqtt/broker/ Broker %}
      • +
    • {% active_link /docs/mqtt/certificate/ Certificate %}
      • +
    • {% active_link /docs/mqtt/discovery/ Discovery %}
      • +
    • {% active_link /docs/mqtt/service/ Publish service %}
      • +
    • {% active_link /docs/mqtt/birth_will/ Birth and last will messages %}
      • +
    • {% active_link /docs/mqtt/testing/ Testing your setup %}
      • +
    • {% active_link /docs/mqtt/logging/ Logging %}
      • +
    • {% active_link /docs/mqtt/processing_json/ Processing JSON %}
      • +
    +
    • +
  • + Ecosystem +
      +
    • + {% active_link /docs/autostart/ Autostart %} +
        +
      • {% active_link /docs/autostart/systemd/ systemd (Linux) %}
        • +
      • {% active_link /docs/autostart/upstart/ Upstart (Linux) %}
        • +
      • {% active_link /docs/autostart/init.d/ init.d (Linux) %}
        • +
      • {% active_link /docs/autostart/macos/ macOS %}
        • +
      • {% active_link /docs/autostart/synology/ Synology NAS %}
        • +
      +
      • +
    • + {% active_link /docs/appdaemon/ AppDaemon %} +
        +
      • {% active_link /docs/appdaemon/installation/ Installation %}
        • +
      • {% active_link /docs/appdaemon/configuration/ Configuration %}
        • +
      • {% active_link /docs/appdaemon/example_apps/ Example Apps %}
        • +
      • {% active_link /docs/appdaemon/running/ Running AppDaemon %}
        • +
      • {% active_link /docs/appdaemon/reboot/ Starting AppDaemon at Reboot %}
        • +
      • {% active_link /docs/appdaemon/operation/ Operation %}
        • +
      • {% active_link /docs/appdaemon/windows/ AppDaemon on Windows %}
        • +
      • {% active_link /docs/appdaemon/updating/ Updating AppDaemon %}
        • +
      • {% active_link /docs/appdaemon/tutorial/ AppDaemon Tutorial %}
        • +
      • {% active_link /docs/appdaemon/api/ AppDaemon API Reference %}
        • +
      +
      • + +
    • + {% active_link /docs/hadashboard/ HADashboard %} +
        +
      • {% active_link /docs/hadashboard/installation/ Installation %}
        • +
      • {% active_link /docs/hadashboard/dash_config/ Dashboard Configuration %}
        • +
      • {% active_link /docs/hadashboard/hapush/ HAPush %}
        • +
      • {% active_link /docs/hadashboard/reboot/ Reboot %}
        • +
      • {% active_link /docs/hadashboard/updating/ Updating HADashboard %}
        • +
      +
      • + +
    • + {% active_link /docs/notebooks/ Notebooks %} +
        +
      • {% active_link /docs/notebooks/ Introduction %}
        • +
      • {% active_link /docs/notebooks/installation/ Installation %}
        • +
      • {% active_link /docs/notebooks/graph/ Graph %}
        • +
      • {% active_link /docs/notebooks/api/ Home Assistant API %}
        • +
      • {% active_link /docs/notebooks/database/ Databsase %}
        • +
      • {% active_link /docs/notebooks/stats/ Statistics %}
        • +
      +
      • +
    • + {% active_link /docs/ios/notifications/ iOS %} +
        +
      • {% active_link /docs/ios/notifications/basic/ Basic notifications %}
        • +
          +
        • {% active_link /docs/ios/notifications/examples/ Examples %}
          • +
        • {% active_link /docs/ios/notifications/sounds/ Sounds %}
          • +
        • {% active_link /docs/ios/notifications/architecture/ Architecture %}
          • +
        • {% active_link /docs/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
          • +
        +
      • Advanced notifications
        • +
          +
        • {% active_link /docs/ios/notifications/attachments/ Attachments %}
          • +
        • {% active_link /docs/ios/notifications/content_extensions/ Dynamic content %}
          • +
        • {% active_link /docs/ios/notifications/actions/ Actionable notifications %}
          • +
        • {% active_link /docs/ios/notifications/requesting_location_updates/ Requesting location updates %}
          • +
        +
      • {% active_link /docs/ios/location/ Location Tracking %}
        • +
      • {% active_link /docs/ios/integration/ Integration with other apps %}
        • +
      +
      • +
    +
+
+
diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 98337cf3137c..d6188c1408ea 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -11,7 +11,7 @@ {% endcomment %}
  • Getting started
  • Components
    • -
  • Ecosystem
    • +
  • Docs
  • Examples
  • Developers
  • Blog
    • diff --git a/source/_includes/site/sidebar.html b/source/_includes/site/sidebar.html index 14fdb5f499d6..dcaf694b71e5 100644 --- a/source/_includes/site/sidebar.html +++ b/source/_includes/site/sidebar.html @@ -6,10 +6,10 @@ {% include asides/cookbook_navigation.html | compact_newlines %} {% elsif url_parts[1] == 'developers' %} {% include asides/developers_navigation.html | compact_newlines %} - {% elsif url_parts[1] == 'ecosystem' %} - {% include asides/ecosystem_navigation.html | compact_newlines %} {% elsif url_parts[1] == 'getting-started' %} {% include asides/getting_started_navigation.html | compact_newlines %} + {% elsif url_parts[1] == 'docs' %} + {% include asides/docs_navigation.html | compact_newlines %} {% else %} {% include asides/about.html %} From 70c819cecb37262f58651ecdd0870c539579aba7 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 09:20:11 +0100 Subject: [PATCH 31/51] Add docs overview page --- source/docs/index.markdown | 51 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 source/docs/index.markdown diff --git a/source/docs/index.markdown b/source/docs/index.markdown new file mode 100644 index 000000000000..83eae518e335 --- /dev/null +++ b/source/docs/index.markdown @@ -0,0 +1,51 @@ +--- +layout: page +title: "Documentation" +description: "Documentation for Home Assistant" +date: 2016-10-26 00:46 +sidebar: true +comments: false +sharing: true +footer: true +hide_github_edit: true +--- + +The documentation covers from beginner to advanced topic around the installation, the setup, the configuration, and the usage of Home Assistant. + +
    + +
    + +
    +
    Hassbian
    +     + +
    + +
    +
    Configuration
    +     + +
    + +
    +
    Z-Wave
    +     + +
    + +
    +
    MQTT
    +     + +
    + +
    +
    HADashboard
    +     +
    + +
    + + +To see what Home Assistant can do, take a look at the [demo page](/demo). From 4226964f9b5125e98697e8f17c716fce2219cf74 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 09:20:23 +0100 Subject: [PATCH 32/51] Remove ecosystem navigation --- source/_docs/automation/create-first.markdown | 117 ------------------ .../ecosystem_appdaemon_navigation.html | 19 --- .../ecosystem_hadashboard_navigation.html | 14 --- .../asides/ecosystem_ios_navigation.html | 39 ------ .../asides/ecosystem_navigation.html | 31 ----- .../ecosystem_notebooks_navigation.html | 15 --- source/getting-started/run.markdown | 22 ++++ 7 files changed, 22 insertions(+), 235 deletions(-) delete mode 100644 source/_docs/automation/create-first.markdown delete mode 100755 source/_includes/asides/ecosystem_appdaemon_navigation.html delete mode 100755 source/_includes/asides/ecosystem_hadashboard_navigation.html delete mode 100644 source/_includes/asides/ecosystem_ios_navigation.html delete mode 100755 source/_includes/asides/ecosystem_navigation.html delete mode 100644 source/_includes/asides/ecosystem_notebooks_navigation.html create mode 100644 source/getting-started/run.markdown diff --git a/source/_docs/automation/create-first.markdown b/source/_docs/automation/create-first.markdown deleted file mode 100644 index 9f9f4f5f1e74..000000000000 --- a/source/_docs/automation/create-first.markdown +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: page -title: "Your First Automation" -description: "Step by step guiding through making your first automation." -date: 2016-04-24 08:30 +0100 -sidebar: true -comments: false -sharing: true -footer: true ---- - -Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets** - -In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. - -```yaml -# Example configuration.yaml entry -automation: - alias: Turn on light when sun sets - initial_state: True - hide_entity: False - trigger: - platform: sun - event: sunset - action: - service: light.turn_on -``` - -Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when HASS starts set `initial_state:` to `False`. - -After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home. - -```yaml -# Example configuration.yaml entry -automation: - alias: Turn on light when sun sets - trigger: - platform: sun - event: sunset - offset: "-01:00:00" - condition: - condition: state - entity_id: group.all_devices - state: 'home' - action: - service: light.turn_on -``` - -Now you're happy and all is good. You start to like this automation business and buy some more lights, this time you put them in the bedroom. But what you now realize is that when the sun is setting, the lights in the bedroom are also being turned on! Time to tweak the automation to only turn on the living room lights. - -The first thing you do is to look at the entities in the developer tools (second icon) in the app. You see the names of your lights and you write them down: `light.table_lamp`, `light.bedroom`, `light.ceiling`. - -Instead of hard coding the entity IDs of the lights in the automation rule, we will set up a group. This will allow us to see the living room separate in the app and be able to address it from automation rules. - -So we tweak the config to add the group and have the automation rule only turn on the group. - -```yaml -# Example configuration.yaml entry -group: - living_room: - - light.table_lamp - - light.ceiling - -automation: - alias: Turn on light when sun sets - trigger: - platform: sun - event: sunset - offset: "-01:00:00" - condition: - condition: state - entity_id: group.all_devices - state: 'home' - action: - service: light.turn_on - entity_id: group.living_room -``` - -Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights! - -We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. - -```yaml -# Example configuration.yaml entry -group: - living_room: - - light.table_lamp - - light.ceiling - - switch.christmas_lights - -automation: - alias: Turn on light when sun sets - hide_entity: True - trigger: - platform: sun - event: sunset - offset: "-01:00:00" - condition: - condition: state - entity_id: group.all_devices - state: 'home' - action: - service: homeassistant.turn_on - entity_id: group.living_room -``` - -### {% linkable_title Learn more %} - - - [Triggers] - - [Conditions] - - [Actions] - - [Templating] (advanced) - -[Triggers]: /getting-started/automation-trigger/ -[Conditions]: /getting-started/automation-condition/ -[Actions]: /getting-started/automation-action/ -[Templating]: /getting-started/automation-templating/ diff --git a/source/_includes/asides/ecosystem_appdaemon_navigation.html b/source/_includes/asides/ecosystem_appdaemon_navigation.html deleted file mode 100755 index 8333511804ea..000000000000 --- a/source/_includes/asides/ecosystem_appdaemon_navigation.html +++ /dev/null @@ -1,19 +0,0 @@ -
    - -
    -

    AppDaemon

    -
      -
    • {% active_link /ecosystem/appdaemon/ General %}
      • -
    • {% active_link /ecosystem/appdaemon/installation/ Installation %}
      • -
    • {% active_link /ecosystem/appdaemon/configuration/ AppDaemon Configuration %}
      • -
    • {% active_link /ecosystem/appdaemon/example_apps/ Example Apps %}
      • -
    • {% active_link /ecosystem/appdaemon/running/ Running AppDaemon %}
      • -
    • {% active_link /ecosystem/appdaemon/reboot/ Starting AppDaemon at Reboot %}
      • -
    • {% active_link /ecosystem/appdaemon/operation/ AppDaemon Operation %}
      • -
    • {% active_link /ecosystem/appdaemon/windows/ AppDaemon on Windows %}
      • -
    • {% active_link /ecosystem/appdaemon/updating/ Updating AppDaemon %}
      • -
    • {% active_link /ecosystem/appdaemon/tutorial/ AppDaemon Tutorial %}
      • -
    • {% active_link /ecosystem/appdaemon/api/ AppDaemon API Reference %}
      • -
    -
    -
    diff --git a/source/_includes/asides/ecosystem_hadashboard_navigation.html b/source/_includes/asides/ecosystem_hadashboard_navigation.html deleted file mode 100755 index 8053a2ff9933..000000000000 --- a/source/_includes/asides/ecosystem_hadashboard_navigation.html +++ /dev/null @@ -1,14 +0,0 @@ -
    - -
    -

    HADashboard

    -
      -
    • {% active_link /ecosystem/hadashboard/ General %}
      • -
    • {% active_link /ecosystem/hadashboard/installation/ Installation %}
      • -
    • {% active_link /ecosystem/hadashboard/dash_config/ Dashboard Configuration %}
      • -
    • {% active_link /ecosystem/hadashboard/hapush/ HAPush %}
      • -
    • {% active_link /ecosystem/hadashboard/reboot/ Reboot %}
      • -
    • {% active_link /ecosystem/hadashboard/updating/ Updating HADashboard %}
      • -
    -
    -
    diff --git a/source/_includes/asides/ecosystem_ios_navigation.html b/source/_includes/asides/ecosystem_ios_navigation.html deleted file mode 100644 index 152b4494be54..000000000000 --- a/source/_includes/asides/ecosystem_ios_navigation.html +++ /dev/null @@ -1,39 +0,0 @@ -
    - -
    -

    iOS Guide

    -
      -
    • - {% active_link /ecosystem/ios/ General %} - {% comment %} -
        -
      • {% active_link /ecosystem/ios/requirements/ Requirements %}
        • -
      • {% active_link /ecosystem/ios/getting_started/ Getting Started %}
        • -
      • {% active_link /ecosystem/ios/features/ Features %}
        • -
      • {% active_link /ecosystem/ios/devices_file/ ios.conf %}
        • -
      - {% endcomment %} -
      • -
    • - {% active_link /ecosystem/ios/notifications/ Push Notifications %} -
        -
      • {% active_link /ecosystem/ios/notifications/basic/ Basic notifications %}
        • -
      • Advanced notifications
        • -
          -
        • {% active_link /ecosystem/ios/notifications/attachments/ Attachments %}
          • -
        • {% active_link /ecosystem/ios/notifications/content_extensions/ Dynamic content %}
          • -
        • {% active_link /ecosystem/ios/notifications/actions/ Actionable notifications %}
          • -
        • {% active_link /ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}
          • -
        -
      • {% active_link /ecosystem/ios/notifications/examples/ Examples %}
        • -
      • {% active_link /ecosystem/ios/notifications/sounds/ Sounds %}
        • -
      • {% active_link /ecosystem/ios/notifications/architecture/ Architecture %}
        • -
      • {% active_link /ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
        • -
      -
      • -
    • {% active_link /ecosystem/ios/location/ Location Tracking %}
      • - {% comment %}
    • {% active_link /ecosystem/ios/sensor/ Battery Sensors %}
      • {% endcomment %} -
    • {% active_link /ecosystem/ios/integration/ Integration with other apps %}
      • -
    -
    -
    diff --git a/source/_includes/asides/ecosystem_navigation.html b/source/_includes/asides/ecosystem_navigation.html deleted file mode 100755 index 24285c4f0bf6..000000000000 --- a/source/_includes/asides/ecosystem_navigation.html +++ /dev/null @@ -1,31 +0,0 @@ -{% assign url_parts = page.url | split: "/" %} -{% if url_parts[2] == "ios" %} - {% 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 %} -{% elsif url_parts[2] == "notebooks" %} - {% include asides/ecosystem_notebooks_navigation.html | compact_newlines %} -{% comment %} -{% elsif url_parts[2] == "cookbook" %} - {% include asides/cookbook_navigation.html | compact_newlines %} -{% endcomment %} -{% else %} -
    - {% include edit_github.html %} - {% assign ecosystem = site.ecosystem | sort: "title" %} - -
    -

    Ecosystem

    -
      - {% for tool in ecosystem %} - {% assign filename = tool.path | split: "/" %} - {% if filename.size == 2 %} -
    • {{tool.title}}
      • - {% endif %} - {% endfor %} -
    -
    -
    -{% endif %} diff --git a/source/_includes/asides/ecosystem_notebooks_navigation.html b/source/_includes/asides/ecosystem_notebooks_navigation.html deleted file mode 100644 index 72415a3dd0be..000000000000 --- a/source/_includes/asides/ecosystem_notebooks_navigation.html +++ /dev/null @@ -1,15 +0,0 @@ -
    - -
    -

    Jupyter Notebooks

    -
      -
    • {% active_link /ecosystem/notebooks/ Introduction %}
      • -
    • {% active_link /ecosystem/notebooks/installation/ Installation %}
      • -
    • {% active_link /ecosystem/notebooks/graph/ Graph %}
      • -
    • {% active_link /ecosystem/notebooks/api/ Home Assistant API %}
      • -
    • {% active_link /ecosystem/notebooks/Database/ Databsase %}
      • -
    • {% active_link /ecosystem/notebooks/stats/ Statistics %}
      • -
    -
    -
    - diff --git a/source/getting-started/run.markdown b/source/getting-started/run.markdown new file mode 100644 index 000000000000..ac2b054cc1ae --- /dev/null +++ b/source/getting-started/run.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "Run Home Assistant" +description: "Instructions about how you can run Home Assistant." +date: 2016-09-26 21:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +If you are using Hassbian, browse to [http://hassbian.local:8123](http://hassbian.local:8123) to open the Home Assistant frontend. + +For a standard installation the command shown below starts Home Assistant and serves the frontend at [http://IP_ADDRESS:8123](http://IP_ADDRESS:8123). + +```bash +$ hass +``` + +To see what Home Assistant can do, launch the demo mode: `hass --demo-mode`. + +For tweaking your Home Assistant setup, take a look at the [documentation](/docs/), ask your questions in our [forum](https://community.home-assistant.io/), join us for a [chat](https://gitter.im/home-assistant/home-assistant), or report your [issues](https://github.com/home-assistant/home-assistant/issues). From 08fb15f3ec2f213ad7c1d31efce97ba1fedff61e Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 09:21:14 +0100 Subject: [PATCH 33/51] Add docs and remove other collections --- _config.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/_config.yml b/_config.yml index 2704d4cca9dc..644ca3e00ff2 100644 --- a/_config.yml +++ b/_config.yml @@ -73,11 +73,7 @@ collections: output: true cookbook: output: true - ecosystem: - output: true - details: - output: true - topics: + docs: output: true # ----------------------- # From 2cb671225716a304774911fed3390a7cfc708552 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Thu, 16 Feb 2017 09:25:24 +0100 Subject: [PATCH 34/51] Move ecosystem to docs --- source/_docs/appdaemon.markdown | 14 + source/_docs/appdaemon/api.markdown | 2108 +++++++++++++++++ source/_docs/appdaemon/configuration.markdown | 79 + source/_docs/appdaemon/example_apps.markdown | 13 + source/_docs/appdaemon/installation.markdown | 45 + source/_docs/appdaemon/operation.markdown | 13 + source/_docs/appdaemon/reboot.markdown | 13 + source/_docs/appdaemon/running.markdown | 95 + source/_docs/appdaemon/tutorial.markdown | 128 + source/_docs/appdaemon/updating.markdown | 26 + source/_docs/appdaemon/windows.markdown | 22 + source/_docs/backend.markdown | 17 + source/_docs/hadashboard.markdown | 20 + source/_docs/hadashboard/dash_config.markdown | 274 +++ source/_docs/hadashboard/hapush.markdown | 94 + .../_docs/hadashboard/installation.markdown | 151 ++ source/_docs/hadashboard/reboot.markdown | 16 + source/_docs/hadashboard/updating.markdown | 24 + source/_docs/ios.markdown | 66 + source/_docs/ios/devices_file.markdown | 12 + source/_docs/ios/features.markdown | 12 + source/_docs/ios/integration.markdown | 25 + source/_docs/ios/location.markdown | 36 + source/_docs/ios/notifications.markdown | 14 + .../_docs/ios/notifications/actions.markdown | 142 ++ .../ios/notifications/architecture.markdown | 15 + .../ios/notifications/attachments.markdown | 76 + source/_docs/ios/notifications/basic.markdown | 58 + .../notifications/content_extensions.markdown | 61 + .../privacy_security_rate_limits.markdown | 22 + .../requesting_location_updates.markdown | 30 + .../_docs/ios/notifications/sounds.markdown | 184 ++ source/_docs/ios/requirements.markdown | 14 + source/_docs/nginx.markdown | 133 ++ source/_docs/notebooks.markdown | 20 + source/_docs/notebooks/api.markdown | 12 + source/_docs/notebooks/database.markdown | 12 + source/_docs/notebooks/graph.markdown | 12 + source/_docs/notebooks/installation.markdown | 50 + source/_docs/notebooks/stats.markdown | 12 + source/_docs/synology.markdown | 24 + source/_docs/tools.markdown | 12 + source/_docs/tools/dev-tools.markdown | 12 + source/_docs/tools/hass.markdown | 43 + source/_docs/tools/scripts.markdown | 12 + 45 files changed, 4273 insertions(+) create mode 100755 source/_docs/appdaemon.markdown create mode 100755 source/_docs/appdaemon/api.markdown create mode 100644 source/_docs/appdaemon/configuration.markdown create mode 100644 source/_docs/appdaemon/example_apps.markdown create mode 100644 source/_docs/appdaemon/installation.markdown create mode 100644 source/_docs/appdaemon/operation.markdown create mode 100644 source/_docs/appdaemon/reboot.markdown create mode 100755 source/_docs/appdaemon/running.markdown create mode 100755 source/_docs/appdaemon/tutorial.markdown create mode 100644 source/_docs/appdaemon/updating.markdown create mode 100755 source/_docs/appdaemon/windows.markdown create mode 100644 source/_docs/backend.markdown create mode 100644 source/_docs/hadashboard.markdown create mode 100755 source/_docs/hadashboard/dash_config.markdown create mode 100755 source/_docs/hadashboard/hapush.markdown create mode 100755 source/_docs/hadashboard/installation.markdown create mode 100755 source/_docs/hadashboard/reboot.markdown create mode 100755 source/_docs/hadashboard/updating.markdown create mode 100644 source/_docs/ios.markdown create mode 100644 source/_docs/ios/devices_file.markdown create mode 100644 source/_docs/ios/features.markdown create mode 100644 source/_docs/ios/integration.markdown create mode 100644 source/_docs/ios/location.markdown create mode 100644 source/_docs/ios/notifications.markdown create mode 100644 source/_docs/ios/notifications/actions.markdown create mode 100644 source/_docs/ios/notifications/architecture.markdown create mode 100644 source/_docs/ios/notifications/attachments.markdown create mode 100644 source/_docs/ios/notifications/basic.markdown create mode 100644 source/_docs/ios/notifications/content_extensions.markdown create mode 100644 source/_docs/ios/notifications/privacy_security_rate_limits.markdown create mode 100644 source/_docs/ios/notifications/requesting_location_updates.markdown create mode 100644 source/_docs/ios/notifications/sounds.markdown create mode 100644 source/_docs/ios/requirements.markdown create mode 100644 source/_docs/nginx.markdown create mode 100644 source/_docs/notebooks.markdown create mode 100644 source/_docs/notebooks/api.markdown create mode 100644 source/_docs/notebooks/database.markdown create mode 100644 source/_docs/notebooks/graph.markdown create mode 100644 source/_docs/notebooks/installation.markdown create mode 100644 source/_docs/notebooks/stats.markdown create mode 100644 source/_docs/synology.markdown create mode 100644 source/_docs/tools.markdown create mode 100644 source/_docs/tools/dev-tools.markdown create mode 100644 source/_docs/tools/hass.markdown create mode 100644 source/_docs/tools/scripts.markdown diff --git a/source/_docs/appdaemon.markdown b/source/_docs/appdaemon.markdown new file mode 100755 index 000000000000..9ec0e87f8e3f --- /dev/null +++ b/source/_docs/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. \ No newline at end of file diff --git a/source/_docs/appdaemon/api.markdown b/source/_docs/appdaemon/api.markdown new file mode 100755 index 000000000000..891ef1dec870 --- /dev/null +++ b/source/_docs/appdaemon/api.markdown @@ -0,0 +1,2108 @@ +--- +layout: page +title: "AppDaemon API Reference" +description: "AppDaemon API Reference" +release_date: 2016-11-27 08:00:00 -0500 +sidebar: true +comments: false +sharing: true +footer: true +hide_github_edit: true +--- + +## {% linkable_title Anatomy of an App %} + +Automations in AppDaemon are performed by creating a piece of code (essentially a Python Class) and then instantiating it as an Object one or more times by configuring it as an App in the configuration file. The App is given a chance to register itself for whatever events it wants to subscribe to, and AppDaemon will then make calls back into the Object's code when those events occur, allowing the App to respond to the event with some kind of action. + +The first step is to create a unique file within the apps directory (as defined in the `[AppDaemon]` section of configuration file). This file is in fact a Python module, and is expected to contain one or more classes derived from the supplied `AppDaemon` class, imported from the supplied `homeassistant.appapi` module. The start of an app might look like this: + +```python +import homeassistant.appapi as appapi + +class MotionLights(appapi.AppDaemon): +``` + +When configured as an app in the config file (more on that later) the lifecycle of the App begins. It will be instantiated as an object by AppDaemon, and immediately, it will have a call made to it's `initialize()` function - this function must appear as part of every app: + +```python + def initialize(self): +``` + +The initialize function allows the app to register any callbacks it might need for responding to state changes, and also any setup activities. When the `initialize()` function returns, the App will be dormant until any of it's callbacks are activated. + +There are several circumstances under which `initialize()` might be called: + +- Initial start of AppDaemon +- Following a change to the Class code +- Following a change to the module parameters +- Following initial configuration of an app +- Following a change in the status of Daylight Savings Time +- Following a restart of Home Assistant + +In every case, the App is responsible for recreating any state it might need as if it were the first time it was ever started. If `initialize()` is called, the app can safely assume that it is either being loaded for the first time, or that all callbacks and timers have been cancelled. In either case, the APP will need to recreate them. Depending upon the application it may be desirable for the App to establish state such as whether or not a particular light is on, within the `initialize()` function to ensure that everything is as expected or to make immediate remedial action (e.g. turn off a light that might have been left on by mistake when the app was restarted). + +After the `initialize()` function is in place, the rest of the app consists of functions that are called by the various callback mechanisms, and any additional functions the user wants to add as part of the program logic. Apps are able to subscribe to 2 main classes of events: + +- Scheduled Events +- State Change Events + +These, along with their various subscription calls and helper functions, will be described in detail in later sections. + +To wrap up this section, here is a complete functioning App (with comments): + +```python +import homeassistant.appapi as appapi +import datetime + +# Declare Class +class NightLight(appapi.AppDaemon): + #initialize() function which will be called at startup and reload + def initialize(self): + # Create a time object for 7pm + time = datetime.time(19, 00, 0) + # Schedule a daily callback that will call run_daily() at 7pm every night + self.run_daily(self.run_daily_callback, time) + + # Our callback function will be called by the scheduler every day at 7pm + def run_daily_callback(self, kwargs): + # Call to Home Assistant to turn the porch light on + self.turn_on("light.porch") +``` + +To summarize - an App's lifecycle consists of being initialized, which allows it to set one or more state and/or schedule callbacks. When those callbacks are activated, the App will typically use one of the Service Calling calls to effect some change to the devices of the system and then wait for the next relevant state change. That's all there is to it! + +## {% linkable_title About the API %} + +The implementation of the API is located in the AppDaemon class that Apps are derived from. The code for the functions is therefore available to the App simply by invoking the name of the function from the object namespace using the `self` keyword, as in the above examples. `self.turn_on()` for example is just a method defined in the parent class and made available to the child. This design decision was made to simplify some of the implementation and hide passing of unnecessary variables during the API invocation. + +## {% linkable_title Configuration of Apps %} +Apps are configured by specifying new sections in the configuration file. `[AppDaemon]` is a reserved section, for configuration of AppDaemon itself. The name of the section is the name the App is referred to within the system in log files etc. and must be unique. + +To configure a new App you need a minimum of two directives: + +- `module` - the name of the module (without the `.py`) that contains the class to be used for this App +- `class` - the name of the class as defined within the module for the APPs code + +Although the section/App name must be unique, it is possible to re-use a class as many times as you want, and conversely to put as many classes in a module as you want. A sample definition for a new App might look as follows: + +```ini +[newapp] +module = new +class = NewApp +``` + +When AppDaemon sees the following configuration it will expect to find a class called `NewApp` defined in a module called `new.py` in the apps subdirectory. Apps can be placed at the root of the Apps directory or within a subdirectory, an arbitrary depth down - wherever the App is, as long as it is in some subdirectory of the Apps dir, or in the Apps dir itself, AppDaemon will find it. There is no need to include information about the path, just the name of the file itself (without the `.py`) is sufficient. If names in the subdirectories overlap, AppDir will pick one of them but the exact choice it will make is undefined. + +When starting the system for the first time or when reloading an App or Module, the system will log the fact in it's main log. It is often the case that there is a problem with the class, maybe a syntax error or some other problem. If that is the case, details will be output to the error log allowing the user to remedy the problem and reload. + +## {% linkable_title Steps to writing an App %} + +1. Create the code in a new or shared module by deriving a class from AppDaemon, add required callbacks and code +2. Add the App to the configuration file +3. There is no number 3 + +## {% linkable_title Reloading Modules and Classes %} + +Reloading of modules is automatic. When the system spots a change in a module, it will automatically reload and recompile the module. It will also figure out which Apps were using that Module and restart them, causing all of their existing callbacks to be cleared, and their `initialize()` function to be called. + +The same is true if changes are made to an App's configuration - changing the class, or arguments (see later) will cause that app to be reloaded in the same way. The system is also capable of detecting if a new app has been added, or if one has been removed, and it will act appropriately, starting the new app immediately and removing all callbacks for the removed app. + +The suggested order for creating a new App is to add the module code first and work until it compiles cleanly, and only then add an entry in the configuration file to actually run it. A good workflow is to continuously monitor the error file (using `tail -f` on Linux for instance) to ensure that errors are seen and can be remedied. + +## {% linkable_title Passing Arguments to Apps %} + +There wouldn't be much point in being able to run multiple versions of an App if there wasn't some way to instruct them to do something different. For this reason it is possible to pass any required arguments to an App, which are then made available to the object at runtime. The arguments themselves can be called anything (apart from `module` or `class`) and are simply added into the section after the 2 mandatory directives like so: + +```ini +[MyApp] +module = myapp +class = MyApp +param1 = spam +param2 = eggs +``` + +Within the Apps code, the 2 parameters (as well as the module and class) are available as a dictionary called `args`, and accessed as follows: + +```python +param1 = self.args["param1"] +param2 = self.args["param2"] +``` + +A use case for this might be an App that detects motion and turns on a light. If you have 3 places you want to run this, rather than hardcoding this into 3 separate Apps, you need only code a single app and instantiate it 3 times with different arguments. It might look something like this: + +```ini +[downstairs_motion_light] +module = motion_light +class = MotionLight +sensor = binary_sensor.downstairs_hall +light = light.downstairs_hall +[upstairs_motion_light] +module = motion_light +class = MotionLight +sensor = binary_sensor.upstairs_hall +light = light.upstairs_hall +[garage_motion_light] +module = motion_light +class = MotionLight +sensor = binary_sensor.garage +light = light.garage +``` + +## {% linkable_title Callback Constraints %} + +Callback constraints are a feature of AppDaemon that removes the need for repetition of some common coding checks. Many Apps will wish to process their callbacks only when certain conditions are met, e.g. someone is home, and it's after sunset. These kinds of conditions crop up a lot, and use of callback constraints can significantly simplify the logic required within callbacks. + +Put simply, callback constraints are one or more conditions on callback execution that can be applied to an individual App. An App's callbacks will only be executed if all of the constraints are met. If a constraint is absent it will not be checked for. + +For example, the presence callback constraint can be added to an App by adding a parameter to it's configuration like this: + +```ini +[some_app] +module = some_module +class = SomeClass +constrain_presence = noone +``` + +Now, although the `initialize()` function will be called for MyClass, and it will have a chance to register as many callbacks as it desires, none of the callbacks will execute, in this case, until everyone has left. This could be useful for an interior motion detector App for instance. There are several different types of constraints: + +- input_boolean +- input_select +- presence +- time + +An App can have as many or as few as are required. When more than one constraint is present, they must all evaluate to true to allow the callbacks to be called. Constraints becoming true are not an event in their own right, but if they are all true at a point in time, the next callback that would otherwise been blocked due to constraint failure will now be called. Similarly, if one of the constraints becomes false, the next callback that would otherwise have been called will be blocked. + +They are described individually below. + +### {% linkable_title input_boolean %} +By default, the input_boolean constraint prevents callbacks unless the specified input_boolean is set to "on". This is useful to allow certain Apps to be turned on and off from the user interface. For example: + +```ini +[some_app] +module = some_module +class = SomeClass +constrain_input_boolean = input_boolean.enable_motion_detection +``` + +If you want to reverse the logic so the constraint is only called when the input_boolean is off, use the optional state parameter by appending ",off" to the argument, e.g.: + +```ini +[some_app] +module = some_module +class = SomeClass +constrain_input_boolean = input_boolean.enable_motion_detection,off +``` + +### {% linkable_title input_select %} +The input_select constraint prevents callbacks unless the specified input_select is set to one or more of the nominated (comma separated) values. This is useful to allow certain Apps to be turned on and off according to some flag, e.g. a house mode flag. + +```ini +# Single value +constrain_input_select = input_select.house_mode,Day +# or multiple values +constrain_input_select = input_select.house_mode,Day,Evening,Night +``` + +### {% linkable_title presence %} +The presence constraint will constrain based on presence of device trackers. It takes 3 possible values: +- `noone` - only allow callback execution when no one is home +- `anyone` - only allow callback execution when one or more person is home +- `everyone` - only allow callback execution when everyone is home + +```ini +constrain_presence = anyone +# or +constrain_presence = someone +# or +constrain_presence = noone +``` + +### {% linkable_title time %} +The time constraint consists of 2 variables, `constrain_start_time` and `constrain_end_time`. Callbacks will only be executed if the current time is between the start and end times. +- If both are absent no time constraint will exist +- If only start is present, end will default to 1 second before midnight +- If only end is present, start will default to midnight + +The times are specified in a string format with one of the following formats: +- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. +- `sunrise`|`sunset` [+|- HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds + +The time based constraint system correctly interprets start and end times that span midnight. + +```ini +# Run between 8am and 10pm +constrain_start_time = 08:00:00 +constrain_end_time = 22:00:00 +# Run between sunrise and sunset +constrain_start_time = sunrise +constrain_end_time = sunset +# Run between 45 minutes before sunset and 45 minutes after sunrise the next day +constrain_start_time = sunset - 00:45:00 +constrain_end_time = sunrise + 00:45:00 +``` + +### {% linkable_title days %} +The day constraint consists of as list of days for which the callbacks will fire, e.g. + +```ini +constrain_days = mon,tue,wed +``` + +Callback constraints can also be applied to individual callbacks within Apps, see later for more details. + +## {% linkable_title A Note on Threading %} + +AppDaemon is multithreaded. This means that any time code within an App is executed, it is executed by one of many threads. This is generally not a particularly important consideration for this application; in general, the execution time of callbacks is expected to be far quicker than the frequency of events causing them. However, it should be noted for completeness, that it is certainly possible for different pieces of code within the App to be executed concurrently, so some care may be necessary if different callback for instance inspect and change shared variables. This is a fairly standard caveat with concurrent programming, and if you know enough to want to do this, then you should know enough to put appropriate safeguards in place. For the average user however this shouldn't be an issue. If there are sufficient use cases to warrant it, I will consider adding locking to the function invocations to make the entire infrastructure threadsafe, but I am not convinced that it is necessary. + +An additional caveat of a threaded worker pool environment is that it is the expectation that none of the callbacks tie threads up for a significant amount of time. To do so would eventually lead to thread exhaustion, which would make the system run behind events. No events would be lost as they would be queued, but callbacks would be delayed which is a bad thing. + +Given the above, NEVER use Python's `time.sleep()` if you want to perform an operation some time in the future, as this will tie up a thread for the period of the sleep. Instead use the scheduler's `run_in()` function which will allow you to delay without blocking any threads. + +## {% linkable_title State Operations %} + +### {% linkable_title A note on Home Assistant State %} + +State within Home Assistant is stored as a collection of dictionaries, one for each entity. Each entity's dictionary will have some common fields and a number of entity type specific fields The state for an entity will always have the attributes: + +- `last_updated` +- `last_changed` +- `state` + +Any other attributes such as brightness for a lamp will only be present if the entity supports them, and will be stored in a sub-dictionary called `attributes`. When specifying these optional attributes in the `get_state()` call, no special distinction is required between the main attributes and the optional ones - `get_state()` will figure it out for you. + +Also bear in mind that some attributes such as brightness for a light, will not be present when the light is off. + +In most cases, the attribute `state` has the most important value in it, e.g. for a light or switch this will be `on` or `off`, for a sensor it will be the value of that sensor. Many of the AppDaemon API calls and callbacks will implicitly return the value of state unless told to do otherwise. + +### {% linkable_title get_state() %} + +#### {% linkable_title Synopsis %} + +```python +get_state(entity = None, attribute = None) +``` + +`get_state()` is used to query the state of any component within Home Assistant. State updates are continuously tracked so this call runs locally and does not require AppDaemon to call back to Home Assistant and as such is very efficient. + +#### {% linkable_title Returns %} + +`get_state()` returns a `dictionary` or single value, the structure of which varies according to the parameters used. + +#### {% linkable_title Parameters %} + +All parameters are optional, and if `get_state()` is called with no parameters it will return the entire state of Home Assistant at that given time. This will consist of a dictionary with a key for each entity. Under that key will be the standard entity state information. + +##### {% linkable_title entity %} + +This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `get_state()` will return a dictionary of all devices of that type, indexed by the entity_id, containing all the state for each entity. + +If a fully qualified `entity_id` is provided, `get_state()` will return the state attribute for that entity, e.g. `on` or `off` for a light. + +##### {% linkable_title attribute %} + +Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified `entity_id`, a single value representing the attribute will be returned, or `None` if it is not present. + +The value `all` for attribute has special significance and will return the entire state dictionary for the specified entity rather than an individual attribute value. + +#### {% linkable_title Examples %} + +```python +# Return state for the entire system +state = self.get_state() + +# Return state for all switches in the system +state = self.get_state("switch") + +# Return the state attribute for light.office_1 +state = self.get_state("light.office_1") + +# Return the brightness attribute for light.office_1 +state = self.get_state("light.office_1", "brightness") + +# Return the entire state for light.office_1 +state = self.get_state("light.office_1", "all") +``` + +### {% linkable_title set_state() %} + +`set_state()` will make a call back to Home Assistant and make changes to the internal state of Home Assistant. This is not something that you would usually want to do and the applications are limited however the call is included for completeness. Note that for instance, setting the state of a light to `on` won't actually switch the device on, it will merely change the state of the device in Home Assistant so that it no longer reflects reality. In most cases, the state will be corrected the next time Home Assistant polls the device or someone causes a state change manually. To effect actual changes of devices use one of the service call functions. + +One possible use case for `set_state()` is for testing. If for instance you are writing an App to turn on a light when it gets dark according to a luminance sensor, you can use `set_state()` to temporarily change the light level reported by the sensor to test your program. However this is also possible using the developer tools. + +At the time of writing, it appears that no checking is done as to whether or not the entity exists, so it is possible to add entirely new entries to Home Assistant's state with this call. + +#### {% linkable_title Synopsis %} + +```python +set_state(entity_id, **kwargs) +``` + +#### {% linkable_title Returns %} + +`set_state()` returns a dictionary representing the state of the device after the call has completed. + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Entity id for which the state is to be set, e.g. `light.office_1`. + +##### {% linkable_title values %} + +A list of keyword values to be changed or added to the entities state. e.g. `state = "off"`. Note that any optional attributes such as colors for bulbs etc, need to reside in a dictionary called `attributes`; see the example. + +#### {% linkable_title Examples %} + +```python +status = self.set_state("light.office_1", state = "on", attributes = {"color_name": "red"}) +``` + +### {% linkable_title About Callbacks %} + +A large proportion of home automation revolves around waiting for something to happen and then reacting to it; a light level drops, the sun rises, a door opens etc. Home Assistant keeps track of every state change that occurs within the system and streams that information to AppDaemon almost immediately. + +An individual App however usually doesn't care about the majority of state changes going on in the system; Apps usually care about something very specific, like a specific sensor or light. Apps need a way to be notified when a state change happens that they care about, and be able to ignore the rest. They do this through registering callbacks. A callback allows the App to describe exactly what it is interested in, and tells AppDaemon to make a call into its code in a specific place to be able to react to it - this is a very familiar concept to anyone familiar with event-based programming. + +There are 3 types of callbacks within AppDaemon: + +- State Callbacks - react to a change in state +- Scheduler Callbacks - react to a specific time or interval +- Event Callbacks - react to specific Home Assistant and Appdaemon events. + +All callbacks allow the user to specify additional parameters to be handed to the callback via the standard Python `**kwargs` mechanism for greater flexibility. + +### {% linkable_title About Registering Callbacks %} + +Each of the various types of callback have their own function or functions for registering the callback: + +- `listen_state()` for state callbacks +- Various scheduler calls such as `run_once()` for scheduler callbacks +- `listen_event()` for event callbacks. + +Each type of callback shares a number of common mechanisms that increase flexibility. + +#### {% linkable_title Callback Level Constraints %} + +When registering a callback, you can add constraints identical to the Application level constraints described earlier. The difference is that a constraint applied to an individual callback only affects that callback and no other. The constraints are applied by adding Python keyword-value style arguments after the positional arguments. The parameters themselves are named identically to the previously described constraints and have identical functionality. For instance, adding: + +`constrain_presence="everyone"` + +to a callback registration will ensure that the callback is only run if the callback conditions are met and in addition everyone is present although any other callbacks might run whenever their event fires if they have no constraints. + +For example: + +`self.listen_state(self.motion, "binary_sensor.drive", constrain_presence="everyone")` + +#### {% linkable_title User Arguments %} + +Any callback has the ability to allow the App creator to pass through arbitrary keyword arguments that will be presented to the callback when it is run. The arguments are added after the positional parameters just like the constraints. The only restriction is that they cannot be the same as any constraint name for obvious reasons. For example, to pass the parameter `arg1 = "home assistant"` through to a callback you would register a callback as follows: + +`self.listen_state(self.motion, "binary_sensor.drive", arg1="home assistant")` + +Then in the callback you could use it as follows: + +```python +def motion(self, entity, attribute, old, new, **kwargs): + self.log("Arg1 is {}".format(kwargs["arg1"])) +``` + +### {% linkable_title State Callbacks %} + +AppDaemons's state callbacks allow an App to listen to a wide variety of events, from every state change in the system, right down to a change of a single attribute of a particular entity. Setting up a callback is done using a single API call `listen_state()` which takes various arguments to allow it to do all of the above. Apps can register as many or as few callbacks as they want. + +### {% linkable_title About State Callback Functions %} + +When calling back into the App, the App must provide a class function with a known signature for AppDaemon to call. The callback will provide various information to the function to enable the function to respond appropriately. For state callbacks, a class defined callback function should look like this: + +```python + def my_callback(self, entity, attribute, old, new, **kwargs): + +``` + +You can call the function whatever you like - you will reference it in the `listen_state()` call, and you can create as many callback functions as you need. + +The parameters have the following meanings: + +#### {% linkable_title self %} + +A standard Python object reference. + +#### {% linkable_title entity %} + +Name of the entity the callback was requested for or `None`. + +#### {% linkable_title attribute %} + +Name of the attribute the callback was requested for or `None`. + +#### {% linkable_title old %} + +The value of the state before the state change. + +#### {% linkable_title new %} + +The value of the state after the state change. + +`old` and `new` will have varying types depending on the type of callback. + +#### {% linkable_title \*\*kwargs %} + +A dictionary containing any constraints and/or additional user specific keyword arguments supplied to the `listen_state()` call. + +### {% linkable_title listen_state() %} + +`listen_state()` allows the user to register a callback for a wide variety of state changes. + +#### {% linkable_title Synopsis %} + +```python +handle = listen_state(callback, entity = None, **kwargs) +``` + +#### {% linkable_title Returns %} + +A unique identifier that can be used to cancel the callback if required. Since variables created within object methods are local to the function they are created in, and in all likelihood the cancellation will be invoked later in a different function, it is recommended that handles are stored in the object namespace, e.g. `self.handle`. + +#### {% linkable_title Parameters %} + +All parameters except `callback` are optional, and if `listen_state()` is called with no additional parameters it will subscribe to any state change within Home Assistant. + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard State Callback format documented above. + +##### {% linkable_title entity %} + +This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `listen_state()` will subscribe to state changes of all devices of that type. If a fully qualified `entity_id` is provided, `listen_state()` will listen for state changes for just that entity. + +When called, AppDaemon will supply the callback function, in old and new, with the state attribute for that entity, e.g. `on` or `off` for a light. + +##### {% linkable_title attribute (optional) %} + +Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified `entity_id`, `listen_state()` will subscribe to changes for just that attribute within that specific entity. The new and old parameters in the callback function will be provided with a single value representing the attribute. + +The value `all` for attribute has special significance and will listen for any state change within the specified entity, and supply the callback functions with the entire state dictionary for the specified entity rather than an individual attribute value. + +##### {% linkable_title new = (optional) %} + +If `new` is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually `state`) in the new state match the value of `new`. + +##### {% linkable_title old = (optional) %} + +If `old` is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually `state`) in the old state match the value of `old`. + +Note: `old` and `new` can be used singly or together. + +##### {% linkable_title duration = (optional) %} + +If duration is supplied as a parameter, the callback will not fire unless the state listened for is maintained for that number of seconds. This makes the most sense if a specific attribute is specified (or the default os `state` is used), an in conjunction with the `old` or `new` parameters, or both. When the callback is called, it is supplied with the values of `entity`, `attr`, `old` and `new` that were current at the time the actual event occured, since the assumption is that none of them have changed in the intervening period. + +```python + def my_callback(self, **kwargs): + +``` + +(Scheduler callbacks are documented in detail laer in this document) + +##### {% linkable_title \*\*kwargs %} + +Zero or more keyword arguments that will be supplied to the callback when it is called. + +#### {% linkable_title Examples %} + +```python +# Listen for any state change and return the state attribute +self.handle = self.listen_state(self.my_callback) + +# Listen for any state change involving a light and return the state attribute +self.handle = self.listen_state(self.my_callback, "light") + +# Listen for a state change involving light.office1 and return the state attribute +self.handle = self.listen_state(self.my_callback, "light.office_1") + +# Listen for a state change involving light.office1 and return the entire state as a dict +self.handle = self.listen_state(self.my_callback, "light.office_1", attribute = "all") + +# Listen for a state change involving the brightness attribute of light.office1 +self.handle = self.listen_state(self.my_callback, "light.office_1", attribute = "brightness") + +# Listen for a state change involving light.office1 turning on and return the state attribute +self.handle = self.listen_state(self.my_callback, "light.office_1", new = "on") + +# Listen for a state change involving light.office1 changing from brightness 100 to 200 and return the state attribute +self.handle = self.listen_state(self.my_callback, "light.office_1", old = "100", new = "200") + +# Listen for a state change involving light.office1 changing to state on and remaining on for a minute +self.handle = self.listen_state(self.my_callback, "light.office_1", new = "on", duration = 60) + +``` + +### {% linkable_title cancel_listen_state() %} + +Cancel a `listen_state()` callback. This will mean that the App will no longer be notified for the specific state change that has been cancelled. Other state changes will continue to be monitored. + +#### {% linkable_title Synopsis %} + +```python +cancel_listen_state(handle) +``` + +#### {% linkable_title Returns %} + +Nothing + +#### {% linkable_title Parameters %} + +##### {% linkable_title handle %} + +The handle returned when the `listen_state()` call was made. + +#### {% linkable_title Examples %} + +```python +self.cancel_listen_state(self.office_light_handle) +``` + +### {% linkable_title info_listen_state() %} + +Get information on state a callback from it's handle. + +#### {% linkable_title Synopsis %} + +```python +entity, attribute, kwargs = self.info_listen_state(self.handle) +``` + +#### {% linkable_title Returns %} + +entity, attribute, kwargs - the values supplied when the callback was initially created. + +#### {% linkable_title Parameters %} + +##### {% linkable_title handle %} + +The handle returned when the `listen_state()` call was made. + +#### {% linkable_title Examples %} + +```python +entity, attribute, kwargs = self.info_listen_state(self.handle) +``` + +## {% linkable_title Scheduler %} + +AppDaemon contains a powerful scheduler that is able to run with 1 second resolution to fire off specific events at set times, or after set delays, or even relative to sunrise and sunset. In general, events should be fired less than a second after specified but under certain circumstances there may be short additional delays. + +### {% linkable_title About Schedule Callbacks %} + +As with State Change callbacks, Scheduler Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this: + +```python + def my_callback(self, **kwargs): + +``` + +You can call the function whatever you like; you will reference it in the Scheduler call, and you can create as many callback functions as you need. + +The parameters have the following meanings: + +#### {% linkable_title self %} +A standard Python object reference + +#### {% linkable_title \*\*kwargs %} + +A dictionary containing Zero or more keyword arguments to be supplied to the callback. + +### {% linkable_title Creation of Scheduler Callbacks %} + +Scheduler callbacks are created through use of a number of convenience functions which can be used to suit the situation. + +#### {% linkable_title run_in() %} + +Run the callback in a defined number of seconds. This is used to add a delay, for instance a 60 second delay before a light is turned off after it has been triggered by a motion detector. This callback should always be used instead of `time.sleep()` as discussed previously. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_in(callback, delay, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### vcallback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title delay %} + +Delay, in seconds before the callback is invoked. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +self.handle = self.run_in(self.run_in_c) +self.handle = self.run_in(self.run_in_c, title = "run_in5") +``` +#### {% linkable_title run_once() %} + +Run the callback once, at the specified time of day. If the time of day is in the past, the callback will occur on the next day. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_once(callback, time, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title time %} + +A Python `time` object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run at 4pm today, or 4pm tomorrow if it is already after 4pm +import datetime +... +runtime = datetime.time(16, 0, 0) +handle = self.run_once(self.run_once_c, runtime) +``` + +#### {% linkable_title run_at() %} + +Run the callback once, at the specified date and time. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_at(callback, datetime, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. `run_at()` will raise an exception if the specified time is in the past. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title datetime %} + +A Python `datetime` object that specifies when the callback will occur. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run at 4pm today +import datetime +... +runtime = datetime.time(16, 0, 0) +today = datetime.date.today() +event = datetime.datetime.combine(today, runtime) +handle = self.run_once(self.run_once_c, event) +``` +#### {% linkable_title run_daily() %} + +Execute a callback at the same time every day. If the time has already passed, the function will not be invoked until the following day at the specified time. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_daily(callback, time, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title time %} + +A Python `time` object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run daily at 7pm +import datetime +... +time = datetime.time(19, 0, 0) +self.run_daily(self.run_daily_c, runtime) +``` + +#### {% linkable_title run_hourly() %} + +Execute a callback at the same time every hour. If the time has already passed, the function will not be invoked until the following hour at the specified time. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_hourly(callback, time = None, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title time %} + +A Python `time` object that specifies when the callback will occur, the hour component of the time object is ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start an hour from the time that `run_hourly()` was executed. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run every hour, on the hour +import datetime +... +time = datetime.time(0, 0, 0) +self.run_daily(self.run_daily_c, runtime) +``` +#### {% linkable_title run_minutely() %} + +Execute a callback at the same time every minute. If the time has already passed, the function will not be invoked until the following minute at the specified time. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_minutely(callback, time = None, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title time %} + +A Python `time` object that specifies when the callback will occur, the hour and minute components of the time object are ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start a minute from the time that `run_minutely()` was executed. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run Every Minute on the minute +import datetime +... +time = datetime.time(0, 0, 0) +self.run_minutely(self.run_minutely_c, time) +``` + +#### {% linkable_title run_every() %} + +Execute a repeating callback with a configurable delay starting at a specific time. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_every(callback, time, repeat, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title time %} + +A Python `time` object that specifies when the initial callback will occur. + +##### {% linkable_title repeat %} + +After the initial callback has occurred, another will occur every `repeat` seconds. + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Run every 17 minutes starting in 2 hours time +import datetime +... +self.run_every(self.run_every_c, time, 17 * 60) +``` + +#### {% linkable_title cancel_timer() %} +Cancel a previously created timer + +#### {% linkable_title Synopsis %} + +```python +self.cancel_timer(handle) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title handle %} + +A handle value returned from the original call to create the timer. + +#### {% linkable_title Examples %} + +```python +self.cancel_timer(handle) +``` + +### {% linkable_title info_timer() %} + +Get information on a scheduler event from it's handle. + +#### {% linkable_title Synopsis %} + +```python +time, interval, kwargs = self.info_timer(handle) +``` + +#### {% linkable_title Returns %} + +time - datetime object representing the next time the callback will be fired + +interval - repeat interval if applicable, `0` otherwise. + +kwargs - the values supplied when the callback was initially created. + +#### {% linkable_title Parameters %} + +##### {% linkable_title handle %} + +The handle returned when the scheduler call was made. + +#### {% linkable_title Examples %} + +```python +time, interval, kwargs = self.info_timer(handle) +``` + +### {% linkable_title Scheduler Ransomization %} + +All of the scheduler calls above support 2 additional optional arguments, `random_start` and `random_end`. Using these arguments it is possible to randomize the firing of callbacks to the degree desired by setting the appropriate number of seconds with the parameters. + +- `random_start` - start of range of the random time +- `random_end` - end of range of the random time + +`random_start` must always be numerically lower than `random_end`, they can be negative to denote a random offset before and event, or positive to denote a random offset after an event. The event would be a an absolute or relative time or sunrise/sunset depending on whcih scheduler call you use and these values affect the base time by the spcified amount. If not specified, they will default to `0`. + +For example: + +```python +# Run a callback in 2 minutes minus a random number of seconds between 0 and 60, e.g. run between 60 and 120 seconds from now +self.handle = self.run_in(callback, 120, random_start = -60, **kwargs) +# Run a callback in 2 minutes plus a random number of seconds between 0 and 60, e.g. run between 120 and 180 seconds from now +self.handle = self.run_in(callback, 120, random_end = 60, **kwargs) +# Run a callback in 2 minutes plus or minus a random number of seconds between 0 and 60, e.g. run between 60 and 180 seconds from now +self.handle = self.run_in(callback, 120, random_start = -60, random_end = 60, **kwargs) +``` + +## {% linkable_title Sunrise and Sunset %} + +AppDaemon has a number of features to allow easy tracking of sunrise and sunset as well as a couple of scheduler functions. Note that the scheduler functions also support the randomization parameters described above, but they cannot be used in conjunction with the `offset` parameter`. + +### {% linkable_title run_at_sunrise() %} + +Run a callback at or around sunrise. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_at_sunrise(callback, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title offset = %} + +The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with `random_start` or `random_end` + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +import datetime +... +# Run 45 minutes before sunset +self.run_at_sunrise(self.sun, offset = datetime.timedelta(minutes = -45).total_seconds(), "Sunrise -45 mins") +# or you can just do the math yourself +self.run_at_sunrise(self.sun, offset = 30 * 60, "Sunrise +30 mins") +# Run at a random time +/- 60 minutes from sunrise +self.run_at_sunrise(self.sun, random_start = -60*60, random_end = 60*60, "Sunrise, random +/- 60 mins") +# Run at a random time between 30 and 60 minutes before sunrise +self.run_at_sunrise(self.sun, random_start = -60*60, random_end = 30*60, "Sunrise, random - 30 - 60 mins") +``` + +### {% linkable_title run_at_sunset() %} + +Run a callback at or around sunset. + +#### {% linkable_title Synopsis %} + +```python +self.handle = self.run_at_sunset(callback, offset, **kwargs) +``` + +#### {% linkable_title Returns %} + +A handle that can be used to cancel the timer. + +#### {% linkable_title Parameters %} + +##### {% linkable_title callback %} + +Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. + +##### {% linkable_title offset = %} + +The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with `random_start` or `random_end` + +##### {% linkable_title \*\*kwargs %} + +Arbitary keyword parameters to be provided to the callback function when it is invoked. + +#### {% linkable_title Examples %} + +```python +# Example using timedelta +import datetime +... +self.run_at_sunset(self.sun, datetime.timedelta(minutes = -45).total_seconds(), "Sunset -45 mins") +# or you can just do the math yourself +self.run_at_sunset(self.sun, 30 * 60, "Sunset +30 mins") +# Run at a random time +/- 60 minutes from sunset +self.run_at_sunset(self.sun, random_start = -60*60, random_end = 60*60, "Sunset, random +/- 60 mins") +# Run at a random time between 30 and 60 minutes before sunset +self.run_at_sunset(self.sun, random_start = -60*60, random_end = 30*60, "Sunset, random - 30 - 60 mins") +``` +### {% linkable_title sunrise() %} + +Return the time that the next Sunrise will occur. + +#### {% linkable_title Synopsis %} + +```python +self.sunrise() +``` + +#### {% linkable_title Returns %} + +A Python datetime that represents the next time Sunrise will occur. + +#### {% linkable_title Examples %} + +```python +rise_time = self.sunrise() +``` +### {% linkable_title sunset() %} + +Return the time that the next Sunset will occur. + +#### {% linkable_title Synopsis %} + +```python +self.sunset() +``` + +#### {% linkable_title Returns %} + +A Python datetime that represents the next time Sunset will occur. + +#### {% linkable_title Examples %} + +```python +set_time = self.sunset() +``` +### {% linkable_title sun_up() %} + +A function that allows you to determine if the sun is currently up. + +#### {% linkable_title Synopsis %} + +```python +result = self.sun_up() +``` + +#### {% linkable_title Returns %} + +`True` if the sun is up, False otherwise. + +#### {% linkable_title Examples %} + +```python +if self.sun_up(): + do something +``` + +### {% linkable_title sun_down() %} + +A function that allows you to determine if the sun is currently down. + +#### {% linkable_title Synopsis %} + +```python +result = self.sun_down() +``` + +#### {% linkable_title Returns %} + +`True` if the sun is down, False otherwise. + +#### {% linkable_title Examples %} + +```python +if self.sun_down(): + do something +``` + +## {% linkable_title Calling Services %} + +### {% linkable_title About Services %} + +Services within Home Assistant are how changes are made to the system and its devices. Services can be used to turn lights on and off, set thermostats and a whole number of other things. Home Assistant supplies a single interface to all these disparate services that take arbitrary parameters. AppDaemon provides the `call_service()` function to call into Home Assistant and run a service. In addition, it also provides convenience functions for some of the more common services making calling them a little easier. + +### {% linkable_title call_service() %} + +Call service is the basic way of calling a service within AppDaemon. It can call any service and provide any required parameters. Available services can be found using the developer tools in the UI. For listed services, the part before the first period is the domain, and the part after is the service name. For instance, `light.turn_on` has a domain of `light` and a service name of `turn_on`. + +#### {% linkable_title Synopsis %} + +```python +self.call_service(self, service, **kwargs) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title service %} + +The service name, e.g. `light.turn_on`. + +##### {% linkable_title \*\*kwargs %} + +Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g. `entity_id = light.office_1`. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an `entity_id` however, so use of the above example is very common with this call. + +#### {% linkable_title Examples %} + +```python +self.call_service("light/turn_on", entity_id = "light.office_lamp", color_name = "red") +self.call_service("notify/notify", title = "Hello", message = "Hello World") +``` +### {% linkable_title turn_on() %} + +This is a convenience function for the `homassistant.turn_on` function. It is able to turn on pretty much anything in Home Assistant that can be turned on or run: + +- Lights +- Switches +- Scenes +- Scripts + +And many more. + +#### {% linkable_title Synopsis %} + +```python +self.turn_on(entity_id, **kwargs) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity_id of the thing to be turned on, e.g. `light.office_lamp` or ```scene.downstairs_on``` + +##### {% linkable_title \*\*kwargs %} + +A comma separated list of key value pairs to allow specification of parameters over and above `entity_id`. + +#### {% linkable_title Examples %} + +```python +self.turn_on("switch.patio_lights") +self.turn_on("scene.bedrrom_on") +self.turn_on("light.office_1", color_name = "green") +``` + +### {% linkable_title turn_off() %} + +This is a convenience function for the `homassistant.turn_off` function. Like `homeassistant.turn_on`, it is able to turn off pretty much anything in Home Assistant that can be turned off. + +#### {% linkable_title Synopsis %} + +```python +self.turn_off(entity_id) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity_id of the thing to be turned off, e.g. `light.office_lamp` or `scene.downstairs_on`. + +#### {% linkable_title Examples %} + +```python +self.turn_off("switch.patio_lights") +self.turn_off("light.office_1") +``` + +### {% linkable_title toggle() %} + +This is a convenience function for the `homassistant.toggle` function. It is able to flip the state of pretty much anything in Home Assistant that can be turned on or off. + +#### {% linkable_title Synopsis %} + +```python +self.toggle(entity_id) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity_id of the thing to be toggled, e.g. `light.office_lamp` or `scene.downstairs_on`. + +#### {% linkable_title Examples %} + +```python +self.toggle("switch.patio_lights") +self.toggle("light.office_1", color_name = "green") +``` + +### {% linkable_title select_value() %} + +This is a convenience function for the `input_slider.select_value` function. It is able to set the value of an input_slider in Home Assistant. + +#### {% linkable_title Synopsis %} + +```python +self.select_value(entity_id, value) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity_id of the input_slider to be changed, e.g. `input_slider.alarm_hour`. + +##### {% linkable_title value %} + +The new value to set the input slider to. + +#### {% linkable_title Examples %} + +```python +self.select_value("input_slider.alarm_hour", 6) +``` + +### {% linkable_title select_option() %} + +This is a convenience function for the `input_select.select_option` function. It is able to set the value of an input_select in Home Assistant. + +#### {% linkable_title Synopsis %} + +```python +self.select_option(entity_id, option) +``` + +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity_id of the input_select to be changed, e.g. `input_select.mode`. + +##### {% linkable_title value %} + +The new value to set the input slider to. + +#### {% linkable_title Examples %} + +```python +self.select_option("input_select.mode", "Day") +``` + +### {% linkable_title notify() %} + +This is a convenience function for the `notify.notify` service. It will send a notification to your defualt notification service. If you have more than one, use `call_service()` to call the specific notification service you require instead. + +#### {% linkable_title Synopsis %} + +```python +notify(message, title=None) +``` +#### {% linkable_title Returns %} + +None + +#### {% linkable_title Parameters %} + +##### {% linkable_title message %} + +Message to be sent to the notification service. + +##### {% linkable_title title %} + +Title of the notification - optional. + +#### {% linkable_title Examples %} + +```python +self.notify("", "Switching mode to Evening") +``` + +## {% linkable_title Events %} + +### {% linkable_title About Events %} + +Events are a fundamental part of how Home Assistant works under the covers. HA has an event bus that all components can read and write to, enabling components to inform other components when important events take place. We have already seen how state changes can be propagated to AppDaemon - a state change however is merely an example of an event within Home Assistant. There are several other event types, among them are: + +- `homeassistant_start` +- `homeassistant_stop` +- `state_changed` +- `service_registered` +- `call_service` +- `service_executed` +- `platform_discovered` +- `component_loaded` + +Using AppDaemon, it is possible to subscribe to specific events as well as fire off events. + +In addition to the Home Assistant supplied events, AppDaemon adds 2 more events. These are internal to AppDaemon and are not visible on the Home Assistant bus: + +- `appd_started` - fired once when AppDaemon is first started and after Apps are initialized +- `ha_started` - fired every time AppDaemon detects a Home Assistant restart + +### {% linkable_title About Event Callbacks %} + +As with State Change and Scheduler callbacks, Event Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this: + +```python + def my_callback(self, event_name, data, kwargs): + +``` + +You can call the function whatever you like - you will reference it in the Scheduler call, and you can create as many callback functions as you need. + +The parameters have the following meanings: + +#### {% linkable_title self %} + +A standard Python object reference. + +#### {% linkable_title event_name %} + +Name of the event that was called, e.g. `call_service`. + +#### {% linkable_title data %} + +Any data that the system supplied with the event as a dict. + +#### {% linkable_title kwargs %} + +A dictionary containing Zero or more user keyword arguments to be supplied to the callback. + +### {% linkable_title listen_event() %} + +Listen event sets up a callback for a specific event, or any event. + +#### {% linkable_title Synopsis %} + +```python +handle = listen_event(function, event = None, **kwargs): +``` +#### {% linkable_title Returns %} + +A handle that can be used to cancel the callback. + +#### {% linkable_title Parameters %} + +##### {% linkable_title function %} + +The function to be called when the event is fired. + +##### {% linkable_title event %} + +Name of the event to subscribe to. Can be a standard Home Assistant event such as `service_registered` or an arbitrary custom event such as `"MODE_CHANGE"`. If no event is specified, `listen_event()` will subscribe to all events. + +##### {% linkable_title \*\*kwargs (optional) %} + +One or more keyword value pairs representing App specific parameters to supply to the callback. If the keywords match values within the event data, they will act as filters, meaning that if they don't match the values, the callback will not fire. + +As an example of this, a Minimote controller when activated will generate an event called `zwave.scene_activated`, along with 2 pieces of data that are specific to the event - `entity_id` and `scene`. If you include keyword values for either of those, the values supplied to the `listen_event()1 call must match the values in the event or it will not fire. If the keywords do not match any of the data in the event they are simply ignored. + +Filtering will work with any event type, but it will be necessary to figure out the data associated with the event to understand what values can be filtered on. This can be achieved by examining Home Assistant's logfiles when the event fires. + +#### {% linkable_title Examples %} + +```python +self.listen_event(self.mode_event, "MODE_CHANGE") +# Listen for a minimote event activating scene 3: +self.listen_event(self.generic_event, "zwave.scene_activated", scene_id = 3) +# Listen for a minimote event activating scene 3 from a specific minimote: +self.listen_event(self.generic_event, "zwave.scene_activated", entity_id = "minimote_31", scene_id = 3) +``` + +### {% linkable_title cancel_listen_event() %} + +Cancels callbacks for a specific event. + +#### {% linkable_title Synopsis %} + +```python +cancel_listen_event(handle) +``` +#### {% linkable_title Returns %} + +None. + +#### {% linkable_title Parameters %} + +##### handle + +A handle returned from a previous call to `listen_event()`. + +#### {% linkable_title Examples %} + +```python +self.cancel_listen_event(handle) +``` + +### {% linkable_title info_listen_event() %} + +Get information on an event callback from it's handle. + +#### {% linkable_title Synopsis %} + +```python +service, kwargs = self.info_listen_event(handle) +``` + +#### {% linkable_title Returns %} + +service, kwargs - the values supplied when the callback was initially created. + +#### {% linkable_title Parameters %} + +##### {% linkable_title handle %} + +The handle returned when the `listen_event()` call was made. + +#### {% linkable_title Examples %} + +```python +service, kwargs = self.info_listen_event(handle) +``` + + +### {% linkable_title fire_event() %} + +Fire an event on the HomeAssistant bus, for other components to hear. + +#### {% linkable_title Synopsis %} + +```python +fire_event(event, **kwargs) +``` + +#### {% linkable_title Returns %} + +None. + +#### {% linkable_title Parameters %} + +##### {% linkable_title event %} + +Name of the event. Can be a standard Home Assistant event such as `service_registered` or an arbitrary custom event such as `"MODE_CHANGE"`. + +##### {% linkable_title \*\*kwargs %} + +Zero or more keyword arguments that will be supplied as part of the event. + +#### {% linkable_title Examples %} + +```python +self.fire_event("MY_CUSTOM_EVENT", jam="true") +``` + +### {% linkable_title Event Callback Function Signature %} + +Functions called as an event callback will be supplied with 2 arguments: + +```python +def service(self, event_name, data): +``` + +#### {% linkable_title event_name %} + +The name of the event that caused the callback, e.g. `"MODE_CHANGE"` or `call_service`. + +#### {% linkable_title data %} + +A dictionary containing any additional information associated with the event. + +### {% linkable_title Use of Events for Signalling between Home Assistant and AppDaemon %} + +Home Assistant allows for the creation of custom events and existing components can send and receive them. This provides a useful mechanism for signaling back and forth between Home Assistant and AppDaemon. For instance, if you would like to create a UI Element to fire off some code in Home Assistant, all that is necessary is to create a script to fire a custom event, then subscribe to that event in AppDaemon. The script would look something like this: + +```yaml +alias: Day +sequence: +- event: MODE_CHANGE + event_data: + mode: Day +``` + +The custom event `MODE_CHANGE` would be subscribed to with: + +```python +self.listen_event(self.mode_event, "MODE_CHANGE") +``` + +Home Assistant can send these events in a variety of other places - within automations, and also directly from Alexa intents. Home Assistant can also listen for custom events with it's automation component. This can be used to signal from AppDaemon code back to home assistant. Here is a sample automation: + +```yaml +automation: + trigger: + platform: event + event_type: MODE_CHANGE + ... + ... +``` + +This can be triggered with a call to AppDaemon's fire_event() as follows: + +```python +self.fire_event("MODE_CHANGE", mode = "Day") +``` + +## {% linkable_title Presence %} + +Presence in Home Assistant is tracked using Device Trackers. The state of all device trackers can be found using the `get_state()` call, however AppDaemon provides several convenience functions to make this easier. + +### {% linkable_title get_trackers() %} + +Return a list of all device trackers. This is designed to be iterated over. + +#### {% linkable_title Synopsis %} + +```python +tracker_list = get_trackers() +``` +#### {% linkable_title Returns %} + +An iterable list of all device trackers. + +#### {% linkable_title Examples %} + +```python +trackers = self.get_trackers() +for tracker in trackers: + do something +``` + +### {% linkable_title get_tracker_state() %} + +Get the state of a tracker. The values returned depend in part on the configuration and type of device trackers in the system. Simpler tracker types like `Locative` or `NMAP` will return one of 2 states: + +- `home` +- `not_home` + +Some types of device tracker are in addition able to supply locations that have been configured as Geofences, in which case the name of that location can be returned. + +#### {% linkable_title Synopsis %} + +```python +location = self.get_tracker_state(tracker_id) +``` + +#### {% linkable_title Returns %} + +A string representing the location of the tracker. + +#### {% linkable_title Parameters %} + +##### {% linkable_title tracker_id %} + +Fully qualified entity_id of the device tracker to query, e.g. `device_tracker.andrew`. + +#### {% linkable_title Examples %} + +```python +trackers = self.get_trackers() +for tracker in trackers: + self.log("{} is {}".format(tracker, self.get_tracker_state(tracker))) +``` + +### {% linkable_title everyone_home() %} + +A convenience function to determine if everyone is home. Use this in preference to getting the state of `group.all_devices()` as it avoids a race condition when using state change callbacks for device trackers. + +#### {% linkable_title Synopsis %} + +```python +result = self.everyone_home() +``` +#### {% linkable_title Returns %} + +Returns `True` if everyone is at home, `False` otherwise. + +#### {% linkable_title Examples %} + +```python +if self.everyone_home(): + do something +``` +### {% linkable_title anyone_home() %} + +A convenience function to determine if one or more person is home. Use this in preference to getting the state of `group.all_devices()` as it avoids a race condition when using state change callbacks for device trackers. + +#### {% linkable_title Synopsis %} + +```python +result = self.anyone_home() +``` + +#### {% linkable_title Returns %} + +Returns `True` if anyone is at home, `False` otherwise. + +#### {% linkable_title Examples %} + +```python +if self.anyone_home(): + do something +``` +### {% linkable_title noone_home() %} + +A convenience function to determine if no people are at home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers. + +#### {% linkable_title Synopsis %} + +```python +result = self.noone_home() +``` + +#### {% linkable_title Returns %} + +Returns `True` if no one is home, `False` otherwise. + +#### {% linkable_title Examples %} + +```python +if self.noone_home(): + do something +``` + +## {% linkable_title Miscellaneous Helper Functions %} + +### {% linkable_title time() %} + +Returns a python `time` object representing the current time. Use this in preference to the standard Python ways to discover the current time, especially when using the "Time Travel" feature for testing. + +#### {% linkable_title Synopsis %} + +```python +time() +``` + +#### {% linkable_title Returns %} + +A localised Python time object representing the current AppDaemon time. + +#### {% linkable_title Parameters %} + +None + +#### {% linkable_title Example %} + +```python +now = self.time() +``` + +### {% linkable_title date() %} + +Returns a python `date` object representing the current date. Use this in preference to the standard Python ways to discover the current date, especially when using the "Time Travel" feature for testing. + +#### {% linkable_title Synopsis %} + +```python +date() +``` + +#### {% linkable_title Returns %} + +A localised Python time object representing the current AppDaemon date. + +#### {% linkable_title Parameters %} + +None + +#### {% linkable_title Example %} + +```python +today = self.date() +``` + +### {% linkable_title datetime() %} + +Returns a python `datetime` object representing the current date and time. Use this in preference to the standard Python ways to discover the current time, especially when using the "Time Travel" feature for testing. + +#### {% linkable_title Synopsis %} + +```python +datetime() +``` + +#### {% linkable_title Returns %} + +A localised Python datetime object representing the current AppDaemon date and time. + +#### {% linkable_title Parameters %} + +None + +#### {% linkable_title Example %} + +```python +now = self.datetime() +``` + + +### {% linkable_title convert_utc() %} + +Home Assistant provides timestamps of several different sorts that may be used to gain additional insight into state changes. These timestamps are in UTC and are coded as ISO 8601 Combined date and time strings. `convert_utc()` will accept one of these strings and convert it to a localised Python datetime object representing the timestamp + +#### {% linkable_title Synopsis %} + +```python +convert_utc(utc_string) +``` + +#### {% linkable_title Returns %} + +`convert_utc(utc_string)` returns a localised Python datetime object representing the timestamp. + +#### {% linkable_title Parameters %} + +##### {% linkable_title utc_string %} + +An ISO 8601 encoded date and time string in the following format: `2016-07-13T14:24:02.040658-04:00` + +#### {% linkable_title Example %} + +###{% linkable_title parse_time() %} + +Takes a string representation of a time, or sunrise or sunset offset and converts it to a `datetime.time` object. + +#### {% linkable_title Synopsis %} + +```python +parse_time(time_string) +``` + +#### {% linkable_title Returns %} + +A `datetime.time` object, representing the time given in the `time_string` argument. + +#### {% linkable_title Parameters %} + +##### {% linkable_title time_string %} + +A representation of the time in a string format with one of the following formats: + +- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. +- sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds + +#### {% linkable_title Example %} + +```python +time = self.parse_time("17:30:00") +time = self.parse_time("sunrise") +time = self.parse_time("sunset + 00:30:00") +time = self.parse_time("sunrise + 01:00:00") +``` + +### {% linkable_title now_is_between() %} + +Takes two string representations of a time, or sunrise or sunset offset and returns true if the current time is between those 2 times. `now_is_between()` can correctly handle transitions across midnight. + +#### {% linkable_title Synopsis %} + +```python +now_is_between(start_time_string, end_time_string) +``` + +#### {% linkable_title Returns %} + +`True` if the current time is within the specified start and end times, `False` otherwise. + +#### {% linkable_title Parameters %} + +##### {% linkable_title start_time_string, end_time_string %} + +A representation of the start and end time respectively in a string format with one of the following formats: + +- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. +- sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds + +#### {% linkable_title Example %} + +```python +if self.now_is_between("17:30:00", "08:00:00"): + do something +if self.now_is_between("sunset - 00:45:00", "sunrise + 00:45:00"): + do something +``` + +### {% linkable_title friendly_name() %} + +`frindly_name()` will return the Friendly Name of an entity if it has one. + +#### {% linkable_title Synopsis %} + +```python +Name = self.friendly_name(entity_id) +``` + +#### {% linkable_title Returns %} + +The friendly name of the entity if it exists or the entity id if not. + +#### {% linkable_title Example %} + +```python +tracker = "device_tracker.andrew" +self.log("{} ({}) is {}".format(tracker, self.friendly_name(tracker), self.get_tracker_state(tracker))) +``` + +### {% linkable_title split_entity() %} + +`split_entity()` will take a fully qualified entity id of the form `light.hall_light` and split it into 2 values, the device and the entity, e.g. `light` and `hall_light`. + +#### {% linkable_title Synopsis %} + +```python +device, entity = self.split_entity(entity_id) +``` + +#### {% linkable_title Parameters %} + +##### {% linkable_title entity_id %} + +Fully qualified entity id to be split. + +#### {% linkable_title Returns %} + +A list with 2 entries, the device and entity respectively. + +#### {% linkable_title Example %} + +```python +device, entity = self.split_entity(entity_id) +if device == "scene": + do something specific to scenes +``` + + +### {% linkable_title get_app() %} + +`get_app()` will return the instantiated object of another app running within the system. This is useful for calling functions or accessing variables that reside in different apps without requiring duplication of code. + +#### {% linkable_title Synopsis %} + +```python +get_app(self, name) +``` +#### {% linkable_title Parameters %} + +##### {% linkable_title name %} + +Name of the app required. This is the name specified in header section of the config file, not the module or class. + +#### {% linkable_title Returns %} + +An object reference to the class. + +#### {% linkable_title Example %} +```python +MyApp = self.get_app("MotionLights") +MyApp.turn_light_on() +``` + +### {% linkable_title split_device_list() %} + +`split_device_list()` will take a comma separated list of device types (or anything else for that matter) and return them as an iterable list. This is intended to assist in use cases where the App takes a list of entities from an argument, e.g. a list of sensors to monitor. If only one entry is provided, an iterable list will still be returned to avoid the need for special processing. + +#### {% linkable_title Synopsis %} + +```python +devices = split_device_list(list) +``` + +#### {% linkable_title Returns %} + +A list of split devices with 1 or more entries. + +#### {% linkable_title Example %} + +```python +for sensor in self.split_device_list(self.args["sensors"]): + do something for each sensor, e.g. make a state subscription +``` + + +### {% linkable_title Writing to Logfiles %} + +AppDaemon uses 2 separate logs - the general log and the error log. An AppDaemon App can write to either of these using the supplied convenience methods `log()` and `error()`, which are provided as part of parent `AppDaemon` class, and the call will automatically pre-pend the name of the App making the call. The `-D` option of AppDaemon can be used to specify what level of logging is required and the logger objects will work as expected. + +### {% linkable_title log() %} + +#### {% linkable_title Synopsis %} + +```python +log(message, level = "INFO") +``` + +#### {% linkable_title Returns %} + +Nothing + +#### {% linkable_title Parameters %} + +##### {% linkable_title Message %} + +The message to log. + +##### {% linkable_title level %} + +The log level of the message - takes a string representing the standard logger levels. + +#### {% linkable_title Examples %} + +```python +self.log("Log Test: Parameter is {}".format(some_variable)) +self.log("Log Test: Parameter is {}".format(some_variable), level = "ERROR") +``` + +### {% linkable_title error() %} + +#### {% linkable_title Synopsis %} + +```python +error(message, level = "WARNING") +``` +#### {% linkable_title Returns %} + +Nothing + +#### {% linkable_title Parameters %} + +##### {% linkable_title Message %} + +The message to log. + +##### {% linkable_title level %} + +The log level of the message - takes a string representing the standard logger levels. + +#### {% linkable_title Examples %} + +```python +self.error("Some Warning string") +self.error("Some Critical string", level = "CRITICAL") +``` + +## {% linkable_title Sharing information between Apps %} + +Sharing information between different Apps is very simple if required. Each app gets access to a global dictionary stored in a class attribute called `self.global_vars`. Any App can add or read any key as required. This operation is not however threadsafe so some car is needed. + +In addition, Apps have access to the entire configuration if required, meaning they can access AppDaemon configuration items as well as parameters from other Apps. To use this, there is a class attribute called `self.config`. It contains a `ConfigParser` object, which is similar in operation to a `Dictionary`. To access any apps parameters, simply reference the ConfigParser object using the Apps name (form the config file) as the first key, and the parameter required as the second, for instance: + +```python +other_apps_arg = self.config["some_app"]["some_parameter"]. +``` + +To get AppDaemon's config parameters, use the key "AppDaemon", e.g.: + +```python +app_timezone = self.config["AppDaemon"]["time_zone"] +``` + +And finally, it is also possible to use the AppDaemon as a global area for sharing parameters across Apps. Simply add the required parameters to the AppDaemon section of your config: + +```ini +[AppDaemon] +ha_url = +ha_key = +... +global_var = hello world +``` + +Then access it as follows: + +```python +my_global_var = conf.config["AppDaemon"]["global_var"] +``` + +## {% linkable_title Development Workflow %} + +Developing Apps is intended to be fairly simple but is an exercise in programming like any other kind of Python programming. As such, it is expected that apps will contain syntax errors and will generate exceptions during the development process. AppDaemon makes it very easy to iterate through the development process as it will automatically reload code that has changed and also will reload code if any of the parameters in the configuration file change as well. + +The recommended workflow for development is as follows: + +- Open a window and tail the `appdaemon.log` file +- Open a second window and tail the `error.log` file +- Open a third window or the editor of your choice for editing the App + +With this setup, you will see that every time you write the file, AppDaemon will log the fact and let you know it has reloaded the App in the `appdaemon.log` file. + +If there is an error in the compilation or a runtime error, this will be directed to the `error.log` file to enable you to see the error and correct it. When an error occurs, there will also be a warning message in `appdaemon.log` to tell you to check the error log. + +## {% linkable_title Time Travel %} + +OK, time travel sadly isn't really possible but it can be very useful when testing Apps. For instance, imagine you have an App that turns a light on every day at sunset. It might be nice to test it without waiting for Sunset - and with AppDaemon's "Time Travel" features you can. + +### {% linkable_title Choosing a Start Time %} + +Internally, AppDaemon keeps track of it's own time relative to when it was started. This make is possible to start AppDaemon with a different start time and date to the current time. For instance to test that sunset App, start AppDaemon at a time just before sunset and see if it works as expected. To do this, simply use the "-s" argument on AppDaemon's command line. e,g,: + +```bash +$ appdaemon -s "2016-06-06 19:16:00" +2016-09-06 17:16:00 INFO AppDaemon Version 1.3.2 starting +2016-09-06 17:16:00 INFO Got initial state +2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py +... +``` + +Note the timestamps in the log - AppDaemon believes it is now just before sunset and will process any callbacks appropriately. + +### {% linkable_title Speeding things up %} + +Some Apps need to run for periods of a day or two for you to test all aspects. This can be time consuming, but Time Travel can also help here in two ways. The first is by speeding up time. To do this, simply use the `-t` option on the command line. This specifies the amount of time a second lasts while time travelling. The default of course is 1 second, but if you change it to `0.1` for instance, AppDaemon will work 10x faster. If you set it to `0`, AppDaemon will work as fast as possible and, depending in your hardware, may be able to get through an entire day in a matter of minutes. Bear in mind however, due to the threaded nature of AppDaemon, when you are running with `-t 0` you may see actual events firing a little later than expected as the rest of the system tries to keep up with the timer. To set the tick time, start AppDaemon as follows: + +```bash +$ appdaemon -t 0.1 +``` + +AppDaemon also has an interval flag - think of this as a second multiplier. If the flag is set to 3600 for instance, each tick of the scheduler will jump the time forward by an hour. This is good for covering vast amounts of time quickly but event firing accuracy will suffer as a result. For example: + +```bash +$ appdaemon -e 3600 +``` + +### Automatically stopping + +AppDaemon can be set to terminate automatically at a specific time. This can be useful if you want to repeatedly rerun a test, for example to test that random values are behaving as expected. Simply specify the end time with the `-e` flag as follows: + +```bash +$ appdaemon -e "2016-06-06 10:10:00" +2016-09-06 17:16:00 INFO AppDaemon Version 1.3.2 starting +2016-09-06 17:16:00 INFO Got initial state +2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py +... +``` + +The `-e` flag is most useful when used in conjuntion with the -s flag and optionally the `-t` flag. For example, to run from just before sunset, for an hour, as fast as possible: + +```bash +$ appdaemon -s "2016-06-06 19:16:00" -s "2016-06-06 20:16:00" -t 0 +``` + + +### {% linkable_title A Note on Times %} + +Some Apps you write may depend on checking times of events relative to the current time. If you are time travelling this will not work if you use standard python library calls to get the current time and date etc. For this reason, always use the AppDamon supplied `time()`, `date()` and `datetime()` calls, documented earlier. These calls will consult with AppDaemon's internal time rather than the actual time and give you the correct values. diff --git a/source/_docs/appdaemon/configuration.markdown b/source/_docs/appdaemon/configuration.markdown new file mode 100644 index 000000000000..ec955aff6221 --- /dev/null +++ b/source/_docs/appdaemon/configuration.markdown @@ -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 +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 = +ha_key = +logfile = STDOUT +errorfile = STDERR +app_dir = /conf/apps +threads = 10 +latitude = +longitude = +elevation = +cert_path = +# 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 = +ha_key = +logfile = STDOUT +errorfile = STDERR +app_dir = /conf/apps +threads = 10 +latitude = +longitude = +elevation = +``` + +You can run Docker and point the conf volume to that directory. diff --git a/source/_docs/appdaemon/example_apps.markdown b/source/_docs/appdaemon/example_apps.markdown new file mode 100644 index 000000000000..2d7b659ad797 --- /dev/null +++ b/source/_docs/appdaemon/example_apps.markdown @@ -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 +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. \ No newline at end of file diff --git a/source/_docs/appdaemon/installation.markdown b/source/_docs/appdaemon/installation.markdown new file mode 100644 index 000000000000..6eb9f1f16c50 --- /dev/null +++ b/source/_docs/appdaemon/installation.markdown @@ -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 +hide_github_edit: true +--- + +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 . +``` diff --git a/source/_docs/appdaemon/operation.markdown b/source/_docs/appdaemon/operation.markdown new file mode 100644 index 000000000000..9f643719a614 --- /dev/null +++ b/source/_docs/appdaemon/operation.markdown @@ -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 +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. diff --git a/source/_docs/appdaemon/reboot.markdown b/source/_docs/appdaemon/reboot.markdown new file mode 100644 index 000000000000..96d7b9552b89 --- /dev/null +++ b/source/_docs/appdaemon/reboot.markdown @@ -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 +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. diff --git a/source/_docs/appdaemon/running.markdown b/source/_docs/appdaemon/running.markdown new file mode 100755 index 000000000000..78e5cf3976e6 --- /dev/null +++ b/source/_docs/appdaemon/running.markdown @@ -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 +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. + +## {% 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 /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 + -e ENDTIME, --endtime ENDTIME + end time for scheduler + -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. diff --git a/source/_docs/appdaemon/tutorial.markdown b/source/_docs/appdaemon/tutorial.markdown new file mode 100755 index 000000000000..bec655b90746 --- /dev/null +++ b/source/_docs/appdaemon/tutorial.markdown @@ -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 +hide_github_edit: true +--- + +## {% 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! + diff --git a/source/_docs/appdaemon/updating.markdown b/source/_docs/appdaemon/updating.markdown new file mode 100644 index 000000000000..20a5ebef141a --- /dev/null +++ b/source/_docs/appdaemon/updating.markdown @@ -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 +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. diff --git a/source/_docs/appdaemon/windows.markdown b/source/_docs/appdaemon/windows.markdown new file mode 100755 index 000000000000..360bf975a122 --- /dev/null +++ b/source/_docs/appdaemon/windows.markdown @@ -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 +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. + +## {% 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. diff --git a/source/_docs/backend.markdown b/source/_docs/backend.markdown new file mode 100644 index 000000000000..23659871a0e7 --- /dev/null +++ b/source/_docs/backend.markdown @@ -0,0 +1,17 @@ +--- +layout: page +title: "Backend of Home Assistant" +description: "Backend of Home Assistant." +date: 2017-02-14 12:50 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The frontend of Home Assistant is running with [Python 3](https://www.python.org/). + +The [Architecture page](/developers/architecture/) show the details about the elements running in the background of Home Assistant. + +To implement a new platform or component, please refer to the [Development documentation](/developers/development/). + diff --git a/source/_docs/hadashboard.markdown b/source/_docs/hadashboard.markdown new file mode 100644 index 000000000000..799468d0e6a6 --- /dev/null +++ b/source/_docs/hadashboard.markdown @@ -0,0 +1,20 @@ +--- +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 +--- + +HADashboard is a dashboard for [Home Assistant](https://home-assistant.io/) that is intended to be wall mounted, and is optimized for distance viewing. + +

    + + Sample Dashboard +

    + +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. + diff --git a/source/_docs/hadashboard/dash_config.markdown b/source/_docs/hadashboard/dash_config.markdown new file mode 100755 index 000000000000..4abc93d3fd88 --- /dev/null +++ b/source/_docs/hadashboard/dash_config.markdown @@ -0,0 +1,274 @@ +--- +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 +--- + +(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 +
  • +
    +
    • +``` + +- **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 `
    ` like this: + +``` html +
  • +
    +
    +
    • +``` + +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 +
  • +
    +
    • +``` + +- **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="°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="°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: + +

    + + The Alarm Panel +

    + +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="°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 +
  • +
    +
    • +``` +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="°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 +
    + +
    + +
    +
    + +``` + +- ***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://: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. diff --git a/source/_docs/hadashboard/hapush.markdown b/source/_docs/hadashboard/hapush.markdown new file mode 100755 index 000000000000..d390f22f3fc9 --- /dev/null +++ b/source/_docs/hadashboard/hapush.markdown @@ -0,0 +1,94 @@ +--- +layout: page +title: "HAPush" +description: "HAPush" +release_date: 2016-11-13 15:00:00 -0500 +sidebar: true +comments: false +sharing: true +footer: true +--- + +# 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 + 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 +``` diff --git a/source/_docs/hadashboard/installation.markdown b/source/_docs/hadashboard/installation.markdown new file mode 100755 index 000000000000..ecce1549c1b0 --- /dev/null +++ b/source/_docs/hadashboard/installation.markdown @@ -0,0 +1,151 @@ +--- +layout: page +title: "Installation" +description: "Installation" +release_date: 2016-11-13 15:00:00 -0500 +sidebar: true +comments: false +sharing: true +footer: true +--- + +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 /dashboards:/app/dashboards -v /lib/ha_conf.rb:/app/lib/ha_conf.rb -v /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. + diff --git a/source/_docs/hadashboard/reboot.markdown b/source/_docs/hadashboard/reboot.markdown new file mode 100755 index 000000000000..0d87ef287250 --- /dev/null +++ b/source/_docs/hadashboard/reboot.markdown @@ -0,0 +1,16 @@ +--- +layout: page +title: "Reboot" +description: "Reboot" +release_date: 2016-11-13 15:00:00 -0500 +sidebar: true +comments: false +sharing: true +footer: true +--- + +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. diff --git a/source/_docs/hadashboard/updating.markdown b/source/_docs/hadashboard/updating.markdown new file mode 100755 index 000000000000..96d6f9731bd2 --- /dev/null +++ b/source/_docs/hadashboard/updating.markdown @@ -0,0 +1,24 @@ +--- +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 +--- + +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. diff --git a/source/_docs/ios.markdown b/source/_docs/ios.markdown new file mode 100644 index 000000000000..862fce661c42 --- /dev/null +++ b/source/_docs/ios.markdown @@ -0,0 +1,66 @@ +--- +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 +--- + +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 + +

    +Currently, the app is only available via a closed beta. It will be on the App Store within the next few weeks. +

    + +

    + + An example of a Home Assistant group as seen in the iOS app. +

    + +## 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/ diff --git a/source/_docs/ios/devices_file.markdown b/source/_docs/ios/devices_file.markdown new file mode 100644 index 000000000000..4b27059456fa --- /dev/null +++ b/source/_docs/ios/devices_file.markdown @@ -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. diff --git a/source/_docs/ios/features.markdown b/source/_docs/ios/features.markdown new file mode 100644 index 000000000000..895a6a25311c --- /dev/null +++ b/source/_docs/ios/features.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Features" +description: "Describes the features of Home Assistant for iOS" +date: 2016-10-25 15:00:00 -0700 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Coming soon diff --git a/source/_docs/ios/integration.markdown b/source/_docs/ios/integration.markdown new file mode 100644 index 000000000000..e9db1dd875e9 --- /dev/null +++ b/source/_docs/ios/integration.markdown @@ -0,0 +1,25 @@ +--- +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 +--- + +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/` diff --git a/source/_docs/ios/location.markdown b/source/_docs/ios/location.markdown new file mode 100644 index 000000000000..f9bd14bf0a54 --- /dev/null +++ b/source/_docs/ios/location.markdown @@ -0,0 +1,36 @@ +--- +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 +--- + +## {% 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 diff --git a/source/_docs/ios/notifications.markdown b/source/_docs/ios/notifications.markdown new file mode 100644 index 000000000000..49490161de0f --- /dev/null +++ b/source/_docs/ios/notifications.markdown @@ -0,0 +1,14 @@ +--- +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 +--- + +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. diff --git a/source/_docs/ios/notifications/actions.markdown b/source/_docs/ios/notifications/actions.markdown new file mode 100644 index 000000000000..7cddb7e8aced --- /dev/null +++ b/source/_docs/ios/notifications/actions.markdown @@ -0,0 +1,142 @@ +--- +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 +--- + +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. + +

    + + Actionable notifications allow the user to send a command back to Home Assistant. +

    + +## {% 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. + +

    + + How the iOS device and Home Assistant work together to enable actionable notifications. +

    + +## {% 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: + 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. diff --git a/source/_docs/ios/notifications/architecture.markdown b/source/_docs/ios/notifications/architecture.markdown new file mode 100644 index 000000000000..c699e4529989 --- /dev/null +++ b/source/_docs/ios/notifications/architecture.markdown @@ -0,0 +1,15 @@ +--- +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 +--- + +

    + + The push notification infrastructure layout +

    diff --git a/source/_docs/ios/notifications/attachments.markdown b/source/_docs/ios/notifications/attachments.markdown new file mode 100644 index 000000000000..639f087b362c --- /dev/null +++ b/source/_docs/ios/notifications/attachments.markdown @@ -0,0 +1,76 @@ +--- +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 +--- + +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. + +

    +To expand a notification on 3D Touch devices simply force touch any notification. On non-3D Touch devices swipe and tap the "View" button. +

    + +```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 + +

    + + An unexpanded push notification with an attachment. +

    + +

    + + The same notification but expanded to show the full size attachment +

    + +## 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. diff --git a/source/_docs/ios/notifications/basic.markdown b/source/_docs/ios/notifications/basic.markdown new file mode 100644 index 000000000000..fbb217edffe8 --- /dev/null +++ b/source/_docs/ios/notifications/basic.markdown @@ -0,0 +1,58 @@ +--- +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 +--- + +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. + +

    + + A push notification showing all of the basic options `title` and `message` as well as `subtitle` and [actions](/ecosystem/ios/notifications/actions/). +

    + +### {% 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" +``` diff --git a/source/_docs/ios/notifications/content_extensions.markdown b/source/_docs/ios/notifications/content_extensions.markdown new file mode 100644 index 000000000000..9279f75d5959 --- /dev/null +++ b/source/_docs/ios/notifications/content_extensions.markdown @@ -0,0 +1,61 @@ +--- +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 +--- + +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 +``` + +

    + + An example of the map dynamic content. +

    + + +# 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 +``` + +
    + +
    + +# 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. diff --git a/source/_docs/ios/notifications/privacy_security_rate_limits.markdown b/source/_docs/ios/notifications/privacy_security_rate_limits.markdown new file mode 100644 index 000000000000..ebb0b1462674 --- /dev/null +++ b/source/_docs/ios/notifications/privacy_security_rate_limits.markdown @@ -0,0 +1,22 @@ +--- +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 +--- + +## {% 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. diff --git a/source/_docs/ios/notifications/requesting_location_updates.markdown b/source/_docs/ios/notifications/requesting_location_updates.markdown new file mode 100644 index 000000000000..f02f63f30e3f --- /dev/null +++ b/source/_docs/ios/notifications/requesting_location_updates.markdown @@ -0,0 +1,30 @@ +--- +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 +--- + +

    +**Do not rely on this functionality due to the time limits mentioned below.** +

    + +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. + diff --git a/source/_docs/ios/notifications/sounds.markdown b/source/_docs/ios/notifications/sounds.markdown new file mode 100644 index 000000000000..cbe35943ad89 --- /dev/null +++ b/source/_docs/ios/notifications/sounds.markdown @@ -0,0 +1,184 @@ +--- +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 +--- + +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 +``` diff --git a/source/_docs/ios/requirements.markdown b/source/_docs/ios/requirements.markdown new file mode 100644 index 000000000000..89e89e6dcbbf --- /dev/null +++ b/source/_docs/ios/requirements.markdown @@ -0,0 +1,14 @@ +--- +layout: page +title: "Requirements" +description: "Basic requirements to use Home Assistant for iOS" +date: 2016-10-25 15:00:00 -0700 +sidebar: true +comments: false +sharing: true +footer: true +--- + +* 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. diff --git a/source/_docs/nginx.markdown b/source/_docs/nginx.markdown new file mode 100644 index 000000000000..8d657a500311 --- /dev/null +++ b/source/_docs/nginx.markdown @@ -0,0 +1,133 @@ +--- +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 +--- + +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; + } + } +} +``` diff --git a/source/_docs/notebooks.markdown b/source/_docs/notebooks.markdown new file mode 100644 index 000000000000..6dfd9a73633a --- /dev/null +++ b/source/_docs/notebooks.markdown @@ -0,0 +1,20 @@ +--- +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 +--- + +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. + +

    + +

    + +[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. diff --git a/source/_docs/notebooks/api.markdown b/source/_docs/notebooks/api.markdown new file mode 100644 index 000000000000..bf20faaecb37 --- /dev/null +++ b/source/_docs/notebooks/api.markdown @@ -0,0 +1,12 @@ +--- +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 +--- + +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). diff --git a/source/_docs/notebooks/database.markdown b/source/_docs/notebooks/database.markdown new file mode 100644 index 000000000000..5b0cd3cd5569 --- /dev/null +++ b/source/_docs/notebooks/database.markdown @@ -0,0 +1,12 @@ +--- +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 +--- + +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. diff --git a/source/_docs/notebooks/graph.markdown b/source/_docs/notebooks/graph.markdown new file mode 100644 index 000000000000..257d5adf4b94 --- /dev/null +++ b/source/_docs/notebooks/graph.markdown @@ -0,0 +1,12 @@ +--- +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 +--- + +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. diff --git a/source/_docs/notebooks/installation.markdown b/source/_docs/notebooks/installation.markdown new file mode 100644 index 000000000000..ffc67af78d24 --- /dev/null +++ b/source/_docs/notebooks/installation.markdown @@ -0,0 +1,50 @@ +--- +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 +--- + +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 +``` + +

    +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. +

    + +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. + +

    + +

    + +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. + +

    + +

    + +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. + + diff --git a/source/_docs/notebooks/stats.markdown b/source/_docs/notebooks/stats.markdown new file mode 100644 index 000000000000..542d7dbb18c0 --- /dev/null +++ b/source/_docs/notebooks/stats.markdown @@ -0,0 +1,12 @@ +--- +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 +--- + +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. diff --git a/source/_docs/synology.markdown b/source/_docs/synology.markdown new file mode 100644 index 000000000000..93002049f71e --- /dev/null +++ b/source/_docs/synology.markdown @@ -0,0 +1,24 @@ +--- +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 +--- + +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"; +``` diff --git a/source/_docs/tools.markdown b/source/_docs/tools.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. diff --git a/source/_docs/tools/dev-tools.markdown b/source/_docs/tools/dev-tools.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools/dev-tools.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. diff --git a/source/_docs/tools/hass.markdown b/source/_docs/tools/hass.markdown new file mode 100644 index 000000000000..a00c68c5bd66 --- /dev/null +++ b/source/_docs/tools/hass.markdown @@ -0,0 +1,43 @@ +--- +layout: page +title: "Hass" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The command-line part of Home Assistant is + + +```bash +$ hass -h +usage: hass [-h] [--version] [-c path_to_config_dir] [--demo-mode] [--debug] + [--open-ui] [--skip-pip] [-v] [--pid-file path_to_pid_file] + [--log-rotate-days LOG_ROTATE_DAYS] [--runner] [--script ...] + [--daemon] + +Home Assistant: Observe, Control, Automate. + +optional arguments: + -h, --help show this help message and exit + --version show program's version number and exit + -c path_to_config_dir, --config path_to_config_dir + Directory that contains the Home Assistant + configuration + --demo-mode Start Home Assistant in demo mode + --debug Start Home Assistant in debug mode + --open-ui Open the webinterface in a browser + --skip-pip Skips pip install of required packages on startup + -v, --verbose Enable verbose logging to file. + --pid-file path_to_pid_file + Path to PID file useful for running as daemon + --log-rotate-days LOG_ROTATE_DAYS + Enables daily log rotation and keeps up to the + specified days + --runner On restart exit with code 100 + --script ... Run one of the embedded scripts + --daemon Run Home Assistant as daemon +``` diff --git a/source/_docs/tools/scripts.markdown b/source/_docs/tools/scripts.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools/scripts.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. From 52576ec0f564a3a065700da3ba4ccc9e24422c9d Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 17 Feb 2017 08:08:23 +0100 Subject: [PATCH 35/51] Remove duplicate files --- .../_docs/{ => ecosystem}/appdaemon.markdown | 0 .../{ => ecosystem}/appdaemon/api.markdown | 0 .../appdaemon/configuration.markdown | 0 .../appdaemon/example_apps.markdown | 0 .../appdaemon/installation.markdown | 0 .../appdaemon/operation.markdown | 0 .../{ => ecosystem}/appdaemon/reboot.markdown | 0 .../appdaemon/running.markdown | 0 .../appdaemon/tutorial.markdown | 0 .../appdaemon/updating.markdown | 0 .../appdaemon/windows.markdown | 0 .../{ => ecosystem}/hadashboard.markdown | 0 .../hadashboard/dash_config.markdown | 0 .../hadashboard/hapush.markdown | 0 .../hadashboard/installation.markdown | 0 .../hadashboard/reboot.markdown | 0 .../hadashboard/updating.markdown | 0 source/_docs/{ => ecosystem}/nginx.markdown | 0 .../_docs/{ => ecosystem}/scenegen.markdown | 0 .../_docs/{ => ecosystem}/synology.markdown | 0 source/appdaemon.markdown | 14 - source/appdaemon/api.markdown | 2108 ----------------- source/appdaemon/configuration.markdown | 79 - source/appdaemon/example_apps.markdown | 13 - source/appdaemon/installation.markdown | 45 - source/appdaemon/operation.markdown | 13 - source/appdaemon/reboot.markdown | 13 - source/appdaemon/running.markdown | 95 - source/appdaemon/tutorial.markdown | 128 - source/appdaemon/updating.markdown | 26 - source/appdaemon/windows.markdown | 22 - source/hadashboard.markdown | 20 - source/hadashboard/dash_config.markdown | 274 --- source/hadashboard/hapush.markdown | 94 - source/hadashboard/installation.markdown | 151 -- source/hadashboard/reboot.markdown | 16 - source/hadashboard/updating.markdown | 24 - source/ios.markdown | 66 - source/ios/devices_file.markdown | 12 - source/ios/features.markdown | 12 - source/ios/integration.markdown | 25 - source/ios/location.markdown | 36 - source/ios/notifications.markdown | 14 - source/ios/notifications/actions.markdown | 142 -- .../ios/notifications/architecture.markdown | 15 - source/ios/notifications/attachments.markdown | 76 - source/ios/notifications/basic.markdown | 58 - .../notifications/content_extensions.markdown | 61 - .../privacy_security_rate_limits.markdown | 22 - .../requesting_location_updates.markdown | 30 - source/ios/notifications/sounds.markdown | 184 -- source/ios/requirements.markdown | 14 - source/nginx.markdown | 133 -- source/notebooks.markdown | 20 - source/notebooks/api.markdown | 12 - source/notebooks/database.markdown | 12 - source/notebooks/graph.markdown | 12 - source/notebooks/installation.markdown | 50 - source/notebooks/stats.markdown | 12 - source/scenegen.markdown | 182 -- source/synology.markdown | 24 - 61 files changed, 4359 deletions(-) rename source/_docs/{ => ecosystem}/appdaemon.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/api.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/configuration.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/example_apps.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/installation.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/operation.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/reboot.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/running.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/tutorial.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/updating.markdown (100%) rename source/_docs/{ => ecosystem}/appdaemon/windows.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard/dash_config.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard/hapush.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard/installation.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard/reboot.markdown (100%) rename source/_docs/{ => ecosystem}/hadashboard/updating.markdown (100%) rename source/_docs/{ => ecosystem}/nginx.markdown (100%) rename source/_docs/{ => ecosystem}/scenegen.markdown (100%) rename source/_docs/{ => ecosystem}/synology.markdown (100%) delete mode 100755 source/appdaemon.markdown delete mode 100755 source/appdaemon/api.markdown delete mode 100644 source/appdaemon/configuration.markdown delete mode 100644 source/appdaemon/example_apps.markdown delete mode 100644 source/appdaemon/installation.markdown delete mode 100644 source/appdaemon/operation.markdown delete mode 100644 source/appdaemon/reboot.markdown delete mode 100755 source/appdaemon/running.markdown delete mode 100755 source/appdaemon/tutorial.markdown delete mode 100644 source/appdaemon/updating.markdown delete mode 100755 source/appdaemon/windows.markdown delete mode 100644 source/hadashboard.markdown delete mode 100755 source/hadashboard/dash_config.markdown delete mode 100755 source/hadashboard/hapush.markdown delete mode 100755 source/hadashboard/installation.markdown delete mode 100755 source/hadashboard/reboot.markdown delete mode 100755 source/hadashboard/updating.markdown delete mode 100644 source/ios.markdown delete mode 100644 source/ios/devices_file.markdown delete mode 100644 source/ios/features.markdown delete mode 100644 source/ios/integration.markdown delete mode 100644 source/ios/location.markdown delete mode 100644 source/ios/notifications.markdown delete mode 100644 source/ios/notifications/actions.markdown delete mode 100644 source/ios/notifications/architecture.markdown delete mode 100644 source/ios/notifications/attachments.markdown delete mode 100644 source/ios/notifications/basic.markdown delete mode 100644 source/ios/notifications/content_extensions.markdown delete mode 100644 source/ios/notifications/privacy_security_rate_limits.markdown delete mode 100644 source/ios/notifications/requesting_location_updates.markdown delete mode 100644 source/ios/notifications/sounds.markdown delete mode 100644 source/ios/requirements.markdown delete mode 100644 source/nginx.markdown delete mode 100644 source/notebooks.markdown delete mode 100644 source/notebooks/api.markdown delete mode 100644 source/notebooks/database.markdown delete mode 100644 source/notebooks/graph.markdown delete mode 100644 source/notebooks/installation.markdown delete mode 100644 source/notebooks/stats.markdown delete mode 100644 source/scenegen.markdown delete mode 100644 source/synology.markdown diff --git a/source/_docs/appdaemon.markdown b/source/_docs/ecosystem/appdaemon.markdown similarity index 100% rename from source/_docs/appdaemon.markdown rename to source/_docs/ecosystem/appdaemon.markdown diff --git a/source/_docs/appdaemon/api.markdown b/source/_docs/ecosystem/appdaemon/api.markdown similarity index 100% rename from source/_docs/appdaemon/api.markdown rename to source/_docs/ecosystem/appdaemon/api.markdown diff --git a/source/_docs/appdaemon/configuration.markdown b/source/_docs/ecosystem/appdaemon/configuration.markdown similarity index 100% rename from source/_docs/appdaemon/configuration.markdown rename to source/_docs/ecosystem/appdaemon/configuration.markdown diff --git a/source/_docs/appdaemon/example_apps.markdown b/source/_docs/ecosystem/appdaemon/example_apps.markdown similarity index 100% rename from source/_docs/appdaemon/example_apps.markdown rename to source/_docs/ecosystem/appdaemon/example_apps.markdown diff --git a/source/_docs/appdaemon/installation.markdown b/source/_docs/ecosystem/appdaemon/installation.markdown similarity index 100% rename from source/_docs/appdaemon/installation.markdown rename to source/_docs/ecosystem/appdaemon/installation.markdown diff --git a/source/_docs/appdaemon/operation.markdown b/source/_docs/ecosystem/appdaemon/operation.markdown similarity index 100% rename from source/_docs/appdaemon/operation.markdown rename to source/_docs/ecosystem/appdaemon/operation.markdown diff --git a/source/_docs/appdaemon/reboot.markdown b/source/_docs/ecosystem/appdaemon/reboot.markdown similarity index 100% rename from source/_docs/appdaemon/reboot.markdown rename to source/_docs/ecosystem/appdaemon/reboot.markdown diff --git a/source/_docs/appdaemon/running.markdown b/source/_docs/ecosystem/appdaemon/running.markdown similarity index 100% rename from source/_docs/appdaemon/running.markdown rename to source/_docs/ecosystem/appdaemon/running.markdown diff --git a/source/_docs/appdaemon/tutorial.markdown b/source/_docs/ecosystem/appdaemon/tutorial.markdown similarity index 100% rename from source/_docs/appdaemon/tutorial.markdown rename to source/_docs/ecosystem/appdaemon/tutorial.markdown diff --git a/source/_docs/appdaemon/updating.markdown b/source/_docs/ecosystem/appdaemon/updating.markdown similarity index 100% rename from source/_docs/appdaemon/updating.markdown rename to source/_docs/ecosystem/appdaemon/updating.markdown diff --git a/source/_docs/appdaemon/windows.markdown b/source/_docs/ecosystem/appdaemon/windows.markdown similarity index 100% rename from source/_docs/appdaemon/windows.markdown rename to source/_docs/ecosystem/appdaemon/windows.markdown diff --git a/source/_docs/hadashboard.markdown b/source/_docs/ecosystem/hadashboard.markdown similarity index 100% rename from source/_docs/hadashboard.markdown rename to source/_docs/ecosystem/hadashboard.markdown diff --git a/source/_docs/hadashboard/dash_config.markdown b/source/_docs/ecosystem/hadashboard/dash_config.markdown similarity index 100% rename from source/_docs/hadashboard/dash_config.markdown rename to source/_docs/ecosystem/hadashboard/dash_config.markdown diff --git a/source/_docs/hadashboard/hapush.markdown b/source/_docs/ecosystem/hadashboard/hapush.markdown similarity index 100% rename from source/_docs/hadashboard/hapush.markdown rename to source/_docs/ecosystem/hadashboard/hapush.markdown diff --git a/source/_docs/hadashboard/installation.markdown b/source/_docs/ecosystem/hadashboard/installation.markdown similarity index 100% rename from source/_docs/hadashboard/installation.markdown rename to source/_docs/ecosystem/hadashboard/installation.markdown diff --git a/source/_docs/hadashboard/reboot.markdown b/source/_docs/ecosystem/hadashboard/reboot.markdown similarity index 100% rename from source/_docs/hadashboard/reboot.markdown rename to source/_docs/ecosystem/hadashboard/reboot.markdown diff --git a/source/_docs/hadashboard/updating.markdown b/source/_docs/ecosystem/hadashboard/updating.markdown similarity index 100% rename from source/_docs/hadashboard/updating.markdown rename to source/_docs/ecosystem/hadashboard/updating.markdown diff --git a/source/_docs/nginx.markdown b/source/_docs/ecosystem/nginx.markdown similarity index 100% rename from source/_docs/nginx.markdown rename to source/_docs/ecosystem/nginx.markdown diff --git a/source/_docs/scenegen.markdown b/source/_docs/ecosystem/scenegen.markdown similarity index 100% rename from source/_docs/scenegen.markdown rename to source/_docs/ecosystem/scenegen.markdown diff --git a/source/_docs/synology.markdown b/source/_docs/ecosystem/synology.markdown similarity index 100% rename from source/_docs/synology.markdown rename to source/_docs/ecosystem/synology.markdown diff --git a/source/appdaemon.markdown b/source/appdaemon.markdown deleted file mode 100755 index 9ec0e87f8e3f..000000000000 --- a/source/appdaemon.markdown +++ /dev/null @@ -1,14 +0,0 @@ ---- -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. \ No newline at end of file diff --git a/source/appdaemon/api.markdown b/source/appdaemon/api.markdown deleted file mode 100755 index 891ef1dec870..000000000000 --- a/source/appdaemon/api.markdown +++ /dev/null @@ -1,2108 +0,0 @@ ---- -layout: page -title: "AppDaemon API Reference" -description: "AppDaemon API Reference" -release_date: 2016-11-27 08:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: true -hide_github_edit: true ---- - -## {% linkable_title Anatomy of an App %} - -Automations in AppDaemon are performed by creating a piece of code (essentially a Python Class) and then instantiating it as an Object one or more times by configuring it as an App in the configuration file. The App is given a chance to register itself for whatever events it wants to subscribe to, and AppDaemon will then make calls back into the Object's code when those events occur, allowing the App to respond to the event with some kind of action. - -The first step is to create a unique file within the apps directory (as defined in the `[AppDaemon]` section of configuration file). This file is in fact a Python module, and is expected to contain one or more classes derived from the supplied `AppDaemon` class, imported from the supplied `homeassistant.appapi` module. The start of an app might look like this: - -```python -import homeassistant.appapi as appapi - -class MotionLights(appapi.AppDaemon): -``` - -When configured as an app in the config file (more on that later) the lifecycle of the App begins. It will be instantiated as an object by AppDaemon, and immediately, it will have a call made to it's `initialize()` function - this function must appear as part of every app: - -```python - def initialize(self): -``` - -The initialize function allows the app to register any callbacks it might need for responding to state changes, and also any setup activities. When the `initialize()` function returns, the App will be dormant until any of it's callbacks are activated. - -There are several circumstances under which `initialize()` might be called: - -- Initial start of AppDaemon -- Following a change to the Class code -- Following a change to the module parameters -- Following initial configuration of an app -- Following a change in the status of Daylight Savings Time -- Following a restart of Home Assistant - -In every case, the App is responsible for recreating any state it might need as if it were the first time it was ever started. If `initialize()` is called, the app can safely assume that it is either being loaded for the first time, or that all callbacks and timers have been cancelled. In either case, the APP will need to recreate them. Depending upon the application it may be desirable for the App to establish state such as whether or not a particular light is on, within the `initialize()` function to ensure that everything is as expected or to make immediate remedial action (e.g. turn off a light that might have been left on by mistake when the app was restarted). - -After the `initialize()` function is in place, the rest of the app consists of functions that are called by the various callback mechanisms, and any additional functions the user wants to add as part of the program logic. Apps are able to subscribe to 2 main classes of events: - -- Scheduled Events -- State Change Events - -These, along with their various subscription calls and helper functions, will be described in detail in later sections. - -To wrap up this section, here is a complete functioning App (with comments): - -```python -import homeassistant.appapi as appapi -import datetime - -# Declare Class -class NightLight(appapi.AppDaemon): - #initialize() function which will be called at startup and reload - def initialize(self): - # Create a time object for 7pm - time = datetime.time(19, 00, 0) - # Schedule a daily callback that will call run_daily() at 7pm every night - self.run_daily(self.run_daily_callback, time) - - # Our callback function will be called by the scheduler every day at 7pm - def run_daily_callback(self, kwargs): - # Call to Home Assistant to turn the porch light on - self.turn_on("light.porch") -``` - -To summarize - an App's lifecycle consists of being initialized, which allows it to set one or more state and/or schedule callbacks. When those callbacks are activated, the App will typically use one of the Service Calling calls to effect some change to the devices of the system and then wait for the next relevant state change. That's all there is to it! - -## {% linkable_title About the API %} - -The implementation of the API is located in the AppDaemon class that Apps are derived from. The code for the functions is therefore available to the App simply by invoking the name of the function from the object namespace using the `self` keyword, as in the above examples. `self.turn_on()` for example is just a method defined in the parent class and made available to the child. This design decision was made to simplify some of the implementation and hide passing of unnecessary variables during the API invocation. - -## {% linkable_title Configuration of Apps %} -Apps are configured by specifying new sections in the configuration file. `[AppDaemon]` is a reserved section, for configuration of AppDaemon itself. The name of the section is the name the App is referred to within the system in log files etc. and must be unique. - -To configure a new App you need a minimum of two directives: - -- `module` - the name of the module (without the `.py`) that contains the class to be used for this App -- `class` - the name of the class as defined within the module for the APPs code - -Although the section/App name must be unique, it is possible to re-use a class as many times as you want, and conversely to put as many classes in a module as you want. A sample definition for a new App might look as follows: - -```ini -[newapp] -module = new -class = NewApp -``` - -When AppDaemon sees the following configuration it will expect to find a class called `NewApp` defined in a module called `new.py` in the apps subdirectory. Apps can be placed at the root of the Apps directory or within a subdirectory, an arbitrary depth down - wherever the App is, as long as it is in some subdirectory of the Apps dir, or in the Apps dir itself, AppDaemon will find it. There is no need to include information about the path, just the name of the file itself (without the `.py`) is sufficient. If names in the subdirectories overlap, AppDir will pick one of them but the exact choice it will make is undefined. - -When starting the system for the first time or when reloading an App or Module, the system will log the fact in it's main log. It is often the case that there is a problem with the class, maybe a syntax error or some other problem. If that is the case, details will be output to the error log allowing the user to remedy the problem and reload. - -## {% linkable_title Steps to writing an App %} - -1. Create the code in a new or shared module by deriving a class from AppDaemon, add required callbacks and code -2. Add the App to the configuration file -3. There is no number 3 - -## {% linkable_title Reloading Modules and Classes %} - -Reloading of modules is automatic. When the system spots a change in a module, it will automatically reload and recompile the module. It will also figure out which Apps were using that Module and restart them, causing all of their existing callbacks to be cleared, and their `initialize()` function to be called. - -The same is true if changes are made to an App's configuration - changing the class, or arguments (see later) will cause that app to be reloaded in the same way. The system is also capable of detecting if a new app has been added, or if one has been removed, and it will act appropriately, starting the new app immediately and removing all callbacks for the removed app. - -The suggested order for creating a new App is to add the module code first and work until it compiles cleanly, and only then add an entry in the configuration file to actually run it. A good workflow is to continuously monitor the error file (using `tail -f` on Linux for instance) to ensure that errors are seen and can be remedied. - -## {% linkable_title Passing Arguments to Apps %} - -There wouldn't be much point in being able to run multiple versions of an App if there wasn't some way to instruct them to do something different. For this reason it is possible to pass any required arguments to an App, which are then made available to the object at runtime. The arguments themselves can be called anything (apart from `module` or `class`) and are simply added into the section after the 2 mandatory directives like so: - -```ini -[MyApp] -module = myapp -class = MyApp -param1 = spam -param2 = eggs -``` - -Within the Apps code, the 2 parameters (as well as the module and class) are available as a dictionary called `args`, and accessed as follows: - -```python -param1 = self.args["param1"] -param2 = self.args["param2"] -``` - -A use case for this might be an App that detects motion and turns on a light. If you have 3 places you want to run this, rather than hardcoding this into 3 separate Apps, you need only code a single app and instantiate it 3 times with different arguments. It might look something like this: - -```ini -[downstairs_motion_light] -module = motion_light -class = MotionLight -sensor = binary_sensor.downstairs_hall -light = light.downstairs_hall -[upstairs_motion_light] -module = motion_light -class = MotionLight -sensor = binary_sensor.upstairs_hall -light = light.upstairs_hall -[garage_motion_light] -module = motion_light -class = MotionLight -sensor = binary_sensor.garage -light = light.garage -``` - -## {% linkable_title Callback Constraints %} - -Callback constraints are a feature of AppDaemon that removes the need for repetition of some common coding checks. Many Apps will wish to process their callbacks only when certain conditions are met, e.g. someone is home, and it's after sunset. These kinds of conditions crop up a lot, and use of callback constraints can significantly simplify the logic required within callbacks. - -Put simply, callback constraints are one or more conditions on callback execution that can be applied to an individual App. An App's callbacks will only be executed if all of the constraints are met. If a constraint is absent it will not be checked for. - -For example, the presence callback constraint can be added to an App by adding a parameter to it's configuration like this: - -```ini -[some_app] -module = some_module -class = SomeClass -constrain_presence = noone -``` - -Now, although the `initialize()` function will be called for MyClass, and it will have a chance to register as many callbacks as it desires, none of the callbacks will execute, in this case, until everyone has left. This could be useful for an interior motion detector App for instance. There are several different types of constraints: - -- input_boolean -- input_select -- presence -- time - -An App can have as many or as few as are required. When more than one constraint is present, they must all evaluate to true to allow the callbacks to be called. Constraints becoming true are not an event in their own right, but if they are all true at a point in time, the next callback that would otherwise been blocked due to constraint failure will now be called. Similarly, if one of the constraints becomes false, the next callback that would otherwise have been called will be blocked. - -They are described individually below. - -### {% linkable_title input_boolean %} -By default, the input_boolean constraint prevents callbacks unless the specified input_boolean is set to "on". This is useful to allow certain Apps to be turned on and off from the user interface. For example: - -```ini -[some_app] -module = some_module -class = SomeClass -constrain_input_boolean = input_boolean.enable_motion_detection -``` - -If you want to reverse the logic so the constraint is only called when the input_boolean is off, use the optional state parameter by appending ",off" to the argument, e.g.: - -```ini -[some_app] -module = some_module -class = SomeClass -constrain_input_boolean = input_boolean.enable_motion_detection,off -``` - -### {% linkable_title input_select %} -The input_select constraint prevents callbacks unless the specified input_select is set to one or more of the nominated (comma separated) values. This is useful to allow certain Apps to be turned on and off according to some flag, e.g. a house mode flag. - -```ini -# Single value -constrain_input_select = input_select.house_mode,Day -# or multiple values -constrain_input_select = input_select.house_mode,Day,Evening,Night -``` - -### {% linkable_title presence %} -The presence constraint will constrain based on presence of device trackers. It takes 3 possible values: -- `noone` - only allow callback execution when no one is home -- `anyone` - only allow callback execution when one or more person is home -- `everyone` - only allow callback execution when everyone is home - -```ini -constrain_presence = anyone -# or -constrain_presence = someone -# or -constrain_presence = noone -``` - -### {% linkable_title time %} -The time constraint consists of 2 variables, `constrain_start_time` and `constrain_end_time`. Callbacks will only be executed if the current time is between the start and end times. -- If both are absent no time constraint will exist -- If only start is present, end will default to 1 second before midnight -- If only end is present, start will default to midnight - -The times are specified in a string format with one of the following formats: -- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. -- `sunrise`|`sunset` [+|- HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds - -The time based constraint system correctly interprets start and end times that span midnight. - -```ini -# Run between 8am and 10pm -constrain_start_time = 08:00:00 -constrain_end_time = 22:00:00 -# Run between sunrise and sunset -constrain_start_time = sunrise -constrain_end_time = sunset -# Run between 45 minutes before sunset and 45 minutes after sunrise the next day -constrain_start_time = sunset - 00:45:00 -constrain_end_time = sunrise + 00:45:00 -``` - -### {% linkable_title days %} -The day constraint consists of as list of days for which the callbacks will fire, e.g. - -```ini -constrain_days = mon,tue,wed -``` - -Callback constraints can also be applied to individual callbacks within Apps, see later for more details. - -## {% linkable_title A Note on Threading %} - -AppDaemon is multithreaded. This means that any time code within an App is executed, it is executed by one of many threads. This is generally not a particularly important consideration for this application; in general, the execution time of callbacks is expected to be far quicker than the frequency of events causing them. However, it should be noted for completeness, that it is certainly possible for different pieces of code within the App to be executed concurrently, so some care may be necessary if different callback for instance inspect and change shared variables. This is a fairly standard caveat with concurrent programming, and if you know enough to want to do this, then you should know enough to put appropriate safeguards in place. For the average user however this shouldn't be an issue. If there are sufficient use cases to warrant it, I will consider adding locking to the function invocations to make the entire infrastructure threadsafe, but I am not convinced that it is necessary. - -An additional caveat of a threaded worker pool environment is that it is the expectation that none of the callbacks tie threads up for a significant amount of time. To do so would eventually lead to thread exhaustion, which would make the system run behind events. No events would be lost as they would be queued, but callbacks would be delayed which is a bad thing. - -Given the above, NEVER use Python's `time.sleep()` if you want to perform an operation some time in the future, as this will tie up a thread for the period of the sleep. Instead use the scheduler's `run_in()` function which will allow you to delay without blocking any threads. - -## {% linkable_title State Operations %} - -### {% linkable_title A note on Home Assistant State %} - -State within Home Assistant is stored as a collection of dictionaries, one for each entity. Each entity's dictionary will have some common fields and a number of entity type specific fields The state for an entity will always have the attributes: - -- `last_updated` -- `last_changed` -- `state` - -Any other attributes such as brightness for a lamp will only be present if the entity supports them, and will be stored in a sub-dictionary called `attributes`. When specifying these optional attributes in the `get_state()` call, no special distinction is required between the main attributes and the optional ones - `get_state()` will figure it out for you. - -Also bear in mind that some attributes such as brightness for a light, will not be present when the light is off. - -In most cases, the attribute `state` has the most important value in it, e.g. for a light or switch this will be `on` or `off`, for a sensor it will be the value of that sensor. Many of the AppDaemon API calls and callbacks will implicitly return the value of state unless told to do otherwise. - -### {% linkable_title get_state() %} - -#### {% linkable_title Synopsis %} - -```python -get_state(entity = None, attribute = None) -``` - -`get_state()` is used to query the state of any component within Home Assistant. State updates are continuously tracked so this call runs locally and does not require AppDaemon to call back to Home Assistant and as such is very efficient. - -#### {% linkable_title Returns %} - -`get_state()` returns a `dictionary` or single value, the structure of which varies according to the parameters used. - -#### {% linkable_title Parameters %} - -All parameters are optional, and if `get_state()` is called with no parameters it will return the entire state of Home Assistant at that given time. This will consist of a dictionary with a key for each entity. Under that key will be the standard entity state information. - -##### {% linkable_title entity %} - -This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `get_state()` will return a dictionary of all devices of that type, indexed by the entity_id, containing all the state for each entity. - -If a fully qualified `entity_id` is provided, `get_state()` will return the state attribute for that entity, e.g. `on` or `off` for a light. - -##### {% linkable_title attribute %} - -Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified `entity_id`, a single value representing the attribute will be returned, or `None` if it is not present. - -The value `all` for attribute has special significance and will return the entire state dictionary for the specified entity rather than an individual attribute value. - -#### {% linkable_title Examples %} - -```python -# Return state for the entire system -state = self.get_state() - -# Return state for all switches in the system -state = self.get_state("switch") - -# Return the state attribute for light.office_1 -state = self.get_state("light.office_1") - -# Return the brightness attribute for light.office_1 -state = self.get_state("light.office_1", "brightness") - -# Return the entire state for light.office_1 -state = self.get_state("light.office_1", "all") -``` - -### {% linkable_title set_state() %} - -`set_state()` will make a call back to Home Assistant and make changes to the internal state of Home Assistant. This is not something that you would usually want to do and the applications are limited however the call is included for completeness. Note that for instance, setting the state of a light to `on` won't actually switch the device on, it will merely change the state of the device in Home Assistant so that it no longer reflects reality. In most cases, the state will be corrected the next time Home Assistant polls the device or someone causes a state change manually. To effect actual changes of devices use one of the service call functions. - -One possible use case for `set_state()` is for testing. If for instance you are writing an App to turn on a light when it gets dark according to a luminance sensor, you can use `set_state()` to temporarily change the light level reported by the sensor to test your program. However this is also possible using the developer tools. - -At the time of writing, it appears that no checking is done as to whether or not the entity exists, so it is possible to add entirely new entries to Home Assistant's state with this call. - -#### {% linkable_title Synopsis %} - -```python -set_state(entity_id, **kwargs) -``` - -#### {% linkable_title Returns %} - -`set_state()` returns a dictionary representing the state of the device after the call has completed. - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Entity id for which the state is to be set, e.g. `light.office_1`. - -##### {% linkable_title values %} - -A list of keyword values to be changed or added to the entities state. e.g. `state = "off"`. Note that any optional attributes such as colors for bulbs etc, need to reside in a dictionary called `attributes`; see the example. - -#### {% linkable_title Examples %} - -```python -status = self.set_state("light.office_1", state = "on", attributes = {"color_name": "red"}) -``` - -### {% linkable_title About Callbacks %} - -A large proportion of home automation revolves around waiting for something to happen and then reacting to it; a light level drops, the sun rises, a door opens etc. Home Assistant keeps track of every state change that occurs within the system and streams that information to AppDaemon almost immediately. - -An individual App however usually doesn't care about the majority of state changes going on in the system; Apps usually care about something very specific, like a specific sensor or light. Apps need a way to be notified when a state change happens that they care about, and be able to ignore the rest. They do this through registering callbacks. A callback allows the App to describe exactly what it is interested in, and tells AppDaemon to make a call into its code in a specific place to be able to react to it - this is a very familiar concept to anyone familiar with event-based programming. - -There are 3 types of callbacks within AppDaemon: - -- State Callbacks - react to a change in state -- Scheduler Callbacks - react to a specific time or interval -- Event Callbacks - react to specific Home Assistant and Appdaemon events. - -All callbacks allow the user to specify additional parameters to be handed to the callback via the standard Python `**kwargs` mechanism for greater flexibility. - -### {% linkable_title About Registering Callbacks %} - -Each of the various types of callback have their own function or functions for registering the callback: - -- `listen_state()` for state callbacks -- Various scheduler calls such as `run_once()` for scheduler callbacks -- `listen_event()` for event callbacks. - -Each type of callback shares a number of common mechanisms that increase flexibility. - -#### {% linkable_title Callback Level Constraints %} - -When registering a callback, you can add constraints identical to the Application level constraints described earlier. The difference is that a constraint applied to an individual callback only affects that callback and no other. The constraints are applied by adding Python keyword-value style arguments after the positional arguments. The parameters themselves are named identically to the previously described constraints and have identical functionality. For instance, adding: - -`constrain_presence="everyone"` - -to a callback registration will ensure that the callback is only run if the callback conditions are met and in addition everyone is present although any other callbacks might run whenever their event fires if they have no constraints. - -For example: - -`self.listen_state(self.motion, "binary_sensor.drive", constrain_presence="everyone")` - -#### {% linkable_title User Arguments %} - -Any callback has the ability to allow the App creator to pass through arbitrary keyword arguments that will be presented to the callback when it is run. The arguments are added after the positional parameters just like the constraints. The only restriction is that they cannot be the same as any constraint name for obvious reasons. For example, to pass the parameter `arg1 = "home assistant"` through to a callback you would register a callback as follows: - -`self.listen_state(self.motion, "binary_sensor.drive", arg1="home assistant")` - -Then in the callback you could use it as follows: - -```python -def motion(self, entity, attribute, old, new, **kwargs): - self.log("Arg1 is {}".format(kwargs["arg1"])) -``` - -### {% linkable_title State Callbacks %} - -AppDaemons's state callbacks allow an App to listen to a wide variety of events, from every state change in the system, right down to a change of a single attribute of a particular entity. Setting up a callback is done using a single API call `listen_state()` which takes various arguments to allow it to do all of the above. Apps can register as many or as few callbacks as they want. - -### {% linkable_title About State Callback Functions %} - -When calling back into the App, the App must provide a class function with a known signature for AppDaemon to call. The callback will provide various information to the function to enable the function to respond appropriately. For state callbacks, a class defined callback function should look like this: - -```python - def my_callback(self, entity, attribute, old, new, **kwargs): - -``` - -You can call the function whatever you like - you will reference it in the `listen_state()` call, and you can create as many callback functions as you need. - -The parameters have the following meanings: - -#### {% linkable_title self %} - -A standard Python object reference. - -#### {% linkable_title entity %} - -Name of the entity the callback was requested for or `None`. - -#### {% linkable_title attribute %} - -Name of the attribute the callback was requested for or `None`. - -#### {% linkable_title old %} - -The value of the state before the state change. - -#### {% linkable_title new %} - -The value of the state after the state change. - -`old` and `new` will have varying types depending on the type of callback. - -#### {% linkable_title \*\*kwargs %} - -A dictionary containing any constraints and/or additional user specific keyword arguments supplied to the `listen_state()` call. - -### {% linkable_title listen_state() %} - -`listen_state()` allows the user to register a callback for a wide variety of state changes. - -#### {% linkable_title Synopsis %} - -```python -handle = listen_state(callback, entity = None, **kwargs) -``` - -#### {% linkable_title Returns %} - -A unique identifier that can be used to cancel the callback if required. Since variables created within object methods are local to the function they are created in, and in all likelihood the cancellation will be invoked later in a different function, it is recommended that handles are stored in the object namespace, e.g. `self.handle`. - -#### {% linkable_title Parameters %} - -All parameters except `callback` are optional, and if `listen_state()` is called with no additional parameters it will subscribe to any state change within Home Assistant. - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard State Callback format documented above. - -##### {% linkable_title entity %} - -This is the name of an entity or device type. If just a device type is provided, e.g. `light` or `binary_sensor`, `listen_state()` will subscribe to state changes of all devices of that type. If a fully qualified `entity_id` is provided, `listen_state()` will listen for state changes for just that entity. - -When called, AppDaemon will supply the callback function, in old and new, with the state attribute for that entity, e.g. `on` or `off` for a light. - -##### {% linkable_title attribute (optional) %} - -Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified `entity_id`, `listen_state()` will subscribe to changes for just that attribute within that specific entity. The new and old parameters in the callback function will be provided with a single value representing the attribute. - -The value `all` for attribute has special significance and will listen for any state change within the specified entity, and supply the callback functions with the entire state dictionary for the specified entity rather than an individual attribute value. - -##### {% linkable_title new = (optional) %} - -If `new` is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually `state`) in the new state match the value of `new`. - -##### {% linkable_title old = (optional) %} - -If `old` is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually `state`) in the old state match the value of `old`. - -Note: `old` and `new` can be used singly or together. - -##### {% linkable_title duration = (optional) %} - -If duration is supplied as a parameter, the callback will not fire unless the state listened for is maintained for that number of seconds. This makes the most sense if a specific attribute is specified (or the default os `state` is used), an in conjunction with the `old` or `new` parameters, or both. When the callback is called, it is supplied with the values of `entity`, `attr`, `old` and `new` that were current at the time the actual event occured, since the assumption is that none of them have changed in the intervening period. - -```python - def my_callback(self, **kwargs): - -``` - -(Scheduler callbacks are documented in detail laer in this document) - -##### {% linkable_title \*\*kwargs %} - -Zero or more keyword arguments that will be supplied to the callback when it is called. - -#### {% linkable_title Examples %} - -```python -# Listen for any state change and return the state attribute -self.handle = self.listen_state(self.my_callback) - -# Listen for any state change involving a light and return the state attribute -self.handle = self.listen_state(self.my_callback, "light") - -# Listen for a state change involving light.office1 and return the state attribute -self.handle = self.listen_state(self.my_callback, "light.office_1") - -# Listen for a state change involving light.office1 and return the entire state as a dict -self.handle = self.listen_state(self.my_callback, "light.office_1", attribute = "all") - -# Listen for a state change involving the brightness attribute of light.office1 -self.handle = self.listen_state(self.my_callback, "light.office_1", attribute = "brightness") - -# Listen for a state change involving light.office1 turning on and return the state attribute -self.handle = self.listen_state(self.my_callback, "light.office_1", new = "on") - -# Listen for a state change involving light.office1 changing from brightness 100 to 200 and return the state attribute -self.handle = self.listen_state(self.my_callback, "light.office_1", old = "100", new = "200") - -# Listen for a state change involving light.office1 changing to state on and remaining on for a minute -self.handle = self.listen_state(self.my_callback, "light.office_1", new = "on", duration = 60) - -``` - -### {% linkable_title cancel_listen_state() %} - -Cancel a `listen_state()` callback. This will mean that the App will no longer be notified for the specific state change that has been cancelled. Other state changes will continue to be monitored. - -#### {% linkable_title Synopsis %} - -```python -cancel_listen_state(handle) -``` - -#### {% linkable_title Returns %} - -Nothing - -#### {% linkable_title Parameters %} - -##### {% linkable_title handle %} - -The handle returned when the `listen_state()` call was made. - -#### {% linkable_title Examples %} - -```python -self.cancel_listen_state(self.office_light_handle) -``` - -### {% linkable_title info_listen_state() %} - -Get information on state a callback from it's handle. - -#### {% linkable_title Synopsis %} - -```python -entity, attribute, kwargs = self.info_listen_state(self.handle) -``` - -#### {% linkable_title Returns %} - -entity, attribute, kwargs - the values supplied when the callback was initially created. - -#### {% linkable_title Parameters %} - -##### {% linkable_title handle %} - -The handle returned when the `listen_state()` call was made. - -#### {% linkable_title Examples %} - -```python -entity, attribute, kwargs = self.info_listen_state(self.handle) -``` - -## {% linkable_title Scheduler %} - -AppDaemon contains a powerful scheduler that is able to run with 1 second resolution to fire off specific events at set times, or after set delays, or even relative to sunrise and sunset. In general, events should be fired less than a second after specified but under certain circumstances there may be short additional delays. - -### {% linkable_title About Schedule Callbacks %} - -As with State Change callbacks, Scheduler Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this: - -```python - def my_callback(self, **kwargs): - -``` - -You can call the function whatever you like; you will reference it in the Scheduler call, and you can create as many callback functions as you need. - -The parameters have the following meanings: - -#### {% linkable_title self %} -A standard Python object reference - -#### {% linkable_title \*\*kwargs %} - -A dictionary containing Zero or more keyword arguments to be supplied to the callback. - -### {% linkable_title Creation of Scheduler Callbacks %} - -Scheduler callbacks are created through use of a number of convenience functions which can be used to suit the situation. - -#### {% linkable_title run_in() %} - -Run the callback in a defined number of seconds. This is used to add a delay, for instance a 60 second delay before a light is turned off after it has been triggered by a motion detector. This callback should always be used instead of `time.sleep()` as discussed previously. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_in(callback, delay, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### vcallback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title delay %} - -Delay, in seconds before the callback is invoked. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -self.handle = self.run_in(self.run_in_c) -self.handle = self.run_in(self.run_in_c, title = "run_in5") -``` -#### {% linkable_title run_once() %} - -Run the callback once, at the specified time of day. If the time of day is in the past, the callback will occur on the next day. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_once(callback, time, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title time %} - -A Python `time` object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run at 4pm today, or 4pm tomorrow if it is already after 4pm -import datetime -... -runtime = datetime.time(16, 0, 0) -handle = self.run_once(self.run_once_c, runtime) -``` - -#### {% linkable_title run_at() %} - -Run the callback once, at the specified date and time. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_at(callback, datetime, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. `run_at()` will raise an exception if the specified time is in the past. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title datetime %} - -A Python `datetime` object that specifies when the callback will occur. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run at 4pm today -import datetime -... -runtime = datetime.time(16, 0, 0) -today = datetime.date.today() -event = datetime.datetime.combine(today, runtime) -handle = self.run_once(self.run_once_c, event) -``` -#### {% linkable_title run_daily() %} - -Execute a callback at the same time every day. If the time has already passed, the function will not be invoked until the following day at the specified time. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_daily(callback, time, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title time %} - -A Python `time` object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run daily at 7pm -import datetime -... -time = datetime.time(19, 0, 0) -self.run_daily(self.run_daily_c, runtime) -``` - -#### {% linkable_title run_hourly() %} - -Execute a callback at the same time every hour. If the time has already passed, the function will not be invoked until the following hour at the specified time. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_hourly(callback, time = None, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title time %} - -A Python `time` object that specifies when the callback will occur, the hour component of the time object is ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start an hour from the time that `run_hourly()` was executed. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run every hour, on the hour -import datetime -... -time = datetime.time(0, 0, 0) -self.run_daily(self.run_daily_c, runtime) -``` -#### {% linkable_title run_minutely() %} - -Execute a callback at the same time every minute. If the time has already passed, the function will not be invoked until the following minute at the specified time. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_minutely(callback, time = None, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title time %} - -A Python `time` object that specifies when the callback will occur, the hour and minute components of the time object are ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start a minute from the time that `run_minutely()` was executed. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run Every Minute on the minute -import datetime -... -time = datetime.time(0, 0, 0) -self.run_minutely(self.run_minutely_c, time) -``` - -#### {% linkable_title run_every() %} - -Execute a repeating callback with a configurable delay starting at a specific time. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_every(callback, time, repeat, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title time %} - -A Python `time` object that specifies when the initial callback will occur. - -##### {% linkable_title repeat %} - -After the initial callback has occurred, another will occur every `repeat` seconds. - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Run every 17 minutes starting in 2 hours time -import datetime -... -self.run_every(self.run_every_c, time, 17 * 60) -``` - -#### {% linkable_title cancel_timer() %} -Cancel a previously created timer - -#### {% linkable_title Synopsis %} - -```python -self.cancel_timer(handle) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title handle %} - -A handle value returned from the original call to create the timer. - -#### {% linkable_title Examples %} - -```python -self.cancel_timer(handle) -``` - -### {% linkable_title info_timer() %} - -Get information on a scheduler event from it's handle. - -#### {% linkable_title Synopsis %} - -```python -time, interval, kwargs = self.info_timer(handle) -``` - -#### {% linkable_title Returns %} - -time - datetime object representing the next time the callback will be fired - -interval - repeat interval if applicable, `0` otherwise. - -kwargs - the values supplied when the callback was initially created. - -#### {% linkable_title Parameters %} - -##### {% linkable_title handle %} - -The handle returned when the scheduler call was made. - -#### {% linkable_title Examples %} - -```python -time, interval, kwargs = self.info_timer(handle) -``` - -### {% linkable_title Scheduler Ransomization %} - -All of the scheduler calls above support 2 additional optional arguments, `random_start` and `random_end`. Using these arguments it is possible to randomize the firing of callbacks to the degree desired by setting the appropriate number of seconds with the parameters. - -- `random_start` - start of range of the random time -- `random_end` - end of range of the random time - -`random_start` must always be numerically lower than `random_end`, they can be negative to denote a random offset before and event, or positive to denote a random offset after an event. The event would be a an absolute or relative time or sunrise/sunset depending on whcih scheduler call you use and these values affect the base time by the spcified amount. If not specified, they will default to `0`. - -For example: - -```python -# Run a callback in 2 minutes minus a random number of seconds between 0 and 60, e.g. run between 60 and 120 seconds from now -self.handle = self.run_in(callback, 120, random_start = -60, **kwargs) -# Run a callback in 2 minutes plus a random number of seconds between 0 and 60, e.g. run between 120 and 180 seconds from now -self.handle = self.run_in(callback, 120, random_end = 60, **kwargs) -# Run a callback in 2 minutes plus or minus a random number of seconds between 0 and 60, e.g. run between 60 and 180 seconds from now -self.handle = self.run_in(callback, 120, random_start = -60, random_end = 60, **kwargs) -``` - -## {% linkable_title Sunrise and Sunset %} - -AppDaemon has a number of features to allow easy tracking of sunrise and sunset as well as a couple of scheduler functions. Note that the scheduler functions also support the randomization parameters described above, but they cannot be used in conjunction with the `offset` parameter`. - -### {% linkable_title run_at_sunrise() %} - -Run a callback at or around sunrise. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_at_sunrise(callback, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title offset = %} - -The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with `random_start` or `random_end` - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -import datetime -... -# Run 45 minutes before sunset -self.run_at_sunrise(self.sun, offset = datetime.timedelta(minutes = -45).total_seconds(), "Sunrise -45 mins") -# or you can just do the math yourself -self.run_at_sunrise(self.sun, offset = 30 * 60, "Sunrise +30 mins") -# Run at a random time +/- 60 minutes from sunrise -self.run_at_sunrise(self.sun, random_start = -60*60, random_end = 60*60, "Sunrise, random +/- 60 mins") -# Run at a random time between 30 and 60 minutes before sunrise -self.run_at_sunrise(self.sun, random_start = -60*60, random_end = 30*60, "Sunrise, random - 30 - 60 mins") -``` - -### {% linkable_title run_at_sunset() %} - -Run a callback at or around sunset. - -#### {% linkable_title Synopsis %} - -```python -self.handle = self.run_at_sunset(callback, offset, **kwargs) -``` - -#### {% linkable_title Returns %} - -A handle that can be used to cancel the timer. - -#### {% linkable_title Parameters %} - -##### {% linkable_title callback %} - -Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above. - -##### {% linkable_title offset = %} - -The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with `random_start` or `random_end` - -##### {% linkable_title \*\*kwargs %} - -Arbitary keyword parameters to be provided to the callback function when it is invoked. - -#### {% linkable_title Examples %} - -```python -# Example using timedelta -import datetime -... -self.run_at_sunset(self.sun, datetime.timedelta(minutes = -45).total_seconds(), "Sunset -45 mins") -# or you can just do the math yourself -self.run_at_sunset(self.sun, 30 * 60, "Sunset +30 mins") -# Run at a random time +/- 60 minutes from sunset -self.run_at_sunset(self.sun, random_start = -60*60, random_end = 60*60, "Sunset, random +/- 60 mins") -# Run at a random time between 30 and 60 minutes before sunset -self.run_at_sunset(self.sun, random_start = -60*60, random_end = 30*60, "Sunset, random - 30 - 60 mins") -``` -### {% linkable_title sunrise() %} - -Return the time that the next Sunrise will occur. - -#### {% linkable_title Synopsis %} - -```python -self.sunrise() -``` - -#### {% linkable_title Returns %} - -A Python datetime that represents the next time Sunrise will occur. - -#### {% linkable_title Examples %} - -```python -rise_time = self.sunrise() -``` -### {% linkable_title sunset() %} - -Return the time that the next Sunset will occur. - -#### {% linkable_title Synopsis %} - -```python -self.sunset() -``` - -#### {% linkable_title Returns %} - -A Python datetime that represents the next time Sunset will occur. - -#### {% linkable_title Examples %} - -```python -set_time = self.sunset() -``` -### {% linkable_title sun_up() %} - -A function that allows you to determine if the sun is currently up. - -#### {% linkable_title Synopsis %} - -```python -result = self.sun_up() -``` - -#### {% linkable_title Returns %} - -`True` if the sun is up, False otherwise. - -#### {% linkable_title Examples %} - -```python -if self.sun_up(): - do something -``` - -### {% linkable_title sun_down() %} - -A function that allows you to determine if the sun is currently down. - -#### {% linkable_title Synopsis %} - -```python -result = self.sun_down() -``` - -#### {% linkable_title Returns %} - -`True` if the sun is down, False otherwise. - -#### {% linkable_title Examples %} - -```python -if self.sun_down(): - do something -``` - -## {% linkable_title Calling Services %} - -### {% linkable_title About Services %} - -Services within Home Assistant are how changes are made to the system and its devices. Services can be used to turn lights on and off, set thermostats and a whole number of other things. Home Assistant supplies a single interface to all these disparate services that take arbitrary parameters. AppDaemon provides the `call_service()` function to call into Home Assistant and run a service. In addition, it also provides convenience functions for some of the more common services making calling them a little easier. - -### {% linkable_title call_service() %} - -Call service is the basic way of calling a service within AppDaemon. It can call any service and provide any required parameters. Available services can be found using the developer tools in the UI. For listed services, the part before the first period is the domain, and the part after is the service name. For instance, `light.turn_on` has a domain of `light` and a service name of `turn_on`. - -#### {% linkable_title Synopsis %} - -```python -self.call_service(self, service, **kwargs) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title service %} - -The service name, e.g. `light.turn_on`. - -##### {% linkable_title \*\*kwargs %} - -Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g. `entity_id = light.office_1`. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an `entity_id` however, so use of the above example is very common with this call. - -#### {% linkable_title Examples %} - -```python -self.call_service("light/turn_on", entity_id = "light.office_lamp", color_name = "red") -self.call_service("notify/notify", title = "Hello", message = "Hello World") -``` -### {% linkable_title turn_on() %} - -This is a convenience function for the `homassistant.turn_on` function. It is able to turn on pretty much anything in Home Assistant that can be turned on or run: - -- Lights -- Switches -- Scenes -- Scripts - -And many more. - -#### {% linkable_title Synopsis %} - -```python -self.turn_on(entity_id, **kwargs) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity_id of the thing to be turned on, e.g. `light.office_lamp` or ```scene.downstairs_on``` - -##### {% linkable_title \*\*kwargs %} - -A comma separated list of key value pairs to allow specification of parameters over and above `entity_id`. - -#### {% linkable_title Examples %} - -```python -self.turn_on("switch.patio_lights") -self.turn_on("scene.bedrrom_on") -self.turn_on("light.office_1", color_name = "green") -``` - -### {% linkable_title turn_off() %} - -This is a convenience function for the `homassistant.turn_off` function. Like `homeassistant.turn_on`, it is able to turn off pretty much anything in Home Assistant that can be turned off. - -#### {% linkable_title Synopsis %} - -```python -self.turn_off(entity_id) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity_id of the thing to be turned off, e.g. `light.office_lamp` or `scene.downstairs_on`. - -#### {% linkable_title Examples %} - -```python -self.turn_off("switch.patio_lights") -self.turn_off("light.office_1") -``` - -### {% linkable_title toggle() %} - -This is a convenience function for the `homassistant.toggle` function. It is able to flip the state of pretty much anything in Home Assistant that can be turned on or off. - -#### {% linkable_title Synopsis %} - -```python -self.toggle(entity_id) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity_id of the thing to be toggled, e.g. `light.office_lamp` or `scene.downstairs_on`. - -#### {% linkable_title Examples %} - -```python -self.toggle("switch.patio_lights") -self.toggle("light.office_1", color_name = "green") -``` - -### {% linkable_title select_value() %} - -This is a convenience function for the `input_slider.select_value` function. It is able to set the value of an input_slider in Home Assistant. - -#### {% linkable_title Synopsis %} - -```python -self.select_value(entity_id, value) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity_id of the input_slider to be changed, e.g. `input_slider.alarm_hour`. - -##### {% linkable_title value %} - -The new value to set the input slider to. - -#### {% linkable_title Examples %} - -```python -self.select_value("input_slider.alarm_hour", 6) -``` - -### {% linkable_title select_option() %} - -This is a convenience function for the `input_select.select_option` function. It is able to set the value of an input_select in Home Assistant. - -#### {% linkable_title Synopsis %} - -```python -self.select_option(entity_id, option) -``` - -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity_id of the input_select to be changed, e.g. `input_select.mode`. - -##### {% linkable_title value %} - -The new value to set the input slider to. - -#### {% linkable_title Examples %} - -```python -self.select_option("input_select.mode", "Day") -``` - -### {% linkable_title notify() %} - -This is a convenience function for the `notify.notify` service. It will send a notification to your defualt notification service. If you have more than one, use `call_service()` to call the specific notification service you require instead. - -#### {% linkable_title Synopsis %} - -```python -notify(message, title=None) -``` -#### {% linkable_title Returns %} - -None - -#### {% linkable_title Parameters %} - -##### {% linkable_title message %} - -Message to be sent to the notification service. - -##### {% linkable_title title %} - -Title of the notification - optional. - -#### {% linkable_title Examples %} - -```python -self.notify("", "Switching mode to Evening") -``` - -## {% linkable_title Events %} - -### {% linkable_title About Events %} - -Events are a fundamental part of how Home Assistant works under the covers. HA has an event bus that all components can read and write to, enabling components to inform other components when important events take place. We have already seen how state changes can be propagated to AppDaemon - a state change however is merely an example of an event within Home Assistant. There are several other event types, among them are: - -- `homeassistant_start` -- `homeassistant_stop` -- `state_changed` -- `service_registered` -- `call_service` -- `service_executed` -- `platform_discovered` -- `component_loaded` - -Using AppDaemon, it is possible to subscribe to specific events as well as fire off events. - -In addition to the Home Assistant supplied events, AppDaemon adds 2 more events. These are internal to AppDaemon and are not visible on the Home Assistant bus: - -- `appd_started` - fired once when AppDaemon is first started and after Apps are initialized -- `ha_started` - fired every time AppDaemon detects a Home Assistant restart - -### {% linkable_title About Event Callbacks %} - -As with State Change and Scheduler callbacks, Event Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this: - -```python - def my_callback(self, event_name, data, kwargs): - -``` - -You can call the function whatever you like - you will reference it in the Scheduler call, and you can create as many callback functions as you need. - -The parameters have the following meanings: - -#### {% linkable_title self %} - -A standard Python object reference. - -#### {% linkable_title event_name %} - -Name of the event that was called, e.g. `call_service`. - -#### {% linkable_title data %} - -Any data that the system supplied with the event as a dict. - -#### {% linkable_title kwargs %} - -A dictionary containing Zero or more user keyword arguments to be supplied to the callback. - -### {% linkable_title listen_event() %} - -Listen event sets up a callback for a specific event, or any event. - -#### {% linkable_title Synopsis %} - -```python -handle = listen_event(function, event = None, **kwargs): -``` -#### {% linkable_title Returns %} - -A handle that can be used to cancel the callback. - -#### {% linkable_title Parameters %} - -##### {% linkable_title function %} - -The function to be called when the event is fired. - -##### {% linkable_title event %} - -Name of the event to subscribe to. Can be a standard Home Assistant event such as `service_registered` or an arbitrary custom event such as `"MODE_CHANGE"`. If no event is specified, `listen_event()` will subscribe to all events. - -##### {% linkable_title \*\*kwargs (optional) %} - -One or more keyword value pairs representing App specific parameters to supply to the callback. If the keywords match values within the event data, they will act as filters, meaning that if they don't match the values, the callback will not fire. - -As an example of this, a Minimote controller when activated will generate an event called `zwave.scene_activated`, along with 2 pieces of data that are specific to the event - `entity_id` and `scene`. If you include keyword values for either of those, the values supplied to the `listen_event()1 call must match the values in the event or it will not fire. If the keywords do not match any of the data in the event they are simply ignored. - -Filtering will work with any event type, but it will be necessary to figure out the data associated with the event to understand what values can be filtered on. This can be achieved by examining Home Assistant's logfiles when the event fires. - -#### {% linkable_title Examples %} - -```python -self.listen_event(self.mode_event, "MODE_CHANGE") -# Listen for a minimote event activating scene 3: -self.listen_event(self.generic_event, "zwave.scene_activated", scene_id = 3) -# Listen for a minimote event activating scene 3 from a specific minimote: -self.listen_event(self.generic_event, "zwave.scene_activated", entity_id = "minimote_31", scene_id = 3) -``` - -### {% linkable_title cancel_listen_event() %} - -Cancels callbacks for a specific event. - -#### {% linkable_title Synopsis %} - -```python -cancel_listen_event(handle) -``` -#### {% linkable_title Returns %} - -None. - -#### {% linkable_title Parameters %} - -##### handle - -A handle returned from a previous call to `listen_event()`. - -#### {% linkable_title Examples %} - -```python -self.cancel_listen_event(handle) -``` - -### {% linkable_title info_listen_event() %} - -Get information on an event callback from it's handle. - -#### {% linkable_title Synopsis %} - -```python -service, kwargs = self.info_listen_event(handle) -``` - -#### {% linkable_title Returns %} - -service, kwargs - the values supplied when the callback was initially created. - -#### {% linkable_title Parameters %} - -##### {% linkable_title handle %} - -The handle returned when the `listen_event()` call was made. - -#### {% linkable_title Examples %} - -```python -service, kwargs = self.info_listen_event(handle) -``` - - -### {% linkable_title fire_event() %} - -Fire an event on the HomeAssistant bus, for other components to hear. - -#### {% linkable_title Synopsis %} - -```python -fire_event(event, **kwargs) -``` - -#### {% linkable_title Returns %} - -None. - -#### {% linkable_title Parameters %} - -##### {% linkable_title event %} - -Name of the event. Can be a standard Home Assistant event such as `service_registered` or an arbitrary custom event such as `"MODE_CHANGE"`. - -##### {% linkable_title \*\*kwargs %} - -Zero or more keyword arguments that will be supplied as part of the event. - -#### {% linkable_title Examples %} - -```python -self.fire_event("MY_CUSTOM_EVENT", jam="true") -``` - -### {% linkable_title Event Callback Function Signature %} - -Functions called as an event callback will be supplied with 2 arguments: - -```python -def service(self, event_name, data): -``` - -#### {% linkable_title event_name %} - -The name of the event that caused the callback, e.g. `"MODE_CHANGE"` or `call_service`. - -#### {% linkable_title data %} - -A dictionary containing any additional information associated with the event. - -### {% linkable_title Use of Events for Signalling between Home Assistant and AppDaemon %} - -Home Assistant allows for the creation of custom events and existing components can send and receive them. This provides a useful mechanism for signaling back and forth between Home Assistant and AppDaemon. For instance, if you would like to create a UI Element to fire off some code in Home Assistant, all that is necessary is to create a script to fire a custom event, then subscribe to that event in AppDaemon. The script would look something like this: - -```yaml -alias: Day -sequence: -- event: MODE_CHANGE - event_data: - mode: Day -``` - -The custom event `MODE_CHANGE` would be subscribed to with: - -```python -self.listen_event(self.mode_event, "MODE_CHANGE") -``` - -Home Assistant can send these events in a variety of other places - within automations, and also directly from Alexa intents. Home Assistant can also listen for custom events with it's automation component. This can be used to signal from AppDaemon code back to home assistant. Here is a sample automation: - -```yaml -automation: - trigger: - platform: event - event_type: MODE_CHANGE - ... - ... -``` - -This can be triggered with a call to AppDaemon's fire_event() as follows: - -```python -self.fire_event("MODE_CHANGE", mode = "Day") -``` - -## {% linkable_title Presence %} - -Presence in Home Assistant is tracked using Device Trackers. The state of all device trackers can be found using the `get_state()` call, however AppDaemon provides several convenience functions to make this easier. - -### {% linkable_title get_trackers() %} - -Return a list of all device trackers. This is designed to be iterated over. - -#### {% linkable_title Synopsis %} - -```python -tracker_list = get_trackers() -``` -#### {% linkable_title Returns %} - -An iterable list of all device trackers. - -#### {% linkable_title Examples %} - -```python -trackers = self.get_trackers() -for tracker in trackers: - do something -``` - -### {% linkable_title get_tracker_state() %} - -Get the state of a tracker. The values returned depend in part on the configuration and type of device trackers in the system. Simpler tracker types like `Locative` or `NMAP` will return one of 2 states: - -- `home` -- `not_home` - -Some types of device tracker are in addition able to supply locations that have been configured as Geofences, in which case the name of that location can be returned. - -#### {% linkable_title Synopsis %} - -```python -location = self.get_tracker_state(tracker_id) -``` - -#### {% linkable_title Returns %} - -A string representing the location of the tracker. - -#### {% linkable_title Parameters %} - -##### {% linkable_title tracker_id %} - -Fully qualified entity_id of the device tracker to query, e.g. `device_tracker.andrew`. - -#### {% linkable_title Examples %} - -```python -trackers = self.get_trackers() -for tracker in trackers: - self.log("{} is {}".format(tracker, self.get_tracker_state(tracker))) -``` - -### {% linkable_title everyone_home() %} - -A convenience function to determine if everyone is home. Use this in preference to getting the state of `group.all_devices()` as it avoids a race condition when using state change callbacks for device trackers. - -#### {% linkable_title Synopsis %} - -```python -result = self.everyone_home() -``` -#### {% linkable_title Returns %} - -Returns `True` if everyone is at home, `False` otherwise. - -#### {% linkable_title Examples %} - -```python -if self.everyone_home(): - do something -``` -### {% linkable_title anyone_home() %} - -A convenience function to determine if one or more person is home. Use this in preference to getting the state of `group.all_devices()` as it avoids a race condition when using state change callbacks for device trackers. - -#### {% linkable_title Synopsis %} - -```python -result = self.anyone_home() -``` - -#### {% linkable_title Returns %} - -Returns `True` if anyone is at home, `False` otherwise. - -#### {% linkable_title Examples %} - -```python -if self.anyone_home(): - do something -``` -### {% linkable_title noone_home() %} - -A convenience function to determine if no people are at home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers. - -#### {% linkable_title Synopsis %} - -```python -result = self.noone_home() -``` - -#### {% linkable_title Returns %} - -Returns `True` if no one is home, `False` otherwise. - -#### {% linkable_title Examples %} - -```python -if self.noone_home(): - do something -``` - -## {% linkable_title Miscellaneous Helper Functions %} - -### {% linkable_title time() %} - -Returns a python `time` object representing the current time. Use this in preference to the standard Python ways to discover the current time, especially when using the "Time Travel" feature for testing. - -#### {% linkable_title Synopsis %} - -```python -time() -``` - -#### {% linkable_title Returns %} - -A localised Python time object representing the current AppDaemon time. - -#### {% linkable_title Parameters %} - -None - -#### {% linkable_title Example %} - -```python -now = self.time() -``` - -### {% linkable_title date() %} - -Returns a python `date` object representing the current date. Use this in preference to the standard Python ways to discover the current date, especially when using the "Time Travel" feature for testing. - -#### {% linkable_title Synopsis %} - -```python -date() -``` - -#### {% linkable_title Returns %} - -A localised Python time object representing the current AppDaemon date. - -#### {% linkable_title Parameters %} - -None - -#### {% linkable_title Example %} - -```python -today = self.date() -``` - -### {% linkable_title datetime() %} - -Returns a python `datetime` object representing the current date and time. Use this in preference to the standard Python ways to discover the current time, especially when using the "Time Travel" feature for testing. - -#### {% linkable_title Synopsis %} - -```python -datetime() -``` - -#### {% linkable_title Returns %} - -A localised Python datetime object representing the current AppDaemon date and time. - -#### {% linkable_title Parameters %} - -None - -#### {% linkable_title Example %} - -```python -now = self.datetime() -``` - - -### {% linkable_title convert_utc() %} - -Home Assistant provides timestamps of several different sorts that may be used to gain additional insight into state changes. These timestamps are in UTC and are coded as ISO 8601 Combined date and time strings. `convert_utc()` will accept one of these strings and convert it to a localised Python datetime object representing the timestamp - -#### {% linkable_title Synopsis %} - -```python -convert_utc(utc_string) -``` - -#### {% linkable_title Returns %} - -`convert_utc(utc_string)` returns a localised Python datetime object representing the timestamp. - -#### {% linkable_title Parameters %} - -##### {% linkable_title utc_string %} - -An ISO 8601 encoded date and time string in the following format: `2016-07-13T14:24:02.040658-04:00` - -#### {% linkable_title Example %} - -###{% linkable_title parse_time() %} - -Takes a string representation of a time, or sunrise or sunset offset and converts it to a `datetime.time` object. - -#### {% linkable_title Synopsis %} - -```python -parse_time(time_string) -``` - -#### {% linkable_title Returns %} - -A `datetime.time` object, representing the time given in the `time_string` argument. - -#### {% linkable_title Parameters %} - -##### {% linkable_title time_string %} - -A representation of the time in a string format with one of the following formats: - -- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. -- sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds - -#### {% linkable_title Example %} - -```python -time = self.parse_time("17:30:00") -time = self.parse_time("sunrise") -time = self.parse_time("sunset + 00:30:00") -time = self.parse_time("sunrise + 01:00:00") -``` - -### {% linkable_title now_is_between() %} - -Takes two string representations of a time, or sunrise or sunset offset and returns true if the current time is between those 2 times. `now_is_between()` can correctly handle transitions across midnight. - -#### {% linkable_title Synopsis %} - -```python -now_is_between(start_time_string, end_time_string) -``` - -#### {% linkable_title Returns %} - -`True` if the current time is within the specified start and end times, `False` otherwise. - -#### {% linkable_title Parameters %} - -##### {% linkable_title start_time_string, end_time_string %} - -A representation of the start and end time respectively in a string format with one of the following formats: - -- HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format. -- sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds - -#### {% linkable_title Example %} - -```python -if self.now_is_between("17:30:00", "08:00:00"): - do something -if self.now_is_between("sunset - 00:45:00", "sunrise + 00:45:00"): - do something -``` - -### {% linkable_title friendly_name() %} - -`frindly_name()` will return the Friendly Name of an entity if it has one. - -#### {% linkable_title Synopsis %} - -```python -Name = self.friendly_name(entity_id) -``` - -#### {% linkable_title Returns %} - -The friendly name of the entity if it exists or the entity id if not. - -#### {% linkable_title Example %} - -```python -tracker = "device_tracker.andrew" -self.log("{} ({}) is {}".format(tracker, self.friendly_name(tracker), self.get_tracker_state(tracker))) -``` - -### {% linkable_title split_entity() %} - -`split_entity()` will take a fully qualified entity id of the form `light.hall_light` and split it into 2 values, the device and the entity, e.g. `light` and `hall_light`. - -#### {% linkable_title Synopsis %} - -```python -device, entity = self.split_entity(entity_id) -``` - -#### {% linkable_title Parameters %} - -##### {% linkable_title entity_id %} - -Fully qualified entity id to be split. - -#### {% linkable_title Returns %} - -A list with 2 entries, the device and entity respectively. - -#### {% linkable_title Example %} - -```python -device, entity = self.split_entity(entity_id) -if device == "scene": - do something specific to scenes -``` - - -### {% linkable_title get_app() %} - -`get_app()` will return the instantiated object of another app running within the system. This is useful for calling functions or accessing variables that reside in different apps without requiring duplication of code. - -#### {% linkable_title Synopsis %} - -```python -get_app(self, name) -``` -#### {% linkable_title Parameters %} - -##### {% linkable_title name %} - -Name of the app required. This is the name specified in header section of the config file, not the module or class. - -#### {% linkable_title Returns %} - -An object reference to the class. - -#### {% linkable_title Example %} -```python -MyApp = self.get_app("MotionLights") -MyApp.turn_light_on() -``` - -### {% linkable_title split_device_list() %} - -`split_device_list()` will take a comma separated list of device types (or anything else for that matter) and return them as an iterable list. This is intended to assist in use cases where the App takes a list of entities from an argument, e.g. a list of sensors to monitor. If only one entry is provided, an iterable list will still be returned to avoid the need for special processing. - -#### {% linkable_title Synopsis %} - -```python -devices = split_device_list(list) -``` - -#### {% linkable_title Returns %} - -A list of split devices with 1 or more entries. - -#### {% linkable_title Example %} - -```python -for sensor in self.split_device_list(self.args["sensors"]): - do something for each sensor, e.g. make a state subscription -``` - - -### {% linkable_title Writing to Logfiles %} - -AppDaemon uses 2 separate logs - the general log and the error log. An AppDaemon App can write to either of these using the supplied convenience methods `log()` and `error()`, which are provided as part of parent `AppDaemon` class, and the call will automatically pre-pend the name of the App making the call. The `-D` option of AppDaemon can be used to specify what level of logging is required and the logger objects will work as expected. - -### {% linkable_title log() %} - -#### {% linkable_title Synopsis %} - -```python -log(message, level = "INFO") -``` - -#### {% linkable_title Returns %} - -Nothing - -#### {% linkable_title Parameters %} - -##### {% linkable_title Message %} - -The message to log. - -##### {% linkable_title level %} - -The log level of the message - takes a string representing the standard logger levels. - -#### {% linkable_title Examples %} - -```python -self.log("Log Test: Parameter is {}".format(some_variable)) -self.log("Log Test: Parameter is {}".format(some_variable), level = "ERROR") -``` - -### {% linkable_title error() %} - -#### {% linkable_title Synopsis %} - -```python -error(message, level = "WARNING") -``` -#### {% linkable_title Returns %} - -Nothing - -#### {% linkable_title Parameters %} - -##### {% linkable_title Message %} - -The message to log. - -##### {% linkable_title level %} - -The log level of the message - takes a string representing the standard logger levels. - -#### {% linkable_title Examples %} - -```python -self.error("Some Warning string") -self.error("Some Critical string", level = "CRITICAL") -``` - -## {% linkable_title Sharing information between Apps %} - -Sharing information between different Apps is very simple if required. Each app gets access to a global dictionary stored in a class attribute called `self.global_vars`. Any App can add or read any key as required. This operation is not however threadsafe so some car is needed. - -In addition, Apps have access to the entire configuration if required, meaning they can access AppDaemon configuration items as well as parameters from other Apps. To use this, there is a class attribute called `self.config`. It contains a `ConfigParser` object, which is similar in operation to a `Dictionary`. To access any apps parameters, simply reference the ConfigParser object using the Apps name (form the config file) as the first key, and the parameter required as the second, for instance: - -```python -other_apps_arg = self.config["some_app"]["some_parameter"]. -``` - -To get AppDaemon's config parameters, use the key "AppDaemon", e.g.: - -```python -app_timezone = self.config["AppDaemon"]["time_zone"] -``` - -And finally, it is also possible to use the AppDaemon as a global area for sharing parameters across Apps. Simply add the required parameters to the AppDaemon section of your config: - -```ini -[AppDaemon] -ha_url = -ha_key = -... -global_var = hello world -``` - -Then access it as follows: - -```python -my_global_var = conf.config["AppDaemon"]["global_var"] -``` - -## {% linkable_title Development Workflow %} - -Developing Apps is intended to be fairly simple but is an exercise in programming like any other kind of Python programming. As such, it is expected that apps will contain syntax errors and will generate exceptions during the development process. AppDaemon makes it very easy to iterate through the development process as it will automatically reload code that has changed and also will reload code if any of the parameters in the configuration file change as well. - -The recommended workflow for development is as follows: - -- Open a window and tail the `appdaemon.log` file -- Open a second window and tail the `error.log` file -- Open a third window or the editor of your choice for editing the App - -With this setup, you will see that every time you write the file, AppDaemon will log the fact and let you know it has reloaded the App in the `appdaemon.log` file. - -If there is an error in the compilation or a runtime error, this will be directed to the `error.log` file to enable you to see the error and correct it. When an error occurs, there will also be a warning message in `appdaemon.log` to tell you to check the error log. - -## {% linkable_title Time Travel %} - -OK, time travel sadly isn't really possible but it can be very useful when testing Apps. For instance, imagine you have an App that turns a light on every day at sunset. It might be nice to test it without waiting for Sunset - and with AppDaemon's "Time Travel" features you can. - -### {% linkable_title Choosing a Start Time %} - -Internally, AppDaemon keeps track of it's own time relative to when it was started. This make is possible to start AppDaemon with a different start time and date to the current time. For instance to test that sunset App, start AppDaemon at a time just before sunset and see if it works as expected. To do this, simply use the "-s" argument on AppDaemon's command line. e,g,: - -```bash -$ appdaemon -s "2016-06-06 19:16:00" -2016-09-06 17:16:00 INFO AppDaemon Version 1.3.2 starting -2016-09-06 17:16:00 INFO Got initial state -2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py -... -``` - -Note the timestamps in the log - AppDaemon believes it is now just before sunset and will process any callbacks appropriately. - -### {% linkable_title Speeding things up %} - -Some Apps need to run for periods of a day or two for you to test all aspects. This can be time consuming, but Time Travel can also help here in two ways. The first is by speeding up time. To do this, simply use the `-t` option on the command line. This specifies the amount of time a second lasts while time travelling. The default of course is 1 second, but if you change it to `0.1` for instance, AppDaemon will work 10x faster. If you set it to `0`, AppDaemon will work as fast as possible and, depending in your hardware, may be able to get through an entire day in a matter of minutes. Bear in mind however, due to the threaded nature of AppDaemon, when you are running with `-t 0` you may see actual events firing a little later than expected as the rest of the system tries to keep up with the timer. To set the tick time, start AppDaemon as follows: - -```bash -$ appdaemon -t 0.1 -``` - -AppDaemon also has an interval flag - think of this as a second multiplier. If the flag is set to 3600 for instance, each tick of the scheduler will jump the time forward by an hour. This is good for covering vast amounts of time quickly but event firing accuracy will suffer as a result. For example: - -```bash -$ appdaemon -e 3600 -``` - -### Automatically stopping - -AppDaemon can be set to terminate automatically at a specific time. This can be useful if you want to repeatedly rerun a test, for example to test that random values are behaving as expected. Simply specify the end time with the `-e` flag as follows: - -```bash -$ appdaemon -e "2016-06-06 10:10:00" -2016-09-06 17:16:00 INFO AppDaemon Version 1.3.2 starting -2016-09-06 17:16:00 INFO Got initial state -2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py -... -``` - -The `-e` flag is most useful when used in conjuntion with the -s flag and optionally the `-t` flag. For example, to run from just before sunset, for an hour, as fast as possible: - -```bash -$ appdaemon -s "2016-06-06 19:16:00" -s "2016-06-06 20:16:00" -t 0 -``` - - -### {% linkable_title A Note on Times %} - -Some Apps you write may depend on checking times of events relative to the current time. If you are time travelling this will not work if you use standard python library calls to get the current time and date etc. For this reason, always use the AppDamon supplied `time()`, `date()` and `datetime()` calls, documented earlier. These calls will consult with AppDaemon's internal time rather than the actual time and give you the correct values. diff --git a/source/appdaemon/configuration.markdown b/source/appdaemon/configuration.markdown deleted file mode 100644 index ec955aff6221..000000000000 --- a/source/appdaemon/configuration.markdown +++ /dev/null @@ -1,79 +0,0 @@ ---- -layout: page -title: "Configuration" -description: "AppDaemon Configuration" -release_date: 2016-11-27 08:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: 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 = -ha_key = -logfile = STDOUT -errorfile = STDERR -app_dir = /conf/apps -threads = 10 -latitude = -longitude = -elevation = -cert_path = -# 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 = -ha_key = -logfile = STDOUT -errorfile = STDERR -app_dir = /conf/apps -threads = 10 -latitude = -longitude = -elevation = -``` - -You can run Docker and point the conf volume to that directory. diff --git a/source/appdaemon/example_apps.markdown b/source/appdaemon/example_apps.markdown deleted file mode 100644 index 2d7b659ad797..000000000000 --- a/source/appdaemon/example_apps.markdown +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 -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. \ No newline at end of file diff --git a/source/appdaemon/installation.markdown b/source/appdaemon/installation.markdown deleted file mode 100644 index 6eb9f1f16c50..000000000000 --- a/source/appdaemon/installation.markdown +++ /dev/null @@ -1,45 +0,0 @@ ---- -layout: page -title: "Installation" -description: "AppDaemon Installation" -release_date: 2016-11-27 08:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: true -hide_github_edit: true ---- - -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 . -``` diff --git a/source/appdaemon/operation.markdown b/source/appdaemon/operation.markdown deleted file mode 100644 index 9f643719a614..000000000000 --- a/source/appdaemon/operation.markdown +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: page -title: "Operation" -description: "Operation" -release_date: 2016-11-27 08:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: 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. diff --git a/source/appdaemon/reboot.markdown b/source/appdaemon/reboot.markdown deleted file mode 100644 index 96d7b9552b89..000000000000 --- a/source/appdaemon/reboot.markdown +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 -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. diff --git a/source/appdaemon/running.markdown b/source/appdaemon/running.markdown deleted file mode 100755 index 78e5cf3976e6..000000000000 --- a/source/appdaemon/running.markdown +++ /dev/null @@ -1,95 +0,0 @@ ---- -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 -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. - -## {% 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 /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 - -e ENDTIME, --endtime ENDTIME - end time for scheduler - -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. diff --git a/source/appdaemon/tutorial.markdown b/source/appdaemon/tutorial.markdown deleted file mode 100755 index bec655b90746..000000000000 --- a/source/appdaemon/tutorial.markdown +++ /dev/null @@ -1,128 +0,0 @@ ---- -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 -hide_github_edit: true ---- - -## {% 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! - diff --git a/source/appdaemon/updating.markdown b/source/appdaemon/updating.markdown deleted file mode 100644 index 20a5ebef141a..000000000000 --- a/source/appdaemon/updating.markdown +++ /dev/null @@ -1,26 +0,0 @@ ---- -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 -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. diff --git a/source/appdaemon/windows.markdown b/source/appdaemon/windows.markdown deleted file mode 100755 index 360bf975a122..000000000000 --- a/source/appdaemon/windows.markdown +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 -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. - -## {% 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. diff --git a/source/hadashboard.markdown b/source/hadashboard.markdown deleted file mode 100644 index 799468d0e6a6..000000000000 --- a/source/hadashboard.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -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 ---- - -HADashboard is a dashboard for [Home Assistant](https://home-assistant.io/) that is intended to be wall mounted, and is optimized for distance viewing. - -

    - - Sample Dashboard -

    - -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. - diff --git a/source/hadashboard/dash_config.markdown b/source/hadashboard/dash_config.markdown deleted file mode 100755 index 4abc93d3fd88..000000000000 --- a/source/hadashboard/dash_config.markdown +++ /dev/null @@ -1,274 +0,0 @@ ---- -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 ---- - -(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 -
  • -
    -
    • -``` - -- **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 `
    ` like this: - -``` html -
  • -
    -
    -
    • -``` - -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 -
  • -
    -
    • -``` - -- **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="°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="°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: - -

    - - The Alarm Panel -

    - -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="°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 -
  • -
    -
    • -``` -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="°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 -
    - -
    - -
    -
    - -``` - -- ***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://: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. diff --git a/source/hadashboard/hapush.markdown b/source/hadashboard/hapush.markdown deleted file mode 100755 index d390f22f3fc9..000000000000 --- a/source/hadashboard/hapush.markdown +++ /dev/null @@ -1,94 +0,0 @@ ---- -layout: page -title: "HAPush" -description: "HAPush" -release_date: 2016-11-13 15:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: true ---- - -# 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 - 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 -``` diff --git a/source/hadashboard/installation.markdown b/source/hadashboard/installation.markdown deleted file mode 100755 index ecce1549c1b0..000000000000 --- a/source/hadashboard/installation.markdown +++ /dev/null @@ -1,151 +0,0 @@ ---- -layout: page -title: "Installation" -description: "Installation" -release_date: 2016-11-13 15:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: true ---- - -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 /dashboards:/app/dashboards -v /lib/ha_conf.rb:/app/lib/ha_conf.rb -v /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. - diff --git a/source/hadashboard/reboot.markdown b/source/hadashboard/reboot.markdown deleted file mode 100755 index 0d87ef287250..000000000000 --- a/source/hadashboard/reboot.markdown +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: page -title: "Reboot" -description: "Reboot" -release_date: 2016-11-13 15:00:00 -0500 -sidebar: true -comments: false -sharing: true -footer: true ---- - -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. diff --git a/source/hadashboard/updating.markdown b/source/hadashboard/updating.markdown deleted file mode 100755 index 96d6f9731bd2..000000000000 --- a/source/hadashboard/updating.markdown +++ /dev/null @@ -1,24 +0,0 @@ ---- -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 ---- - -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. diff --git a/source/ios.markdown b/source/ios.markdown deleted file mode 100644 index 862fce661c42..000000000000 --- a/source/ios.markdown +++ /dev/null @@ -1,66 +0,0 @@ ---- -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 ---- - -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 - -

    -Currently, the app is only available via a closed beta. It will be on the App Store within the next few weeks. -

    - -

    - - An example of a Home Assistant group as seen in the iOS app. -

    - -## 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/ diff --git a/source/ios/devices_file.markdown b/source/ios/devices_file.markdown deleted file mode 100644 index 4b27059456fa..000000000000 --- a/source/ios/devices_file.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -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. diff --git a/source/ios/features.markdown b/source/ios/features.markdown deleted file mode 100644 index 895a6a25311c..000000000000 --- a/source/ios/features.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: page -title: "Features" -description: "Describes the features of Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -Coming soon diff --git a/source/ios/integration.markdown b/source/ios/integration.markdown deleted file mode 100644 index e9db1dd875e9..000000000000 --- a/source/ios/integration.markdown +++ /dev/null @@ -1,25 +0,0 @@ ---- -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 ---- - -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/` diff --git a/source/ios/location.markdown b/source/ios/location.markdown deleted file mode 100644 index f9bd14bf0a54..000000000000 --- a/source/ios/location.markdown +++ /dev/null @@ -1,36 +0,0 @@ ---- -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 ---- - -## {% 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 diff --git a/source/ios/notifications.markdown b/source/ios/notifications.markdown deleted file mode 100644 index 49490161de0f..000000000000 --- a/source/ios/notifications.markdown +++ /dev/null @@ -1,14 +0,0 @@ ---- -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 ---- - -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. diff --git a/source/ios/notifications/actions.markdown b/source/ios/notifications/actions.markdown deleted file mode 100644 index 9749cfec8aee..000000000000 --- a/source/ios/notifications/actions.markdown +++ /dev/null @@ -1,142 +0,0 @@ ---- -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 ---- - -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. - -

    - - Actionable notifications allow the user to send a command back to Home Assistant. -

    - -## 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. - -

    - - How the iOS device and Home Assistant work together to enable actionable notifications. -

    - -## 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: - 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. diff --git a/source/ios/notifications/architecture.markdown b/source/ios/notifications/architecture.markdown deleted file mode 100644 index c699e4529989..000000000000 --- a/source/ios/notifications/architecture.markdown +++ /dev/null @@ -1,15 +0,0 @@ ---- -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 ---- - -

    - - The push notification infrastructure layout -

    diff --git a/source/ios/notifications/attachments.markdown b/source/ios/notifications/attachments.markdown deleted file mode 100644 index 639f087b362c..000000000000 --- a/source/ios/notifications/attachments.markdown +++ /dev/null @@ -1,76 +0,0 @@ ---- -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 ---- - -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. - -

    -To expand a notification on 3D Touch devices simply force touch any notification. On non-3D Touch devices swipe and tap the "View" button. -

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

    - - An unexpanded push notification with an attachment. -

    - -

    - - The same notification but expanded to show the full size attachment -

    - -## 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. diff --git a/source/ios/notifications/basic.markdown b/source/ios/notifications/basic.markdown deleted file mode 100644 index fbb217edffe8..000000000000 --- a/source/ios/notifications/basic.markdown +++ /dev/null @@ -1,58 +0,0 @@ ---- -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 ---- - -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. - -

    - - A push notification showing all of the basic options `title` and `message` as well as `subtitle` and [actions](/ecosystem/ios/notifications/actions/). -

    - -### {% 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" -``` diff --git a/source/ios/notifications/content_extensions.markdown b/source/ios/notifications/content_extensions.markdown deleted file mode 100644 index 9279f75d5959..000000000000 --- a/source/ios/notifications/content_extensions.markdown +++ /dev/null @@ -1,61 +0,0 @@ ---- -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 ---- - -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 -``` - -

    - - An example of the map dynamic content. -

    - - -# 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 -``` - -
    - -
    - -# 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. diff --git a/source/ios/notifications/privacy_security_rate_limits.markdown b/source/ios/notifications/privacy_security_rate_limits.markdown deleted file mode 100644 index ebb0b1462674..000000000000 --- a/source/ios/notifications/privacy_security_rate_limits.markdown +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 ---- - -## {% 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. diff --git a/source/ios/notifications/requesting_location_updates.markdown b/source/ios/notifications/requesting_location_updates.markdown deleted file mode 100644 index f02f63f30e3f..000000000000 --- a/source/ios/notifications/requesting_location_updates.markdown +++ /dev/null @@ -1,30 +0,0 @@ ---- -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 ---- - -

    -**Do not rely on this functionality due to the time limits mentioned below.** -

    - -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. - diff --git a/source/ios/notifications/sounds.markdown b/source/ios/notifications/sounds.markdown deleted file mode 100644 index cbe35943ad89..000000000000 --- a/source/ios/notifications/sounds.markdown +++ /dev/null @@ -1,184 +0,0 @@ ---- -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 ---- - -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 -``` diff --git a/source/ios/requirements.markdown b/source/ios/requirements.markdown deleted file mode 100644 index 89e89e6dcbbf..000000000000 --- a/source/ios/requirements.markdown +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: page -title: "Requirements" -description: "Basic requirements to use Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -* 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. diff --git a/source/nginx.markdown b/source/nginx.markdown deleted file mode 100644 index 8d657a500311..000000000000 --- a/source/nginx.markdown +++ /dev/null @@ -1,133 +0,0 @@ ---- -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 ---- - -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; - } - } -} -``` diff --git a/source/notebooks.markdown b/source/notebooks.markdown deleted file mode 100644 index 6dfd9a73633a..000000000000 --- a/source/notebooks.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -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 ---- - -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. - -

    - -

    - -[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. diff --git a/source/notebooks/api.markdown b/source/notebooks/api.markdown deleted file mode 100644 index bf20faaecb37..000000000000 --- a/source/notebooks/api.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 ---- - -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). diff --git a/source/notebooks/database.markdown b/source/notebooks/database.markdown deleted file mode 100644 index 5b0cd3cd5569..000000000000 --- a/source/notebooks/database.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 ---- - -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. diff --git a/source/notebooks/graph.markdown b/source/notebooks/graph.markdown deleted file mode 100644 index 257d5adf4b94..000000000000 --- a/source/notebooks/graph.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 ---- - -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. diff --git a/source/notebooks/installation.markdown b/source/notebooks/installation.markdown deleted file mode 100644 index ffc67af78d24..000000000000 --- a/source/notebooks/installation.markdown +++ /dev/null @@ -1,50 +0,0 @@ ---- -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 ---- - -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 -``` - -

    -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. -

    - -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. - -

    - -

    - -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. - -

    - -

    - -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. - - diff --git a/source/notebooks/stats.markdown b/source/notebooks/stats.markdown deleted file mode 100644 index 542d7dbb18c0..000000000000 --- a/source/notebooks/stats.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 ---- - -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. diff --git a/source/scenegen.markdown b/source/scenegen.markdown deleted file mode 100644 index 0d8a8d047a76..000000000000 --- a/source/scenegen.markdown +++ /dev/null @@ -1,182 +0,0 @@ ---- -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 ---- - -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. - -## Installation - -### Clone the Repository -Clone the **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 -``` - -## Install Prereqs - -Before running `SceneGen` you will need to add some python prerequisites: - -```bash -$ sudo pip3 install configparser -``` - -You should now be ready to run `scenegen` - -## 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:// -k -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. - -## 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:// -k > 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. - -## 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`. - -## 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:// -k --types light,switch -``` - -or: - -``` -./scenegen.py https:// -k --types light -``` - -This will make more sense as and when more types are added. - -## 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:// -k --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. - -## Updating SceneGen -To update SceneGen after a new version is released, just run the following command to update your copy: - -```bash -$ git pull -``` - -## Release Notes - -***Version 1.2*** - -- Add installation instructions - -***Version 1.1*** - -- Add better error checking for Home Assistant errors - -***Version 1.0*** - -Initial Release \ No newline at end of file diff --git a/source/synology.markdown b/source/synology.markdown deleted file mode 100644 index 93002049f71e..000000000000 --- a/source/synology.markdown +++ /dev/null @@ -1,24 +0,0 @@ ---- -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 ---- - -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"; -``` From 94adff31817682abf0958e857e2f6931e33076c3 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 17 Feb 2017 08:14:13 +0100 Subject: [PATCH 36/51] Re-add ecosystem overview --- source/_docs/ecosystem.markdowm | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 source/_docs/ecosystem.markdowm diff --git a/source/_docs/ecosystem.markdowm b/source/_docs/ecosystem.markdowm new file mode 100644 index 000000000000..ea1512a9c316 --- /dev/null +++ b/source/_docs/ecosystem.markdowm @@ -0,0 +1,14 @@ +--- +layout: page +title: "Ecosystem" +description: "External tools for Home Assistant" +date: 2016-10-26 00:46 +sidebar: true +comments: false +sharing: true +footer: true +hide_github_edit: true +--- + +Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems. + From 38a515d6c0297cdd2a7bab59111aadaa2fec4a7c Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 17 Feb 2017 08:14:35 +0100 Subject: [PATCH 37/51] Move to ecosystem --- source/_docs/{ => ecosystem}/ios.markdown | 0 source/_docs/{ => ecosystem}/ios/devices_file.markdown | 0 source/_docs/{ => ecosystem}/ios/features.markdown | 0 source/_docs/{ => ecosystem}/ios/integration.markdown | 0 source/_docs/{ => ecosystem}/ios/location.markdown | 0 source/_docs/{ => ecosystem}/ios/notifications.markdown | 0 source/_docs/{ => ecosystem}/ios/notifications/actions.markdown | 0 .../_docs/{ => ecosystem}/ios/notifications/architecture.markdown | 0 .../_docs/{ => ecosystem}/ios/notifications/attachments.markdown | 0 source/_docs/{ => ecosystem}/ios/notifications/basic.markdown | 0 .../{ => ecosystem}/ios/notifications/content_extensions.markdown | 0 .../ios/notifications/privacy_security_rate_limits.markdown | 0 .../ios/notifications/requesting_location_updates.markdown | 0 source/_docs/{ => ecosystem}/ios/notifications/sounds.markdown | 0 source/_docs/{ => ecosystem}/ios/requirements.markdown | 0 source/_docs/{ => ecosystem}/mqtt.markdown | 0 source/_docs/{ => ecosystem}/mqtt/birth_will.markdown | 0 source/_docs/{ => ecosystem}/mqtt/broker.markdown | 0 source/_docs/{ => ecosystem}/mqtt/certificate.markdown | 0 source/_docs/{ => ecosystem}/mqtt/discovery.markdown | 0 source/_docs/{ => ecosystem}/mqtt/logging.markdown | 0 source/_docs/{ => ecosystem}/mqtt/processing_json.markdown | 0 source/_docs/{ => ecosystem}/mqtt/service.markdown | 0 source/_docs/{ => ecosystem}/mqtt/testing.markdown | 0 24 files changed, 0 insertions(+), 0 deletions(-) rename source/_docs/{ => ecosystem}/ios.markdown (100%) rename source/_docs/{ => ecosystem}/ios/devices_file.markdown (100%) rename source/_docs/{ => ecosystem}/ios/features.markdown (100%) rename source/_docs/{ => ecosystem}/ios/integration.markdown (100%) rename source/_docs/{ => ecosystem}/ios/location.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/actions.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/architecture.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/attachments.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/basic.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/content_extensions.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/privacy_security_rate_limits.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/requesting_location_updates.markdown (100%) rename source/_docs/{ => ecosystem}/ios/notifications/sounds.markdown (100%) rename source/_docs/{ => ecosystem}/ios/requirements.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/birth_will.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/broker.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/certificate.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/discovery.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/logging.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/processing_json.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/service.markdown (100%) rename source/_docs/{ => ecosystem}/mqtt/testing.markdown (100%) diff --git a/source/_docs/ios.markdown b/source/_docs/ecosystem/ios.markdown similarity index 100% rename from source/_docs/ios.markdown rename to source/_docs/ecosystem/ios.markdown diff --git a/source/_docs/ios/devices_file.markdown b/source/_docs/ecosystem/ios/devices_file.markdown similarity index 100% rename from source/_docs/ios/devices_file.markdown rename to source/_docs/ecosystem/ios/devices_file.markdown diff --git a/source/_docs/ios/features.markdown b/source/_docs/ecosystem/ios/features.markdown similarity index 100% rename from source/_docs/ios/features.markdown rename to source/_docs/ecosystem/ios/features.markdown diff --git a/source/_docs/ios/integration.markdown b/source/_docs/ecosystem/ios/integration.markdown similarity index 100% rename from source/_docs/ios/integration.markdown rename to source/_docs/ecosystem/ios/integration.markdown diff --git a/source/_docs/ios/location.markdown b/source/_docs/ecosystem/ios/location.markdown similarity index 100% rename from source/_docs/ios/location.markdown rename to source/_docs/ecosystem/ios/location.markdown diff --git a/source/_docs/ios/notifications.markdown b/source/_docs/ecosystem/ios/notifications.markdown similarity index 100% rename from source/_docs/ios/notifications.markdown rename to source/_docs/ecosystem/ios/notifications.markdown diff --git a/source/_docs/ios/notifications/actions.markdown b/source/_docs/ecosystem/ios/notifications/actions.markdown similarity index 100% rename from source/_docs/ios/notifications/actions.markdown rename to source/_docs/ecosystem/ios/notifications/actions.markdown diff --git a/source/_docs/ios/notifications/architecture.markdown b/source/_docs/ecosystem/ios/notifications/architecture.markdown similarity index 100% rename from source/_docs/ios/notifications/architecture.markdown rename to source/_docs/ecosystem/ios/notifications/architecture.markdown diff --git a/source/_docs/ios/notifications/attachments.markdown b/source/_docs/ecosystem/ios/notifications/attachments.markdown similarity index 100% rename from source/_docs/ios/notifications/attachments.markdown rename to source/_docs/ecosystem/ios/notifications/attachments.markdown diff --git a/source/_docs/ios/notifications/basic.markdown b/source/_docs/ecosystem/ios/notifications/basic.markdown similarity index 100% rename from source/_docs/ios/notifications/basic.markdown rename to source/_docs/ecosystem/ios/notifications/basic.markdown diff --git a/source/_docs/ios/notifications/content_extensions.markdown b/source/_docs/ecosystem/ios/notifications/content_extensions.markdown similarity index 100% rename from source/_docs/ios/notifications/content_extensions.markdown rename to source/_docs/ecosystem/ios/notifications/content_extensions.markdown diff --git a/source/_docs/ios/notifications/privacy_security_rate_limits.markdown b/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown similarity index 100% rename from source/_docs/ios/notifications/privacy_security_rate_limits.markdown rename to source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown diff --git a/source/_docs/ios/notifications/requesting_location_updates.markdown b/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown similarity index 100% rename from source/_docs/ios/notifications/requesting_location_updates.markdown rename to source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown diff --git a/source/_docs/ios/notifications/sounds.markdown b/source/_docs/ecosystem/ios/notifications/sounds.markdown similarity index 100% rename from source/_docs/ios/notifications/sounds.markdown rename to source/_docs/ecosystem/ios/notifications/sounds.markdown diff --git a/source/_docs/ios/requirements.markdown b/source/_docs/ecosystem/ios/requirements.markdown similarity index 100% rename from source/_docs/ios/requirements.markdown rename to source/_docs/ecosystem/ios/requirements.markdown diff --git a/source/_docs/mqtt.markdown b/source/_docs/ecosystem/mqtt.markdown similarity index 100% rename from source/_docs/mqtt.markdown rename to source/_docs/ecosystem/mqtt.markdown diff --git a/source/_docs/mqtt/birth_will.markdown b/source/_docs/ecosystem/mqtt/birth_will.markdown similarity index 100% rename from source/_docs/mqtt/birth_will.markdown rename to source/_docs/ecosystem/mqtt/birth_will.markdown diff --git a/source/_docs/mqtt/broker.markdown b/source/_docs/ecosystem/mqtt/broker.markdown similarity index 100% rename from source/_docs/mqtt/broker.markdown rename to source/_docs/ecosystem/mqtt/broker.markdown diff --git a/source/_docs/mqtt/certificate.markdown b/source/_docs/ecosystem/mqtt/certificate.markdown similarity index 100% rename from source/_docs/mqtt/certificate.markdown rename to source/_docs/ecosystem/mqtt/certificate.markdown diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/ecosystem/mqtt/discovery.markdown similarity index 100% rename from source/_docs/mqtt/discovery.markdown rename to source/_docs/ecosystem/mqtt/discovery.markdown diff --git a/source/_docs/mqtt/logging.markdown b/source/_docs/ecosystem/mqtt/logging.markdown similarity index 100% rename from source/_docs/mqtt/logging.markdown rename to source/_docs/ecosystem/mqtt/logging.markdown diff --git a/source/_docs/mqtt/processing_json.markdown b/source/_docs/ecosystem/mqtt/processing_json.markdown similarity index 100% rename from source/_docs/mqtt/processing_json.markdown rename to source/_docs/ecosystem/mqtt/processing_json.markdown diff --git a/source/_docs/mqtt/service.markdown b/source/_docs/ecosystem/mqtt/service.markdown similarity index 100% rename from source/_docs/mqtt/service.markdown rename to source/_docs/ecosystem/mqtt/service.markdown diff --git a/source/_docs/mqtt/testing.markdown b/source/_docs/ecosystem/mqtt/testing.markdown similarity index 100% rename from source/_docs/mqtt/testing.markdown rename to source/_docs/ecosystem/mqtt/testing.markdown From d5767611154e4c1eefd0498e34b83b17a4628f65 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 17 Feb 2017 08:15:05 +0100 Subject: [PATCH 38/51] Fix permission --- source/_docs/ecosystem/appdaemon.markdown | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 source/_docs/ecosystem/appdaemon.markdown diff --git a/source/_docs/ecosystem/appdaemon.markdown b/source/_docs/ecosystem/appdaemon.markdown old mode 100755 new mode 100644 From 0a1786f0516487f92e97dac930958e0b89421e31 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Fri, 17 Feb 2017 08:24:39 +0100 Subject: [PATCH 39/51] Update navigation --- source/_includes/asides/docs_navigation.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 62661e4d2e3e..c9f68be63cbd 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -110,7 +110,7 @@

    Topics

  • - Ecosystem + {% active_link /docs/ecosystem/ Ecosystem %}
    • {% active_link /docs/autostart/ Autostart %} From e7a46c63cc0bfc6f8a329843d63f9668cb7c7fe1 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 20 Feb 2017 22:39:47 +0100 Subject: [PATCH 40/51] Remove collection --- _config.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/_config.yml b/_config.yml index 644ca3e00ff2..233124d6ce05 100644 --- a/_config.yml +++ b/_config.yml @@ -73,8 +73,6 @@ collections: output: true cookbook: output: true - docs: - output: true # ----------------------- # # 3rd Party Settings # From aea29ffbfa92d2935bf6ee50320cab3371c99291 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 20 Feb 2017 23:10:28 +0100 Subject: [PATCH 41/51] Move overview to right folder --- source/_docs/{ => ecosystem}/notebooks.markdown | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/_docs/{ => ecosystem}/notebooks.markdown (100%) diff --git a/source/_docs/notebooks.markdown b/source/_docs/ecosystem/notebooks.markdown similarity index 100% rename from source/_docs/notebooks.markdown rename to source/_docs/ecosystem/notebooks.markdown From 4f5a6d9117700a49451ac2e1ce5e884d8e8d1afd Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 20 Feb 2017 23:12:15 +0100 Subject: [PATCH 42/51] Move mqtt to upper level --- source/_docs/{ecosystem => }/mqtt.markdown | 0 source/_docs/{ecosystem => }/mqtt/birth_will.markdown | 0 source/_docs/{ecosystem => }/mqtt/broker.markdown | 0 source/_docs/{ecosystem => }/mqtt/certificate.markdown | 0 source/_docs/{ecosystem => }/mqtt/discovery.markdown | 0 source/_docs/{ecosystem => }/mqtt/logging.markdown | 0 source/_docs/{ecosystem => }/mqtt/processing_json.markdown | 0 source/_docs/{ecosystem => }/mqtt/service.markdown | 0 source/_docs/{ecosystem => }/mqtt/testing.markdown | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename source/_docs/{ecosystem => }/mqtt.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/birth_will.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/broker.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/certificate.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/discovery.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/logging.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/processing_json.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/service.markdown (100%) rename source/_docs/{ecosystem => }/mqtt/testing.markdown (100%) diff --git a/source/_docs/ecosystem/mqtt.markdown b/source/_docs/mqtt.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt.markdown rename to source/_docs/mqtt.markdown diff --git a/source/_docs/ecosystem/mqtt/birth_will.markdown b/source/_docs/mqtt/birth_will.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/birth_will.markdown rename to source/_docs/mqtt/birth_will.markdown diff --git a/source/_docs/ecosystem/mqtt/broker.markdown b/source/_docs/mqtt/broker.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/broker.markdown rename to source/_docs/mqtt/broker.markdown diff --git a/source/_docs/ecosystem/mqtt/certificate.markdown b/source/_docs/mqtt/certificate.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/certificate.markdown rename to source/_docs/mqtt/certificate.markdown diff --git a/source/_docs/ecosystem/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/discovery.markdown rename to source/_docs/mqtt/discovery.markdown diff --git a/source/_docs/ecosystem/mqtt/logging.markdown b/source/_docs/mqtt/logging.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/logging.markdown rename to source/_docs/mqtt/logging.markdown diff --git a/source/_docs/ecosystem/mqtt/processing_json.markdown b/source/_docs/mqtt/processing_json.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/processing_json.markdown rename to source/_docs/mqtt/processing_json.markdown diff --git a/source/_docs/ecosystem/mqtt/service.markdown b/source/_docs/mqtt/service.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/service.markdown rename to source/_docs/mqtt/service.markdown diff --git a/source/_docs/ecosystem/mqtt/testing.markdown b/source/_docs/mqtt/testing.markdown similarity index 100% rename from source/_docs/ecosystem/mqtt/testing.markdown rename to source/_docs/mqtt/testing.markdown From ea601a3f06193dec648a7032f008abb94a39787c Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 20 Feb 2017 23:31:46 +0100 Subject: [PATCH 43/51] Move notebook to ecosystem --- source/_docs/{ => ecosystem}/notebooks/api.markdown | 0 source/_docs/{ => ecosystem}/notebooks/database.markdown | 0 source/_docs/{ => ecosystem}/notebooks/graph.markdown | 0 source/_docs/{ => ecosystem}/notebooks/installation.markdown | 0 source/_docs/{ => ecosystem}/notebooks/stats.markdown | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename source/_docs/{ => ecosystem}/notebooks/api.markdown (100%) rename source/_docs/{ => ecosystem}/notebooks/database.markdown (100%) rename source/_docs/{ => ecosystem}/notebooks/graph.markdown (100%) rename source/_docs/{ => ecosystem}/notebooks/installation.markdown (100%) rename source/_docs/{ => ecosystem}/notebooks/stats.markdown (100%) diff --git a/source/_docs/notebooks/api.markdown b/source/_docs/ecosystem/notebooks/api.markdown similarity index 100% rename from source/_docs/notebooks/api.markdown rename to source/_docs/ecosystem/notebooks/api.markdown diff --git a/source/_docs/notebooks/database.markdown b/source/_docs/ecosystem/notebooks/database.markdown similarity index 100% rename from source/_docs/notebooks/database.markdown rename to source/_docs/ecosystem/notebooks/database.markdown diff --git a/source/_docs/notebooks/graph.markdown b/source/_docs/ecosystem/notebooks/graph.markdown similarity index 100% rename from source/_docs/notebooks/graph.markdown rename to source/_docs/ecosystem/notebooks/graph.markdown diff --git a/source/_docs/notebooks/installation.markdown b/source/_docs/ecosystem/notebooks/installation.markdown similarity index 100% rename from source/_docs/notebooks/installation.markdown rename to source/_docs/ecosystem/notebooks/installation.markdown diff --git a/source/_docs/notebooks/stats.markdown b/source/_docs/ecosystem/notebooks/stats.markdown similarity index 100% rename from source/_docs/notebooks/stats.markdown rename to source/_docs/ecosystem/notebooks/stats.markdown From 41ca677d9b4ad4b49460936e68d95405946e37c8 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 09:28:33 +0100 Subject: [PATCH 44/51] Remove un-used files --- source/_docs/ecosystem/ios/features.markdown | 12 ------------ source/_docs/ecosystem/ios/requirements.markdown | 14 -------------- 2 files changed, 26 deletions(-) delete mode 100644 source/_docs/ecosystem/ios/features.markdown delete mode 100644 source/_docs/ecosystem/ios/requirements.markdown diff --git a/source/_docs/ecosystem/ios/features.markdown b/source/_docs/ecosystem/ios/features.markdown deleted file mode 100644 index 895a6a25311c..000000000000 --- a/source/_docs/ecosystem/ios/features.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: page -title: "Features" -description: "Describes the features of Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -Coming soon diff --git a/source/_docs/ecosystem/ios/requirements.markdown b/source/_docs/ecosystem/ios/requirements.markdown deleted file mode 100644 index 89e89e6dcbbf..000000000000 --- a/source/_docs/ecosystem/ios/requirements.markdown +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: page -title: "Requirements" -description: "Basic requirements to use Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -* 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. From dace65af80fcba3fa6e079d2e4cf2b1781af40ff Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 10:21:40 +0100 Subject: [PATCH 45/51] Add one more rectangle for iOS --- source/docs/index.markdown | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/docs/index.markdown b/source/docs/index.markdown index 83eae518e335..4c743e1b1210 100644 --- a/source/docs/index.markdown +++ b/source/docs/index.markdown @@ -7,7 +7,6 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true --- The documentation covers from beginner to advanced topic around the installation, the setup, the configuration, and the usage of Home Assistant. @@ -37,12 +36,18 @@ The documentation covers from beginner to advanced topic around the installation
      MQTT
      - +
      HADashboard
       + +
      + +
      +
      iOS
      +
      From 2e3a6760bc49566ba58cce4dc207e5be13f47fee Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:14:29 +0100 Subject: [PATCH 46/51] Move two parts back from docs and rename Run step --- .../tutorial.markdown => getting-started/automation-2.markdown} | 0 .../configuration => getting-started}/presence-detection.markdown | 0 source/getting-started/{run.markdown => use.markdown} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename source/{_docs/automation/tutorial.markdown => getting-started/automation-2.markdown} (100%) rename source/{_docs/configuration => getting-started}/presence-detection.markdown (100%) rename source/getting-started/{run.markdown => use.markdown} (100%) diff --git a/source/_docs/automation/tutorial.markdown b/source/getting-started/automation-2.markdown similarity index 100% rename from source/_docs/automation/tutorial.markdown rename to source/getting-started/automation-2.markdown diff --git a/source/_docs/configuration/presence-detection.markdown b/source/getting-started/presence-detection.markdown similarity index 100% rename from source/_docs/configuration/presence-detection.markdown rename to source/getting-started/presence-detection.markdown diff --git a/source/getting-started/run.markdown b/source/getting-started/use.markdown similarity index 100% rename from source/getting-started/run.markdown rename to source/getting-started/use.markdown From d4f00d347a5dbeda4f9830f4e38c37b2755b884c Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:15:52 +0100 Subject: [PATCH 47/51] Remove colon --- source/getting-started/use.markdown | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/source/getting-started/use.markdown b/source/getting-started/use.markdown index ac2b054cc1ae..75cc86d8b10c 100644 --- a/source/getting-started/use.markdown +++ b/source/getting-started/use.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Run Home Assistant" -description: "Instructions about how you can run Home Assistant." +title: "Manage Home Assistant" +description: "Instructions about how to manage Home Assistant." date: 2016-09-26 21:00 sidebar: true comments: false @@ -11,12 +11,16 @@ footer: true If you are using Hassbian, browse to [http://hassbian.local:8123](http://hassbian.local:8123) to open the Home Assistant frontend. -For a standard installation the command shown below starts Home Assistant and serves the frontend at [http://IP_ADDRESS:8123](http://IP_ADDRESS:8123). +To reload your configuration, [login](/docs/hassbian/common-tasks/#login-to-the-raspberry-pi) your Raspberry Pi ```bash -$ hass +$ ssh pi@ip-address-of-pi ``` -To see what Home Assistant can do, launch the demo mode: `hass --demo-mode`. +and [restart](/docs/hassbian/common-tasks/#startstoprestart-home-assistant) Home Assistant + +```bash +$ sudo systemctl restart home-assistant@homeassistant.service +``` For tweaking your Home Assistant setup, take a look at the [documentation](/docs/), ask your questions in our [forum](https://community.home-assistant.io/), join us for a [chat](https://gitter.im/home-assistant/home-assistant), or report your [issues](https://github.com/home-assistant/home-assistant/issues). From 363052a3d848e533b6de24919686260b12f387b2 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:16:40 +0100 Subject: [PATCH 48/51] update getting-started section --- source/getting-started/automation-2.markdown | 20 ++++++++----------- source/getting-started/automation.markdown | 4 ++-- source/getting-started/configuration.markdown | 2 +- .../presence-detection.markdown | 2 ++ 4 files changed, 13 insertions(+), 15 deletions(-) diff --git a/source/getting-started/automation-2.markdown b/source/getting-started/automation-2.markdown index 06276c9dcfbb..71c32304f8da 100644 --- a/source/getting-started/automation-2.markdown +++ b/source/getting-started/automation-2.markdown @@ -1,17 +1,18 @@ --- layout: page -title: "Your First Automation" -description: "Step by step guiding through making your first automation." +title: "Your second Automation" +description: "Step by step guiding through making your second automation." date: 2016-04-24 08:30 +0100 sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-create-first/ --- -Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets** +After the scratch on the Automation surface, let's dive deeper and create the automation rule: **Turn on the lights when the sun sets** -In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. +We are defining a [trigger](/docs/automation/trigger/) to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. ```yaml # Example configuration.yaml entry @@ -28,7 +29,7 @@ automation: Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when Home Assistant starts set `initial_state:` to `False`. -After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home. +After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a [condition](/docs/automation/condition/) to only turn on the lights if anyone is home. ```yaml # Example configuration.yaml entry @@ -78,7 +79,7 @@ automation: Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights! -We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. +We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our [action](/docs/automation/action/). We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. ```yaml # Example configuration.yaml entry @@ -104,10 +105,5 @@ automation: entity_id: group.living_room ``` -### {% linkable_title Learn more %} - - - [Triggers](/docs/automation/trigger/) - - [Conditions](/docs/automation/condition/) - - [Actions](/docs/automation/action/) - - [Templating](/docs/automation/templating/) (advanced) +### [Next step: Presence detection »](/getting-started/presence-detection/) diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index a4ea79f91c3f..31812056d94c 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -26,6 +26,6 @@ automation: message: "Sensor value greater than 10" ``` -For further details about automation, please take a look at the [automation tutorial](/docs/automation/tutorial/) to get started with full-speed or the [automation documentation](/docs/automation/). +For further details about automation, please take the next step or the [automation documentation](/docs/automation/). -### [Next step: Run Home Assistant »](/getting-started/run/) +### [Next step: Home Assistant Automation Part 2 »](/getting-started/automation-2/) diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index 579435241f70..fa8d70c03610 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -20,7 +20,7 @@ sensor: - platform: random ``` -The [Setting up devices part](/docs/configuration/devices/) of the documentation additional details about adding device and services and [customizization](docs/configuration/customizing-devices/). +The [Setting up devices part](/docs/configuration/devices/) contains of the documentation additional details about adding device and services and [customizization](docs/configuration/customizing-devices/). For further details about configuration, please take a look at the [configuration documentation](/docs/configuration/). diff --git a/source/getting-started/presence-detection.markdown b/source/getting-started/presence-detection.markdown index 63050fdf19ad..b3956b7213a9 100644 --- a/source/getting-started/presence-detection.markdown +++ b/source/getting-started/presence-detection.markdown @@ -51,3 +51,5 @@ Home Assistant will know the location of your device if you are using OwnTracks. [trigger]: /getting-started/automation-trigger/#zone-trigger [condition]: /getting-started/automation-condition/#zone-condition +### [Next step: Use Home Assistant »](/getting-started/use/) + From 736c529d889ed2e9596bf300dda38801693ce15c Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:19:15 +0100 Subject: [PATCH 49/51] Add redirect --- source/_docs/automation.markdown | 4 ++-- source/_docs/automation/action.markdown | 10 ++++----- source/_docs/automation/condition.markdown | 4 ++-- source/_docs/automation/examples.markdown | 3 +++ source/_docs/automation/templating.markdown | 5 +++-- source/_docs/automation/trigger.markdown | 1 + .../_docs/automation/troubleshooting.markdown | 1 + source/_docs/autostart.markdown | 10 +++++---- source/_docs/autostart/init.d.markdown | 17 ++++++++------- source/_docs/autostart/macos.markdown | 1 + source/_docs/autostart/synology.markdown | 1 + source/_docs/autostart/systemd.markdown | 5 +++-- source/_docs/backend/database.markdown | 1 + source/_docs/backend/updater.markdown | 1 + source/_docs/configuration/basic.markdown | 1 + .../customizing-devices.markdown | 1 + source/_docs/configuration/devices.markdown | 1 + source/_docs/configuration/events.markdown | 1 + .../configuration/group_visibility.markdown | 1 + source/_docs/configuration/packages.markdown | 1 + .../configuration/platform_options.markdown | 1 + source/_docs/configuration/remote.markdown | 1 + source/_docs/configuration/secrets.markdown | 1 + source/_docs/configuration/securing.markdown | 1 + .../splitting_configuration.markdown | 1 + .../_docs/configuration/state_object.markdown | 1 + .../_docs/configuration/templating.markdown | 1 + .../configuration/troubleshooting.markdown | 1 + source/_docs/configuration/yaml.markdown | 1 + source/_docs/ecosystem/appdaemon.markdown | 7 +++---- source/_docs/ecosystem/appdaemon/api.markdown | 2 +- .../appdaemon/configuration.markdown | 2 +- .../ecosystem/appdaemon/example_apps.markdown | 4 ++-- .../ecosystem/appdaemon/installation.markdown | 2 +- .../ecosystem/appdaemon/operation.markdown | 2 +- .../_docs/ecosystem/appdaemon/reboot.markdown | 2 +- .../ecosystem/appdaemon/running.markdown | 2 +- .../ecosystem/appdaemon/tutorial.markdown | 2 +- .../ecosystem/appdaemon/updating.markdown | 2 +- .../ecosystem/appdaemon/windows.markdown | 2 +- source/_docs/ecosystem/hadashboard.markdown | 1 + .../hadashboard/dash_config.markdown | 1 + .../ecosystem/hadashboard/hapush.markdown | 1 + .../hadashboard/installation.markdown | 1 + .../ecosystem/hadashboard/reboot.markdown | 1 + .../ecosystem/hadashboard/updating.markdown | 1 + source/_docs/ecosystem/ios.markdown | 1 + .../_docs/ecosystem/ios/integration.markdown | 1 + source/_docs/ecosystem/ios/location.markdown | 1 + .../ecosystem/ios/notifications.markdown | 1 + .../ios/notifications/actions.markdown | 1 + .../ios/notifications/architecture.markdown | 1 + .../ios/notifications/attachments.markdown | 1 + .../ios/notifications/basic.markdown | 1 + .../notifications/content_extensions.markdown | 1 + .../privacy_security_rate_limits.markdown | 1 + .../requesting_location_updates.markdown | 1 + .../ios/notifications/sounds.markdown | 1 + source/_docs/ecosystem/nginx.markdown | 7 ++++--- source/_docs/ecosystem/notebooks.markdown | 1 + source/_docs/ecosystem/notebooks/api.markdown | 1 + .../ecosystem/notebooks/database.markdown | 1 + .../_docs/ecosystem/notebooks/graph.markdown | 1 + .../ecosystem/notebooks/installation.markdown | 1 + .../_docs/ecosystem/notebooks/stats.markdown | 1 + source/_docs/ecosystem/scenegen.markdown | 1 + source/_docs/ecosystem/synology.markdown | 1 + source/_docs/frontend/browsers.markdown | 1 + source/_docs/frontend/mobile.markdown | 2 +- source/_docs/frontend/webserver.markdown | 1 + source/_docs/hassbian.markdown | 3 ++- source/_docs/hassbian/common-tasks.markdown | 1 + source/_docs/hassbian/customization.markdown | 1 + source/_docs/hassbian/integrations.markdown | 1 + source/_docs/hassbian/upgrading.markdown | 1 + source/_docs/installation.markdown | 1 + source/_docs/installation/docker.markdown | 21 ++++++++++++------- source/_docs/installation/python.markdown | 3 ++- .../raspberry-pi-all-in-one.markdown | 1 + .../_docs/installation/raspberry-pi.markdown | 1 + source/_docs/installation/synology.markdown | 1 + .../installation/troubleshooting.markdown | 1 + source/_docs/installation/updating.markdown | 1 + source/_docs/installation/vagrant.markdown | 3 ++- source/_docs/installation/virtualenv.markdown | 1 + source/_docs/mqtt/broker.markdown | 1 + source/_docs/mqtt/discovery.markdown | 1 + source/_docs/mqtt/logging.markdown | 1 + source/_docs/mqtt/processing_json.markdown | 1 + source/_docs/mqtt/service.markdown | 1 + source/_docs/mqtt/testing.markdown | 1 + source/_docs/scripts.markdown | 1 + source/_docs/scripts/conditions.markdown | 1 + source/_docs/scripts/service-calls.markdown | 1 + source/_docs/z-wave.markdown | 1 + source/_docs/z-wave/controllers.markdown | 1 + source/_docs/z-wave/device-specific.markdown | 11 +++++++--- source/_docs/z-wave/settings.markdown | 1 + 98 files changed, 151 insertions(+), 58 deletions(-) diff --git a/source/_docs/automation.markdown b/source/_docs/automation.markdown index 5c5497b0a132..ceb424df6643 100644 --- a/source/_docs/automation.markdown +++ b/source/_docs/automation.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Home Assistant offers a wide range of automation configurations. In the next few pages, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][/cookbook/#example-configurationyaml]. +Home Assistant offers a wide range of automation configurations. In this section, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][/cookbook/#example-configurationyaml]. ### {% linkable_title Automation basics %} @@ -21,7 +21,7 @@ Before you can go ahead and create your own automations, it's important to learn (action) Turn the lights in the living room on ``` -The example consists of three different parts: a trigger, a condition and an action. +The example consists of three different parts: a [trigger](/docs/automation/trigger/), a [condition](/docs/automation/condition/) and an [action](/docs/automation/action/). The first line is the **trigger** of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'. diff --git a/source/_docs/automation/action.markdown b/source/_docs/automation/action.markdown index 485e3514f422..87295918ac52 100644 --- a/source/_docs/automation/action.markdown +++ b/source/_docs/automation/action.markdown @@ -7,14 +7,12 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-action/ --- -The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax] which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness). +The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax](/docs/scripts/) which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness). -You can also call the service to activate [a scene] which will allow you to define how you want your devices to be and have Home Assistant call the right services. - -[script syntax]: /getting-started/scripts/ -[a scene]: /components/scene/ +You can also call the service to activate [a scene](/components/scene/) which will allow you to define how you want your devices to be and have Home Assistant call the right services. ```yaml automation: @@ -69,4 +67,4 @@ automation: value_template: '{% raw %}{{ states.sensor.sensorluz_7_0.state < 10 }}{% endraw %}' - service: scene.turn_on entity_id: scene.DespiertaDespacho -``` \ No newline at end of file +``` diff --git a/source/_docs/automation/condition.markdown b/source/_docs/automation/condition.markdown index 5105ff7e94f0..78f396fa670f 100644 --- a/source/_docs/automation/condition.markdown +++ b/source/_docs/automation/condition.markdown @@ -7,11 +7,12 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-condition/ --- Conditions are an optional part of an automation rule and can be used to prevent an action from happening when triggered. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off. -The available conditions for an automation are the same as for the script syntax so see that page for a [full list of available conditions][script-condition]. +The available conditions for an automation are the same as for the script syntax so see that page for a [full list of available conditions](/docs/scripts/conditions/). Example of using condition: @@ -33,4 +34,3 @@ Example of using condition: entity_id: scene.DespiertaDespacho ``` -[script-condition]: /getting-started/scripts-conditions/ diff --git a/source/_docs/automation/examples.markdown b/source/_docs/automation/examples.markdown index ef7eea40ca7a..941e7a978956 100644 --- a/source/_docs/automation/examples.markdown +++ b/source/_docs/automation/examples.markdown @@ -7,8 +7,11 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-examples/ --- +Just some sample automation rules to get you started. + ```yaml # Example of entry in configuration.yaml automation: diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown index 5e30fe2bdeb3..e1c085ea738b 100644 --- a/source/_docs/automation/templating.markdown +++ b/source/_docs/automation/templating.markdown @@ -7,11 +7,12 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-templating/ --- In Home Assistant 0.19 we introduced a new powerful feature: variables in scripts and automations. This makes it possible to adjust your condition and action based on the information of the trigger. -The trigger data made is available during [template](/topics/templating/) rendering as the `trigger` variable. +The trigger data made is available during [template](/configuration/templating/) rendering as the `trigger` variable. ```yaml # Example configuration.yaml entries @@ -127,4 +128,4 @@ The following tables show the available trigger data per platform. | `trigger.zone` | State object of zone | `trigger.event` | Event that trigger observed: `enter` or `leave`. -[state object]: /topics/state_object/ +[state object]: /configuration/state_object/ diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index d6e15fa263a9..0f5b73551393 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-trigger/ --- Triggers are what starts the processing of an automation rule. It is possible to specify multiple triggers for the same rule. Once a trigger starts, Home Assistant will validate the conditions, if any, and call the action. diff --git a/source/_docs/automation/troubleshooting.markdown b/source/_docs/automation/troubleshooting.markdown index feb82dab9f64..5207175e2583 100644 --- a/source/_docs/automation/troubleshooting.markdown +++ b/source/_docs/automation/troubleshooting.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-troubleshooting/ --- You can verify that your automation rules are being initialized correctly by watching both the realtime logs (`homeassistant.log` in the configuration directory) and also the [Logbook](/components/logbook/). The realtime logs will show the rules being initialized (once for each trigger), example: diff --git a/source/_docs/autostart.markdown b/source/_docs/autostart.markdown index 34951c2c957b..95e9608adc8f 100644 --- a/source/_docs/autostart.markdown +++ b/source/_docs/autostart.markdown @@ -7,11 +7,13 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/autostart/ --- Once you get started with Home Assistant you want it to start automatically when you launch your machine. To help you get started we've compiled a few guides for different systems. - - [Linux - systemd](/getting-started/autostart-systemd/) - - [Linux - Upstart](/getting-started/autostart-upstart/) - - [macOS](/getting-started/autostart-macos/) - - [Synology NAS](/getting-started/autostart-synology/) + - [systemd (Linux)](/docs/autostart/systemd/) + - [Upstart (Linux)](/docs/autostart/upstart/) + - [init.d (Linux)](/docs/autostart/init.d/) + - [macOS](/docs/autostart/macos/) + - [Synology NAS](/docs/autostart/synology/) diff --git a/source/_docs/autostart/init.d.markdown b/source/_docs/autostart/init.d.markdown index 27bd44f8d413..abe1ccb6ff14 100644 --- a/source/_docs/autostart/init.d.markdown +++ b/source/_docs/autostart/init.d.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/autostart-init.d/ --- Home Assistant can run as a daemon within init.d with the script below. @@ -17,8 +18,8 @@ Copy the script at the end of this page to `/etc/init.d/hass-daemon`. After that, set the script to be executable: -``` -sudo chmod +x /etc/init.d/hass-daemon +```bash +$ sudo chmod +x /etc/init.d/hass-daemon ``` ### {% linkable_title 2. Select a user. %} @@ -27,14 +28,14 @@ Create or pick a user that the Home Assistant daemon will run under. Update scri ### {% linkable_title 3. Register the daemon with Linux %} -``` -sudo update-rc.d hass-daemon defaults +```bash +$ sudo update-rc.d hass-daemon defaults ``` ### {% linkable_title 4. Install this service %} -``` -sudo service hass-daemon install +```bash +$ sudo service hass-daemon install ``` ### {% linkable_title 5. Restart Machine %} @@ -49,7 +50,7 @@ If any commands need to run before executing hass (like loading a virutal enviro ### {% linkable_title Daemon script %} -``` +```bash #!/bin/sh ### BEGIN INIT INFO # Provides: hass @@ -134,4 +135,4 @@ case "$1" in *) echo "Usage: $0 {start|stop|restart|install|uninstall}" esac -``` \ No newline at end of file +``` diff --git a/source/_docs/autostart/macos.markdown b/source/_docs/autostart/macos.markdown index d0c5798665e0..0a1b6ea13488 100644 --- a/source/_docs/autostart/macos.markdown +++ b/source/_docs/autostart/macos.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/autostart-macos/ --- Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant on boot and make sure it's always running. diff --git a/source/_docs/autostart/synology.markdown b/source/_docs/autostart/synology.markdown index f41bd1277f06..38dfded8ece9 100644 --- a/source/_docs/autostart/synology.markdown +++ b/source/_docs/autostart/synology.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/autostart-synology/ --- To get Home Assistant to automatically start when you boot your Synology NAS: diff --git a/source/_docs/autostart/systemd.markdown b/source/_docs/autostart/systemd.markdown index c9a94abbbcc4..ff3289246264 100644 --- a/source/_docs/autostart/systemd.markdown +++ b/source/_docs/autostart/systemd.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/autostart-systemd/ --- Newer linux distributions are trending towards using `systemd` for managing daemons. Typically, systems based on Fedora, ArchLinux, or Debian (8 or later) use `systemd`. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using `systemd`, you may check with the following command: @@ -20,7 +21,7 @@ If the preceding command returns the string `systemd`, you are likely using `sys If you want Home Assistant to be launched automatically, an extra step is needed to setup `systemd`. You need a service file to control Home Assistant with `systemd`. If you are using a Raspberry Pi with Raspbian then replace the `[your user]` with `pi` otherwise use your user you want to run Home Assistant. `ExecStart` contains the path to `hass` and this may vary. Check with `whereis hass` for the location. ```bash -$ su -c 'cat <> /etc/systemd/system/home-assistant@[your user].service +$ su -c 'cat <> /etc/systemd/system/home-assistant@.service [Unit] Description=Home Assistant After=network.target @@ -45,7 +46,7 @@ After=network.target [Service] Type=simple User=homeassistant -#make sure the virtualenv python binary is used +# Make sure the virtualenv Python binary is used Environment=VIRTUAL_ENV="/srv/homeassistant" Environment=PATH="$VIRTUAL_ENV/bin:$PATH" ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant" diff --git a/source/_docs/backend/database.markdown b/source/_docs/backend/database.markdown index 653be34c40a9..9fe42de98663 100644 --- a/source/_docs/backend/database.markdown +++ b/source/_docs/backend/database.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /details/database/ --- The default database that is used for Home Assistant is [SQLite](https://www.sqlite.org/) and is stored in your [configuration directory](/getting-started/configuration/), eg. `/.homeassistant/home-assistant_v2.db`. You will need an installation of `sqlite3`, the command-line for SQLite database, or [DB Browser for SQLite](http://sqlitebrowser.org/) which provide an editor for executing SQL commands. diff --git a/source/_docs/backend/updater.markdown b/source/_docs/backend/updater.markdown index d2c15d531fb0..dcdb3cb54331 100644 --- a/source/_docs/backend/updater.markdown +++ b/source/_docs/backend/updater.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /details/updater/ --- Starting with 0.31 the [updater component](/components/updater/) sends an optional report about Home Assistant instance. diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index 21cfcbeee7c2..4af7df1a3501 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/basic/ --- By default, Home Assistant will try to detect your location from IP address geolocation. Home Assistant will automatically select a temperature unit and time zone based on this location. You can overwrite this by adding the following information to your `configuration.yaml`: diff --git a/source/_docs/configuration/customizing-devices.markdown b/source/_docs/configuration/customizing-devices.markdown index 15cc891f9985..e1b65217fd89 100644 --- a/source/_docs/configuration/customizing-devices.markdown +++ b/source/_docs/configuration/customizing-devices.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/customizing-devices/ --- By default, all of your devices will be visible and have a default icon determined by their domain. You can customize the look and feel of your front page by altering some of these parameters. This can be done by overriding attributes of specific entities. diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown index 2a1f912e929b..76b4f82447e2 100644 --- a/source/_docs/configuration/devices.markdown +++ b/source/_docs/configuration/devices.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/devices/ --- Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component](/components/discovery/) enabled (the default setting). diff --git a/source/_docs/configuration/events.markdown b/source/_docs/configuration/events.markdown index c5ecaeb5a253..48cb5df1af0c 100644 --- a/source/_docs/configuration/events.markdown +++ b/source/_docs/configuration/events.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/events/ --- The core of Home Assistant is the event bus. The event bus allows any component to fire or listen for events. It is the core of everything. For example, any state change will be announced on the event bus as a `state_changed` event containing the previous and the new state of an entity. diff --git a/source/_docs/configuration/group_visibility.markdown b/source/_docs/configuration/group_visibility.markdown index 2a325fc8d3f0..13c5cf9d7bef 100644 --- a/source/_docs/configuration/group_visibility.markdown +++ b/source/_docs/configuration/group_visibility.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/group_visibility/ --- After filling Home Assistant with all your precious home automation devices, you usually end up with a cluttered interface and lots of groups that are not interesting in your current context. What if you just want to show groups that are interesting _now_ and hide the rest? That's when group visibility comes to play. diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown index dc2dae1482c1..39f231e832d5 100644 --- a/source/_docs/configuration/packages.markdown +++ b/source/_docs/configuration/packages.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/packages/ --- Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/docs/configuration/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/docs/configuration/splitting_configuration). diff --git a/source/_docs/configuration/platform_options.markdown b/source/_docs/configuration/platform_options.markdown index eb8f1300c22e..0d7945d3d10d 100644 --- a/source/_docs/configuration/platform_options.markdown +++ b/source/_docs/configuration/platform_options.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/platform_options/ --- Any component that is based on the entity component allows various extra options to be set per platform. diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown index 7f89ccaab288..273d92c2f959 100644 --- a/source/_docs/configuration/remote.markdown +++ b/source/_docs/configuration/remote.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/basic/#remote-access --- If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible. diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index 325987909710..e3531c2db8ca 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/secrets/ --- The `configuration.yaml` file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. By using `!secrets` you can remove any private information from you configuration files. This separation can also help you to keep easier track of your passwords and API keys. As they are all stored at one place and no longer spread across the `configuration.yaml` file or even multiple yaml files if you [split up your configuration](/topics/splitting_configuration/). diff --git a/source/_docs/configuration/securing.markdown b/source/_docs/configuration/securing.markdown index 9ed36dc13f77..31e3a1fbca7f 100644 --- a/source/_docs/configuration/securing.markdown +++ b/source/_docs/configuration/securing.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/securing/ --- One major advantage of Home Assistant is that it's not dependent on cloud services. Even if you're only using Home Assistant on a local network, you should take steps to secure your instance. diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown index 396a08b76b79..a13b5db7e2e4 100644 --- a/source/_docs/configuration/splitting_configuration.markdown +++ b/source/_docs/configuration/splitting_configuration.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/yaml/ --- So you've been using Home Assistant for a while now and your [configuration.yaml file brings people to tears](https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/) or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: humanly readable) pieces. diff --git a/source/_docs/configuration/state_object.markdown b/source/_docs/configuration/state_object.markdown index d7c3d78aeb75..9659e255241b 100644 --- a/source/_docs/configuration/state_object.markdown +++ b/source/_docs/configuration/state_object.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/state_object/ --- Your devices are represented in Home Assistant as entities. The entities will write their current state to the state machine for other entities/templates/frontend to access. States are a current representation of the entity. diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index a83aee8c3fd5..bb94a2c912ed 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /topics/templating/ --- This is an advanced feature of Home Assistant. You'll need a basic understanding of the following things: diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown index f06c7e17cc85..f16cdb7ab857 100644 --- a/source/_docs/configuration/troubleshooting.markdown +++ b/source/_docs/configuration/troubleshooting.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/troubleshooting-configuration/ --- It can happen that you run into trouble while configuring Home Assistant. Perhaps a component is not showing up or is acting strangely. This page will discuss a few of the most common problems. diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index cce574cddecb..7ce62138fa73 100644 --- a/source/_docs/configuration/yaml.markdown +++ b/source/_docs/configuration/yaml.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/yaml/ --- Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations. diff --git a/source/_docs/ecosystem/appdaemon.markdown b/source/_docs/ecosystem/appdaemon.markdown index 9ec0e87f8e3f..43094211190f 100644 --- a/source/_docs/ecosystem/appdaemon.markdown +++ b/source/_docs/ecosystem/appdaemon.markdown @@ -1,14 +1,13 @@ --- layout: page title: "AppDaemon" -description: "AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant" +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 +redirect_from: /ecosystem/appdaemon/ --- -AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant. \ No newline at end of file +AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant. diff --git a/source/_docs/ecosystem/appdaemon/api.markdown b/source/_docs/ecosystem/appdaemon/api.markdown index 891ef1dec870..5ebe762f1bef 100755 --- a/source/_docs/ecosystem/appdaemon/api.markdown +++ b/source/_docs/ecosystem/appdaemon/api.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true +redirect_from: /ecosystem/appdaemon/api/ --- ## {% linkable_title Anatomy of an App %} diff --git a/source/_docs/ecosystem/appdaemon/configuration.markdown b/source/_docs/ecosystem/appdaemon/configuration.markdown index ec955aff6221..ee497f2d4dda 100644 --- a/source/_docs/ecosystem/appdaemon/configuration.markdown +++ b/source/_docs/ecosystem/appdaemon/configuration.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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: diff --git a/source/_docs/ecosystem/appdaemon/example_apps.markdown b/source/_docs/ecosystem/appdaemon/example_apps.markdown index 2d7b659ad797..bf696f634c49 100644 --- a/source/_docs/ecosystem/appdaemon/example_apps.markdown +++ b/source/_docs/ecosystem/appdaemon/example_apps.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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. \ No newline at end of file +There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them. diff --git a/source/_docs/ecosystem/appdaemon/installation.markdown b/source/_docs/ecosystem/appdaemon/installation.markdown index 6eb9f1f16c50..cd6d1cf4cd99 100644 --- a/source/_docs/ecosystem/appdaemon/installation.markdown +++ b/source/_docs/ecosystem/appdaemon/installation.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true +redirect_from: /ecosystem/appdaemon/installation/ --- Installation is either by `pip3` or Docker. diff --git a/source/_docs/ecosystem/appdaemon/operation.markdown b/source/_docs/ecosystem/appdaemon/operation.markdown index 9f643719a614..536f474aee03 100644 --- a/source/_docs/ecosystem/appdaemon/operation.markdown +++ b/source/_docs/ecosystem/appdaemon/operation.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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. diff --git a/source/_docs/ecosystem/appdaemon/reboot.markdown b/source/_docs/ecosystem/appdaemon/reboot.markdown index 96d7b9552b89..1ccdd8773a99 100644 --- a/source/_docs/ecosystem/appdaemon/reboot.markdown +++ b/source/_docs/ecosystem/appdaemon/reboot.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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. diff --git a/source/_docs/ecosystem/appdaemon/running.markdown b/source/_docs/ecosystem/appdaemon/running.markdown index 78e5cf3976e6..d4006526d6f6 100755 --- a/source/_docs/ecosystem/appdaemon/running.markdown +++ b/source/_docs/ecosystem/appdaemon/running.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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. diff --git a/source/_docs/ecosystem/appdaemon/tutorial.markdown b/source/_docs/ecosystem/appdaemon/tutorial.markdown index bec655b90746..18f25c5b1b6b 100755 --- a/source/_docs/ecosystem/appdaemon/tutorial.markdown +++ b/source/_docs/ecosystem/appdaemon/tutorial.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true +redirect_from: /ecosystem/appdaemon/tutorial/ --- ## {% linkable_title Another Take on Automation %} diff --git a/source/_docs/ecosystem/appdaemon/updating.markdown b/source/_docs/ecosystem/appdaemon/updating.markdown index 20a5ebef141a..8b39e9ccf8bd 100644 --- a/source/_docs/ecosystem/appdaemon/updating.markdown +++ b/source/_docs/ecosystem/appdaemon/updating.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true +redirect_from: /ecosystem/appdaemon/updating/ --- To update AppDaemon after I have released new code, just run the following command to update your copy: diff --git a/source/_docs/ecosystem/appdaemon/windows.markdown b/source/_docs/ecosystem/appdaemon/windows.markdown index 360bf975a122..a903f37f4243 100755 --- a/source/_docs/ecosystem/appdaemon/windows.markdown +++ b/source/_docs/ecosystem/appdaemon/windows.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: 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: diff --git a/source/_docs/ecosystem/hadashboard.markdown b/source/_docs/ecosystem/hadashboard.markdown index 799468d0e6a6..871ec17cda69 100644 --- a/source/_docs/ecosystem/hadashboard.markdown +++ b/source/_docs/ecosystem/hadashboard.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/hadashboard/dash_config.markdown b/source/_docs/ecosystem/hadashboard/dash_config.markdown index 4abc93d3fd88..1436f3fd981d 100755 --- a/source/_docs/ecosystem/hadashboard/dash_config.markdown +++ b/source/_docs/ecosystem/hadashboard/dash_config.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/hadashboard/dash_config/ --- (All installations) diff --git a/source/_docs/ecosystem/hadashboard/hapush.markdown b/source/_docs/ecosystem/hadashboard/hapush.markdown index d390f22f3fc9..6445a12ae3ea 100755 --- a/source/_docs/ecosystem/hadashboard/hapush.markdown +++ b/source/_docs/ecosystem/hadashboard/hapush.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/hadashboard/hapush/ --- # Installing hapush (Manual install only) diff --git a/source/_docs/ecosystem/hadashboard/installation.markdown b/source/_docs/ecosystem/hadashboard/installation.markdown index ecce1549c1b0..0fd3df48efc1 100755 --- a/source/_docs/ecosystem/hadashboard/installation.markdown +++ b/source/_docs/ecosystem/hadashboard/installation.markdown @@ -7,6 +7,7 @@ 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) diff --git a/source/_docs/ecosystem/hadashboard/reboot.markdown b/source/_docs/ecosystem/hadashboard/reboot.markdown index 0d87ef287250..3f912b0268f9 100755 --- a/source/_docs/ecosystem/hadashboard/reboot.markdown +++ b/source/_docs/ecosystem/hadashboard/reboot.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/hadashboard/updating.markdown b/source/_docs/ecosystem/hadashboard/updating.markdown index 96d6f9731bd2..6854a5541511 100755 --- a/source/_docs/ecosystem/hadashboard/updating.markdown +++ b/source/_docs/ecosystem/hadashboard/updating.markdown @@ -7,6 +7,7 @@ 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: diff --git a/source/_docs/ecosystem/ios.markdown b/source/_docs/ecosystem/ios.markdown index 862fce661c42..9a176f006bdf 100644 --- a/source/_docs/ecosystem/ios.markdown +++ b/source/_docs/ecosystem/ios.markdown @@ -7,6 +7,7 @@ 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: diff --git a/source/_docs/ecosystem/ios/integration.markdown b/source/_docs/ecosystem/ios/integration.markdown index e9db1dd875e9..c37e3342458f 100644 --- a/source/_docs/ecosystem/ios/integration.markdown +++ b/source/_docs/ecosystem/ios/integration.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/ios/integration/ --- Home Assistant for iOS supports opening from other apps via URL. diff --git a/source/_docs/ecosystem/ios/location.markdown b/source/_docs/ecosystem/ios/location.markdown index f9bd14bf0a54..ac344227c2b1 100644 --- a/source/_docs/ecosystem/ios/location.markdown +++ b/source/_docs/ecosystem/ios/location.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/ios/location/ --- ## {% linkable_title Location tracking when outside a Home Assistant zone %} diff --git a/source/_docs/ecosystem/ios/notifications.markdown b/source/_docs/ecosystem/ios/notifications.markdown index 49490161de0f..21e393687739 100644 --- a/source/_docs/ecosystem/ios/notifications.markdown +++ b/source/_docs/ecosystem/ios/notifications.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/ios/notifications/actions.markdown b/source/_docs/ecosystem/ios/notifications/actions.markdown index 7cddb7e8aced..5e2f49f3e45e 100644 --- a/source/_docs/ecosystem/ios/notifications/actions.markdown +++ b/source/_docs/ecosystem/ios/notifications/actions.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/ios/notifications/architecture.markdown b/source/_docs/ecosystem/ios/notifications/architecture.markdown index c699e4529989..b7dac74dfb11 100644 --- a/source/_docs/ecosystem/ios/notifications/architecture.markdown +++ b/source/_docs/ecosystem/ios/notifications/architecture.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/ios/notifications/architecture/ ---

      diff --git a/source/_docs/ecosystem/ios/notifications/attachments.markdown b/source/_docs/ecosystem/ios/notifications/attachments.markdown index 639f087b362c..2138ae602d19 100644 --- a/source/_docs/ecosystem/ios/notifications/attachments.markdown +++ b/source/_docs/ecosystem/ios/notifications/attachments.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/ios/notifications/basic.markdown b/source/_docs/ecosystem/ios/notifications/basic.markdown index fbb217edffe8..0400888a2c68 100644 --- a/source/_docs/ecosystem/ios/notifications/basic.markdown +++ b/source/_docs/ecosystem/ios/notifications/basic.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/ios/notifications/content_extensions.markdown b/source/_docs/ecosystem/ios/notifications/content_extensions.markdown index 9279f75d5959..8b9ec5b5053a 100644 --- a/source/_docs/ecosystem/ios/notifications/content_extensions.markdown +++ b/source/_docs/ecosystem/ios/notifications/content_extensions.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown b/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown index ebb0b1462674..f0a60e1af880 100644 --- a/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown +++ b/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/ios/notifications/privacy_security_rate_limits/ --- ## {% linkable_title Privacy %} diff --git a/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown b/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown index f02f63f30e3f..a014cb5334a2 100644 --- a/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown +++ b/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/ios/notifications/requesting_location_updates/ ---

      diff --git a/source/_docs/ecosystem/ios/notifications/sounds.markdown b/source/_docs/ecosystem/ios/notifications/sounds.markdown index cbe35943ad89..7e0a96635237 100644 --- a/source/_docs/ecosystem/ios/notifications/sounds.markdown +++ b/source/_docs/ecosystem/ios/notifications/sounds.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/nginx.markdown b/source/_docs/ecosystem/nginx.markdown index 8d657a500311..b3305a9de347 100644 --- a/source/_docs/ecosystem/nginx.markdown +++ b/source/_docs/ecosystem/nginx.markdown @@ -7,20 +7,21 @@ 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. %} +### {% 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. %} +### {% 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. %} +### {% linkable_title 3. Obtain an SSL certificate %} There are two ways of obtaining an SSL certificate. diff --git a/source/_docs/ecosystem/notebooks.markdown b/source/_docs/ecosystem/notebooks.markdown index 6dfd9a73633a..9cde967703a9 100644 --- a/source/_docs/ecosystem/notebooks.markdown +++ b/source/_docs/ecosystem/notebooks.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/notebooks/api.markdown b/source/_docs/ecosystem/notebooks/api.markdown index bf20faaecb37..11d01248a296 100644 --- a/source/_docs/ecosystem/notebooks/api.markdown +++ b/source/_docs/ecosystem/notebooks/api.markdown @@ -7,6 +7,7 @@ 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). diff --git a/source/_docs/ecosystem/notebooks/database.markdown b/source/_docs/ecosystem/notebooks/database.markdown index 5b0cd3cd5569..afb900c56e86 100644 --- a/source/_docs/ecosystem/notebooks/database.markdown +++ b/source/_docs/ecosystem/notebooks/database.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/notebooks/graph.markdown b/source/_docs/ecosystem/notebooks/graph.markdown index 257d5adf4b94..4fda74e239af 100644 --- a/source/_docs/ecosystem/notebooks/graph.markdown +++ b/source/_docs/ecosystem/notebooks/graph.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/notebooks/installation.markdown b/source/_docs/ecosystem/notebooks/installation.markdown index ffc67af78d24..96997dd06501 100644 --- a/source/_docs/ecosystem/notebooks/installation.markdown +++ b/source/_docs/ecosystem/notebooks/installation.markdown @@ -7,6 +7,7 @@ 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/). diff --git a/source/_docs/ecosystem/notebooks/stats.markdown b/source/_docs/ecosystem/notebooks/stats.markdown index 542d7dbb18c0..c94ccb583b88 100644 --- a/source/_docs/ecosystem/notebooks/stats.markdown +++ b/source/_docs/ecosystem/notebooks/stats.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/scenegen.markdown b/source/_docs/ecosystem/scenegen.markdown index dc62e1621a37..aa512fd18330 100644 --- a/source/_docs/ecosystem/scenegen.markdown +++ b/source/_docs/ecosystem/scenegen.markdown @@ -7,6 +7,7 @@ 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. diff --git a/source/_docs/ecosystem/synology.markdown b/source/_docs/ecosystem/synology.markdown index 93002049f71e..099ea41ef084 100644 --- a/source/_docs/ecosystem/synology.markdown +++ b/source/_docs/ecosystem/synology.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /ecosystem/synology/ --- Synology NAS are the perfect companion to running Home Assistant. diff --git a/source/_docs/frontend/browsers.markdown b/source/_docs/frontend/browsers.markdown index f36be2f2a45f..8ddb3f805b4e 100644 --- a/source/_docs/frontend/browsers.markdown +++ b/source/_docs/frontend/browsers.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/browsers/ --- Home Assistant requires a web browser to show the frontend and supports all major modern browsers. We don't test the web interface against all available browsers but this page tracks different browsers on various operating systems and should help you to pick a browser which works. diff --git a/source/_docs/frontend/mobile.markdown b/source/_docs/frontend/mobile.markdown index 8f3657f838c2..d5537e664b4a 100644 --- a/source/_docs/frontend/mobile.markdown +++ b/source/_docs/frontend/mobile.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -redirect_from: /getting-started/android/ +redirect_from: /getting-started/mobile/ --- Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new W3C [manifest.json](https://w3c.github.io/manifest/) support, allowing mobile devices to add the "web app" to your homescreen as if it was native. diff --git a/source/_docs/frontend/webserver.markdown b/source/_docs/frontend/webserver.markdown index 2fc3d17b3f12..bf4bf1b8b103 100644 --- a/source/_docs/frontend/webserver.markdown +++ b/source/_docs/frontend/webserver.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /details/webserver/ --- It was only a matter of time till the first queries for tools like [https://www.shodan.io](https://www.shodan.io/search?query=Home+Assistant) to search for Home Assistant instances showed up. diff --git a/source/_docs/hassbian.markdown b/source/_docs/hassbian.markdown index d4033ea3f5b8..a9177f3ab1d7 100644 --- a/source/_docs/hassbian.markdown +++ b/source/_docs/hassbian.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian/ --- Hassbian is our customized operating system for the Raspberry Pi 3. It is the easiest way of installing Home Assistant. @@ -16,7 +17,7 @@ Hassbian is our customized operating system for the Raspberry Pi 3. It is the ea - [Pi specific integrations][integrations] - [Learn how to perform common tasks][common] -[install]: /docs/hassbian-installation/ +[install]: /docs/hassbian/installation/ [customize]: /docs/hassbian/customization/ [common]: /docs/hassbian/common-tasks/ [integrations]: /docs/hassbian/integrations/ diff --git a/source/_docs/hassbian/common-tasks.markdown b/source/_docs/hassbian/common-tasks.markdown index 0e5399ae9451..25104502c317 100644 --- a/source/_docs/hassbian/common-tasks.markdown +++ b/source/_docs/hassbian/common-tasks.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-common-tasks/ --- ### {% linkable_title Login to the Raspberry Pi %} diff --git a/source/_docs/hassbian/customization.markdown b/source/_docs/hassbian/customization.markdown index 54a34a2c0704..2c86da09b935 100644 --- a/source/_docs/hassbian/customization.markdown +++ b/source/_docs/hassbian/customization.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-customization/ --- To allow you to customize your installation further, we have included a set of Hassbian scripts. diff --git a/source/_docs/hassbian/integrations.markdown b/source/_docs/hassbian/integrations.markdown index 957b263a6303..122ae0b54eeb 100644 --- a/source/_docs/hassbian/integrations.markdown +++ b/source/_docs/hassbian/integrations.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-installation/ --- Some components that are specific for the Raspberry Pi can require some further configuration outside of Home Assistant. All commands below are assumed to be executed with the `pi` account. For full documentation of these components refer to the [components](/components) page. diff --git a/source/_docs/hassbian/upgrading.markdown b/source/_docs/hassbian/upgrading.markdown index 9c353469f2ba..dff4e81e8d86 100644 --- a/source/_docs/hassbian/upgrading.markdown +++ b/source/_docs/hassbian/upgrading.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-upgrading/ --- HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following. diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown index b85b2ebf9c60..1db05d075783 100644 --- a/source/_docs/installation.markdown +++ b/source/_docs/installation.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation/ --- Home Assistant provides multiple ways to be installed. If you are a Raspberry Pi owner then the [Hassbian](/docs/hassbian/) is an easy and simple way to run home Assistant. diff --git a/source/_docs/installation/docker.markdown b/source/_docs/installation/docker.markdown index 0823ca99163f..ac3bd466f2ba 100644 --- a/source/_docs/installation/docker.markdown +++ b/source/_docs/installation/docker.markdown @@ -7,25 +7,32 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-docker/ --- Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it: +### {% linkable_title Linux %} + ```bash $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant ``` -This will launch Home Assistant and serve the web interface from port 8123 on your Docker host. +### {% linkable_title macOS %} -

      -When using boot2docker on macOS you are unable to map the local time to your Docker container. Replace `-v /etc/localtime:/etc/localtime:ro` with `-e "TZ=America/Los_Angeles"` (replacing America/Los_Angeles with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) +When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10). -

      -If you change the config you have to restart the server. -To do that you have 2 options. +```bash +$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant +``` + +### {% linkable_title Restart %} + +This will launch Home Assistant and serve the web interface from port 8123 on your Docker host. + +If you change the configuration you have to restart the server. To do that you have 2 options. 1. You can go to the service developer tool icon service developer tools, select the service `homeassistant/restart` and click "Call Service". 2. Or you can restart it from an terminal by running `docker restart home-assistant` - diff --git a/source/_docs/installation/python.markdown b/source/_docs/installation/python.markdown index 022fdd0b43b8..e0603a076c17 100644 --- a/source/_docs/installation/python.markdown +++ b/source/_docs/installation/python.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-python/ --- Once Python is installed, execute the following code in a console: @@ -21,7 +22,7 @@ Running these commands will: - Install Home Assistant - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123) -If you're running a Linux-based platform, we suggest you follow the [VirtualEnv instructions][/docs/installation/virtualenv/] to avoid using `root`. +If you're running a Linux-based platform, we suggest you follow the [VirtualEnv instructions](/docs/installation/virtualenv/) to avoid using `root`. Video tutorials of this process for various operating systems are available here: diff --git a/source/_docs/installation/raspberry-pi-all-in-one.markdown b/source/_docs/installation/raspberry-pi-all-in-one.markdown index f2655a4909ee..06e03d6c3367 100644 --- a/source/_docs/installation/raspberry-pi-all-in-one.markdown +++ b/source/_docs/installation/raspberry-pi-all-in-one.markdown @@ -5,6 +5,7 @@ date: 2016-05-12 01:39 comments: false sharing: true footer: true +redirect_from: /getting-started/installation-raspberry-pi-all-in-one/ --- The [Raspberry Pi All-In-One Installer](https://github.com/home-assistant/fabric-home-assistant) deploys a complete Home Assistant server including support for MQTT with websockets, Z-Wave, and the Open-Zwave Control Panel. diff --git a/source/_docs/installation/raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown index 8447f5f2e163..bb899d6c3770 100644 --- a/source/_docs/installation/raspberry-pi.markdown +++ b/source/_docs/installation/raspberry-pi.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-raspberry-pi/ --- This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite. diff --git a/source/_docs/installation/synology.markdown b/source/_docs/installation/synology.markdown index 073bda4ee15b..773476f9bb3b 100644 --- a/source/_docs/installation/synology.markdown +++ b/source/_docs/installation/synology.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-synology/ --- The following configuration has been tested on Synology 413j running DSM 6.0-7321 Update 1. diff --git a/source/_docs/installation/troubleshooting.markdown b/source/_docs/installation/troubleshooting.markdown index e049f2ee3e47..b78544b025ad 100644 --- a/source/_docs/installation/troubleshooting.markdown +++ b/source/_docs/installation/troubleshooting.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/troubleshooting/ --- It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems. diff --git a/source/_docs/installation/updating.markdown b/source/_docs/installation/updating.markdown index 06546d3d2e17..eeb83e0d5afe 100644 --- a/source/_docs/installation/updating.markdown +++ b/source/_docs/installation/updating.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-upgrading/ ---

      diff --git a/source/_docs/installation/vagrant.markdown b/source/_docs/installation/vagrant.markdown index c5251f5c6614..2ab59b2019ee 100644 --- a/source/_docs/installation/vagrant.markdown +++ b/source/_docs/installation/vagrant.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-vagrant/ --- A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them. @@ -60,7 +61,7 @@ To start it again, just run `vagrant up` ## {% linkable_title Restarting Home Assistant process to test changes %} -The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Getting started section](https://home-assistant.io/getting-started/configuration/) for more information about how to configure Home Assistant). +The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Configuration section](/docs/configuration/) in the docmentation for more information about how to configure Home Assistant). Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it: diff --git a/source/_docs/installation/virtualenv.markdown b/source/_docs/installation/virtualenv.markdown index 6bedb6863793..613b3ecd7c4a 100644 --- a/source/_docs/installation/virtualenv.markdown +++ b/source/_docs/installation/virtualenv.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/installation-virtualenv/ --- There are several reasons why it makes sense to run Home Assistant in a virtual environment. A [virtualenv](https://virtualenv.pypa.io/en/latest/) encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant won't interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer won't break Home Assistant, and it means you don't need to install Python packages as root. diff --git a/source/_docs/mqtt/broker.markdown b/source/_docs/mqtt/broker.markdown index 2c84c8b05462..ff1e873e67ac 100644 --- a/source/_docs/mqtt/broker.markdown +++ b/source/_docs/mqtt/broker.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#picking-a-broker --- The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy. diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 509ee420c9f6..12b7af279398 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#discovery --- The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment. diff --git a/source/_docs/mqtt/logging.markdown b/source/_docs/mqtt/logging.markdown index a7fd1adfdf85..d40f99cd7964 100644 --- a/source/_docs/mqtt/logging.markdown +++ b/source/_docs/mqtt/logging.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#logging --- The [logger](/components/logger/) component allow the logging of received MQTT messages. diff --git a/source/_docs/mqtt/processing_json.markdown b/source/_docs/mqtt/processing_json.markdown index 552dd0816763..b10558655cb7 100644 --- a/source/_docs/mqtt/processing_json.markdown +++ b/source/_docs/mqtt/processing_json.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#processing-json --- The MQTT [switch](/components/switch.mqtt/) and [sensor](/components/sensor.mqtt/) platforms support processing JSON over MQTT messages and parsing them using JSONPath. JSONPath allows you to specify where in the JSON the value resides that you want to use. The following examples will always return the value `100`. diff --git a/source/_docs/mqtt/service.markdown b/source/_docs/mqtt/service.markdown index d751856fe4c6..0b3e778fdf2e 100644 --- a/source/_docs/mqtt/service.markdown +++ b/source/_docs/mqtt/service.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#publish-service --- The MQTT component will register the service `publish` which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use `payload` to hard-code a payload or use `payload_template` to specify a [template](/topics/templating/) that will be rendered to generate the payload. diff --git a/source/_docs/mqtt/testing.markdown b/source/_docs/mqtt/testing.markdown index f71ac52e2f16..3cc565d05116 100644 --- a/source/_docs/mqtt/testing.markdown +++ b/source/_docs/mqtt/testing.markdown @@ -8,6 +8,7 @@ comments: false sharing: true footer: true logo: mqtt.png +redirect_from: /components/mqtt/#testing-your-setup --- The `mosquitto` broker package ships commandline tools (often as `*-clients` package) to send and receive MQTT messages. As an alternative have a look at [hbmqtt_pub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_pub.html) and [hbmqtt_sub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_sub.html) which are provided by HBMQTT. For sending test messages to a broker running on localhost check the example below: diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index 69441a23ab92..22e094ce445f 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts/ --- Scripts are a sequence of actions that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in [automations] and [Alexa/Amazon Echo] configurations. diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index dde7f9cf2efe..85837d5372ef 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts-conditions/ --- Conditions can be used within a script or automation to prevent further execution. A condition will look at the system right now. For example a condition can test if a switch is currently turned on or off. diff --git a/source/_docs/scripts/service-calls.markdown b/source/_docs/scripts/service-calls.markdown index 2f9e4b07a10c..58ee3b4b9243 100644 --- a/source/_docs/scripts/service-calls.markdown +++ b/source/_docs/scripts/service-calls.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts-service-calls/ --- Various components allow calling services when a certain event occurs. The most common one is calling a service when an automation trigger happens. But a service can also be called from a script or via the Amazon Echo. diff --git a/source/_docs/z-wave.markdown b/source/_docs/z-wave.markdown index 8e5786e754b1..88eb7a3de18b 100644 --- a/source/_docs/z-wave.markdown +++ b/source/_docs/z-wave.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +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. diff --git a/source/_docs/z-wave/controllers.markdown b/source/_docs/z-wave/controllers.markdown index 694f7263d0c5..76831a22993a 100644 --- a/source/_docs/z-wave/controllers.markdown +++ b/source/_docs/z-wave/controllers.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-controllers/ --- Z-Wave is a popular home automation protocol that is not always straightforward to setup. This page will try to help you make sense of it all. diff --git a/source/_docs/z-wave/device-specific.markdown b/source/_docs/z-wave/device-specific.markdown index 047fd29e67f1..5437d4b60142 100644 --- a/source/_docs/z-wave/device-specific.markdown +++ b/source/_docs/z-wave/device-specific.markdown @@ -7,9 +7,10 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-device-specific/ --- -##### {% linkable_title Motion or alarm sensors %} +## {% linkable_title Motion or alarm sensors %} In order for Home Assistant to recognize the sensor properly, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`. These devices will either show as a binary sensor or a sensor called `Alarm xxxx` and will report a numeric value. Test to see what value is what. Sometimes this is noted in the device manual. @@ -21,8 +22,12 @@ The following parameters can be entered: - **parameter** (*Required*): The index number of the parameter to be set. Refer to device manual or zwcfg_[home_id].xml - **value** (*Required*): The value to set the parameter to. Refer to device manual or zwcfg_[home_id].xml - **size** (*Optional*): The size of the value. It is normally not needed to specify this parameter, but in some cases it's needed. Check OZW.log for details on this. -You should check OZW.log to see if your new setting has been set + +You should check OZW.log to see if your new setting has been set. + Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6: + + ```yaml # Example entry in dev-service { @@ -32,7 +37,7 @@ Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6 } ``` -##### {% linkable_title Locks and other secure devices %} +## {% linkable_title Locks and other secure devices %} These devices require a network key to be set for the Z-Wave network before they are paired. This key is set in OpenZWave's `options.xml` which is located in OpenZWave's directory. This should also be the same directory as `config_path:` in your `configuration.yaml`. If it's not, make sure you have the same values in all the files you are using. The option is commented out by default in `options.xml` and is a default key. Make your own unique key. The key is in Hexadecimals. diff --git a/source/_docs/z-wave/settings.markdown b/source/_docs/z-wave/settings.markdown index 64102acd8f6e..fecba91fd50c 100644 --- a/source/_docs/z-wave/settings.markdown +++ b/source/_docs/z-wave/settings.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-settings/ --- You may wish to modify the Z-Wave settings in your `ozw*.xml` file (stored in the `.homeassistant` configuration directory), or certain situations/devices may require it (i.e. Aeon Multisensor 6). To do this, utilize [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel). Alternatively, use [Domoticz](https://www.domoticz.com/), which incorporates the Open-Zwave Control Panel project into an easy to use Raspberry Pi image. From 10f438164e450d063b8c3af4836a894e66eb06ac Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:19:48 +0100 Subject: [PATCH 50/51] Update --- source/_docs/ecosystem.markdowm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_docs/ecosystem.markdowm b/source/_docs/ecosystem.markdowm index ea1512a9c316..2d221faf0072 100644 --- a/source/_docs/ecosystem.markdowm +++ b/source/_docs/ecosystem.markdowm @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -hide_github_edit: true +redirect_from: /ecosystem/ --- Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems. From d3441224a05efb50c33a12d840aafb9569f09ba6 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 21 Feb 2017 19:20:08 +0100 Subject: [PATCH 51/51] Update navigation --- source/_includes/asides/docs_navigation.html | 89 +++++++++---------- .../asides/getting_started_navigation.html | 4 +- 2 files changed, 46 insertions(+), 47 deletions(-) diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index c9f68be63cbd..59a3e6f813dd 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -1,7 +1,4 @@ -

      - {% include edit_github.html %} -

      Topics

        @@ -58,7 +55,7 @@

        Topics

      • {% active_link /docs/automation/ Automation %}
          -
        • {% active_link /docs/automation/tutorial/ Tutorial %}
          • +
        • {% active_link /docs/automation/examples/ Examples %}
        • {% active_link /docs/automation/trigger/ Triggers %}
        • {% active_link /docs/automation/condition/ Conditions %}
        • {% active_link /docs/automation/action/ Actions %}
          • @@ -113,72 +110,72 @@

          Topics

          {% active_link /docs/ecosystem/ Ecosystem %}
          • - {% active_link /docs/autostart/ Autostart %} + {% active_link /docs/ecosystem/autostart/ Autostart %}
              -
            • {% active_link /docs/autostart/systemd/ systemd (Linux) %}
              • -
            • {% active_link /docs/autostart/upstart/ Upstart (Linux) %}
              • -
            • {% active_link /docs/autostart/init.d/ init.d (Linux) %}
              • -
            • {% active_link /docs/autostart/macos/ macOS %}
              • -
            • {% active_link /docs/autostart/synology/ Synology NAS %}
              • +
            • {% active_link /docs/ecosystem/autostart/systemd/ systemd (Linux) %}
              • +
            • {% active_link /docs/ecosystem/autostart/upstart/ Upstart (Linux) %}
              • +
            • {% active_link /docs/ecosystem/autostart/init.d/ init.d (Linux) %}
              • +
            • {% active_link /docs/ecosystem/autostart/macos/ macOS %}
              • +
            • {% active_link /docs/ecosystem/autostart/synology/ Synology NAS %}
          • - {% active_link /docs/appdaemon/ AppDaemon %} + {% active_link /docs/ecosystem/appdaemon/ AppDaemon %}
              -
            • {% active_link /docs/appdaemon/installation/ Installation %}
              • -
            • {% active_link /docs/appdaemon/configuration/ Configuration %}
              • -
            • {% active_link /docs/appdaemon/example_apps/ Example Apps %}
              • -
            • {% active_link /docs/appdaemon/running/ Running AppDaemon %}
              • -
            • {% active_link /docs/appdaemon/reboot/ Starting AppDaemon at Reboot %}
              • -
            • {% active_link /docs/appdaemon/operation/ Operation %}
              • -
            • {% active_link /docs/appdaemon/windows/ AppDaemon on Windows %}
              • -
            • {% active_link /docs/appdaemon/updating/ Updating AppDaemon %}
              • -
            • {% active_link /docs/appdaemon/tutorial/ AppDaemon Tutorial %}
              • -
            • {% active_link /docs/appdaemon/api/ AppDaemon API Reference %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/installation/ Installation %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/configuration/ Configuration %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/example_apps/ Example Apps %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/running/ Running AppDaemon %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/reboot/ Starting AppDaemon at Reboot %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/operation/ Operation %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/windows/ AppDaemon on Windows %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/updating/ Updating AppDaemon %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/tutorial/ AppDaemon Tutorial %}
              • +
            • {% active_link /docs/ecosystem/appdaemon/api/ AppDaemon API Reference %}
          • - {% active_link /docs/hadashboard/ HADashboard %} + {% active_link /docs/ecosystem/hadashboard/ HADashboard %}
              -
            • {% active_link /docs/hadashboard/installation/ Installation %}
              • -
            • {% active_link /docs/hadashboard/dash_config/ Dashboard Configuration %}
              • -
            • {% active_link /docs/hadashboard/hapush/ HAPush %}
              • -
            • {% active_link /docs/hadashboard/reboot/ Reboot %}
              • -
            • {% active_link /docs/hadashboard/updating/ Updating HADashboard %}
              • +
            • {% active_link /docs/ecosystem/hadashboard/installation/ Installation %}
              • +
            • {% active_link /docs/ecosystem/hadashboard/dash_config/ Dashboard Configuration %}
              • +
            • {% active_link /docs/ecosystem/hadashboard/hapush/ HAPush %}
              • +
            • {% active_link /docs/ecosystem/hadashboard/reboot/ Reboot %}
              • +
            • {% active_link /docs/ecosystem/hadashboard/updating/ Updating HADashboard %}
          • - {% active_link /docs/notebooks/ Notebooks %} + {% active_link /docs/ecosystem/notebooks/ Notebooks %}
              -
            • {% active_link /docs/notebooks/ Introduction %}
              • -
            • {% active_link /docs/notebooks/installation/ Installation %}
              • -
            • {% active_link /docs/notebooks/graph/ Graph %}
              • -
            • {% active_link /docs/notebooks/api/ Home Assistant API %}
              • -
            • {% active_link /docs/notebooks/database/ Databsase %}
              • -
            • {% active_link /docs/notebooks/stats/ Statistics %}
              • +
            • {% active_link /docs/ecosystem/notebooks/ Introduction %}
              • +
            • {% active_link /docs/ecosystem/notebooks/installation/ Installation %}
              • +
            • {% active_link /docs/ecosystem/notebooks/graph/ Graph %}
              • +
            • {% active_link /docs/ecosystem/notebooks/api/ Home Assistant API %}
              • +
            • {% active_link /docs/ecosystem/notebooks/database/ Databsase %}
              • +
            • {% active_link /docs/ecosystem/notebooks/stats/ Statistics %}
          • - {% active_link /docs/ios/notifications/ iOS %} + {% active_link /docs/ecosystem/ios/notifications/ iOS %}
              -
            • {% active_link /docs/ios/notifications/basic/ Basic notifications %}
              • +
            • {% active_link /docs/ecosystem/ios/notifications/basic/ Basic notifications %}
                • -
              • {% active_link /docs/ios/notifications/examples/ Examples %}
                • -
              • {% active_link /docs/ios/notifications/sounds/ Sounds %}
                • -
              • {% active_link /docs/ios/notifications/architecture/ Architecture %}
                • -
              • {% active_link /docs/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/examples/ Examples %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/sounds/ Sounds %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/architecture/ Architecture %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
            • Advanced notifications
                • -
              • {% active_link /docs/ios/notifications/attachments/ Attachments %}
                • -
              • {% active_link /docs/ios/notifications/content_extensions/ Dynamic content %}
                • -
              • {% active_link /docs/ios/notifications/actions/ Actionable notifications %}
                • -
              • {% active_link /docs/ios/notifications/requesting_location_updates/ Requesting location updates %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/attachments/ Attachments %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/content_extensions/ Dynamic content %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/actions/ Actionable notifications %}
                • +
              • {% active_link /docs/ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}
              -
            • {% active_link /docs/ios/location/ Location Tracking %}
              • -
            • {% active_link /docs/ios/integration/ Integration with other apps %}
              • +
            • {% active_link /docs/ecosystem/ios/location/ Location Tracking %}
              • +
            • {% active_link /docs/ecosystem/ios/integration/ Integration with other apps %}
          diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index af6b13736c6a..9d41bb402b13 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -7,7 +7,9 @@

          Getting Started Guide

        • {% active_link /getting-started/ Installation %}
        • {% active_link /getting-started/configuration/ Configuration %}
        • {% active_link /getting-started/automation/ Automation %}
          • -
        • {% active_link /getting-started/run/ Run it! %}
          • +
        • {% active_link /getting-started/automation-2/ Automation 2 %}
          • +
        • {% active_link /getting-started/presence-detection/ Presence detection %}
          • +
        • {% active_link /getting-started/use/ Use it! %}