Update KNX component configuration variable (#6602)

* Update KNX component configuration variable

Update style of KNX component (all the 7 files) documentation to follow new configuration variables description.
Related to #6385.

* Update binary_sensor.knx.markdown

* 🚑 Syntax fix

* 🚑 Tweak after source check

* 🚑 Tweak after suggestion
This commit is contained in:
Klaas Schoute 2018-10-11 20:59:34 +02:00 committed by Franck Nijhof
parent 4f7c62b21f
commit 6577daf37f
7 changed files with 223 additions and 74 deletions

View File

@ -26,13 +26,29 @@ binary_sensor:
address: '6/0/2'
```
Configuration variables:
- **address** (*Required*): KNX group address of the binary sensor.
- **name** (*Optional*): A name for this device used within Home Assistant.
- **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.
- **reset_after** (*Optional*): Reset back to OFF state after specified milliseconds.
{% configuration %}
address:
description: KNX group address of the binary sensor.
required: true
type: string
name:
description: A name for this device used within Home Assistant.
required: false
type: string
device_class:
description: HASS device class e.g., "motion".
required: false
type: string
significant_bit:
description: Specify which significant bit of the KNX value should be used.
required: false
default: 1
type: integer
reset_after:
description: Reset back to OFF state after specified milliseconds.
required: false
type: integer
{% endconfiguration %}
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.
@ -57,10 +73,23 @@ binary_sensor:
service: homeassistant.turn_on
```
Configuration variables:
- **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 [automation rules](/docs/automation/action/).
{% configuration %}
name:
description: A name for this device used within Home Assistant.
required: false
type: string
counter:
description: 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.
required: false
default: 1
type: integer
hook:
description: Indicates if the automation should be executed on what state of the binary sensor. Values are "on" or "off".
required: false
default: "on"
type: string
action:
description: Specify a list of actions analog to the [automation rules](/docs/automation/action/).
required: false
type: list
{% endconfiguration %}

View File

@ -33,17 +33,54 @@ cover:
travelling_time_up: 61
```
Configuration variables:
- **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. If the KNX device has a stop group address you can use that here.
- **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%.
{% configuration %}
name:
description: A name for this device used within Home Assistant.
required: false
default: KNX Cover
type: string
move_long_address:
description: KNX group address for moving the cover full up or down.
required: false
type: string
move_short_address:
description: KNX group address for moving the cover short time up or down. If the KNX device has a stop group address you can use that here.
required: false
type: string
position_address:
description: KNX group address for moving the cover to the dedicated position.
required: false
type: string
position_state_address:
description: Separate KNX group address for requesting the current position of the cover.
required: false
type: string
angle_address:
description: KNX group address for moving the cover to the dedicated angle.
required: false
type: string
angle_state_address:
description: Separate KNX group address for requesting the current angle of cover.
required: false
type: string
travelling_time_down:
description: Time cover needs to travel down in seconds. Needed to calculate the intermediate positions of cover while traveling.
required: false
default: 25
type: integer
travelling_time_up:
description: Time cover needs to travel up in seconds. Needed to calculate the intermediate positions of cover while traveling.
required: false
default: 25
type: integer
invert_position:
description: Set this to true if your actuator report fully closed as 100%.
required: false
default: false
type: boolean
invert_angle:
description: Set this to true if your actuator reports tilt fully closed as 100%.
required: false
default: false
type: boolean
{% endconfiguration %}

View File

@ -23,7 +23,7 @@ The component requires a local KNX/IP interface like the [Weinzierl 730](http://
</p>
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)
@ -47,12 +47,16 @@ Optional, recommended for large KNX installations (>100 devices) and/or if you w
knx:
config_file: '/path/to/xknx.yaml'
```
- **config_file** (*Optional*): The path for XKNX configuration file.
{% configuration %}
config_file:
description: The path for XKNX configuration file.
required: false
type: string
{% endconfiguration %}
If the auto detection of the KNX/IP device does not work you can specify ip/port of the tunneling device:
```yaml
```yaml
knx:
tunneling:
host: '192.168.2.23'
@ -60,9 +64,17 @@ knx:
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.
{% configuration %}
host:
description: Host of the KNX/IP tunneling device.
type: string
port:
description: Port of the KNX/IP tunneling device.
type: integer
local_ip:
description: IP of the local interface.
type: string
{% endconfiguration %}
Explicit connection to a KNX/IP routing device:
@ -73,7 +85,11 @@ knx:
local_ip: '192.168.2.109'
```
- **local_ip**: The local IP address of interface (which should be used for multicasting).
{% configuration %}
local_ip:
description: The local IP address of interface (which should be used for multicasting).
type: string
{% endconfiguration %}
```yaml
knx:
@ -81,9 +97,21 @@ knx:
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** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus.
- **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behavior.
{% configuration %}
fire_event:
description: If set to True, platform will write all received KNX messages to event bus
required: inclusive
type: boolean
fire_event_filter:
description: If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus.
required: inclusive
type: [list, string]
state_updater:
description: The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behavior.
required: false
default: true
type: boolean
{% endconfiguration %}
### {% linkable_title Services %}
@ -91,12 +119,18 @@ In order to directly interact with the KNX bus, you can now use the following se
```
Domain: knx
Service: send
Service: send
Service Data: {"address": "1/0/15", "payload": 0}
```
* **address**: KNX group address
* **payload**: Payload, either an integer or an array of integers
{% configuration %}
address:
description: KNX group address
type: string
payload:
description: Payload, either an integer or an array of integers
type: [integer, list]
{% endconfiguration %}
### {% linkable_title Exposing sensor values or time to knx bus %}
@ -115,11 +149,18 @@ knx:
address: '0/0/23'
```
* **type**: Type of the exposed value. Either time or datetime or any supported type of [KNX Sensor](/components/sensor.knx/) (e.g., "temperature" or "humidity").
* **entity_id**: Entity id of the HASS component to be exposed. Not necessary for types time and datetime.
* **address**: KNX group address.
{% configuration %}
type:
description: Type of the exposed value. Either time or datetime or any supported type of [KNX Sensor](/components/sensor.knx/) (e.g., "temperature" or "humidity").
type: string
entity_id:
description: Entity id of the HASS component to be exposed. Not necessary for types time and datetime.
type: string
address:
description: KNX group address.
type: string
{% endconfiguration %}
### {% linkable_title Known issues %}
Due to lame multicast support the routing abstraction and the gateway scanner only work with Python >=3.5.

View File

@ -9,7 +9,7 @@ sharing: true
footer: true
logo: knx.png
ha_category: Light
ha_release: 0.44
ha_release: 0.44
ha_iot_class: "Local Polling"
---
@ -26,21 +26,39 @@ To use your KNX light in your installation, add the following lines to your `con
# Example configuration.yaml entry
light:
- platform: knx
name: Kitchen-Light-1
address: '1/0/9'
brightness_address: '1/0/11'
```
Configuration variables:
- **address** (*Required*): KNX group address for switching the light on and off.
- **name** (*Optional*): A name for this device used within Home Assistant.
- **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.
- **color_address** (*Optional*): separate KNX group address for setting the color of the light.
- **color_state_address** (*Optional*): separate KNX group address for retrieving the color of the light.
{% configuration %}
address:
description: KNX group address for switching the light on and off.
required: true
type: string
name:
description: A name for this device used within Home Assistant.
required: false
type: string
brightness_address:
description: KNX group address for dimming light.
required: false
type: string
state_address:
description: separate KNX group address for retrieving the switch state of the light.
required: false
type: string
brightness_state_address:
description: separate KNX group address for retrieving the dimmed state of the light.
required: false
type: string
color_address:
description: separate KNX group address for setting the color of the light.
required: false
type: string
color_state_address:
description: separate KNX group address for retrieving the color of the light.
required: false
type: string
{% endconfiguration %}
Some KNX devices can change their state internally without any messages on the KNX 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.

View File

@ -28,8 +28,13 @@ notify:
address: '5/1/10'
```
Configuration variables:
* **address** (*Required*): KNX group address of the notification.
* **name** (*Optional*): A name for this device used within Home Assistant.
{% configuration %}
address:
description: KNX group address of the notification.
required: true
type: string
name:
description: A name for this device used within Home Assistant.
required: false
type: string
{% endconfiguration %}

View File

@ -29,9 +29,17 @@ scene:
scene_number: 23
```
Configuration variables:
- **address** (*Required*): KNX group address of the binary sensor.
- **scene_number** (*Required*): Zero-indexed KNX scene number to be activated.
- **name** (*Optional*): A name for this device used within Home Assistant.
{% configuration %}
address:
description: KNX group address of the binary sensor.
required: true
type: string
scene_number:
description: Zero-indexed KNX scene number to be activated.
required: true
type: integer
name:
description: A name for this device used within Home Assistant.
required: false
type: string
{% endconfiguration %}

View File

@ -13,7 +13,7 @@ ha_release: 0.29
ha_iot_class: "Local Push"
---
The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) sensors.
The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) sensors.
The `knx` component must be configured correctly, see [KNX Component](/components/knx).
@ -30,10 +30,21 @@ sensor:
```
{% configuration %}
address:
description: KNX group address of the sensor.
required: true
type: string
name:
description: A name for this device used within Home Assistant.
required: false
type: string
type:
description: A type from the following table can be defined. The DPT of the group address should match the expected KNX DPT to be parsed correctly.
required: false
type: string
{% endconfiguration %}
- **address** (*Required*): KNX group address of the sensor.
- **name** (*Optional*): A name for this device used within Home Assistant.
- **type** (*Optional*): A type from the following table can be defined. The DPT of the group address should match the expected KNX DPT to be parsed correctly.
| type | unit | expected KNX DPT |
|--------------------|------|------------------|