diff --git a/README.markdown b/README.markdown index 2f7a81af39c..38c15c62b77 100644 --- a/README.markdown +++ b/README.markdown @@ -13,24 +13,3 @@ In order to make the preview available on [http://127.0.0.1:4000](http://127.0.0 ```bash $ rake preview ``` - -### Setup on Fedora and CentOS -On Fedora 22 and later or CentOS 7.1.1503, Ruby is not available by default. Please take the notes here as a little guide for the Ruby installation process. - -```bash -$ curl -sSL https://rvm.io/mpapis.asc | gpg2 --import - -$ curl -L get.rvm.io | bash -s stable -$ source ~/.profile -$ rvm requirements -$ rvm install ruby-2.2.3 -$ rvm use ruby-2.2.3 --default -$ ruby -v -``` - -The last command will give you something like this: `ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]`. Then install `bundler`. - -```bash -$ gem install bundler -``` - -Now you can follow the [setup instructions](https://home-assistant.io/developers/website/). diff --git a/_config.yml b/_config.yml index a1121023aa9..aaff623f774 100644 --- a/_config.yml +++ b/_config.yml @@ -72,6 +72,10 @@ collections: output: true cookbook: output: true + ecosystem: + output: true + details: + output: true topics: output: true diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index 46c436b3e82..73af089aa6a 100644 --- a/source/_components/alexa.markdown +++ b/source/_components/alexa.markdown @@ -337,19 +337,24 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf ### {% linkable_title Configuring your Flash Briefing skill %} - Log in to [Amazon developer console][amazon-dev-console] -- Click the Alexa button at the top of the console +- Click the Alexa navigation tab at the top of the console +- Click on the "Get Started >" button under "Alexa Skills Kit" - Click the yellow "Add a new skill" button in the top right - Skill Information - - For Skill Type select Flash Briefing Skill API + - For Skill Type select "Flash Briefing Skill API" - You can enter whatever name you want - - Hit next + - Hit "Next" - Interaction Model - Nothing to do here - Configuration - Add new feed - - For URL, enter `https://YOUR_HOST/api/alexa/flash_briefings/BRIEFING_ID?api_password=YOUR_API_PASSWORD` where `BRIEFING_ID` is the key you entered in your configuration (such as `whoishome` in the above example) + - For URL, enter `https://YOUR_HOST/api/alexa/flash_briefings/BRIEFING_ID?api_password=YOUR_API_PASSWORD` where `BRIEFING_ID` is the key you entered in your configuration (such as `whoishome` in the above example). **NOTE:** Do not use a non-standard http or https port, AWS will not connect to it. - You can use this [specially sized Home Assistant logo][large-icon] as the Feed Icon - All other settings are up to you + - Hit "Next" + - Test + - Having passed all validations to reach this screen you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service. +- To invoke your flash briefing, open the Alexa app on your phone or go to [Alexa|http://alexa.amazon.com/], open the "Skills" configuration section, select "Your Skills", scroll to the bottom, tap on the Flash Briefing Skill you just created, enable it, then manage Flash Briefing and adjust ordering as necessary. Finally ask your Echo for your "news","flash briefing", or "briefing". [amazon-dev-console]: https://developer.amazon.com [flash-briefing-api]: https://developer.amazon.com/alexa-skills-kit/flash-briefing diff --git a/source/_components/binary_sensor.concord232.markdown b/source/_components/binary_sensor.concord232.markdown index b373909ee98..b31d6689c6c 100644 --- a/source/_components/binary_sensor.concord232.markdown +++ b/source/_components/binary_sensor.concord232.markdown @@ -8,7 +8,7 @@ comments: false sharing: true footer: true logo: interlogix.png -ha_category: Binary sensor +ha_category: Binary Sensor ha_release: 0.31 --- diff --git a/source/_components/binary_sensor.rest.markdown b/source/_components/binary_sensor.rest.markdown index dda929874c3..058a50219cc 100644 --- a/source/_components/binary_sensor.rest.markdown +++ b/source/_components/binary_sensor.rest.markdown @@ -56,9 +56,13 @@ Configuration variables: - **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value. - **payload** (*Optional*): The payload to send with a POST request. Usualy formed as a dictionary. - **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to True. +- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`. +- **username** (*Optional*): The username for accessing the REST endpoint. +- **password** (*Optional*): The password for accessing the REST endpoint. +- **headers** (*Optional*): The headers for the requests.

-Make sure that the URL matches exactly your endpoint or resource. +Make sure that the URL exactly matches your endpoint or resource.

@@ -68,7 +72,7 @@ In this section you find some real life examples of how to use this sensor. ### {% linkable_title aREST sensor %} -Instead of using an [aREST](/components/binary_sensor.arest/) binary sensor could the value of a device supporting aREST directly retrieved with a REST binary sensor. +Instead of using an [aREST](/components/binary_sensor.arest/) binary sensor, you could retrieve the value of a device supporting aREST directly with a REST binary sensor. ```yaml binary_sensor: @@ -77,6 +81,31 @@ binary_sensor: method: GET name: Light sensor_class: light - value_template: '{{ value_json.return_value }}' + value_template: {% raw %}'{{ value_json.return_value }}'{% endraw %} ``` +### {% linkable_title Accessing an HTTP authentication protected endpoint %} + +The REST sensor supports HTTP authentication and customized headers. + +```yaml +binary_sensor: + - platform: rest + resource: http://IP_ADDRESS:5000/binary_sensor + username: ha1 + password: test1 + authentication: basic + headers: + User-Agent: Home Assistant + Content-Type: application/json +``` + +The headers will contain all relevant details. This will also give you the ability to access endpoints that are protected by tokens. + +```bash +Content-Length: 1024 +Host: IP_ADDRESS1:5000 +Authorization: Basic aGExOnRlc3Qx +Accept-Encoding: identity +Content-Type: application/json +User-Agent: Home Assistant diff --git a/source/_components/device_tracker.icloud.markdown b/source/_components/device_tracker.icloud.markdown index 4c19a009cc4..79ffd9acf66 100644 --- a/source/_components/device_tracker.icloud.markdown +++ b/source/_components/device_tracker.icloud.markdown @@ -25,12 +25,14 @@ device_tracker: - platform: icloud username: USERNAME password: PASSWORD + account_name: accountname ``` Configuration variables: - **username** (*Required*): The username for the iCloud account. - **password** (*Required*): The password for your given username. +- **account_name** (*Optional*): The friendly name for the account_name. If this isn't given, it will use the account_name of the username (so the part before the `@` in the email address).

This may cause battery drainage as it wakes up your device to get the current location. @@ -40,7 +42,12 @@ This may cause battery drainage as it wakes up your device to get the current lo You may receive an email from Apple stating that someone has logged into your account.

-

-If you have two-factor authentication enabled on your iCloud account you will not be able to use this presence detection in HA, even with an app-specific password. -

+To disable the drainage of the battery, a dynamic interval is being used for each individual device instead of a fixed interval for all devices linked to one account. The dynamic interval is based on the current zone of a device, the distance towards home and the battery level of the device. +2 Factor Authentication is enabled for iCloud. The component will ask which device you want to use as Trusted Device and then you can enter the code that has been sent to that device. The duration of this authentication is determined by Apple, but is now at 2 months, so you will only need to verify your account each two months, even after restarting Home Assistant. + +4 services are available for this component: +- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional. +- **icloud_lost_iphone**: This service will play the Lost iPhone sound on a certain iDevice. The `account_name` and `device_name` are optional. +- **icloud_set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to it's default dynamic interval based on it's current zone, it's distance towards home and it's battery level. +- **icloud_reset_account**: This service can be used to reset an iCloud account. This is helpful when not all devices are being found by the component or if you have added a new iDevice to your account. The `account_name` is optional. diff --git a/source/_components/device_tracker.markdown b/source/_components/device_tracker.markdown index ce3f13b4eaa..d325c1d4e92 100644 --- a/source/_components/device_tracker.markdown +++ b/source/_components/device_tracker.markdown @@ -73,7 +73,7 @@ devicename: | `name` | Host name or "Unnamed Device" | The friendly name of the device | | `mac` | None | The MAC address of the device. Add this if you are using a network device tracker like Nmap or SNMP | | `icon` | None | A name of an MDI Icon. | -| `picture` | None | A picture that you can use to easily identify the person or device, if provided, will override 'icon' | +| `picture` | None | A picture that you can use to easily identify the person or device. You can also save the image file in a folder "www" in the same location (can be obtained from developer tools) where you have your configuration.yaml file and just use `picture: /local/favicon-192x192.png`. | | `gravatar` | None | An email address for the device's owner. If provided, it will override `picture` | | `track` | False | If `yes`/`on`/`true` then the device will be tracked. Otherwise its location and state will not update | | `hide_if_away` | False | If `yes`/`on`/`true` then the device will be hidden if it is not at home | diff --git a/source/_components/device_tracker.tomato.markdown b/source/_components/device_tracker.tomato.markdown index 01b8336ac41..e7a105ea2fe 100644 --- a/source/_components/device_tracker.tomato.markdown +++ b/source/_components/device_tracker.tomato.markdown @@ -15,6 +15,8 @@ ha_release: pre 0.7 The `tomato` platform requires an extra config variable called `http_id`. The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code. +Because of a limitation in Tomato's API, this platform will only track wireless devices. If tracking wired devices like a Philips Hue Hub is necessary, it is possible to use another platform like [NMAP](/components/device_tracker.nmap_tracker/). + To use this device tracker in your installation, add the following to your `configuration.yaml` file: ```yaml diff --git a/source/_components/discovery.markdown b/source/_components/discovery.markdown index 763f6fe8276..276571e3f81 100644 --- a/source/_components/discovery.markdown +++ b/source/_components/discovery.markdown @@ -18,7 +18,13 @@ Home Assistant can discover and automatically configure zeroconf/mDNS and uPnP d * Belkin WeMo switches * Philips Hue * Netgear routers - * Plex Media Server + * Plex media server + * Panasonic Viera + * Roku media player + * Sono Speaker + * Yamaha media player + * Logitech media server (Squeezebox) + * DirecTV It will be able to add Google Chromecasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user. @@ -30,8 +36,8 @@ discovery: ```

-The home-assistant server must be on the same network as the devices for uPnP discovery to work. -If running home-assistant in a docker container use switch `--net=host` to put it on the host's network. +Home Assistant must be on the same network as the devices for uPnP discovery to work. +If running Home Assistant in a Docker container use switch `--net=host` to put it on the host's network.

If you are developing a new platform, please read [how to make your platform discoverable]({{site_root}}/developers/add_new_platform/#discovery). diff --git a/source/_components/emulated_hue.markdown b/source/_components/emulated_hue.markdown index 0d965681ff0..241e697aa32 100644 --- a/source/_components/emulated_hue.markdown +++ b/source/_components/emulated_hue.markdown @@ -84,6 +84,13 @@ The following are attributes that can be applied in the `customize` section: - **emulated_hue** (*Optional*): Whether or not the entity should be exposed by the emulated Hue bridge. The default value for this attribute is controlled by the `expose_by_default` option. - **emulated_hue_name** (*Optional*): The name that the emulated Hue will use. The default for this is the entity's friendly name. +### {% linkable_title Troubleshooting %} + +You can verify that the `emulated_hue` component has been loaded and is responding by pointing a local browser to the following URL: +http://``:8300/description.xml - This URL should return a descriptor file in the form of an XML file. +http://``:8300/api/pi/lights - This will return a list of devices, lights, scenes, groups, etc.. that `emulated_hue` is exposing to Alexa. + + ### {% linkable_title License %} Much of this code is based on work done by Bruce Locke on his [ha-local-echo](https://github.com/blocke/ha-local-echo) project, originally released under the MIT License. The license is located [here](https://github.com/blocke/ha-local-echo/blob/b9bf5dcaae6d8e305e2283179ffba64bde9ed29e/LICENSE). diff --git a/source/_components/fan.mqtt.markdown b/source/_components/fan.mqtt.markdown index 2ddbbfc5db2..61111b227a8 100644 --- a/source/_components/fan.mqtt.markdown +++ b/source/_components/fan.mqtt.markdown @@ -32,15 +32,27 @@ fan: Configuration variables: -- **name** (*Optional*): The name of the lock. Default is 'MQTT Lock'. +- **command_topic** (*Required*): The MQTT topic to publish commands to change the fan state. - **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **command_topic** (*Required*): The MQTT topic to publish commands to change the lock state. +- **name** (*Optional*): The name of the fan. Default is 'MQTT Fan'. - **payload_on** (*Optional*): The payload that represents the running state. Default is "ON". - **payload_off** (*Optional*): The payload that represents the stop state. Default is "OFF". - **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no state topic defined, else `false`. - **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. - **retain** (*Optional*): If the published message should have the retain flag on or not. -- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload. +- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the state. +- **speed_state_topic** (*Optional*): The MQTT topic subscribed to receive speed updates. +- **speed_command_topic** (*Optional*): The MQTT topic to publish commands to change the fan speed. +- **speed_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the speed. +- **oscillation_state_topic** (*Optional*): The MQTT topic subscribed to receive oscillation updates. +- **oscillation_command_topic** (*Optional*): The MQTT topic to publish commands to change the fan oscillation. +- **oscillation_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the oscillation. +- **payload_oscillation_on** (*Optional*): The payload that represents the oscillation state. Default is "ON". +- **payload_oscillation_off** (*Optional*): The payload that represents the oscillation state. Default is "OFF". +- **payload_low_speed** (*Optional*): The payload that represents the low speed state. Default is "low". +- **payload_medium_speed** (*Optional*): The payload that represents the low speed state. Default is "med". +- **payload_high_speed** (*Optional*): The payload that represents the low speed state. Default is "high". +- **speeds** array (*Optional*): Valid entries for the list are `off`, `low`, `med`, and `high`.

Make sure that your topic match exact. `some-topic/` and `some-topic` are different topics. diff --git a/source/_components/ifttt.markdown b/source/_components/ifttt.markdown index d00a95ba70d..5810441ddf1 100644 --- a/source/_components/ifttt.markdown +++ b/source/_components/ifttt.markdown @@ -71,7 +71,11 @@ automation: To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web. This can be achieved by forwarding port 8123 from your router to the device running Home Assistant. If your ISP is giving you a new IP address from time to time, consider using [DuckDNS][duck-dns]. +In the URL field, you can then put an [API URL][rest-api]. You probably want to use a POST action, so select `POST` as method. After your request line, you need to add your Home Assistant password, which you defined in the [http section of your config][http-configuration], in the form off `?api_password=`. For the message body, refer to the API page linked above. + [duck-dns]: https://duckdns.org +[rest-api]: https://home-assistant.io/developers/rest_api/ +[http-configuration]: https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface

diff --git a/source/_components/influxdb.markdown b/source/_components/influxdb.markdown index 889afd56a70..0c38b6584fa 100644 --- a/source/_components/influxdb.markdown +++ b/source/_components/influxdb.markdown @@ -8,7 +8,7 @@ comments: false sharing: true footer: true logo: influxdb.png -ha_category: "History" +ha_category: History ha_release: 0.9 --- diff --git a/source/_components/media_player.webostv.markdown b/source/_components/media_player.webostv.markdown index 12b25fbfbdc..061017fd08f 100644 --- a/source/_components/media_player.webostv.markdown +++ b/source/_components/media_player.webostv.markdown @@ -23,7 +23,6 @@ To add a TV to your installation, add the following to your `configuration.yaml` # Example configuration.yaml entry media_player: - platform: webostv - host: 192.168.0.10 ``` Configuration variables: diff --git a/source/_components/media_player.yamaha.markdown b/source/_components/media_player.yamaha.markdown index 142979ed880..e81241e09b9 100644 --- a/source/_components/media_player.yamaha.markdown +++ b/source/_components/media_player.yamaha.markdown @@ -43,7 +43,7 @@ A few notes: - For receivers that support more than one zone, Home Assistant will add one media player per zone supported by the player, named "$name Zone 2" and "$name Zone 3". - In some cases, autodiscovery fails due to a known bug in the receiver's firmware. It is possible to manually specify the reveiver's IP address or via it's hostname (if it is discoverably by your DNS) then. - Please note: If adding the IP address or hostname manually, you **must** enable network standby on your receiver, or else startup of Home Assistant will hang if you have your receiver switched off. -- Currently, this component supports powering on/off, mute, volume control and source selection. +- Currently, this component supports powering on/off, mute, volume control and source selection. Playback controls, for instance play and stop are available for sources that supports it. A full configuration example will look like the sample below: ```yaml diff --git a/source/_components/notify.xmpp.markdown b/source/_components/notify.xmpp.markdown index 6ebdc4383bd..a9d0595e5f1 100644 --- a/source/_components/notify.xmpp.markdown +++ b/source/_components/notify.xmpp.markdown @@ -15,6 +15,8 @@ ha_release: pre 0.7 The `xmpp` platform allows you to deliver notifications from Home Assistant to a [Jabber (XMPP)](http://xmpp.org) account. +To enable Jabber notifications in your installation, add the following to your `configuration.yaml` file: + ```yaml # Example configuration.yaml entry notify: diff --git a/source/_components/rfxtrx.markdown b/source/_components/rfxtrx.markdown index 3cecbf5fe65..a14fb061124 100644 --- a/source/_components/rfxtrx.markdown +++ b/source/_components/rfxtrx.markdown @@ -27,3 +27,7 @@ Configuration variables: - **device** (*Required*): The path to your device, e.g. `/dev/serial/by-id/usb-RFXCOM_RFXtrx433_A1Y0NJGR-if00-port0` - **debug** (*Optional*): If you want to receive debug output. - **dummy** (*Optional*): Then you have need a connected drive to test your settings. Can be usefull for debugging and testing. + +Supported protocols + +Not all protocols as advertised are enabled on inital setup of your transceiver. Enabling all protocols is not recommmended either. Your 433.92 product not showing in the logs? Visit the RFXtrx website to [download RFXmgmr](http://www.rfxcom.com/epages/78165469.sf/nl_NL/?ObjectPath=/Shops/78165469/Categories/Downloads) and enable the required protocol. diff --git a/source/_components/sensor.efergy.markdown b/source/_components/sensor.efergy.markdown index 3669b17f51c..7acafd281aa 100644 --- a/source/_components/sensor.efergy.markdown +++ b/source/_components/sensor.efergy.markdown @@ -14,7 +14,15 @@ ha_iot_class: "Cloud Polling" --- -Integrate your [Efergy](https://efergy.com) meter information into Home Assistant. To get an app token, log in to your efergy account, go to the Settings page, click on App tokens, and click "Add token". +Integrate your [Efergy](https://efergy.com) meter information into Home Assistant. To get an app token: + +1. Log in to your efergy account + +2. Go to the Settings page + +3. Click on App tokens + +4. Click "Add token" ```yaml # Example configuration.yaml entry diff --git a/source/_components/sensor.fixer.markdown b/source/_components/sensor.fixer.markdown index ce9071e4bcd..3a555f2c254 100644 --- a/source/_components/sensor.fixer.markdown +++ b/source/_components/sensor.fixer.markdown @@ -16,7 +16,7 @@ ha_release: 0.23 The `fixer` sensor will show you the current exchange rate from [Fixer.io](http://fixer.io/) which is using data from the [European Central Bank (ECB)](https://www.ecb.europa.eu). -To get an owerview about the available [currencies](http://api.fixer.io/latest). +To get an overview about the available [currencies](http://api.fixer.io/latest). To enable this sensor, add the following lines to your `configuration.yaml` file: diff --git a/source/_components/sensor.plex.markdown b/source/_components/sensor.plex.markdown index 30ca14ad0f4..c147419359e 100644 --- a/source/_components/sensor.plex.markdown +++ b/source/_components/sensor.plex.markdown @@ -21,20 +21,14 @@ If you want to enable the plex sensor, add the following lines to your `configur ```yaml # Example configuration.yaml entry sensor: - platform: plex - name: Plex Spy - host: 192.168.1.100 - port: 32400 - username: plexuser - password: plexpw - server: MyPlexServer + - platform: plex ``` Configuration variables: - **host** (*Optional*): The IP address of your Plex server. Defaults to `localhost`. -- **port** (*Optional*): The port of your Plex Server. Defaults to 32400. -- **name** (*Optional*): Name of the Plex server. Defaults to Plex. +- **port** (*Optional*): The port of your Plex Server. Defaults to `32400`. +- **name** (*Optional*): Name of the Plex server. Defaults to "Plex". - **username** (*Optional*): The username for the remote Plex server. - **password** (*Optional*): The password for your given account on the remote Plex server. - **server** (*Optional*): The name of your remote Plex server. diff --git a/source/_components/sensor.rest.markdown b/source/_components/sensor.rest.markdown index 9893ba89461..009fc9c38ac 100644 --- a/source/_components/sensor.rest.markdown +++ b/source/_components/sensor.rest.markdown @@ -50,10 +50,10 @@ Configuration variables: - **headers** (*Optional*): The headers for the requests.

-Make sure that the URL matches exactly your endpoint or resource. +Make sure that the URL exactly matches your endpoint or resource.

-`curl` could help you with the identification of the variable you want to display in your Home Assistant frontend. The example below show the JSON response of a device that is running with [aREST](http://arest.io/). +`curl` can help you identify the variable you want to display in your Home Assistant frontend. The example below shows the JSON response of a device that is running with [aREST](http://arest.io/). ```bash $ curl -X GET http://192.168.1.31/temperature/ @@ -97,6 +97,8 @@ sensor: The Home Assistant [API](/developers/rest_api/) exposes the data from your attached sensors. If you are running multiple Home Assistant instances which are not [connected](/developers/architecture/#multiple-connected-instances) you can still get information from them. +If the Home Assistant instance in the resource variable is protected by an API password, you can append `?api_password=YOUR_PASSWORD` to the resource URL to authenticate or use `headers:`. + ```yaml sensor: - platform: rest @@ -105,6 +107,7 @@ sensor: value_template: {% raw %}'{{ value_json.state }}'{% endraw %} unit_of_measurement: "°C" ``` + ### {% linkable_title Accessing a HTTP authentication protected endpoint %} The REST sensor supports HTTP authentication and customized headers. @@ -117,14 +120,14 @@ sensor: password: test1 authentication: basic headers: - User-agent: Home Assistant + User-Agent: Home Assistant Content-Type: application/json ``` -The header will contains all relevant details. This will give you the flexibility to access also endpoints wich are protected by Tokens. +The headers will contain all relevant details. This will also give you the ability to access endpoints that are protected by tokens. ```bash -Content-Length: +Content-Length: 1024 Host: IP_ADDRESS1:5000 Authorization: Basic aGExOnRlc3Qx Accept-Encoding: identity @@ -134,7 +137,7 @@ User-Agent: Home Assistant ### {% linkable_title Use GitHub to get the latest release of Home Assistant %} -This sample is very similar to the [`updater`](/components/updater/) component but the information are recieved from GitHub. +This sample is very similar to the [`updater`](/components/updater/) component but the information is recieved from GitHub. ```yaml sensor: diff --git a/source/_components/sensor.systemmonitor.markdown b/source/_components/sensor.systemmonitor.markdown index 4797d01dbf6..be8be3f0f42 100644 --- a/source/_components/sensor.systemmonitor.markdown +++ b/source/_components/sensor.systemmonitor.markdown @@ -13,7 +13,7 @@ ha_release: pre 0.7 ha_iot_class: "Local Push" --- -The `systemmonitor` sensor platform to allow you to monitor disk usage, memory usage, CPU usage, and running processes. This platform has superseded the process component which is now considered deprecated. +The `systemmonitor` sensor platform allows you to monitor disk usage, memory usage, CPU usage, and running processes. This platform has superseded the process component which is now considered deprecated. To add this platform to your installation, add the following to your `configuration.yaml` file: diff --git a/source/_components/switch.arduino.markdown b/source/_components/switch.arduino.markdown index 2b57d01cb94..6b15a63431b 100644 --- a/source/_components/switch.arduino.markdown +++ b/source/_components/switch.arduino.markdown @@ -27,7 +27,6 @@ switch: name: Fan Office 12: name: Light Desk - type: digital initial: true negate: true ``` diff --git a/source/_components/switch.rfxtrx.markdown b/source/_components/switch.rfxtrx.markdown index 372aaa76f2a..7e31df8da39 100644 --- a/source/_components/switch.rfxtrx.markdown +++ b/source/_components/switch.rfxtrx.markdown @@ -43,7 +43,30 @@ switch: name: device_name ``` -Example configuration: +Configuration variables: + +- **devices** (*Required*): A list of devices with their name to use in the frontend. +- **automatic_add** (*Optional*): To enable the automatic addition of new switches. +- **signal_repetitions** (*Optional*): Because the rxftrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly. +- **fire_event** (*Optional*): Fires an event even if the state is the same as before, for example a doorbell switch. Can also be used for automations. + +Generate codes: + +If you need to generate codes for switches you can use a template (usefull for example COCO switches). + +- Go to home-assistant-IP:8123/dev-template +- Use this code to generate a code: +```yaml +0b11000{{ range(0,700) | random | int }}bc0cfe0{{ range(0,10) | random | int }}010f70 +``` +- Use this code to add a new switch in your configuration.yaml +- Launch your homeassistant and go the website. +- Enable learning mode on your switch (i.e. push learn button or plug it in a wall socket) +- Toggle your new switch in the homeassisant interface + +## {% linkable_title Examples %} + +Basic configuration with 3 devices: ```yaml # Example configuration.yaml entry @@ -61,9 +84,68 @@ switch: fire_event: True ``` -Configuration variables: +Doorbell configuration: -- **devices** (*Required*): A list of devices with their name to use in the frontend. -- **automatic_add** (*Optional*): To enable the automatic addition of new switches. -- **signal_repetitions** (*Optional*): Because the rxftrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly. -- **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations. +```yaml +# Example configuration.yaml entry +switch: + platform: rfxtrx + automatic_add: False + devices: + 0710014c440f0160: + name: Hall + 0710010244080780: + name: Door + fire_event: true + +automation: + - alias: Switch light on when door bell rings if sun is below horizon and light was off + trigger: + platform: event + event_type: button_pressed + event_data: {"entity_id": "switch.door"} + condition: + condition: and + conditions: + - condition: state + entity_id: sun.sun + state: "below_horizon" + - condition: state + entity_id: switch.hall + state: 'off' + action: + - service: switch.turn_on + entity_id: switch.hall +``` + +Use remote to enable scene: + +```yaml +# Example configuration.yaml entry +switch: + platform: rfxtrx + automatic_add: False + devices: + 0b1100ce3213c7f210010f70: + name: Light1 + 0b11000a02ef2gf210010f50: + name: Light2 + 0b1111e003af16aa10000060: + name: Keychain remote + fire_event: true +scene: + name: Livingroom + entities: + switch.light1: on + switch.light2: on + +automation: + - alias: Use remote to enable scene + trigger: + platform: event + event_type: button_pressed + event_data: {"state": "on", "entity_id": "switch.keychain_remote"} + action: + service: scene.turn_on + entity_id: scene.livingroom +``` diff --git a/source/_cookbook/automation_for_rainy_days.markdown b/source/_cookbook/automation_for_rainy_days.markdown index 566a3001102..f141a71a714 100644 --- a/source/_cookbook/automation_for_rainy_days.markdown +++ b/source/_cookbook/automation_for_rainy_days.markdown @@ -10,7 +10,7 @@ footer: true ha_category: Automation Examples --- -This requires a [forecast.io](/components/sensor.forecast/) sensor with the condition `weather_precip` that tells if it's raining or not. +This requires a [Dark Sky](/components/sensor.darksky/) sensor with the condition `precip_intensity` that tells if it's raining or not. You could also experiment with other attributes such as `cloud_cover`. Turn on a light in the living room when it starts raining, someone is home, and it's afternoon or later. @@ -20,7 +20,7 @@ automation: trigger: - platform: state - entity_id: sensor.weather_precip + entity_id: sensor.precip_intensity state: 'rain' - platform: state entity_id: group.all_devices @@ -43,7 +43,7 @@ automation 2: alias: 'Rain is over' trigger: - platform: state - entity_id: sensor.weather_precip + entity_id: sensor.precip_intensity state: 'None' - platform: sun event: 'sunset' diff --git a/source/_cookbook/configuration_yaml_by_alok_saboo.markdown b/source/_cookbook/configuration_yaml_by_alok_saboo.markdown new file mode 100644 index 00000000000..a5cfc0512f1 --- /dev/null +++ b/source/_cookbook/configuration_yaml_by_alok_saboo.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Configuration.yaml by Alok Saboo" +description: "" +date: 2016-10-25 10:45 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Example configuration.yaml +ha_external_link: https://github.com/arsaboo/homeassistant-config +--- diff --git a/source/_cookbook/configuration_yaml_by_daniel_hoyer_iversen.markdown b/source/_cookbook/configuration_yaml_by_daniel_hoyer_iversen.markdown new file mode 100644 index 00000000000..5fe391eb75b --- /dev/null +++ b/source/_cookbook/configuration_yaml_by_daniel_hoyer_iversen.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Configuration.yaml by Daniel Høyer Iversen" +description: "" +date: 2016-10-11 11:45 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Example configuration.yaml +ha_external_link: https://github.com/Danielhiversen/home-assistant_config +--- diff --git a/source/configuration_yaml_by_mertenats.markdown b/source/_cookbook/configuration_yaml_by_mertenats.markdown similarity index 100% rename from source/configuration_yaml_by_mertenats.markdown rename to source/_cookbook/configuration_yaml_by_mertenats.markdown diff --git a/source/_cookbook/tor_configuration.markdown b/source/_cookbook/tor_configuration.markdown index 83a76091353..5bc371d176a 100644 --- a/source/_cookbook/tor_configuration.markdown +++ b/source/_cookbook/tor_configuration.markdown @@ -37,7 +37,7 @@ Onion sites are websites that run on a Tor Hidden Service node. "dot onion" site #### {% linkable_title Setting up Tor on your Home Assistant %} -First, install Tor. On a Debain-based system, you can install the package easily: +First, install Tor. On a Debian-based system, you can install the package easily: ```bash $ sudo apt-get install tor @@ -104,7 +104,7 @@ On iOS, we have not fully tested this yet, but you should be able to add custom With this configuration, only you can access your Home Assistant instance Onion site through Tor, and no one else. You can share the authentication cookie with multiple devices and users, or you can generate a unique one for each - up to you! If you have multiple, say for an industrial, business or corporate configuration, this would provide an easy way to revoke access to a specific user or device. -If you always access your Home Assistant instance via Tor, you can easily run this on an isolated "IoT" network segment at your install site, keeping your internal home network traffic seperate from any potentially compromised devices (like cheap "smart" lightbulbs with backdoors!). +If you always access your Home Assistant instance via Tor, you can easily run this on an isolated "IoT" network segment at your install site, keeping your internal home network traffic separate from any potentially compromised devices (like cheap "smart" lightbulbs with backdoors!). You could also use Tor as a means to connect your Home Assistant instance to a remote device, sensor or other service that you do not want to or connect provide a direct, open IP connection to. Again, Tor provides authenticated and confidential routing (aka "privacy and encryption") by default, without having to setup TLS/SSL or VPN. It is just important to secure IoT nodes within your network, as it is to secure remote access! diff --git a/source/_topics/database.markdown b/source/_details/database.markdown similarity index 98% rename from source/_topics/database.markdown rename to source/_details/database.markdown index eed1326201d..a4c7ec00acb 100644 --- a/source/_topics/database.markdown +++ b/source/_details/database.markdown @@ -1,9 +1,9 @@ --- layout: page -title: "Home Assistant Database" +title: "Database" description: "Details about the database which Home Assistant is using." date: 2016-10-10 10:00 -sidebar: true +sidebar: false comments: false sharing: true footer: true diff --git a/source/_topics/updater_details.markdown b/source/_details/updater.markdown similarity index 98% rename from source/_topics/updater_details.markdown rename to source/_details/updater.markdown index de2fa26044e..ccf13eb8116 100644 --- a/source/_topics/updater_details.markdown +++ b/source/_details/updater.markdown @@ -1,13 +1,12 @@ --- layout: page -title: "Details about the updater" +title: "Updater" description: "Details what the updater component is reporting about your Home Assistant instance." date: 2016-10-22 08:00 sidebar: false comments: false sharing: true footer: true -ha_category: Infrastructure --- Starting with 0.31 the [updater component](/components/updater/) sends an optional report about Home Assistant instance. diff --git a/source/_topics/webserver_details.markdown b/source/_details/webserver.markdown similarity index 95% rename from source/_topics/webserver_details.markdown rename to source/_details/webserver.markdown index 18ba4a3c152..f9e2f4e0031 100644 --- a/source/_topics/webserver_details.markdown +++ b/source/_details/webserver.markdown @@ -1,13 +1,12 @@ --- layout: page -title: "Details about the web server" +title: "Web server" description: "Use nmap to scan your Home Assistant instance." date: 2016-10-06 08:00 sidebar: false comments: false sharing: true footer: true -ha_category: Infrastructure --- 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/_ecosystem/ios.markdown b/source/_ecosystem/ios.markdown new file mode 100644 index 00000000000..49dc72fbf54 --- /dev/null +++ b/source/_ecosystem/ios.markdown @@ -0,0 +1,68 @@ +--- +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 +regenerate: true +hide_github_edit: 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] and [`zeroconf`][zeroconf] components. It also provides functionality required for the iOS notify platform but will not automatically load the `notify` component or platform as of 0.31.1. You must manually load it. See the [iOS notify platform][ios-notify] for more information. + +## {% 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/_ecosystem/ios/devices_file.markdown b/source/_ecosystem/ios/devices_file.markdown new file mode 100644 index 00000000000..4b27059456f --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/features.markdown b/source/_ecosystem/ios/features.markdown new file mode 100644 index 00000000000..895a6a25311 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/integration.markdown b/source/_ecosystem/ios/integration.markdown new file mode 100644 index 00000000000..e9db1dd875e --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/location.markdown b/source/_ecosystem/ios/location.markdown new file mode 100644 index 00000000000..f9bd14bf0a5 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications.markdown b/source/_ecosystem/ios/notifications.markdown new file mode 100644 index 00000000000..ff2fa1d5f1b --- /dev/null +++ b/source/_ecosystem/ios/notifications.markdown @@ -0,0 +1,24 @@ +--- +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. + +## {% linkable_title Setup %} + +```yaml +# Example configuration.yaml entry +notify: + - platform: ios +``` + +Configuration variables: + +- **name** (*Optional*): The name of the service. diff --git a/source/_ecosystem/ios/notifications/actions.markdown b/source/_ecosystem/ios/notifications/actions.markdown new file mode 100644 index 00000000000..9749cfec8ae --- /dev/null +++ b/source/_ecosystem/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. +

+ +## 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/_ecosystem/ios/notifications/architecture.markdown b/source/_ecosystem/ios/notifications/architecture.markdown new file mode 100644 index 00000000000..c699e452998 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications/attachments.markdown b/source/_ecosystem/ios/notifications/attachments.markdown new file mode 100644 index 00000000000..639f087b362 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications/basic.markdown b/source/_ecosystem/ios/notifications/basic.markdown new file mode 100644 index 00000000000..fbb217edffe --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications/content_extensions.markdown b/source/_ecosystem/ios/notifications/content_extensions.markdown new file mode 100644 index 00000000000..9279f75d595 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications/examples.markdown b/source/_ecosystem/ios/notifications/examples.markdown new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown b/source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown new file mode 100644 index 00000000000..ebb0b146267 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/notifications/requesting_location_updates.markdown b/source/_ecosystem/ios/notifications/requesting_location_updates.markdown new file mode 100644 index 00000000000..97b237ceb12 --- /dev/null +++ b/source/_ecosystem/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_updates" +``` + +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/_ecosystem/ios/notifications/sounds.markdown b/source/_ecosystem/ios/notifications/sounds.markdown new file mode 100644 index 00000000000..cbe35943ad8 --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/ios/requirements.markdown b/source/_ecosystem/ios/requirements.markdown new file mode 100644 index 00000000000..89e89e6dcbb --- /dev/null +++ b/source/_ecosystem/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/_ecosystem/scenegen.markdown b/source/_ecosystem/scenegen.markdown new file mode 100755 index 00000000000..77c3590ecbf --- /dev/null +++ b/source/_ecosystem/scenegen.markdown @@ -0,0 +1,184 @@ +--- +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 +regenerate: true +hide_github_edit: 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/_includes/asides/ecosystem_ios_navigation.html b/source/_includes/asides/ecosystem_ios_navigation.html new file mode 100644 index 00000000000..152b4494be5 --- /dev/null +++ b/source/_includes/asides/ecosystem_ios_navigation.html @@ -0,0 +1,39 @@ +
+ +
+

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 new file mode 100644 index 00000000000..a149574cd31 --- /dev/null +++ b/source/_includes/asides/ecosystem_navigation.html @@ -0,0 +1,25 @@ +{% assign url_parts = page.url | split: "/" %} +{% if url_parts[2] == "ios" %} + {% include asides/ecosystem_ios_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/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index 672f5816d56..0ab006db506 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -65,6 +65,7 @@
  • {% active_link {{site_root}}/topics/ Advanced Topics %}
    • +
  • {% active_link {{site_root}}/details/ Details %}
  • {% active_link /getting-started/android/ Add to Android Homescreen %}
  • {% active_link /getting-started/browsers/ Browser Compatibility List %}
    • diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 33d52b98af3..98337cf3137 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -4,14 +4,15 @@
  • Getting started
    • {% endcomment %} -
  • Getting started
    • -
  • Components
    • -
  • Examples
    • +
  • Getting started
    • +
  • Components
    • +
  • Ecosystem
    • +
  • Examples
  • Developers
  • Blog
  • Need help?
    • diff --git a/source/_includes/site/sidebar.html b/source/_includes/site/sidebar.html index 0fc5b4e130a..14fdb5f499d 100644 --- a/source/_includes/site/sidebar.html +++ b/source/_includes/site/sidebar.html @@ -6,6 +6,8 @@ {% 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 %} {% else %} diff --git a/source/_posts/2016-10-22-flash-briefing-updater-hacktoberfest.markdown b/source/_posts/2016-10-22-flash-briefing-updater-hacktoberfest.markdown index 8d2d249edf5..bc8bf9610e2 100644 --- a/source/_posts/2016-10-22-flash-briefing-updater-hacktoberfest.markdown +++ b/source/_posts/2016-10-22-flash-briefing-updater-hacktoberfest.markdown @@ -203,7 +203,8 @@ This is super annoying, I know, especially since we had said in [0.12][zero-one- ## {% linkable_title Breaking changes %} - The [HTTP] component now takes a different format for authenticating IPs - - Config format has changed for [Proximity] + - Configuration format has changed for [Proximity] + - The [Arduino] platform are now covered by the configuration check. Please check the documentation to see how. - The Z-Wave entity ID change mentioned above ## {% linkable_title If you need help... %} @@ -263,6 +264,7 @@ Thanks for reading all of the above, especially since this week was a pretty lon [@vittoriom]: https://github.com/vittoriom [@wokar]: https://github.com/wokar +[Arduino]: https://home-assistant.io/components/arduino/ [APNS]: https://home-assistant.io/components/notify.apns/ [ARWN]: https://home-assistant.io/components/sensor.arwn/ [Concord232]: https://home-assistant.io/components/alarm_control_panel.concord232/ diff --git a/source/_topics/state_object.markdown b/source/_topics/state_object.markdown index 35716de6b58..ca4f6827bfa 100644 --- a/source/_topics/state_object.markdown +++ b/source/_topics/state_object.markdown @@ -17,6 +17,7 @@ All states will always have an entity id, a state and a timestamp when last upda Field | Description ----- | ----------- +`state.state` | String representation of the current state of the entity. Example `off` `state.entity_id` | Entity ID. Format: `.`. Example: `light.kitchen`. `state.domain` | Domain of the entity. Example: `light`. `state.object_id` | Object ID of entity. Example: `kitchen`. diff --git a/source/_topics/templating.markdown b/source/_topics/templating.markdown index 5a84181d89f..6aca8ed1ad0 100644 --- a/source/_topics/templating.markdown +++ b/source/_topics/templating.markdown @@ -85,7 +85,7 @@ Home Assistant adds extensions to allow templates to access all of the current s ## {% linkable_title Examples %} ### {% linkable_title States %} -Next two statements result in same value if state exists. Second one will result in an error if state does not exist. +The next two statements result in same value if state exists. The second one will result in an error if state does not exist. ```text {% raw %}{{ states('device_tracker.paulus') }} @@ -134,7 +134,7 @@ Print out a list of all the sensor states. ### {% linkable_title Distance examples %} -If only 1 location is passed in will measure the distance from home. +If only 1 location is passed in, Home Assistant will measure the distance from home. ```text {% raw %}Using Lat Lng coordinates: {{ distance(123.45, 123.45) }} @@ -166,7 +166,7 @@ Closest to an entity: {{ closest(states.zone.school, 'group.children') }}{% endr ``` ### {% linkable_title Combined %} -Since closest returns a state, we can combine it with distance too +Since closest returns a state, we can combine it with distance too. ```text {% raw %}{{ closest(states).name }} is {{ distance(closest(states)) }} meters away.{% endraw %} @@ -176,7 +176,7 @@ Since closest returns a state, we can combine it with distance too The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data you care about. This will work only for platforms and components that mentioned support for this in their documentation. -It depends per component or platform but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions: +It depends per component or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions: | Variable | Description | | ------------ | -------------------------------------- | diff --git a/source/details/index.markdown b/source/details/index.markdown new file mode 100644 index 00000000000..ff2fccd135e --- /dev/null +++ b/source/details/index.markdown @@ -0,0 +1,20 @@ +--- +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/developers/architecture.markdown b/source/developers/architecture.markdown index 59ff0912d58..2e967a087c5 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -14,7 +14,7 @@ Before we dive into the Home Assistant architecture, let's get a clear overview For more information about each part in this overview, check out our blog. Here's the tl;dr version of the blog: * Home Control is responsible for collecting information and controlling devices. - * Home Automation triggers command based on user configurations. + * Home Automation triggers commands based on user configurations. * Smart Home triggers commands based on previous behaviour.

    @@ -25,9 +25,9 @@ For more information about each part in this overview, @@ -63,4 +63,4 @@ When we put all the different pieces of Home Assistant together, it's a close ma Overview of the full Home Assistant architecture with a couple of loaded components and platforms

    -The platform logic for components uses third-party Python libraries to communicate with the devices so we can leverage the great device libraries in the Python community. +The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community. diff --git a/source/developers/development_testing.markdown b/source/developers/development_testing.markdown index 60d927dd725..713f3830a9c 100644 --- a/source/developers/development_testing.markdown +++ b/source/developers/development_testing.markdown @@ -38,6 +38,7 @@ During development on a specific file, speed up your workflow by running tests a ```bash $ flake8 homeassistant/core.py $ pylint homeassistant/core.py +$ pydocstyle homeassistant/core.py $ py.test tests/test_core.py ``` diff --git a/source/developers/helpers.markdown b/source/developers/helpers.markdown index 3aeac28dd3f..390bf17b242 100644 --- a/source/developers/helpers.markdown +++ b/source/developers/helpers.markdown @@ -9,11 +9,10 @@ sharing: true footer: true --- -There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining platforms/components. Some are directly connected to Pull Requests and the repositories itself, others are only publishing details and updates in our [gitter.im](https://gitter.im/home-assistant/home-assistant/devs) chatroom. +There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining components. Some of these are directly connected to Pull Requests and the repositories, while others publish details and updates in our [Gitter.im](https://gitter.im/home-assistant/home-assistant/devs) chatroom. - [Coveralls](https://coveralls.io/github/home-assistant/home-assistant) - [Travis CI](https://travis-ci.org/home-assistant/home-assistant) - [gemnasium](https://gemnasium.com/github.com/home-assistant/home-assistant) - [Requires.io](https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev) - [Pivotal Tracker](https://www.pivotaltracker.com/n/projects/1250084) - diff --git a/source/developers/rest_api.markdown b/source/developers/rest_api.markdown index 9cedcc71dc6..1903af9863d 100644 --- a/source/developers/rest_api.markdown +++ b/source/developers/rest_api.markdown @@ -205,7 +205,7 @@ Returns an array of state changes in the past. Each object contains further deta }, "entity_id": "sensor.weather_temperature", "last_changed": "2016-02-06T22:15:00+00:00", - "last_updated": "2016-02-06T22:15:00+00:00"", + "last_updated": "2016-02-06T22:15:00+00:00", "state": "-3.9" }, { @@ -343,7 +343,7 @@ The return code is 200 if the entity existed, 201 if the state of a new entity w }, "entity_id": "sun.sun", "last_changed": "2016-05-30T21:43:29.204838+00:00", - "last_updated": "2016-05-30T21:47:30.533530+00:00" + "last_updated": "2016-05-30T21:47:30.533530+00:00", "state": "below_horizon" } ``` @@ -364,7 +364,7 @@ You can pass an optional JSON object to be used as `event_data`. ```json { - next_rising":"2016-05-31T03:39:14+00:00", + "next_rising":"2016-05-31T03:39:14+00:00", } ``` @@ -447,7 +447,7 @@ Set up event forwarding to another Home Assistant instance. Requires a JSON object that represents the API to forward to. -```json +```javascript { "host": "machine", "api_password": "my_super_secret_password", @@ -468,7 +468,7 @@ Cancel event forwarding to another Home Assistant instance.
    Requires a JSON object that represents the API to cancel forwarding to. -```json +```javascript { "host": "machine", "api_password": "my_super_secret_password", diff --git a/source/developers/website.markdown b/source/developers/website.markdown index 800a3b58da5..b48bc10332c 100644 --- a/source/developers/website.markdown +++ b/source/developers/website.markdown @@ -17,11 +17,13 @@ You can use the "**Edit this page on GitHub**" link to edit pages without creati For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a pull request. -To test your changes locally, you need to install the **Ruby** dependencies (gems): +To test your changes locally, you need to install **Ruby** and its dependencies (gems): - [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. -- Install `bundler`, a dependency manager for Ruby: `gem install bundler` -- In your home-assistant.github.io root directory, run `bundle` to install the gems you need. +- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` +- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need. + +Short cut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler && bundle` Then you can work on the documentation: diff --git a/source/ecosystem/index.markdown b/source/ecosystem/index.markdown new file mode 100644 index 00000000000..0af82796dab --- /dev/null +++ b/source/ecosystem/index.markdown @@ -0,0 +1,13 @@ +--- +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/getting-started/android.markdown b/source/getting-started/android.markdown index b2244fdd605..2ef656adf82 100644 --- a/source/getting-started/android.markdown +++ b/source/getting-started/android.markdown @@ -9,15 +9,15 @@ sharing: true footer: true --- -Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new [manifest.json support](https://w3c.github.io/manifest/) to allow Mobile devices to add the web application to your homescreen as if it was a native application. +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. On Android: 1. Open Chrome 2. Navigate to your Home Assistant instance - 3. Click on the menu icon (three vertical dots) - 4. Click on Add to Homescreen - 5. A dialog will popup, click on Add + 3. Tap on the Menu icon (three vertical bars) + 4. Tap on Add to Homescreen + 5. A dialog will popup; tap on Add

    @@ -27,6 +27,6 @@ On iOS: 1. Open Safari 2. Navigate to your Home Assistant instance - 3. Click on the share icon in the middle of the toolbar (on the bottom) - 4. Click on Add to Home Screen - 5. A dialog will popup, click on Add + 3. Tap on the Share icon in the middle of the bottom toolbar + 4. Tap on "Add to Home Screen" + 5. A dialog will popup; tap on Add diff --git a/source/getting-started/automation-create-first.markdown b/source/getting-started/automation-create-first.markdown index 22a6bc38cea..9f9f4f5f1e7 100644 --- a/source/getting-started/automation-create-first.markdown +++ b/source/getting-started/automation-create-first.markdown @@ -26,9 +26,9 @@ automation: 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 is 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`. +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. +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 diff --git a/source/getting-started/automation-trigger.markdown b/source/getting-started/automation-trigger.markdown index 0fd59bde246..f47c0a1c695 100644 --- a/source/getting-started/automation-trigger.markdown +++ b/source/getting-started/automation-trigger.markdown @@ -141,5 +141,5 @@ automation: entity_id: device_tracker.paulus zone: zone.home # Event is either enter or leave - event: enter + event: enter # or "leave" ``` diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index dea2435fd7e..435039e1937 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -9,15 +9,15 @@ 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 mainly you'll be using the automation component to set up your own rules. +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 automations. 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 automation configurations [publicly available][cookbook-config]. +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 ### {% linkable_title Automation basics %} -Before you can go ahead and create your own automations, it's important to learn the basics. To explore the basics, let's have a look at the following example home automation rule: +Before you can go ahead and create your own automations, it's important to learn the basics. To explore these, let's have a look at the following example home automation rule: ```text (trigger) When Paulus arrives home @@ -27,19 +27,19 @@ Before you can go ahead and create your own automations, it's important to learn The example consists of three different parts: a trigger, a condition and an 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'. +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'. -The second line is the condition part of the automation rule. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case we only want to act when the sun has set. +The second line is the **condition**. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set. -The third part is the action which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene. +The third part is the **action**, which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.

    -The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on vs a light being on. +The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on versus a light being on.

    ### {% linkable_title Exploring the internal state %} -Automation rules interact directly with the internal state of Home Assistant so you'll need to familiarize yourself with it. Home Assistant exposes it's current state via the developer tools which are available at the bottom of the sidebar in the frontend. The icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: +Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. The icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: | Name | Description | Example | | ---- | ----- | ---- | diff --git a/source/getting-started/autostart-macos.markdown b/source/getting-started/autostart-macos.markdown index c61bf57331d..d0c5798665e 100644 --- a/source/getting-started/autostart-macos.markdown +++ b/source/getting-started/autostart-macos.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Autostart on OS X" -description: "Instructions how to setup Home Assistant to launch on OS X." +title: "Autostart on macOS" +description: "Instructions how to setup Home Assistant to launch on Apple macOS." date: 2015-9-1 22:57 sidebar: true comments: false @@ -9,7 +9,7 @@ sharing: true footer: true --- -Setting up Home Assistant to run as a background service is simple. OS X will start it on boot and make sure it's always running. +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. To get Home Assistant installed as a background service, run: diff --git a/source/getting-started/autostart-systemd.markdown b/source/getting-started/autostart-systemd.markdown index f3e90be5959..245b9f9e64e 100644 --- a/source/getting-started/autostart-systemd.markdown +++ b/source/getting-started/autostart-systemd.markdown @@ -35,6 +35,23 @@ WantedBy=multi-user.target EOF' ``` +If you've setup Home Assistant in virtualenv following the guide the following template should work for you. + +``` +[Unit] +Description=Home Assistant +After=network.target + +[Service] +Type=simple +User=hass +ExecStartPre=source /srv/hass/bin/activate +ExecStart=/srv/hass/bin/hass -c "/home/hass/.homeassistant" + +[Install] +WantedBy=multi-user.target +``` + There is also another [sample service file](https://raw.githubusercontent.com/home-assistant/home-assistant/master/script/home-assistant%40.service) available. To use this one, just download it. ```bash diff --git a/source/getting-started/basic.markdown b/source/getting-started/basic.markdown index f9b4d69fada..f8cb5b33cc6 100644 --- a/source/getting-started/basic.markdown +++ b/source/getting-started/basic.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -By default Home Assistant will try to detect your location and will automatically select a temperature unit and time zone based on your location. You can overwrite this by adding the following information to your `configuration.yaml`: +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`: ```yaml homeassistant: @@ -35,7 +35,7 @@ homeassistant: ### {% linkable_title Password protecting the web interface %} -The first thing you will want to add is a password for the web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section: +First, you'll want to add a password for the Home Assistant web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section: ```yaml http: @@ -43,26 +43,24 @@ http: ```

    -If you are planning to expose your Home Assistant instance to the internet and don't set a password then your installation could be accessed by everybody. +If you decide to expose your Home Assistant instance to the internet and forget to set a password, your installation could be accessed by everybody.

    -See the [HTTP component documentation](/components/http/) for more options like HTTPS encryption. +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 contains support to be added to your home screen. If you're on Android you can 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 option. - +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 %} -To make Home Assistant accessible while away from home, you will have to make it accessible. +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. Instructions on how to do this can be found by searching ` port forwarding instructions`. +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`. -The problem with making a port accessible is that some Internet service providers will only offer dynamic IPs. This can cause you to be unable to access Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/). +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/). -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. +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/getting-started/browsers.markdown b/source/getting-started/browsers.markdown index aa46de88274..a45460a227f 100644 --- a/source/getting-started/browsers.markdown +++ b/source/getting-started/browsers.markdown @@ -25,7 +25,7 @@ We would appreciate if you help to keep this page up-to-date and add feedback. | [Firefox] | 43.0.1 | works | | | [Iridium] | 48.2 | works | | -## {% linkable_title MacOS %} +## {% linkable_title macOS %} | Browser | Release | State | Comments | | :-------------------- |:---------------|:-----------|:-------------------------| @@ -35,9 +35,9 @@ We would appreciate if you help to keep this page up-to-date and add feedback. | Browser | Release | State | Comments | | :-------------------- |:---------------|:-----------|:-------------------------| -| [Firefox] | 47.0 | works | | +| [Firefox] | 49.0 | works | | | [Midori] | 0.5.11 | works | | -| [Chromium] | 50.0.2661.102 | works | | +| [Chromium] | 53.0.2785.143 | works | | | [Conkeror] | 1.0.2 | works | | | [Konqueror] | | unknown | | | [Uzbl] | 0.9.0 | works | | diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index 50f2b82f18b..5561cb24ffb 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the user interface. +When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and appear in the user interface. The location of the folder differs between operating systems: @@ -21,7 +21,7 @@ The location of the folder differs between operating systems: If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`. -Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is. Throughout the documentation you will find snippets that you can add to your configuration file to enable that functionality. +Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains components to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality.

    You will have to restart Home Assistant for changes to `configuration.yaml` to take effect. diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index a3d0d220257..feee3871cee 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -25,7 +25,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 prefer to watch a video tutorial, [tktino](https://github.com/tktino) has made some great ones. +If you prefer to watch a video tutorial, [tktino](https://github.com/tktino) has made some great ones: - [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY) - [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls) @@ -41,9 +41,9 @@ If you run into any issues, please see [the troubleshooting page](/getting-start 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. + - [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? %} diff --git a/source/getting-started/installation-raspberry-pi-image.markdown b/source/getting-started/installation-raspberry-pi-image.markdown index 7ba140cec80..a22a0b38ba6 100644 --- a/source/getting-started/installation-raspberry-pi-image.markdown +++ b/source/getting-started/installation-raspberry-pi-image.markdown @@ -46,30 +46,38 @@ To login to your Raspberry Pi running HASSbian your going to be using a ssh clie Connect to the Raspberry Pi over ssh. Default user name is `pi` and password is `raspberry`. Linux and Mac OS users execute the following command in a terminal. + ```bash $ ssh pi@ip-address-of-pi ``` + Windows users start [Putty][ssh-putty], enter the IP address of the Raspberry Pi in the *Host name* field and port 22 in the *Port* field. Then click *Open* and a terminal window will open. Enter the credentials. Default user name is `pi` and password is `raspberry`. #### {% linkable_title Start/Stop/Restart Home Assistant on HaSSbian %} Log in as the `pi` account account and execute the following commands: + ```bash -sudo systemctl stop home-assistant@homeassistant.service +$ sudo systemctl stop home-assistant@homeassistant.service ``` + Replace `stop` with `start` or `restart` to get the desired functionality. To get the current state of the `homeassistant.service` replace `stop` with `status`. #### {% linkable_title Update Home Assistant on HASSbian %} + Log in as the `pi` account and execute the following commands: + ```bash -sudo systemctl stop home-assistant@homeassistant.service -sudo su -s /bin/bash homeassistant -source /srv/homeassistant/bin/activate -pip3 install --upgrade homeassistant -exit -sudo systemctl start home-assistant@homeassistant.service +$ sudo systemctl stop home-assistant@homeassistant.service +$ sudo su -s /bin/bash homeassistant +$ source /srv/homeassistant/bin/activate +$ pip3 install --upgrade homeassistant +$ exit +$ sudo systemctl start home-assistant@homeassistant.service ``` + This will in order do the following: + - Stop the Home Assistant service running on HASSbian - Open a shell as the `homeassistant` user running the Homeassistant service and that has ownership over the Home Assistant installation. - Change into the virtual Python environment at `/src/homeassistant/` containing the Home Assistant installation. @@ -79,60 +87,74 @@ This will in order do the following: #### {% linkable_title Manually launch Home Assistant on HASSbian %} Log in as the `pi` account and execute the following commands: + ```bash -sudo su -s /bin/bash homeassistant -source /srv/homeassistant/bin/activate -hass +$ sudo su -s /bin/bash homeassistant +$ source /srv/homeassistant/bin/activate +$ hass ``` + This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first. #### {% linkable_title Check your configuration on HASSbian %} Log in as the `pi` account and execute the following commands: + ```bash -sudo su -s /bin/bash homeassistant -source /srv/homeassistant/bin/activate -hass --script check_config +$ sudo su -s /bin/bash homeassistant +$ source /srv/homeassistant/bin/activate +$ hass --script check_config ``` + This will output any errors in your configuration files to console. #### {% linkable_title Read the Home Assistant log file on HASSbian %} Log in as the `pi` account and execute the following commands: + ```bash -sudo su -s /bin/bash homeassistant -cd /home/homeassistant/.homeassistant -nano homeassistant.log +$ sudo su -s /bin/bash homeassistant +$ cd /home/homeassistant/.homeassistant +$ nano homeassistant.log ``` + This will in order do the following: + - Open a shell as the `homeassistant` user. - Change directory to the Home Assistant configuration directory. - Open the log file in the nano editor. -Optionaly, you can also view the log with `journalctl`. +Optionaly, you can also view the log with `journalctl`. Log in as the `pi` account and execute the following commands: + ```bash -sudo journalctl -fu home-assistant@homeassistant.service +$ sudo journalctl -fu home-assistant@homeassistant.service ``` #### {% linkable_title Edit the Home Assistant configuration on HASSbian %} Log in as the `pi` account and execute the following commands: + ```bash -sudo su -s /bin/bash homeassistant -cd /home/homeassistant/.homeassistant -nano configuration.yaml +$ sudo su -s /bin/bash homeassistant +$ cd /home/homeassistant/.homeassistant +$ nano configuration.yaml ``` + This will in order do the following: + - Open a shell as the `homeassistant` user. - Change directory to the Home Assistant configuration directory. - Open the configuration file in the nano editor. + It's generally recommended that you read the [Getting started][configuring-homeassistant] guide for how to configure Home Assistant. #### {% linkable_title Upgrade and update HASSbian %} HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following. Log in as the `pi` account and execute the following commands: + ```bash -sudo apt-get update -sudo apt-get upgrade +$ sudo apt-get update +$ sudo apt-get upgrade ``` + Press `Y` to confirm that you would like to continue. ### {% linkable_title Troubleshooting %} diff --git a/source/getting-started/installation-synology.markdown b/source/getting-started/installation-synology.markdown index cdd9d9358c3..114d3629055 100644 --- a/source/getting-started/installation-synology.markdown +++ b/source/getting-started/installation-synology.markdown @@ -46,7 +46,7 @@ $ ./python3 -m ensurepip Use PIP to install Homeassistant package ```bash -$ ./python3 pip install homeassistant +$ ./python3 -m pip install homeassistant ``` Create homeassistant config directory & switch to it diff --git a/source/getting-started/securing.markdown b/source/getting-started/securing.markdown index 690d8a210a0..9ed36dc13f7 100644 --- a/source/getting-started/securing.markdown +++ b/source/getting-started/securing.markdown @@ -9,20 +9,21 @@ sharing: true footer: true --- -One of the reasons to use Home Assistant is that it's not depending on cloud services. Even if you are only using Home Assistant in your local network, you should consider securing your instance. +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. ### {% linkable_title Checklist %} - [Protect your web interface with a password](https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface) - Secure your host. Sources could be [Red Hat Enterprise Linux 7 Security Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/pdf/Security_Guide/Red_Hat_Enterprise_Linux-7-Security_Guide-en-US.pdf), [CIS Red Hat Enterprise Linux 7 Benchmark](https://benchmarks.cisecurity.org/tools2/linux/CIS_Red_Hat_Enterprise_Linux_7_Benchmark_v1.0.0.pdf), or the [Securing Debian Manual](https://www.debian.org/doc/manuals/securing-debian-howto/index.en.html). -- Restrict network access to your device. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use keys for authentication instead of passwords. -- Don't run Home Assistant as root. +- Restrict network access to your devices. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use SSH keys for authentication instead of passwords. +- Don't run Home Assistant as root – consider the Principle of Least Privilege. - Keep your [secrets](/topics/secrets/) safe. -Additional points if you want to allow remote access: +If you want to allow remote access, consider these additional points: -- Protect your communication with [TLS](blog/2015/12/13/setup-encryption-using-lets-encrypt/) +- Protect your communication with [TLS](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) - Protect your communication with [Tor](/cookbook/tor_configuration/) +- Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/) - Use a [proxy](/cookbook/apache_configuration/) diff --git a/source/getting-started/updating.markdown b/source/getting-started/updating.markdown index 0da8ad75536..cceed8df558 100644 --- a/source/getting-started/updating.markdown +++ b/source/getting-started/updating.markdown @@ -18,18 +18,18 @@ $ pip3 install --upgrade homeassistant Different installation methods as [HASSbian](/getting-started/installation-raspberry-pi-image/#update-home-assistant-on-hassbian), [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) may have an alternative way for updating Home Assistant. -After updating, restart Home Assistant for the changes to take effect. This means that you have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon if you use any. +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)

    - The upgrade needs to be run as the same user as the installation was done to avoid permission errors. + To avoid permission errors, the upgrade must be run as the same user as the installation was completed.

    [BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant. #### {% linkable_title Run a specific version %} -It can happen that a version doesn't play well with your hardware setup. If that's the case you can downgrade to a previous release. +In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release: ```bash $ pip3 install homeassistant==0.XX.X @@ -37,10 +37,10 @@ $ pip3 install homeassistant==0.XX.X #### {% linkable_title Run the development version %} -If you want to stay on top of the development of Home Assistant then you can upgrade to the `dev` branch. +If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`.

    - This can result in an unstable system, loss of data, etc. etc. + The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption.

    ```bash diff --git a/source/getting-started/z-wave.markdown b/source/getting-started/z-wave.markdown index b1301dd53cd..5a4ba4f1cd3 100644 --- a/source/getting-started/z-wave.markdown +++ b/source/getting-started/z-wave.markdown @@ -23,10 +23,10 @@ Make sure you have the correct dependencies installed before running the script: $ sudo apt-get install cython3 libudev-dev python3-sphinx python3-setuptools ``` -Make sure you have at least version 0.23 of cython. +Make sure you have at least version 0.23 and at the most 0.24.1 of cython. ```bash -$ sudo pip3 install --upgrade cython +$ sudo pip3 install --upgrade cython==0.24.1 ``` Then get the OpenZWave files and switch to the `python3` branch: @@ -43,14 +43,13 @@ $ sudo PYTHON_EXEC=$(which python3) make install

    Instead of `make install`, you can alternatively build your own python-openzwave package which can be easily uninstalled: +

    ```bash $ sudo apt-get install -y checkinstall $ sudo PYTHON_EXEC=$(which python3) checkinstall --pkgname python-openzwave --pkgversion 1.0 --provides python-openzwave ``` -

    - With this installation, your `config_path` needed below will resemble: ```bash diff --git a/source/images/ios/NotificationActionFlow.png b/source/images/ios/NotificationActionFlow.png new file mode 100644 index 00000000000..c356c32ff00 Binary files /dev/null and b/source/images/ios/NotificationActionFlow.png differ diff --git a/source/images/ios/PushNotificationLayout.png b/source/images/ios/PushNotificationLayout.png new file mode 100644 index 00000000000..6bb2da8c41a Binary files /dev/null and b/source/images/ios/PushNotificationLayout.png differ diff --git a/source/images/ios/actions.png b/source/images/ios/actions.png new file mode 100644 index 00000000000..d4970f28dfc Binary files /dev/null and b/source/images/ios/actions.png differ diff --git a/source/images/ios/attachment.png b/source/images/ios/attachment.png new file mode 100644 index 00000000000..2b30ec7ab27 Binary files /dev/null and b/source/images/ios/attachment.png differ diff --git a/source/images/ios/control1.png b/source/images/ios/control1.png new file mode 100644 index 00000000000..0c29f917dd0 Binary files /dev/null and b/source/images/ios/control1.png differ diff --git a/source/images/ios/control2.png b/source/images/ios/control2.png new file mode 100644 index 00000000000..2b59af8c232 Binary files /dev/null and b/source/images/ios/control2.png differ diff --git a/source/images/ios/example.png b/source/images/ios/example.png new file mode 100644 index 00000000000..42b6e74a2c2 Binary files /dev/null and b/source/images/ios/example.png differ diff --git a/source/images/ios/expanded_attachment.png b/source/images/ios/expanded_attachment.png new file mode 100644 index 00000000000..c26c44716a9 Binary files /dev/null and b/source/images/ios/expanded_attachment.png differ diff --git a/source/images/ios/map.png b/source/images/ios/map.png new file mode 100644 index 00000000000..cf84e0f242a Binary files /dev/null and b/source/images/ios/map.png differ