From 6577daf37ffe044df6e893e8d4f07d98e0355738 Mon Sep 17 00:00:00 2001 From: Klaas Schoute Date: Thu, 11 Oct 2018 20:59:34 +0200 Subject: [PATCH] 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 * :ambulance: Syntax fix * :ambulance: Tweak after source check * :ambulance: Tweak after suggestion --- source/_components/binary_sensor.knx.markdown | 57 ++++++++++---- source/_components/cover.knx.markdown | 65 ++++++++++++---- source/_components/knx.markdown | 77 ++++++++++++++----- source/_components/light.knx.markdown | 44 +++++++---- source/_components/notify.knx.markdown | 15 ++-- source/_components/scene.knx.markdown | 20 +++-- source/_components/sensor.knx.markdown | 19 ++++- 7 files changed, 223 insertions(+), 74 deletions(-) diff --git a/source/_components/binary_sensor.knx.markdown b/source/_components/binary_sensor.knx.markdown index 6f5ff097906..97004e94b8e 100644 --- a/source/_components/binary_sensor.knx.markdown +++ b/source/_components/binary_sensor.knx.markdown @@ -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 %} diff --git a/source/_components/cover.knx.markdown b/source/_components/cover.knx.markdown index d6d3733c1e1..4e43d315cf1 100644 --- a/source/_components/cover.knx.markdown +++ b/source/_components/cover.knx.markdown @@ -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 %} diff --git a/source/_components/knx.markdown b/source/_components/knx.markdown index 802b288f4c2..4f1b5b2c4a1 100644 --- a/source/_components/knx.markdown +++ b/source/_components/knx.markdown @@ -23,7 +23,7 @@ The component requires a local KNX/IP interface like the [Weinzierl 730](http://

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. - diff --git a/source/_components/light.knx.markdown b/source/_components/light.knx.markdown index 4a229b62586..2fc2af1508c 100644 --- a/source/_components/light.knx.markdown +++ b/source/_components/light.knx.markdown @@ -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. - diff --git a/source/_components/notify.knx.markdown b/source/_components/notify.knx.markdown index 4e81f1e2362..72c18e724d4 100644 --- a/source/_components/notify.knx.markdown +++ b/source/_components/notify.knx.markdown @@ -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 %} diff --git a/source/_components/scene.knx.markdown b/source/_components/scene.knx.markdown index 7fd18417d87..95fe53698a7 100644 --- a/source/_components/scene.knx.markdown +++ b/source/_components/scene.knx.markdown @@ -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 %} diff --git a/source/_components/sensor.knx.markdown b/source/_components/sensor.knx.markdown index 3819a6dfdfd..d558d1c3a15 100644 --- a/source/_components/sensor.knx.markdown +++ b/source/_components/sensor.knx.markdown @@ -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 | |--------------------|------|------------------|