diff --git a/README.markdown b/README.markdown index d7531a67054..32421af2737 100644 --- a/README.markdown +++ b/README.markdown @@ -4,15 +4,11 @@ This is the source for the [Home Assistant](https://github.com/balloob/home-assi Please point your Pull Request (PR) at the `next` branch. -## Jekyll project to generate and deploy +## Preview Jekyll website locally | Command | Action | |---|---| | `rake preview` | Preview site on [http://127.0.0.1:4000](http://127.0.0.1:4000) -| `rake generate` | Generate new version of the site -| `rake deploy` | Deploy a new version of the site - -_Generating and deploying is no longer necessary as we now have auto-deply._ ## Setup @@ -27,36 +23,6 @@ $ cd home-assistant.io $ bundle ``` -## Create a new blog post - -```bash -$ rake new_post["title"] -``` - -## Site preview - -```bash -$ rake preview -``` - -The preview is now available on [http://127.0.0.1:4000](http://127.0.0.1:4000). - -## Steps for the deployment of the site - -All developers with write access to the repositories are able to deploy the website. The deploy process is fully automated with `rake generate && rake deploy`. - -```bash -$ git submodule update --init -$ cd _deploy -$ git fetch -$ git pull origin gh-pages -$ cd .. -$ rake generate && rake deploy -``` -```bash -TZ=UTC rake generate && rake deploy -``` - ### Setup on Fedora and CentOS On Fedora > 22 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. diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index 0cfeb9a1153..fd378d865f8 100644 --- a/source/_components/alexa.markdown +++ b/source/_components/alexa.markdown @@ -9,17 +9,50 @@ sharing: true footer: true logo: amazon-echo.png ha_category: Voice -featured: false +featured: true --- -The Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. There are no supported sentences out of the box as of now, you will have to define them all yourself. +There are two ways that you can use Amazon Echo and Home Assistant together. + +No matter which method(s) you decide to use, please remember that Amazon Echo requires an active Internet connection to function. If your Internet is down or experiencing issues (or Amazon's infrastructure is having issues), neither of these methods will work. + +### {% linkable_title I just want to turn devices on and off using Echo %} + +If you just want to be able to turn anything with a switch (like lights, switches, media players, etc) on and off, check out Michael Auchter's [Haaska][haaska-github-link] which integrates the [Alexa Lighting API][alexa-lighting-api] into Home Assistant. + +[haaska-github-link]: https://github.com/auchter/haaska +[alexa-lighting-api]: https://developer.amazon.com/public/binaries/content/assets/html/alexa-lighting-api.html + +Implementing Haaska means you can turn things on and off by simply saying + +> Alexa, turn the living room lights on. + +or + +> Alexa, set the living room lights to twenty percent. + +instead of + +> Alexa, tell Home Assistant to turn the living room lights on. + +or + +> Alexa, tell Home Assistant to set the living room lights to twenty percent. + +In addition, you would need to build custom intents for each device and on/off combination using the below method, whereas everything just works without any extra work by using Haaska. + +Please note that you can use Haaska and the built-in Alexa component side-by-side without issue if you wish. + +### {% linkable_title I want to build custom commands to use with Echo %} + +The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. There are no supported sentences out of the box as of now, you will have to define them all yourself.
-### {% linkable_title Requirements before using %} -Amazon requires the endpoint of a skill to be hosted via SSL. Self-signed certificates are ok because our skills will only run in development mode. Read more on [our blog][blog-lets-encrypt] about how to set up encryption for Home Assistant. If you are unable to get https up and running, consider using [this AWS Lambda proxy for Alexa skills](https://forums.developer.amazon.com/forums/thread.jspa?messageID=18604). +#### {% linkable_title Requirements before using %} +Amazon requires the endpoint of a skill to be hosted via SSL. Self-signed certificates are ok because our skills will only run in development mode. Read more on [our blog][blog-lets-encrypt] about how to set up encryption for Home Assistant. If you are unable to get HTTPS up and running, consider using [this AWS Lambda proxy for Alexa skills](https://forums.developer.amazon.com/forums/thread.jspa?messageID=18604). [blog-lets-encrypt]: https://home-assistant.io/blog/2015/12/13/setup-encryption-using-lets-encrypt/ @@ -35,7 +68,7 @@ To get started with Alexa skills: - https - https://YOUR_HOST/api/alexa?api_password=YOUR_API_PASSWORD -### {% linkable_title Configuring your Amazon Alexa skill %} +#### {% linkable_title Configuring your Amazon Alexa skill %} Alexa works based on intents. Each intent has a name and variable slots. For example, a `LocateIntent` with a slot that contains a `User`. Example intent schema: diff --git a/source/_components/automation.markdown b/source/_components/automation.markdown index 6d592a7307c..85550695486 100644 --- a/source/_components/automation.markdown +++ b/source/_components/automation.markdown @@ -15,6 +15,10 @@ This page will go into more detail about the various options the `automation` co A configuration section of an automation requires a `trigger` and an `action` section. `condition` and `condition_type` are optional. To keep this page compact, all following sections will not show the full configuration but only the relevant part. + - [Jump to conditions](#conditions) + - [Jump to actions](#actions) + - [Jump to troubleshooting](#troubleshooting) + ```yaml # Example of entry in configuration.yaml automation: @@ -69,10 +73,6 @@ automation: message: 'Paulus left the house' ``` - - [Jump to conditions](#conditions) - - [Jump to actions](#actions) - - [Jump to troubleshooting](#troubleshooting) - ## {% linkable_title Triggers %} Triggers are what starts the processing of an automation rule. It is possible to specify multiple triggers for the same rule. Once a trigger starts, Home Assistant will validate the conditions, if any, and call the action. @@ -207,9 +207,9 @@ automation: ## {% linkable_title Conditions %} -Conditions are an optional part of an automation rule and be used to prevent an action from happening when triggered. Conditions look very familiar to triggers but are very different. A trigger will look at events happening at the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is on or off. +Conditions are an optional part of an automation rule and be used to prevent an action from happening when triggered. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off. -An automation rule can have mulitiple conditions. By default the action will only fire if all conditions pass. An optional key `condition_type: 'or'` can be set on the automation rule to fire action if any condition matches. In the example below, the automation would trigger if the time is before 05:00 _OR_ after 20:00. +An automation rule can have multiple conditions. By default the action will only fire if all conditions pass. An optional key `condition_type: 'or'` can be set on the automation rule to fire action if any condition matches. In the example below, the automation would trigger if the time is before 05:00 _OR_ after 20:00. ```yaml automation: @@ -230,18 +230,17 @@ automation: #### {% linkable_title Numeric state condition %} -Attempts to parse the state of specified entity as a number and triggers if value is above and/or below a threshold. +This type of condition attempts to parse the state of specified entity as a number and triggers if the value matches all of the above or below thresholds. +Either `above` or `below`, or both need to be specified. If both are used, the condition is true when the value is >= `before` *and** < `after`. +You can optionally use a `value_template` to make the value of the entity the same type of value as the condition. ```yaml automation: condition: platform: numeric_state entity_id: sensor.temperature - # At least one of the following required above: 17 below: 25 - # Optional - value_template: '{% raw %}{{ state.attributes.battery }}{% endraw %}' ``` #### {% linkable_title State condition %} @@ -259,7 +258,6 @@ automation: hours: 1 minutes: 10 seconds: 5 - ``` #### {% linkable_title Sun condition %} @@ -277,7 +275,7 @@ automation: #### {% linkable_title Template condition %} -The template condition will test if [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. +The template condition will test if the [given template][template] renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render 'true'. ```yaml @@ -322,7 +320,7 @@ automation: ## {% linkable_title Actions %} -When an automation rule fires, it calls a service. For this service you can specify an entity id it should apply to and optional service parameters (to specify for example the brightness). +When an automation rule fires, it calls a service. For this service you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness). ```yaml automation: @@ -346,11 +344,11 @@ automation: message: Something just happened, better take a look! ``` -If you want to specify multiple services to be called or include a delay, have a look at the [script component](/components/script/). If you want to describe how certain entities should look, check out the [scene component](/components/scene/). +If you want to specify multiple services to be called, or to include a delay, have a look at the [script component](/components/script/). If you want to describe the desired state of certain entities, check out the [scene component](/components/scene/). ## {% linkable_title Troubleshooting %} -You can verify that your automation rules are being initialized correctly by watching both the realtime logs and also the logbook. The realtime logs will show the rules being initialized (once for each trigger): +You can verify that your automation rules are being initialized correctly by watching both the realtime logs (`homeassistant.log` in the configuration directory) and also the [Logbook](/components/logbook/). The realtime logs will show the rules being initialized (once for each trigger), example: ```plain INFO [homeassistant.components.automation] Initialized rule Rainy Day @@ -359,7 +357,7 @@ INFO [homeassistant.components.automation] Initialized rule Rainy Day INFO [homeassistant.components.automation] Initialized rule Rain is over ``` -The Logbook component will show a line entry when an automation is triggered. You can look at the previous entry to determine which trigger in the rule triggered the event. +The Logbook component will show a line entry when an automation is triggered. You can look at the previous entry to determine which trigger in the rule triggered the event. ![Logbook example](/images/components/automation/logbook.png) diff --git a/source/_components/binary_sensor.rest.markdown b/source/_components/binary_sensor.rest.markdown index e1fac78ddce..d6fc619a1a4 100644 --- a/source/_components/binary_sensor.rest.markdown +++ b/source/_components/binary_sensor.rest.markdown @@ -22,6 +22,7 @@ binary_sensor: resource: http://IP_ADDRESS/ENDPOINT method: GET name: REST GET binary sensor + sensor_class: opening value_template: '{% raw %}{{ value_json.state }}{% endraw %}' ``` @@ -33,18 +34,20 @@ binary_sensor: platform: rest resource: http://IP_ADDRESS/ENDPOINT method: POST + name: REST POST binary sensor + sensor_class: opening value_template: '{% raw %}{{ value_json.state }}{% endraw %}' payload: '{ "device" : "door" }' - name: REST POST binary sensor ``` Configuration variables: - **resource** (*Required*): The resource or endpoint that contains the value. - **method** (*Optional*): The method of the request. Default is GET. +- **name** (*Optional*): Name of the REST binary sensor. +- **sensor_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend. - **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. -- **name** (*Optional*): Name of the REST binary sensor.

Make sure that the URL matches exactly your endpoint or resource. diff --git a/source/_components/binary_sensor.tcp.markdown b/source/_components/binary_sensor.tcp.markdown index e328ffb034f..9cd1be3043b 100644 --- a/source/_components/binary_sensor.tcp.markdown +++ b/source/_components/binary_sensor.tcp.markdown @@ -10,23 +10,22 @@ footer: true ha_category: Binary Sensor --- - The TCP Binary Sensor is a type of [TCP Sensor](/components/sensor.tcp/) which is either "off" or "on". In order to use this sensor type, in addition to the configuration for the TCP Sensor, you must supply a `value_on` value to represent what is returned when the device is turned on. To enable this sensor, add the following lines to your `configuration.yaml`: ```yaml -sensor: +binary_sensor: # Example configuration.yaml entry - - platform: tcp - name: TCP Binary Sensor - host: IP_ADDRESS - port: PORT - payload: "r State\n" - value_on: 1 - timeout: 5 - value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" - unit: UNIT_OF_MEASUREMENT + platform: tcp + name: TCP Binary Sensor + host: IP_ADDRESS + port: PORT + payload: "r State\n" + value_on: 1 + timeout: 5 + value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" + buffer_size: BUFFER_SIZE ``` Configuration options for the a TCP Sensor: @@ -38,6 +37,5 @@ Configuration options for the a TCP Sensor: - **value_on** (*Required*): The value returned when the device is "on". - **timeout** (*Optional*): How long in seconds to wait for a response from the service before giving up and disconnecting. Defaults to 10. - **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the value. By default it's assumed that the entire response is the value. -- **unit** (*Optional*): The unit of measurement to use for the value. - **buffer_size** (*Optional*): The size of the receive buffer in bytes. Set this to a larger value if you expect to receive a response larger than the default. Defaults to 1024. diff --git a/source/_components/binary_sensor.vera.markdown b/source/_components/binary_sensor.vera.markdown new file mode 100644 index 00000000000..b8004fa74bb --- /dev/null +++ b/source/_components/binary_sensor.vera.markdown @@ -0,0 +1,17 @@ +--- +layout: page +title: "Vera Binary Sensor" +description: "Instructions how to integrate Vera binary sensors into Home Assistant." +date: 2016-03-26 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: vera.png +ha_category: Binary Sensor +ha_iot_class: "Local Push" +--- + +The `vera` platform allows you to get data from your [Vera](http://getvera.com/) binary sensors from within Home Assistant. + +They will be automatically discovered if the vera component is loaded. diff --git a/source/_components/camera.mjpeg.markdown b/source/_components/camera.mjpeg.markdown index 4f166f044c4..5cc0c6f3bff 100644 --- a/source/_components/camera.mjpeg.markdown +++ b/source/_components/camera.mjpeg.markdown @@ -31,3 +31,7 @@ Configuration variables: - **name** *Optional*: This parameter allows you to override the name of your camera. - **username** *Optional*: The username for accessing your camera. - **password** *Optional*: The password for accessing your camera. + +

+There is a known issue in urllib3 that you will get error messages in your logs like [StartBoundaryNotFoundDefect(), MultipartInvariantViolationDefect()], unparsed data: '' but the component still works fine. You can ignore the messages. +

diff --git a/source/_components/conversation.markdown b/source/_components/conversation.markdown index 720b6f46be9..8e52a6927a1 100644 --- a/source/_components/conversation.markdown +++ b/source/_components/conversation.markdown @@ -12,7 +12,8 @@ ha_category: "Voice" --- -The conversation component can process sentences into commands for Home Assistant. It is currently limited to parsing commands in the format `turn `. +The conversation component can process sentences into commands for Home Assistant. It is currently limited to parsing commands in the format `turn `. + To enable the conversion option in your installation, add the following to your `configuration.yaml` file: @@ -26,3 +27,7 @@ When this component is active and you are using a supported browser voice comman

+ +

+Apple iPhones do not support this feature in any browser. +

diff --git a/source/_components/ecobee.markdown b/source/_components/ecobee.markdown index 69879ddab9a..529a293ad0e 100644 --- a/source/_components/ecobee.markdown +++ b/source/_components/ecobee.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: ecobee.png ha_category: Hub +featured: true --- diff --git a/source/_components/http.markdown b/source/_components/http.markdown index a05b058d1f7..e66976ca8d5 100644 --- a/source/_components/http.markdown +++ b/source/_components/http.markdown @@ -33,8 +33,8 @@ Configuration variables: On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. -The `http` platforms are not a real platform within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) is consuming and proceeding messages received over HTTP. +The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP. To use those kind of sensors in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. -All [requests](/developers/rest_api/#post-apistatesltentity_id) needs to be sent to the endpoint of the device and must be **POST**. +All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent to the endpoint of the device and must be **POST**. diff --git a/source/_components/influxdb.markdown b/source/_components/influxdb.markdown index 32ed6d6ac39..b17c53fd144 100644 --- a/source/_components/influxdb.markdown +++ b/source/_components/influxdb.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: influxdb.png ha_category: "History" +featured: true --- The `influxdb` component makes it possible to transfer all state changes to an external [InfluxDB](https://influxdb.com/) database. For more details, [see the blog post on InfluxDB](/blog/2015/12/07/influxdb-and-grafana/). @@ -25,6 +26,9 @@ influxdb: password: MY_PASSWORD ssl: true verify_ssl: true + blacklist: + - entity.id1 + - entity.id2 ``` Configuration variables: @@ -36,3 +40,4 @@ Configuration variables: - **password** (*Optional*): The password for the database user account. - **ssl** (*Optional*): Use https instead of http to connect. Defaults to false. - **verify_ssl** (*Optional*): Verify SSL certificate for https request. Defaults to false. +- **blacklist** (*Optional*): List of entities not logged to influxdb. diff --git a/source/_components/input_boolean.markdown b/source/_components/input_boolean.markdown index 2fcdedc64b4..68d26181d13 100644 --- a/source/_components/input_boolean.markdown +++ b/source/_components/input_boolean.markdown @@ -17,7 +17,7 @@ The `input_boolean` component allows the user to define boolean values that can # Example configuration.yaml entry input_boolean: notify_home: - name: Notify when someome arrives home + name: Notify when someone arrives home initial: off icon: mdi:car ``` @@ -31,3 +31,22 @@ Configuration variables: Pick an icon that you can find on [materialdesignicons.com](https://materialdesignicons.com/) to use for your input and prefix the name with `mdi:`. For example `mdi:car`, `mdi:ambulance`, or `mdi:motorbike`. +Here's an example of an automation using the above input_boolean. This action will only occur if the switch is on. + +```yaml +automation: + alias: Arriving home + trigger: + platform: state + entity_id: binary_sensor.motion_garage + to: 'on' + condition: + platform: state + entity_id: input_boolean.notify_home + state: 'on' + action: + service: notify.pushbullet + data: + title: "" + message: "Honey, I'm home!" +``` diff --git a/source/_components/light.hue.markdown b/source/_components/light.hue.markdown index 1236a070420..c6bc83680df 100644 --- a/source/_components/light.hue.markdown +++ b/source/_components/light.hue.markdown @@ -28,7 +28,7 @@ light: Configuration variables: -- **host** (*Required*): IP address aof the device, eg. 192.168.1.10. +- **host** (*Required*): IP address of the device, eg. 192.168.1.10. - **allow_unreachable** (*Optional*): This will allow unreachable bulbs to report their state correctly. By default *name* from the device is used. - **filename** (*Optional*): Make this unique if specifying multiple Hue hubs. diff --git a/source/_components/light.rfxtrx.markdown b/source/_components/light.rfxtrx.markdown index 076f8efb495..c16b42a4b20 100644 --- a/source/_components/light.rfxtrx.markdown +++ b/source/_components/light.rfxtrx.markdown @@ -23,6 +23,7 @@ light: living_room: name: Living Room packetid: XXXXX + fire_event: True automatic_add: True ``` @@ -31,3 +32,4 @@ 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 lights. - **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. diff --git a/source/_components/light.vera.markdown b/source/_components/light.vera.markdown index 3ed552548a4..810ea94cfca 100644 --- a/source/_components/light.vera.markdown +++ b/source/_components/light.vera.markdown @@ -9,31 +9,12 @@ sharing: true footer: true logo: vera.png ha_category: Light +ha_iot_class: "Local Push" --- +The `vera` platform allows you to control your [Vera](http://getvera.com/) lights from within Home Assistant. -This `vera` light platform allows you to control your [Vera](http://getvera.com/) lights. +They will be automatically discovered if the vera component is loaded. -This platform is useful if you wish for switches connected to your Vera controller to appear as lights in Home Assistant. All switches will be added as a light unless you exclude them in the configuration file. +For more configuration information see the [Vera component](/components/vera/) documentation. -To use your Vera lights in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -light: - platform: vera - vera_controller_url: http://YOUR_VERA_IP:3480/ - device_data: - 12: - name: My awesome sensor - exclude: true - 13: - name: Another sensor -``` - -Configuration variables: - -- **vera_controller_url** (*Required*): This is the base URL of your vera controller including the port number if not running on 80, eg. http://192.168.1.21:3480/ -- **device_data** array (*Optional*):This contains an array additional device information for your Vera devices. It is not required and if not specified all sensors configured in your Vera controller will be added with default values. You should use the id of your Vera device as the key for the device within `device_data`. - - **name** (*Optional*):This parameter allows you to override the name of your Vera device in the frontend, if not specified the value configured for the device in your Vera will be used. - - **exclude** (*Optional*): This parameter allows you to exclude the specified device, it should be set to "True" if you want this device excluded. diff --git a/source/_components/logger.markdown b/source/_components/logger.markdown index 66c521e09ea..3cb7a36d2f5 100644 --- a/source/_components/logger.markdown +++ b/source/_components/logger.markdown @@ -11,11 +11,11 @@ logo: home-assistant.png ha_category: "Other" --- -The logger component lets one define the level of logging activities in Home Assistant. +The logger component lets you define the level of logging activities in Home Assistant. To enable the logger in your installation, add the following to your `configuration.yaml` file: -By default log all messages and ignore log event lowest than critical for custom omponents. +By default log all messages and ignore events lower than critical for specified components. ```yaml # Example configuration.yaml entry @@ -26,7 +26,7 @@ logger: homeassistant.components.camera: critical ``` -By default ignore all messages lowest than critical and log event for custom components. +By default ignore all messages lower than critical and log event for specified components. ```yaml # Example configuration.yaml entry @@ -41,7 +41,7 @@ logger: Possible log severities are: -- citical +- critical - fatal - error - warning diff --git a/source/_components/media_player.sonos.markdown b/source/_components/media_player.sonos.markdown index 8b7dcc4e698..ebea7c807d6 100644 --- a/source/_components/media_player.sonos.markdown +++ b/source/_components/media_player.sonos.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Sonos" -description: "Instructions how to integrateSonos devices into Home Assistant." +description: "Instructions how to integrate Sonos devices into Home Assistant." date: 2015-09-12 13:00 sidebar: true comments: false @@ -23,3 +23,12 @@ media_player: platform: sonos ``` +You can also specify hosts to connect to if they cannot be found with auto-discovery. + +```yaml +# Example configuration.yaml entry +media_player: + platform: sonos + hosts: IP +``` + diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index 614af9061f8..718a44a3bbc 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -46,18 +46,22 @@ The MQTT component needs you to run an MQTT broker for Home Assistant to connect #### {% linkable_title Use the embedded broker %} -Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Asssistant connects to it. Default settings for the embedded broker: +Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Asssistant connects to it. Embedded broker default configuration: | Setting | Value | | ------- | ----- | | Host | localhost | Port | 1883 -| Version | 3.1 +| Protocol | 3.1.1 | User | homeassistant | Password | Your API password | Websocket port | 8080 -If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). +

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

+ +If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration. ```yaml # Example configuration.yaml entry diff --git a/source/_components/proximity.markdown b/source/_components/proximity.markdown index b42a218d441..8e6c6d2aeee 100644 --- a/source/_components/proximity.markdown +++ b/source/_components/proximity.markdown @@ -23,7 +23,7 @@ Some examples of its use include: The Proximity entity which is created has the following values: - `state`: Distance from the monitored zone (in km) -- `dir_of_travel`: Direction of the closest device to the monitoed zone. Values are: +- `dir_of_travel`: Direction of the closest device to the monitored zone. Values are: - 'not set' - 'arrived' - 'towards' diff --git a/source/_components/scene.markdown b/source/_components/scene.markdown index 3ba280133dc..8b3cd94cd9d 100644 --- a/source/_components/scene.markdown +++ b/source/_components/scene.markdown @@ -11,9 +11,7 @@ logo: home-assistant.png ha_category: Organization --- -A user can create scenes that capture the states you want certain entities to be. For example a scene can contain that light A should be turned on and light B should be bright red. - -Scenes can be activated using the service `scene.turn_on`. +You can create scenes that capture the states you want certain entities to be. For example a scene can specify that light A should be turned on and light B should be bright red. ```yaml # Example configuration.yaml entry @@ -33,3 +31,19 @@ scene: brightness: 100 light.ceiling: off ``` + +Scenes can be activated using the service `scene.turn_on` (there is no 'scene.turn_off' service). + +```yaml +# Example automation +... +automation: + trigger: + platform: state + entity_id: device_tracker.sweetheart + from: 'not_home' + to: 'home' + action: + service: scene.turn_on + entity_id: scene.romantic +``` diff --git a/source/_components/sensor.mqtt.markdown b/source/_components/sensor.mqtt.markdown index 7d55875f3f3..be3d99c3608 100644 --- a/source/_components/sensor.mqtt.markdown +++ b/source/_components/sensor.mqtt.markdown @@ -41,7 +41,7 @@ In this section you find some real life examples of how to use this sensor. ### {% linkable_title Get battery level %} -If you are using the [Owntracks](components/device_tracker.owntracks/) and enable the reporting of the battery level then you can use a MQTT sensor to keep track of your battery. A regular MQTT message from Owntracks looks like this: +If you are using the [Owntracks](/components/device_tracker.owntracks/) and enable the reporting of the battery level then you can use a MQTT sensor to keep track of your battery. A regular MQTT message from Owntracks looks like this: ```bash owntracks/tablet/tablet {"_type":"location","lon":7.21,"t":"u","batt":92,"tst":144995643,"tid":"ta","acc":27,"lat":46.12} @@ -56,6 +56,6 @@ sensor: state_topic: "owntracks/tablet/tablet" name: "Battery Tablet" unit_of_measurement: "%" - value_template: '{{ value_json.batt }}' + value_template: {% raw %}'{{ value_json.batt }}'{% endraw %} ``` diff --git a/source/_components/sensor.rest.markdown b/source/_components/sensor.rest.markdown index 5e55cdda28d..26c3203d471 100644 --- a/source/_components/sensor.rest.markdown +++ b/source/_components/sensor.rest.markdown @@ -45,7 +45,7 @@ Configuration variables: - **resource** (*Required*): The resource or endpoint that contains the value. - **method** (*Optional*): The method of the request. Default is GET. - **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. +- **payload** (*Optional*): The payload to send with a POST request. Depends on the service, but usually formed as JSON. - **name** (*Optional*): Name of the REST sensor. - **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any. @@ -66,7 +66,7 @@ In this section you find some real life examples of how to use this sensor. ### {% linkable_title External IP address %} -Always want to know your external IP address. [JSON Test](http://www.jsontest.com) will provide you this information at their http://ip.jsontest.com/ endpoint. +You can find your external IP address using the service [JSON Test](http://www.jsontest.com) at their http://ip.jsontest.com/ endpoint. To display the IP address, the entry for a sensor in the `configuration.yaml` file will look like this. @@ -93,7 +93,7 @@ Add something similar to the entry below to your `configuration.yaml` file: ### {% linkable_title Value for other Home Assistant instance %} -The Home Assistant [API](/developers/rest_api/) is exposing 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. +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. ```yaml diff --git a/source/_components/sensor.tcp.markdown b/source/_components/sensor.tcp.markdown index a6227a641bf..bbf501e7345 100644 --- a/source/_components/sensor.tcp.markdown +++ b/source/_components/sensor.tcp.markdown @@ -17,14 +17,14 @@ To enable this sensor, add the following lines to your `configuration.yaml`: ```yaml sensor: # Example configuration.yaml entry - - platform: tcp - name: Central Heating Pressure - host: IP_ADDRESS - port: PORT - timeout: 5 - payload: PAYLOAD - value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" - unit: UNIT_OF_MEASUREMENT + platform: tcp + name: Central Heating Pressure + host: IP_ADDRESS + port: PORT + timeout: 5 + payload: PAYLOAD + value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" + unit: UNIT_OF_MEASUREMENT ``` Configuration options for the a TCP Sensor: @@ -56,19 +56,19 @@ You will notice that the output from the service is not just a single value (it ```yaml sensor: # Example configuration.yaml entry - - platform: tcp - name: Central Heating Pressure - host: 10.0.0.127 - port: 8888 - timeout: 5 - payload: "r WaterPressure\n" - value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" - unit: Bar + platform: tcp + name: Central Heating Pressure + host: 10.0.0.127 + port: 8888 + timeout: 5 + payload: "r WaterPressure\n" + value_template: "{% raw %}{{ value.split(';')[0] }}{% endraw %}" + unit: Bar ``` ### {% linkable_title hddtemp %} -The tool `hddtemp` collects the temperatur of your harddisks. +The tool `hddtemp` collects the temperature of your harddisks. ```bash $ hddtemp @@ -90,12 +90,12 @@ The entry for the `configuration.yaml` file for a `hddtemp` sensor could look li ```yaml sensor: # Example configuration.yaml entry - - platform: tcp - name: HDD temperature - host: 127.0.0.1 - port: 7634 - timeout: 5 - payload: "\n" - value_template: "{% raw %}{{ value.split('|')[3] }}{% endraw %}" - unit: "°C" + platform: tcp + name: HDD temperature + host: 127.0.0.1 + port: 7634 + timeout: 5 + payload: "\n" + value_template: "{% raw %}{{ value.split('|')[3] }}{% endraw %}" + unit: "°C" ``` diff --git a/source/_components/sensor.vera.markdown b/source/_components/sensor.vera.markdown index eb634bf280a..da1c1124d17 100644 --- a/source/_components/sensor.vera.markdown +++ b/source/_components/sensor.vera.markdown @@ -9,29 +9,10 @@ sharing: true footer: true logo: vera.png ha_category: Sensor +ha_iot_class: "Local Push" --- +The `vera` platform allows you to get data from your [Vera](http://getvera.com/) sensors from within Home Assistant. + +They will be automatically discovered if the vera component is loaded. -This `vera` sensor platform allows you to get data from your [Vera](http://getvera.com/) sensors. - -To use your Vera sensor in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - platform: vera - vera_controller_url: http://YOUR_VERA_IP:3480/ - device_data: - 12: - name: My awesome sensor - exclude: true - 13: - name: Another sensor -``` - -Configuration variables: - -- **vera_controller_url** (*Required*): This is the base URL of your vera controller including the port number if not running on 80, eg. http://192.168.1.21:3480/ -- **device_data** array (*Optional*):This contains an array additional device information for your Vera devices. It is not required and if not specified all sensors configured in your Vera controller will be added with default values. You should use the id of your Vera device as the key for the device within `device_data`. - - **name** (*Optional*):This parameter allows you to override the name of your Vera device in the frontend, if not specified the value configured for the device in your Vera will be used. - - **exclude** (*Optional*): This parameter allows you to exclude the specified device, it should be set to "True" if you want this device excluded. diff --git a/source/_components/sun.markdown b/source/_components/sun.markdown index 18058bc1421..e5538d3a9e7 100644 --- a/source/_components/sun.markdown +++ b/source/_components/sun.markdown @@ -22,12 +22,12 @@ homeassistant: longitude: -117.22743 sun: - elevation: 123 + elevation: 102 ``` Configuration variables: -- **elevation** (*Optional*): The solar elevation angle is the altitude of the sun. If ommitted will be retrieved from Google Maps. +- **elevation** (*Optional*): The (physical) elevation of your location, in metres above sea level. If ommitted will be retrieved from Google Maps.

@@ -59,5 +59,6 @@ The sun event need to have the type 'sun', which service to call, which event (s | State Attributes | Description | | --------- | ----------- | -| `next_rising` | Date and time of the next sun rising -| `next_setting` | Date and time of the next sun setting +| `next_rising` | Date and time of the next sun rising (in UTC). +| `next_setting` | Date and time of the next sun setting (in UTC). +| `elevation` | Solar elevation. This is the angle between the sun and the horizon. Negative values mean the sun is below the horizon. diff --git a/source/_components/switch.command_line.markdown b/source/_components/switch.command_line.markdown index 6bba25ea65f..6ddb7baa179 100644 --- a/source/_components/switch.command_line.markdown +++ b/source/_components/switch.command_line.markdown @@ -75,7 +75,7 @@ switch: ### {% linkable_title Control your VLC player %} -This switch will control a local VLC media player ([Source](https://automic.us/forum/viewtopic.php?f=4&t=144)). +This switch will control a local VLC media player ([Source](https://community.home-assistant.io/t/vlc-player/106)). ```yaml diff --git a/source/_components/switch.rfxtrx.markdown b/source/_components/switch.rfxtrx.markdown index a0f7fbdd52d..9cb5cb5a510 100644 --- a/source/_components/switch.rfxtrx.markdown +++ b/source/_components/switch.rfxtrx.markdown @@ -23,6 +23,7 @@ switch: living_room: name: Living Room packetid: XXXXX + fire_event: True automatic_add: True ``` @@ -31,3 +32,4 @@ 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. Can be used for automations. diff --git a/source/_components/switch.vera.markdown b/source/_components/switch.vera.markdown index 07bad9bea28..db2562a193d 100644 --- a/source/_components/switch.vera.markdown +++ b/source/_components/switch.vera.markdown @@ -9,29 +9,11 @@ sharing: true footer: true logo: vera.png ha_category: Switch +ha_iot_class: "Local Push" --- +The `vera` platform allows you to control your [Vera](http://getvera.com/) switches from within Home Assistant. -This `vera` switch platform allows you to control your [Vera](http://getvera.com/) switches. +They will be automatically discovered if the vera component is loaded. -To use your Vera switches in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -switch: - platform: vera - vera_controller_url: http://YOUR_VERA_IP:3480/ - device_data: - 12: - name: My awesome sensor - exclude: true - 13: - name: Another sensor -``` - -Configuration variables: - -- **vera_controller_url** (*Required*): This is the base URL of your vera controller including the port number if not running on 80, eg. http://192.168.1.21:3480/ -- **device_data** array (*Optional*):This contains an array additional device information for your Vera devices. It is not required and if not specified all sensors configured in your Vera controller will be added with default values. You should use the id of your Vera device as the key for the device within `device_data`. - - **name** (*Optional*):This parameter allows you to override the name of your Vera device in the frontend, if not specified the value configured for the device in your Vera will be used. - - **exclude** (*Optional*): This parameter allows you to exclude the specified device, it should be set to "True" if you want this device excluded. +For more configuration information see the [Vera component](/components/vera/) documentation. diff --git a/source/_components/vera.markdown b/source/_components/vera.markdown index 50167fd0d4a..e41ac4410f0 100644 --- a/source/_components/vera.markdown +++ b/source/_components/vera.markdown @@ -11,8 +11,22 @@ logo: vera.png ha_category: Hub --- +The [Vera](http://getvera.com) hub is a controller ainly connecting to Z-Wave devices. -The [Vera](http://getvera.com) ecosystem is using Z-Wave for communication between the Vera controller and the devices. +Switches, Lights (inc Dimmers), Sensors and Binary sensors are supported - and will be automaticaly added when HA connects to your Vera controller. + +To use Vera devices in your installation, add the following to your configuration.yaml file using the IP and port number of your Vera controller: + +```yaml +vera: + vera_controller_url: http://192.168.1.161:3480/ +``` + +By default your switches will be added to HA as switches, however if some of them are light switches, you can tell HA this using the optional ```lights``` parameter as shown below. + +Vera imports detailed zwave devices into HA - this can include system devices and other devices that you don't use, you can tell HA not to load these devices using the ```exclude:``` parameter as shown below. + +You can find the vera device id either by looking at your vera controller - or by checking the ```Vera Device Id``` attribute on each device imported into HA. ```yaml vera: @@ -22,3 +36,4 @@ vera: # Optional to import switches as lights - this is a list of vera device ids lights: [15, 17, 19, 21, 22, 24, 26, 43, 64, 70, 87] ``` + diff --git a/source/_components/weblink.markdown b/source/_components/weblink.markdown index 4d08fc67f6f..69467bfaafa 100644 --- a/source/_components/weblink.markdown +++ b/source/_components/weblink.markdown @@ -11,9 +11,9 @@ logo: ha_category: Other --- -The `weblinks` component allows you to display links in the Home Assistant frontend. +The `weblink` component allows you to display links in the Home Assistant frontend. -To use this component in your installation, add the following to your `configuration.yaml` file: +To use this component in your installation, add something like the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry diff --git a/source/_components/wemo.markdown b/source/_components/wemo.markdown index e2bf5c9236a..df99afa5081 100644 --- a/source/_components/wemo.markdown +++ b/source/_components/wemo.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: belkin_wemo.png ha_category: Hub +featured: true --- The `wemo` component is the main component to integrate various [Belkin WeMo](http://www.belkin.com/us/Products/home-automation/c/wemo-home-automation/) devices with Home Assistant. diff --git a/source/_components/zone.markdown b/source/_components/zone.markdown index accd4824824..29c84024dc6 100644 --- a/source/_components/zone.markdown +++ b/source/_components/zone.markdown @@ -51,6 +51,10 @@ Configuration variables: If no configuration is given, the `zone` component will create a zone for home. This zone will use location given in the `configuration.yaml` file and have a radius of 100 meters. To override this, create a zone configuration and name it **'Home'**. +

+Devices that are in the zone **'Home'** will not appear on the map in the Home Assistant UI. +

+ #### {% linkable_title Icons %} It is preferred to pick an icon to use for your zone. Pick any zone that you can find on [materialdesignicons.com](https://materialdesignicons.com/) and prefix the name with `mdi:`. For example `mdi:school`, `mdi:worker`, `mdi:home`, `mdi:cart`, or `mdi:castle`. diff --git a/source/_components/zwave.markdown b/source/_components/zwave.markdown index 83c13ff0325..607851ec90c 100644 --- a/source/_components/zwave.markdown +++ b/source/_components/zwave.markdown @@ -9,6 +9,7 @@ sharing: true footer: true logo: z-wave.png ha_category: Hub +featured: true --- [Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host. @@ -25,7 +26,7 @@ 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 of cython. ```bash $ sudo pip3 install --upgrade cython @@ -61,7 +62,7 @@ With this installation, your `config_path` needed below will resemble: zwave: usb_path: /dev/ttyUSB0 config_path: /usr/local/share/python-openzwave/config - polling_interval: 10000 + polling_interval: 60000 customize: sensor.greenwave_powernode_6_port_energy_10: polling_intensity: 1 @@ -71,7 +72,7 @@ Configuration variables: - **usb_path** (*Required*): The port where your device is connected to your Home Assistant host. - **config_path** (*Optional*): The path to the Python Open Z-Wave configuration files. -- **polling_interval** (*Optional*): The time period in milliseconds between polls of a nodes value. +- **polling_interval** (*Optional*): The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems. - **customize** (*Optional*): This attribute contains node-specific override values: - **polling_intensity** (*Optional*): Enables polling of a value and sets the frequency of polling (0=none, 1=every time through the list, 2-every other time, etc) @@ -102,7 +103,7 @@ automation: trigger: platform: event event_type: zwave.scene_activated - event_data: + event_data: entity_id: zwaveme_zme_wallcs_secure_wall_controller_8 scene_id: 11 ``` @@ -111,12 +112,105 @@ The *entity_id* and *scene_id* of all triggered events can be seen in the consol #### {% linkable_title Services %} -The Z-Wave component exposes two services to help maintain the network. +The Z-Wave component exposes four services to help maintain the network. | Service | Description | | ------- | ----------- | -| add_node | | -| remove_node | | -| heal_network | | -| soft_reset | | +| add_node | Put the zwave controller in inclusion mode. Allows one to add a new device to the zwave network.| +| remove_node | Put the zwave controller in exclusion mode. Allows one to remove a device from the zwave network.| +| heal_network | Tells the controller to "heal" the network. Bascially asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. | +| soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.| | test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead".| + +The soft_reset and heal_network commands can be used as part of an automation script +to help keep a zwave network running relliably. For example: + +```yaml +# Example configuration.yaml automation entry +automation: + - alias: soft reset at 2:30am + trigger: + platform: time + after: '2:30:00' + action: + service: zwave.soft_reset + + - alias: heal at 2:31am + trigger: + platform: time + after: '2:31:00' + action: + service: zwave.heal_network +``` + +#### {% linkable_title Device Specific Notes & Configuration %} + +##### {% linkable_title Aeon Minimote %} + +Here's a handy configuration for the Aeon Labs Minimote that defines all possible button presses. Put it into `automation.yaml`. + +```yaml +- alias: Minimote Button 1 Pressed + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 1 + +- alias: Minimote Button 1 Held + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 2 + +- alias: Minimote Button 2 Pressed + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 3 + +- alias: Minimote Button 2 Held + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 4 + +- alias: Minimote Button 3 Pressed + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 5 + +- alias: Minimote Button 3 Held + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 6 + +- alias: Minimote Button 4 Pressed + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 7 + +- alias: Minimote Button 4 Held + trigger: + platform: event + event_type: zwave.scene_activated + event_data: + entity_id: aeon_labs_minimote_1 + scene_id: 8 +``` diff --git a/source/_cookbook/automation_flashing_lights.markdown b/source/_cookbook/automation_flashing_lights.markdown new file mode 100644 index 00000000000..9bd23647d42 --- /dev/null +++ b/source/_cookbook/automation_flashing_lights.markdown @@ -0,0 +1,108 @@ +--- +layout: page +title: "Examples for flashing lights" +description: "Automation examples for flashing lights in case of an alarm." +date: 2016-03-30 08:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Automation Examples +--- + +#### {% linkable_title Flashing lights triggered by an alarm %} + +For flashing regular lights in case the the triggering of an alarm. + +```yaml +# AlmAct1 - switch to activate the alarm in Room1 +# AlmSnd1 - switch for a buzzer + +automation: +- alias: 'Alarm_PIR_Room1' + trigger: + platform: state + entity_id: binary_sensor.PIR1 + state: 'on' + condition: + - platform: state + entity_id: switch.AlmAct1 + state: 'on' + - platform: state + entity_id: script.alarm_room1 + state: 'off' + action: + # start alarm on movement if alarm activated + # and the alarm is not triggered + service: script.turn_on + entity_id: script.alarm_room1 + +- alias: 'flash_room1_start' + trigger: + platform: state + entity_id: switch.AlmSnd1 + state: 'on' + action: + service: script.turn_on + entity_id: script.flash_room1 + +- alias: 'flash_room1_stop' + trigger: + platform: state + entity_id: switch.REL1 + state: 'off' + condition: + platform: state + entity_id: switch.AlmSnd1 + state: 'off' + action: + service: script.turn_off + entity_id: script.flash_room1 + +script: + alarm_room1: + alias: Alarm room1 + sequence: + - alias: Alarm Room1 Start + service: homeassistant.turn_on + data: + entity_id: switch.AlmSnd1 + - alias: Set Ack Room1 + service: homeassistant.turn_on + data: + entity_id: input_boolean.ack1 + - alias: email_Room1 + service: notify.email + data: + message: 'Movement alarm in Room1' + - delay: + # time interval for alarm sound and light flashing + seconds: 60 + - alias: Alarm Room1 Stop + service: homeassistant.turn_off + data: + entity_id: switch.AlmSnd1 + + flash_room1: + alias: Flash Room1 On + sequence: + - alias: Light Room1 On + service: homeassistant.turn_on + data: + entity_id: switch.REL1 + - delay: + # time for flash light on + seconds: 1 + - alias: Light Room1 Off + service: homeassistant.turn_off + data: + entity_id: switch.REL1 + - delay: + # time for flash light off + seconds: 1 + - alias: loop_room1 + service: script.turn_on + data: + entity_id: script.flash_room1 +``` + diff --git a/source/_cookbook/configuration_yaml_from_bassclarinetl2.markdown b/source/_cookbook/configuration_yaml_from_bassclarinetl2.markdown index 90f2298fa69..dd69f051804 100644 --- a/source/_cookbook/configuration_yaml_from_bassclarinetl2.markdown +++ b/source/_cookbook/configuration_yaml_from_bassclarinetl2.markdown @@ -223,7 +223,7 @@ http: ssl_key: /etc/letsencrypt/live/example.com/privkey.pem ifttt: - key: gm3dAtxwX8RpbA793mHWbK1bftO1wgScKt0ZHiT9GyC + key: [redacted] media_player 1: platform: plex @@ -249,8 +249,8 @@ media_player 7: name: Parents TV wink: - access_token: cf83448f669cd3acd3b969b063028565 - refresh_token: 6213c8a1d519d864e08b7364c91eaf22 + access_token: [redacted] + refresh_token: [redacted] zwave: usb_path: /dev/ttyUSB0 @@ -264,8 +264,8 @@ zwave: mqtt: broker: 127.0.0.1 port: 8883 - username: hass - password: austin + username: [redacted] + password: [redacted] device_tracker 1: platform: owntracks @@ -281,7 +281,7 @@ device_tracker 2: #sensor: # platform: openweathermap -# api_key: b693a8bb2f60dcedc7b4bf33649ed4f1 +# api_key: [redacted] # forecast: 1 # monitored_conditions: # - temperature diff --git a/source/_cookbook/customize_polling_interval.markdown b/source/_cookbook/customize_polling_interval.markdown index e6aff18ebe8..ef73095c114 100644 --- a/source/_cookbook/customize_polling_interval.markdown +++ b/source/_cookbook/customize_polling_interval.markdown @@ -7,7 +7,7 @@ sidebar: true comments: false sharing: true footer: true -ha_category: Example configuration.yaml +ha_category: Customize Defaults --- Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a `scan_interval` config key. In the example below we setup the Philips Hue lights but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds. diff --git a/source/_cookbook/foscam_away_mode_PTZ.markdown b/source/_cookbook/foscam_away_mode_PTZ.markdown index 3ac9578ccce..59d20576c58 100644 --- a/source/_cookbook/foscam_away_mode_PTZ.markdown +++ b/source/_cookbook/foscam_away_mode_PTZ.markdown @@ -47,18 +47,18 @@ The `script.foscam_off` and `script.foscam_on` can be used to set the motion det script: foscam_off: sequence: - - execute_service: switch.turn_off - service_data: + - service: switch.turn_off + data: entity_id: switch.foscam_motion - service: shell_command.foscam_turn_off foscam_on: sequence: - - execute_service: switch.turn_off - service_data: + - service: switch.turn_off + data: entity_id: switch.foscam_motion - service: shell_command.foscam_turn_on - - execute_service: switch.turn_on - service_data: + - service: switch.turn_on + data: entity_id: switch.foscam_motion ``` diff --git a/source/_cookbook/restart_ha_if_wemo_switch_is_not_detected.markdown b/source/_cookbook/restart_ha_if_wemo_switch_is_not_detected.markdown index 5c7accebee2..cca4f2f07d1 100644 --- a/source/_cookbook/restart_ha_if_wemo_switch_is_not_detected.markdown +++ b/source/_cookbook/restart_ha_if_wemo_switch_is_not_detected.markdown @@ -53,11 +53,11 @@ script: sequence: - delay: minutes: 15 - - execute_service: notify.pushbullet - service_data: + - service: notify.pushbullet + data: message: 'WeMo not found, restarting HA' - - execute_service: switch.turn_on - service_data: + - service: switch.turn_on + data: entity_id: switch.killhass automation: diff --git a/source/_cookbook/turn_on_light_for_10_minutes_when_motion_detected.markdown b/source/_cookbook/turn_on_light_for_10_minutes_when_motion_detected.markdown index 1cbdbdde6e1..78c668a00da 100644 --- a/source/_cookbook/turn_on_light_for_10_minutes_when_motion_detected.markdown +++ b/source/_cookbook/turn_on_light_for_10_minutes_when_motion_detected.markdown @@ -30,15 +30,15 @@ script: alias: "Turn on lamp and set timer" sequence: # Cancel ev. old timers - - execute_service: script.turn_off - service_data: + - service: script.turn_off + data: entity_id: script.timer_off - - execute_service: light.turn_on - service_data: + - service: light.turn_on + data: entity_id: light.kitchen # Set new timer - - execute_service: script.turn_on - service_data: + - service: script.turn_on + data: entity_id: script.timer_off timer_off: @@ -46,7 +46,7 @@ script: sequence: - delay: minutes: 10 - - execute_service: light.turn_off - service_data: + - service: light.turn_off + data: entity_id: light.kitchen ``` diff --git a/source/_posts/2015-08-26-laundry-automation-with-moteino-mqtt-and-home-assistant.markdown b/source/_posts/2015-08-26-laundry-automation-with-moteino-mqtt-and-home-assistant.markdown index 0fdd5bcfab6..676de505396 100644 --- a/source/_posts/2015-08-26-laundry-automation-with-moteino-mqtt-and-home-assistant.markdown +++ b/source/_posts/2015-08-26-laundry-automation-with-moteino-mqtt-and-home-assistant.markdown @@ -55,6 +55,10 @@ Materials used: Home Assistant Configuration: +

+The automation and script syntax here is using a deprecated and no longer supported format. +

+ ```yaml mqtt: broker: 192.168.1.100 diff --git a/source/_posts/2015-12-06-community-highlights.markdown b/source/_posts/2015-12-06-community-highlights.markdown index bce943466ae..f4e35542694 100644 --- a/source/_posts/2015-12-06-community-highlights.markdown +++ b/source/_posts/2015-12-06-community-highlights.markdown @@ -13,7 +13,7 @@ og_image: /images/blog/2015-12-community/hass-alexa.png From time to time we come along things that are worth sharing with fellow Home Assisters. Here a list of some cool stuff from last week: -First is the public beta of [Let's Encrypt](https://letsencrypt.org/). Let's Encrypt is a new certificate authority that is free, automated and open. This means that it will now be very easy to secure your connection to Home Assistant while you are away from home. W1ll1am23 has written up [a guide how to get started](https://automic.us/forum/viewtopic.php?f=4&t=29). +First is the public beta of [Let's Encrypt](https://letsencrypt.org/). Let's Encrypt is a new certificate authority that is free, automated and open. This means that it will now be very easy to secure your connection to Home Assistant while you are away from home. W1ll1am23 has written up [a guide how to get started](https://community.home-assistant.io/t/homeassistant-nginx-ssl-proxy-setup/53). The next thing is a show-off of some of the cool stuff people do with Home Assistant. This is miniconfig talking to Home Assistant using the Amazon Echo! diff --git a/source/_posts/2016-02-20-community-highlights.markdown b/source/_posts/2016-02-20-community-highlights.markdown index d3a277cca1e..e489028e05e 100644 --- a/source/_posts/2016-02-20-community-highlights.markdown +++ b/source/_posts/2016-02-20-community-highlights.markdown @@ -52,7 +52,7 @@ Example config.json entry to load Home Assistant: ### {% linkable_title Custom alarm system with Home Assistant %} -User thaijames [describes in the Home Assistant forums](https://automic.us/forum/viewtopic.php?f=4&t=43&hilit=nfc) how he has created his own NFC-based alarm system using Home Assistant, DIY components and Garfield dolls. +User thaijames [describes in the Home Assistant forums](https://community.home-assistant.io/t/controlling-house-alarm-from-ha/67) how he has created his own NFC-based alarm system using Home Assistant, DIY components and Garfield dolls.

diff --git a/source/_topics/splitting_configuration.markdown b/source/_topics/splitting_configuration.markdown index 46dddbdf1d7..644296f28ec 100644 --- a/source/_topics/splitting_configuration.markdown +++ b/source/_topics/splitting_configuration.markdown @@ -9,50 +9,42 @@ sharing: true footer: true --- -So you've been using Home Assistant (HA, hass, or any number of other abbreviations) for a while now and your configuration.yaml file brings people to tears (https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/) or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: husmanly readable) pieces. +So you've been using Home Assistant for a while now and your [configuration.yaml file brings people to tears](https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/) or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: humanly readable) pieces. -First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing: - -- https://github.com/bassclarinetl2/HASS -- https://github.com/happyleavesaoc/my-home-automation/tree/master/homeassistant +First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](https://home-assistant.io/cookbook/#example-configurationyaml). As commenting code doesn't always happen, please read on for the details. -Now despite the logical assumption that the configuration.yaml will be replaced by this process it will in fact remain all be it in a much less cluttered form. +Now despite the logical assumption that the `configuration.yaml` will be replaced by this process it will in fact remain all be it in a much less cluttered form. In this lighter version we will still need what could be called the core snippet: - homeassistant: - # Name of the location where Home Assistant is running - name: My Hass Instance - # Location required to calculate the time the sun rises and sets - latitude: 37 - longitude: -121 - # C for Celcius, F for Fahrenheit - temperature_unit: F - # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones - time_zone: America/Los_Angeles - customize: !include customize.yaml +```yaml +homeassistant: + # Name of the location where Home Assistant is running + name: My Hass Instance + # Location required to calculate the time the sun rises and sets + latitude: 37 + longitude: -121 + # C for Celcius, F for Fahrenheit + temperature_unit: F + # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones + time_zone: America/Los_Angeles + customize: !include customize.yaml +``` -Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML "language", indentation and spacing are important. Also note that seemingly strange entry under `customize:`. +Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under `customize:`. -`!include filename.yaml` is the statement that tells Home Assistant to insert the contents of `filename.yaml` at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks. +`!include filename.yaml` is the statement that tells Home Assistant to insert the contents of `filename.yaml` at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks. Now before we start splitting out the different components, let's look at the other components (in our example) that will stay in the base file: -``` -#discovery: -sun: -#updater: +```yaml history: -#conversation: frontend: logbook: http: api_password: ImNotTelling! - server_port: 8123 - ssl_certificate: /etc/letsencrypt/live/example.com/fullchain.pem - ssl_key: /etc/letsencrypt/live/example.com/privkey.pem ifttt: key: [nope] @@ -72,54 +64,41 @@ zwave: mqtt: broker: 127.0.0.1 - port: 8883 - username: user - password: password ``` -As with the core snippet, indentation makes a difference. The component headers (`mqtt:`) should be fully left aligned (aka no indent), and the parameters (`port:`) should be indented two (2) spaces. +As with the core snippet, indentation makes a difference. The component headers (`mqtt:`) should be fully left aligned (aka no indent), and the parameters (`port:`) should be indented two (2) spaces. -While some of these components can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient , not to mention turning off features while leaving the entry intact. (Look at the `zigbee:` entry above and the sensors entry further down) +While some of these components can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact. (Look at the `zigbee:` entry above and the b entry further down) Now, lets assume that a blank file has been created in the hass configuration directory for each of the following: - groups.yaml - zones.yaml - automation.yaml - notifications.yaml - sensors.yaml - switches.yaml - scripts.yaml - media_player.yaml - device_tracker.yaml - customize.yaml - -`automation.yaml`will hold all the automation component details -`zones.yaml` will hold the zone component details -and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of. +```text +automation.yaml +zones.yaml +sensors.yaml +switches.yaml +device_tracker.yaml +customize.yaml +``` + +`automation.yaml` will hold all the automation component details. `zones.yaml` will hold the zone component details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of. Inside the base configuration file add the following entries: -``` -group: !include groups.yaml -zone: !include zones.yaml + +```yaml automation: !include automation.yaml -notifications: !include notifications.yaml +zone: !include zones.yaml sensor: !include sensors.yaml switch: !include switches.yaml -scripts: !include: scripts.yaml -media_player: !include media_player.yaml device_tracker: !include device_tracker.yaml ``` -Note that there can only be one `!include:` for each component so chaining them isn't going to work. If that sounds like greek, don't worry about it. + +Note that there can only be one `!include:` for each component so chaining them isn't going to work. If that sounds like greek, don't worry about it. Alright, so we've got the single components and the include statements in the base file, what goes in those extra files? -Let's look at the `device_tracker` file from our example: - -``` -### device_tracker.yaml -### -### +Let's look at the `device_tracker.yaml` file from our example: +```yaml - platform: owntracks - platform: nmap_tracker hosts: 192.168.2.0/24 @@ -127,27 +106,24 @@ Let's look at the `device_tracker` file from our example: track_new_devices: yes interval_seconds: 40 - consider_home: 120 + consider_home: 120 ``` -This small example illustrates how the "split" files work. In this case, we start with a "comment block" identifying the file followed by two (2) device tracker entries (owntracks and nmap). These files follow "style 2" that is to say a fully left aligned leading entry (`- platform: owntracks`) followed by the parameter entries indented two (2) spaces. + +This small example illustrates how the "split" files work. In this case, we start with a "comment block" identifying the file followed by two (2) device tracker entries (`owntracks` and `nmap`). These files follow ["style 1"](/getting-started/devices/#style-2-list-each-device-separately) that is to say a fully left aligned leading entry (`- platform: owntracks`) followed by the parameter entries indented two (2) spaces. This (large) sensor configuration gives us another example: -``` + +```yaml ### sensors.yaml -### -### -### ############################################################## ### METEOBRIDGE #### -### http://meteobridge.com/wiki/index.php/Add-On_Services #### -### Live Data as Plain text #### ############################################################## - platform: tcp name: 'Outdoor Temp (Meteobridge)' host: 192.168.2.82 timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" + payload: "Content-type: text/xml; charset=UTF-8\n\n" value_template: "{{value.split (' ')[2]}}" unit: C - platform: tcp @@ -166,102 +142,6 @@ This (large) sensor configuration gives us another example: payload: "Content-type: text/xml; charset=UTF-8\n\n" value_template: "{{value.split (' ')[4] }}" unit: C -- platform: tcp - name: 'Wind Direction (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" - value_template: "{{value.split (' ')[7]}}" - unit: Degrees -- platform: tcp - name: 'Wind Gust (Meteohub)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" - value_template: "{{value.split (' ')[8]}}" - unit: m/s -- platform: tcp - name: 'Wind Speed (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" - value_template: "{{value.split (' ')[9]}}" - unit: m/s -- platform: tcp - name: 'Wind Chill (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" - value_template: "{{value.split (' ')[10]}}" - unit: C -- platform: tcp - name: 'Precip Rate (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charset=UTF-8\n\n" - value_template: "{{value.split (' ')[13]}}" - unit: mm/hr -- platform: tcp - name: 'Precip Total (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[14]}}" - unit: mm -- platform: tcp - name: 'Precip Change (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[15]}}" - unit: mm -- platform: tcp - name: 'Indoor Temp (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[18]}}" - unit: C -- platform: tcp - name: 'Indoor Humidity (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[19]}}" - unit: percent -- platform: tcp - name: 'Indoor Dewpoint (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[20]}}" - unit: C -- platform: tcp - name: 'Barometric Pressure (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[21]}}" - unit: mb -- platform: tcp - name: 'Sea Level Pressure (Meteobridge)' - host: 192.168.2.82 - port: 5556 - timeout: 6 - payload: "Content-type: text/xml; charaset=UTF-8\n\n" - value_template: "{{value.split (' ')[22]}}" - unit: mb ################################### #### STEAM FRIENDS #### ################################## @@ -281,7 +161,7 @@ This (large) sensor configuration gives us another example: - 'date' - platform: worldclock time_zone: Etc/UTC - name: 'UTC' + name: 'UTC' - platform: worldclock time_zone: America/New_York name: 'Ann Arbor' @@ -295,7 +175,7 @@ This (large) sensor configuration gives us another example: You'll notice that this example includes a secondary parameter section (under the steam section) as well as a better example of the way comments can be used to break down files into sections. -That about wraps it up. +That about wraps it up. -If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to the gitter.im chat and ask away. +If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to the [Gitter Chatroom](https://gitter.im/balloob/home-assistant) and ask away. diff --git a/source/_topics/z-wave.markdown b/source/_topics/z-wave.markdown index 84d15a60c62..4fff9fea8e2 100644 --- a/source/_topics/z-wave.markdown +++ b/source/_topics/z-wave.markdown @@ -13,7 +13,9 @@ footer: true Z-Wave is a popular home automation protocol that is not always straightforward to setup. This page will try to help you make sense of it all. -- Note: Upon first run, the z-wave component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may expidite this proccess. +

+Upon first run, the z-wave component will take time to initialize entities and entities may appear with incomplete names. Running a network heal may expidite this proccess. +

## {% linkable_title Supported Z-Wave Sticks %} @@ -21,6 +23,7 @@ Z-Wave is a popular home automation protocol that is not always straightforward |-------------------------|----------------|------------------|--------------|-----------| | Aeotec Z-Stick Series 2 | X | | | | | Aeotec Z-Stick Series 5 | X | | | | +| Razberry GPIO Module | X | | | | ## {% linkable_title Stick Alternatives %} diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index 3bf10db703a..e457e5d8e9e 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -28,7 +28,7 @@ The Home Assistant core is responsible for Home Control. It has four parts to ma * The **Event Bus** facilitates the firing and listening of events. This is the beating heart of Home Assistant. * The **State Machine** keeps track of the states of things. Fires a `state_changed` event when a state has been changed. * The **Service Registry** listens on the event bus for `call_service` events and allows other code to register services. - * The **Timer** will send every 1 second a `time_changed` event on the event bus. + * The **Timer** will send a `time_changed` event every 1 second on the event bus.

@@ -37,16 +37,18 @@ The Home Assistant core is responsible for Home Control. It has four parts to ma Overview of the Home Assistant core architecture

-Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for- or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/). +Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/). -We can differentiate between two different types ofcomponents within Home Assistant. +We can differentiate between two different types of components within Home Assistant. #### {% linkable_title Components that interact with an Internet of Things domain %} -These components will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. +These components will track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches. +A platform provides support for a particular kind/brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform. + If you are planning to add support for a new platform, please check out the [add new platform section]({{root_url}}/developers/add_new_platform/). #### {% linkable_title Components that respond to events that happen within Home Assistant %} @@ -86,7 +88,7 @@ When we put all the different pieces of Home Assistant together we see that we m Overview of the full Home Assistant architecture with a couple of loaded components and platforms.

-Component's platform logic uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community. +The platform logic for components uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community. ## {% linkable_title Multiple connected instances %} @@ -99,7 +101,7 @@ Home Assistant supports running multiple synchronized instances using a master-s Overview of the Home Assistant architecture for multiple devices.

-A slave instance can be started with the following code and has the same support for components as a master-instance. +A slave instance can be started with the following code and has the same support for components as a master instance. ```python import homeassistant.remote as remote @@ -120,5 +122,5 @@ hass.block_till_stopped() ```

-Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call. +Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call.

diff --git a/source/developers/credits.markdown b/source/developers/credits.markdown index 115a38e7747..f6f63365775 100644 --- a/source/developers/credits.markdown +++ b/source/developers/credits.markdown @@ -22,6 +22,7 @@ This page contains a list of people who have contributed in one way or another t - [Adrien Brault](https://github.com/adrienbrault) - [Alex Harvey](https://github.com/infamy) - [Allan Glen](https://github.com/allanglen) +- [Andrew](https://github.com/aoakeson) - [Andy Loughran](https://github.com/andylockran) - [andythigpen](https://github.com/andythigpen) - [Arthur Leonard Andersen](https://github.com/leoc) @@ -74,6 +75,7 @@ This page contains a list of people who have contributed in one way or another t - [Karen Goode](https://github.com/kfgoode) - [kennedyshead](https://github.com/kennedyshead) - [kixam](https://github.com/kixam) +- [Luca Soldi](https://github.com/LucaSoldi) - [Lukas Hetzenecker](https://github.com/lukas-hetzenecker) - [Magnus Knutas](https://github.com/MagnusKnutas) - [MakeMeASandwich](https://github.com/MakeMeASandwich) @@ -99,6 +101,7 @@ This page contains a list of people who have contributed in one way or another t - [rhooper](https://github.com/rhooper) - [Richard Arends](https://github.com/Mosibi) - [rkabadi](https://github.com/rkabadi) +- [Robbie Trencheny](https://github.com/robbiet480) - [Rowan Hine](https://github.com/GreenTurtwig) - [Ryan Kraus](https://github.com/rmkraus) - [Ryan Turner](https://github.com/ryanturner) diff --git a/source/developers/website.markdown b/source/developers/website.markdown index cc0a3f6c756..fac5d007e18 100644 --- a/source/developers/website.markdown +++ b/source/developers/website.markdown @@ -11,7 +11,7 @@ footer: true The home of Home Assistant is [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers. -home-assistant.io is using [Octopress](http://octopress.org/). To get more details, please checkout the [documentation](http://octopress.org/docs/). That means that creating a new page is simple. The pages are written in [markdown](http://daringfireball.net/projects/markdown/), you don't need to care about HTML or alike. +home-assistant.io is using the [Octopress](http://octopress.org/) framework for [Jekyll](http://github.com/mojombo/jekyll). To get more details, please checkout the [documentation](http://octopress.org/docs/). That means that creating a new page is simple. The pages are written in [markdown](http://daringfireball.net/projects/markdown/), you don't need to care about HTML or alike. To work on the website the process is no different to working on Home Assistant itself. @@ -24,13 +24,13 @@ To work on the website the process is no different to working on Home Assistant For a platform page it would be the fastest way to make a copy of an existing page and edit it. The [component overview](/components/) is generated automatically, so there is no need to add a link to that your page. ### {% linkable_title Code %} -To take advantage of the build-in features of Octopress to display code snipplets, just use the default markdown syntax. Please use `$` and `#` if it's a command and to differ from output. +To take advantage of the built-in features of Octopress to display code snippets, just use the default markdown syntax. Please use `$` and `#` if it's a command and to differ from output. ```bash Here goes the code... ``` -If you want to display line numbers, add the following snipplets somewhere on your page. +If you want to display line numbers, add the following snippet somewhere on your page. ``` {::options coderay_line_numbers="table" /} @@ -44,5 +44,5 @@ The images which are displayed on the pages are stored in various directories ac | screen shots | source/images/screenshots | | logos | source/images/supported_brands | -Not everything (product, component, etc.) has a logo, to show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). +Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). diff --git a/source/getting-started/autostart.markdown b/source/getting-started/autostart.markdown index 000ed53c2c7..c10625a3b12 100644 --- a/source/getting-started/autostart.markdown +++ b/source/getting-started/autostart.markdown @@ -32,7 +32,6 @@ Upstart will launch init scripts that are located in the directory `/etc/init.d/ To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: - ```bash $ sudo service hass-daemon start $ sudo service hass-daemon stop @@ -44,64 +43,64 @@ When running daemons, it is good practice to have the daemon run under its own u
-Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command: - +Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using `systemd`, you may check with the following command: ```bash $ ps -p 1 -o comm= ``` -If the preceding command returns the string `systemd`, you are likely using systemd. - -If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd. +If the preceding command returns the string `systemd`, you are likely using `systemd`. +If you want Home Assistant to be launched automatically, an extra step is needed to setup `systemd`. You need a service file to control Home Assistant with `systemd`. If you are using a Raspberry Pi then replace the `[your user]` with `pi` otherwise use your user you want to run Home Assistant. ```bash -$ su -c 'cat <> /lib/systemd/system/home-assistant.service +$ su -c 'cat <> /lib/systemd/system/home-assistant@[your user].service [Unit] Description=Home Assistant After=network.target [Service] Type=simple -ExecStart=/usr/local/bin/hass -# Next line is to run as a specific user -# for Raspberry Pi users, keep it at 'pi' -User=pi +User=%i +ExecStart=/usr/bin/hass [Install] WantedBy=multi-user.target EOF' ``` -You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that. +There is also another [sample service file](https://raw.githubusercontent.com/balloob/home-assistant/master/script/home-assistant%40.service) available. To use this one, just download it. +```bash +$ sudo wget https://raw.githubusercontent.com/balloob/home-assistant/master/script/home-assistant%40.service -O /lib/systemd/system/home-assistant@[your user].service +``` + +You need to reload `systemd` to make the daemon aware of the new configuration. Enable and launch Home Assistant after that. ```bash $ sudo systemctl --system daemon-reload -$ sudo systemctl enable home-assistant -$ sudo systemctl start home-assistant +$ sudo systemctl enable home-assistant@[your user] +$ sudo systemctl start home-assistant@[your user] ``` If everything went well, `sudo systemctl start home-assistant` should give you a positive feedback. - ```bash -$ sudo systemctl status home-assistant -l -● home-assistant.service - Home Assistant - Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled) - Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago - Main PID: 8557 (python3.4) - CGroup: /system.slice/home-assistant.service - └─8557 /usr/bin/python3.4 -m homeassistant +$ sudo systemctl status home-assistant@[your user] -l +● home-assistant@fab.service - Home Assistant for [your user] + Loaded: loaded (/usr/lib/systemd/system/home-assistant@[your user].service; enabled; vendor preset: disabled) + Active: active (running) since Sat 2016-03-26 12:26:06 CET; 13min ago + Main PID: 30422 (hass) + CGroup: /system.slice/system-home\x2dassistant.slice/home-assistant@[your user].service + ├─30422 /usr/bin/python3 /usr/bin/hass + └─30426 /usr/bin/python3 /usr/bin/hass [...] ``` To get Home Assistant's logging output, simple use `journalctl`. - ```bash -$ sudo journalctl -f -u home-assistant +$ sudo journalctl -f -u home-assistant@[your user] ```
diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index c236513ee9b..ca1ae21f43c 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -11,11 +11,12 @@ footer: true Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X/Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `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. An example configuration file is located [here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). +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. +This file contains YAML code, which is explained briefly in [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/). An example configuration file is located [here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). When launched for the first time, Home Assistant will write a default configuration 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 interface. -If you are running into trouble while configuring Home Assistant, have a look at [the configuration troubleshoot page](/getting-started/troubleshooting-configuration/). +If you run into trouble while configuring Home Assistant, have a look at [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/).

You will have to restart Home Assistant for changes in configuration.yaml to take effect. @@ -46,7 +47,7 @@ homeassistant: ### {% linkable_title Password protecting the web interface %} -The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/configuration.yaml` and add the following to the bottom: +The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `/config/configuration.yaml` and add the following to the `http` section: ```yaml http: @@ -59,12 +60,12 @@ _See the [HTTP component documentation][http] for more options like HTTPS encryp ### {% 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 homescreen. 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 on the add to homescreen option. +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. ### {% linkable_title Remote access %} To make Home Assistant accessible while away from home, you will have to setup 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`. -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/). +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/). ### [Next step: Setting up devices »](/getting-started/devices/) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index d8d95d3c10c..19f691c215a 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -280,7 +280,7 @@ If you run into any issues, please see [the troubleshooting page](/getting-start For additional help, in addition to this site, there are four sources: - - [Forum](https://automic.us/forum/) + - [Forum](https://community.home-assistant.io/) - [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions. - [GitHub Page](https://github.com/balloob/home-assistant/issues) for issue reporting. diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/getting-started/troubleshooting-configuration.markdown index 43fd9234c04..5b3420d1462 100644 --- a/source/getting-started/troubleshooting-configuration.markdown +++ b/source/getting-started/troubleshooting-configuration.markdown @@ -9,36 +9,37 @@ sharing: true footer: true --- -It can happen that you run into trouble while configuring Home Assistant. A component is not showing up or is acting weird. This page will discuss a few of the most common problems. +It can happen that you run into trouble while configuring Home Assistant. Perhaps a component is not showing up or is acting strangely. This page will discuss a few of the most common problems. Before we dive into common issues, make sure you know where your configuration directory is. Home Assistant will print out the configuration directory it is using when starting up. -Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log`. This file is reset on start of Home Assistant. +Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log` in the configuration directory. This file is reset on start of Home Assistant. ### {% linkable_title YAML %} -Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really powerful in allowing you to express complex configurations. +Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML can be confusing to start with but is really powerful in allowing you to express complex configurations. -The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item start with a `-` while lookup tables will have the format `key: value`. The last value for a key is used in case you specify a duplicate key. +The basics of YAML are block collections and mappings containing key-value pairs. Collections will have each item start with a `-` while mappings will have the format `key: value`. The last value for a key is used in case you specify a duplicate key. +Note that the indentation is an important part of specifying relationships using YAML. ```yaml -# A list +# A collection - hello - how - are - you -# Lookup table +# Lookup mapping beer: ice cold # <-- will be ignored because key specified twice beer: warm wine: room temperature water: cold -# Nesting tables +# Nesting mappings (note the indentation) device_tracker: platform: mqtt -# Nesting a list of tables in a table +# Nesting a collection of mappings in a mapping sensor: - platform: mqtt state_topic: sensor/topic @@ -46,10 +47,10 @@ sensor: state_topic: sensor2/topic ``` -Indentation is used to specify which objects are nested under one anohter. Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. You can test your configuration using [online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/). +Indentation is used to specify which objects are nested under one another. Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. - To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack. - - You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/). + - You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/). ### {% linkable_title My component does not show up %} @@ -57,19 +58,19 @@ When a component does not show up, many different things can be the case. Before #### {% linkable_title Problems with the configuration %} -`configuration.yaml` does not allow multiple sections to have the same name. If you want a specific platform to be loaded twice, append a [number/string](/getting-started/devices/#style-2) to the name or use [this style](/getting-started/devices/#style-1). +`configuration.yaml` does not allow multiple sections to have the same name. If you want a specific platform to be loaded twice, append a [number or string](/getting-started/devices/#style-2) to the name or nest them using [this style](/getting-started/devices/#style-1). ```yaml sensor: platform: forecast - [...] + ... sensor 2: platform: bitcoin - [...] + ... ``` -Another common problem is that a required configuration setting is missing. If this is the case, the component will report this to `home-assistant.log`. You can have a look at [the component page](/components/) for instructions how to setup the components. +Another common problem is that a required configuration setting is missing. If this is the case, the component will report this to `home-assistant.log`. You can have a look at [the component page](/components/) for instructions on how to setup the components. If you find any errors or want to expand the documentation, please [let us know](https://github.com/balloob/home-assistant.io/issues). @@ -77,7 +78,7 @@ If you find any errors or want to expand the documentation, please [let us know] Almost all components have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in `home-assistant.log`. -First step is trying to restart Home Assistant and see if the problem persists. If it does, please [report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on. +The first step is trying to restart Home Assistant and see if the problem persists. If it does, look at the log to see what the error is. If you can't figure it out, please [report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on. #### {% linkable_title Problems with components %} @@ -96,7 +97,7 @@ Contents of `lights.yaml`: ```yaml - platform: hyperion host: 192.168.1.98 - [...] + ... ``` Contents of `sensors.yaml`: @@ -108,9 +109,9 @@ Contents of `sensors.yaml`: - platform: mqtt name: "Door Motion" state_topic: "door/motion" - [...] + ... ```

-Whenever you report an issue, be aware that we are a group of volunteers that do not have access to every single device in the world nor unlimited time to fix every problem out there. +Whenever you report an issue, be aware that we are volunteers who do not have access to every single device in the world nor unlimited time to fix every problem out there.

diff --git a/source/getting-started/troubleshooting.markdown b/source/getting-started/troubleshooting.markdown index 4fd9c7b57aa..984a73525ed 100644 --- a/source/getting-started/troubleshooting.markdown +++ b/source/getting-started/troubleshooting.markdown @@ -9,20 +9,20 @@ sharing: true footer: true --- -It can happen that you run into trouble while installing Home Assistant. This page is here to help you figure out the most common problems. +It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems. #### {% linkable_title pip3: command not found %} This utility should have been installed as part of the Python 3.4 installation. Check if Python 3.4 is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/). -If you are able to successfully run `python3 --version` but not `pip3`, run the following command instead to install Home Assistant: +If you are able to successfully run `python3 --version` but not `pip3`, install Home Assistant by running the following command instead: ```bash $ python3 -m pip install homeassistant ``` #### {% linkable_title No module named pip %} -[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is ommitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and run it with Python 3: +[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is omitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and running it with Python 3: ```bash $ python3 get-pip.py @@ -63,7 +63,7 @@ $ iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhe ``` #### {% 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. This can result in an unstable system, loss of data, etc, etc. +If you want to stay on top of the development of Home Assistant then you can upgrade to the `dev` branch. This can result in an unstable system, loss of data, etc. etc. ```bash $ pip3 install --upgrade git+git://github.com/balloob/home-assistant.git@dev diff --git a/source/help/index.markdown b/source/help/index.markdown index 6f578f97ff3..14c2aecbacf 100644 --- a/source/help/index.markdown +++ b/source/help/index.markdown @@ -13,7 +13,7 @@ There are various ways to get in touch with the Home Assistant community. It doe ### {% linkable_title Communication channels %} - - [Forum](https://automic.us/forum/) + - [Forum](https://community.home-assistant.io/) - [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions. ### {% linkable_title Bugs, Feature requests, and alike %} diff --git a/source/help/trivia.markdown b/source/help/trivia.markdown index 0fdd107d19a..69751b83855 100644 --- a/source/help/trivia.markdown +++ b/source/help/trivia.markdown @@ -17,7 +17,7 @@ Unknown at the moment. ### {% linkable_title Website %} -The website [https://home-assistant.io](https://home-assistant.io) was launched on December 18, 2014 and contains doumentation about the setup process, the platforms and components, and for the developers. +The website [https://home-assistant.io](https://home-assistant.io) was launched on December 18, 2014 and contains documentation about the setup process, the platforms and components, and for the developers. ### {% linkable_title Logo %} @@ -31,15 +31,15 @@ Home Assistant is open source software and available under the [MIT](https://ope This sections just contains some random numbers of the Home Assistant eco-system. -| Description | 2015 | +| Description | 2015 | |---|---| -| [Gitter.io](https://gitter.im/balloob/home-assistant) | 334 | -| [Forum posts](https://automic.us/forum/index.php) | 352 | -| [Forum topics](https://automic.us/forum/index.php) | 83 | -| [Forum members](https://automic.us/forum/index.php) | 92 | -| [Github stars](https://github.com/balloob/home-assistant/stargazers) | 2519 | +| [Gitter.io](https://gitter.im/balloob/home-assistant) | 334 | +| [Forum posts](https://community.home-assistant.io/) | 352 | +| [Forum topics](https://community.home-assistant.io/) | 83 | +| [Forum members](https://community.home-assistant.io/) | 92 | +| [Github stars](https://github.com/balloob/home-assistant/stargazers) | 2519 | | [Github forks](https://github.com/balloob/home-assistant/network) | 374 | -| Pageviews [ha.io](https://home-assistant.io) | 190'271| +| Page views [ha.io](https://home-assistant.io) | 190'271| ### {% linkable_title Commit per year %} @@ -49,6 +49,7 @@ The numbers below only covers the [main git repository](https://github.com/ballo 2013: 147 2014: 328 2015: 2963 +2016: 1439 (so far) ``` More details and statistics can be found on [Github](https://github.com/balloob/home-assistant/graphs/contributors).