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

Merge pull request #2657 from home-assistant/release-0-45

Browse source 
0.45
This commit is contained in:
Fabian Affolter 2017-05-21 00:53:22 +02:00 • committed by GitHub
commit b497fc4882
62 changed files with 2088 additions and 117 deletions
Download patch file Download diff file Expand all files Collapse all files

75
source/_components/axis.markdown Normal file
View file

@ -0,0 +1,75 @@
---
layout: page
title: "Axis"
description: "Instructions on how to setup devices from Axis Communications within Home Assistant."
date: 2017-04-30 23:04
sidebar: true
comments: false
sharing: true
footer: true
logo: axis.png
ha_category: Hub
ha_release: "0.45"
---
[Axis Communications](https://www.axis.com/) devices are surveillance cameras and other security related network connected hardware. Sensor API works with firmware 5.50 and newer.
Home Assistant will automatically discover their presence on your network.
You can also manually configure your devices by adding the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
axis:
m1065lw:
host: IP ADDRESS
username: USERNAME
password: PASSWORD
include:
- camera
- motion
- pir
- audio
- daynight
trigger_time: 0
location: köket
```
## {% linkable_title Dependencies %}
```bash
sudo apt-get install python3-gi gir1.2-gstreamer-1.0
```
Depending on how you run Home Assistant you might be needed to symlink the `gi` module into your environment (e.g. in Hassbian):
```bash
ln -s /usr/lib/python3/dist-packages/gi /srv/homeassistant/lib/python3.4/site-packages
```
## {% linkable_title Configuration variables %}
- **device** (*Required*): Unique name
- **host** (*Required*): The IP address to your Axis device.
- **username** (*Optional*): The username to your Axis device. Default 'root'.
- **password** (*Optional*): The password to your Axis device. Default 'pass'.
- **trigger_time** (*Optional*): Minimum time (in seconds) a sensor should keep its positive value. Default 0.
- **location** (*Optional*): Physical location of your Axis device. Default not set.
- **include** (*Required*): This cannot be empty else there would be no use adding the device at all.
- **camera**: Stream MJPEG video to Home Assistant
- **motion**: The Built in motion detection in Axis cameras
- **vmd3**: ACAP Motion Detection app which has better algorithms for motion detection
- **pir**: PIR sensor that can trigger on motion
- **sound**: Sound detector
- **daynight**: Certain cameras have day/night mode if they have built-in IR lights
- **tampering**: signals when camera believes that it has been tampered with
- **input**: trigger on whatever you have connected to device input port
<p class='note'>
Any specific levels for triggers needs to be configured on the device.
</p>
<p class='note'>
It is recommended that you create a user on your Axis device specifically for Home Assistant. For all current functionality it is enough to create a user belonging to user group viewer.
</p>

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

@ -0,0 +1,28 @@
---
layout: page
title: "Axis Binary Sensor"
description: "Instructions how to integrate Axis binary sensors into Home Assistant."
date: 2017-04-01 19:00
sidebar: true
comments: false
sharing: true
footer: true
logo: axis.png
ha_category: Binary Sensor
ha_iot_class: "Local Push"
ha_release: "0.45"
---
The `Axis` platform allows you to get data from your [Axis](https://www.axis.com/) devices from within Home Assistant.
See the [Axis main component](/components/axis/) for configuration instructions.
The following sensor types are supported:
* Motion detection
* Passive IR motion detection
* Sound detection
* Day/night mode
* Tampering detection
* Input port

70
source/_components/binary_sensor.mystrom.markdown Normal file
View file

@ -0,0 +1,70 @@
---
layout: page
title: "myStrom Binary Sensor"
description: "Instructions how to integrate myStrom buttons into Home Assistant."
date: 2017-04-14 08:15
sidebar: true
comments: false
sharing: true
footer: true
logo: mystrom.png
ha_category: Binary Sensor
ha_iot_class: "Local Polling"
ha_release: 0.45
---
The `mystrom` binary sensor platform allows you to use [myStrom Wifi Buttons](https://mystrom.ch/wifi-button/) with Home Assistant. The myStrom Wifi Buttons support three and the myStrom WiFi Button + four different push pattern:
- `single`: Short push (approx. 1/2 seconds)
- `double`: 2x sequential short pushes (within 2 seconds)
- `long`: Long push (approx. 2 seconds)
- `touch`: Touch of the button's surface (only affective for WiFi Button +)
The first usage of the pattern will create the binary sensor for the pattern. If the WiFi Button is pushed one time then a binary sensor for the `single` pattern will be created. The same applies for the other patterns. With the second usage of the pattern the binary sensors become fully functional.
The buttons will give you feedback with its built-in LED:
- white then green: Pattern was submitted successfully
- white then red: There is a problem with the communication
To use your myStrom WiFi Button in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: mystrom
```
### {% linkable_title Setup of the myStrom Buttons %}
After the Wifi Buttons are connected to your Wireless network, you have three minutes to set the actions for the push patterns. The fastest way is to use `curl`. Check the [documentation](https://mystrom.ch/wp-content/uploads/REST_API_WBP.txt) of the WiFi Button for further details about implementation (`http://` is replaced by `get://` or `post://`). `action` is the name of the corresponding push pattern.
```bash
$ curl -d "[action]=get://[IP address Home Assistant]:8123/api/mystrom?single%3D[ID of the button]" http://[IP address of the button]/api/v1/device/[MAC address of the button]
{
"[MAC address of the button]": {
"type": "button",
"battery": true,
"reachable": true,
"meshroot": false,
"charge": true,
"voltage": 4.292,
"fw_version": "2.26",
"single": "get://[IP address Home Assistant]:8123/api/mystrom?single=[if of the button]",
"double": "",
"long": "",
"touch": ""
}
}
```
A complete command to set the URL for a double click could look like the example below:
```bash
$ curl -d "double=get://192.168.1.3:8123/api/mystrom?double%3DButton1" http://192.168.1.12/api/v1/device/4D5F5D5CD553
```
<p class='note'>
The firmware version 2.26 doesn't support TLS/SSL. This means that you are only able to use the WiFi Buttons if you are using plain-text communication between Home Assistant and the clients/entities.
</p>

47
source/_components/binary_sensor.raspihats.markdown Normal file
View file

@ -0,0 +1,47 @@
---
layout: page
title: "Raspihats Binary Sensor"
description: "Instructions how to integrate Raspihats add-on boards for Raspberry PI into Home Assistant as a binary_sensor."
date: 2017-05-01 04:09
sidebar: true
comments: false
sharing: true
footer: true
logo: raspihats.png
ha_category: Binary Sensor
ha_release: 0.44
ha_iot_class: "Local Push"
---
The `raspihats` binary sensor platform allows you to read sensor values ​​using the digital inputs of the [raspihats](http://www.raspihats.com/) boards.
To use your `raspihats` boards in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: raspihats
i2c_hats:
- board: DI6acDQ6rly
address: 0x60
channels:
- index: 0
name: PIR Office
invert_logic: true
device_class: motion
- index: 1
name: PIR Bedroom
```
Configuration variables:
- **i2c_hats** (*Optional*): Array of used I2C-HATs.
- **board** (*Required*): The board name [Di16, Di6Rly6, DI16ac, DI6acDQ6rly].
- **address** (*Required*): The board I2C address, hex value.
- **channels** (*Required*): Array of used digital input channels.
- **index** (*Required*): Digital input channel index.
- **name** (*Required*): Friendly name to use for the frontend.
- **invert_logic** (*Optional*): Inverts the input logic, default is `false`.
- **device_class** (*Optional*): See device classes in [binary_sensor component](/components/binary_sensor/), default is `None`
For more details about the `raspihats` add-on boards for Raspberry PI, visit [raspihats.com](http://www.raspihats.com/).

39
source/_components/binary_sensor.rpi_pfio.markdown Normal file
View file

@ -0,0 +1,39 @@
---
layout: page
title: "PiFace Digital I/O Binary Sensor"
description: "Instructions how to integrate the PiFace Digital I/O module into Home Assistant as a binary sensor."
date: 2016-05-08 15:00
sidebar: true
comments: false
sharing: true
footer: true
logo: raspberry-pi.png
ha_category: Binary Sensor
ha_release: 0.45
---
The `rpi_pfio` binary sensor platform allows you to read sensor values of the [PiFace Digital I/O](http://www.piface.org.uk/products/piface_digital/) .
To use your PiFace Digital I/O module in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: rpi_pfio
ports:
0:
name: PIR Office
invert_logic: true
1:
name: Doorbell
settle_time: 50
```
Configuration variables:
- **ports** array (*Required*): Array of used ports.
- **num** (*Required*): Port number.
- **name** (*Required*): Port name.
- **settle_time** (*Optional*): The time in milliseconds for port debouncing. Default is 2 0ms.
- **invert_logic** (*Optional*): If true, inverts the output logic to ACTIVE LOW. Default is false (ACTIVE HIGH).

11
source/_components/blink.markdown
View file

@ -33,15 +33,16 @@ Once loaded, your front end will have the following components:
* A sensor per camera that reports battery level.
* A sensor per camera that reports unread notification (ie. detected motion events).
Since the cameras are battery operated, the images are only updated in Home Assistant when the user manually forces a new photo. The image can only be updated in Home Assistant every 60 seconds in order to not overwhelm Blink's servers with API requests.
Since the cameras are battery operated, the images are only updated in Home Assistant when the user manually forces a new photo. This image can be updated with the `blink.snap_picture` service followed by a `blink.force_update` service call to force Home Assistant to request an update from Blink's servers. If the `blink.force_update` service is not called, the image will be updated within a 180 second interval, set so that automatic server requests don't overwhelm the Blink API. As a note, all of the camera-specific sensors are only polled when a new image is requested from the camera. This means that relying on any of these sensors to provide timely and accurate data is not recommended.
Services:
There are three services availiabe for the blink platform:
- arm_system
- arm_camera
- snap_picture
- force_update
For arm_system, the value sent can be either "True" or "False" and will arm and disarm the whole blink system, respectively
For `blink.arm_system`, the value sent can be either "True" or "False" and will arm and disarm the whole blink system, respectively
Arm system example
```json
@ -50,7 +51,7 @@ Arm system example
}
```
Arm camera follows a similar structure, but each indidivual camera can have motion detection enabled or disabled. Because of this, you also need to supply a name. For example, if I have a camera named "Living Room" and I want to turn off motion detection on that camera, I'd call the blink.arm_camera service with the following payload:
Arm camera follows a similar structure, but each indidivual camera can have motion detection enabled or disabled. Because of this, you also need to supply a name. For example, if I have a camera named "Living Room" and I want to turn off motion detection on that camera, I'd call the `blink.arm_camera` service with the following payload:
```json
{
"friendly_name": "Living Room",
@ -58,13 +59,15 @@ Arm camera follows a similar structure, but each indidivual camera can have moti
}
```
The blink.snap_picture service takes the camera name as the payload and with take a new picture with your camera.
The `blink.snap_picture` service takes the camera name as the payload and with take a new picture with your camera.
```
{
"friendly_name": "Living Room"
}
```
The `blink.force_update` service can simply be called with no payload to force a server update.
Configuration variables:
- **username** (*Required*): Your username to login to Blink

6
source/_components/camera.amcrest.markdown
View file

@ -33,8 +33,12 @@ Configuration variables:
- **name** (*Optional*): This parameter allows you to override the name of your camera. The default is "Amcrest Camera".
- **port** (*Optional*): The port that the camera is running on. The default is 80.
- **resolution** (*Optional*): This parameter allows you to specify the camera resolution. For a high resolution (1080/720p), specify the option `high`. For VGA resolution (640x480p), specify the option `low`. If omitted, it defaults to *high*.
- **stream_source** (*Optional*): The data source for the live stream. `mjpeg` will use the camera's native MJPEG stream, whereas `snapshot` will use the camera's snapshot API to create a stream from still images. If omitted, it defaults to *mjpeg*.
- **stream_source** (*Optional*): The data source for the live stream. `mjpeg` will use the camera's native MJPEG stream, whereas `snapshot` will use the camera's snapshot API to create a stream from still images. You can also set the `rtsp` option to generate the streaming via RTSP protocol. If omitted, it defaults to *mjpeg*.
- **ffmpeg_arguments**: (*Optional*): Extra options to pass to ffmpeg, e.g. image quality or video filter options.
**Note:** Amcrest cameras with newer firmwares no longer have the ability to stream `high` definition video with MJPEG encoding. You may need to use `low` resolution stream or the `snapshot` stream source instead. If the quality seems too poor, lower the `Frame Rate (FPS)` and max out the `Bit Rate` settings in your camera's configuration manager.
**Note:** If you set the `stream_source` option to `rtsp`, make sure to follow the steps mentioned at
[FFMPEG](https://home-assistant.io/components/ffmpeg/) documentation to install the `ffmpeg`.
To check if your Amcrest camera is supported/tested, visit the [supportability matrix](https://github.com/tchellomello/python-amcrest#supportability-matrix) link from the `python-amcrest` project.

17
source/_components/camera.axis.markdown Normal file
View file

@ -0,0 +1,17 @@
---
layout: page
title: "Axis Camera"
description: "Instructions how to setup Axis cameras within Home Assistant."
date: 2017-05-01 19:09
sidebar: true
comments: false
sharing: true
footer: true
logo: axis.png
ha_category: Camera
ha_release: "0.45"
---
The `Axis` camera platform allows you to stream video from your [Axis](https://www.axis.com/) cameras.
The requirement is that you have setup your [Axis camera](/components/axis/).

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

@ -28,6 +28,6 @@ camera:
Configuration variables:
- **nvr** (*Required*): The IP or hostname of the NVR (Network Video Recorder) server.
- **port** (*Optional*): The port number to use for accessing the NVR.
- **key** (*Required*): The API key available from the NVR web interface.
- **port** (*Optional*): The port number to use for accessing the NVR.
- **password** (*Optional*): The camera password. Defaults to `ubnt` if not given.

14
source/_components/cover.lutron_caseta.markdown Normal file
View file

@ -0,0 +1,14 @@
---
layout: page
title: "Lutron Caseta Cover"
description: "Instructions how to setup the Lutron Caseta covers within Home Assistant."
date: 2017-05-20 09:00
sidebar: true
comments: false
sharing: true
footer: true
logo: lutron.png
ha_category: Cover
---
To get your Lutron Caseta covers working with Home Assistant, follow the instructions for the general [Lutron Caseta component](/components/lutron_caseta/).

41
source/_components/datadog.markdown Normal file
View file

@ -0,0 +1,41 @@
---
layout: page
title: "Datadog"
description: "Send data and events to Datadog."
date: 2017-04-18 00:00
sidebar: true
comments: false
sharing: true
logo: datadog.png
footer: true
ha_category: History
ha_release: 0.45
---
The `datadog` component sends all state changes to [Datadog](https://www.datadoghq.com/) using a [Datadog Agent](http://docs.datadoghq.com/guides/basic_agent_usage/).
Datadog allows you to analyze, monitor, cross-reference and alert upon your data. You can use it to detect statistical anomalies, see graphs across multiple sources in real-time, send critical alerts to Slack, etc.
<p class='img'>
<img src='{{site_root}}/images/screenshots/datadog-board-example.png' />
</p>
The component also sends events from the logbook into Datadog, allowing you to correlate these events with your data.
<p class='img'>
<img src='{{site_root}}/images/screenshots/datadog-event-stream.png' />
</p>
To use the `datadog` component in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
datadog:
```
Configuration variables:
- **host** (*Optional*): The IP address or hostname of your Datadog host, e.g. 192.168.1.23. Defaults to `localhost`.
- **port** (*Optional*): Port to use. Defaults to 8125.
- **prefix** (*Optional*): Prefix to use. Defaults to `hass`.
- **rate** (*Optional*): The sample rate of UDP packets sent to Datadog. Defaults to 1.

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

@ -18,6 +18,8 @@ The `automatic` platform offers presence detection by retrieving your car's info
To use Automatic with Home Assistant, first you must [create a free development account](https://developer.automatic.com/). Automatic will generate a Client ID and Secret for you to use in your Home Assistant configuration. You will also need to update your Event Delivery preferences to ensure Home Assistant can receive updates. On the developer page, under App Settings / Event Delivery, select "Websocket" for Event Delivery Preference.
Home Assistant will also take advantage of `scope:current_location` if available. This will allow Home Assistant to receive periodic location updates during a trip. In order to use this functionality, you must request the scope for your application from Automatic. Once `scope:current_location` is available, Home Assistant will automatically make use of it after the next restart.
Once your developer account is created, add the following to your `configuration.yaml` file:
```yaml

13
source/_components/device_tracker.mikrotik.markdown
View file

@ -9,11 +9,11 @@ sharing: true
footer: true
logo: mikrotik.png
ha_category: Presence Detection
ha_release: "0.43"
ha_release: 0.44
---
The `Mikrotik` platform offers presence detection by looking at connected devices to a [Mikrotik Routerboard](http://routerboard.com) based router.
The `mikrotik` platform offers presence detection by looking at connected devices to a [Mikrotik Routerboard](http://routerboard.com) based router.
To use an Mikrotik router in your installation, add the following to your `configuration.yaml` file:
@ -21,10 +21,9 @@ To use an Mikrotik router in your installation, add the following to your `confi
# Example configuration.yaml entry
device_tracker:
- platform: mikrotik
host: 192.168.81.1
username: admin
password: hellomoto
port: 1603
host: IP_ADDRESS
username: ADMIN_USERNAME
password: ADMIN_PASSWORD
```
Configuration variables:
@ -32,6 +31,6 @@ Configuration variables:
- **host** (*Required*): The IP address of your router.
- **username** (*Required*: The username of an user with administrative privileges.
- **password** (*Required*): The password for your given admin account.
- **port** (*Optional*): Mikrotik api port (See IP -> Services -> api ), default 8728
- **port** (*Optional*): Mikrotik API port (see IP -> Services -> api ). Defaults to `8728`.
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.

2
source/_components/discovery.markdown
View file

@ -31,6 +31,7 @@ Home Assistant can discover and automatically configure zeroconf/mDNS and uPnP d
* Linn / Openhome
* Denon Network Receivers
* Bose Soundtouch speakers
* Axis Communications security devices
* IKEA Trådfri (Tradfri)
It will be able to add Google Chromecasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user.
@ -52,6 +53,7 @@ Configuration variables:
Valid values for ignore are:
* `apple_tv`: Apple TV
* `axis`: (Axis Communications security devices)
* `denonavr`: Denon Network Receivers
* `directv`: DirecTV
* `flux_led`: Flux Led/MagicLight

4
source/_components/ha.markdown
View file

@ -1,6 +1,6 @@
---
layout: page
title: "Home Assistant 0.42"
title: "Home Assistant 0.45"
description: ""
date: 2016-12-16 17:00
sidebar: true
@ -9,7 +9,7 @@ sharing: true
footer: true
logo: home-assistant.png
ha_category: Other
ha_release: 0.42
ha_release: 0.45
---
Details about the latest release can always be found at:

92
source/_components/image_processing.seven_segments.markdown Normal file
View file

@ -0,0 +1,92 @@
---
layout: page
title: "Seven segments display"
description: "Instructions how to use OCR for seven segemnts displays into Home Assistant."
date: 2017-05-18 08:00
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Image Processing
featured: false
ha_release: 0.45
---
The `seven_segments` image processing platform allows you to read physical seven segments displays through Home Assistant. [`ssocr`](https://www.unix-ag.uni-kl.de/~auerswal/ssocr/) is used to extract the value shown on the display which is observed by a [camera](/components/camera/). `ssocr` need to be available on your system. Check the installation instruction for Fedora below or use `$ sudo apt-get install ssocr` on a Debian-based system:
```bash
$ sudo dnf -y install imlib2-devel
$ git clone https://github.com/auerswal/ssocr.git
$ cd ssocr
$ make
$ sudo make PREFIX=/usr install
```
To enable the OCR of a seven segement display in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
image_processing:
- platform: seven_segments
source:
- entity_id: camera.seven_segments
```
Configuration variables:
- **ssocr_bin** (*Optional*): The command line tool `ssocr`. Set it if you use a different name for the executable. Defaults to `ssorc`.
- **x_position** (*Optional*): X coordinate of the upper left corner of the area to crop. Defaults to `0`.
- **y_position** (*Optional*): Y coordinate of the upper left corner of the area to crop. Defaults to `0`.
- **height** (*Optional*): Height of the area to crop. Defaults to `0`.
- **width** (*Optional*): Width of the area to crop. Defaults to `0`.
- **threshold** (*Optional*): Threshold for the difference between the digits and the background. Defaults to `0`.
- **digits** (*Optional*): Number of digits in the display. Defaults to `-1`.
- **source** array (*Required*): List of image sources.
- **entity_id** (*Required*): A camera entity id to get picture from.
- **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity.
### {% linkable_title Setup process %}
It's suggested that the first attempt to determine the needed parameters is using `ssocr` directly. This may require a couple of iterations to get the result
```bash
$ ssocr -D erosion crop 390 250 490 280 -t 20 -d 4 ss-test.jpg
```
This would lead to the following entry for the `configuration.yaml` file:
```yaml
camera:
- platform: local_file
file_path: /home/fab/.homeassistant/seven-seg.png
name: seven_segments
image_processing:
- platform: seven_segments
x_position: 390
y_position: 250
height: 280
width: 490
threshold: 20
digits: 4
source:
- entity_id: camera.seven_segments
```
<p class='img'>
<img src='{{site_root}}/images/screenshots/ssocr.png' />
</p>
With the help of a [template sensor](/components/sensor.template/), the value can be shown as badge.
```yaml
sensor:
- platform: template
sensors:
power_meter:
value_template: '{{ states.image_processing.sevensegement_ocr_seven_segments.state }}'
friendly_name: 'Ampere'
unit_of_measurement: 'A'
```

88
source/_components/kira.markdown Normal file
View file

@ -0,0 +1,88 @@
---
layout: page
title: "Kira"
description: "Instructions how to integrate Keene Electronics IR over IP modules (Kira) into Home Assistant."
date: 2017-05-07 00:00
sidebar: true
comments: false
sharing: true
footer: true
logo: keene.png
ha_category: Hub
ha_release: 0.45
---
The `kira` component is the main component to integrate Keene Electronics IR over IP [Kira](https://www.keene.co.uk/keene-ir-anywhere-single-worldwide.html) modules with Home Assistant.
### {% linkable_title Example Configuration %}
```yaml
# Example configuration.yaml entry
kira:
```
Kira modules have no built-in mechanism for auto-discovery, so will need to be configured to send packets to Home Assistant. Documentation for this can be found on the manufacturer's website [Here](https://www.keene.co.uk/pages/iranywhere/index.html).
### {% linkable_title Configuration Options %}
```yaml
# Example configuration.yaml entry
kira:
sensors:
- name: kira_sensor
host: 0.0.0.0
port: 65432
remotes:
name: kira_remote
host: 192.168.100.1
port: 65432
```
Configuration variables:
- **sensors** (*Optional*): Kira sensors to register
- **name** (*Optional*): Name of this sensor.
- **host** (*Optional*): Bind address for this sensor. 0.0.0.0 is default.
- **port** (*Optional*): UDP port to listen for packets on. 65432 is default.
- **remotes** (*Optional*): Remote Kira modules to register
- **name** (*Optional*): Name of this remote.
- **host** (*Required*): IP address of Kira module to send commands to.
- **port** (*Optional*): UDP port to send packets to. 65432 is default.
If no sensors or remotes are specified, a sensor with default values will be added.
### {% linkable_title Code Configuration %}
The first time the Kira component is loaded, `kira_codes.yaml` will be created in the Home Assistant configuration directory.
```yaml
# Example kira_codes.yaml entry
- name: LivingRoomTVOn
code: "K 2322 228A 1126 023E 0227 023E 0207 023F 0658 025D 0207 023F 0227 0220 0227 023F 0222 023E 0222 0220 067D 023F 0658 0222 0227 025C 0640 023F 0658 025D 0640 023E 0658 025D 0640 023F 0222 025C 0207 0222 0678 023E 0207 023F 0227 023F 0222 025C 063B 025C 0640 023E 0660 023E 0658 025D 0207 0222 0678 023E 0660 0220 0678 023E 0202 025D 0207 023F 2000"
type: kira
- name: HDMI_1
code: "0000 006d 0026 0000 0155 00aa 0016 0015 0016 0015 0016 0040 0016 0015 0016 0015 0016 0014 0016 0015 0016 0015 0016 0040 0016 0040 0016 0015 0016 0040 0016 0040 0016 0040 0016 0040 0016 0040 0016 0015 0016 0040 0016 0040 0016 0040 0016 0014 0016 0015 0016 0040 0016 0040 0016 0040 0016 0015 0016 0014 0016 0014 0016 0040 0016 0040 0016 0014 0016 0015 0016 060b 0155 0055 0016 0e58 0155 0055 0016 00aa"
device: LivingRoomTv
type: pronto
- name: RGB
code: "F709 DC24"
device: LivingRoomTv
type: nec
```
Configuration variables:
- **name** (*Required*): The name of this code.
- **code** (*Required*): The data for this code (see below).
- **device** (*Optional*): The device this code is associated with. Default is "unknown".
- **type** (*Optional*): The type of this code. If this field is omitted, the type will be autodetected if possible.
- **repeat** (*Optional*): The number of times to repeat this code (on transmit). Default is 1.
Some manufacturers (e.g. Samsung) require an IR code to be sent a number of times in a row in rapid succession (usually 3). This doesn't apply to the vast majority of devices, but it can be helpful if needed.
### {% linkable_title Code Types %}
When creating an entry in `kira_codes.yaml`, a few different kinds of codes can be used.
- **kira**: This is the native wire protocol used by Kira modules. These can be captured using netcat.
- **pronto**: Pronto codes are supported.
- **nec**: If the device uses NEC IR codes and the manufacturer has published them, they can be used here.
**NOTE**: NEC codes by themselves contain enough information to recognize an IR sequence, but not enough to reconstruct it. Codes of this type are receive-only (usable by sensors but not remotes).

16
source/_components/light.lifx.markdown
View file

@ -27,6 +27,22 @@ Configuration variables:
- **server** (*Optional*): Your server address. Only needed if using more than one network interface. Omit if you are unsure.
## {% linkable_title Set state %}
The LIFX bulbs allow a change of color and brightness even when they are turned off. This way you can control the light during the day so its settings are correct when events for turning on are received, for example from motion detectors or external buttons.
The normal `light.turn_on` call cannot be used for this because it always turns the power on. Thus, LIFX has its own service call that allows color changes without affecting the current power state.
### {% linkable_title Service `light.lifx_set_state` %}
Change the light to a new state.
| Service data attribute | Description |
| ---------------------- | ----------- |
| `entity_id` | String or list of strings that point at `entity_id`s of lights. Else targets all.
| `transition` | Duration (in seconds) for the light to fade to the new state.
| `power` | Turn the light on (`True`) or off (`False`). Leave out to keep the power as it is.
| `...` | Use `color_name`, `brightness` etc. from [`light.turn_on`]({{site_root}}/components/light/#service-lightturn_on) to specify the new state.
## {% linkable_title Light effects %}

2
source/_components/light.markdown
View file

@ -38,8 +38,10 @@ Turns one light on or multiple lights on using [groups]({{site_root}}/components
| `xy_color` | yes | A list containing two floats representing the xy color you want the light to be. Two comma separated floats that represent the color in XY.
| `rgb_color` | yes | A list containing three integers representing the rgb color you want the light to be. Three comma separated integers that represent the color in RGB. You can find a great chart here: [Hue Color Chart](http://www.developers.meethue.com/documentation/hue-xy-values)
| `color_temp` | yes | An INT in mireds representing the color temperature you want the light to be.
| `kelvin` | yes | Alternatively, you can specify the color temperature in Kelvin.
| `color_name` | yes | A human readable string of a color name, such as `blue` or `goldenrod`. All [CSS3 color names](https://www.w3.org/TR/2010/PR-css3-color-20101028/#svg-color) are supported.
| `brightness` | yes | Integer between 0 and 255 for how bright the color should be.
| `brightness_pct`| yes | Alternatively, you can specify brightness in percent (a number between 0 and 100).
| `flash` | yes | Tell light to flash, can be either value `short` or `long`. *Not supported by all lights.
| `effect`| yes | Applies an effect such as `colorloop` or `random`.

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

@ -16,6 +16,8 @@ logo: raspberry-pi.png
The `rpi_gpio_pwm` platform allows to control multiple lights using pulse-width modulation, for example led strips. It supports one-color, RGB and RGBW LEDs driven by GPIOs of a Raspberry Pi or a PCA9685 controller.
For controlling the GPIOs, the platform connects to the [pigpio-daemon](http://abyz.co.uk/rpi/pigpio/pigpiod.html), which must be running. On Raspbian Jessie 2016-05-10 or newer the `pigpio` library is already included. On other operating systems it needs to be installed first (see [installation instructions](https://github.com/soldag/python-pwmled#installation)).
To enable this platform, add the following lines to your `configuration.yaml`:
```yaml

105
source/_components/lock.wink.markdown
View file

@ -24,6 +24,111 @@ The requirement is that you have setup [Wink](/components/wink/).
- Schlage
- Generic Z-wave
<p class='note'>
The following services have only been confirmed on Schlage locks.
</p>
### {% linkable_title Service `wink_set_lock_alarm_mode` %}
You can use the service wink/wink_set_lock_alarm_mode to set the alarm mode of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `mode` | no | String one of tamper, activity, or forced_entry
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
Example:
```yaml
script:
set_locks_to_tamper:
sequence:
- service: wink.wink_set_lock_alarm_mode
data:
mode: "tamper"
```
### {% linkable_title Service `wink_set_lock_alarm_sensitivity` %}
You can use the service wink/wink_set_lock_alarm_sensitivity to set the alarm sensitivity of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
Example:
```yaml
script:
set_locks_to_high_sensitivity:
sequence:
- service: wink.wink_set_lock_alarm_sensitivity
data:
sensitivity: "high"
```
### {% linkable_title Service `wink_set_lock_alarm_state` %}
You can use the service wink/wink_set_lock_alarm_state to set the alarm state of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
Example:
```yaml
script:
disable_all_locks_alarm:
sequence:
- service: wink.wink_set_lock_alarm_state
data:
enabled: false
```
### {% linkable_title Service `wink_set_lock_beeper_state` %}
You can use the service wink/wink_set_lock_beeper_state to set the beeper state of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
Example:
```yaml
script:
disable_all_locks_beepers:
sequence:
- service: wink.wink_set_lock_beeper_state
data:
enabled: false
```
### {% linkable_title Service `wink_set_lock_vacation_mode` %}
You can use the service wink/wink_set_lock_vacation_mode to set the vacation mode of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
Example:
```yaml
script:
enabled_vacation_mode_on_all_locks:
sequence:
- service: wink.wink_set_lock_vacation_mode
data:
enabled: false
```
<p class='note'>
If supported by your lock, a binary sensor will be created for each user key code you have defined. These key codes will turn on when the code is entered and automatically turn off after a few seconds.
</p>

9
source/_components/lutron_caseta.markdown
View file

@ -13,11 +13,14 @@ featured: False
ha_release: 0.41
---
[Lutron](http://www.lutron.com/) is an American lighting control company. They have several lines of home automation devices that manage light switches/dimmers, occupancy sensors, HVAC controls, etc. The `lutron_caseta` component in Home Assistant is responsible for communicating with the Lutron SmartBridge for these systems.
[Lutron](http://www.lutron.com/) is an American lighting control company. They have several lines of home automation devices that manage light switches/dimmers, occupancy sensors, HVAC controls, etc. The `lutron_caseta` component in Home Assistant is responsible for communicating with the Lutron SmartBridge for these systems. Both 'pro' and 'standard' models are supported.
This component only supports the Caseta line of products. Current only supports Caseta dimmers as Home Assistant lights and caseta wall switches as Home Assistant switches.
This component only supports the Caseta line of products. The current supported Caseta devices are:
- Dimmers as Home Assistant lights
- Wall switches as Home Assistant switches
- Serena shades as Home Assistant covers
When configured, the `lutron_caseta` component will automatically discover dimmers and switches as setup in the Lutron SmartBridge.
When configured, the `lutron_caseta` component will automatically discover the currently support devices as setup in the Lutron SmartBridge.
To use Lutron Caseta devices in your installation, add the following to your `configuration.yaml` file using the IP of your lutron Smartbridge:

58
source/_components/media_player.kodi.markdown
View file

@ -37,3 +37,61 @@ Configuration variables:
- **password** (*Optional*): The XBMC/Kodi HTTP password.
- **turn_off_action** (*Optional*): The desired turn off action. Options are `none`, `quit`, `hibernate`, `suspend`, `reboot`, or `shutdown`. Default `none`.
- **enable_websocket** (*Optional*): Enable websocket connections to Kodi via the TCP port. Defaults to `true`. The websocket connection allows Kodi to push updates to Home Assistant and removes the need for Home Assistant to poll. If websockets don't work on your installation this can be set to `false`.
- **timeout** (*Optional*): Set timeout for connections to Kodi. Defaults to 5 seconds.
### {% linkable_title Service `kodi_add_to_playlist` %}
Add music to the default playlist (i.e. playlistid=0).
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Name(s) of the Kodi entities where to add the media.
| `media_type` | yes | Media type identifier. It must be one of SONG or ALBUM.
| `media_id` | no | Unique Id of the media entry to add (`songid` or `albumid`). If not defined, `media_name` and `artist_name` are needed to search the Kodi music library.
| `media_name` | no| Optional media name for filtering media. Can be 'ALL' when `media_type` is 'ALBUM' and `artist_name` is specified, to add all songs from one artist.
| `artist_name` | no | Optional artist name for filtering media.
### {% linkable_title Service `kodi_call_method` %}
Call a [Kodi JSONRPC API](http://kodi.wiki/?title=JSON-RPC_API) method with optional parameters. Results of the Kodi API call will be redirected in a Home Assistant event: `kodi_call_method_result`.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | Name(s) of the Kodi entities where to run the API method.
| `method` | yes | Name of the Kodi JSONRPC API method to be called.
| any other parameter | no | Optional parameters for the Kodi API call.
### {% linkable_title Event triggering %}
When calling the `kodi_call_method` service, if the Kodi JSONRPC API returns data, when received by Home Assistant it will fire a `kodi_call_method_result` event on the event bus with the following `event_data`:
```yaml
entity_id: "<Kodi media_player entity_id>"
result_ok: <boolean>
input: <input parameters of the service call>
result: <data received from the Kodi API>
```
### {% linkable_title Kodi services samples %}
#### Simple script to turn on the TV with the Kodi JSON-CEC Addon
```yaml
script:
activate_tv:
alias: Turn on TV
sequence:
- alias: TV on
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: Addons.ExecuteAddon
addonid: script.json-cec
params:
command: activate
```
For a more complex usage of the `kodi_call_method` service, with event triggering of Kodi API results, you can have a look at this [example](/cookbook/kodi_dynamic_input_select/)

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

@ -107,3 +107,15 @@ Clear the sleep timer on a speaker, if one is set.
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of `entity_id`s that will have their timers cleared. Must be a coordinator speaker.
### {% linkable_title Service `sonos_update_alarm` %}
Update an existing sonos alarm.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of `entity_id`s that will have their timers cleared. Must be a coordinator speaker.
| `alarm_id` | no | Integer that is used in Sonos to refer to your alarm.
| `time` | yes | Time to set the 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.

2
source/_components/microsoft_face.markdown
View file

@ -22,11 +22,13 @@ To enable the Microsoft Face component, add the following lines to your `configu
# Example configuration.yaml entry
microsoft_face:
api_key: YOUR_API_KEY
azure_region: eastus2
```
Configuration variables:
- **api_key** (*Required*): The API key for your Cognitive resource.
- **azure_region** (*Optional*): The region where you instantiated your Microsoft Cognitive services endpoint
- **timeout** (*Optional)*: Set timeout for the API connection. Defaults to 10s.
### {% linkable_title Person and Groups %}

75
source/_components/notify.smtp.markdown
View file

@ -35,8 +35,9 @@ Configuration variables:
- **sender** (*Optional*): E-mail address of the sender.
- **username** (*Optional*): Username for the SMTP account.
- **password** (*Optional*): Password for the SMTP server that belongs to the given username. If the password contains a colon it need to be wrapped in apostrophes.
- **recipient** (*Required*): E-mail address of the recipient of the notification. This can be a recpient address or a list of addresses for multiple recipients.
- **recipient** (*Required*): E-mail address of the recipient of the notification. This can be a recipient address or a list of addresses for multiple recipients.
- **starttls** (*Optional*): Enables STARTTLS, eg. True or False. Defaults to False.
- **sender_name** (*Optional*): Sets a custom 'sender name' in the emails headers (*From*: Custom name <example@mail.com>).
- **debug** (*Optional*): Enables Debug, eg. True or False. Defaults to False.
A sample configuration entry for Google Mail.
@ -56,6 +57,7 @@ notify:
recipient:
- james@gmail.com
- bob@gmail.com
sender_name: My Home Assistant
```
Keep in mind that Google has some extra layers of protection which need special attention (Hint: 'Less secure apps').
@ -63,7 +65,7 @@ Keep in mind that Google has some extra layers of protection which need special
To use the SMTP notification, refer to it in an automation or script like in this example:
```yaml
burglar:
burglar:
alias: Burglar Alarm
sequence:
- service: shell_command.snapshot
@ -74,13 +76,80 @@ To use the SMTP notification, refer to it in an automation or script like in thi
title: 'Intruder alert'
message: 'Intruder alert at apartment!!'
data:
images:
images:
- /home/pi/snapshot1.jpg
- /home/pi/snapshot2.jpg
```
The optional `images` field adds in-line image attachments to the email. This sends a text/HTML multi-part message instead of the plain text default.
The optional `html` field makes a custom text/HTML multi-part message, allowing total freedom for sending rich html emails. In them, if you need to attach images, you can pass both arguments (`html` and `images`), the attachments will be joined with the basename of the images, so they can be included in the html page with `src="cid:image_name.ext"`.
```yaml
burglar:
alias: Burglar Alarm
sequence:
- service: shell_command.snapshot
- delay:
seconds: 1
- service: notify.NOTIFIER_NAME
data_template:
message: 'Intruder alert at apartment!!'
data:
images:
- /home/pi/snapshot1.jpg
- /home/pi/snapshot2.jpg
html: >
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="UTF-8">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Intruder alert</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">
<style type="text/css">
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'), url(http://fonts.gstatic.com/s/opensans/v13/DXI1ORHCpsQm3Vp6mXoaTZS3E-kSBmtLoNJPDtbj2Pk.ttf) format('truetype');
}
h1,h2,h3,h4,h5,h6 {
font-family:'Open Sans',Arial,sans-serif;
font-weight:400;
margin:10px 0
}
</style>
</head>
<body>
<div class="jumbotron jumbotron-fluid" style="background-color: #f00a2d; color: white;">
<div class="container py-0">
<h1>Intruder alert at apartment!!</h1>
</div>
</div>
<div class="container-fluid">
<div class="row">
<div class="col-xs-12 col-md-6 px-0">
<img class="rounded" style="width: 100%;"
alt="snapshot1" src="cid:snapshot1.jpg" />
</div>
<div class="col-xs-12 col-md-6 px-0">
<img class="rounded" style="width: 100%;"
alt="snapshot2" src="cid:snapshot2.jpg" />
</div>
</div>
<br>
</div>
</body>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/js/bootstrap.min.js"></script>
</html>
```
Obviously, this kind of complex html email reporting is done much more conveniently using Jinja2 templating from an [AppDaemon app](https://home-assistant.io/docs/ecosystem/appdaemon/tutorial/), for example.
This platform is fragile and not able to catch all exceptions in a smart way because of the large number of possible configuration combinations.
A combination that will work properly is port 587 and STARTTLS. It's recommended to enable STARTTLS, if possible.

55
source/_components/notify.telegram.markdown
View file

@ -18,7 +18,8 @@ The `telegram` platform uses [Telegram](https://web.telegram.org) to delivery no
The requirements are:
- You need a [Telegram bot](https://core.telegram.org/bots). Please follow those [instructions](https://core.telegram.org/bots#6-botfather) to create one and get the token for your bot. Keep in mind that bots are not allowed to contact users. You need to make the first contact with your user. Meaning that you need to send a message to the bot from your user.
- The `chat_id` of an user.
- You need to configure a [Telegram bot in Home Assistant](/components/telegram_bot) and define there your API key and the allowed chat ids to interact with.
- The `chat_id` of an allowed user.
To retrieve your `chat_id`, contact any of the Telegram bots created for this purpose (@myidbot, @get_id_bot)
@ -45,22 +46,51 @@ $ python3
To enable Telegram notifications in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
# Example configuration.yaml entry for the Telegram Bot
telegram_bot:
platform: webhooks
api_key: ABCDEFGHJKLMNOPQRSTUVXYZ
allowed_chat_ids:
- CHAT_ID_1
- CHAT_ID_2
- CHAT_ID_3
# Example configuration.yaml entry for the notifier
notify:
- name: NOTIFIER_NAME
platform: telegram
api_key: ABCDEFGHJKLMNOPQRSTUVXYZ
chat_id: YOUR_CHAT_ID
chat_id: CHAT_ID_2
```
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`.
- **api_key** (*Required*): The API token of your bot.
- **chat_id** (*Required*): The chat ID of your user.
To use notifications, please see the [getting started with automation page](/getting-started/automation/).
### {% linkable_title Text message %}
```yaml
...
action:
service: notify.NOTIFIER_NAME
data:
title: '*Send a message*'
message: 'That's an example that _sends_ a *formatted* message with a custom keyboard.'
data:
keyboard:
- '/command1, /command2'
- '/command3, /command4'
```
Configuration variables:
- **message** (*Required*): Message text.
- **title** (*Optional*): Will be composed as '%title\n%message'.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.
### {% linkable_title Photo support %}
```yaml
@ -81,10 +111,15 @@ action:
caption: I.e. for a Title
```
Configuration variables:
- **url** or **file** (*Required*): For local or remote path to an image.
- **caption** (*Optional*): The title of the image.
- **username** (*Optional*): Username for a URL which require HTTP basic authentication.
- **password** (*Optional*): Username for a URL which require HTTP basic authentication.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.
### {% linkable_title Document support %}
@ -99,13 +134,16 @@ action:
document:
file: /tmp/whatever.odf
caption: Document Title xy
```
Configuration variables:
- **url** or **file** (*Required*): For local or remote path to a document.
- **caption** (*Optional*): The title of the document.
- **username** (*Optional*): Username for a URL which require HTTP basic authentication.
- **password** (*Optional*): Username for a URL which require HTTP basic authentication.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.
### {% linkable_title Location support %}
@ -123,7 +161,10 @@ action:
longitude: 117.22743
```
Configuration variables:
- **location** (*Required*): For local or remote path to an image.
- **latitude** (*Required*): The latitude to send.
- **longitude** (*Required*): The longitude to send.
- **keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom keyboard.
- **inline_keyboard** (*Optional*): List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data.

15
source/_components/raspihats.markdown Normal file
View file

@ -0,0 +1,15 @@
---
layout: page
title: "Raspihats"
description: "Instructions how to integrate Raspihats add-on boards for Raspberry PI into Home Assistant."
date: 2017-05-01 04:06
sidebar: true
comments: false
sharing: true
footer: true
logo: raspihats.png
ha_category: DIY
ha_release: 0.45
---
The `raspihats` component is the base for all related Raspihats platforms in Home Assistant. There is no setup needed for the component itself, for the platforms please check their corresponding pages.

18
source/_components/remote.kira.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Kira Remote"
description: "Instructions how to integrate Kira modules into Home Assistant."
date: 2017-05-07 17:00
sidebar: true
comments: false
sharing: true
footer: true
logo: keene.png
ha_category: Remote
ha_iot_class: "Assumed State"
ha_release: 0.45
---
The `kira` platform allows you to send IR commands via [Kira](https://www.keene.co.uk/keene-ir-anywhere-single-worldwide.html) modules from within Home Assistant.
For configuration information see the [Kira component](/components/kira/) documentation.

16
source/_components/rpi_pfio.markdown Normal file
View file

@ -0,0 +1,16 @@
---
layout: page
title: "PiFace Digital I/O"
description: "Instructions how to integrate the PiFace Digital I/O module into Home Assistant."
date: 2016-05-08 15:00
sidebar: true
comments: false
sharing: true
footer: true
logo: raspberry-pi.png
ha_category: DIY
ha_release: 0.45
---
The `rpi_pfio` component is the base for all related [PiFace Digital I/O (PFIO)](http://www.piface.org.uk/) platforms in Home Assistant. There is no setup needed for the component itself, for the platforms please check their corresponding pages.

60
source/_components/sensor.file.markdown Normal file
View file

@ -0,0 +1,60 @@
---
layout: page
title: "File Sensor"
description: "Instructions how to integrate sensors which read from files into Home Assistant."
date: 2017-05-13 12:10
sidebar: true
comments: false
sharing: true
footer: true
logo: file.png
ha_category: Sensor
ha_iot_class: "Local Polling"
ha_release: 0.45
---
The `file` sensor platform reading the entries from a plain-text file and shows the found value. Only the last line of the file is used. This is similar to do `$ tail -n 1 sensor.txt` on the command-line.
To enable the `file` sensor, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
sensor:
- platform: file
file_path: /home/user/.homeassistant/sensor-data.txt
```
Configuration variables:
- **file_path** (*Required*): path to file that stores the sensor data.
- **name** (*Optional*): Name of the sensor to use in the frontend. Defaults to `File`.
- **unit_of_measurement** (*Optional*): Defines the units of measurement of the sensor, if any.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
## {% linkable_title Examples %}
In this section you find some real life examples of how to use this sensor.
### {% linkable_title Entries as JSON %}
Assuming that the log file contains multiple values formatted as JSON like shown below:
```text
[...]
{"temperature": 21, "humidity": 39}
{"temperature": 22, "humidity": 36}
```
This would require the following entry in the `configuration.yaml` file to extract the temperature:
```yaml
# Example configuration.yaml entry
sensor:
- platform: file
name: Temperature
file_path: /home/user/.homeassistant/sensor.json
value_template: {% raw %}'{{ value_json.temperature }}'{% endraw %}
unit_of_measurement: '°C'
```

18
source/_components/sensor.kira.markdown Normal file
View file

@ -0,0 +1,18 @@
---
layout: page
title: "Kira Sensor"
description: "Instructions how to integrate Kira modules into Home Assistant."
date: 2017-05-07 17:00
sidebar: true
comments: false
sharing: true
footer: true
logo: keene.png
ha_category: Sensor
ha_iot_class: "Local Push"
ha_release: 0.45
---
The `kira` platform allows you to respond to your [Kira](https://www.keene.co.uk/keene-ir-anywhere-single-worldwide.html) modules from within Home Assistant. This enables Home Assistant to respond to infrared inputs from a standard remote control.
For configuration information see the [Kira component](/components/kira/) documentation.

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

@ -27,7 +27,7 @@ sensor:
```
- **mac** (*Required*): The MAC address of your sensor. You can find this be running `hcitool lescan` from command line.
- **monitored_conditions** array (*Required*): The paramaters that should be monitored.
- **monitored_conditions** array (*Optional*): The paramaters that should be monitored (defaults to monitoring all parameters).
- **moisture**: Moisture in the soil.
- **light**: Brightness at the sensor's location.
- **temperature**: Temperature at the sensor's location.

1
source/_components/sensor.nzbget.markdown
View file

@ -32,6 +32,7 @@ Configuration variables:
- **host** (*Required*): IP address where your NZBGet installation is running.
- **port** (*Optional*): The port of your NZBGet installation. Defaults to 6789.
- **ssl** (*Optional*): Whether or not to use SSL to access NZBGet. Defaults to false.
- **name** (*Optional*): The prefix to use for your sensor. Defaults to NZBGet.
- **username** (*Optional*): The username to access your NZBGet installation.
- **password** (*Optional*): The password to access your NZBGet installation.

47
source/_components/switch.raspihats.markdown Normal file
View file

@ -0,0 +1,47 @@
---
layout: page
title: "Raspihats Switch"
description: "Instructions how to integrate Raspihats add-on boards for Raspberry PI into Home Assistant as a switch."
date: 2017-05-15 04:20
sidebar: true
comments: false
sharing: true
footer: true
logo: raspihats.png
ha_category: Switch
ha_release: 0.45
---
The `raspihats` switch platform allows you to control the digital outputs of your [raspihats](http://www.raspihats.com/) boards.
To use your raspihats boards in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
switch:
- platform: raspihats
i2c_hats:
- board: DI6acDQ6rly
address: 0x60
channels:
- index: 0
name: Fan Office
invert_logic: true
initial_state: true
- index: 1
name: Light Office
```
Configuration variables:
- **i2c_hats** (*Optional*): Array of used I2C-HATs.
- **board** (*Required*): The board name.
- **address** (*Required*): The board I2C address, hex value.
- **channels** (*Required*): Array of used digital output channels.
- **index** (*Required*): Digital output channel index.
- **name** (*Required*): Friendly name to use for the frontend.
- **invert_logic** (*Optional*): Inverts the output logic, default is `False`.
- **initial_state** (*Optional*): Initial state, default is `None`, can also be `True` or `False`. `None` means no state is forced on the corresponding digital output when this switch is instantiated.
For more details about the Raspihats add-on boards for Raspberry PI, visit [raspihats.com](http://www.raspihats.com/).

37
source/_components/switch.rpi_pfio.markdown Normal file
View file

@ -0,0 +1,37 @@
---
layout: page
title: "PiFace Digital I/O Switch"
description: "Instructions how to integrate the PiFace Digital I/O module into Home Assistant as a switch."
date: 2016-05-08 15:00
sidebar: true
comments: false
sharing: true
footer: true
logo: raspberry-pi.png
ha_category: Switch
ha_release: 0.45
---
The `rpi_pfio` switch platform allows you to control the [PiFace Digital I/O](http://www.piface.org.uk/products/piface_digital/) module.
To use your PiFace Digital I/O module in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
switch:
- platform: rpi_pfio
ports:
0:
name: Doorlock
invert_logic: true
1:
name: Light Desk
```
Configuration variables:
- **ports** array (*Required*): Array of used ports.
- **num** (*Required*): Port number.
- **name** (*Required*): Port name.
- **invert_logic** (*Optional*): If true, inverts the output logic to ACTIVE LOW. Default is false (ACTIVE HIGH).

317
source/_components/telegram_bot.markdown
View file

@ -11,12 +11,132 @@ logo: telegram.png
ha_release: 0.42
---
Use Telegram on your mobile device to send messages or commands to your Home Assistant.
Use Telegram on your mobile or desktop device to send and receive messages or commands to/from your Home Assistant.
This component creates notification services to send, or edit previously sent, messages from a [Telegram Bot account](https://core.telegram.org/bots) configured either with the [polling](/_components/telegram_bot.polling.markdown) method or with the [webhooks](/_components/telegram_bot.webhooks.markdown) one, and trigger events when receiving messages.
A command looks like `/thecommand`
### {% linkable_title Notification services %}
Available services: `send_message`, `send_photo`, `send_document`, `send_location`, `edit_message`, `edit_replymarkup`, `edit_caption`, `answer_callback_query`.
When received by hass it will fire a `telegram_command` event on the event bus with the following `event_data`:
#### {% linkable_title Service `telegram_bot/send_message` %}
Send a notification.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `message` | no | Message body of the notification. |
| `title` | yes | Optional title for your notification. Will be composed as '%title\n%message'. |
| `target` | yes | An array of pre-authorized chat_ids to send the notification to. Defaults to the first allowed chat_id. |
| `parse_mode` | yes | Parser for the message text: `html` or `markdown`. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_photo` %}
Send a photo.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `url` | no | Remote path to an image. |
| `file` | no | Local path to an image. |
| `caption` | yes | The title of the image. |
| `username` | yes | Username for a URL which require HTTP basic authentication. |
| `password` | yes | Password for a URL which require HTTP basic authentication. |
| `target` | yes | An array of pre-authorized chat_ids to send the notification to. Defaults to the first allowed chat_id. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_document` %}
Send a document.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `url` | no | Remote path to a document. |
| `file` | no | Local path to a document. |
| `caption` | yes | The title of the document. |
| `username` | yes | Username for a URL which require HTTP basic authentication. |
| `password` | yes | Password for a URL which require HTTP basic authentication. |
| `target` | yes | An array of pre-authorized chat_ids to send the notification to. Defaults to the first allowed chat_id. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/send_location` %}
Send a location.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `latitude` | no | The latitude to send. |
| `longitude` | no | The longitude to send. |
| `target` | yes | An array of pre-authorized chat_ids to send the notification to. Defaults to the first allowed chat_id. |
| `disable_notification` | yes | True/false for send the message silently. iOS users and web users will not receive a notification, Android users will receive a notification with no sound. Defaults to False. |
| `keyboard` | yes | List of rows of commands, comma-separated, to make a custom keyboard. Example: `["/command1, /command2", "/command3"]` |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_message` %}
Edit a previusly sent message in a conversation.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: `{{ trigger.event.data.message.message_id }}`. |
| `chat_id` | no | The chat_id where to edit the message. |
| `message` | no | Message body of the notification. |
| `title` | yes | Optional title for your notification. Will be composed as '%title\n%message'. |
| `parse_mode` | yes | Parser for the message text: `html` or `markdown`. |
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_caption` %}
Edit the caption of a previusly sent message.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: `{{ trigger.event.data.message.message_id }}`. |
| `chat_id` | no | The chat_id where to edit the caption. |
| `caption` | no | Message body of the notification. |
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/edit_replymarkup` %}
Edit the inline keyboard of a previusly sent message.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `message_id` | no | Id of the message to edit. When answering a callback from a pressed button, the id of the origin message is in: `{{ trigger.event.data.message.message_id }}`. |
| `chat_id` | no | The chat_id where to edit the reply_markup. |
| `disable_web_page_preview`| yes | True/false for disable link previews for links in the message. |
| `inline_keyboard` | yes | List of rows of commands, comma-separated, to make a custom inline keyboard with buttons with asociated callback data. Example: `["/button1, /button2", "/button3"]` or `[[["Text btn1", "/button1"], ["Text btn2", "/button2"]], [["Text btn3", "/button3"]]]` |
#### {% linkable_title Service `telegram_bot/answer_callback_query` %}
Respond to a callback query originated by clicking on an online keyboard button. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.
| Service data attribute | Optional | Description |
|---------------------------|----------|--------------------------------------------------|
| `message` | no | Unformatted text message body of the notification. |
| `callback_query_id` | no | Unique id of the callback response. In the `telegram_callback` event data: `{{ trigger.event.data.id }}` |
| `show_alert` | yes | True/false for show a permanent notification. Defaults to False. |
### {% linkable_title `Telegram` notification platform %}
The [Telegram notification platform](/_components/notify.telegram.markdown) requires the `telegram_bot` component to work with, and it's designed to generate a customised shortcut (`notify.USERNAME`) to send notifications (messages, photos, documents and locations) to a particular `chat_id` with the old syntax, allowing backward compatibility.
The required yaml configuration now reduces to:
```yaml
notify:
- name: NOTIFIER_NAME
platform: telegram
chat_id: USER_CHAT_ID
```
### {% linkable_title Event triggering %}
A command looks like `/thecommand`, or `/othercommand with some args`.
When received by Home Assistant it will fire a `telegram_command` event on the event bus with the following `event_data`:
```yaml
command: "/thecommand"
@ -26,13 +146,34 @@ from_last: "<last name of the sender>"
user_id: "<id of the sender>"
```
Any other message not starting with `/` will be processed as simple text, firing a `telegram_text` event on the event bus with the following `event_data`:
```yaml
text: "some text received"
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
```
if the message is sent from a [press from an inline button](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating), for example, a callback query is received, and Home Assistant will fire a `telegram_callback` event with:
```yaml
data: "<data associated to action callback>"
message: <message origin of the action callback>
from_first: "<first name of the sender>"
from_last: "<last name of the sender>"
user_id: "<id of the sender>"
id: "<unique id of the callback>"
chat_instance: "<chat instance>"
```
### {% linkable_title Configuration samples %}
Simple ping pong example.
```yaml
alias: 'telegram bot that reply pong to ping'
alias: 'Telegram bot that reply pong to ping'
hide_entity: true
trigger:
platform: event
@ -95,3 +236,171 @@ An example to show the use of event_data in the action:
message: >
Message from {% raw %}{{ trigger.event.data["from_first"] }}. {% for state in trigger.event.data["args"] %} {{ state }} {% endfor %}{% endraw %}
```
### {% linkable_title Sample automations with callback queries and inline keyboards %}
Quick example to show some of the callback capabilities of inline keyboards with a dumb automation consisting in a simple repeater of normal text that presents an inline keyboard with 3 buttons: 'EDIT', 'NO' and 'REMOVE BUTTON':
- Pressing 'EDIT' changes the sent message.
- Pressing 'NO' only shows a brief notification (answering the callback query).
- Pressing 'REMOVE BUTTON' changes the inline keyboard removing that button.
Text repeater:
```yaml
- alias: 'Telegram bot that repeats text'
hide_entity: true
trigger:
platform: event
event_type: telegram_text
action:
- service: telegram_bot.send_message
data_template:
title: '*Dumb automation*'
target: '{{ trigger.event.data.user_id }}'
message: 'You said: ``` {{ trigger.event.data.text }} ```'
disable_notification: true
inline_keyboard:
- '/edit,/NO'
- '/remove button'
```
Message editor:
```yaml
- alias: 'Telegram bot that edits the last sent message'
hide_entity: true
trigger:
platform: event
event_type: telegram_callback
event_data:
data: '/edit'
action:
- service: telegram_bot.answer_callback_query
data_template:
callback_query_id: '{{ trigger.event.data.id }}'
message: 'Editing the message!'
show_alert: true
- service: telegram_bot.edit_message
data_template:
message_id: '{{ trigger.event.data.message.message_id }}'
chat_id: '{{ trigger.event.data.user_id }}'
title: '*Message edit*'
inline_keyboard:
- '/edit,/NO'
- '/remove button'
message: >
Callback received from {{ trigger.event.data.from_first }}.
Message id: {{ trigger.event.data.message.message_id }}.
Data: ``` {{ trigger.event.data.data }} ```
```
Keyboard editor:
```yaml
- alias: 'Telegram bot that edits the keyboard'
hide_entity: true
trigger:
platform: event
event_type: telegram_callback
event_data:
data: '/remove button'
action:
- service: telegram_bot.answer_callback_query
data_template:
callback_query_id: '{{ trigger.event.data.id }}'
message: 'Callback received for editing the inline keyboard!'
- service: telegram_bot.edit_replymarkup
data_template:
message_id: 'last'
chat_id: '{{ trigger.event.data.user_id }}'
inline_keyboard:
- '/edit,/NO'
```
Only acknowledges the 'NO' answer:
```yaml
- alias: 'Telegram bot that simply acknowledges'
hide_entity: true
trigger:
platform: event
event_type: telegram_callback
event_data:
data: '/NO'
action:
- service: telegram_bot.answer_callback_query
data_template:
callback_query_id: '{{ trigger.event.data.id }}'
message: 'OK, you said no!'
```
For a more complex usage of the `telegram_bot` capabilities, using [AppDaemon](https://home-assistant.io/docs/ecosystem/appdaemon/tutorial/) is advised.
This is how the previous 4 automations would be through a simple AppDaemon app:
```python
import appdaemon.appapi as appapi
class TelegramBotEventListener(appapi.AppDaemon):
"""Event listener for Telegram bot events."""
def initialize(self):
"""Listen to Telegram Bot events of interest."""
self.listen_event(self.receive_telegram_text, 'telegram_text')
self.listen_event(self.receive_telegram_callback, 'telegram_callback')
def receive_telegram_text(self, event_id, payload_event, *args):
"""Text repeater."""
assert event_id == 'telegram_text'
user_id = payload_event['user_id']
msg = 'You said: ``` %s ```' % payload_event['text']
keyboard = ['/edit,/NO', '/remove button']
self.call_service('telegram_bot/send_message',
title='*Dumb automation*',
target=user_id,
message=msg,
disable_notification=True,
inline_keyboard=keyboard)
def receive_telegram_callback(self, event_id, payload_event, *args):
"""Event listener for Telegram callback queries."""
assert event_id == 'telegram_callback'
data_callback = payload_event['data']
callback_id = payload_event['id']
user_id = payload_event['user_id']
if data_callback == '/edit': # Message editor:
# Answer callback query
self.call_service('telegram_bot/answer_callback_query',
message='Editing the message!',
callback_query_id=callback_id,
show_alert=True)
# Edit the message origin of the callback query
msg_id = payload_event['message']['message_id']
user = payload_event['from_first']
title = '*Message edit*'
msg = 'Callback received from %s. Message id: %s. Data: ``` %s ```'
keyboard = ['/edit,/NO', '/remove button']
self.call_service('telegram_bot/edit_message',
chat_id=user_id,
message_id=msg_id,
title=title,
message=msg % (user, msg_id, data_callback),
inline_keyboard=keyboard)
elif data_callback == '/remove button': # Keyboard editor:
# Answer callback query
self.call_service('telegram_bot/answer_callback_query',
message='Callback received for editing the '
'inline keyboard!',
callback_query_id=callback_id)
# Edit the keyboard
new_keyboard = ['/edit,/NO']
self.call_service('telegram_bot/edit_replymarkup',
chat_id=user_id,
message_id='last',
inline_keyboard=new_keyboard)
elif data_callback == '/NO': # Only Answer to callback query
self.call_service('telegram_bot/answer_callback_query',
message='OK, you said no!',
callback_query_id=callback_id)
```

5
source/_components/telegram_bot.polling.markdown
View file

@ -14,7 +14,7 @@ ha_release: 0.42
Telegram chatbot polling implementation.
One of two bot implementations supported by Telegram. Your hass does not have to be exposed to the internet.
One of two bot implementations supported by Telegram. Your Home Assistant does not have to be exposed to the internet.
To integrate this into Home Assistant, add the following section to your `configuration.yaml` file:
@ -33,6 +33,7 @@ Configuration variables:
- **allowed_chat_ids** (*Required*): A list of user in the `user_id` Telegram format enabled to interact to webhook
- **api_key** (*Required*): The API token of your bot.
- **parse_mode** (*Optional*): Default parser for messages if not explicit in message data: 'html' or 'markdown'. Default is 'markdown'.
To get your `chat_id` and `api_key` follow the instructions [here](/components/notify.telegram) .
To get your `chat_id` and `api_key` follow the instructions [here](/components/notify.telegram/).

4
source/_components/telegram_bot.webhooks.markdown
View file

@ -21,11 +21,12 @@ To integrate this into Home Assistant, add the following section to your `config
```yaml
# Example configuration.yaml entry
http:
base_url: <public_url> # the hass https url which is exposed to the internet.
base_url: <public_url> # the Home Assistant https url which is exposed to the internet.
telegram_bot:
platform: webhooks
api_key: telegram api key
parse_mode: html
allowed_chat_ids:
- 12345
- 67890
@ -36,6 +37,7 @@ Configuration variables:
- **allowed_chat_ids** (*Required*): A list of user in the `user_id` Telegram format enabled to interact to webhook
- **api_key** (*Required*): The API token of your bot.
- **trusted_networks** (*Optional*): Telegram server access ACL as list. Defaults to `149.154.167.197-233`.
- **parse_mode** (*Optional*): Default parser for messages if not explicit in message data: 'html' or 'markdown'. Default is 'markdown'.
To get your `chat_id` and `api_key` follow the instructions [here](/components/notify.telegram) .

1
source/_components/tradfri.markdown
View file

@ -64,3 +64,4 @@ Configuration variables:
- **host** (*Required*): The IP address or hostname of your Trådfri gateway.
- **api_key** (*Required*): Can be found listed as Security Key on the back of the Trådfri gateway.
- **allow_tradfri_groups** (*Optional*): (true/false) Enable this to stop Home Assistant from importing the groups defined on the Tradfri bridge.