jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 01:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into next

Browse Source 
Conflicts:
	source/_components/zwave.markdown
This commit is contained in:
Paulus Schoutsen 2016-04-01 00:02:26 -07:00
commit 3dc15ca6de
54 changed files with 610 additions and 469 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
README.markdown
View File

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

43
source/_components/alexa.markdown
View File

@ -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.
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/1Ke3mtWd_cQ" frameborder="0" allowfullscreen></iframe>
</div>
### {% 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:

30
source/_components/automation.markdown
View File

@ -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)

7
source/_components/binary_sensor.rest.markdown
View File

@ -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.
<p class='note warning'>
Make sure that the URL matches exactly your endpoint or resource.

22
source/_components/binary_sensor.tcp.markdown
View File

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

17
source/_components/binary_sensor.vera.markdown Normal file
View File

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

4
source/_components/camera.mjpeg.markdown
View File

@ -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.
<p class='note'>
There is a <a href="https://github.com/shazow/urllib3/issues/800" target="_blank">known issue in urllib3</a> that you will get error messages in your logs like <code>[StartBoundaryNotFoundDefect(), MultipartInvariantViolationDefect()], unparsed data: ''</code> but the component still works fine. You can ignore the messages.
</p>

7
source/_components/conversation.markdown
View File

@ -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 <Friendly Name> <on/off>`.
The conversation component can process sentences into commands for Home Assistant. It is currently limited to parsing commands in the format `turn <Friendly Name> <on/off>`.
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
<p class='img'>
<img src="/images/screenshots/voice-commands.png" />
</p>
<p class='note'>
Apple iPhones do not support this feature in any browser.
</p>

1
source/_components/ecobee.markdown
View File

@ -9,6 +9,7 @@ sharing: true
footer: true
logo: ecobee.png
ha_category: Hub
featured: true
---

4
source/_components/http.markdown
View File

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

5
source/_components/influxdb.markdown
View File

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

21
source/_components/input_boolean.markdown
View File

@ -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!"
```

2
source/_components/light.hue.markdown
View File

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

2
source/_components/light.rfxtrx.markdown
View File

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

27
source/_components/light.vera.markdown
View File

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

8
source/_components/logger.markdown
View File

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

11
source/_components/media_player.sonos.markdown
View File

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

10
source/_components/mqtt.markdown
View File

@ -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).
<p class='note'>
This broker does not currently work with OwnTracks because of a protocol version issue.
</p>
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

2
source/_components/proximity.markdown
View File

@ -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'

20
source/_components/scene.markdown
View File

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

4
source/_components/sensor.mqtt.markdown
View File

@ -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 %}
```

6
source/_components/sensor.rest.markdown
View File

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

50
source/_components/sensor.tcp.markdown
View File

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

27
source/_components/sensor.vera.markdown
View File

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

9
source/_components/sun.markdown
View File

@ -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.
<p class='img'>
<img src='/images/screenshots/more-info-dialog-sun.png' />
@ -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.

2
source/_components/switch.command_line.markdown
View File

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

2
source/_components/switch.rfxtrx.markdown
View File

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

26
source/_components/switch.vera.markdown
View File

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

17
source/_components/vera.markdown
View File

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

4
source/_components/weblink.markdown
View File

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

1
source/_components/wemo.markdown
View File

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

4
source/_components/zone.markdown
View File

@ -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'**.
<p class='note'>
Devices that are in the zone **'Home'** will not appear on the map in the Home Assistant UI.
</p>
#### {% 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`.

112
source/_components/zwave.markdown
View File

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

108
source/_cookbook/automation_flashing_lights.markdown Normal file
View File

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

12
source/_cookbook/configuration_yaml_from_bassclarinetl2.markdown
View File

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

2
source/_cookbook/customize_polling_interval.markdown
View File

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

12
source/_cookbook/foscam_away_mode_PTZ.markdown
View File

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

8
source/_cookbook/restart_ha_if_wemo_switch_is_not_detected.markdown
View File

@ -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:

16
source/_cookbook/turn_on_light_for_10_minutes_when_motion_detected.markdown
View File

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

4
source/_posts/2015-08-26-laundry-automation-with-moteino-mqtt-and-home-assistant.markdown
View File

@ -55,6 +55,10 @@ Materials used:
Home Assistant Configuration:
<p class='note'>
The automation and script syntax here is using a deprecated and no longer supported format.
</p>
```yaml
mqtt:
broker: 192.168.1.100

2
source/_posts/2015-12-06-community-highlights.markdown
View File

@ -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!

2
source/_posts/2016-02-20-community-highlights.markdown
View File

@ -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.
<p class='img'>
<img src='/images/blog/2016-02-community-highlights/garfield-nfc.png'>

214
source/_topics/splitting_configuration.markdown
View File

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

5
source/_topics/z-wave.markdown
View File

@ -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.
<p class='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.
</p>
## {% 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 %}

16
source/developers/architecture.markdown
View File

@ -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.
<p class='img'>
<a href='/images/architecture/ha_architecture.png' name='architecture'>
@ -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
</p>
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.
</p>
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.
</p>
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()
```
<p class='note'>
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.
</p>

3
source/developers/credits.markdown
View File

@ -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)

8
source/developers/website.markdown
View File

@ -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/).

47
source/getting-started/autostart.markdown
View File

@ -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
</div> <!-- UPSTART -->
<div class='advanced-installs systemd' markdown='1'>
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 <<EOF >> /lib/systemd/system/home-assistant.service
$ su -c 'cat <<EOF >> /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]
```
</div> <!-- SYSTEMD -->

11
source/getting-started/configuration.markdown
View File

@ -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/).
<p class='note'>
You will have to restart Home Assistant for changes in <code>configuration.yaml</code> 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 `<Router model> 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 &raquo;](/getting-started/devices/)

2
source/getting-started/index.markdown
View File

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

37
source/getting-started/troubleshooting-configuration.markdown
View File

@ -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"
[...]
...
```
<p class='note'>
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.
</p>

8
source/getting-started/troubleshooting.markdown
View File

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

2
source/help/index.markdown
View File

@ -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 %}

17
source/help/trivia.markdown
View File

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