Skip to content

Commit c3736c2

Browse files
Julius2342frenck
Julius2342
authored and
frenck
committed
Documentation for KNX component (home-assistant#3298)
* documentation for knx component * documentation of knx component * fixed typo * updated documentation for new HVAC controller status * fixed spelling
1 parent b12dce2 commit c3736c2

File tree

8 files changed

+256
-69
lines changed

8 files changed

+256
-69
lines changed

‎source/_components/binary_sensor.knx.markdown

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,48 @@ ha_release: 0.24
1313
ha_iot_class: "Local Polling"
1414
---
1515

16-
To get your KNX binary sensors working with Home Assistant, follow the instructions for the [KNX component](/components/knx/).
16+
The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) binary sensors.
17+
18+
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
19+
20+
```yaml
21+
binary_sensor:
22+
- platform: knx
23+
name: "Entrance.Motion.Sensor"
24+
address: '6/0/2'
25+
device_class: 'motion'
26+
#significant_bit: 2
27+
```
28+
29+
* **name** (*Optional*): A name for this device used within Home Assistant.
30+
* **address**: KNX group address of the binary sensor
31+
* **device_class**: (Optional) HASS device class e.g. "motion"
32+
* **significant_bit**: (Optional) Specify which significant bit of the KNX value should be used. Default is 1.
33+
34+
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.
35+
36+
```yaml
37+
binary_sensor:
38+
- platform: knx
39+
name: Livingroom.3Switch3
40+
address: '5/0/26'
41+
automation:
42+
- counter: 1
43+
hook: 'on'
44+
action:
45+
- entity_id: light.hue_color_lamp_1
46+
service: homeassistant.turn_on
47+
- counter: 2
48+
hook: 'on'
49+
action:
50+
- entity_id: light.hue_bloom_1
51+
service: homeassistant.turn_on
52+
- entity_id: light.hue_bloom_2
53+
service: homeassistant.turn_on
54+
```
55+
56+
- **name** (*Optional*): A name for this device used within Home Assistant.
57+
- **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.
58+
- **hook**: (Optional): Indicates if the automation should be executed on what state of the binary sensor. Values: "on" or "off". Defaults to "on".
59+
- **action**: Specify a list of actions analog to the [HASS automation rules](https://home-assistant.io/docs/automation/action/).
60+

‎source/_components/climate.knx.markdown

Lines changed: 40 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
layout: page
3-
title: "KNX Thermostat"
3+
title: "KNX Climate"
44
description: "Instructions on how to integrate KXN thermostats with Home Assistant."
55
date: 2016-06-24 12:00
66
sidebar: true
@@ -16,22 +16,49 @@ ha_iot_class: "Local Polling"
1616

1717
The `knx` climate platform is used as in interface with KNX thermostats.
1818

19-
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).
19+
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
2020

21-
To use your KNX thermostats in your installation, add the following to your `configuration.yaml` file:
21+
To use your KNX thermostats in your installation, add the following lines to your `configuration.yaml` file:
2222

2323
```yaml
24-
# Example configuration.yaml entry
2524
climate:
26-
- platform: knx
27-
address : KNX_ADDRESS
28-
temperature_address: 0/1/1
29-
setpoint_address: 0/1/0
25+
- platform: knx
26+
name: HASS-Kitchen.Temperature
27+
temperature_address: '6/2/1'
28+
setpoint_address: '5/1/2'
29+
target_temperature_address: '5/1/1'
30+
operation_mode_address: '5/1/3'
3031
```
3132
32-
- **address** (*Required*): The KNX group address that is used to turn on/off this actuator channel.
33-
- **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).
34-
- **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.
35-
- **name** (*Optional*): A name for this devices used within Home Assistant.
33+
Alternatively, if your device has dedicated binary group addresses for frost/night/comfort mode:
34+
35+
```yaml
36+
climate:
37+
- platform: knx
38+
name: HASS-Kitchen.Temperature
39+
temperature_address: '6/2/1'
40+
setpoint_address: '5/1/2'
41+
target_temperature_address: '5/1/1'
42+
operation_mode_frost_protection_address: '5/1/3'
43+
operation_mode_night_address: '5/1/4'
44+
operation_mode_comfort_address: '5/1/5'
45+
```
46+
47+
48+
* **name** (*Optional*): A name for this device used within Home Assistant.
49+
* **temperature_address**: KNX group address for reading current room temperature from KNX bus.
50+
* **target_temperature_address**: KNX group address for reading current target temperature from KNX bus.
51+
* **setpoint_address**: KNX group address for basis setpoint
52+
53+
* **operation_mode_address** (*Optional*) KNX address for operation mode (Frost protection/night/comfort).
54+
* **operation_mode_state_address** (*Optional*) Explicit KNX address for reading operation mode
55+
* **controller_status_address** (*Optional*) KNX address for HVAC controller status (in accordance with KNX AN 097/07 rev 3)
56+
* **controller_status_state_address** (*Optional*) Explicit KNX address for reading HVAC controller status
57+
58+
* **operation_mode_frost_protection_address** (*Optional*) KNX address for switching on/off frost/heat protection mode.
59+
* **operation_mode_night_address** (*Optional*) KNX address for switching on/off night nmode.
60+
* **operation_mode_comfort_address** (*Optional*) KNX address for switching on/off comfort mode.
61+
62+
`operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` are not necessary if `operation_mode_address` was specified.
63+
3664

37-
With the current version of the module, no advanced KNX thermostat functionalities (e.g. HVAC mode) are supported.

‎source/_components/cover.knx.markdown

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,22 +16,32 @@ ha_iot_class: "Local Polling"
1616

1717
The `knx` cover platform is used as in interface with KNX covers.
1818

19+
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
20+
1921
To use your KNX covers in your installation, add the following to your `configuration.yaml` file:
2022

2123
```yaml
2224
# Example configuration.yaml entry
2325
cover:
24-
- platform: knx
25-
updown_address: 9/0/0
26-
stop_address: 9/0/1
26+
- platform: knx
27+
name: "Kitchen.Shutter"
28+
move_long_address: '3/0/0'
29+
move_short_address: '3/0/1'
30+
position_address: '3/0/3'
31+
position_state_address: '3/0/2'
32+
travelling_time_down: 51
33+
travelling_time_up: 61
2734
```
2835
29-
- **name** (*Optional*): A name for this devices used within Home Assistant.
30-
- **updown_address** (*Required*): The KNX group address that is used to move the cover up and down.
31-
- **stop_address** (*Required*): The group address that is used to stop the cover.
32-
- **setposition_address** (*Optional*): The group address that is used to set the position.
33-
- **getposition_address** (*Optional*): The group address that is used to read the position.
34-
- **setangle_address** (*Optional*): The group address that is used to set the tilt angle.
35-
- **getangle_address** (*Optional*): The group address that is used to read the tilt angle.
36-
- **invert_position** (*Optional*): Set this to true if your actuator report fully closed as 100%
37-
- **invert_angle** (*Optional*): Set this to true if your actuator reports tilt fully closed as 100%
36+
- **name** (*Optional*): A name for this device used within Home Assistant.
37+
- **move_long_address**: KNX group address for moving the cover full up or down.
38+
- **move_short_address**: (*Optional*) KNX group address for moving the cover short time up or down.
39+
- **position_address**: (*Optional*) KNX group address for moving the cover to the dedicated position.
40+
- **position_state_address**: (*Optional*) Separate KNX group address for requesting the current position of the cover.
41+
- **angle_address**: (*Optional*) KNX group address for moving the cover to the dedicated angle.
42+
- **angle_state_address**: (*Optional*) Separate KNX group address for requesting the current angle of cover.
43+
- **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.
44+
- **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.
45+
- **invert_position**: (*Optional*) Set this to true if your actuator report fully closed as 100%
46+
- **invert_angle**: (*Optional*) Set this to true if your actuator reports tilt fully closed as 100%
47+

‎source/_components/knx.markdown

Lines changed: 78 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,95 @@ ha_release: 0.24
1313
ha_iot_class: "Local Polling"
1414
---
1515

16-
[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.
16+
Overview
17+
--------
1718

18-
There is currently support for the following device types within Home Assistant:
19+
The [KNX](http://www.knx.org) integration for Home Assistant allows you to connect to a KNX/IP devices.
20+
21+
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.
1922

23+
There is currently support for the following device types within Home Assistant:
24+
2025
- [Binary Sensor](/components/binary_sensor.knx)
2126
- [Cover](/components/cover.knx)
2227
- [Sensor](/components/sensor.knx)
2328
- [Switch](/components/switch.knx)
2429
- [Light](/components/light.knx)
2530
- [Thermostat](/components/climate.knx)
31+
- [Notify](/components/notify.knx)
32+
33+
Configuration
34+
--------------
35+
36+
To use your KNX in your installation, add the following lines to your `configuration.yaml` file:
2637

27-
A `knx` section must be present in the `configuration.yaml` file and contain the following options as required:
38+
```yaml
39+
knx:
40+
```
41+
42+
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:
2843
2944
```yaml
30-
# Example configuration.yaml entry
3145
knx:
46+
config_file: '/path/to/xknx.yaml'
3247
```
48+
* **config_file**: (*Optional*) path for xknx configuration file.
49+
50+
If the auto detection of the KNX/IP device does not work you can specify ip/port of the tunneling device:
51+
52+
```yaml
53+
knx:
54+
tunneling:
55+
host: '192.168.2.23'
56+
port: 3671
57+
local_ip: '192.168.2.109'
58+
```
59+
* **host**: Host of the KNX/IP tunneling device
60+
* **port**: Port of the KNX/IP tunneling device
61+
* **local_ip**: IP of the local interface
62+
63+
Explicit connection to a KNX/IP routing device:
64+
65+
```yaml
66+
knx:
67+
config_file: '/path/to/xknx.yaml'
68+
routing:
69+
local_ip: '192.168.2.109'
70+
```
71+
* **local_ip**: local ip of interface (which should be used for multicasting)
72+
73+
```yaml
74+
knx:
75+
fire_event: True
76+
fire_event_filter: ["1/0/*", "6/2,3,4-6/*"]
77+
```
78+
79+
* **fire_event** (Optional) if set to True, platform will write all received KNX messages to event bus
80+
* **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.
81+
82+
83+
84+
Service
85+
-------
86+
87+
In order to directly interact with the KNX bus, you can now use the following service:
88+
89+
```
90+
Domain: knx
91+
Service: send
92+
Service Data: {"address": "1/0/15", "payload": 0}
93+
```
94+
95+
* **address** : KNX group address
96+
* **payload** : payload, either an integer or an array of integers
97+
98+
99+
100+
Known issues:
101+
-------------
102+
103+
Due to lame multicast support the routing abstraction and the gateway scanner
104+
only work with python >=3.5.
105+
106+
33107

34-
- **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.
35-
- **port** (*Optional*): The UDP port number. Defaults to `3671`.

‎source/_components/light.knx.markdown

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,28 @@ ha_iot_class: "Local Polling"
1616

1717
The `knx` light component is used as in interface to switching/light actuators.
1818

19-
To use your KNX light in your installation, add the following to your `configuration.yaml` file:
19+
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
20+
21+
To use your KNX light in your installation, add the following lines to your `configuration.yaml` file:
2022

2123
```yaml
22-
# Example configuration.yaml entry
2324
light:
2425
- platform: knx
25-
name: KNX light
26-
address: 0/0/1
26+
name: Kitchen-Light-1
27+
address: '1/0/9'
28+
brightness_address: '1/0/11'
29+
30+
- platform: knx
31+
name: Kitchen-Light-2
32+
address: '1/0/12'
33+
brightness_address: '1/0/14'
2734
```
2835
29-
- **name** (*Optional*): A name for this devices used within Home assistant
30-
- **address** (*Required*): The KNX group address that is used to turn on/off this actuator channel
31-
- **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.
32-
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.
36+
* **name** (*Optional*): A name for this device used within Home Assistant.
37+
* **address**: KNX group address for switching the light on and off
38+
* **brightness_address**: (Optional) KNX group address for dimming light.
39+
* **state_address**: (*Optional*) separate KNX group address for retrieving the switch state of the light.
40+
* **brightness_state_address**: (*Optional*) separate KNX group address for retrieving the dimmed state of the light.
3341
42+
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.
43+
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.

‎source/_components/notify.knx.markdown

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
layout: page
3+
title: "KNX Notify"
4+
description: "Instructions on how to use the KNX notify with Home Assistant."
5+
date: 2016-09-03 17:00
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: knx.png
11+
ha_category: Notify
12+
ha_release: 0.53
13+
ha_iot_class: "Local Push"
14+
---
15+
16+
The `knx` notify platform allows you to send notifications to [KNX](http://www.knx.org) devices.
17+
18+
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
19+
20+
To use your KNX switch in your installation, add the following lines to your `configuration.yaml` file:
21+
22+
```yaml
23+
notify:
24+
- platform: knx
25+
name: Alarm
26+
address: '5/1/10'
27+
```
28+
29+
* **name** (*Optional*): A name for this device used within Home Assistant.
30+
* **address**: KNX group address of the notification

‎source/_components/sensor.knx.markdown

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,23 +17,20 @@ The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) sensor
1717

1818
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
1919

20-
There is currently support for the following KNX data point types:
21-
22-
| Condition | KNX Datapoint Type | Unit of measurement | Data type |
23-
| :-------------------|:--------------------|:--------------------|:-------------------------------|
24-
| Temperature | 9.001 | °C | 2 Byte Float |
25-
| Speed (Wind speed) | 9.005 | m/s | 2 Byte Float |
26-
| Illuminance (Lux) | 9.004 | Lux | 2 Byte Float |
27-
| Percentage | 5.001 | % | 1 Byte Scaled Unsigned Integer |
28-
29-
To use your KNX sensor in your installation, add the following to your `configuration.yaml` file:
20+
To use your KNX sensor in your installation, add the following lines to your `configuration.yaml` file:
3021

3122
```yaml
3223
# Example configuration.yaml entry
3324
sensor:
3425
- platform: knx
35-
type: temperature
36-
address: 1/0/3
26+
name: Heating.Valve1
27+
address: '2/0/0'
28+
type: 'percent'
29+
30+
- platform: knx
31+
name: Kitchen.Temperature
32+
address: '6/2/1'
33+
type: 'temperature'
3734

3835
- platform: knx
3936
name: Wind speed
@@ -44,18 +41,11 @@ sensor:
4441
name: Lux
4542
type: illuminance
4643
address: 1/0/1
47-
48-
- platform: knx
49-
name: percent
50-
type: percentage
51-
address: 1/0/4
5244
```
5345
54-
Configuration variables:
46+
* **name** (*Optional*): A name for this device used within Home Assistant.
47+
* **address**: KNX group address of the sensor
48+
* **type**: (Optional) "percent", "temperature", "illuminance", "speed_ms", "current"
49+
5550
56-
- **type** (*Required*): The type of the sensor. See table above for available options.
57-
- **address** (*Required*): The address of the sensor on the bus.
58-
- **name** (*Optional*): The name to use in the frontend.
59-
- **minimum** (*Optional*): Minimum sensor value - defaults to a hardcoded default value.
60-
- **maximum** (*Optional*): Maximum sensor value - defaults to a hardcoded default value.
6151

0 commit comments

Comments
 (0)