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

Documentation for KNX component (#3298)

Browse Source 
* documentation for knx component

* documentation of knx component

* fixed typo

* updated documentation for new HVAC controller status

* fixed spelling
This commit is contained in:
Julius Mittenzwei 2017-09-07 09:41:38 +02:00 committed by Franck Nijhof
parent b12dce2779
commit c3736c2fd9
8 changed files with 256 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
source/_components/binary_sensor.knx.markdown
View File

@ -13,4 +13,48 @@ ha_release: 0.24
ha_iot_class: "Local Polling"
---
To get your KNX binary sensors working with Home Assistant, follow the instructions for the [KNX component](/components/knx/).
The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) binary sensors.
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
```yaml
binary_sensor:
- platform: knx
name: "Entrance.Motion.Sensor"
address: '6/0/2'
device_class: 'motion'
#significant_bit: 2
```
* **name** (*Optional*): A name for this device used within Home Assistant.
* **address**: KNX group address of the binary sensor
* **device_class**: (Optional) HASS device class e.g. "motion"
* **significant_bit**: (Optional) Specify which significant bit of the KNX value should be used. Default is 1.
You can also attach actions to binary sensors (e.g., to switch on a light when a switch was pressed). In this example, one light is switched on when the button was pressed once and two others when the button was pressed a second time.
```yaml
binary_sensor:
- platform: knx
name: Livingroom.3Switch3
address: '5/0/26'
automation:
- counter: 1
hook: 'on'
action:
- entity_id: light.hue_color_lamp_1
service: homeassistant.turn_on
- counter: 2
hook: 'on'
action:
- entity_id: light.hue_bloom_1
service: homeassistant.turn_on
- entity_id: light.hue_bloom_2
service: homeassistant.turn_on
```
- **name** (*Optional*): A name for this device used within Home Assistant.
- **counter**: (*Optional*) Set to 2 if your only want the action to be executed if the button was pressed twice. To 3 for three times button pressed. Defaults to 1.
- **hook**: (Optional): Indicates if the automation should be executed on what state of the binary sensor. Values: "on" or "off". Defaults to "on".
- **action**: Specify a list of actions analog to the [HASS automation rules](https://home-assistant.io/docs/automation/action/).

53
source/_components/climate.knx.markdown
View File

@ -1,6 +1,6 @@
---
layout: page
title: "KNX Thermostat"
title: "KNX Climate"
description: "Instructions on how to integrate KXN thermostats with Home Assistant."
date: 2016-06-24 12:00
sidebar: true
@ -16,22 +16,49 @@ ha_iot_class: "Local Polling"
The `knx` climate platform is used as in interface with KNX thermostats.
KNX thermostats use at least 2 group addresses: one for the current temperature and one for the target temperature (named set-point in KNX terms).
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
To use your KNX thermostats in your installation, add the following to your `configuration.yaml` file:
To use your KNX thermostats in your installation, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
climate:
- platform: knx
address : KNX_ADDRESS
temperature_address: 0/1/1
setpoint_address: 0/1/0
- platform: knx
name: HASS-Kitchen.Temperature
temperature_address: '6/2/1'
setpoint_address: '5/1/2'
target_temperature_address: '5/1/1'
operation_mode_address: '5/1/3'
```
- **address** (*Required*): The KNX group address that is used to turn on/off this actuator channel.
- **temperature_address** (*Required*): The group address that is used to communicate the current temperature. Data format must be datapoint type 9.001 DPT_Value_Temp (2-Octet float value), check [details](http://www.knx.org/fileadmin/template/documents/downloads_support_menu/KNX_tutor_seminar_page/Advanced_documentation/05_Interworking_E1209.pdf).
- **setpoint_address** (*Required*): The group address that is used to set/read the target temperature. Data format must be datapoint type 9.001 DPT_Value_Temp (2-Octet float value). Make sure, you set the read-flag for the thermostat to allow Home Assistant to read the target temperature.
- **name** (*Optional*): A name for this devices used within Home Assistant.
Alternatively, if your device has dedicated binary group addresses for frost/night/comfort mode:
```yaml
climate:
- platform: knx
name: HASS-Kitchen.Temperature
temperature_address: '6/2/1'
setpoint_address: '5/1/2'
target_temperature_address: '5/1/1'
operation_mode_frost_protection_address: '5/1/3'
operation_mode_night_address: '5/1/4'
operation_mode_comfort_address: '5/1/5'
```
* **name** (*Optional*): A name for this device used within Home Assistant.
* **temperature_address**: KNX group address for reading current room temperature from KNX bus.
* **target_temperature_address**: KNX group address for reading current target temperature from KNX bus.
* **setpoint_address**: KNX group address for basis setpoint
* **operation_mode_address** (*Optional*) KNX address for operation mode (Frost protection/night/comfort).
* **operation_mode_state_address** (*Optional*) Explicit KNX address for reading operation mode
* **controller_status_address** (*Optional*) KNX address for HVAC controller status (in accordance with KNX AN 097/07 rev 3)
* **controller_status_state_address** (*Optional*) Explicit KNX address for reading HVAC controller status
* **operation_mode_frost_protection_address** (*Optional*) KNX address for switching on/off frost/heat protection mode.
* **operation_mode_night_address** (*Optional*) KNX address for switching on/off night nmode.
* **operation_mode_comfort_address** (*Optional*) KNX address for switching on/off comfort mode.
`operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` are not necessary if `operation_mode_address` was specified.
With the current version of the module, no advanced KNX thermostat functionalities (e.g. HVAC mode) are supported.

34
source/_components/cover.knx.markdown
View File

@ -16,22 +16,32 @@ ha_iot_class: "Local Polling"
The `knx` cover platform is used as in interface with KNX covers.
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
To use your KNX covers in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: knx
updown_address: 9/0/0
stop_address: 9/0/1
- platform: knx
name: "Kitchen.Shutter"
move_long_address: '3/0/0'
move_short_address: '3/0/1'
position_address: '3/0/3'
position_state_address: '3/0/2'
travelling_time_down: 51
travelling_time_up: 61
```
- **name** (*Optional*): A name for this devices used within Home Assistant.
- **updown_address** (*Required*): The KNX group address that is used to move the cover up and down.
- **stop_address** (*Required*): The group address that is used to stop the cover.
- **setposition_address** (*Optional*): The group address that is used to set the position.
- **getposition_address** (*Optional*): The group address that is used to read the position.
- **setangle_address** (*Optional*): The group address that is used to set the tilt angle.
- **getangle_address** (*Optional*): The group address that is used to read the tilt angle.
- **invert_position** (*Optional*): Set this to true if your actuator report fully closed as 100%
- **invert_angle** (*Optional*): Set this to true if your actuator reports tilt fully closed as 100%
- **name** (*Optional*): A name for this device used within Home Assistant.
- **move_long_address**: KNX group address for moving the cover full up or down.
- **move_short_address**: (*Optional*) KNX group address for moving the cover short time up or down.
- **position_address**: (*Optional*) KNX group address for moving the cover to the dedicated position.
- **position_state_address**: (*Optional*) Separate KNX group address for requesting the current position of the cover.
- **angle_address**: (*Optional*) KNX group address for moving the cover to the dedicated angle.
- **angle_state_address**: (*Optional*) Separate KNX group address for requesting the current angle of cover.
- **travelling_time_down**: (*Optional*) Time cover needs to travel down in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25.
- **travelling_time_up**: (*Optional*) Time cover needs to travel up in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25.
- **invert_position**: (*Optional*) Set this to true if your actuator report fully closed as 100%
- **invert_angle**: (*Optional*) Set this to true if your actuator reports tilt fully closed as 100%

84
source/_components/knx.markdown
View File

@ -13,23 +13,95 @@ ha_release: 0.24
ha_iot_class: "Local Polling"
---
[KNX/EIB](http://www.knx.org) integration for Home Assistant allows you to connect to a KNX bus. The component requires a local KNX/IP interface like the [Weinzierl 730](http://www.weinzierl.de/index.php/en/all-knx/knx-devices-en/knx-ip-interface-730-en). Through this it will send and receive commands to and from other devices to the KNX bus.
Overview
--------
The [KNX](http://www.knx.org) integration for Home Assistant allows you to connect to a KNX/IP devices.
The component requires a local KNX/IP interface like the [Weinzierl 730](http://www.weinzierl.de/index.php/en/all-knx/knx-devices-en/knx-ip-interface-730-en). Through this, it will send and receive commands to and from other devices to the KNX bus.
There is currently support for the following device types within Home Assistant:
- [Binary Sensor](/components/binary_sensor.knx)
- [Cover](/components/cover.knx)
- [Sensor](/components/sensor.knx)
- [Switch](/components/switch.knx)
- [Light](/components/light.knx)
- [Thermostat](/components/climate.knx)
- [Notify](/components/notify.knx)
A `knx` section must be present in the `configuration.yaml` file and contain the following options as required:
Configuration
--------------
To use your KNX in your installation, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
knx:
```
- **host** (*Optional*): The IP address of the KNX/IP interface to use. It defaults to `0.0.0.0` which will start discovery for your KNX/IP gateway.
- **port** (*Optional*): The UDP port number. Defaults to `3671`.
Optional, recommended for large KNX installations (>100 devices) and/or if you want to use the XKNX abstraction also for other scripted tools outside HASS:
```yaml
knx:
config_file: '/path/to/xknx.yaml'
```
* **config_file**: (*Optional*) path for xknx configuration file.
If the auto detection of the KNX/IP device does not work you can specify ip/port of the tunneling device:
```yaml
knx:
tunneling:
host: '192.168.2.23'
port: 3671
local_ip: '192.168.2.109'
```
* **host**: Host of the KNX/IP tunneling device
* **port**: Port of the KNX/IP tunneling device
* **local_ip**: IP of the local interface
Explicit connection to a KNX/IP routing device:
```yaml
knx:
config_file: '/path/to/xknx.yaml'
routing:
local_ip: '192.168.2.109'
```
* **local_ip**: local ip of interface (which should be used for multicasting)
```yaml
knx:
fire_event: True
fire_event_filter: ["1/0/*", "6/2,3,4-6/*"]
```
* **fire_event** (Optional) if set to True, platform will write all received KNX messages to event bus
* **fire_event_filter** 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 HASS event bus.
Service
-------
In order to directly interact with the KNX bus, you can now use the following service:
```
Domain: knx
Service: send
Service Data: {"address": "1/0/15", "payload": 0}
```
* **address** : KNX group address
* **payload** : payload, either an integer or an array of integers
Known issues:
-------------
Due to lame multicast support the routing abstraction and the gateway scanner
only work with python >=3.5.

26
source/_components/light.knx.markdown
View File

@ -16,18 +16,28 @@ ha_iot_class: "Local Polling"
The `knx` light component is used as in interface to switching/light actuators.
To use your KNX light in your installation, add the following to your `configuration.yaml` file:
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
To use your KNX light in your installation, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: knx
name: KNX light
address: 0/0/1
name: Kitchen-Light-1
address: '1/0/9'
brightness_address: '1/0/11'
- platform: knx
name: Kitchen-Light-2
address: '1/0/12'
brightness_address: '1/0/14'
```
- **name** (*Optional*): A name for this devices used within Home assistant
- **address** (*Required*): The KNX group address that is used to turn on/off this actuator channel
- **state_address** (*Optional*): Some KNX devices can change their state internally without any messages on the KXN bus, e.g. if you configure a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object.
For switching/light actuators that are only controlled by a single group address and can't change their state internally, you don't have to configure the state address.
* **name** (*Optional*): A name for this device used within Home Assistant.
* **address**: KNX group address for switching the light on and off
* **brightness_address**: (Optional) KNX group address for dimming light.
* **state_address**: (*Optional*) separate KNX group address for retrieving the switch state of the light.
* **brightness_state_address**: (*Optional*) separate KNX group address for retrieving the dimmed state of the light.
Some KNX devices can change their state internally without any messages on the KXN bus, e.g., if you configure a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object.
For switching/light actuators that are only controlled by a single group address and can't change their state internally, you don't have to configure the state address.

30
source/_components/notify.knx.markdown Normal file
View File

@ -0,0 +1,30 @@
---
layout: page
title: "KNX Notify"
description: "Instructions on how to use the KNX notify with Home Assistant."
date: 2016-09-03 17:00
sidebar: true
comments: false
sharing: true
footer: true
logo: knx.png
ha_category: Notify
ha_release: 0.53
ha_iot_class: "Local Push"
---
The `knx` notify platform allows you to send notifications to [KNX](http://www.knx.org) devices.
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
To use your KNX switch in your installation, add the following lines to your `configuration.yaml` file:
```yaml
notify:
- platform: knx
name: Alarm
address: '5/1/10'
```
* **name** (*Optional*): A name for this device used within Home Assistant.
* **address**: KNX group address of the notification

36
source/_components/sensor.knx.markdown
View File

@ -17,23 +17,20 @@ The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) sensor
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
There is currently support for the following KNX data point types:
| Condition | KNX Datapoint Type | Unit of measurement | Data type |
| :-------------------|:--------------------|:--------------------|:-------------------------------|
| Temperature | 9.001 | °C | 2 Byte Float |
| Speed (Wind speed) | 9.005 | m/s | 2 Byte Float |
| Illuminance (Lux) | 9.004 | Lux | 2 Byte Float |
| Percentage | 5.001 | % | 1 Byte Scaled Unsigned Integer |
To use your KNX sensor in your installation, add the following to your `configuration.yaml` file:
To use your KNX sensor in your installation, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: knx
type: temperature
address: 1/0/3
name: Heating.Valve1
address: '2/0/0'
type: 'percent'
- platform: knx
name: Kitchen.Temperature
address: '6/2/1'
type: 'temperature'
- platform: knx
name: Wind speed
@ -44,18 +41,11 @@ sensor:
name: Lux
type: illuminance
address: 1/0/1
- platform: knx
name: percent
type: percentage
address: 1/0/4
```
Configuration variables:
* **name** (*Optional*): A name for this device used within Home Assistant.
* **address**: KNX group address of the sensor
* **type**: (Optional) "percent", "temperature", "illuminance", "speed_ms", "current"
- **type** (*Required*): The type of the sensor. See table above for available options.
- **address** (*Required*): The address of the sensor on the bus.
- **name** (*Optional*): The name to use in the frontend.
- **minimum** (*Optional*): Minimum sensor value - defaults to a hardcoded default value.
- **maximum** (*Optional*): Maximum sensor value - defaults to a hardcoded default value.

16
source/_components/switch.knx.markdown
View File

@ -16,18 +16,22 @@ ha_iot_class: "Local Polling"
The `knx` switch component is used as in interface to switching actuators.
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
To use your KNX switch in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
switch:
- platform: knx
name: KNX Switch
address: 0/0/1
name: Kitchen.Coffee
address: '1/1/6'
```
* **name** (*Optional*): A name for this device used within Home Assistant.
* **address**: KNX group address for switching the switch on/off
* **state_address**: (*Optional*) separate KNX group address for retrieving the switch state.
- **name** (*Optional*): A name for this devices used within Home assistant
- **address** (*Required*): The KNX group address that is used to turn on/off this actuator channel
- **state_address** (*Optional*): Some KNX devices can change their state internally without any messages on the KXN bus, e.g. if you configure a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object.
Some KNX devices can change their state internally without any messages on the KXN bus, e.g., if you configure a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object.
For switching actuators that are only controlled by a single group address and can't change their state internally, you don't have to configure the state address.