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-24 09:46:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1515 from home-assistant/next

Browse Source 
0.34
This commit is contained in:
Fabian Affolter 2016-12-03 22:05:53 +01:00 committed by GitHub
commit fda0b14c13
59 changed files with 1915 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
_config.yml
View File

@ -128,10 +128,12 @@ social:
twitter:
account: home_assistant
# Home Assistant release details
current_major_version: 0
current_minor_version: 33
current_patch_version: 4
date_released: 2016-11-23
current_minor_version: 34
current_patch_version: 0
date_released: 2016-12-03
# Either # or the anchor link to latest release notes in the blog post.
# Must be prefixed with a # and have double quotes around it.
patch_version_notes: "#release-0334---november-24"
patch_version_notes: "#"

11
source/_components/binary_sensor.nest.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Binary Sensor
ha_release: pre 0.7
---
@ -22,19 +22,12 @@ You must have the [Nest component](/components/nest/) configured to use these se
To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: nest
monitored_conditions:
- 'fan'
- 'hvac_ac_state'
- 'hvac_heater_state'
- 'hvac_aux_heater_state'
- 'hvac_heat_x2_state'
- 'hvac_heat_x3_state'
- 'hvac_alt_heat_state'
- 'hvac_alt_heat_x2_state'
- 'hvac_emer_heat_state'
- 'online'
```
Configuration variables:

42
source/_components/binary_sensor.threshold.markdown Normal file
View File

@ -0,0 +1,42 @@
---
layout: page
title: "Threshold Binary Sensor"
description: "Instructions how to integrate threshold binary sensors into Home Assistant."
date: 2016-11-26 12:10
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Binary Sensor
ha_iot_class: "Local Polling"
ha_release: 0.34
---
The `threshold` binary sensor platform is consuming the state from another sensor. If the value is below (`lower`) or higher (`upper`) than the given threshold then state of this sensor change..
It's an alternative to the template binary sensor's `value_template:` to get the abnormal/too high/too low states.
```yaml
{% raw %}{{ states.sensor.furnace.state > 2.5 }}{% endraw %}
```
To enable the threshold sensor, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
sensor:
- platform: threshold
threshold: 15
type: lower
entity_id: sensor.random
```
Configuration variables:
- **entity_id** (*Required*): The entity to monitor. Only [sensors](/components/sensor/) are supported.
- **threshold** (*Required*): The value which is the threshold.
- **type** (*Required*): `lower` if the value needs to be below the threshold or `upper` if higher.
- **name** (*Optional*): Name of the sensor to use in the frontend. Defaults to `Stats`.

34
source/_components/camera.amcrest.markdown Normal file
View File

@ -0,0 +1,34 @@
---
layout: page
title: "Amcrest Camera"
description: "Instructions how to integrate Amcrest camera into Home Assistant."
date: 2016-12-03 08:10
sidebar: true
comments: false
sharing: true
footer: true
logo: amcrest.png
ha_category: Camera
ha_release: 0.34
---
The `amcrest` platform allows you to watch the live stream of your [Amcrest](https://amcrest.com/) IP camera in Home Assistant.
To enable your Amcrest camera in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
camera:
- platform: amcrest
host: IP_ADDRESS
username: USERNAME
password: PASSWORD
```
Configuration variables:
- **host** (*Required*): The IP address your camera.
- **port** (*Optional*): The port that the camera is running on. The default is 80.
- **username** (*Required*): The username for accessing your camera.
- **password** (*Required*): The password for accessing your camera.
- **name** (*Optional*): This parameter allows you to override the name of your camera.

27
source/_components/camera.nest.markdown Normal file
View File

@ -0,0 +1,27 @@
---
layout: page
title: "Nest Camera"
description: "Instructions how to integrate Nest cameras into Home Assistant."
date: 2016-12-03 08:10
sidebar: true
comments: false
sharing: true
footer: true
logo: nest.png
ha_category: Camera
ha_release: 0.34
---
The `nest` platform allows you to watch the live stream of your [Nest](https://nest.com/camera/meet-nest-cam/) camera in Home Assistant.
<p class='note'>
You must have the [Nest component](/components/nest/) configured to use those thermostats.
</p>
To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
camera:
- platform: nest
```

2
source/_components/climate.generic_thermostat.markdown
View File

@ -34,6 +34,7 @@ Configuration variables:
- **target_temp** (*Optional*): Set initial target temperature. Failure to set this variable will result in target temperature being set to null on startup.
- **ac_mode** (*Optional*): Set the switch specified in the *heater* option to be treated as a cooling device instead of a heating device.
- **min_cycle_duration** (*Optional*): Set a minimum amount of time that the switch specified in the *heater* option must be in it's current state prior to being switched either off or on.
- **tolerance** (*Optional*): Set a minimum amount of temperature change that the sensor specified in the *target_sensor* option must change prior to being switched either off or on.
A full configuration example looks like the one below. `min_cycle_duration` must contains at least one of the following entries: `days:`, `hours:`, `minutes:`, `seconds:` or `milliseconds:`.
@ -47,6 +48,7 @@ climate:
min_temp: 15
max_temp: 21
target_temp: 17
tolerance: 0.3
min_cycle_duration:
seconds: 5
```

4
source/_components/climate.mysensors.markdown
View File

@ -29,8 +29,8 @@ Home Assistant State | MySensors State
---------------------|----------------
STATE_COOL | CoolOn
STATE_HEAT | HeatOn
STATE_AUTO | Off
STATE_OFF | AutoChangeOver
STATE_AUTO | AutoChangeOver
STATE_OFF | Off
Currently humidity, away_mode, aux_heat, swing_mode is not supported. This will be included in later versions as feasible.

5
source/_components/climate.nest.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Climate
---
@ -21,8 +21,9 @@ You must have the [Nest component](/components/nest/) configured to use those th
To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
climate:
platform: nest
- platform: nest
```
<p class='img'>

1
source/_components/demo.markdown
View File

@ -25,6 +25,7 @@ Available demo platforms:
- [Light](/components/light/) (`light`)
- [Lock](/components/lock/) (`lock`)
- [Notification](/components/notify/) (`notify`)
- [Remote](/components/remote/) (`remote`)
- [Sensor](/components/sensor/) (`sensor`)
- [Switch](/components/switch/) (`switch`)
- [Weather](/components/weather/) (`weather`)

48
source/_components/device_tracker.gpslogger.markdown Normal file
View File

@ -0,0 +1,48 @@
---
layout: page
title: "GPSLogger"
description: "Instructions how to use GPSLogger to track devices in Home Assistant."
date: 2016-11-25 15:00
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Presence Detection
ha_release: 0.34
---
This platform allows you to detect presence using [GPSLogger](http://code.mendhak.com/gpslogger/). GPSLogger is an open source app for [Android](https://play.google.com/store/apps/details?id=com.mendhak.gpslogger) that allows users to set up a `GET` request to update GPS coordinates. This can be configured with Home Assistant to update your location.
To integrate GPSLogger in Home Assistant, add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
device_tracker:
- platform: gpslogger
```
## {% linkable_title Setup on your smartphone %}
- [GPSLogger for Android](https://play.google.com/store/apps/details?id=com.mendhak.gpslogger)
To configure GPSLogger, you must set up the app to send a `GET` request to your Home Assistant server at `http://<ha_server>/api/gpslogger?latitude=%LAT&longitude=%LON&battery=%BATT&device=%SER&accuracy=%ACC`. Make sure to include the API password if you have configured a password in Home Assistant (add `?api_password=<password>` to the end of the URL). Configure that options under "General Options":
- Start on boot: yes
- Start on app launch: yes
Set the URL under "General Options -> Logging details":
- Log to GPX: no
- Log to KML: no
- Log to custom URL: yes and set `http://<ha_server>/api/gpslogger?latitude=%LAT&longitude=%LON&battery=%BATT&device=%SER&accuracy=%ACC` (be sure you include API password (`api_password=<password>`) if needed, or you can also use HTTP Basic authentication `http://<username>:<password>@<ha_server>/api/gpslogger...`)
- Log to OpenGTS Server: no
- Log to Plain Text: no
- Log to NMEA: no
You should also tune GPSLogger performance to save your battery under "General Options -> Logging details -> Performance -> Location providers":
- GPS: no
- Network: no
- Passive: yes
A request can be forced from the app to test if everything is working fine. A succesfull request will update `known_devices.yaml` with device serial number.

5
source/_components/fan.nest.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Fan
ha_release: 0.29
ha_iot_class: "Local Polling"
@ -23,7 +23,8 @@ You must have the [Nest component](/components/nest/) configured to use those th
To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
fan:
platform: nest
- platform: nest
```

14
source/_components/foursquare.markdown
View File

@ -28,6 +28,20 @@ Configuration variables:
- **access_token** (*Required*): A Foursquare API access token.
- **push_secret** (*Required*): The push secret that Foursquare provides to you in the app dashboard.
#### Getting the access token ####
After you have registered your APP on your [My Apps Page](https://foursquare.com/developers/apps) you get a `CLIENT_ID` and you have specified a
`REDIRECT_URL` which can be any URL you like, but since it will get your access token via a HTTP GET request, it should be a URL which will ignore the `access_token` HTTP GET variable. A good idea is to choose the URL of your Home Assistant.
Visit the following URL in your browser:
```
https://foursquare.com/oauth2/authenticate?client_id=CLIENT_ID&response_type=token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
```
and change the `CLIENT_ID` and `YOUR_REGISTERED_REDIRECT_URL` to your actual values.
You will receive an OAuth request landing page, asking you if you want to connect your Foursquare account to your newly created app. Say "Yes".
After that, you will get redirected to your `REDIRECT_URL` with the `access_token` as a HTTP GET variable. Copy everything after the = and paste it in your configuration.yaml as the `access_token`.
### {% linkable_title Real-Time API %}
The component accepts pushes from Foursquare at `/api/foursquare`. The route does not require authentication.

162
source/_components/homematic.markdown
View File

@ -2,7 +2,7 @@
layout: page
title: "Homematic"
description: "Instructions for integrating Homematic into Home Assistant."
date: 2016-06-28 23:25
date: 2016-11-27 21:38
sidebar: true
comments: false
sharing: true
@ -14,54 +14,100 @@ featured: false
---
The [Homematic](http://www.homematic.com/) component provides bi-directional communication of Homematic platforms with their real world counterparts. This implementation does in no way modify your existing setup. Instead it queries your setup for its devices and subscribes to them to send and receive events.
The [Homematic](http://www.homematic.com/) component provides bi-directional communication with your CCU/Homegear. It uses a XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit.
Device support is currently available for most of:
Device support is available for most of the wired and wireless devices, as well as a few IP devices. If you have a setup with mixed protocols, you have to configure additional hosts with the appropriate ports. The default is using port 2001, which are wireless devices. Wired devices usually are available through port 2000 and IP devices through port 2010.
- Switch/Dimmer-actors
- Thermostats
- Rollershutters
- Sensors (shutter contacts, motion detectors, power meters and more)
- Simple remote controls
If you want to see if a specific device you have is supported, head over to the [pyhomematic](https://github.com/danielperna84/pyhomematic/tree/master/pyhomematic/devicetypes) repository and browse through the source code. A dictionary with the device identifiers (e.g. HM-Sec-SC-2) can be found within the relevant modules near the bottom.
If you want to see if a specific device you have is supported, head over to the [pyhomematic](https://github.com/danielperna84/pyhomematic/tree/master/pyhomematic/devicetypes) repository and browse through the source code. A dictionary with the device identifiers (e.g. HM-Sec-SC-2) can be found within the relevant modules near the bottom. If your device is not supported, feel free to contribute.
We automatically detect all devices we currently support and try to generate useful names. If you enable name-resolving, we try to fetch names from Metadata (Homegear), via JSON-RPC or the XML-API you may have installed on your CCU. Since this may fail this is disabled by default.
You can manually override the created entities be using Home Assistants [Customizing](https://home-assistant.io/getting-started/customizing-devices/) feature. With it you are able to hide entities you don't need to see within the UI.
You can manually rename the created entities by using Home Assistants [Customizing](https://home-assistant.io/getting-started/customizing-devices/) feature. With it you are also able to hide entities you don't want to see in the UI.
To set up the component, add the following information to your `configuration.yaml` file:
```yaml
homematic:
local_ip: 127.0.0.1
hosts:
wireless:
ip: 127.0.0.1
```
Configuration variables:
Configuration variables (global):
- **local_ip** (*Required*): IP of device running Home Assistant
- **local_port** (*Optional*): Port for connection with Home Assistant. Defaults to 8943.
- **remote_ip** (*Required*): IP of CCU/Homegear
- **remote_port** (*Optional*): Port of Homegear/CCU XML-RPC Server (usually 2001)
- **resolvenames** (*Optional*): <metadata, json, xml> Try to fetch device names. Defaults to `False` if not specified.
- **hosts** (*Required*): Configuration for each host to integrate into Home Assistant.
- **local_ip** (*Optional*): IP of device running Home Assistant. Override autodetected value for exotic network setups.
- **local_port** (*Optional*): Port for connection with Home Assistant. By default it is randomly assigned.
- **delay** (*Optional*): [Float] Delay fetching of current state per device on startup. Used to prevent overloading of the CCU. Defaults to 0.5.
Configuration variables (host):
- **ip** (*Required*): IP of CCU/Homegear
- **port** (*Optional*): Port of Homegear/CCU XML-RPC Server (default is 2001, use 2000 for wired and 2010 for IP)
- **resolvenames** (*Optional*): [`metadata`, `json`, `xml`] Try to fetch device names. Defaults to `false` if not specified.
- **username** (*Optional*): When fetching names via JSON-RPC, you need to specify a user with guest-access to the CCU.
- **password** (*Optional*): When fetching names via JSON-RPC, you need to specify the password of the user you have configured above.
- **delay** (*Optional*): <Float> Delay fetching of current state per device on startup. Used to prevent overloading of the CCU. Defaults to 0.5.
- **variables** (*Optional*): True or False if you want use CCU2/Homegear variables. Default False.
- **primary** (*Optional*): Set to `true` when using multiple hosts and this host should provide the services and variables.
- **variables** (*Optional*): Set to `true` if you want to use CCU2/Homegear variables. Should only be enabled for the primary host.
#### Example configuration with multiple protocols and some other options set:
```yaml
homematic:
delay: 1.0
hosts:
rf:
ip: 127.0.0.1
resolvenames: json
username: Admin
password: secret
primary: true
variables: true
wired:
ip: 127.0.0.1
port: 2000
resolvenames: json
username: Admin
password: secret
ip:
ip: 127.0.0.1
port: 2010
```
### The `resolvenames` option
To further explain the `resolvenames` option:
We use three approaches to fetch the names of devices. Each assumes you have properly named your devices in your existing Homematic setup. As a general advice: Use ASCII for your devices names. Home Assistant won't include non-ASCII characters in entity-names.
1. The CCU allows to fetch details of the paired devices via JSON-RPC. For this to work you need to add valid credentials to your component-configuration. Guest-access is sufficient to query for device names.
2. If you use a regular CCU, there is an add-on called the "XML-API". With it installed, you are able to fetch all kinds of information from you CCU using XML-RPC. We can leverage this and fetch the names of devices set within the CCU. We don't support authentication with this method.
3. Homegear provides device-names through the metadata devices internally have. When using an HM-CFG-LAN interface, you typically use a configuration software ("HomeMatic-Komponenten konfigurieren" is the name of the shortcut on your desktop by default) to pair and configure your devices. If you have paired devices, you'll see them listed in a table. The leftmost column (Name) is prefilled with default names. You can click such a name and enter whatever you like.
1. `json`: The CCU allows to fetch details of the paired devices via JSON-RPC. For this to work you need to add valid credentials to your component-configuration. Guest-access is sufficient to query for device names.
2. `xml`: If you use a CCU, there is an add-on called the "XML-API". With it installed, you are able to fetch all kinds of information from you CCU using XML-RPC. We can leverage this and fetch the names of devices set within the CCU. We don't support authentication with this method.
3. `metadata`: Homegear provides device-names through the metadata devices internally have. When using an HM-CFG-LAN interface, you typically use a configuration software ("HomeMatic-Komponenten konfigurieren" is the name of the shortcut on your desktop by default) to pair and configure your devices. If you have paired devices, you'll see them listed in a table. The leftmost column (Name) is prefilled with default names. You can click such a name and enter whatever you like.
Resolving names can take some time. So when you start Home Assistant you won't see you devices at first. For a setup with 20+ devices it can take up to a minute until all devices show up in the UI.
**Devices with buttons**
### Multiple hosts
In order to allow communication with multiple hosts or different protocols in parallel (wireless, wired and ip), multiple connections will be established, each to the configured destination. The name you choose for the host has to be unique and limited to ASCII letters.
Using multiple hosts has the drawback, that the services (explained below) may not work as expected. Only one connection can be used for services, which limits the devices/variables a service can use to the scope/protocol of the host.
This does *not* affect the entites in Home Assistant. They all use their own connection and work as expected.
### Variables
It is possible to read and set values of system variables you have setup on the CCU/Homegear. An example of how that is done can be found below. The supported types for setting values are float- and bool-variables.
Each variable will be available as it's own entity in the form of `homematic.name`. The predefined `homematic.homematic` variable has the number of service messages as it's value. You can use these variable-entities like any other entity in Home Assistant to trigger automations.
The values of variables are polled from the CCU/Homegear in an interval of 30 seconds. Setting the value of a variable happens instantly and is directly pushed.
### Events
When HomeMatic devices change their state or some other internal value, the CCU/Homegear sends event messages to Home Assistant. These events are automatically parsed and the entities in Home Assistant are updated. However, you can also manually use these events to trigger automations. Two event-types are available:
* **homematic.keypress**: For devices with buttons, see information below
* **homematic.impulse**: For impulse sensors
#### Devices with buttons
Devices with buttons (e.g. HM-Sen-MDIR-WM55, remote controls) may not be fully visible in the UI. This is intended, as buttons don't serve any value here and all they do is trigger events.
As an example:
The HM-Sen-MDIR-WM55 motion detector will be displayed as 2 entities. A motion sensor and a brightness sensor. On top of that we have 2 sets (one set per button) of 4 events: PRESS_SHORT, PRESS_LONG, PRESS_CONT, PRESS_LONG_RELEASE. Be aware, that there are devices which don't provide all of these events. But in general: if you can press it, it at least has PRESS_SHORT.
The HM-Sen-MDIR-WM55 motion detector will be displayed as 2 entities. A motion sensor and a brightness sensor. On top of that we have 2 sets (one set per button) of 4 events: PRESS_SHORT, PRESS_LONG, PRESS_CONT, PRESS_LONG_RELEASE. Be aware, that there are devices which don't provide all of these events. But in general: if you can press it, it usually at least has PRESS_SHORT.
Here's an example of how to use these events for automations:
```yaml
@ -76,25 +122,22 @@ automation:
action:
service: switch.turn_on
entity_id: switch.Kitchen_Ambience
```
The channel parameter is equal to the channel of the button you are configuring the automation for. You can view the available channels in the UI you use to pair your devices.
The name depends on if you chose to resolve names or not. If not, it will be the device ID (e.g. LEQ1234657). If you chose to resolve names (and that is successful), it will be the name you have set in your CCU or in the metadata (e.g. "Kitchen Switch").
**Other events**
### Services
*homematic.keypress*: See above.
*homematic.impulse*: For impulse sensors with event_data 'name' and 'channel'.
**Service**
*homematic/virtualkey*: Simulate a keypress on CCU/Homegear with device or virtual keys.
* *homematic.virtualkey*: Simulate a keypress (or other valid action) on CCU/Homegear with device or virtual keys.
* *homematic.reconnect*: Reconnect to CCU/Homegear without restarting Home Assistant (useful when CCU has been restarted)
* *homematic.set_var_value*: Set the value of a system variable.
* *homematic.set_dev_value*: Control a device manually (even devices without support). Equivalent to setValue-method from XML-RPC.
#### Examples
Simulate a button being pressed
```yaml
...
action:
service: homematic.virtualkey
data:
@ -103,14 +146,53 @@ action:
param: PRESS_LONG
```
*homematic/set_value*: Set the value of a system variable.
Open KeyMatic
```yaml
...
action:
service: homematic.set_value
service: homematic.virtualkey
data:
address: LEQ1234567
channel: 1
param: OPEN
```
Set variable
```yaml
...
action:
service: homematic.set_var_value
data:
entity_id: homematic.varname_bool
value: true
```
#### Advanced examples
If you are familiar with the internals of HomeMatic devices, you can manually set values on the devices. This can serve as a workaround if support for a device is currently not available, or only limited functionality has been implemented.
Using this service provides you direct access to the setValue-method of the primary connection. If you have multiple hosts, you may select the one hosting a specific device by providing the proxy-parameter with a value equivalent to the name you have chosen. In the example configuration from above `rf`, `wired` and `ip` would be valid values.
Manually turn on a switch actor
```yaml
...
action:
service: homematic.set_dev_value
data:
address: LEQ1234567
channel: 1
param: STATE
value: true
```
Manually set temperature on thermostat
```yaml
...
action:
service: homematic.set_dev_value
data:
address: LEQ1234567
channel: 4
param: SET_TEMPERATURE
value: 23.0
```

17
source/_components/http.markdown
View File

@ -34,6 +34,8 @@ Configuration variables:
- **cors_allowed_origins** (*Optional*): A list of origin domain names to allow [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests from. Enabling this will set the `Access-Control-Allow-Origin` header to the Origin header if it is found in the list, and the `Access-Control-Allow-Headers` header to `Origin, Accept, X-Requested-With, Content-type, X-HA-access`. You must provide the exact Origin, i.e. `https://home-assistant.io` will allow requests from `https://home-assistant.io` but __not__ `http://home-assistant.io`.
- **use_x_forwarded_for** (*Optional*): Enable parsing of the `X-Forwarded-For` header, passing on the client's correct IP address in proxied setups. You should only enable this in a trustworthy network environment, as clients passing that header could easily spoof their source IP address.
- **trusted_networks** (*Optional*): List of trusted networks, consisting of IP addresses or networks, that are allowed to bypass password protection when accessing Home Assistant.
- **ip_ban_enabled** (*Optional*): Flag indicating whether additional IP filtering is enabled. Defaults to False.
- **login_attempts_threshold** (*Optional*): Number of failed login attemt from single IP after which it will be automatically banned if `ip_ban_enabled` is True. Defaults to -1, meaning that no new automatic bans will be added.
The sample below shows a configuration entry with possible values:
@ -52,6 +54,8 @@ http:
- ::1
- 192.168.0.0/24
- 2001:DB8:ABCD::/48
ip_ban_enabled: True
login_attempts_threshold: 5
```
The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/).
@ -65,3 +69,16 @@ To use those kind of [sensors](/components/sensor.http/) or [binary sensors](com
All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent to the endpoint of the device and must be **POST**.
If you want to use Home Assistant to host or serve static files then create a directory called `www` under the `.homeassistant` configuration path. The static files in `.homeassistant/www/` can be accessed by the following URL `http://your.domain:8123/local/`.
If you want to apply additional IP filtering, and automatically ban bruteforce attempts, set `ip_ban_enabled` to `True` and select number of attempts. After first ban file `ip_bans.yaml` will be created in the root configuration folder. It will have IP address and time in UTC when it was added:
```yaml
127.0.0.1:
banned_at: '2016-11-16T19:20:03'
```
After a ban is added a Persistent Notification is populated to the Home Assistant frontend.
<p class='note warning'>
Please note, that sources from `trusted_networks` won't be banned automatically.
</p>

4
source/_components/ifttt.markdown
View File

@ -87,8 +87,8 @@ automation:
service: script.ifttt_notify
data_template:
value1: 'HA Status:'
value2: "{{ trigger.event.data.entity_id.split('_')[1] }} is "
value3: "{{ trigger.event.data.to_state.state }}"
value2: {% raw %}"{{ trigger.event.data.entity_id.split('_')[1] }} is "{% endraw %}
value3: {% raw %}"{{ trigger.event.data.to_state.state }}"{% endraw %}
```
```yaml

2
source/_components/influxdb.markdown
View File

@ -32,6 +32,7 @@ Configuration variables:
- **database** (*Optional*): Name of the database to use. Defaults to `home_assistant`. The database must already exist.
- **ssl** (*Optional*): Use https instead of http to connect. Defaults to false.
- **verify_ssl** (*Optional*): Verify SSL certificate for https request. Defaults to false.
- **default_measurement** (*Optional*): Measurement name to use when an entity doesn't have a unit. Defaults to entity id.
- **blacklist** (*Optional*): List of entities not logged to InfluxDB.
- **whitelist** (*Optional*): List of the entities (only) that will be logged to InfluxDB. If not set, all entities will be logged. Values set by the **blacklist** option will prevail.
- **tags** (*Optional*): Tags to mark the data.
@ -51,6 +52,7 @@ influxdb:
password: MY_PASSWORD
ssl: true
verify_ssl: true
default_measurement: state
blacklist:
- entity.id1
- entity.id2

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

@ -35,3 +35,56 @@ Configuration variables:
- **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.
### {% linkable_title Using Hue Scenes in Home Assistant %} ###
The Hue platform has it's own concept of Scenes for setting the colors
of a group of lights at once. Hue Scenes are very cheap, get created
by all kinds of apps (as it is the only way to have 2 or more lights
change at the same time), and are rarely deleted. A typical Hue hub
might have hundreds of scenes stored in them, many that you've never
used, almost all very poorly named.
To avoid user interface overload we don't expose Scenes
directly. Instead there is a
[light.hue_activate_scene]/(/components/light/#service-lighthue_activate_scene)
service which can be used by `automation` or `script` components. For
instance:
```
script:
porch_on:
sequence:
- service: light.hue_activate_scene
data:
group_name: "Porch"
scene_name: "Porch Orange"
```
*** Finding Group and Scene Names ***
How do you find these names?
The easiest way to do this is only use the scenes from the 2nd
generation Hue app. That is organized by Room (Group) and Scene
Name. Use the values of Room name and Scene name that you see in the
app. You can test these work on the `dev-service` console of your Home
Assistant instance.
Alternatively, you can dump all rooms and scene names using this
[gist](https://gist.github.com/sdague/5479b632e0fce931951c0636c39a9578). This
does **not** tell you which groups and scenes work together but it's
sufficient to get values that you can test in the `dev-service` console.
*** Caveats ***
The Hue API doesn't activate Scenes directly, only on a Hue Group
(typically Rooms, especially if using the 2nd gen app). But Hue Scenes
don't actually reference their group. So heuristic matching is used.
Neither Group names or Scene names are guarunteed unique in Hue. If
you are getting non deterministic behavior, adjust your Hue scenes via
the App to be more identifying.
The Hue hub has limitted spaces for Scenes, and will delete Scenes if
new ones get created that would overflow that space. The API docs say
this is based on Least Recently Used.

31
source/_components/litejet.markdown
View File

@ -8,7 +8,7 @@ comments: false
sharing: true
footer: true
ha_category: Hub
ha_iot_class: "Local Polling"
ha_iot_class: "Local Push"
ha_release: 0.32
---
@ -27,18 +27,12 @@ Your LiteJet MCP should be configured for 19.2 K baud, 8 data bits, 1 stop bit,
You can also configure the Home Assistant to ignore lights, scenes, and switches via their name. This is highly recommended since LiteJet has a fixed number of each of these and with most systems many will be unused.
```yaml
litejet:
```
Configuration variables:
- **port** (*Required*): The path to the serial port connected to the LiteJet.
- **exclude_names** (*Optional*): A list of light or switch names that should be ignored.
- **include_switches** (*Optional*): Cause entities to be created for all the LiteJet switches. Default is `false`. This can be useful when debugging your lighting as you can press/release switches remotely.
```yaml
litejet:
exclude_names:
@ -49,3 +43,26 @@ litejet:
- 'LV Rel #'
- 'Fan #'
```
### Trigger
LiteJet switches can be used as triggers too to allow those buttons to behave differently based on hold time. For example, automation can distinguish quick tap versus long hold.
- **platform** (*Required*): Must be 'litejet'.
- **number** (*Required*): The switch number to be monitored.
- **held_more_than** (*Optional*): The minimum time the switch must be held before the trigger can activate.
- **held_less_than** (*Optional*): The maximum time the switch can be held for the trigger to activate.
The trigger will activate at the earliest moment both `held_more_than` and `held_less_than` are known to be satisfied. If neither are specified, the trigger activates the moment the switch is pressed. If only `held_more_than` is specified, the trigger will activate the moment the switch has been held down at least that time. If `held_less_than` specified, the trigger can only activate when the switch is released.
```yaml
automation:
- trigger:
platform: litejet
number: 55
held_more_than:
milliseconds: 1000
held_less_than:
milliseconds: 2000
...
```

33
source/_components/media_player.dunehd.markdown Normal file
View File

@ -0,0 +1,33 @@
---
layout: page
title: "DuneHD media players"
description: "Instructions how to integrate DuneHD media players into Home Assistant."
date: 2016-11-26 09:00
sidebar: true
comments: false
sharing: true
footer: true
logo: dunehd.png
ha_category: Media Player
ha_iot_class: "Local Polling"
ha_release: 0.34
---
The `dunehd` platform allows you to control a [Dune HD media player](http://dune-hd.com/eng/products/full_hd_media_players) from Home Assistant. Support is based on the official [IP protocol](http://dune-hd.com/support/ip_control/dune_ip_control_overview.txt) published by Dune.
Devices with firmware 110127_2105_beta or above are supported. Some functions may depend on the version of the protocol (volume / mute control is only available with version 2 onwards).
To add a Dune HD player to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: dunehd
host: IP_ADDRESS
```
Configuration variables:
- **host** (*Required*): IP address or hostname of the device. Example: 192.168.1.32
- **name** (*Optional*): Name of the device.
- **sources** (*Optional*): A name-value dictionary of sources that HA component can request to play.

9
source/_components/media_player.philips_js.markdown
View File

@ -10,7 +10,7 @@ footer: true
logo: philips.png
ha_category: Media Player
ha_iot_class: "Local Polling"
ha_release: 0.32
ha_release: 0.34
---
@ -21,12 +21,11 @@ To add your TV to your installation, add the following to your `configuration.ya
```yaml
# Example configuration.yaml entry
media_player:
- name: NAME
platform: philips_js
host: 192.168.1.99
- platform: philips_js
host: 192.168.1.99
```
Configuration variables:
- **name** (*Optional*): The name you would like to give to the Philips TV.
- **host** (*Required*): IP address of TV.
- **name** (*Optional*): The name you would like to give to the Philips TV.

98
source/_components/media_player.soundtouch.markdown Normal file
View File

@ -0,0 +1,98 @@
---
layout: page
title: "Soundtouch"
description: "Instructions how to integrate Bose Soundtouch devices into Home Assistant."
date: 2016-11-06 13:00
sidebar: true
comments: false
sharing: true
footer: true
logo: soundtouch.jpg
ha_category: Media Player
ha_release: X.X.X
ha_iot_class: "Local Polling"
---
The `soundtouch` platform allows you to control your [Bose Soundtouch](https://www.soundtouch.com/) speakers from Home Assistant.
To add your Soundtouch components to your installation, add the following to your `configuration.yaml` file.
```yaml
# Example configuration.yaml
media_player:
- platform: soundtouch
host: 192.168.1.1
port: 8090
name: Soundtouch Living Room
```
Or for multiple hosts
```yaml
# Example configuration.yaml with many devices
media_player:
- platform: soundtouch
host: 192.168.1.1
port: 8090
name: Soundtouch Living Room
- platform: soundtouch
host: 192.168.1.1
port: 8090
name: Soundtouch kitchen
```
Configuration variables:
- **host** (*Required*): The host name or address of the Soundtouch device.
- **name** (*Required*): The name of the device used in the frontend.
- **port** (*Optional*): The port number. Defaults to 8090.
You can switch between one of your 6 pre-configured presets using ```media_player.play_media```
```yaml
# Play media in configuration.yaml
- service: media_player.play_media
data:
entity_id: media_player.soundtouch_living_room
media_content_id: 1..6
media_content_type: PLAYLIST
```
### {% linkable_title Service `soundtouch_play_everywhere` %}
Create a multi-room (zone) from a master and play same content on all other
devices (slaves)
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `master` | no | `entity_id` of the master device
### {% linkable_title Service `soundtouch_create_zone` %}
Create a multi-room (zone) from a master and play on selected slaves
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `master` | no | `entity_id` of the master device|
| `slaves` | no | List of slaves `entity_id` |
### {% linkable_title Service `soundtouch_add_zone_slave` %}
Add slave(s) to an existing zone
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------ |
| `master` | no | `entity_id` of the master device |
| `slaves` | no | List of slaves `entity_id` to add|
### {% linkable_title Service `soundtouch_remove_zone_slave` %}
Remove slave(s) from an existing zone.
Removing the last slave will destroy the zone. You will need to
create a new zone in order to be able to add slave(s) again
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------- |
| `master` | no | `entity_id` of the master device |
| `slaves` | no | List of slaves `entity_id` to remove |

2
source/_components/media_player.squeezebox.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: logitech.png
logo: squeezebox.png
ha_category: Media Player
ha_release: pre 0.7
ha_iot_class: "Local Polling"

29
source/_components/nest.markdown
View File

@ -7,32 +7,18 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Hub
featured: true
---
The Nest component is the main component to integrate all [Nest](https://nest.com/) related platforms. Besides this component you will have to setup your thermostat and any connected sensors separately.
The Nest component is the main component to integrate all [Nest](https://nest.com/) related platforms. To connect Nest, you will have to [sign up for a developer account](https://developers.nest.com/products) and get a client_id and client_secret.
```yaml
# Example configuration.yaml entry
nest:
username: USERNAME
password: PASSWORD
climate:
platform: nest
```
```yaml
# Example configuration.yaml entry to show only devices at your vacation home
nest:
username: USERNAME
password: PASSWORD
structure: Vacation
climate:
platform: nest
client_id: ABCD
client_secret: ABCD
```
```yaml
@ -43,13 +29,10 @@ nest:
structure:
- Vacation
- Primary
climate:
platform: nest
```
Configuration variables:
- **username** (*Required*): Your Nest username.
- **password** (*Required*): Your Nest password.
- **client_id** (*Required*): Your Nest developer client id.
- **client_secret** (*Required*): Your Nest developer client secret.
- **structure** (*Optional*): The structure or structures you would like to include devices from. If not specified, this will include all structures in your Nest account.

102
source/_components/remote.harmony.markdown Executable file
View File

@ -0,0 +1,102 @@
---
layout: page
title: "Harmony Hub Remote"
description: "Instructions how to integrate Harmony Hub remotes into Home Assistant."
date: 2016-11-05 17:00
sidebar: true
comments: false
sharing: true
footer: true
logo: logitech.png
ha_category: Remote
ha_iot_class: "Local Polling"
ha_release: "0.34"
---
The `harmony` remote platform allows you to control the state of your [Harmony Hub Device](http://www.logitech.com/en-us/product/harmony-hub).
Supported units:
- Harmony Hub
- Harmony Companion
- Harmony Pro
- Harmony Elite
To use your Harmony remote in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
remote:
- platform: harmony
name: Bedroom
host: 10.168.1.13
```
Configuration variables:
- **name** (*Required*): The hub's name to display in the front end.
- **host** (*Required*): The Harmony device's IP address.
- **port** (*Optional*): The Harmony device's port. 5222 is default.
- **activity** (*Optional*): Activity to use when turnon service is called without any data.
- **scan_interval** (*Optional*): Amount in seconds in between polling for device's current activity. Defaults to 30 seconds.
Configuration file:
Upon startup one file will be written to your Home Assistant configuration directory per device in the following format: `harmony_REMOTENAME.conf`. The file will contain:
- List of all programmed activity names and ID numbers
- List of all programmed device names and ID numbers
- List of all available commands per programmed device
Supported services:
- **Turn Off**: Turn off all devices that were switched on from the start of the current activity
- **Turn On**: Start an activity, will start the default activity from configuration.yaml if no activity is specified. The specified activity can either be the activity name or the activity ID from the configuration file written to your HASS config directory. The service will respond faster if the activity ID is passed instead of the name
- **Send Command**: Send a command to one device, device ID and available commands are written to the configuration file at startup
- **Sync**: Synchronizes the Harmony device with the Harmony web service if any changes are made from the web portal or app
### {% linkable_title Examples %}
Template sensors can be utilized to display current activity in the frontend.
```yaml
sensor:
- platform: template
sensors:
family_room:
value_template: {% raw %}'{{ states.remote.family_room.attributes.current_activity }}'{% endraw %}
friendly_name: 'Family Room'
bedroom:
value_template: {% raw %}'{{ states.remote.bedroom.attributes.current_activity }}'{% endraw %}
friendly_name: 'bedroom'
```
The example below shows how to control an `input_boolean` switch using the Harmony remote's current activity. The switch will turn on when the remote's state changes and the Kodi activity is started and off when the remote's state changes and the current activity is PowerOff.
```yaml
automation:
- alias: "Watch TV started from harmony hub"
trigger:
platform: state
entity_id: remote.family_room
condition:
condition: template
value_template: {% raw %}'{{ trigger.to_state.attributes.current_activity == "Kodi" }}'{% endraw %}
action:
service: input_boolean.turn_on
entity_id: input_boolean.notify
- alias: "PowerOff started from harmony hub"
trigger:
platform: state
entity_id: remote.family_room
condition:
condition: template
value_template: {% raw %}'{{ trigger.to_state.attributes.current_activity == "PowerOff" }}'{% endraw %}
action:
service: input_boolean.turn_off
entity_id: input_boolean.notify
````

29
source/_components/remote.markdown Executable file
View File

@ -0,0 +1,29 @@
---
layout: page
title: "Remotes"
description: "Instructions how to setup your remotes with Home Assistant."
date: 2016-11-05 19:39
sidebar: true
comments: false
sharing: true
footer: true
ha_release: "0.34"
---
Keeps track which remotes are in your environment, their state and allows you to control them.
* Maintains a state per remote and a combined state `all_remotes`.
* Registers services `remote/turn_on`, `remote/turn_off`,`remote/sync`, and `remote/send_command` to control remotes.
### {% linkable_title Use the services %}
Go the the **Developer Tools**, then to **Call Service** in the frontend, and choose `remote/turn_on` or `remote/turn_off` from the list of available services (**Available services:** on the left). Enter something like the sample below into the **Service Data** field and hit **Call Service**.
```json
{"entity_id":"remote.family_room"}
```
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | Only act on specific remote. Else targets all.

12
source/_components/sensor.darksky.markdown
View File

@ -85,6 +85,18 @@ Configuration variables:
- **precip_intensity_max**: Today's expected maximum intensity of precipitation.
- **units** (*Optional*): Specify the unit system. Default to `si` or `us` based on the temperature preference in Home Assistant. Other options are `auto`, `us`, `si`, `ca`, and `uk2`.
`auto` will let forecast.io decide the unit system based on location.
- **update_inverval** (*Optional*): Minimum time interval between updates. Default is 2 minutes. Supported formats:
- `update_interval: 'HH:MM:SS'`
- `update_interval: 'HH:MM'`
- Time period dictionary, e.g.:
<pre>update_interval:
# At least one of these must be specified:
days: 0
hours: 0
minutes: 3
seconds: 30
milliseconds: 0
</pre>
<p class='note warning'>
Note: While the platform is called "darksky" the sensors will show up in Home Assistant as "dark_sky" (eg: sensor.dark_sky_summary).

69
source/_components/sensor.dsmr.markdown Normal file
View File

@ -0,0 +1,69 @@
---
layout: page
title: "DSMR/Slimme meter"
description: "Instructions how to integrate DSMR Smartmeter within Home Assistant."
date: 2016-11-12 12:00
sidebar: true
comments: false
sharing: true
footer: true
logo: netbeheernederland.jpg
ha_category: Energy
ha_version: 0.34
ha_iot_class: "Local Push"
---
A sensor platform for Dutch Smart Meters which comply to DSMR (Dutch Smart Meter Requirements), also known as 'Slimme meter' or 'P1 poort'.
Currently support DSMR V2.2 and V4 through the [dsmr_parser](https://github.com/ndokter/dsmr_parser) module by Nigel Dokter.
For official information about DSMR refer to: [DSMR Document](http://www.netbeheernederland.nl/themas/hotspot/hotspot-documenten/?dossierid=11010056&title=Slimme%20meter&onderdeel=Documenten)
For unofficial hardware connection examples refer to: [Domoticx](http://domoticx.com/p1-poort-slimme-meter-hardware/)
<p class='img'>
<img src='/images/screenshots/dsmr.png' />
</p>
This component is known to work for:
- Iskra ME382 / MT382 (DSMR 2.2)
- Landis+Gyr E350 (DMSR 4)
- Landis+Gyr ZCF110 / ZM F110 (DSMR 4.2)
- Kaifa E0026
And USB serial converters:
- Cheap (Banggood/ebay) Generic PL2303
- https://sites.google.com/site/nta8130p1smartmeter/webshop
```yaml
# Example configuration.yaml entry
sensor:
- platform: dsmr
```
Configuration variables:
- **port** string (*Optional*): Serial port to which Smartmeter is connected (default: /dev/ttyUSB0).
- **dsmr_version_** string (*Optional*): Version of DSMR used by meter, choices: 2.2, 4 (default: 2.2).
A full configuration example can be found below:
```yaml
# Example configuration.yaml entry
sensor:
- platform: dsmr
port: /dev/ttyUSB1
dsmr_version: 4
group:
meter_readings:
name: Meter readings
entities:
- sensor.power_consumption_low
- sensor.power_consumption_normal
- sensor.power_production_low
- sensor.power_production_normal
- sensor.gas_consumption
```

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

@ -36,6 +36,8 @@ sensor:
- type: cost
period: day
currency: $
- type: amount
period: day
```
Configuration variables:
@ -45,6 +47,10 @@ Configuration variables:
negative number of minutes your timezone is ahead/behind UTC time.
- **monitored_variables** array (*Required*): Variables to monitor.
- **type** (*Required*): Name of the variable.
- **instant_readings**: Instant energy consumption.
- **budget**: Monthly budget.
- **cost**: The cost for energy consumption (with the tariff that has been set in Efergy) over a given period.
- **amount**: The amount of energy consumed over a given period.
- **period** (*Optional*): Some variables take a period argument. Valid options are "day", "week", "month", and "year".
- **currency** (*Optional*): This is used to display the cost/period as the unit when monitoring the cost. It should correspond to the actual currency used in your dashboard.

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

@ -40,6 +40,6 @@ sensor:
Configuration variables:
- **entity_ids** (*Required*): At least two entities to monitor
- **type** (*Optional*): The type of sensor. Defaults to `max`.
- **type** (*Optional*): The type of sensor: `min`, `max` or `mean`. Defaults to `max`.
- **name** (*Optional*): Name of the sensor to use in the frontend.
- **round_digits** (*Optional*): Round mean value to specified number of digits. Defaults to 2.

16
source/_components/sensor.nest.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Sensor
ha_release: pre 0.7
---
@ -24,15 +24,10 @@ To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
platform: nest
monitored_conditions:
- 'temperature'
- 'target'
- 'humidity'
- 'operation_mode'
- 'last_connection'
- 'co_status' # Nest Protect only
- 'smoke_status' # Nest Protect only
- platform: nest
monitored_conditions:
- 'temperature'
- 'target'
```
Configuration variables:
@ -43,6 +38,7 @@ The following conditions can be monitored with a Nest Thermostat or Protect.
- 'battery_level'
The following conditions can be monitored with a Nest Thermostat only.
- 'temperature'
- 'target'
- 'humidity'

16
source/_components/sensor.nest_weather.markdown
View File

@ -7,7 +7,7 @@ sidebar: true
comments: false
sharing: true
footer: true
logo: nest_thermostat.png
logo: nest.png
ha_category: Weather
ha_iot_class: "Cloud Poll"
---
@ -26,18 +26,14 @@ sensor:
- platform: nest
monitored_conditions:
- 'weather_temperature'
- 'weather_humidity'
- 'weather_condition'
- 'wind_speed'
- 'wind_direction'
```
Configuration variables:
- **monitored_conditions** array (*Required*): States to monitor.
- 'weather_temperature'
- 'weather_humidity'
- 'weather_condition'
- 'wind_speed'
- 'wind_direction'
- 'weather_temperature'
- 'weather_humidity'
- 'weather_condition'
- 'wind_speed'
- 'wind_direction'

95
source/_components/sensor.nut.markdown Normal file
View File

@ -0,0 +1,95 @@
---
layout: page
title: NUT Sensor
description: "Instructions on how to set up NUT sensors within Home Assistant."
date: 2016-11-23
sidebar: true
comments: false
sharing: true
footer: true
logo: nut.png
ha_category: Sensor
ha_version: 0.34
---
The `nut` sensor platform allows you to monitor a UPS (battery backup) by using data from a [NUT](http://networkupstools.org/) (Network UPS Tools) server.
To use this sensor platform, you need to add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: nut
resources:
- ups.load
- ups.realpower.nominal
- input.voltage
- battery.runtime
```
Configuration variables:
- **name** (*Optional*): Name prefix for defined sensors. Defaults to 'NUT UPS'.
- **host** (*Optional*): The host name or address of the device that is running NUT. Defaults to localhost.
- **port** (*Optional*): The port number. Defaults to 3493.
- **alias** (*Optional*): Name of the ups on the NUT server. Will default to the first UPS name listed.
- **username** (*Optional*): Username to login to the NUT server. Default is none.
- **password** (*Optional*): Password to login to the NUT server. Default is none.
- **resources** array (*Required*): Contains all entries to display.
### {% linkable_title Example %}
Given the following example output from NUT (Your variables may differ):
```yaml
'ups.timer.reboot': '0',
'battery.voltage': '27.0',
'ups.firmware.aux': 'L3 -P ',
'ups.mfr': 'American Power Conversion',
'battery.runtime.low': '120',
'ups.delay.shutdown': '20',
'ups.load': '19',
'ups.realpower.nominal': '600',
'battery.charge.warning': '50',
'battery.charge.low': '10',
'ups.vendorid': '051d',
'ups.timer.shutdown': '-1',
'ups.test.result': 'No test initiated',
'ups.firmware': '868.L3 -P.D',
'battery.mfr.date': '2015/05/08',
'ups.serial': '3B1519X19994 ',
'ups.productid': '0002',
'battery.runtime': '2552',
'battery.date': '2001/09/25',
'battery.voltage.nominal': '24.0',
'battery.type': 'PbAc',
'ups.mfr.date': '2015/05/08',
'ups.status': 'OL',
'ups.model': 'Back-UPS RS1000G',
'ups.beeper.status': 'disabled',
'battery.charge': '100',
'input.sensitivity': 'medium',
'input.transfer.low': '88'
'input.transfer.high': '147',
'input.voltage': '121.0',
'input.voltage.nominal': '120',
'input.transfer.reason': 'input voltage out of range',
```
Use the values from the left hand column. Support is included for most values with 'ups', 'battery', and 'input' prefixes.
```yaml
sensor:
- platform: nut
name: UPS Name
host: 192.168.11.5
port: 3493
alias: ups_name
username: user
password: pass
resources:
- ups.load
- ups.realpower.nominal
- input.voltage
- battery.runtime
```

123
source/_components/sensor.sonarr.markdown Normal file
View File

@ -0,0 +1,123 @@
---
layout: page
title: "Sonarr Sensor"
description: "Instructions how to integrate Sonarr sensors with Home Assistant"
date: 2016-11-19 13:35
sidebar: true
comments: false
sharing: true
footer: true
logo: sonarr.png
ha_category: Sensor
ha_release: 0.34
---
This `sonarr` sensor platform pulls data from a given Sonarr instance.
To use your [Sonarr](https://sonarr.tv/) sensor in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: IP_ADDRESS
port: PORT
```
Configuration variables:
- **api_key** (*Required*): Your Sonarr API key, found in Settings > General in the Sonarr Web UI.
- **monitored_conditions** array (*Required*): Conditions to display on the frontend.
- **series**: The number of series in Sonarr.
- **upcoming**: The number of upcoming episodes.
- **wanted**: The number of episodes still 'wanted'.
- **queue**: The number of episodes in the queue.
- **commands**: The number of commands being run.
- **diskspace**: Available disk space.
- **host** (*Optional*): The host Sonarr is running on (Default: localhost).
- **port** (*Optional*): The port Sonarr is running on (Default: 8989).
- **days** (*Optional*): How many days to look ahead for the upcoming sensor, 1 means today only (Default: 1).
- **included_paths** (*Optional*): Array of filepaths to include when calculating diskspace. Leave blank to include all.
- **unit**: (*Optional*): The unit to display disk space in (Default: GB).
- **ssl**: boolean (*Optional*): Whether or not to use SSL for Sonarr.
## {% linkable_title Examples %}
In this section you find some real life examples of how to use this sensor.
### {% linkable_title Get Episodes airing in next 2 days %}
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: 192.168.1.8
monitored_conditions:
- upcoming
days: 2
```
### {% linkable_title Enable SSL %}
SSL may run on a different port than the default (8989). The SSL port can be bound to any port in Sonarr, so it should be set in the config here (unless it is changed to 8989). See the [Sonarr site](https://github.com/Sonarr/Sonarr/wiki/SSL) for details on SSL in Sonarr.
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: 192.168.1.8
port: 9898
monitored_conditions:
- upcoming
days: 2
ssl: true
```
### {% linkable_title Get disk space for all storage locations %}
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: 192.168.1.8
monitored_conditions:
- diskspace
```
### {% linkable_title Get disk space for listed storage locations %}
The storage locations Sonarr returns are in the system page and in some cases this can list duplicates if sub paths are mounted separately. By listing paths to include, you can choose what data is reported by the sensor.
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: 192.168.1.8
monitored_conditions:
- diskspace
included_paths:
- /tank/plex
```
### {% linkable_title Get disk space in different unit %}
The Sonarr API returns available space in bytes, but this sensor will default to reporting it in GB to make the number more manageable. This can be overridden if your storage needs require a different unit. All units from bytes (B) to yottabytes (YB) are supported.
*This calculation is done using base 2 math, and may differ from systems calculating using base 10 math.*
```yaml
# Example configuration.yml entry
sensor:
- platform: sonarr
api_key: YOUR_API_KEY
host: 192.168.1.8
monitored_conditions:
- diskspace
unit: TB
```

41
source/_components/sensor.waqi.markdown Normal file
View File

@ -0,0 +1,41 @@
---
layout: page
title: "World Air Quality Index"
description: "Instructions how to setup World Air Quality Index sensor in Home Assistant."
date: 2016-11-17 06:00
sidebar: true
comments: false
sharing: true
footer: true
logo: smtp.png
ha_category: Sensor
ha_release: 0.34
ha_iot_class: "Local Polling"
---
The `waqi` sensor platform will query [World Air Quality Index](http://aqicn.org) service to check AQI value for a specific set of locations. The resulting indexes will be added to the Home Assistant as sensor outputs.
To enable this sensor, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: waqi
locations:
- beijin
```
Configuration variables:
- **locations** (*Required*): a list of location names to look for air quality data. In case a specific location has multiple registered stations all of them will be added to Home Assistant
The value reported is an overall AQ index for the location. The values of the index can be interpreted as following:
AQI | Status | Description
------- | :----------------: | ----------
0 - 50 | **Good** | Air quality is considered satisfactory, and air pollution poses little or no risk
51 - 100 | **Moderate** | Air quality is acceptable; however, for some pollutants there may be a moderate health concern for a very small number of people who are unusually sensitive to air pollution
101 - 150 | **Unhealthy for Sensitive Groups** | Members of sensitive groups may experience health effects. The general public is not likely to be affected
151 - 200 | **Unhealthy** | Everyone may begin to experience health effects; members of sensitive groups may experience more serious health effects
201 - 300 | **Very unhealthy** | Health warnings of emergency conditions. The entire population is more likely to be affected
301+ | **Hazardous** | Health alert: everyone may experience more serious health effects

7
source/_components/sensor.zoneminder.markdown
View File

@ -13,7 +13,7 @@ ha_release: 0.31
---
The `zoneminder` sensor platform let you monitor the current state of your zoneminder install including the number of events and the current state of the cameras.
The `zoneminder` sensor platform let you monitor the current state of your ZoneMinder install including the number of events and the current state of the cameras.
<p class='note'>
You must have the [ZoneMinder component](/components/zoneminder/) configured to use those sensors.
@ -25,4 +25,9 @@ To set it up, add the following information to your `configuration.yaml` file:
# Example configuration.yaml entry
sensor:
- platform: zoneminder
include_archived: false
```
Configuration variables:
- **include_archived** (*Optional*): Whether to include archived ZoneMinder events in event counts. Default is `false`.

38
source/_components/switch.hook.markdown Normal file
View File

@ -0,0 +1,38 @@
---
layout: page
title: "Hook Switch"
description: "Instructions on how to integrate the Hook Smart Home Hub into Home Assistant."
sidebar: true
comments: false
sharing: true
footer: true
logo: hook.png
ha_category: Switch
ha_iot_class: "Assumed State"
ha_release: 0.34
---
The `hook` component allows you to control the [Hook Smart Home Hub](http://www.hooksmarthome.com/) from within Home Assistant.
Hook allows you to control cheap mains electrical outlets, like these ones at [Amazon](https://www.amazon.com/Etekcity-Wireless-Electrical-Household-Appliances/dp/B00DQELHBS).
In short, Hook is an RF to Wi-Fi bridge, controlling devices that recieve commands at 315MHz and 433MHz. Unfortunately, this does not allow Hook to determine if the command was successful, so the state is assumed.
Hook provides a simple [REST API](https://app.swaggerhub.com/api/rahilj/GetHook_RestAPI/v1). This Home Assistant component reads in devices that have been set up in the official app.
```yaml
# Example configuration.yaml entry
- platform: hook
username: <email address>
password: !secret hook
```
Extra debug logging is available, if you need it.
```yaml
# Example configuration.yaml entry
logger:
default: error
logs:
homeassistant.components.switch.hook: debug
```

5
source/_cookbook/track_battery_level.markdown
View File

@ -10,11 +10,12 @@ footer: true
ha_category: Automation Examples
---
iOS Devices
### {% linkable_title iOS Devices %}
If you have a device running iOS (iPhone, iPad, etc), The [iCloud](/components/device_tracker.icloud/) is gathering various details about your device including the battery level. To display it in the Frontend use a [template sensor](/components/sensor.template/).
```yaml
sensor:
- platform: template
sensors:
battery_iphone:
@ -29,7 +30,7 @@ If you have a device running iOS (iPhone, iPad, etc), The [iCloud](/components/d
The `else` part is used to have the sensor keep it's last state if the newest [iCloud](/components/device_tracker.icloud/) update doesn't have any battery state in it (which happens sometimes). Otherwise the sensor will be blank.
Android and iOS Devices
### {% linkable_title Android and iOS Devices %}
While running the [Owntracks](/components/device_tracker.owntracks/) device tracker you can retrieve the battery level with a MQTT sensor.

132
source/_ecosystem/nginx.markdown Normal file
View File

@ -0,0 +1,132 @@
---
layout: page
title: "NGINX"
description: "Documentation about setting up Home Assistant with NGINX."
release_date: 2016-12-02 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Using nginx as a proxy for Home Assistant allows you to serve Home Assistant securely over standard ports. This configuration file and instructions will walk you through setting up Home Assistant over a secure connection.
### {% linkable_title 1. Get a domain name forwarded to your IP. %}
Chances are, you have a dynamic IP Address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
### {% linkable_title 2 Install nginx on your server. %}
This will vary depending on your OS. Check out Google for this. After installing, ensure that nginx is not running.
### {% linkable_title 3. Obtain an SSL certificate. %}
There are two ways of obtaining an SSL certificate.
#### {% linkable_title Using Let's Encrypt %}
If you purchased your own domain, you can use https://letsencrypt.org/ to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command.
```
./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
```
Instead of example.com, use your domain. You will need to renew this certificate every 90 days.
#### {% linkable_title Using openssl %}
If you do not own your own domain, you may generate a self-signed certificate. This will not work with IFTTT, but it will encrypt all of your Home Assistant traffic.
```
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 9999
sudo cp key.pem cert.pem /etc/nginx/ssl
sudo chmod 600 /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
sudo chown root:root /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
```
### {% linkable_title 4. Create dhparams file %}
As a fair warning, this file will take a while to generate.
```
cd /etc/nginx/ssl
sudo openssl dhparam -out dhparams.pem 2048
```
### {% linkable_title 5. Install configuration file in nginx. %}
Create a new file `/etc/nginx/sites-available/hass` and copy the configuration file at the bottom of the page into it.
### {% linkable_title 6. Enable the Home Assistant configuration. %}
```
cd /etc/nginx/sites-enabled
sudo unlink default
sudo ln ../sites-available/hass default
```
### {% linkable_title 7. Start NGINX. %}
Double check this configuration to ensure all settings are correct and start nginx.
### {% linkable_title 8. Port forwarding. %}
Forward ports 443 and 80 to your server on your router. Do not forward port 8123.
### {% linkable_title NGINX Config %}
```
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
# Update this line to be your domain
server_name example.com;
# These shouldn't need to be changed
listen 80 default_server;
listen [::]:80 default_server ipv6only=on;
return 301 https://$host$request_uri;
}
server {
# Update this line to be your domain
server_name example.com;
# Ensure these lines point to your SSL certificate and key
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# Use these lines instead if you created a self-signed certificate
# ssl_certificate /etc/nginx/ssl/cert.pem;
# ssl_certificate_key /etc/nginx/ssl/key.pem;
# Ensure this line points to your dhparams file
ssl_dhparam /etc/nginx/ssl/dhparams.pem;
# These shouldn't need to be changed
listen 443 default_server;
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
ssl on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
proxy_buffering off;
location / {
proxy_pass http://localhost:8123;
proxy_set_header Host $host;
proxy_redirect http:// https://;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
}
```

1
source/_includes/asides/developers_navigation.html
View File

@ -62,6 +62,7 @@
API
<ul>
<li>{% active_link https://dev-docs.home-assistant.io/en/dev/ Home Assistant API %}</li>
<li>{% active_link /developers/websocket_api/ Websocket API %}</li>
<li>{% active_link /developers/rest_api/ RESTful API %}</li>
<li>{% active_link /developers/python_api/ Python API %}</li>
<li>{% active_link /developers/server_sent_events/ Server-sent events %}</li>

3
source/_includes/asides/getting_started_navigation.html
View File

@ -60,7 +60,8 @@
<ul>
<li>{% active_link /getting-started/autostart-systemd/ Linux - systemd %}</li>
<li>{% active_link /getting-started/autostart-upstart/ Linux - Upstart %}</li>
<li>{% active_link /getting-started/autostart-macos/ OS X %}</li>
<li>{% active_link /getting-started/autostart-init.d/ Linux - init.d %}</li>
<li>{% active_link /getting-started/autostart-macos/ macOS %}</li>
<li>{% active_link /getting-started/autostart-synology/ Synology NAS %}</li>
</ul>
</li>

174
source/_posts/2016-12-03-remote-websockets-sonarr.markdown Normal file
View File

@ -0,0 +1,174 @@
---
layout: post
title: "0.34: New Remote component, Websockets, Sonarr, GPSLogger"
description: "Major improvements of HomeMatic, Tellstick, the HTTP component, and more."
date: 2016-12-03 08:04:05 +0000
date_formatted: "December 3, 2016"
author: Fabian Affolter et al.
author_twitter: fabaff
comments: true
categories: Release-Notes
og_image: /images/blog/2016-12-0.34/social.png
---
Here we go...0.34. Let's call it the "Santa Claus" release. Rodolfo was faster than expected and there are a lot of goodies on the sled. Of course, more work on async programming done by [@pvizeli] and [@balloob], a new components, new platforms, major improvements, and much more.
### {% linkable_title GPSLogger %}
The work of [@dainok] let you use your Android device, with the Geolocation feature enabled, to track itself using the GPS sensor or WiFi networks with [GPSLogger](https://play.google.com/store/apps/details?id=com.mendhak.gpslogger) app. GPSLogger can use multiple source: the passive one just get the latest Android known location, without activating GPS sensors or scanning for WiFi networks.
### {% linkable_title Remote component %}
The brand new [`remote`][remote] component made by [@iandday] will simplyfy the integration of all kind remote control units. The first platform for [Harmony][harmony] is included in this release.
### {% linkable_title HomeMatic %}
The [HomeMatic][homematic] component has received some updates worth mentioning:
* Additional services
* `reconnect`: Reconnect to your CCU/Homegear without restarting Home Assistant.
* `set_dev_value`: Manually control a device, even if it's not supported by Home Assistant yet.
* Support for multiple HomeMatic hosts
* Support for HomeMatic Wired (most devices) and HomeMatic IP (a few devices)
* Various improvements and fixes, especially for HM-Sec-Key (KeyMatic)
The support for multiple hosts is a result of allowing mixed configurations with wireless, wired, and IP devices. This has the drawback of making the update a breaking change (along with the renamed `set_value` service). However, the benefits and possibilities gained will be worth it.
### {% linkable_title Websocket API %}
This release includes a new [websockets][websockets] based API by [@balloob] to power the next generation of Home Assistant frontends. The current frontend has been partly migrated to use it and will be further migrated in the future.
## {% linkable_title All changes %}
- Sensor: [Broadlink][boradlink] RM2 and A1 E-air support ([@skyval])
- New services and improved device support for [HomeMatic][homematic] ([@pvizeli], [@danielperna84])
- Device tracker: New support for [GPSLogger][gpslogger] ([@dainok])
- Sensor: Support for [Sonarr][sonarr] ([@hborawski])
- Sensor: [World Air Quality Index][waqi] sensor ([@valentinalexeev], [@fabaff])
- Sensor: Support for [Dutch Smart Meter Requirements][dsmr] ([@aequitas])
- Switch: [Hook][hook] support by hooksmarthome.com ([@dasos])
- Camera: Integration for [Nest cameras][nest-cam] ([@technicalpickles])
- Light: Support for light effects ([@Diaoul])
- Sensor: New [Threshold][threshold] sensor ([@fabaff])
- Media player: New [DuneHD][dunehd] integration([@valentinalexeev])
- Media player: Controlling support for [Philips TVs][philips] ([@aequitas])
- Camera: Support for [Amcrest][amcrest] cameras ([@tchellomello])
- Sensor: Monitoring support for [Network UPS Tools (NUT)][nut] ([@mezz64])
- Mediap player - Denon: Source selection support ([@Gilles95])
- Sensor - MinMax: Precision now configurable ([@exxamalte])
- Tellstick: Massive [improvement][tellstick] ([@magicus])
- Light - Osram: New requirement ([@tfriedel])
- Sensor - Systemmonitor: Support for removable network adapters ([@mnoorenberghe])
- LiteJet: New trigger option ([@joncar])
- Media player - Bose: Add Bose SoundTouch device support ([@CharlesBlonde])
- HTTP: Re-organisation and [websockets] support ([@balloob])
- HTTP: Advanced [IP filtering][filtering] ([@vkorn])
- Sensor - KNX: Fix unit of mesaurement ([@cyberjunky])
- Climate: New precision properties ([@sdague])
- Sensor - TEMPer: Reset [devices][temper] on address change ([@vemek])
- Core: Color names now follows w3.org recommandations ([@srcLurker])
- Updater: Robustness improvements ([@balloob]])
- Media player - MPD: Reconnect to daemon ([@janLo])
- Device tracker: Fall-back for MAC address lookup ([@aequitas])
- Sensor - Efergy: Get the amount of [energy consumed][efergy] ([@gonzalezcalleja])
- Zeroconf: Fix for IPv6 support ([@rcloran])
- Minor and not so minor features and bug fixes by [@turbokongen], [@sdague], [@pvizeli], [@fabaff], [@chapple], [@mweinelt], [@Khabi], [@balloob], [@mnestor], [@kellerza], [@Morrisai],
[@michaelarnauts], [@tchellomello], [@lwis], [@bjarniivarsson], [@danielperna84], [@LinuxChristian], [@MartinHjelmare], [@dethpickle], [@jnewland], [@lichtteil], [@brandonweeks], [@partofthething], [@mnoorenberghe], [@bah2830], and [@albertoarias].
## {% linkable_title Breaking changes %}
- The [HomeMatic][homematic] component now uses a different syntax for hosts and the `set_value` service has been renamed.
- All [RFXtrx][rfxtrx] sensors will get a new entity ID.
- If you are using NGINX, you will have to [adapt your configuration][nginx].
- [Nest][nest] contains changes which will require your attention.
### {% linkable_title If you need help... %}
...don't hesitate to use our [Forum](https://community.home-assistant.io/) or join us for a little [chat](https://gitter.im/home-assistant/home-assistant). The release notes have comments enabled but it's preferred if you use the former communication channels. Thanks.
### {% linkable_title Reporting Issues %}
Experiencing issues introduced by this release? Please report them in our [issue tracker](https://github.com/home-assistant/home-assistant/issues). Make sure to fill in all fields of the issue template.
[@aequitas]: https://github.com/aequitas
[@albertoarias]: https://github.com/albertoarias
[@bah2830]: https://github.com/bah2830
[@balloob]: https://github.com/balloob
[@bjarniivarsson]: https://github.com/bjarniivarsson
[@brandonweeks]: https://github.com/brandonweeks
[@cawilliamson]: https://github.com/cawilliamson
[@chapple]: https://github.com/chapple
[@CharlesBlonde]: https://github.com/CharlesBlonde
[@cyberjunky]: https://github.com/cyberjunky
[@dainok]: https://github.com/dainok
[@danielperna84]: https://github.com/danielperna84
[@dasos]: https://github.com/dasos
[@dethpickle]: https://github.com/dethpickle
[@Diaoul]: https://github.com/Diaoul
[@exxamalte]: https://github.com/exxamalte
[@fabaff]: https://github.com/fabaff
[@Gilles95]: https://github.com/Gilles95
[@gonzalezcalleja]: https://github.com/gonzalezcalleja
[@hartmms]: https://github.com/hartmms
[@hborawski]: https://github.com/hborawski
[@iandday]: https://github.com/iandday
[@janLo]: https://github.com/janLo
[@jnewland]: https://github.com/jnewland
[@joncar]: https://github.com/joncar
[@kellerza]: https://github.com/kellerza
[@Khabi]: https://github.com/Khabi
[@lichtteil]: https://github.com/lichtteil
[@LinuxChristian]: https://github.com/LinuxChristian
[@lwis]: https://github.com/lwis
[@magicus]: https://github.com/magicus
[@MartinHjelmare]: https://github.com/MartinHjelmare
[@mezz64]: https://github.com/mezz64
[@mezz64]: https://github.com/mezz64
[@michaelarnauts]: https://github.com/michaelarnauts
[@mnestor]: https://github.com/mnestor
[@mnoorenberghe]: https://github.com/mnoorenberghe
[@molobrakos]: https://github.com/molobrakos
[@Morrisai]: https://github.com/Morrisai
[@mtreinish]: https://github.com/mtreinish
[@mweinelt]: https://github.com/mweinelt
[@nsideras]: https://github.com/nsideras
[@partofthething]: https://github.com/partofthething
[@pavoni]: https://github.com/pavoni
[@persandstrom]: https://github.com/persandstrom
[@postlund]: https://github.com/postlund
[@pvizeli]: https://github.com/pvizeli
[@rcloran]: https://github.com/rcloran
[@sdague]: https://github.com/sdague
[@skyval]: https://github.com/skyval
[@srcLurker]: https://github.com/srcLurker
[@tchellomello]: https://github.com/tchellomello
[@technicalpickles]: https://github.com/technicalpickles
[@tfriedel]: https://github.com/tfriedel
[@turbokongen]: https://github.com/turbokongen
[@valentinalexeev]: https://github.com/valentinalexeev
[@vemek]: https://github.com/vemek
[@vkorn]: https://github.com/vkorn
[amcrest]: https://home-assistant.io/components/camera.amcrest/
[boradlink]: https://home-assistant.io/components/sensor.broadlink/
[dsmr]: https://home-assistant.io/components/sensor.dsmr/
[dunehd]: https://home-assistant.io/components/dunehd/
[efergy]: https://home-assistant.io/components/sensor.efergy/
[filtering]: https://home-assistant.io/components/http/
[harmony]: https://home-assistant.io/components/remote.harmony/
[homematic]: https://home-assistant.io/components/homematic/
[hook]: https://home-assistant.io/components/switch.hook/
[nest-cam]: https://home-assistant.io/components/camera.nest/
[nest]: https://home-assistant.io/components/nest/
[nginx]: https://home-assistant.io/ecosystem/nginx/
[nut]: https://home-assistant.io/components/sensor.nut/
[philips]: https://home-assistant.io/components/media_palyer.dunehd/
[remote]: https://home-assistant.io/components/remote/
[rfxtrx]: https://home-assistant.io/components/rfxtrx/
[tellstick]: https://home-assistant.io/components/tellstick/
[temper]: https://home-assistant.io/components/sensor.temper/
[threshold]: https://home-assistant.io/components/binary_sensor.threshold/
[websockets]: https://home-assistant.io/developers/websockets_api/
[wqai]: https://home-assistant.io/components/sensor.waqi/

15
source/developers/credits.markdown
View File

@ -51,6 +51,7 @@ This page contains a list of people who have contributed in one way or another t
- [Bruno Adele](https://github.com/badele)
- [Cameron Bulock](https://github.com/cbulock)
- [Carlo Costanzo](https://github.com/CCOSTAN)
- [cawilliamson](https://github.com/cawilliamson)
- [Charles Spirakis](https://github.com/srcLurker)
- [Chris Mulder](https://github.com/chrisvis)
- [Christian Braedstrup](https://github.com/LinuxChristian)
@ -58,6 +59,7 @@ This page contains a list of people who have contributed in one way or another t
- [chrom3](https://github.com/chrom3)
- [Corban Mailloux](https://github.com/corbanmailloux)
- [coteyr](https://github.com/coteyr/)
- [dainok](https://github.com/dainok)
- [Dale Higgs](https://github.com/dale3h)
- [Dan Cinnamon](https://github.com/Cinntax)
- [Dan Ford](https://github.com/dpford)
@ -70,6 +72,7 @@ This page contains a list of people who have contributed in one way or another t
- [Dan Smith](https://github.com/kk7ds)
- [Dan Sullivan](https://github.com/dansullivan86/)
- [Daren Lord](https://github.com/Xorso)
- [dasos](https://github.com/dasos)
- [Dave Banks](https://github.com/djbanks)
- [David-Leon Pohl](https://github.com/DavidLP)
- [David Straub](https://github.com/DavidMStraub)
@ -95,6 +98,7 @@ This page contains a list of people who have contributed in one way or another t
- [GadgetReactor](https://github.com/GadgetReactor)
- [Geoff Norton](https://github.com/kangaroo)
- [Giel Janssens](https://github.com/gieljnssns)
- [Gilles Margerie](https://github.com/Gilles95)
- [goir](https://github.com/goir)
- [Greg Dowling](https://github.com/pavoni)
- [gross1989](https://github.com/gross1989)
@ -104,6 +108,7 @@ This page contains a list of people who have contributed in one way or another t
- [gwendalg](https://github.com/gwendalg)
- [happyleavesaoc](https://github.com/happyleavesaoc)
- [Harald Nagel](https://github.com/haraldnagel)
- [Harris Borawski](https://github.com/hborawski)
- [HBDK](https://github.com/HBDK)
- [hcooper](https://github.com/hcooper)
- [Heathbar](https://github.com/heathbar)
@ -113,8 +118,10 @@ This page contains a list of people who have contributed in one way or another t
- [Hugo Dupras](https://github.com/jabesq)
- [Hydreliox](https://github.com/HydrelioxGitHub)
- [Ian Copp](https://github.com/icopp)
- [iandday](https://github.com/iandday)
- [Igor Shults](https://github.com/ishults)
- [Issac Kelly](https://github.com/issackelly)
- [Jack Chapple](https://github.com/chapple)
- [Jacob Tomlinson](https://github.com/jacobtomlinson)
- [James Cole](https://github.com/jamespcole)
- [Jan Harkes](https://github.com/jaharkes)
@ -123,6 +130,7 @@ This page contains a list of people who have contributed in one way or another t
- [Jared Beckham](https://github.com/tbeckha)
- [Jaret Stezelberger](https://github.com/DesignFirst)
- [Jason Carter](https://github.com/JasonCarter80)
- [Javier González Calleja](https://github.com/gonzalezcalleja)
- [Jean-Philippe Bouillot](https://github.com/Jypy)
- [Jean Regisser](https://github.com/jeanregisser)
- [Jeffrey Lin](https://github.com/linjef/)
@ -133,6 +141,7 @@ This page contains a list of people who have contributed in one way or another t
- [jnimmo](https://github.com/jnimmo)
- [Joel Asher Friedman](https://github.com/joelash)
- [Joe McMonagle](https://github.com/joemcmonagle)
- [Johan Bloemberg](https://github.com/aequitas)
- [John Arild Berentsen](https://github.com/turbokongen)
- [John](https://github.com/mezz64)
- [John Lindley](https://github.com/jwl17330536)
@ -167,6 +176,7 @@ This page contains a list of people who have contributed in one way or another t
- [Magnus Knutas](https://github.com/MagnusKnutas)
- [Mal Curtis](https://github.com/snikch)
- [Malte Deiseroth](https://github.com/deisi)
- [Malte Franken](https://github.com/exxamalte)
- [Manoj](https://github.com/vmulpuru)
- [Marcelo Moreira de Mello](https://github.com/tchellomello)
- [Marc Pabst](https://github.com/mxtra)
@ -177,6 +187,7 @@ This page contains a list of people who have contributed in one way or another t
- [Matthew Bowen](https://github.com/mgbowen)
- [Matthew Treinish](https://github.com/mtreinish)
- [Matthias Grawinkel](https://github.com/meatz)
- [Matt Noorenberghe](https://github.com/mnoorenberghe)
- [Michaël Arnauts](https://github.com/michaelarnauts)
- [Michael Gilbert](https://github.com/Zyell)
- [Michael Kutý](https://github.com/michaelkuty)
@ -212,6 +223,7 @@ This page contains a list of people who have contributed in one way or another t
- [Rob Johnson](https://github.com/robjohnson189)
- [Rob Olimpiu](https://github.com/olimpiurob)
- [Roi Dayan](https://github.com/roidayan)
- [Ron Klinkien](https://github.com/cyberjunky)
- [Rowan Hine](https://github.com/GreenTurtwig)
- [rubund](https://github.com/rubund)
- [Russell Cloran](https://github.com/rcloran)
@ -234,6 +246,7 @@ This page contains a list of people who have contributed in one way or another t
- [Teemu Patja](https://github.com/tpatja)
- [Theb-1](https://github.com/Theb-1)
- [Theodor Lindquist](https://github.com/theolind)
- [Thomas Friedel](https://github.com/tfriedel)
- [tilutza](https://github.com/tilutza)
- [Tim Harton](https://github.com/timharton)
- [Tim](https://github.com/tinglis1)
@ -241,7 +254,9 @@ This page contains a list of people who have contributed in one way or another t
- [toddeye](https://github.com/toddeye)
- [Tom Duijf](https://github.com/tomduijf)
- [trollkarlen](https://github.com/trollkarlen)
- [Valentin Alexeev](https://github.com/valentinalexeev)
- [vitorespindola](https://github.com/vitorespindola)
- [Vlad Korniev](https://github.com/vkorn)
- [vladonemo](https://github.com/vladonemo)
- [Warren Konkel](https://github.com/wkonkel)
- [Willems Davy](https://github.com/joyrider3774)

353
source/developers/websocket_api.markdown Normal file
View File

@ -0,0 +1,353 @@
---
layout: page
title: "Websocket API"
description: "Home Assistant Websocket API documentation"
date: 2016-11-26 13:27
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant contains a websocket API. This API can be used to stream information from the Home Assistant server to any client that implements websockets. Implementations in different languages:
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
# Server states
1. Client connects
2. Authentication phase starts
a. If no further authentication necessary for the user: go to 3
b. Server sends `auth_required` message
c. Client sends `auth` message
d. If `auth` message correct: go to 3.
e. Server sends `auth_invalid`. Go to 6.
3. Send `auth_ok` message
4. Authentication phase ends.
5. Command phase starts.
a. Client can send commands.
b. Server can send results of previous commands.
6. Client or server disconnects session.
During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to it's origin.
# Message format
Each API message is a JSON serialized object containing a `type` key. After the authentication phase messages also must contain an `id`, an integer that contains the number of interactions.
Example of an auth message:
```json5
{
"type": "auth",
"api_password": "supersecret"
}
```
```json5
{
"id" 5,
"type":"event",
"event":{
"data":{},
"event_type":"test_event",
"time_fired":"2016-11-26T01:37:24.265429+00:00",
"origin":"LOCAL"
}
}
```
# Authentication phase
When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).
If no authentication is needed, the authentication phase will complete and the server will send an `auth_ok` message.
```json5
{
"type": "auth_ok"
}
```
If authentication is necessary, the server sends out `auth_required`.
```json5
{
"type": "auth_required"
}
```
This means that the next message from the client should be an auth message:
```json5
{
"type": "auth",
"api_password": "supersecret"
}
```
If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message:
```json5
{
"type": "auth_ok"
}
```
If the data is incorrect, the server will reply with `auth_invalid` message and disconnect the session.
```json5
{
"type": "auth_invalid",
"message": "Invalid password"
}
```
# Command phase
During this phase the client can give commands to the server. The server will respond to each command with a `result` message indicating when the command is done and if it was successful.
```json5
{
"id": 6.
"type": "result",
"success": true,
// Can contain extra result info
"result": null
}
```
## Subscribe to events
The command `subscribe_events` will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple `subscribe_events` commands.
```json5
{
"id": 18,
"type": "subscribe_events",
// Optional
"event_type": "state_changed"
}
```
The server will respond with a result message to indicate that the subscription is active.
```json5
{
"id": 18,
"type": "result",
"success": true,
"result": null
}
```
For each event that matches, the server will send a message of type `event`. The `id` in the message will point at the original `id` of the `listen_event` command.
```json5
{
"id": 18,
"type":"event",
"event":{
"data":{
"entity_id":"light.bed_light",
"new_state":{
"entity_id":"light.bed_light",
"last_changed":"2016-11-26T01:37:24.265390+00:00",
"state":"on",
"attributes":{
"rgb_color":[
254,
208,
0
],
"color_temp":380,
"supported_features":147,
"xy_color":[
0.5,
0.5
],
"brightness":180,
"white_value":200,
"friendly_name":"Bed Light"
},
"last_updated":"2016-11-26T01:37:24.265390+00:00"
},
"old_state":{
"entity_id":"light.bed_light",
"last_changed":"2016-11-26T01:37:10.466994+00:00",
"state":"off",
"attributes":{
"supported_features":147,
"friendly_name":"Bed Light"
},
"last_updated":"2016-11-26T01:37:10.466994+00:00"
}
},
"event_type":"state_changed",
"time_fired":"2016-11-26T01:37:24.265429+00:00",
"origin":"LOCAL"
}
}
```
## Unsubscribing from events
You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.
```json5
{
"id": 19,
"type": "unsubscribe_events",
"subscription": 18
}
```
The server will respond with a result message to indicate that unsubscribing was successful.
```json5
{
"id": 19,
"type": "result",
"success": true,
"result": null
}
```
## Calling a service
This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call.
```json5
{
"id": 24,
"type": "call_service",
"domain": "light",
"service": "turn_on",
// Optional
"service_data": {
"entity_id": "light.kitchen"
}
}
```
The server will indicate with a message indicating that the service is done executing.
```json5
{
"id": 24,
"type": "result",
"success": true,
"result": null
}
```
## Fetching states
This will get a dump of all the current states in Home Assistant.
```json5
{
"id": 19,
"type": "get_states"
}
```
The server will respond with a result message containing the states.
```json5
{
"id": 19,
"type": "result",
"success": true,
"result": [ … ]
}
```
## Fetching config
This will get a dump of the current config in Home Assistant.
```json5
{
"id": 19,
"type": "get_config"
}
```
The server will respond with a result message containing the config.
```json5
{
"id": 19,
"type": "result",
"success": true,
"result": { … }
}
```
## Fetching services
This will get a dump of the current services in Home Assistant.
```json5
{
"id": 19,
"type": "get_config"
}
```
The server will respond with a result message containing the services.
```json5
{
"id": 19,
"type": "result",
"success": true,
"result": { … }
}
```
## Fetching panels
This will get a dump of the current registered panels in Home Assistant.
```json5
{
"id": 19,
"type": "get_panels"
}
```
The server will respond with a result message containing the current registered panels.
```json5
{
"id": 19,
"type": "result",
"success": true,
"result": [ … ]
}
```
# Error handling
If an error occurs, the `success` key in the `result` message will be set to `false`. It will contain an `error` key containing an object with two keys: `code` and `message`.
| Code | Description |
| ----- | ------------ |
| 1 | A non-increasing identifier has been supplied.
| 2 | Received message is not in expected format (voluptuous validation error).
| 3 | Requested item cannot be found
```json5
{
"id": 12,
"type":"result",
"success": false,
"error": {
"code": 2,
"message": "Message incorrectly formatted: expected str for dictionary value @ data['event_type']. Got 100"
}
}
```

137
source/getting-started/autostart-init.d.markdown Normal file
View File

@ -0,0 +1,137 @@
---
layout: page
title: "Autostart using init.d"
description: "Documentation about setting up Home Assistant as a daemon running under init.d."
release_date: 2016-12-02 15:00:00 -0700
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant can run as a daemon within init.d with the script below.
### {% linkable_title 1. Copy script %}
Copy the script at the end of this page to `/etc/init.d/hass-daemon`.
After that, set the script to be executable:
```
sudo chmod +x /etc/init.d/hass-daemon
```
### {% linkable_title 2. Select a user. %}
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute hass.
### {% linkable_title 3. Register the daemon with Linux %}
```
sudo update-rc.d hass-daemon defaults
```
### {% linkable_title 4. Install this service %}
```
sudo service hass-daemon install
```
### {% linkable_title 5. Restart Machine %}
That's it. Restart your machine and Home Assistant should start automatically.
If HA does not start, check the log file output for errors at `/var/opt/homeassistant/home-assistant.log`
### {% linkable_title Extra: Running commands before hass executes %}
If any commands need to run before executing hass (like loading a virutal environment), put them in PRE_EXEC. This command must end with a semicolon.
### {% linkable_title Daemon script %}
```
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
PRE_EXEC=""
RUN_AS="USER"
PID_FILE="/var/run/hass.pid"
CONFIG_DIR="/var/opt/homeassistant"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
start() {
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo 'Starting service…' >&2
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
su -c "$CMD" $RUN_AS
echo 'Service started' >&2
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo 'Stopping service…' >&2
kill $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
echo 'Service stopped' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
echo "999999" > $PID_FILE
chown $RUN_AS $PID_FILE
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
}
uninstall() {
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
rm -fv "$PID_FILE"
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```

8
source/getting-started/autostart-systemd.markdown
View File

@ -35,13 +35,7 @@ WantedBy=multi-user.target
EOF'
```
There is also another [sample service file](https://raw.githubusercontent.com/home-assistant/home-assistant/master/script/home-assistant%40.service) available. To use this one, just download it.
```bash
$ sudo wget https://raw.githubusercontent.com/home-assistant/home-assistant/master/script/home-assistant%40.service -O /etc/systemd/system/home-assistant@[your user].service
```
If you've setup Home Assistant in virtualenv following the guide the following template should work for you.
If you've setup Home Assistant in `virtualenv` following the guide the following template should work for you.
```
[Unit]

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

@ -13,5 +13,5 @@ Once you get started with Home Assistant you want it to start automatically when
- [Linux - systemd](/getting-started/autostart-systemd/)
- [Linux - Upstart](/getting-started/autostart-upstart/)
- [OS X](/getting-started/autostart-macos/)
- [macOS](/getting-started/autostart-macos/)
- [Synology NAS](/getting-started/autostart-synology/)

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

@ -15,7 +15,7 @@ The location of the folder differs between operating systems:
| OS | Path |
| -- | ---- |
| OS X | `~/.homeassistant` |
| macOS | `~/.homeassistant` |
| Linux | `~/.homeassistant` |
| Windows | `%APPDATA%/.homeassistant` |

BIN
source/images/blog/2016-12-0.34/social.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 116 KiB

BIN
source/images/screenshots/dsmr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 106 KiB

BIN
source/images/supported_brands/amcrest.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 112 KiB

BIN
source/images/supported_brands/dunehd.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
source/images/supported_brands/hook.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
source/images/supported_brands/logitech.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.3 KiB

After

Width:  |  Height:  |  Size: 9.9 KiB

0
source/images/supported_brands/nest_thermostat.png → source/images/supported_brands/nest.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
source/images/supported_brands/netbeheernederland.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
source/images/supported_brands/nut.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
source/images/supported_brands/sonarr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
source/images/supported_brands/soundtouch.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
source/images/supported_brands/squeezebox.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB