jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge branch 'current' into patch-3

Browse source
This commit is contained in:
David De Sloovere 2017-12-30 14:03:28 +01:00 • committed by GitHub
commit 477adc8525
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1066 changed files with 4694 additions and 2450 deletions
Download patch file Download diff file Expand all files Collapse all files

4
source/_addons/google_assistant.markdown
View file

@ -10,6 +10,10 @@ footer: true
featured: true
---
<p class='note'>
If you are wanting to integrate your Google Home, or mobile phone running Google Assistant, with Home Assistant then you want the [Google Assistant component](https://home-assistant.io/components/google_assistant/).
</p>
[Google Assistant][GoogleAssistant] is an AI-powered voice assistant that runs on the Raspberry Pi and x86 platforms and interact over [api.ai] with Home-Assistant. You can also use [Google Actions][GoogleActions] to extend its functionality.
To enable access to the Google Assistant API, do the following:

70
source/_addons/homematic.markdown Normal file
View file

@ -0,0 +1,70 @@
---
layout: page
title: "HomeMatic"
description: "HomeMatic hardware support to turn you Home-Assistant into a CCU."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
---
Set up a [HomeMatic](https://github.com/eq-3/occu) hardware layer. At the moment we don't support hmIP but that is in progress. For learning and handling devices use our internal homematic panel and services (in progress) or use [Homematic-Manager](https://github.com/hobbyquaker/homematic-manager) > 2.0.
The logic layer will be Home-Assistant. There is no ReGa or other logic layer installed. You can't import exists configuration, you need new learn it into Home-Assistant.
Follow devices will be supported and tested:
- [HM-MOD-RPI-PCB](https://www.elv.ch/homematic-funkmodul-fuer-raspberry-pi-bausatz.html)
```json
{
"rf_enable": true,
"rf": [
{
"type": "CCU2",
"device": "/dev/ttyAMA0"
}
],
"wired_enable": false,
"wired": [
{
"serial": "xy",
"key": "abc",
"ip": "192.168.0.0"
}
]
}
```
Configuration variables:
- **rf_enable** (*Require*): Boolean. Enable or disable BidCoS-RF.
- **wired_enable** (*Require*): Boolean. Enable or disable BidCoS-Wired.
For RF devices
- **type** (*Require*): Device type for RFD service. Look into handbook of your device.
- **device** (*Require*): Device on host.
For RF devices
- **serial** (*Require*): Serial number of device.
- **key** (*Require*): Encrypted key.
- **ip** (*Require*): IP address of lan gateway.
## {% linkable_title Home Assistant configuration %}
Use the following configuration in Home Assistant to use it:
```yaml
homematic:
interfaces
BidCoS-RF:
host: core-homematic
port: 2001
```
## {% linkable_title Raspberry Pi3 %}
With HM-MOD-PRI-PCB you need add follow into your `config.txt` on boot partition:
```
dtoverlay=pi3-miniuart-bt
```

13
source/_addons/mosquitto.markdown
View file

@ -23,7 +23,9 @@ Set up [Mosquitto](https://mosquitto.org/) as MQTT broker.
"customize": {
"active": false,
"folder": "mosquitto"
}
},
"certfile": "fullchain.pem",
"keyfile": "privkey.pem"
}
```
@ -48,3 +50,12 @@ To use the Mosquitto as [broker](/docs/mqtt/broker/#run-your-own) add the follow
mqtt:
broker: core-mosquitto
```
If username and password are set up in add-on, your `configuration.yaml` file should contain that data.
```yaml
mqtt:
broker: core-mosquitto
username: YOUR_USERNAME
password: YOUR_PASSWORD
```

103
source/_addons/tellstick.markdown Normal file
View file

@ -0,0 +1,103 @@
---
layout: page
title: "TellStick"
description: "Telldus TellStick service enabler and tools."
date: 2017-12-04 21:31
sidebar: true
comments: false
sharing: true
footer: true
featured: false
---
Setting up the [Tellstick](http://telldus.com) service and tools contained in the [telldus-core](http://developer.telldus.com/) package and adding configuration to enable Tellstick and Tellstick Duo to work on your Hass.io.
To use this add-on, you first install it from the list of Built-in add-ons in Hass.io.
After installation you are presented with a default and example configuration, to alter this you must follow both the JSON format and also be aligned with the [valid parameters for Tellstick configuration file (tellstick.conf)](https://developer.telldus.com/wiki/TellStick_conf).
After any changes has been made to the configuration you need to restart the add-on for the changes to take effect.
Configuration variables:
- **id** (*Required*): This is a number and must be unique for each device.
- **name** (*Required*): A name for easy identification of the device.
- **protocol** (*Required*): This is the protocol the device uses. More on the different protocols later down.
- **model** (*Optional*): The parameter model is only used by some protocols where there exists different types of devices using the same protocol. This can be dimmers versus non-dimmers, codeswitch versus selflearning etc.
- **house** (*Optional*): Depending on protocol the values here can vary a lot to identify or group per house or type.
- **unit** (*Optional*): Unit identifier, in most cases a value between 1 to 16 and often used in combination with house.
- **fade** (*Optional*): Fade is either `true` or `false` and tells a dimmer if is should fade smooth or instant between values (only for IKEA protocol as it seems).
- **code** (*Optional*): A number series based on ones and zeroes often used for dip-switch based devices.
You will need to add internal communication details to `configuration.yaml` to enable the integration from Hass.io and the add-on.
```yaml
# Example configuration.yaml entry
tellstick:
host: core-tellstick
port: [50800, 50801]
```
To add [lights](https://home-assistant.io/components/light.tellstick/), [sensors](https://home-assistant.io/components/sensor.tellstick/) and [switches](https://home-assistant.io/components/switch.tellstick/) you follow the guidelines for each type individually that is [described for Home Assistant](https://home-assistant.io/components/tellstick/)
The add-on will also enable you to interact with tdtool via a Home Assistant services call, see example below for selflearning device.
## {% linkable_title Examples %}
Example for adding more devices in the add-on configuration (note the comma separator between devices):
```json
{
"devices": [
{
"id": 1,
"name": "Outdoor light",
"protocol": "everflourish",
"model": "selflearning-switch",
"house": "A",
"unit": "1"
},
{
"id": 2,
"name": "Hallway dimmer",
"protocol": "risingsun",
"model": "selflearning-dimmer",
"house": "A",
"unit": "2"
}
]
}
```
## Service calls
If you wish to teach a selflearning device in your TellStick configuration:
Go to Home Assistant [service call](http://hassio.local:8123/dev-service) in Developer tools and select.
- Service: `hassio.addon_stdin`
- Enter service Data:
`{"addon":"core_tellstick","input":{"function":"learn","device":"1"}}`
Replace `1` with the corresponding ID of the device in your TellStick configuration.
You can also use this to list devices or sensors and read the output in the add-on log:
`{"addon":"core_tellstick","input":{"function":"list-sensors"}}`
#### Supported service commands
- `"function":"list"`: List currently configured devices with name and device id and all discovered sensors.
- `"function":"list-sensors"`
- `"function":"list-devices"`: Alternative devices/sensors listing: Shows devices and/or sensors using key=value format (with tabs as separators, one device/sensor per line, no header lines.)
- `"function":"on","device":"x"`: Turns on device. ’x’ could either be an integer of the device-id, or the name of the device.
- `"function":"off","device":"x"`: Turns off device. ’x’ could either be an integer of the device-id, or the name of the device.
- `"function":"bell","device":"x"`: Sends bell command to devices supporting this. ’x’ could either be an integer of the device-id, or the name of the device.
- `"function":"learn","device":"x"`: Sends a special learn command to devices supporting this. This is normaly devices of ’selflearning’ type. ’x’ could either be an integer of the device-id, or the name of the device.

59
source/_components/ads.markdown Normal file
View file

@ -0,0 +1,59 @@
---
layout: page
title: "ADS"
description: Connect Home Assistant to TwinCAT devices via the ADS interface
date: 2017-12-05 12:00
sidebar: true
comments: false
sharing: true
footer: true
logo: beckhoff.png
ha_category: Hub
ha_release: "0.60"
ha_iot_class: "Local Push"
---
The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between [Beckhoff](https://www.beckhoff.com/) automation devices running [TwinCAT](http://www.beckhoff.hu/english.asp?twincat/default.htm) and other devices implementing this interface.
To enable ADS, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
ads:
device: '127.0.0.1.1.1'
port: 48898
```
{% configuration %}
device:
required: true
description: The AMS NetId that identifies the device.
type: string
port:
required: true
description: The port that runs the AMS server on the device, typically this would be 801 or 851.
type: int
ip_address:
required: false
description: The IP address of the ADS device, if not set the first 4 bytes of the device id will be used.
type: string
{% endconfiguration %}
## {% linkable_title Service %}
The ADS component will register the service `write_by_name` allowing you to write a value to a variable on your ADS device.
```json
{
"adsvar": ".myvariable",
"adstype": "int",
"value": 123
}
```
Service parameters:
- **adsvar**: Name of the variable on the ADS device. To access global variables on *TwinCAT2* use a prepending dot `.myvariable`, for TwinCAT3 use
`GBL.myvariable`.
- **adstype**: Specify the type of the variable. Use one of the following: `int`, `byte`, `uint`, `bool`
- **value**: The value that will be written in the variable.

54
source/_components/alarm_control_panel.arlo.markdown
View file

@ -14,7 +14,7 @@ ha_iot_class: "Cloud Polling"
---
The `arlo` control panel platform allows you to control your [Arlo](https://arlo.netgear.com/) base stations.
The `arlo` alarm control panel allows you to control your [Arlo](https://arlo.netgear.com/) base stations. You can use it to switch modes and trigger alarms from Home Assistant.
To get your [Arlo](https://arlo.netgear.com/) base stations working within Home Assistant, please follow the instructions for the general [Arlo component](/components/arlo).
@ -26,7 +26,53 @@ alarm_control_panel:
- platform: arlo
```
Configuration variables:
{% configuration %}
home_mode_name:
description: "Arlo base station does not have a built-in home mode. You can map one of your custom modes to home assistant's home mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match exactly as you set it up in the Arlo app."
required: false
type: string
away_mode_name:
description: "Arlo base station does not have a built-in away mode. You can map one of your custom modes to home assistant's away mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match eactly as you set it up in the Arlo app."
required: false
type: string
default: "`Armed` mode in Arlo"
{% endconfiguration %}
## {% linkable_title Examples %}
These examples are based on an Arlo base station named `my_arlo_base_station`. Replace this with the name of your base station's `entity_id`.
Arming the Arlo Base Station when leaving.
```yaml
- id: arm_arlo_when_leaving
alias: Arm Arlo cameras when leaving
trigger:
platform: state
entity_id: group.family
from: home
to: not_home
action:
service: alarm_control_panel.alarm_arm_away
entity_id: alarm_control_panel.my_arlo_base_station
```
Setting Arlo to a custom mode (mapped to `home_mode_name` in `configuration.yaml`) when arriving.
```yaml
- id: disarm_arlo_when_arriving
alias: Set Arlo cameras to Home mode when arriving
trigger:
platform: state
entity_id: group.family
from: not_home
to: home
action:
service: alarm_control_panel.alarm_arm_home
entity_id: alarm_control_panel.my_arlo_base_station
```
You can also completely disarm the Arlo base station by calling the `alarm_control_panel.alarm_disarm` service, and trigger the alarm by calling the `alarm_control_panel.alarm_trigger` service.
More examples and configuration options can be found on the [Manual Alarm Control page](/components/alarm_control_panel.manual/#examples).
- **home_mode_name**: (*Optional*): Arlo base station does not have a built-in home mode. You can map one of your custom modes to home assistant's home mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match exactly as you set it up in the Arlo app.
- **away_mode_name**: (*Optional*): Like the home mode, the Arlo base station does not have a built-in away mode, however, you can map a custom mode from the Arlo app to Home Assistant with this variable, just make sure the name matches exactly what you have set up in the Arlo app.

18
source/_components/alarm_control_panel.canary.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Canary Alarm Control Panel"
description: "Instructions on how to integrate your Canary devices into Home Assistant."
date: 2017-12-07 22:00
sidebar: true
comments: false
sharing: true
footer: true
logo: canary.png
ha_category: Alarm
ha_release: "0.60"
ha_iot_class: "Cloud Polling"
---
The `canary` alarm control panel platform allows you to integrate your [Canary](https://canary.is) alarm system in Home Assistant.
To add `canary` alarm control panel to your installation, follow instructions in [Canary component](/components/canary/).

2
source/_components/alarm_control_panel.egardia.markdown
View file

@ -16,7 +16,7 @@ The `egardia` platform enables the ability to control an [Egardia](http://egardi
You will need to know the IP of your alarm panel on your local network. Test if you can login to the panel by browsing to the IP address and log in using your Egardia/Woonveilig account.
To enable this, add the following lines to your `configuration.yaml`:
To enable this, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry

48
source/_components/alarm_control_panel.ialarm.markdown Normal file
View file

@ -0,0 +1,48 @@
---
layout: page
title: "Antifurto365 iAlarm Control Panel"
description: "Instructions how to integrate iAlarms alarms into Home Assistant."
date: 2017-11-30 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: antifurto365-ialarm.png
ha_category: Alarm
ha_release: "0.60"
---
The `ialarm` platform provides connectivity with the [Antifurto365](https://www.antifurtocasa365.it/) iAlarm alarm systems.
This platform supports the following services: `alarm_arm_away`, `alarm_arm_home` and `alarm_disarm`.
To enable this, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
alarm_control_panel:
- platform: ialarm
host: ALARM_SYSTEM_IP
username: YOUR_USERNAME
password: YOUR_PASSWORD
```
{% configuration %}
host:
description: The IP address of the iAlarm device on your home network.
required: true
type: string
username:
description: Username used to sign into the iAlarm web client (should be admin by default).
required: true
type: string
password:
description: Password used to sign into the iAlarm web client. If it has a leading zero you need to put the password within quotes.
required: true
type: string
name:
description: Name of device in Home Assistant.
required: false
type: string
{% endconfiguration %}

65
source/_components/alarm_control_panel.manual.markdown
View file

@ -25,13 +25,62 @@ Configuration variables:
- **name** (*Optional*): The name of the alarm. Default is "HA Alarm".
- **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend.
- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds.
- **code_template** (*Optional*): If defined, returns a code to enable or disable the alarm in the frontend; an empty string disables checking the code. Inside the template, the variables **from_state** and **to_state** identify the current and desired state. Only one of **code** and **code_template** can be specified.
- **delay_time** (*Optional*): The time in seconds of the pending time before triggering the alarm. Default is 0 seconds.
- **pending_time** (*Optional*): The time in seconds of the pending time before effecting a state change. Default is 60 seconds.
- **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds.
- **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state.
- **armed_home/armed_away/armed_night/triggered** (*Optional*): State specific settings
- **pending_time**: State specific pending time override.
- **armed_custom_bypass/armed_home/armed_away/armed_night/disarmed/triggered** (*Optional*): State specific settings
- **delay_time** (*Optional*): State specific setting for **delay_time** (all states except **triggered**)
- **pending_time** (*Optional*): State specific setting for **pending_time** (all states except **disarmed**)
- **trigger_time** (*Optional*): State specific setting for **trigger_time** (all states except **triggered**)
In the config example below, armed_home state will have no pending time and triggered state will have pending time of 20 second whereas armed_away state will have a default pending time of 30 seconds.
## {% linkable_title State machine %}
The state machine of the manual alarm component is complex but powerful. The
transitions are timed according to three values, **delay_time**, **pending_time**
and **trigger_time**. The values in turn can come from the default configuration
variable or from a state-specific override.
When the alarm is armed, its state first goes to **pending** for a number
of seconds equal to the destination state's **pending_time**, and then
transitions to one of the "armed" states. Note that **code_template**
never receives "pending" in the **to_state** variable; instead,
**to_state** contains the state which the user has requested. However,
**from_state** *can* contain "pending".
When the alarm is triggered, its state goes to **pending** for a number of
seconds equal to the previous state's **delay_time** plus the triggered
state's **pending_time**. Then the alarm transitions to the "triggered"
states. The code is never checked when triggering the alarm, so the
**to_state** variable of **code_template** cannot ever contain "triggered"
either; again, **from_state** *can* contain "triggered".
The alarm remains in the "triggered" state for a number of seconds equal to the
previous state's **trigger_time**. Then, depending on **disarm_after_trigger**,
it goes back to either the previous state or **disarmed**. If the previous
state's **trigger_time** is zero, the transition to "triggered" is entirely
blocked and the alarm remains in the armed state.
Each of the settings is useful in different scenarios. **pending_time** gives
you some time to leave the building (for "armed" states) or to disarm the alarm
(for the "triggered" state).
**delay_time** can also be used to allow some time to disarm the alarm, but with
more flexibility. For example, you could specify a delay time for the
"armed away" state, in order to avoid triggering the alarm while the
garage door opens, but not for the "armed home" state.
**trigger_time** is useful to disable the alarm when disarmed, but it can also
be used for example to sound the siren for a shorter time during the night.
In the config example below:
- the disarmed state never triggers the alarm;
- the armed_home state will leave no time to leave the building or disarm the alarm;
- while other states state will give 30 seconds to leave the building before triggering the alarm, and 20 seconds to disarm the alarm when coming back.
```yaml
# Example configuration.yaml entry
@ -40,11 +89,13 @@ alarm_control_panel:
name: Home Alarm
code: 1234
pending_time: 30
delay_time: 20
trigger_time: 4
disarmed:
trigger_time: 0
armed_home:
pending_time: 0
triggered:
pending_time: 20
trigger_time: 4
delay_time: 0
```
## {% linkable_title Examples %}

30
source/_components/alarm_control_panel.manual_mqtt.markdown
View file

@ -42,15 +42,21 @@ alarm_control_panel:
Configuration variables:
All configuration variables from the base manual alarm platform are available:
The following configuration variables from the base manual alarm platform are available:
- **name** (*Optional*): The name of the alarm. Default is "HA Alarm".
- **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend. This code is not required for MQTT interactions.
- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds.
- **code_template** (*Optional*): If defined, returns a code to enable or disable the alarm in the frontend; an empty string disables checking the code. Inside the template, the variables **from_state** and **to_state** identify the current and desired state. Only one of **code** and **code_template** can be specified.
- **delay_time** (*Optional*): The time in seconds of the pending time before triggering the alarm. Default is 0 seconds.
- **pending_time** (*Optional*): The time in seconds of the pending time before effecting a state change. Default is 60 seconds.
- **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds.
- **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state.
- **armed_home|armed_away|armed_night|triggered** (*Optional*): State specific settings
- **pending_time**: State specific pending time override.
- **armed_home/armed_away/armed_night/disarmed/triggered** (*Optional*): State specific settings
- **delay_time** (*Optional*): State specific setting for **delay_time** (all states except **triggered**)
- **pending_time** (*Optional*): State specific setting for **pending_time** (all states except **disarmed**)
- **trigger_time** (*Optional*): State specific setting for **trigger_time** (all states except **triggered**)
See the documentation for the [manual alarm platform](../alarm_control_panel.manual/) for a description.
Additionally, the following MQTT configuration variables are also available:
@ -62,7 +68,13 @@ Additionally, the following MQTT configuration variables are also available:
- **payload_arm_away** (*Optional*): The payload to set armed-away mode on this Alarm Panel. Default is "ARM_AWAY".
- **payload_arm_night** (*Optional*): The payload to set armed-night mode on this Alarm Panel. Default is "ARM_NIGHT".
In the config example below, armed_home state will have no pending time and triggered state will have a pending time of 20 seconds whereas armed_away state will have a default pending time of 30 seconds.
In the config example below:
- the disarmed state never triggers the alarm;
- the armed_home state will leave no time to leave the building or disarm the alarm;
- while other states state will give 30 seconds to leave the building before triggering the alarm, and 20 seconds to disarm the alarm when coming back.
```yaml
# Example configuration.yaml entry
@ -71,11 +83,13 @@ alarm_control_panel:
state_topic: home/alarm
command_topic: home/alarm/set
pending_time: 30
delay_time: 20
trigger_time: 4
disarmed:
trigger_time: 0
armed_home:
pending_time: 0
triggered:
pending_time: 20
trigger_time: 4
delay_time: 0
```
## {% linkable_title Examples %}

8
source/_components/alexa.markdown
View file

@ -10,9 +10,13 @@ footer: true
logo: amazon-echo.png
ha_category: Voice
featured: true
ha_release: 0.10
ha_release: '0.10'
---
<p class='note'>
Use [Home Assistant Cloud](/components/cloud/) to integrate with Alexa without any effort.
</p>
There are a few ways that you can use Amazon Echo and Home Assistant together.
- [Build custom commands to use](#i-want-to-build-custom-commands-to-use-with-echo)
@ -325,7 +329,7 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf
- All other settings are up to you
- Hit "Next"
- Test
- Having passed all validations to reach this screen, you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service.
- Having passed all validations to reach this screen, you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service.
- To invoke your flash briefing, open the Alexa app on your phone or go to the [Alexa Settings Site][alexa-settings-site], open the "Skills" configuration section, select "Your Skills", scroll to the bottom, tap on the Flash Briefing Skill you just created, enable it, then manage Flash Briefing and adjust ordering as necessary. Finally ask your Echo for your "news","flash briefing", or "briefing".
[amazon-dev-console]: https://developer.amazon.com

4
source/_components/axis.markdown
View file

@ -68,10 +68,6 @@ axis:
location: köket
```
<p class='note'>
If you are using Python 3.6, you might need to replace the 34m with 36m in the _gi.*.so filename in the gi folder.
</p>
<p class='note'>
Any specific levels for triggers needs to be configured on the device.
</p>

41
source/_components/binary_sensor.ads.markdown Normal file
View file

@ -0,0 +1,41 @@
---
layout: page
title: "ADS Binary Sensor"
description: "Instructions on how to set up ADS binary sensors within Home Assistant."
date: 2017-10-25 10:00
sidebar: true
comments: false
sharing: true
footer: true
logo: beckhoff.png
ha_category: Binary Sensor
ha_release: "0.60"
ha_iot_class: "Local Push"
---
The `ads` binary sensor platform can be used to monitor a boolean value on your ADS device.
To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: ads
adsvar: .boolean1
```
{% configuration %}
adsvar:
required: true
description: The name of the variable which you want to access on the ADS device.
type: string
name:
required: false
description: An identifier for the light in the frontend.
type: string
device_class:
required: false
description: The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
type: string
{% endconfiguration %}

28
source/_components/binary_sensor.hive.markdown Normal file
View file

@ -0,0 +1,28 @@
---
layout: page
title: "Hive Sensor"
description: "Instructions on how to integrate Hive Sensors with Home Assistant."
date: 2017-09-24 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: hive.png
ha_category: Binary Sensor
ha_release: 0.59
ha_iot_class: "Cloud Polling"
---
The 'hive' binary sensor component integrates your Hive sensors into Home Assistant.
The Hive sensor component supports the following Hive products:
- **Hive Window or Door Sensor**
- **Hive Motion Sensor**
<p class='note'>
Full configuration details can be found on the main [Hive component](/components/hive/) page.
</p>

2
source/_components/binary_sensor.iss.markdown
View file

@ -28,7 +28,7 @@ binary_sensor:
{% configuration %}
show_on_map:
description: Option to show the position of the ISS on the map.
required: optionsl
required: optional
default: false
type: string
{% endconfiguration %}

3
source/_components/binary_sensor.markdown
View file

@ -14,6 +14,7 @@ Binary sensors gather information about the state of devices which have a "digit
The way these sensors are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for binary sensors:
- **None**: Generic on/off. This is the default and doesn't need to be set.
- **battery**: `On` means low, `Off` means normal
- **cold**: `On` means cold
- **connectivity**: `On` means connection present, `Off` means no connection
- **gas**: `On` means gas detected
@ -26,6 +27,8 @@ The way these sensors are displayed in the frontend can be modified in the [cust
- **opening**: `On` means open, `Off` means closed
- **plug**: `On` means device is plugged in, `Off` means device is unplugged
- **power**: Power, over-current, etc.
- **presence**: `On` means Home, `Off` means Away
- **problem**: `On` means a problem was detected, `Off` means the status is OK
- **safety**: `On` means unsafe, `Off` means safe
- **smoke**: `On` means smoke detected
- **sound**: `On` means sound detected, `Off` means no sound

64
source/_components/binary_sensor.rest.markdown
View file

@ -47,25 +47,61 @@ binary_sensor:
method: POST
```
Configuration variables:
- **resource** (*Required*): The resource or endpoint that contains the value.
- **method** (*Optional*): The method of the request. Default is GET.
- **name** (*Optional*): Name of the REST binary sensor.
- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value.
- **payload** (*Optional*): The payload to send with a POST request. Usually formed as a dictionary.
- **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to True.
- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`.
- **username** (*Optional*): The username for accessing the REST endpoint.
- **password** (*Optional*): The password for accessing the REST endpoint.
- **headers** (*Optional*): The headers for the requests.
{% configuration %}
resource:
description: The resource or endpoint that contains the value.
required: true
type: string
default: string
method:
description: The method of the request.
required: false
type: string
default: GET
name:
description: Name of the REST binary sensor.
required: false
type: string
default: REST Binary Sensor
device_class:
description: "The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend."
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
payload:
description: The payload to send with a POST request. Usually formed as a dictionary.
required: false
type: string
verify_ssl:
description: Verify the certification of the endpoint.
required: false
type: boolean
default: True
authentication:
description: Type of the HTTP authentication. `basic` or `digest`.
required: false
type: string
username:
description: The username for accessing the REST endpoint.
required: false
type: string
password:
description: The password for accessing the REST endpoint.
required: false
type: string
headers:
description: The headers for the requests.
required: false
type: list, string
{% endconfiguration %}
<p class='note warning'>
Make sure that the URL exactly matches your endpoint or resource.
</p>
## {% linkable_title Examples %}
In this section you find some real life examples of how to use this sensor.

2
source/_components/binary_sensor.template.markdown
View file

@ -158,7 +158,7 @@ binary_sensor:
This example creates a washing machine "load running" sensor by monitoring an
energy meter connected to the washer. During the washer's operation, the energy
meter will fluctuate wildly, hitting zero frequently even before the load is
finished. By utilizing `off_delay`, we can have this sensor only turn off if
finished. By utilizing `delay_off`, we can have this sensor only turn off if
there has been no washer activity for 5 minutes.
{% raw %}

2
source/_components/binary_sensor.workday.markdown
View file

@ -22,10 +22,12 @@ To enable the `workday` sensor in your installation, add the following to your `
binary_sensor:
- platform: workday
country: DE
workdays: [ mon, wed, fri ]
```
Configuration variables:
- **name** (*Optional*): A name for this sensor. Defaults to *Workday Sensor*
- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.8.1) notation.
- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.8.1) notation. Defaults to None.
- **workdays** (*Optional*): List of workdays. Defaults to `mon`, `tue`, `wed`, `thu`, `fri`.

99
source/_components/calendar.caldav.markdown Normal file
View file

@ -0,0 +1,99 @@
---
layout: page
title: "CalDav"
description: "Instructions on how to integrate a WebDav calendar into Home Assistant."
date: 2017-11-27 23:14
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Calendar
ha_iot_class: "Cloud Polling"
ha_release: "0.60"
---
The `caldav` platform allows you to connect to your WebDav calendar and generate binary sensors. A different sensor will be created for each individual calendar, or you can specify custom calendars which match a criteria you define (more on that below). These sensors will be `on` if you have an on going event in that calendar or `off` if the event is later in time, or if there is no event at all. The WebDav calendar get updated roughly every 10 minutes.
### {% linkable_title Prerequisites %}
You need to have a CalDav server and eventually credentials for it. This component was tested against [Baikal](http://sabre.io/baikal/) but any component complying with the RFC4791 should work.
You might need some additional system packages to compile the Python caldav library. On a Debian based system, install them by:
```bash
$ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
```
### {% linkable_title Basic Setup %}
To integrate a WebDav calendar in Home Assistant, add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
calendar:
- platform: caldav
url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default
```
{% configuration %}
url:
required: true
description: The full URL to your calendars.
type: string
username:
required: false
description: Username for authentication.
type: string
password:
required: false
description: Password for authentication.
type: string
calendars:
required: false
description: List of the calendars to filter. Empty or absent means no filtering.
type: list
custom_calendars:
required: false
description: Details on any custom binary sensor calendars you want to create.
type: list
keys:
name:
required: true
description: The name of your custom calendar.
type: string
calendar:
required: true
description: The source calendar to search on.
type: string
search:
required: true
pending_charges: Regular expression for filtering the events
type: string
{% endconfiguration %}
### {% linkable_title Sensor attributes %}
- **offset_reached**: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting !!-10 would trigger this attribute to be on 10 minutes before the event starts.
- **all_day**: `True/False` if this is an all day event. Will be `False` if there is no event found.
- **message**: The event title with the `search` values extracted. So in the above example for `offset_reached` the message would be set to Very important meeting
- **description**: The event description.
- **location**: The event Location.
- **start_time**: Start time of event.
- **end_time**: End time of event.
### {% linkable_title Sensor attributes %}
```yaml
# Example configuration.yaml entry
calendar:
- platform: caldav
url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default
username: john.doe@test.com
password: !secret caldav
custom_calendars:
- name: 'HomeOffice'
calendar: 'Agenda'
search: 'HomeOffice'
```

18
source/_components/camera.canary.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Canary Camera"
description: "Instructions on how to integrate your Canary devices into Home Assistant."
date: 2017-12-07 22:00
sidebar: true
comments: false
sharing: true
footer: true
logo: canary.png
ha_category: Camera
ha_release: "0.60"
ha_iot_class: "Cloud Polling"
---
The `canary` camera platform allows you to view the latest camera image (triggered by motion) by your [Canary](https://canary.is) device in Home Assistant.
To add `canary` camera to your installation, follow instructions in [Canary component](/components/canary/).

2
source/_components/camera.generic.markdown
View file

@ -16,7 +16,7 @@ ha_iot_class: "depends"
The `generic` camera platform allows you to integrate any IP camera or other URL into Home Assistant. Templates can be used to generate the URLs on the fly.
Home Assistant will serve the images via its server, making it possible to view your IP camera's while outside of your network. The endpoint is `/api/camera_proxy/camera.[name]`.
Home Assistant will serve the images via its server, making it possible to view your IP cameras while outside of your network. The endpoint is `/api/camera_proxy/camera.[name]`.
To enable this camera in your installation, add the following to your `configuration.yaml` file:

10
source/_components/camera.markdown
View file

@ -45,6 +45,16 @@ Take a snapshot from a camera.
The path part of `filename` must be an entry in the `whitelist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
For example, the following action in an automation would take a snapshot from "yourcamera" and save it to /tmp with a timestamped filename.
```yaml
action:
service: camera.snapshot
data:
entity_id: camera.yourcamera
filename: '/tmp/yourcamera_{{ now().strftime("%Y%m%d-%H%M%S") }}.jpg'
```
### {% linkable_title Test if it works %}
A simple way to test if you have set up your `camera` platform correctly, is to use <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> **Services** from the **Developer Tools**. Choose your service from the dropdown menu **Service**, enter something like the sample below into the **Service Data** field, and hit **CALL SERVICE**.

4
source/_components/camera.onvif.markdown
View file

@ -13,9 +13,9 @@ ha_release: 0.47
---
The `ONVIF` platform allows you to use an ONVIF camera in Home Assistant. This requires FFmpeg component to be already configured.
The `onvif` camera platform allows you to use an ONVIF camera in Home Assistant. This requires the [`ffmpeg` component](/components/ffmpeg/) to be already configured.
To enable your ONVIF in your installation, add the following to your `configuration.yaml` file:
To enable your ONVIF camera in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry

53
source/_components/canary.markdown Normal file
View file

@ -0,0 +1,53 @@
---
layout: page
title: "Canary"
description: "Instructions on how to integrate your Canary devices into Home Assistant."
date: 2017-12-07 22:00
sidebar: true
comments: false
sharing: true
footer: true
logo: canary.png
ha_category: Hub
ha_release: "0.60"
ha_iot_class: "Cloud Polling"
---
The `canary` component allows you to integrate your [Canary](https://canary.is) devices in Home Assistant.
You will need your Canary login information (username, usually your email address, and password) to use this module.
To set it up, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
canary:
username: you@example.com
password: secret
```
{% configuration %}
username:
description: The username for accessing your Canary account.
required: true
type: string
password:
description: The password for accessing your Canary account.
required: true
type: string
timeout:
description: Timeout to wait for connections.
required: false
type: int
default: 10
{% endconfiguration %}
Once loaded, your front end will have the following components:
* A camera image triggered by motion for each camera.
* An alarm control panel for each location.
* A sensor per camera that reports temperature.
* A sensor per camera that reports humidity.
* A sensor per camera that reports air quality.

4
source/_components/climate.generic_thermostat.markdown
View file

@ -32,12 +32,13 @@ Configuration variables:
- **target_sensor** (*Required*): `entity_id` for a temperature sensor, target_sensor.state must be temperature.
- **min_temp** (*Optional*): Set minimum set point available (default: 7)
- **max_temp** (*Optional*): Set maximum set point available (default: 35)
- **target_temp** (*Optional*): Set initial target temperature. Failure to set this variable will result in target temperature being set to null on startup.
- **target_temp** (*Optional*): Set initial target temperature. Failure to set this variable will result in target temperature being set to null on startup. As of version 0.59 it will retain the target temperature set before restart if this variable is not configured.
- **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.
- **cold_tolerance** (*Optional*): Set a minimum amount of difference between the temperature read by the sensor specified in the *target_sensor* option and the target temperature that must change prior to being switched on. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will start when the sensor equals or goes below 24.5.
- **hot_tolerance** (*Optional*): Set a minimum amount of difference between the temperature read by the sensor specified in the *target_sensor* option and the target temperature that must change prior to being switched off. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will stop when the sensor equals or goes above 25.5.
- **keep_alive** (*Optional*): Set a keep-alive interval. If set, the switch specified in the *heater* option will be triggered every time the interval elapses. Use with heaters and A/C units that shut off if they don't receive a signal from their remote for a while.
- **initial_operation_mode** (*Optional*): Set the initial operation mode. Valid values are `off` or `auto`. Value has to be double quoted. If this parameter is not set, it is preferable to set a *keep_alive* value. This is helpful to align any discrepancies between *generic_thermostat* and *heater* state.
A full configuration example looks like the one below. `min_cycle_duration` and `keep_alive` must contain at least one of the following entries: `days:`, `hours:`, `minutes:`, `seconds:` or `milliseconds:`.
@ -57,4 +58,5 @@ climate:
seconds: 5
keep_alive:
minutes: 3
initial_operation_mode: "off"
```

29
source/_components/climate.hive.markdown Normal file
View file

@ -0,0 +1,29 @@
---
layout: page
title: "Hive Thermostat"
description: "Instructions on how to integrate Hive thermostat(s) with Home Assistant."
date: 2017-09-24 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: hive.png
ha_category: Climate
ha_release: 0.59
ha_iot_class: "Cloud Polling"
---
The 'hive' climate component integrates your Hive thermostat and hot water into Home Assistant, enabling control of setting the **mode** and setting the **target temperature**.
The Hive climate component supports the following Hive products:
- **Hive Active Heating**
- **Hive Multizone**
- **Hot water control**
<p class='note'>
Full configuration details can be found on the main [Hive component](/components/hive/) page.
</p>

17
source/_components/cloud.markdown
View file

@ -8,12 +8,19 @@ comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_release: 0.57
ha_release: 0.60
ha_category: Voice
ha_iot_class: "Cloud Push"
---
The Home Assistant Cloud allows you to quickly integrate your local instance with various cloud services. Any processing of services from other cloud services is handled by your local instance.
The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services. Any processing of services from other cloud services is handled by your local Home Assistant.
To get started, create an account and log in via the configuration panel in your Home Assistant instance. There is no need to configure your router or expose your instance to the internet in any other way.
```yaml
# Example configuration.yaml entry to enable the cloud component
cloud:
```
Once activated, go to the configuration panel in Home Assistant and create an account and log in. There is no need to configure your router or expose your instance to the internet in any other way.
### {% linkable_title Amazon Alexa %}
@ -86,3 +93,7 @@ Currently, the following domains are available to be used with Alexa:
- switch
[alexa skill]: https://alexa.amazon.com/spa/index.html#skills/dp/B0772J1QKB/?ref=skill_dsk_skb_sr_2
### {% linkable_title Frequently Asked Questions %}
You can find a list of frequently asked questions (and their answers) in [this blog post](https://home-assistant.io/blog/2017/12/17/introducing-home-assistant-cloud/#faq).

14
source/_components/cover.garadget.markdown
View file

@ -98,3 +98,17 @@ logbook:
- sensor.garage_door_time_in_state
- sensor.garage_door_wifi_signal_strength
```
As of firmware release 1.17 the garadget device has native support for MQTT. The options allow the end-user to configure the device in the following ways 'cloud only', 'cloud and MQTT' or 'MQTT only'.
For configuration of the garadget as a MQTT cover:
```yaml
cover:
- platform: mqtt
name: "Garage Door"
command_topic: "garadget/device_name/command"
state_topic: "garadget/device_name/status"
payload_open: "open"
payload_close: "close"
```

21
source/_components/cover.tahoma.markdown Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
title: "Tahoma Cover"
description: "Instructions how to integrate Tahoma covers into Home Assistant."
date: 2017-07-18 12:00
sidebar: true
comments: false
sharing: true
footer: true
logo: tahoma.png
ha_category: Cover
ha_release: 0.59
---
To use your tahoma covers in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yml entry
cover:
platform: tahoma
```

25
source/_components/cover.tellstick.markdown Normal file
View file

@ -0,0 +1,25 @@
---
layout: page
title: "TellStick Cover"
description: "Instructions how to integrate TellStick covers into Home Assistant."
date: 2017-11-29 16:23
sidebar: true
comments: false
sharing: true
footer: true
logo: telldus_tellstick.png
ha_category: Cover
ha_iot_class: "Assumed State"
ha_release: "0.60"
---
This `tellstick` cover platform allows you to control your [TellStick](http://www.telldus.se/products/tellstick) covers.
To use your TellStick device, you first have to set up your [Tellstick hub](/components/tellstick/) and then add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: tellstick
```

11
source/_components/cover.zwave.markdown
View file

@ -2,7 +2,7 @@
layout: page
title: "Z-Wave Cover"
description: "Instructions how to setup the Z-Wave covers within Home Assistant."
date: 2016-08-24 14:15
date: 2016-12-18 19:41
sidebar: true
comments: false
sharing: true
@ -16,3 +16,12 @@ ha_iot_class: "Local Push"
Z-Wave garage doors, blinds, and roller shutters are supported as cover in Home Assistant.
To get your Z-Wave covers working with Home Assistant, follow the instructions for the general [Z-Wave component](/components/zwave/).
If you discover that you need to [invert the operation]](/docs/z-wave/installation/#invert_openclose_buttons) of open/close for a particular device, you may change this behavior in your Z-Wave section of your `configuration.yaml` file as follows:
```yaml
zwave:
device_config:
cover.my_cover:
invert_openclose_buttons: true
```

3
source/_components/device_tracker.bluetooth_le_tracker.markdown
View file

@ -43,6 +43,9 @@ device_tracker:
Configuration variables:
- **device_id** (*Optional*): The device ID for the Bluetooth device to be used for tracking. Defaults to `hci0`.
- **track_new_devices** (*Optional*): If new discovered devices are tracked by default. Defaults to `True`.
- **scan_duration** (*Optional*): How long should the scanner be looking for BLE devices. Defaults to `10` seconds.
- **interval_seconds** (*Optional*): Seconds between each scan for new devices. Defaults to `12` seconds.
As some BT LE devices change their MAC address regularly, a new device is only discovered when it has been seen 5 times.
Some BTLE devices (e.g. fitness trackers) are only visible to the devices that they are paired with. In this case, the BTLE tracker won't see this device.

16
source/_components/device_tracker.markdown
View file

@ -26,15 +26,19 @@ device_tracker:
host: 192.168.1.1
username: admin
password: YOUR_PASSWORD
new_device_defaults:
track_new_devices: True
hide_if_away: False
```
The following optional parameters can be used with any platform. However device tracker will only look for global settings under the configuration of the first configured platform:
| Parameter | Default | Description |
|---------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `track_new_devices` | True | If new discovered devices are tracked by default |
| `interval_seconds` | 12 | Seconds between each scan for new devices |
| `consider_home` | 180 | Seconds to wait till marking someone as not home after not being seen. This parameter is most useful for households with Apple iOS devices that go into sleep mode while still at home to conserve battery life. iPhones will occasionally drop off the network and then re-appear. `consider_home` helps prevent false alarms in presence detection when using IP scanners such as Nmap. `consider_home` accepts various time representations, (E.g. the following all represents 3 minutes: `180`, `0:03`, `0:03:00`) |
|----------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `interval_seconds` | 12 | Seconds between each scan for new devices |
| `consider_home` | 180 | Seconds to wait till marking someone as not home after not being seen. This parameter is most useful for households with Apple iOS devices that go into sleep mode while still at home to conserve battery life. iPhones will occasionally drop off the network and then re-appear. `consider_home` helps prevent false alarms in presence detection when using IP scanners such as Nmap. `consider_home` accepts various time representations, (E.g. the following all represents 3 minutes: `180`, `0:03`, `0:03:00`) |
| `new_device_defaults`| | Default values for new discovered devices. Available options `track_new_devices` (default: `True`), `hide_if_away` (default: `False`) |
The extended example from above would look like the following sample:
@ -66,6 +70,10 @@ devicename:
hide_if_away: no
```
<p class='note warning'>
In the example above, `devicename` refers to the detected name of the device. For instance, `my_iphone`.
</p>
| Parameter | Default | Description |
|----------------|-------------------------------|---------------------------------------------------------------------------------------------------------|
| `name` | Host name or "Unnamed Device" | The friendly name of the device. |

37
source/_components/device_tracker.meraki.markdown Normal file
View file

@ -0,0 +1,37 @@
---
layout: page
title: "Meraki"
description: "Instructions on how to integrate Meraki-based presence detection into Home Assistant."
date: 2017-11-22 08:00
sidebar: true
comments: false
sharing: true
footer: true
logo: meraki.png
ha_category: Presence Detection
ha_release: "0.60"
---
Use your `Meraki AP` as device tracker. Note that Meraki will see all devices, not only connected to the network.
Follow instructions [here](https://meraki.cisco.com/technologies/location-analytics-api) how to enable Location Analytics.
After you configure access to the Meraki CMX API, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
device_tracker:
- platform: meraki
secret: your_secret
validator: meraki_validator
```
{% configuration %}
secret:
description: Secret code added in Meraki
required: true
type: string
validator:
description: Validation string from Meraki
required: true
type: string
{% endconfiguration %}

2
source/_components/device_tracker.nmap_tracker.markdown
View file

@ -15,7 +15,7 @@ featured: false
As an alternative to the router-based device tracking, it is possible to directly scan the network for devices by using Nmap. The IP addresses to scan can be specified in any format that Nmap understands, including the network-prefix notation (`192.168.1.1/24`) and the range notation (`192.168.1.1-255`).
If you're on Debian or Ubuntu, you might have to install the packages for `arp` and `nmap`. Do so by running `$ sudo apt-get install net-tools nmap`. On a Fedora host run `$ sudo dnf -y install nmap`.
You might have to install the packages for `arp` and `nmap`. On Debian based hosts (for example Hassbian and Raspbian) do so by running `$ sudo apt-get install net-tools nmap`. On a Fedora host run `$ sudo dnf -y install nmap`.
<p class='note'>
If you are using [Hass.io](/hassio/) then just move forward to the configuration as all requirements are already fulfilled.

1
source/_components/device_tracker.snmp.markdown
View file

@ -33,6 +33,7 @@ The following OID examples pull the current MAC Address table from a router. Thi
| TP-Link | Archer VR600 | `1.3.6.1.2.1.3.1.1.2` |
| EdgeRouter | Lite v1.9.0 | `1.3.6.1.2.1.4.22.1.2` |
| Ruckus | ZoneDirector 9.13.3 | `1.3.6.1.4.1.25053.1.2.2.1.1.3.1.1.1.6` |
| DD-WRT | unknown RouterOS version/model | `1.3.6.1.2.1.4.22.1.2` |
To use the SNMP version 1 platform in your installation, add the following to your `configuration.yaml` file:

2
source/_components/device_tracker.unifi.markdown
View file

@ -33,7 +33,7 @@ Configuration variables:
- **password** (*Required*): The password for your given admin account.
- **site_id** (*Optional*): Allows you to specify a `site_id` for device tracking. Defaults to `default`. Found in the URL of the controller (i.e. https://CONTROLLER:PORT/manage/site/SITE_ID/dashboard).
- **verify_ssl** (*Optional*): Controls if the SSL certificate running on your Unifi webserver must be trusted by a known Certificate Authority on the server running Home Assistant. Defaults to 'True' but can also be a value that points to your custom cert "path/to/custom_cert.pem".
- **detection_time** (*Optional*): The Unifi component will not return a device that has not been seen by the controller in the last 180 seconds. You can adjust this threshold with this variable and accepts seconds or `00:00:00` time formats.
- **detection_time** (*Optional*): The Unifi component will only return devices that have been seen by the controller in the last 180 seconds. You can adjust this threshold with this variable and accepts seconds or `00:00:00` time formats.
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.

45
source/_components/device_tracker.unifi_direct.markdown Normal file
View file

@ -0,0 +1,45 @@
---
layout: page
title: "Ubiquiti Unifi direct AP"
description: "Instructions how to use a Unifi WAP as a device tracker."
date: 2017-11-17 14:59
sidebar: true
comments: false
sharing: true
footer: true
logo: ubiquiti.png
ha_category: Presence Detection
ha_release: 0.59
---
This platform allows you to detect presence by looking at devices connected to a [UniFi AP](https://www.ubnt.com/products/#unifi). This device tracker differs form [Ubiquiti Unifi WAP](https://home-assistant.io/components/device_tracker.unifi/) because it doesn't require the Unifi controller software.
To use this device tracker in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
device_tracker:
- platform: unifi_direct
host: YOUR_AP_IP_ADDRESS
username: YOUR_USERNAME
password: YOUR_PASSWORD
```
{% configuration %}
host:
description: The hostname or IP address of your Unifi AP.
required: true
type: string
username:
description: The username used to connect to your Unifi AP.
required: true
type: string
password:
description: The password used to connect to your Unifi AP.
required: true
type: string
{% endconfiguration %}
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.

6
source/_components/discovery.markdown
View file

@ -35,6 +35,7 @@ Home Assistant can discover and automatically configure [zeroconf](https://en.wi
* [SABnzbd downloader](https://home-assistant.io/components/sensor.sabnzbd/)
* [Samsung TVs](https://home-assistant.io/components/media_player.samsungtv/)
* [Sonos speakers](https://home-assistant.io/components/media_player.sonos/)
* [Telldus Live](https://home-assistant.io/components/tellduslive/)
* [Yamaha media player](https://home-assistant.io/components/media_player.yamaha/)
* [Yeelight Sunflower bulb](https://home-assistant.io/components/light.yeelightsunflower/)
@ -77,6 +78,7 @@ Valid values for ignore are:
* `sabnzbd`: SABnzbd downloader
* `samsung_tv`: Samsung TVs
* `sonos`: Sonos speakers
* `tellduslive`: Telldus Live
* `yamaha`: Yamaha media player
* `yeelight`: Yeelight Sunflower bulb
@ -94,7 +96,9 @@ If you are on Windows and you're using Python 3.5, download the [Netifaces](http
</p>
<p class='note'>
If you see `Not initializing discovery because could not install dependency netdisco==0.6.1` in the logs, you will need to install the `python3-dev` or `python3-devel` package on your system manually (eg. `sudo apt-get install python3-dev` or `sudo dnf -y install python3-devel`). On the next restart of home-assistant, discovery should work. If you still get an error, check if you have a compiler (`gcc`) available on your system.
If you see `Not initializing discovery because could not install dependency netdisco==0.6.1` in the logs, you will need to install the `python3-dev` or `python3-devel` package on your system manually (eg. `sudo apt-get install python3-dev` or `sudo dnf -y install python3-devel`). On the next restart of Home Assistant, the discovery should work. If you still get an error, check if you have a compiler (`gcc`) available on your system.
For DSM/Synology, install via debian-chroot [see this forum post](https://community.home-assistant.io/t/error-starting-home-assistant-on-synology-for-first-time/917/15).
</p>
If you are developing a new platform, please read [how to make your platform discoverable](/developers/component_discovery/) for further details.

80
source/_components/dominos.markdown Normal file
View file

@ -0,0 +1,80 @@
---
layout: page
title: "Dominos Pizza"
description: "Instructions on how to setup Dominos Pizza ordering within Home Assistant."
date: 2017-11-05 17:30
sidebar: true
comments: false
sharing: true
footer: true
logo: dominos.png
ha_category: Other
ha_version: 0.59
---
The `Dominos` component allows you to order Dominos Pizza from within your Home Assistant scripts and automations.
At present, this component only supports ordering within Canada and the US.
To enable the component, you need to set up your customer information and define some orders.
Orders are a group of product codes. You can get these product codes by inspecting an order request from the Dominos web app, or you can [add this custom panel by following this readme](https://github.com/wardcraigj/hass-dominos-panel) to see the available product codes in a separate panel in your install.
Currently, there is no support in this component for toppings, coupons or order tracking.
```yaml
dominos:
country_code: ca
first_name: John
last_name: Smith
email: john.smith@example.com
phone: 123456789
address: 24 Housten Dr, Ottawa, ON, K2M2M2
orders:
- name: Medium Pan
codes:
- P12IPAZA
```
Now you can use the Dominos service to order pizza within your automations:
```yaml
- service: dominos.order
data:
order_entity_id: dominos.medium_pan
```
{% configuration %}
country_code:
required: true
description: \'ca\' or \'us\', depending on your location
type: string
first_name:
required: true
description: Your first name
type: string
last_name:
required: true
description: Your last name
type: string
email:
required: true
description: Your email address
type: string
phone:
required: true
description: Your phone number
type: string
address:
required: true
description: Your delivery address
type: string
show_menu:
required: false
description: Dumps product codes from your nearest store into your log (for use in with the custom panel)
type: integer
orders:
required: false
description: Sets of product codes to use for ordering
type: list
{% endconfiguration %}

2
source/_components/ecobee.markdown
View file

@ -61,3 +61,5 @@ Configuration variables:
<img src='{{site_root}}/images/screenshots/ecobee-sensor-badges.png' />
<img src='{{site_root}}/images/screenshots/ecobee-thermostat-card.png' />
</p>
If for whatever reason you delete and re-create your ecobee app at ecobee.com such that your developer API key changes, you will need to delete your `/conf/ecobee.conf file`. You will also need to update the `api_key:` in the `configuration.yaml` or `secrets.yaml` file.

2
source/_components/emulated_hue.markdown
View file

@ -22,7 +22,7 @@ entities. The driving use case behind this functionality is to allow Home Assist
The virtual bridge has the ability to turn entities on or off, or change the brightness of dimmable lights. The volume level of media players can be controlled as brightness.
<p class='note'>
A physical Hue Bridge is required for the lights to function - this virtual bridge will not replace a physical bridge.
A physical Hue Bridge is required for Philips Hue lights to function - this virtual bridge will not replace a physical bridge. Instead, it allows Home Assistant to represent non-Philips Hue devices to Amazon Echo as Philips Hue devices, which Amazon Echo can control with built-in support.
</p>
<p class='note'>

2
source/_components/fan.xiaomi_miio.markdown
View file

@ -13,7 +13,7 @@ ha_version: 0.57
ha_iot_class: "Local Polling"
---
The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier 2. The Air Purifier Pro isn't supported right now.
The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier 2, Air Purifier 2S andd Air Purifier Pro.
Currently, the supported features are

8
source/_components/frontend.markdown
View file

@ -23,7 +23,7 @@ frontend:
description: "Version of the JavaScript to serve to clients. Options: `es5` - transpiled so old browsers understand it. `latest` - not transpiled, so will work on recent browsers only. `auto` - select a version according to the browser user-agent. The value in the config can be overiden by putting `es5` or `latest` in the URL. For example `http://localhost:8123/states?es5` "
required: false
type: string
default: es5
default: auto
themes:
description: Allow to define different themes. See below for further details.
required: false
@ -39,7 +39,11 @@ frontend:
required: true
type: [list, string]
extra_html_url:
description: "List of addtional [resources](/developers/frontend_creating_custom_ui/) to load."
description: "List of addtional [resources](/developers/frontend_creating_custom_ui/) to load in `latest` javascript mode."
required: false
type: list
extra_html_url_es5:
description: "List of addtional [resources](/developers/frontend_creating_custom_ui/) to load in `es5` javascript mode."
required: false
type: list
development_repo:

61
source/_components/google_assistant.markdown
View file

@ -13,14 +13,15 @@ featured: true
ha_release: 0.56
---
# Google Assistant Docs
The `google_assistant` component allows you to control things via Google Assistant (on your mobile or tablet) or a Google Home device.
The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.
<p class='note'>
To use Google Assistant your Home Assistant configuration has to be externally accessible, with a hostname and SSL certificate. If you haven't already configured that you should do so before continuing.
</p>
### {% linkable_title Configuration %}
To enable this, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
@ -36,18 +37,15 @@ google_assistant:
- group
```
*Note:* It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command:
Configuration variables:
`cat /dev/urandom|fold -w 120|head -n 1|base64 -w 0|tr -dc '0-9A-Za-z'|cut -c -80`
*Configuration Variables:*
* *expose_by_default* (Optional): Expose devices in all supported domains by default.
* *project_id* (Required): Project ID from the Google Developer console (looks like `words-2ab12`)
* *client_id* (Required): A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth.
* *access_token* (Required): Another different long random URL safe string.
* *agent_user_id* (Optional): A string to identify the user, e.g., email address. If not provided, the component will generate one.
* *api_key* (Optional): An API Key generated for the project from Google Console which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed.
* *exposed_domains* (Optional): An array of Home Assistant domains to expose to Google Assistant. Options include:
- **expose_by_default** (*Optional*): Expose devices in all supported domains by default.
- **project_id** (*Required*): Project ID from the Google Developer console (looks like `words-2ab12`)
- **client_id** (*Required*): A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth.
- **access_token** (*Required*): Another different long random URL safe string.
- **agent_user_id** (*Optional*): A string to identify the user, e.g., email address. If not provided, the component will generate one.
- **api_key** (*Optional*): An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed.
- **exposed_domains** (*Optional*): An array of Home Assistant domains to expose to Google Assistant. Options include:
- `switch`
- `light`
- `cover`
@ -56,6 +54,16 @@ google_assistant:
- `fan`
- `scene`
- `script`
- `climate`
It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command:
```bash
$ cat /dev/urandom | fold -w 120 | head -n 1 | base64 -w 0 | tr -dc '0-9A-Za-z' | cut -c -80
```
If you're not using Linux, you can use sites such as [this one](https://www.browserling.com/tools/random-string) to generate a random string (containing mixed case letters and numbers) of up to 80 characters.
You can also customize your devices similar to other components by adding keys to entities:
@ -74,11 +82,12 @@ homeassistant:
google_assistant_type: light
```
*Entity Customization Keys:*
* *google_assistant*: True exposes entity, false will hide it
* *google_assistant_name*: Can be used to override the primary name of an entity. By default the `friendly_name` of an entity is used.
* *google_assistant_type*: Can be used to override the domain/type of an entity. For example a switch can be treated as a light
* *aliases*: Provides "nicknames" to Google Assistant. These function as alternate names for an entity that Assistant will understand when spoken.
Entity Customization Keys:
- **google_assistant**: True exposes entity, false will hide it.
- **google_assistant_name**: Can be used to override the primary name of an entity. By default the `friendly_name` of an entity is used.
- **google_assistant_type**: Can be used to override the domain/type of an entity. For example a switch can be treated as a light
- **aliases**: Provides "nicknames" to Google Assistant. These function as alternate names for an entity that Assistant will understand when spoken.
### {% linkable_title Setup %}
@ -111,15 +120,16 @@ homeassistant:
2. Go to Build under the Actions SDK box
3. Copy the command that looks like:
`gactions update --action_package PACKAGE_NAME --project doctest-2d0b8`
4. Replace `PACKAGE_NAME` with `project.json` and run that command from the same directory you saved `project.json` in (you'll need to put `./` before `gactions` so that it reads `./gactions`). It should output a URL like `https://console.actions.google.com/project/doctest-2d0b8/overview` - go there.
4. Replace `PACKAGE_NAME` with `project.json` and run that command from the same directory you saved `project.json` in (you'll need to put `./` before `gactions` so that it reads `./gactions` if you're running on Linux). It should output a URL like `https://console.actions.google.com/project/doctest-2d0b8/overview` - go there.
5. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant.
6. The final item on that page `Account linking` is required for your app to interact with Home Assistant.
1. Grant type: `Implicit`
2. Client ID: Should be the same as `client_id` from your hass config above
2. Client ID: The `client_id` from your Home Assistant configuration above
3. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`
4. Configure your client. Add scopes for `email` and `name`
5. Testing instructions: doesn't matter since you won't submit this app
7. Back on the main app draft page. Click `Test Draft`. That will take you to the simulator (which won't work) so just close that window.
8. If you haven't already added the configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have.
8. Open the Google Assistant app and go into `Settings > Home Control`
9. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead to you the screen where you can set rooms for your devices or nicknames for your devices.
10. If you want to allow other houshold users to control the devices:
@ -127,10 +137,17 @@ homeassistant:
2. Under the gear icon, click `Permissions`
3. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
4. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 7.
11. If you want to use the request_sync service in Home Assistant, then Enable Homegraph API for your project:
1. Go to https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview
11. If you want to use the `google_assistant.request_sync` service in Home Assistant, then enable Homegraph API for your project:
1. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview)
2. Select your project and click Enable Homegraph API
3. Go to Credentials and select API Key from Create Credentials
4. Note down the generated API Key and use this in the configuration
*Note:* The request_sync service requires that the initial sync from Google includes the agent_user_id. If not, the service will log an error that reads something like "Request contains an invalid argument". If this happens, then [unlink the account](https://support.google.com/googlehome/answer/7506443?hl=en-GB) from Home Control and relink.
*Note:* The request_sync service may fail with a 404 if the project_id of the Homegraph API differs from the project_id of the Actions SDK found in the preferences of your project on [developer console](https://console.actions.google.com). Resolve this by:
1. Removing your project on the [developer console](https://console.actions.google.com).
2. Add a new project in the [cloud console](https://console.cloud.google.com). Here you get a new project_id.
3. Enable Homegraph API to the new project.
4. Generete a new API key.
5. Again create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this they share the same project_id.

54
source/_components/hive.markdown Normal file
View file

@ -0,0 +1,54 @@
---
layout: page
title: "Hive"
description: "Instructions on how to integrate Hive devices with Home Assistant."
date: 2017-09-24 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: hive.png
ha_category: Hub
ha_release: 0.59
ha_iot_class: "Cloud Polling"
---
This Hive component is the main component to set up and integrate all supported Hive devices. Once configured with the minimum required details it will detect and add all your Hive devices into Home Assistant, including support for multizone heating.
This component uses the unofficial API used in the official Hive website [https://my.hivehome.com](https://my.hivehome.com), and you will need to use the same Username and Password you use on the Hive website to configure this Hive component in Home Assistant.
To add your Hive devices into your Home Assistant installation, using the default scan_interval, add the following to your 'configuration.yaml' file:
```yaml
# Example configuration.yaml entry
hive:
username: YOUR_USERNAME
password: YOUR_PASSWORD
```
{% configuration %}
username:
description: Your username from [https://my.hivehome.com](https://my.hivehome.com).
required: true
type: string
password:
description: Your password from [https://my.hivehome.com](https://my.hivehome.com).
required: true
type: string
scan_interval:
description: The time in minutes between Hive API calls
required: false
type: int
default: 2
{% endconfiguration %}
The Hive Home Assistant platform currently supports the following Hive devices:
- Hive Active Heating (including hot water and Hive Multizone)
- Hive Active Light Dimmable
- Hive Active Light Cool to Warm White
- Hive Active Plug
- Hive Window or Door Sensor
- Hive Motion Sensor

49
source/_components/homematic.markdown
View file

@ -28,58 +28,69 @@ To set up the component, add the following information to your `configuration.ya
```yaml
homematic:
hosts:
interfaces:
wireless:
ip: 127.0.0.1
host: 127.0.0.1
```
Configuration variables (global):
- **hosts** (*Required*): Configuration for each host to integrate into Home Assistant.
- **interfaces** (*Required*): Configuration for each XML-RPC interface to integrate into Home Assistant.
- **hosts** (*Optional*): Configuration for each Hub (CCU/Homegear) to integrate into Home Assistant.
- **local_ip** (*Optional*): IP of device running Home Assistant. Override auto-detected value for exotic network setups.
- **local_port** (*Optional*): Port for connection with Home Assistant. By default it is randomly assigned.
Configuration variables (host):
Configuration variables (interface):
- **ip** (*Required*): IP address of CCU/Homegear device.
- **host** (*Required*): IP address or Hostname of CCU/Homegear device or Hass.io add-on.
- **port** (*Optional*): Port of CCU/Homegear XML-RPC Server. Wireless: 2001, wired: 2000, IP: 2010, thermostatgroups: 9292.
- **callback_ip** (*Optional*): Set this, if Home Assistant is reachable under a different IP from the CCU (NAT, Docker etc.).
- **callback_port** (*Optional*): Set this, if Home Assistant is reachable under a different port from the CCU (NAT, Docker etc.).
- **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.
- **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. When using a CCU credentials are required.
- **path** (*Optional*): Set to `/groups` when using port 9292.
Configuration variables (host):
- **host** (*Required*): IP address of CCU/Homegear device.
- **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.
#### Example configuration with multiple protocols and some other options set:
```yaml
homematic:
hosts:
interfaces:
rf:
ip: 127.0.0.1
host: 127.0.0.1
resolvenames: json
username: Admin
password: secret
primary: true
variables: true
wired:
ip: 127.0.0.1
host: 127.0.0.1
port: 2000
resolvenames: json
username: Admin
password: secret
ip:
ip: 127.0.0.1
host: 127.0.0.1
port: 2010
groups:
ip: 127.0.0.1
host: 127.0.0.1
port: 9292
resolvenames: json
username: Admin
password: secret
path: /groups
hosts:
ccu2:
host: 127.0.0.1
username: Admin
password: secret
```
### {% linkable_title The `resolvenames` option %}
@ -115,7 +126,7 @@ sensor:
### {% linkable_title Variables %}
It is possible to read and set values of system variables you have setup on the CCU/Homegear. The supported types for setting values are float- and bool-variables.
The states of the variables are available through the attributes of your hub entity (e.g. `homematic.rf`). Use templates (as mentioned above) to make your variables available to automations or as entities.
The states of the variables are available through the attributes of your hub entity (e.g. `homematic.ccu2`). Use templates (as mentioned above) to make your variables available to automations or as entities.
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.
### {% linkable_title Events %}
@ -154,8 +165,8 @@ The name depends on if you chose to resolve names or not. If not, it will be the
* *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.
* *homematic.set_variable_value*: Set the value of a system variable.
* *homematic.set_device_value*: Control a device manually (even devices without support). Equivalent to setValue-method from XML-RPC.
#### {% linkable_title Examples %}
Simulate a button being pressed
@ -184,9 +195,9 @@ Set boolean variable to true
```yaml
...
action:
service: homematic.set_var_value
service: homematic.set_variable_value
data:
entity_id: homematic.rf
entity_id: homematic.ccu2
name: Variablename
value: true
```
@ -200,7 +211,7 @@ Manually turn on a switch actor
```yaml
...
action:
service: homematic.set_dev_value
service: homematic.set_device_value
data:
address: LEQ1234567
channel: 1
@ -212,7 +223,7 @@ Manually set temperature on thermostat
```yaml
...
action:
service: homematic.set_dev_value
service: homematic.set_device_value
data:
address: LEQ1234567
channel: 4

144
source/_components/hue.markdown Normal file
View file

@ -0,0 +1,144 @@
---
layout: page
title: "Philips Hue"
description: "Instructions on setting up Philips Hue within Home Assistant."
date: 2017-11-29 23:51
sidebar: true
comments: false
sharing: true
footer: true
logo: philips_hue.png
ha_category: Hub
ha_iot_class: "Local Polling"
featured: true
ha_release: 0.60
---
Philips Hue support is integrated into Home Assistant as a Hub that can drive the light platform. The preferred way to setup the Philips Hue platform is by enabling the [discovery component](/components/discovery/).
Once discovered, if you have a custom default view, locate `configurator.philips_hue` in the entities list ( < > ) and add it to a group in `configuration.yaml`. Restart Home Assistant so that the configurator is visible in the Home Assistant dashboard. Once Home Assistant is restarted, locate and click on `configurator.philips_hue` to bring up the initiation dialog. This will prompt you to press the Hue button to register the Hue hub in Home Assistant. Once complete, the configurator entity isn't needed anymore and can be removed from any visible group in `configuration.yaml`.
When you configure the Hue bridge from Home Assistant, it writes a token to a file in your Home Assistant [configuration directory](/docs/configuration/). That token authenticates the communication with the Hue bridge. This token uses the Address of the Hue Bridge. If the IP address for the Hue Bridge changes, you will need to register the Hue Bridge with Home Assistant again. To avoid this you may set up DHCP registration for your Hue Bridge, so that it always has the same IP address.
Once registration is complete you should see the Hue lights listed as "light" entities; if you don't you may have to restart Home Assistant once more. Add these light entities to configuration.yaml and restart Home Assistant once more to complete the installation.
If you want to enable the component without relying on the [discovery component](/components/discovery/), add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
hue:
bridges:
- host: DEVICE_IP_ADDRESS
```
Configuration variables:
- **host** (*Optional*): IP address of the device, eg. 192.168.1.10. Required if not using the `discovery` component to discover Hue bridges.
- **allow_unreachable** (*Optional*): (true/false) This will allow unreachable bulbs to report their state correctly.
- **filename** (*Optional*): Make this unique if specifying multiple Hue hubs.
- **allow_in_emulated_hue** (*Optional*): )true/false) Enable this to block all Hue entities from being added to the `emulated_hue` component.
- **allow_hue_groups** (*Optional*): (true/false) Enable this to stop Home Assistant from importing the groups defined on the Hue bridge.
### {% linkable_title Migrating from older configuration %}
In previous versions of the Hue component the configuration looked different:
```yaml
# Example configuration.yaml entry
light:
- platform: hue
host: DEVICE_IP_ADDRESS
```
You will need to convert each bridge into an entry in the new configuration style. See above for an example.
### {% linkable_title Multiple Hue bridges %}
Multiple Hue bridges work transparently with discovery, you don't have to do anything. If you prefer to configure them manually and use multiple Hue bridges then it's needed that you provide a configuration file for every bridge. The bridges can't share a single configuration file.
Add `filename` to your Hue configuration entry in your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
hue:
bridges:
- host: BRIDGE1_IP_ADDRESS
filename: phue.conf
- host: BRIDGE2_IP_ADDRESS
filename: phue2.conf
```
### {% linkable_title Using Hue Groups in Home Assistant %}
The Hue API allows you to group lights. Home Assistant also supports grouping of entities natively, but sometimes it can be useful to use Hue Groups to group light bulbs. By doing so, Home Assistant only needs to send one API call to change the state of all the bulbs in those groups instead of one call for every light in the group. This causes all the bulbs to change state simultaneously.
These Hue Groups can be a `Luminaire`, `Lightsource`, `LightGroup` or `Room`. The `Luminaire` and `Lightsource` can't be created manually since the Hue bridge manages these automatically based on the discovered bulbs. The `Room` and `LightGroup` can be created manually through the API, or the mobile app. A bulb can only exist in one `Room`, but can exist in multiple `LightGroup`. The `LightGroup` can be useful to link certain bulbs together since.
The 2nd generation Hue app only allows to create a `Room`. You need to use the first generation app or the API to create a `LightGroup`.
Example:
To create a `LightGroup` named `Ceiling lights` that contains the lights 1, 2 and 3, execute the following command:
```bash
$ curl -XPOST -d '{"name": "Ceiling lights", "lights": ["1", "2", "3"]}' http://<bridge>/api/<username>/groups
```
The `<username>` is the string that is used to register Home Assistant on the bridge, you can find it in the `phue.conf` file in your configuration path. `<bridge>` is the IP address or hostname of your Hue bridge.
You can find out the ids of your lights by executing the following command:
```bash
$ curl http://<bridge>/api/<username>/lights
```
Home Assistant will automatically detect your new `LightGroup` and add it to the interface.
<p class='note warning'>
To support Hue Light Groups, your bridge needs to have at least firmware 1.13 (released on June 3, 2016).
</p>
More information can be found on the [Philips Hue API documentation](https://www.developers.meethue.com/documentation/groups-api#22_create_group) website.
### {% 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 hue.hue_activate_scene service which can be used by `automation` or `script` components.
This will have all the bulbs transitioned at once, instead of one at a time using standard scenes in Home Assistant.
For instance:
```yaml
script:
porch_on:
sequence:
- service: hue.hue_activate_scene
data:
group_name: "Porch"
scene_name: "Porch Orange"
```
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `group_name` | no | The group/room name of the lights. Find this in the Hue official app.
| `scene_name` | no | The name of the scene. Find this in the Hue official app.
*Note*: `group_name` is not linked to Home Assistant group name.
### {% linkable_title 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.
### {% linkable_title 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 guaranteed 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 limited 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".

10
source/_components/ifttt.markdown
View file

@ -64,6 +64,7 @@ Choose "Webhooks" as service.
You need to setup a unique trigger for each event you sent to IFTTT.
</p>
{% raw %}
```yaml
# Example configuration.yaml Automation entry
automation:
@ -75,9 +76,11 @@ automation:
service: ifttt.trigger
data: {"event":"TestHA_Trigger", "value1":"Hello World!"}
```
{% endraw %}
IFTTT can also be used in scripts and with `data_template`. Here is the above automation broken into an automation and script using variables and data_templates.
{% raw %}
```yaml
# Example configuration.yaml Automation entry
automation:
@ -89,10 +92,12 @@ automation:
service: script.ifttt_notify
data_template:
value1: 'HA Status:'
value2: {% raw %}"{{ trigger.event.data.entity_id.split('_')[1] }} is "{% endraw %}
value3: {% raw %}"{{ trigger.event.data.to_state.state }}"{% endraw %}
value2: "{{ trigger.event.data.entity_id.split('_')[1] }} is "
value3: "{{ trigger.event.data.to_state.state }}"
```
{% endraw %}
{% raw %}
```yaml
#Example Script to send TestHA_Trigger to IFTTT but with some other data (homeassistant UP).
ifttt_notify:
@ -100,6 +105,7 @@ ifttt_notify:
- service: ifttt.trigger
data_template: {"event":"TestHA_Trigger", "value1":"{{ value1 }}", "value2":"{{ value2 }}", "value3":"{{ value3 }}"}
```
{% endraw %}
### {% linkable_title Sending events from IFTTT to Home Assistant %}

3
source/_components/influxdb.markdown
View file

@ -34,6 +34,8 @@ 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.
- **max_retries** (*Optional*): Allow the component to retry if there was a network error when transmitting data
- **retry_queue_limit** (*Optional*): If retry enabled, specify how much calls are allowed to be queued for retry.
- **default_measurement** (*Optional*): Measurement name to use when an entity doesn't have a unit. Defaults to entity id.
- **override_measurement** (*Optional*): Measurement name to use instead of unit or default measurement. This will store all data points in a single measurement.
- **component_config**, **component_config_domain**, **component_config_glob** (*Optional*): These attributes contains component-specific override values. See [Customizing devices and services](https://home-assistant.io/getting-started/customizing-devices/) for format.
@ -175,6 +177,7 @@ influxdb:
password: MY_PASSWORD
ssl: true
verify_ssl: true
max_retries: 3
default_measurement: state
exclude:
entities:

130
source/_components/input_number.markdown
View file

@ -39,27 +39,57 @@ input_number:
mode: box
```
Configuration variables:
- **[alias]** (*Required*): Alias for the input. Multiple entries are allowed.
- **min** (*Required*): Minimum value.
- **max** (*Required*): Maximum value.
- **name** (*Optional*): Friendly name of the input.
- **initial** (*Optional*): Initial value when Home Assistant starts. Defaults to 0.
- **step** (*Optional*): Step value for the slider. Defaults to 1.
- **mode** (*Optional*): Can specify `box`, or `slider`. Defaults to `slider`.
- **unit_of_measurement** (*Optional*): Unit of measurement in which the value of the slider is expressed in.
- **icon** (*Optional*): Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](https://home-assistant.io/docs/configuration/customizing-devices/#possible-values) page for possible values.
{% configuration %}
input_number:
description: Alias for the input. Multiple entries are allowed.
required: true
type: map
keys:
min:
description: Minimum value.
required: true
type: float
max:
description: Maxium value.
required: true
type: float
name:
description: Friendly name of the input.
required: false
type: string
initial:
description: Initial value when Home Assistant starts.
required: false
type: float
default: 0
step:
description: Step value for the slider. Smallest value `0.001`.
required: false
type: float
default: 1
mode:
description: Can specify `box` or `slider`.
required: false
type: box | slider
default: slider
unit_of_measurement:
description: Unit of measurement in which the value of the slider is expressed in.
required: false
type: string
icon:
description: Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](https://home-assistant.io/docs/configuration/customizing-devices/#possible-values) page for possible values.
required: false
type: icon
{% endconfiguration %}
## {% linkable_title Automation Examples %}
Here's an example of `input_number` being used as a trigger in an automation.
```yaml
{% raw %}
```yaml
# Example configuration.yaml entry using 'input_number' as a trigger in an automation
# Define input_number
input_number:
bedroom_brightness:
name: Brightness
@ -67,8 +97,6 @@ input_number:
min: 0
max: 254
step: 1
# Automation.
automation:
- alias: Bedroom Light - Adjust Brightness
trigger:
@ -76,20 +104,18 @@ automation:
entity_id: input_number.bedroom_brightness
action:
- service: light.turn_on
# Note the use of 'data_template:' below rather than the normal 'data:' if you weren't using an input variable
# Note the use of 'data_template:' below rather than the normal 'data:' if you weren't using an input variable
data_template:
entity_id: light.bedroom
brightness: '{{ trigger.to_state.state | int }}'
{% endraw %}
brightness: "{{ trigger.to_state.state | int }}"
```
{% endraw %}
Another code example using `input_number`, this time being used in an action in an automation.
```yaml
{% raw %}
```yaml
# Example configuration.yaml entry using 'input_number' in an action in an automation
# Define 'input_select'
input_select:
scene_bedroom:
name: Scene
@ -101,8 +127,6 @@ input_select:
- Relax
- 'OFF'
initial: 'Select'
# Define input_number
input_number:
bedroom_brightness:
name: Brightness
@ -110,8 +134,6 @@ input_number:
min: 0
max: 254
step: 1
# Automation.
automation:
- alias: Bedroom Light - Custom
trigger:
@ -120,21 +142,18 @@ automation:
to: CUSTOM
action:
- service: light.turn_on
# Again, note the use of 'data_template:' rather than the normal 'data:' if you weren't using an input variable.
# Again, note the use of 'data_template:' rather than the normal 'data:' if you weren't using an input variable.
data_template:
entity_id: light.bedroom
brightness: '{{ states.input_number.bedroom_brightness.state | int }}'
{% endraw %}
brightness: "{{ states('input_number.bedroom_brightness') | int }}"
```
{% endraw %}
Example of `input_number` being used in a bidirectional manner, both being set by and controlled by an MQTT action in an automation.
```yaml
{% raw %}
```yaml
# Example configuration.yaml entry using 'input_number' in an action in an automation
# Define input_number
input_number:
target_temp:
name: Target Heater Temperature Slider
@ -144,30 +163,31 @@ input_number:
unit_of_measurement: step
icon: mdi:target
# Automation.
# This automation script runs when a value is received via MQTT on retained topic: setTemperature
# It sets the value slider on the GUI. This slides also had its own automation when the value is changed.
- alias: Set temp slider
trigger:
platform: mqtt
topic: "setTemperature"
action:
service: input_number.set_value
data_template:
entity_id: input_number.target_temp
value: '{{ trigger.payload}}'
automation:
- alias: Set temp slider
trigger:
platform: mqtt
topic: 'setTemperature'
action:
service: input_number.set_value
data_template:
entity_id: input_number.target_temp
value: "{{ trigger.payload }}"
# This automation script runs when the target temperature slider is moved.
# It publishes its value to the same MQTT topic it is also subscribed to.
- alias: Temp slider moved
trigger:
platform: state
entity_id: input_number.target_temp
action:
service: mqtt.publish
data_template:
topic: "setTemperature"
retain: true
payload: '{{ states.input_number.target_temp.state | int }}'
{% endraw %}
# This automation script runs when the target temperature slider is moved.
# It publishes its value to the same MQTT topic it is also subscribed to.
automation:
- alias: Temp slider moved
trigger:
platform: state
entity_id: input_number.target_temp
action:
service: mqtt.publish
data_template:
topic: 'setTemperature'
retain: true
payload: "{{ states('input_number.target_temp') | int }}"
```
{% endraw %}

44
source/_components/isy994.markdown
View file

@ -34,12 +34,54 @@ Configuration variables:
- **host** (*Required*): The host entry should be in full URL format, eg. http://192.168.10.100:80
- **username** (*Required*): The username that used to access the ISY interface.
- **password** (*Required*): The password that used to access the ISY interface.
- **sensor_string** (*Optional*): This is the string that is used to identify which devices are to be assumed to be sensors instead of lights of switches. By default, this string is 'sensor'. If this string is found in the device name or folder, Home Assistant will assume it is as a sensor or binary sensor (if the device has on/off or true/false states).
- **sensor_string** (*Optional*): This is the string that is used to identify which devices are to be assumed to be sensors instead of lights of switches. By default, this string is 'sensor'. If this string is found in the device name or folder, Home Assistant will assume it is as a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion and leak sensors should all be detected automatically.
- **hidden_string** (*Optional*): The HIDDEN_STRING is a string that is used to identify which devices are to be hidden on Home Assistant's front page. This string will be stripped from the device's name before being used. By default, this value is '{HIDE ME}'.
- **tls** (*Optional*): This entry should reflect the version of TLS that the ISY controller is using for HTTPS encryption. This value can be either 1.1 or 1.2. If this value is not set, it is assumed to be version 1.1. This is the default for most users. ISY994 Pro users may likely be using 1.2. When using HTTPS in the host entry, it is best practice to set this value.
Once the ISY controller is configured, it will automatically import any binary sensors, covers, fans, lights, locks, sensors and switches it can locate.
### {% linkable_title Sensors %}
An Insteon door/window sensor will show up as a single Binary Sensor rather than two discrete devices like it does in the ISY994 admin panel. Note that when in "Two Nodes" mode, the sensor will have an UNKNOWN state until the sensor changes for the first time since the last Home Assistant reboot. If you do not use Insteon scenes that are controlled directly from the door sensor, you may prefer to set the sensor to "One Node" mode using the ISY Admin Panel.
Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY994. The name of the device will be based on what the parent node is named in the ISY994, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node either in the ISY994 Admin Panel (which will change the entity_id in Home Assistant) or assign a `friendly_name` in the [Customization section](https://home-assistant.io/docs/configuration/customizing-devices/) of your configuration.
If your leak or door/window sensor supports heartbeats, a new binary_sensor device will be added to Home Assistant to represent the battery state. The sensor will stay "Off" so long as the daily heartbeats occur. If a heartbeat is missed, the sensor will flip to "On". The name of this device will be based on the heartbeat node in the ISY.
### {% linkable_title Handling Insteon Control Events %}
A Home Assistant `isy994_control` event is emitted for every "control" event in the Insteon network. This allows you to write automations that trigger based on Insteon button presses. You can also trigger off of the unique Insteon events, such as double-presses, long-holds etc.
```yaml
automation:
- alias: turn off living room on double tap lightswitch
trigger:
platform: event
event_type: isy994_control
event_data:
entity_id: light.lr_track_lights_front
control: 'DFOF'
action:
service: light.turn_off
entity_id: light.lr_track_lights_rear
```
All `isy994_control` events will have an `entity_id` and `control` parameter in its `event_data`. You'll need to refer to ISY994 documentation for the list of every possible control type, but the common ones are:
- `DON`: On button
- `DOF`: Off button
- `DFON`: "Fast On", usually from double-tapping an On button
- `DFOF`: "Fast Off", usually from double-tapping an Off button
- `FDUP`: "Fade Up", usually while holding down an On button
- `FDDOWN`: "Fade Down", usually while holding down an Off button
- `FDSTOP`: "Fade Stop", when releasing a long-held button
- `BRT`: "Brighten", from controllers that issue a single command to slightly brighten a light
- `DIM`: "Dim", from controllers that issue a single command to slightly dim a light
### {% linkable_title Insteon Scenes %}
All Insteon scenes configured in the ISY994 will show up as switches in Home Assistant.
### {% linkable_title Creating Custom Devices %}
Using the Programs tab in the controller's Administrative Console, custom devices can be created that will appear natively inside of Home Assistant. Home Assistant will scan the following folders and build the device to the associated domains:

27
source/_components/joaoapps_join.markdown
View file

@ -13,22 +13,21 @@ ha_release: "0.24"
---
The Join platform exposes services from [Join](http://joaoapps.com/join). In Home Assistant, the Join features are divided up in two locations, the Join component, and the Join notify platform. The notify platform allows us to send messages to Join devices, the component allows us to access the other special features that Join offers.
The `joaoapps_join` component exposes services from [Join](http://joaoapps.com/join). In Home Assistant, the Join features are divided up in two locations, the Join component, and the Join notify platform. The notify platform allows us to send messages to Join devices, the component allows us to access the other special features that Join offers.
In the `configuration.yaml` file you need to provide the api key and device id or name of the target device. You can find your device id and api key [here](https://joinjoaomgcd.appspot.com/).
To set it up, add the following information to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- platform: joaoapps_join
api_key: asd97823jb628a34fwsdfwefd5384345tf2d
device_id: d5asdfasdf54645h45h368761dfe5gt8a *optional
device_ids: d5asdfasdf54645h45h368761dfe5gt8a, a4asdfasdf54645h45h368761dfe5gt3b *optional
device_names: Pixel, iPhone *optional
name: Phones *optional
device_id: d5asdfasdf54645h45h368761dfe5gt8a
device_ids: d5asdfasdf54645h45h368761dfe5gt8a, a4asdfasdf54645h45h368761dfe5gt3b
device_names: Pixel, iPhone
name: Phones
joaoapps_join:
- name: android
device_id: group.android
@ -42,20 +41,20 @@ Configuration variables:
- **device_ids** (*Optional*): Comma separated list of device ids.
- **device_names** (*Optional*): Comma separated list of device names.
The notify service has two optional parameters: `icon` and `vibration`. You can use them like so:
The notify service has two optional parameters: `icon` and `vibration`. You can use them like so:
```json
{"message":"Hello from Home Assistant!","title":"Home Assistant","data":{"icon":"https://goo.gl/xeetdy", "vibration":"0,65,706,86,657,95,668,100"}}
```
The services exposed in the joaoapps_join component can be used with the service data described below:
The services exposed in the `joaoapps_join` component can be used with the service data described below:
| Service | Data |
|------------------------------ |------------------------------------------------------------------ |
| joaoapps_join/ring | |
| joaoapps_join/send_sms | {"number":"5553334444", "message":"Hello!"} |
| joaoapps_join/send_tasker | {"command":"test"} |
| joaoapps_join/send_url | {"url":"http://google.com"} |
| joaoapps_join/send_wallpaper | {"url":"http://www.planwallpaper.com/static/images/ZhGEqAP.jpg"} |
| joaoapps_join/send_file | {"url":"http://download.thinkbroadband.com/5MB.zip"} |
| joaoapps_join/send_sms | `{"number":"5553334444", "message":"Hello!"}` |
| joaoapps_join/send_tasker | `{"command":"test"}` |
| joaoapps_join/send_url | `{"url":"http://google.com"}` |
| joaoapps_join/send_wallpaper | `{"url":"http://www.planwallpaper.com/static/images/ZhGEqAP.jpg"}` |
| joaoapps_join/send_file | `{"url":"http://download.thinkbroadband.com/5MB.zip"}` |

1
source/_components/knx.markdown
View file

@ -83,6 +83,7 @@ knx:
- **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus
- **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus.
- **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behaviour.
- **time_address** (*Optional*): Broadcast current local time to KNX bus with configured group address.
### {% linkable_title Services %}

42
source/_components/light.ads.markdown Normal file
View file

@ -0,0 +1,42 @@
---
layout: page
title: "ADS Light"
description: Instructions how to set up ADS lights within Home Assistant
date: 2017-10-25 10:00
sidebar: true
comments: false
sharing: true
footer: true
logo: beckhoff.png
ha_category: Light
ha_release: "0.60"
ha_iot_class: "Local Push"
---
The `ads` light platform allows you to control your connecte ADS lights.
To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
file:
```yaml
# Example configuration.yaml entry
light:
- platform: ads
adsvar: GVL.enable_light
adsvar_brightness: GVL.brightness
```
{% configuration %}
adsvar:
required: true
description: The name of the boolean variable that switches the light on
type: string
adsvar_brightness:
required: false
description: The name of the variable that controls the brightness, use an unsigned integer on the PLC side
type: integer
name:
required: false
description: An identifier for the Light in the frontend
type: string
{% endconfiguration %}

28
source/_components/light.hive.markdown Normal file
View file

@ -0,0 +1,28 @@
---
layout: page
title: "Hive Light"
description: "Instructions on how to integrate Hive lights with Home Assistant."
date: 2017-09-24 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: hive.png
ha_category: Light
ha_release: 0.59
ha_iot_class: "Cloud Polling"
---
The 'hive' light component integrates your Hive lights into Home Assistant, enabling control of various settings, depending on the model light.
The Hive light component supports the following Hive products:
- **Hive Active Light Dimmable**
- **Hive Active Light Cool to Warm White**
<p class='note'>
Full configuration details can be found on the main [Hive component](/components/hive/) page.
</p>

121
source/_components/light.hue.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Philips Hue"
description: "Instructions how to setup Philips Hue within Home Assistant."
title: "Philips Hue Light"
description: "Instructions how to integrate Philips Hue lights into Home Assistant."
date: 2015-03-23 20:09
sidebar: true
comments: false
@ -14,119 +14,8 @@ featured: true
ha_release: pre 0.7
---
Philips Hue support is integrated into Home Assistant as a light platform. The preferred way to setup the Philips Hue platform is by enabling the [discovery component](/components/discovery/).
The Philips Hue light platform allows you to control your Philips Hue lights.
Once discovered, if you have a custom default view, locate `configurator.philips_hue` in the entities list ( < > ) and add it to a group in `configuration.yaml`. Restart Home Assistant so that the configurator is visible in the Home Assistant dashboard. Once Home Assistant is restarted, locate and click on `configurator.philips_hue` to bring up the initiation dialog. This will prompt you to press the Hue button to register the Hue hub in Home Assistant. Once complete, the configurator entity isn't needed anymore and can be removed from any visible group in `configuration.yaml`.
This component will automatically add `Lights` configured on your Hue bridges.
When you configure the Hue bridge from Home Assistant, it writes a token to a file in your Home Assistant [configuration directory](/docs/configuration/). That token authenticates the communication with the Hue bridge. This token uses the IP Address of the Hue Bridge. If the IP address for the Hue Bridge changes, you will need to register the Hue Bridge with Home Assistant again. To avoid this you may set up DHCP registration for your Hue Bridge, so that it always has the same IP address.
Restarting Home Assistant once more should result in the Hue lights listed as "light" entities. Add these light entities to configuration.yaml and restart Home Assistant once more to complete the installation.
If you want to enable the component without relying on the [discovery component](/components/discovery/), add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: hue
host: DEVICE_IP_ADDRESS
```
Configuration variables:
- **host** (*Optional*): IP address of the device, eg. 192.168.1.10. Required if not using the `discovery` component to discover Hue bridges.
- **allow_unreachable** (*Optional*): (true/false) This will allow unreachable bulbs to report their state correctly.
- **filename** (*Optional*): Make this unique if specifying multiple Hue hubs.
- **allow_in_emulated_hue** (*Optional*): )true/false) Enable this to block all Hue entities from being added to the `emulated_hue` component.
- **allow_hue_groups** (*Optional*): (true/false) Enable this to stop Home Assistant from importing the groups defined on the Hue bridge.
### {% linkable_title Multiple Hue bridges %}
If you use multiple Hue bridges then it's needed that you provide a configuration file for every bridge. The bridges can't share a single configuration file.
Add `filename` to your Hue configuration entry in your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: hue
host: BRIDGE1_IP_ADDRESS
filename: phue.conf
- platform: hue
host: BRIDGE2_IP_ADDRESS
filename: phue2.conf
```
### {% linkable_title Using Hue Groups in Home Assistant %}
The Hue API allows you to group lights. Home Assistant also supports grouping of entities natively, but sometimes it can be useful to use Hue Groups to group light bulbs. By doing so, Home Assistant only needs to send one API call to change the state of all the bulbs in those groups instead of one call for every light in the group. This causes all the bulbs to change state simultaneously.
These Hue Groups can be a `Luminaire`, `Lightsource`, `LightGroup` or `Room`. The `Luminaire` and `Lightsource` can't be created manually since the Hue bridge manages these automatically based on the discovered bulbs. The `Room` and `LightGroup` can be created manually through the API, or the mobile app. A bulb can only exist in one `Room`, but can exist in multiple `LightGroup`. The `LightGroup` can be useful to link certain bulbs together since.
The 2nd generation Hue app only allows to create a `Room`. You need to use the first generation app or the API to create a `LightGroup`.
Example:
To create a `LightGroup` named `Ceiling lights` that contains the lights 1, 2 and 3, execute the following command:
```bash
$ curl -XPOST -d '{"name": "Ceiling lights", "lights": ["1", "2", "3"]}' http://<bridge>/api/<username>/groups
```
The `<username>` is the string that is used to register Home Assistant on the bridge, you can find it in the `phue.conf` file in your configuration path. `<bridge>` is the IP address or hostname of your Hue bridge.
You can find out the ids of your lights by executing the following command:
```bash
$ curl http://<bridge>/api/<username>/lights
```
Home Assistant will automatically detect your new `LightGroup` and add it to the interface.
<p class='note warning'>
To support Hue Light Groups, your bridge needs to have at least firmware 1.13 (released on June 3, 2016).
</p>
More information can be found on the [Philips Hue API documentation](https://www.developers.meethue.com/documentation/groups-api#22_create_group) website.
### {% 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.
This will have all the bulbs transitioned at once, instead of one at a time using standard scenes in Home Assistant.
For instance:
```yaml
script:
porch_on:
sequence:
- service: light.hue_activate_scene
data:
group_name: "Porch"
scene_name: "Porch Orange"
```
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `group_name` | no | The group/room name of the lights. Find this in the Hue official app.
| `scene_name` | no | The name of the scene. Find this in the Hue official app.
*Note*: `group_name` is not linked to Home Assistant group name.
*** 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 guaranteed 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 limited 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".
The requirement is that you have setup your [Philips Hue bridge](/components/hue/).

8
source/_components/light.mochad.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Mochad Light"
description: "Instructions how to integrate X10 Mochad switches into Home Assistant."
description: "Instructions how to integrate X10 Mochad lights into Home Assistant."
date: 2017-07-14 11:29
sidebar: true
comments: false
@ -11,7 +11,7 @@ ha_category: Light
ha_release: 0.51
---
The `mochad` switch platform lets you control an X10 enabled dimmer/light
The `mochad` light platform lets you control an X10 enabled dimmer/light
device.
To enable this sensor, you first have to set up the [mochad component](/components/mochad/) and then add the following to your `configuration.yaml` file:
@ -28,5 +28,7 @@ light:
Configuration variables:
- **address** (*Required*): The X10 address of the light.
- **name** (*Optional*): The name of the switch. Default is: x10_light_dev_*address*.
- **name** (*Optional*): The name of the light. Default is: x10_light_dev_*address*.
- **comm_type** (*Optional*): pl (powerline) or rf (radio frequency). Default is pl.
- **brightness_levels** (*Optional*): The number of brightness levels the X10 light device supports. This can either be 32, 64, or 256 (note that the max
value sent to the device will be n-1 because it starts at 0)

2
source/_components/light.mqtt.markdown
View file

@ -53,7 +53,7 @@ Configuration variables:
- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates.
- **rgb_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value.
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value.
- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value. The template should match the payload "on" and "off" values, so if your light uses "power on" to turn on, your `state_value_template` string should return "power on" when the switch is on. For example if the message is just "on", your `state_value_template` should be `power {{ value }}`.
- **white_value_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's white value.
- **white_value_state_topic** (*Optional*): The MQTT topic subscribed to receive white value updates.
- **white_value_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value.

2
source/_components/light.template.markdown
View file

@ -42,7 +42,7 @@ light:
{% endraw %}
{% configuration %}
switches:
lights:
description: List of your lights.
required: true
type: map

2
source/_components/light.yeelight.markdown
View file

@ -47,7 +47,7 @@ Per default the bulb limits the amount of requests per minute to 60, a limitatio
### {% linkable_title Initial setup %}
<p class='note'>
Before trying to control your light through Home Assistant, you have to setup your bulb using Yeelight app. ( [Android](https://play.google.com/store/apps/details?id=com.yeelight.cherry&hl=fr), [IOS](https://itunes.apple.com/us/app/yeelight/id977125608?mt=8) ).
In the bulb property, you have to enable "Developer Mode" Developer mode may only be available with the latest firmware installed on your bulb. Firmware can be updated in the application after connecting the bulb.
In the bulb property, you have to enable "LAN Mode" (previously called "Developer mode"). LAN mode may only be available with the latest firmware installed on your bulb. Firmware can be updated in the application after connecting the bulb.
Determine your bulb IP (using router, software, ping ...)
</p>

12
source/_components/logentries.markdown
View file

@ -11,7 +11,9 @@ footer: true
ha_category: "History"
---
The `logentries` component makes it possible to log all state changes to [your Logentries account](http://logentries.com/) using Logentries Webhook endpoint and a token based log
The `logentries` component makes it possible to log all state changes to [Logentries](http://logentries.com/) using Logentries Webhook endpoint.
Open the **Add a Log** page and choose **Manual**. Enter a name for your log in **Log Name**, add a group in **Select Log Set**, set **Token TCP - logs are identified by a token.** and press **Create Log Token**. The generated token is required for the Home Assistant configuration.
To use the `logentries` component in your installation, add the following to your `configuration.yaml` file:
@ -21,6 +23,10 @@ logentries:
token: TOKEN
```
Configuration variables:
{% configuration %}
token:
description: The token for the log to use.
required: true
type: string
{% endconfiguration %}
- **token** (*Required*): Your Logentries log token.

2
source/_components/maxcube.markdown
View file

@ -30,7 +30,7 @@ A `maxcube` section must be present in the `configuration.yaml` file and contain
```yaml
# Example configuration.yaml entry
maxcube:
host: 192.168.0.20
host: 192.168.0.20
```
Configuration variables:
- **host** (*Required*): The IP address of the eQ-3 MAX! Cube to use.

1
source/_components/media_player.aquostv.markdown
View file

@ -53,5 +53,6 @@ Currently known supported models:
- LC-60LE925UN
- LC-60LE857U
- LC-60EQ10U
- LC-60SQ15U
If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.aquostv.markdown).

1
source/_components/media_player.denonavr.markdown
View file

@ -18,6 +18,7 @@ The `denonavr` platform allows you to control a [Denon Network Receivers](http:/
Supported devices:
- Denon AVR-X1300W
- Denon AVR-X2000
- Denon AVR-X2100W
- Denon AVR-X4100W

3
source/_components/media_player.samsungtv.markdown
View file

@ -55,6 +55,7 @@ Currently known supported models:
- U6300 (port must be set to 8001, and `pip3 install websocket-client` must be executed)
- K6500AF (port must be set to 8001)
- KS8005 (port must be set to 8001, and `pip3 install websocket-client` must be executed)
- MU6170UXZG (port must be set to 8001, and `pip3 install websocket-client` must be executed)
- KS7502 (port must be set to 8001, and `pip3 install websocket-client` must be executed, turn on doesn't work, turn off works fine)
- K5600AK (partially supported, turn on works but state is not updated)
- UE65KS8005 (port must be set to 8001, On/Off, Forward/Backward, Volume are OK, but no Play button)
@ -66,7 +67,7 @@ Currently tested but not working models:
- JU7500 - Unable to see state and unable to control
- JS9000 - State is always "on" and unable to control (but port 8001 *is* open)
- JS9500 - State is always "on" and unable to control (but port 8001 *is* open)
- MU6170UXZG (port set to 8001, `pip3 install websocket-client` must be executed, turning on works, status not working reliably, turning off is not permanent (it comes back on).)
- MU6300 - Port set to 8001, `pip3 install websocket-client` must be executed, turning on works, status not working reliably, turning off is not permanent (it comes back on)
If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.samsungtv.markdown).
The first letter (U, P, L, H & K) represent the screen type, e.g. LED or Plasma. The second letter represents the region, E is Europe, N is North America and A is Asia & Australia. The two numbers following that represent the screen size.

14
source/_components/media_player.sonos.markdown
View file

@ -109,7 +109,7 @@ Clear the sleep timer on a speaker, if one is set.
### {% linkable_title Service `sonos_update_alarm` %}
Update an existing sonos alarm.
Update an existing Sonos alarm.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
@ -119,3 +119,15 @@ Update an existing sonos alarm.
| `volume` | yes | Float for volume level.
| `enabled` | yes | Boolean for whether or not to enable this alarm.
| `include_linked_zones` | yes | Boolean that defines if the alarm also plays on grouped players.
### {% linkable_title Service `sonos_set_option` %}
Set Sonos speaker options.
Night Sound and Speech Enhancement modes are only supported on Sonos PLAYBAR and PLAYBASE speakers when playing from the TV source. Other speaker types will ignore these options.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of `entity_id`s that will have their options set.
| `night_sound` | yes | Boolean to control Night Sound mode.
| `speech_enhance` | yes | Boolean to control Speech Enhancement mode.

38
source/_components/media_player.ue_smart_radio.markdown Normal file
View file

@ -0,0 +1,38 @@
---
layout: page
title: "Logitech UE Smart Radio"
description: "Instructions on how to integrate a Logitech UE Smart Radio player into Home Assistant."
date: 2017-12-09 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: ueradio.png
ha_category: Media Player
ha_release: "0.60"
ha_iot_class: "Cloud Polling"
---
The `ue_radio` platform allows you to control a [Logitech UE Smart Radio](https://www.uesmartradio.com) from Home Assistant. This lets you control both Logitech UE Smart Radios and Logitech Squeezebox Radios that have been updated with the UE Smart Radio update.
To add your UE Smart Radio player to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: ue_smart_radio
username: USERNAME
password: PASSWORD
```
{% configuration %}
username:
description: The email you use to log in to `uesmartradio.com`.
required: true
type: string
password:
description: The password you use to log in to `uesmartradio.com`.
required: true
type: string
{% endconfiguration %}

65
source/_components/media_player.universal.markdown
View file

@ -14,7 +14,7 @@ featured: false
Universal Media Players combine multiple existing entities in Home Assistant into one media player entity. This is used for creating a single entity that controls an entire media center.
Multiple Media Player entities can be controlled from a Universal Media Player. Additionally, the Universal Media Player allows volume and power commands to be re-routed to other entities in Home Assistant. This allows the power and volume to control external devices like a television or audio receiver.
Multiple media player entities can be controlled from an universal media player. Additionally, the universal media player allows volume and power commands to be re-routed to other entities in Home Assistant. This allows the power and volume to control external devices like a television or audio receiver.
A Universal Media Player is created in `configuration.yaml` as follows.
@ -47,31 +47,46 @@ media_player:
state: ENTITY_ID|ATTRIBUTE
```
Configuration variables:
{% configuration %}
name:
description: The name to assign the player.
required: true
type: string
children:
description: Ordered list of child media players this entity will control.
required: true
type: list
state_template:
description: "A [template](/topics/templating/) can be specified to render the state of the media player. This way, the state could depend on entities different from media players, like switches or input booleans."
required: false
type: template
commands:
description: "Commands to be overwritten. Possible entries are `turn_on`, `turn_off`, `select_source`, `volume_set`, `volume_up`, `volume_down` and `volume_mute`."
required: false
type: string
attributes:
description: "Attributes that can be overwritten. Possible entries are `is_volume_muted`, `state`, `source`, `source_list` and `volume_level`. The values should be an entity ID and state attribute separated by a pipe character (|). If the entity ID's state should be used, then only the entity id should be provided."
required: false
type: string
{% endconfiguration %}
- **name** (*Required*): The name to assign the player
- **children** (*Required*): Ordered list of child media players this entity will control
- **state_template** (*Optional*): A [template](/topics/templating/) can be specified to render the state of the media player. This way, the state could depend on entities different from media players, like Switches or Input Booleans.
- **commands** (*Optional*): Commands to be overwritten. Possible entries are *turn_on*, *turn_off*, *select_source*, *volume_set*, *volume_up*, *volume_down*, and *volume_mute*.
- **attributes** (*Optional*): Attributes that can be overwritten. Possible entries are *is_volume_muted*, *state*, *source*, *source_list, and *volume_level*. The values should be an entity id and state attribute separated by a bar (\|). If the entity id's state should be used, then only the entity id should be provided.
The Universal Media Player will primarily imitate one of its `children`. The Universal Media Player will control the first child on the list that is active (not idle/off). The Universal Media Player will also inherit its state from the first active child if a `state_template` is not provided. Entities in the `children:` list must be media players, but the state template can contain any entity.
The Universal Media Player will primarily imitate one of its *children*. The Universal Media Player will control the first child on the list that is active (not idle/off). The Universal Media Player will also inherit its state from the first active child if a `state_template` is not provided. Entities in the *children* list must be media players, but the state template can contain any entity.
It is recommended that the command `turn_on`, the command `turn_off`, and the attribute `state` all be provided together. The `state` attribute indicates if the media player is on or off. If `state` indicates the media player is off, this status will take precedence over the states of the children. If all the children are idle/off and `state` is on, the Universal Media Player's state will be on.
It is recommended that the command *turn_on*, the command *turn_off*, and the attribute *state* all be provided together. The *state* attribute indicates if the Media Player is on or off. If *state* indicates the media player is off, this status will take precedence over the states of the children. If all the children are idle/off and *state* is on, the Universal Media Player's state will be on.
It is also recommended that the command `volume_up`, the command `volume_down`, the command `volume_mute`, and the attribute `is_volume_muted` all be provided together. The attribute `is_volume_muted` should return either True or the on state when the volume is muted. The `volume_mute` service should toggle the mute setting.
It is also recommended that the command *volume_up*, the command *volume_down*, the command *volume_mute*, and the attribute *is_volume_muted* all be provided together. The attribute *is_volume_muted* should return either True or the on state when the volume is muted. The *volume_mute* service should toggle the mute setting.
When providing *select_source* as a command, it is recommended to also provide the attributes *source*, and *source_list*. The *source* attribute is the currently select source, while the *source_list* attribute is a list of all available sources.
When providing `select_source` as a command, it is recommended to also provide the attributes `source`, and `source_list`. The `source` attribute is the currently select source, while the `source_list` attribute is a list of all available sources.
## {% linkable_title Usage examples %}
#### {% linkable_title Chromecast & Kodi control with switches %}
In this example, a switch is available to control the power of the television. Switches are also available to turn the volume up, turn the volume down, and mute the audio. These could be command line switches or any other entity in Home Assistant. The *turn_on* and *turn_off* commands will be redirected to the television, and the volume commands will be redirected to an audio receiver. The *select_source* command will be passed directly to an A/V receiver.
The children are a Chromecast and a Kodi player. If the Chromecast is playing, the Universal Media Player will reflect its status. If the Chromecast is idle and Kodi is playing, the Universal Media player will change to reflect its status.
In this example, a switch is available to control the power of the television. Switches are also available to turn the volume up, turn the volume down, and mute the audio. These could be command line switches or any other entity in Home Assistant. The `turn_on` and `turn_off` commands will be redirected to the television, and the volume commands will be redirected to an audio receiver. The `select_source` command will be passed directly to an A/V receiver.
The children are a Chromecast and a Kodi player. If the Chromecast is playing, the Universal Media Player will reflect its status. If the Chromecast is idle and Kodi is playing, the universal media player will change to reflect its status.
{% raw %}
```yaml
media_player:
platform: universal
@ -104,12 +119,12 @@ media_player:
service: media_player.select_source
data_template:
entity_id: media_player.receiver
source: '{% raw %}{{ source }}{% endraw %}'
source: '{{ source }}'
volume_set:
service: media_player.volume_set
data_template:
entity_id: media_player.receiver
volume_level: '{% raw %}{{ volume_level }}{% endraw %}'
volume_level: '{{ volume_level }}'
attributes:
state: switch.living_room_tv
@ -117,21 +132,22 @@ media_player:
volume_level: media_player.receiver|volume_level
source: media_player.receiver|source
source_list: media_player.receiver|source_list
```
{% endraw %}
#### {% linkable_title Kodi CEC-TV control %}
In this example, a [Kodi Media Player](/components/media_player.kodi/) runs in a CEC capable device (OSMC/OpenElec running in a Raspberry Pi 24/7, for example), and, with the JSON-CEC Kodi addon installed, it can turn on and off the attached TV.
We store the state of the attached TV in a hidden [Input Boolean](/components/input_boolean/), so we can differentiate the TV being on or off, while Kodi is always 'idle', and use the Universal Media Player to render its state with a template. We can hide the Kodi Media Player too, and only show the universal one, which now can differentiate between the 'idle' and the 'off' state (being the second when it is idle and the TV is off).
We store the state of the attached TV in a hidden [input boolean](/components/input_boolean/), so we can differentiate the TV being on or off, while Kodi is always 'idle', and use the universal media player to render its state with a template. We can hide the Kodi Media Player too, and only show the universal one, which now can differentiate between the 'idle' and the 'off' state (being the second when it is idle and the TV is off).
Because the Input Boolean used to store the TV state is only changing when using the Home Assistant `turn_on` and `turn_off` actions, and Kodi could be controlled by so many ways, we also define some automations to update this Input Boolean when needed.
Because the input boolean used to store the TV state is only changing when using the Home Assistant `turn_on` and `turn_off` actions, and Kodi could be controlled by so many ways, we also define some automations to update this Input Boolean when needed.
In an Apple HomeKit scene, we can now expose this Universal Media Player as an on/off switch in Homebridge, and, that way, use Siri to turn on and off the TV.
In an Apple HomeKit scene, we can now expose this universal media player as an on/off switch in Homebridge, and, that way, use Siri to turn on and off the TV.
The complete yaml config is:
The complete configuration is:
{% raw %}
```yaml
homeassistant:
customize:
@ -153,11 +169,11 @@ media_player:
- platform: universal
name: Kodi TV
state_template: >
{% raw %}{% if (is_state('media_player.kodi', 'idle') and (is_state('input_boolean.kodi_tv_state', 'off') %}
{% if is_state('media_player.kodi', 'idle') and is_state('input_boolean.kodi_tv_state', 'off') %}
off
{% else %}
{{ states('media_player.kodi') }}
{% endif %}{% endraw %}
{% endif %}
children:
- media_player.kodi
commands:
@ -224,3 +240,4 @@ automation:
- service: media_player.turn_off
entity_id: media_player.kodi_tv
```
{% endraw %}

43
source/_components/media_player.ziggo_mediabox_xl.markdown Normal file
View file

@ -0,0 +1,43 @@
---
layout: page
title: "Ziggo Mediabox XL"
description: "Instructions how to integrate the Ziggo Mediabox XL into Home Assistant."
date: 2017-11-10 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: ziggo.png
ha_category: Media Player
ha_iot_class: "Local Polling"
ha_release: "0.60"
---
The `ziggo_mediabox_xl` component allows you to control a [Ziggo](https://www.ziggo.nl/) Mediabox XL from Home Assistant.
To add a Ziggo Mediabox XL to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: ziggo_mediabox_xl
host: 192.168.0.123
name: Ziggo Mediabox
```
{% configuration %}
host:
description: The hostname or address of the device.
required: true
type: string
name:
description: The name of the device used in the frontend.
required: false
type: string
{% endconfiguration %}
The channel information (numbers and names) are downloaded from ziggo.nl on startup.
#### {% linkable_title Preparation of the Mediabox %}
Makes sure to enable the Home Network ("mijn thuisnetwerk") service in the settings menu of the media box. Once you have set up the Media Library ("mediabiblotheek"), we can determine whether the device is turned on or off. Without this, the component will fail to start.

9
source/_components/neato.markdown
View file

@ -28,6 +28,13 @@ Configuration variables:
- **username** (*Required*): Username for the Neato account.
- **password** (*Required*): Password for the Neato account.
The Home Assistant Neato platform has not been tested with all models of Botvac.
| BotVac Model | Tested |
| --- | --- |
| Botvac Connected | SUCCESS |
| Botvac D7 Connected | SUCCESS |
<p class='note'>
The Home Assistant Neato platform has only be tested with a Botvac Connected. There is no support for the Botvac D3 Connected and Botvac D5 Connected robots at this time.
There is no support for the Botvac D3 Connected and Botvac D5 Connected robots at this time.
</p>

2
source/_components/nest.markdown
View file

@ -34,7 +34,7 @@ The Nest component is the main component to integrate all [Nest](https://nest.co
9. Once the new product page opens the "Product ID" and "Product Secret" are located on the right side. These will be used as `client_id` and `client_secret` below.
10. Once Home Assistant is started, a configurator will pop up asking you to log into your Nest account and copy a PIN code into Home Assistant.
Connecting to the Nest Developer API requires outbound port 8553 on your firewall. The configuration will fail if this is not accessible.
Connecting to the Nest Developer API requires outbound port 9553 on your firewall. The configuration will fail if this is not accessible.
### {% linkable_title Configuration %}

3
source/_components/netatmo.markdown
View file

@ -55,6 +55,3 @@ That's it. You can copy and paste your new `client id` and `client secret` in yo
<img src='/images/screenshots/netatmo_api.png' />
</p>
<p class='note'>
The Home Assistant Netatmo platform has only be tested with the classic indoor, outdoor module and rain meter. There is no support for the wind meter module at this time because developers does not own these modules.
</p>

4
source/_components/notify.html5.markdown
View file

@ -21,14 +21,14 @@ To enable this platform, add the following lines to your `configuration.yaml` fi
notify:
- name: NOTIFIER_NAME
platform: html5
gcm_api_key: 'gcm-sender-key'
gcm_api_key: 'gcm-server-key'
gcm_sender_id: 'gcm-sender-id'
```
Configuration variables:
- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
- **gcm_api_key** (*Required if pushing to Chrome*): The API key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.
- **gcm_api_key** (*Required if pushing to Chrome*): The API Server key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.
- **gcm_sender_id** (*Required if pushing to Chrome*): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.
### {% linkable_title Getting ready for Chrome %}

70
source/_components/notify.lametric.markdown
View file

@ -12,17 +12,71 @@ ha_category: Notifications
ha_release: 0.49
---
This component allows to send notification to a LaMetric device. It need the LaMetric platform to be configured first.
The `lametric` notification platform allows to send notification to a LaMetric device. It needs the LaMetric platform to be configured first.
To enable LaMetric notifications in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
name: lametric1
name: NOTIFIER_NAME
platform: lametric
display_time: 20
icon: i555
```
- **name** (*Optional*): The name of the LaMetric device. Usually it is "My Lametric"
- **display_time** (*Optional*): Defines how long the message should be displayed (in seconds).
- **icon** (*Optional*): An icon or animation. Check out the list of all icons her: https://developer.lametric.com/icons
Note that icons always begin with "i" while animations begin with "a". This is part of the name, you can't just use the number.
{% configuration %}
name:
description: "The optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`."
required: false
type: string
default: notify
lifetime:
description: Defines how long the message remains in LaMetric notification queue (in seconds).
required: false
type: int
default: 10
icon:
description: An icon or animation.
required: false
type: string
cycles:
description: Defines how often the notification is displayed.
required: false
type: int
default: 1
{% endconfiguration %}
Check out the list of all icons at [https://developer.lametric.com/icons](https://developer.lametric.com/icons). Note that icons always begin with "i" while animations begin with "a". This is part of the name, you can't just use the number!
## {% linkable_title Examples %}
### {% linkable_title Full configuration example %}
```yaml
# Example configuration.yaml entry
notify:
name: NOTIFIER_NAME
platform: lametric
lifetime: 20
icon: a7956
cycles: 3
```
### {% linkable_title Changing sounds and icons %}
To add a notification sound or an icon override, it has to be done via service data.
```yaml
- alias: "Send notification on arrival at school"
trigger:
platform: state
entity_id: device_tracker.son_mobile
from: 'not_home'
to: 'school'
action:
service: notify.lametric
data:
message: "Son has arrived at school!"
data:
sound: 'notification'
icon: 'i51'
```

8
source/_components/notify.nfandroidtv.markdown
View file

@ -14,9 +14,11 @@ ha_iot_class: "Local Polling"
---
Notification platform for [Notifications for Android TV](https://play.google.com/store/apps/details?id=de.cyberdream.androidtv.notifications.google&hl=en) and [Notifications for FireTV](https://play.google.com/store/apps/details?id=de.cyberdream.firenotifications.google).
Notification platform for [Notifications for Android TV](https://play.google.com/store/apps/details?id=de.cyberdream.androidtv.notifications.google) and [Notifications for FireTV](https://play.google.com/store/apps/details?id=de.cyberdream.firenotifications.google).
The notifications are in the global scope of your Android TV device. They will be displayed regardless of which application is running.
The In-App purchases only apply to the client for Android smartphones, so there isn't any limit when pushing notifications from Home Assistant.
When setting this up be aware, that there are two apps: one for your smartphone to send notifications (not required for this platform) and one for your Android TV device to receive the notifications. The app available in the store of your target device is the one that is needed to display notifications sent from Home Assistant. The In-App purchases only apply to the client for Android smartphones, so there isn't any limit when pushing notifications from Home Assistant.
To enable the notification platform, add the following to your `configuration.yaml` file:
@ -50,7 +52,7 @@ This is a fully customized JSON you can use to test how the final notification w
"duration":2,
"transparency":"0%",
"color": "red",
"interrupt": 1
"interrupt": 1,
}
}
```

2
source/_components/notify.slack.markdown
View file

@ -42,7 +42,7 @@ Configuration variables:
### {% linkable_title Slack service data %}
The following attributes can be placed `data` for extended functionality.
The following attributes can be placed inside `data` for extended functionality.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |

7
source/_components/plant.markdown
View file

@ -51,16 +51,18 @@ Configuration variables:
## {% linkable_title Examples %}
### Using plain MQTT sensor to get the data
This is a practical example that uses a multiple of `MQTT sensors` to supply the readings used by the `plant` sensor.
Another good source of this data would be the [Mi Flora](https://home-assistant.io/components/sensor.miflora/) component.
Another good source of this data would be the [Mi Flora](/components/sensor.miflora/) component.
If the sensor data is within the min/max values the status will be `ok`, if not the status will be `problem`. You can use this to trigger a notification, if there is a problem with your plant. Of course you can only monitor attributes of your plant, where the sensor is configured and is providing the data.
## Data Source
The main sources of the data will usually be a [MiFlora sensor](sensor.miflora) or a [MQTT sensor](sensor.mqtt) receiving the data from a [PlantGateway](https://github.com/ChristianKuehnel/plantgateway).
The main sources of the data will usually be a [MiFlora sensor](/components/sensor.miflora/) or a [MQTT sensor](/components/sensor.miflora/) receiving the data from a [PlantGateway](https://github.com/ChristianKuehnel/plantgateway).
If you want to get the date via a PlantGateway, this is a typical configuration for the MQTT sensors:
{% raw %}
```yaml
# Example configuration.yaml entry
plant:
@ -99,5 +101,6 @@ sensor:
state_topic: my_plant_topic
value_template: '{{ value_json.brightness }}'
```
{% endraw %}
You have to replace the `state_topic` with the value that you configured in the PlantGateway. It also depends on the global configuration of your MQTT server.

2
source/_components/recorder.markdown
View file

@ -119,7 +119,7 @@ action:
Not all Python bindings for the chosen database engine can be installed directly. This section contains additional details which should help you to get it working.
### {% linkable_title MariDB and MySQL %}
### {% linkable_title MariaDB and MySQL %}
For MariaDB you may have to install a few dependencies. On the Python side we use the `mysqlclient`:

2
source/_components/rss_feed_template.markdown
View file

@ -17,7 +17,7 @@ The `rss_feed_template` component can export any information from Home Assistant
For example, on Android, the app "Simple RSS Widget" can be used to display temperatures on the home screen.
```yaml
# Example configuration.yml entry
# Example configuration.yaml entry
rss_feed_template:
# Accessible on <home assistant url>/api/rss_template/garden
# Example: https://localhost:8123/api/rss_template/garden

2
source/_components/satel_integra.markdown
View file

@ -13,7 +13,7 @@ ha_release: 0.54
ha_iot_class: "Local Push"
---
The `satel_integra` component will allow Home Assistant users who own a Satel Integra alarm panel to leverage their alarm system and its sensors to provide Home Assistant with information about their homes. Connectivity between Home Assistant and the alarm is accomplished through a ETHM extension module that must be installed in the alarm.
The `satel_integra` component will allow Home Assistant users who own a Satel Integra alarm panel to leverage their alarm system and its sensors to provide Home Assistant with information about their homes. Connectivity between Home Assistant and the alarm is accomplished through a ETHM extension module that must be installed in the alarm. Compatible with ETHM-1 Plus module with firmware version > 2.00 (version 2.04 confirmed).
There is currently support for the following device types within Home Assistant:

21
source/_components/scene.vera.markdown Normal file
View file

@ -0,0 +1,21 @@
---
layout: page
title: "Vera Scene"
description: "Instructions on how to integrate Vera Scenes into Home Assistant."
date: 2017-11-20 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: vera.png
ha_category: Scene
ha_iot_class: "Local Push"
ha_release: "0.60"
---
The `vera` platform allows you to control your [Vera](http://getvera.com/) scenes from within Home Assistant.
They will be automatically discovered if the `vera` component is loaded.
For more configuration information see the [Vera component](/components/vera/) documentation.

51
source/_components/sensor.ads.markdown Normal file
View file

@ -0,0 +1,51 @@
---
layout: page
title: "ADS Sensor"
description: "Instructions how to integrate ADS numeric values into Home Assistant."
date: 2017-10-25 10:00
sidebar: true
comments: false
sharing: true
footer: true
logo: beckhoff.png
ha_category: Sensor
ha_release: "0.60"
ha_iot_class: "Local Push"
---
The `ads` sensor platform allows reading the value of a numeric variable on your ADS device. The variable can be of type *INT*, *UINT* or *BYTE*.
To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: ads
adsvar: GVL.temperature
unit_of_measurement: '°C'
adstype: int
```
{% configuration %}
adsvar:
required: true
description: The name of the variable which you want to access.
type: string
adstype:
required: false
description: The datatype of the ADS variable, possible values are int, uint, byte.
default: int
type: string
name:
required: false
description: An identifier for the sensor.
type: string
factor:
required: false
description: A factor that divides the stored value before displaying in Home Assistant.
default: 1
type: integer
{% endconfiguration %}
The *factor* can be used to implement fixed decimals. E.g., set *factor* to 100 if you want to display a fixed decimal value with two decimals. A variable value of `123` will be displayed as `1.23`.

53
source/_components/sensor.alpha_vantage.markdown Normal file
View file

@ -0,0 +1,53 @@
---
layout: page
title: "Alpha Vantage"
description: "Instructions how to setup Alpha Vantage within Home Assistant."
date: 2017-12-02 12:00
sidebar: true
comments: false
sharing: true
footer: true
logo: alpha_vantage.png
ha_category: Finance
ha_iot_class: "Cloud Polling"
featured: false
ha_release: "0.60"
---
The `alpha_vantage` sensor platform uses [Alpha Vantage](https://www.alphavantage.co) to monitor the stock market.
To enable the `alpha_vantage` platform, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: alpha_vantage
api_key: YOUR_API_KEY
```
{% configuration %}
api_key:
description: "The API Key from [Alpha Vantage](https://www.alphavantage.co)."
required: true
type: string
symbols:
description: List of stock market symbols for given companies.
required: false
type: string, list
default: GOOGL
{% endconfiguration %}
## {% linkable_title Examples %}
In this section you find some real life examples of how to use this sensor.
### {% linkable_title Red Hat and Google %}
```yaml
sensor:
- platform: alpha_vantage
symbols:
- RHT
- GOOGL
```

24
source/_components/sensor.canary.markdown Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: "Canary Sensor"
description: "Instructions on how to integrate your Canary devices into Home Assistant."
date: 2017-12-07 22:00
sidebar: true
comments: false
sharing: true
footer: true
logo: canary.png
ha_category: Sensor
ha_release: "0.60"
ha_iot_class: "Cloud Polling"
---
The `canary` sensor platform allows you to integrate the sensors of your [Canary](https://canary.is) devices in Home Assistant.
To add `canary` sensors to your installation, follow instructions in [Canary component](/components/canary/).
Once loaded, you will see following sensors:
* A sensor per camera that reports temperature.
* A sensor per camera that reports humidity.
* A sensor per camera that reports air quality.

4
source/_components/sensor.coinmarketcap.markdown
View file

@ -28,12 +28,12 @@ sensor:
currency:
description: The cryptocurrency to use.
required: false
type: string, list
type: string
default: Bitcoin
display_currency:
description: The currency to display.
required: false
type: string, list
type: string
default: USD
{% endconfiguration %}

5
source/_components/sensor.dsmr.markdown
View file

@ -107,6 +107,11 @@ Optional configuration example for ser2net:
# Example /etc/ser2net.conf for proxying USB/serial connections to DSMRv4 smart meters
2001:raw:600:/dev/ttyUSB0:115200 NONE 1STOPBIT 8DATABITS XONXOFF LOCAL -RTSCTS
```
or
```sh
# Example /etc/ser2net.conf for proxying USB/serial connections to DSMRv2.2 smart meters
2001:raw:600:/dev/ttyUSB0:9600 EVEN 1STOPBIT 7DATABITS XONXOFF LOCAL -RTSCTS
```
[HASSbian](/getting-started/installation-raspberry-pi-image/) users have to give dialout permission to the user `homeassistant`:

2
source/_components/sensor.eliqonline.markdown
View file

@ -28,7 +28,7 @@ sensor:
Configuration variables:
- **access_token** (*Required*): The Access Token for your account.
- **channel_id** (*Optional*): Channel ID (as integer) of your device. Needed if you have more than one device.
- **channel_id** (*Required*): Channel ID (as integer) of your device.
- **name** (*Optional*): The name of the sensor, eg. the city.
For details please check the [API documentation](https://my.eliq.se/knowledge/sv-SE/49-eliq-online/299-eliq-online-api).

51
source/_components/sensor.fail2ban.markdown
View file

@ -14,10 +14,10 @@ ha_release: 0.57
---
The `fail2ban` sensor allows for IPs banned by [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page) to be displayed in the Home Assistant front-end.
The `fail2ban` sensor allows for IPs banned by [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page) to be displayed in the Home Assistant frontend.
<p class='note'>
Your system must have fail2ban installed and correctly configured for this sensor to work. In addition, Home Assistant must be able to read the fail2ban log file.
Your system must have `fail2ban` installed and correctly configured for this sensor to work. In addition, Home Assistant must be able to read the `fail2ban` log file.
</p>
To enable this sensor, add the following lines to your `configuration.yaml`:
@ -29,29 +29,38 @@ sensor:
jails:
- ssh
- hass-iptables
file_path: /var/log/fail2ban.log
```
Configuration variables:
- **jails** (*Required*): List of configured jails you want to display (each jail is its own sensor).
- **name** (*Optional*): Name of the sensor. Defaults to `fail2ban`.
- **file_path** (*Optional*): Path to the fail2ban log. Defaults to `/var/log/fail2ban.log`.
- **scan_interval** (*Optional*): Used to limit how often log file is read and must be a positive integer (representing number of seconds to wait). Defaults to 120.
{% configuration %}
jails:
description: List of configured jails you want to display.
required: true
type: list
name:
description: Name of the sensor.
required: false
type: string
default: fail2ban
file_path:
description: Path to the fail2ban log.
required: false
type: string
default: /var/log/fail2ban.log
{% endconfiguration %}
### {% linkable_title Set up Fail2Ban %}
For most set-ups, you can follow [this tutorial](https://home-assistant.io/cookbook/fail2ban/) to set up fail2ban on your system. It will walk you through creating jails and filters, allowing you to monitor IPs that have been banned for too many failed ssh login attempts, as well as too many failed Home Assistant log in attempts.
For most setups, you can follow [this tutorial](/cookbook/fail2ban/) to set up `fail2ban` on your system. It will walk you through creating jails and filters, allowing you to monitor IP addresses that have been banned for too many failed SSH login attempts, as well as too many failed Home Assistant login attempts.
### {% linkable_title Fail2Ban with Docker %}
<p class='note'>
These steps assume you already have the Home Assistant docker running behind nginx and that it is externally accessible. It also assumes the docker is running with the `--net='host'` flag.
These steps assume you already have the Home Assistant docker running behind NGINX and that it is externally accessible. It also assumes the docker is running with the `--net='host'` flag.
</p>
For those of us using Docker, the above tutorial may not be sufficient. The following steps specifically outline how to set up `fail2ban` and Home Assistant when running Home Assistant within a Docker behind nginx. The setup this was tested on was an unRAID server using the [let's encrypt docker](https://github.com/linuxserver/docker-letsencrypt) from linuxserver.io.
For those of us using Docker, the above tutorial may not be sufficient. The following steps specifically outline how to set up `fail2ban` and Home Assistant when running Home Assistant within a Docker behind NGINX. The setup this was tested on was an unRAID server using the [let's encrypt docker](https://github.com/linuxserver/docker-letsencrypt) from linuxserver.io.
#### Set http logger
#### {% linkable_title Set http logger %}
In your `configuration.yaml` file, add the following to the `logger` component to ensure that Home Assistant prints failed login attempts to the log.
@ -61,7 +70,7 @@ logger:
homeassistant.components.http.ban: warning
```
#### Edit the `jail.local` file
#### {% linkable_title Edit the `jail.local` file %}
Next, we need to edit the `jail.local` file that is included with the Let's Encrypt docker linked above. Note, for this tutorial, we'll only be implementing the `[hass-iptables]` jail from the [previously linked tutorial](https://home-assistant.io/cookbook/fail2ban/).
@ -76,7 +85,7 @@ logpath = /hass/home-assistant.log
maxretry = 5
```
#### Create a filter for the Home Assistant jail
#### {% linkable_title Create a filter for the Home Assistant jail %}
Now we need to create a filter for `fail2ban` so that it can properly parse the log. This is done with a `failregex`. Create a file called `hass.local` within the `filter.d` directory in `/mnt/user/appdata/letsencrypt/fail2ban` and add the following:
@ -93,7 +102,7 @@ ignoreregex =
datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S
```
#### Map log file directories
#### {% linkable_title Map log file directories %}
First, we need to make sure that fail2ban log can be passed to Home Assistant and that the Home Assistant log can be passed to fail2ban. When starting the Let's Encrypt docker, you need to add the following argument (adjust paths based on your setup):
@ -110,20 +119,20 @@ Now do the same for the Home Assistant docker, but this time we'll be mapping th
```
#### Send client IP to Home Assistant
#### {% linkable_title Send client IP to Home Assistant %}
By default, the IP address that Home Assistant sees will be that of the container (something like `172.17.0.16`). What this means is that for any failed login attempt, assuming you have correctly configured `fail2ban`, the Docker IP will be logged as banned, but the originating IP is still allowed to make attempts. We need `fail2ban` to recognize the originating IP to properly ban it.
First, we have to add the following to the nginx configuration file located in `/mnt/user/appdata/letsencrypt/nginx/site-confs/default`.
```
```bash
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```
This snippet should be added within your Home Assistant server config, so you have something like the following:
```
```bash
server {
...
location / {
@ -158,7 +167,7 @@ http:
At this point, once the Let's Encrypt and Home Assistant dockers are restarted, Home Assistant should be correctly logging the originating IP of any failed login attempt. Once that's done and verified, we can move onto the final step.
#### Add the fail2ban sensor
#### {% linkable_title Add the fail2ban sensor %}
Now that we've correctly set everything up for Docker, we can add our sensors to `configuration.yaml` with the following:
@ -174,7 +183,7 @@ Assuming you've followed all of the steps, you should have one fail2ban sensor,
### {% linkable_title Other debug tips %}
If, after following these steps, you're unable to get the fail2ban sensor working, here are some other steps you can take that may help:
If, after following these steps, you're unable to get the `fail2ban` sensor working, here are some other steps you can take that may help:
- Add `logencoding = utf-8` to the `[hass-iptables]` entry
- Ensure the `failregex` you added to `filter.d/hass.local` matches the output within `home-assistant.log`

72
source/_components/sensor.gearbest.markdown Normal file
View file

@ -0,0 +1,72 @@
---
layout: page
title: "Gearbest"
description: "Instructions on how to integrate a Gearbest sensor into Home Assistant."
date: 2017-11-13 09:08
sidebar: true
comments: false
sharing: true
footer: true
logo: gearbest.png
ha_category: Sensor
ha_iot_class: "Cloud Polling"
ha_release: "0.60"
---
The `gearbest` sensor will track the price of a product from [Gearbest](https://www.gearbest.com). This information can be used in, e.g., automations to notify you when a price drops. The update interval for every item is currently set to 2 hours.
To enable this sensor, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: gearbest
currency: EUR
items:
- url: https://www.gearbest.com/....
```
{% configuration %}
currency:
description: "The currency in which the products should be tracked. Currently supported: USD, EUR, GBP, AUD, CAD, CHF, HKD, CNY, NZD, JPY, RUB, BRL, CLP, NOK, DKK, SEK, KRW, ILS, COP, MXN, PEN, THB, IDR, UAH, PLN, INR, BGN, HUF, RON, TRY, CZK, HRK, MAD, AED, SAR, ZAR, SGD, MYR, TWD, RSD, NGN - if the currency could not be found in the conversion rate list, USD will be used as default. Either an ID or an URL must be present."
required: true
type: string
items:
description: List of products that should be tracked.
required: true
type: map
keys:
id:
description: The ID of the product.
required: false
type: int
url:
description: The URL of the product.
required: false
type: string
name:
description: The name of the item. If not set, it is parsed from the website.
required: false
type: string
currency:
description: Overwrite the currency for the current item.
required: false
type: string
{% endconfiguration %}
### {% linkable_title Extended example %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: gearbest
currency: EUR
items:
- url: https://www.gearbest.com/3d-printers-3d-printer-kits/pp_779174.html?wid=21
name: Creality CR-10 upgraded
currency: USD
- id: 779174
name: Creality CR-10 upgraded #2
currency: EUR
```

24
source/_components/sensor.hive.markdown Normal file
View file

@ -0,0 +1,24 @@
---
layout: page
title: "Hive Sensor"
description: "Instructions on how to integrate Hive Sensors with Home Assistant."
date: 2017-09-24 21:00
sidebar: true
comments: false
sharing: true
footer: true
logo: hive.png
ha_category: Sensor
ha_release: 0.59
ha_iot_class: "Cloud Polling"
---
The 'hive' sensor component can expose as a sensor the current online status of your Hive Hub.
<p class='note'>
Full configuration details can be found on the main [Hive component](/components/hive/) page.
</p>

21
source/_components/sensor.luftdaten.markdown
View file

@ -45,16 +45,6 @@ sensor:
required: false
default: Luftdaten Sensor
type: string
resource:
description: The URL of the API endpoint. Usually this has not to be changed.
required: false
default: https://api.luftdaten.info/v1/sensor/
type: string
verify_ssl:
description: Verify SSL connection.
required: false
default: true
type: boolean
monitored_conditions:
description: A list of conditions you want to monitor.
required: true
@ -65,8 +55,15 @@ sensor:
P2:
description: Show the particle sensors (particles 2.5 microns and below).
temperature:
description: Display the temperature from a weather sensor.
description: Display the temperature from the sensor.
humidity:
description: Display the humidity from a weather sensor.
description: Display the humidity from the sensor.
pressure:
description: Display the pressure from the sensor.
{% endconfiguration %}
Not all sensors provide all conditions. Also, it's possible that the sensor values are not available all the time. To check what a sensor is publishing use `curl`:
```bash
$ curl https://api.luftdaten.info/v1/sensor/[sensorid]/
```

2
source/_components/sensor.miflora.markdown
View file

@ -13,7 +13,7 @@ ha_release: 0.29
ha_iot_class: "Local Polling"
---
The `miflora` sensor platform allows one to monitor to plants. The [Mi Flora plant sensor](https://www.aliexpress.com/item/Newest-Original-Xiaomi-Flora-Monitor-Digital-Plants-Flowers-Soil-Water-Light-Tester-Sensor-Monitor-for-Aquarium/32685750372.html) is a small Bluetooth Low Energy device that monitors not only the moisture, but also light, temperature and conductivity. As only a single BLE device can be polled at the same time, the library implements locking to make sure this is the case.
The `miflora` sensor platform allows one to monitor to plants. The [Mi Flora plant sensor](https://xiaomi-mi.com/sockets-and-sensors/xiaomi-huahuacaocao-flower-care-smart-monitor/) is a small Bluetooth Low Energy device that monitors not only the moisture, but also light, temperature and conductivity. As only a single BLE device can be polled at the same time, the library implements locking to make sure this is the case.
Start a scan to determine the MAC addresses of the sensor:

42
source/_components/sensor.mqtt.markdown
View file

@ -25,14 +25,40 @@ sensor:
state_topic: "home/bedroom/temperature"
```
Configuration variables:
- **state_topic** (*Required*): The MQTT topic subscribed to receive sensor values.
- **name** (*Optional*): The name of the sensor. Default is 'MQTT Sensor'.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **expire_after** (*Optional*): Defines the number of seconds after the value expires if it's not updated. Default is 0 (=never expire).
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
{% configuration %}
state_topic:
description: The MQTT topic subscribed to receive sensor values.
required: true
type: string
name:
description: Name of the MQTT sensor.
required: false
type: string
default: MQTT Sensor
qos:
description: The maximum QoS level of the state topic.
required: false
type: int
default: 0
unit_of_measurement:
description: Defines the units of measurement of the sensor, if any.
required: false
type: string
expire_after:
description: Defines the number of seconds after the value expires if it's not updated.
required: false
type: int
default: 0
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
reqired: false
type: boolean
default: False
{% endconfiguration %}
## {% linkable_title Examples %}

2
source/_components/sensor.openweathermap.markdown
View file

@ -30,7 +30,7 @@ sensor:
```
{% configuration %}
apk_key:
api_key:
description: Your API key for OpenWeatherMap.
required: true
type: string

138
source/_components/sensor.rest.markdown
View file

@ -36,19 +36,65 @@ sensor:
payload: '{ "device" : "heater" }'
```
Configuration variables:
- **resource** (*Required*): The resource or endpoint that contains the value.
- **method** (*Optional*): The method of the request. Default is `GET`.
- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value.
- **payload** (*Optional*): The payload to send with a POST request. Depends on the service, but usually formed as JSON.
- **name** (*Optional*): Name of the REST sensor.
- **unit_of_measurement** (*Optional*): Defines the unit of measurement of the sensor, if any.
- **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to `True`.
- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`.
- **username** (*Optional*): The username for accessing the REST endpoint.
- **password** (*Optional*): The password for accessing the REST endpoint.
- **headers** (*Optional*): The headers for the requests.
{% configuration %}
resource:
description: The resource or endpoint that contains the value.
required: true
type: string
default: string
method:
description: The method of the request.
required: false
type: string
default: GET
name:
description: Name of the REST sensor.
required: false
type: string
default: REST Sensor
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value."
required: false
type: template
payload:
description: The payload to send with a POST request. Depends on the service, but usually formed as JSON.
required: false
type: string
verify_ssl:
description: Verify the certification of the endpoint.
required: false
type: boolean
default: True
unit_of_measurement:
description: Defines the units of measurement of the sensor, if any.
required: false
type: string
authentication:
description: Type of the HTTP authentication. `basic` or `digest`.
required: false
type: string
username:
description: The username for accessing the REST endpoint.
required: false
type: string
password:
description: The password for accessing the REST endpoint.
required: false
type: string
headers:
description: The headers for the requests.
required: false
type: list, string
json_attributes:
description: A list of keys to extract values from a JSON dictionary result and then set as sensor attributes.
reqired: false
type: list, string
force_update:
description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history.
reqired: false
type: boolean
default: False
{% endconfiguration %}
<p class='note warning'>
Make sure that the URL exactly matches your endpoint or resource.
@ -67,9 +113,7 @@ In this section you find some real life examples of how to use this sensor.
### {% linkable_title External IP address %}
You can find your external IP address using the service [JSON Test](http://www.jsontest.com) at their http://ip.jsontest.com/ endpoint.
To display the IP address, the entry for a sensor in the `configuration.yaml` file will look like this.
You can find your external IP address using the service [JSON Test](http://www.jsontest.com) at their [http://ip.jsontest.com/](http://ip.jsontest.com/) URL.
```yaml
sensor:
@ -83,8 +127,6 @@ sensor:
The [glances](/components/sensor.glances/) sensor is doing the exact same thing for all exposed values.
Add something similar to the entry below to your `configuration.yaml` file:
```yaml
sensor:
- platform: rest
@ -154,3 +196,63 @@ sensor:
User-Agent: Home Assistant REST sensor
```
### {% linkable_title Fetch multiple JSON values and present them as attibutes %}
[JSON Test](http://www.jsontest.com) returns the current time, date and milliseconds since epoch from [http://date.jsontest.com/](http://date.jsontest.com/).
{% raw %}
```yaml
sensor:
- platform: rest
name: JSON time
json_attributes:
- date
- milliseconds_since_epoch
resource: http://date.jsontest.com/
value_template: '{{ value_json.time }}'
- platform: template
sensors:
date:
friendly_name: 'Date'
value_template: '{{ states.sensor.json_time.attributes["date"] }}'
milliseconds:
friendly_name: 'milliseconds'
value_template: '{{ states.sensor.json_time.attributes["milliseconds_since_epoch"] }}'
```
{% endraw %}
This sample fetches a weather report from [OpenWeatherMap](http://openweathermap.org/), maps the resulting data into attributes of the RESTful sensor and then creates a set of [template](/components/sensor.template/) sensors that monitor the attributes and present the values in a usable form.
{% raw %}
```yaml
sensor:
- platform: rest
name: OWM_report
json_attributes:
- main
- weather
value_template: '{{ value_json["weather"][0]["description"].title() }}'
resource: http://api.openweathermap.org/data/2.5/weather?zip=80302,us&APPID=VERYSECRETAPIKEY
- platform: template
sensors:
owm_weather:
value_template: '{{ states.sensor.owm_report.attributes.weather[0]["description"].title() }}'
icon_template: '{{ "http://openweathermap.org/img/w/"+states.sensor.owm_report.attributes.weather[0]["icon"]+".png" }}'
entity_id: sensor.owm_report
owm_temp:
friendly_name: 'Outside temp'
value_template: '{{ states.sensor.owm_report.attributes.main["temp"]-273.15 }}'
unit_of_measurement: "°C"
entity_id: sensor.owm_report
owm_pressure:
friendly_name: 'Outside pressure'
value_template: '{{ states.sensor.owm_report.attributes.main["pressure"] }}'
unit_of_measurement: "hP"
entity_id: sensor.owm_report
owm_humidity:
friendly_name: 'Outside humidity'
value_template: '{{ states.sensor.owm_report.attributes.main["humidity"] }}'
unit_of_measurement: "%"
entity_id: sensor.owm_report
```
{% endraw %}

3
source/_components/sensor.sabnzbd.markdown
View file

@ -40,6 +40,7 @@ sensor:
- 'queue_remaining'
- 'disk_size'
- 'disk_free'
- 'queue_count'
```
Configuration variables:
@ -56,6 +57,7 @@ Configuration variables:
- **queue_remaining**: Remaining elements in the queue
- **disk_size**: Disk size of the storage location
- **disk_free**: Free disk space at the storage location
- **queue_count**: Number of items in the queue
Note that this will create the following sensors:
@ -66,6 +68,7 @@ Note that this will create the following sensors:
- sensor.sabnzbd_left
- sensor.sabnzbd_disk
- sensor.sabnzbd_disk_free
- sensor.sabnzdb_queue_count
```
As always, you can determine the names of sensors by looking at the dev-state page `< >` in the web interface.

25
source/_components/sensor.scrape.markdown
View file

@ -45,6 +45,7 @@ In this section you find some real life examples of how to use this sensor. Ther
The current release Home Assistant is published on [https://home-assistant.io/](https://home-assistant.io/)
{% raw %}
```yaml
sensor:
# Example configuration.yaml entry
@ -52,13 +53,15 @@ sensor:
resource: https://home-assistant.io
name: Release
select: ".current-version h1"
value_template: '{% raw %}{{ value.split(":")[1] }}{% endraw %}'
value_template: '{{ value.split(":")[1] }}'
```
{% endraw %}
### {% linkable_title Available implementations %}
Get the counter for all our implementations from the [Component overview](/components/) page.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
@ -66,8 +69,9 @@ sensor:
resource: https://home-assistant.io/components/
name: Home Assistant impl.
select: 'a[href="#all"]'
value_template: '{% raw %}{{ value.split("(")[1].split(")")[0] }}{% endraw %}'
value_template: '{{ value.split("(")[1].split(")")[0] }}'
```
{% endraw %}
### {% linkable_title Get a value out of a tag %}
@ -109,3 +113,20 @@ sensor:
select: 'enclosure:nth-of-type(1)'
attribute: url
```
### {% linkable_title Energy price %}
This example tries to retrieve the price for electricity.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: scrape
resource: https://elen.nu/timpriser-pa-el-for-elomrade-se3-stockholm/
name: Electricity price
select: ".elspot-content"
value_template: '{{ value.split(" ")[0] }}'
unit_of_measurement: "öre/kWh"
```
{% endraw %}

Some files were not shown because too many files have changed in this diff Show more