From ade9374a2243cad196eda5de1ffcb10fa358f0a9 Mon Sep 17 00:00:00 2001 From: Matthias Alphart Date: Sat, 19 Sep 2020 09:32:20 +0200 Subject: [PATCH] Update documentation of KNX sync_state and expected DPTs (#14482) --- .../_integrations/binary_sensor.knx.markdown | 21 +++------------- source/_integrations/climate.knx.markdown | 20 ++++++--------- source/_integrations/cover.knx.markdown | 22 ++++++---------- source/_integrations/knx.markdown | 25 +++++++++---------- source/_integrations/light.knx.markdown | 8 +----- source/_integrations/notify.knx.markdown | 10 ++------ source/_integrations/scene.knx.markdown | 10 ++------ source/_integrations/sensor.knx.markdown | 17 +++++-------- source/_integrations/switch.knx.markdown | 12 +++------ source/_integrations/weather.knx.markdown | 8 +----- 10 files changed, 46 insertions(+), 107 deletions(-) diff --git a/source/_integrations/binary_sensor.knx.markdown b/source/_integrations/binary_sensor.knx.markdown index 0f36a5cace0..054e64f5071 100644 --- a/source/_integrations/binary_sensor.knx.markdown +++ b/source/_integrations/binary_sensor.knx.markdown @@ -8,21 +8,13 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` sensor platform allows you to monitor [KNX](https://www.knx.org/) binary sensors. Binary sensors are read-only. To write to the knx-bus configure an exposure [KNX Integration - Expose](/integrations/knx/#exposing-sensor-values-or-time-to-knx-bus). ## Configuration -The `knx` integration must be configured correctly, see [KNX Integration](/integrations/knx). - -To use your binary sensors please add the relevant configuration to your top level KNX configuration key in `configuration.yaml`: +To use your binary sensors please add the relevant configuration to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml knx: @@ -33,7 +25,7 @@ knx: {% configuration %} state_address: - description: KNX group address of the binary sensor. + description: KNX group address of the binary sensor. *DPT 1* required: true type: string name: @@ -41,19 +33,14 @@ name: required: false type: string sync_state: - description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. + description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire ` to read the state from the KNX bus when no telegram was received for \ or `every ` to update it regularly every \. Maximum value for \ is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `True` which is interpreted as "expire 60". required: false - type: boolean + type: [boolean, string, integer] default: True device_class: description: Sets the [class of the device](/integrations/binary_sensor/), changing the device state and icon that is displayed on the frontend. required: false type: string -significant_bit: - description: Specify which significant bit of the KNX value should be used. - required: false - type: integer - default: 1 reset_after: description: Reset back to OFF state after specified milliseconds. required: false diff --git a/source/_integrations/climate.knx.markdown b/source/_integrations/climate.knx.markdown index 85ab0f5b742..e38c6e19903 100644 --- a/source/_integrations/climate.knx.markdown +++ b/source/_integrations/climate.knx.markdown @@ -8,15 +8,9 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` climate platform is used as an interface to KNX thermostats and room controllers. -To use your KNX thermostats in your installation, add the following lines to your top level KNX configuration key in `configuration.yaml`: +To use your KNX thermostats in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -194,19 +188,19 @@ heat_cool_state_address: required: false type: string operation_mode_frost_protection_address: - description: KNX address for switching on/off frost/heat protection mode. + description: KNX address for switching on/off frost/heat protection mode. *DPT 1* required: false type: string operation_mode_night_address: - description: KNX address for switching on/off night mode. + description: KNX address for switching on/off night mode. *DPT 1* required: false type: string operation_mode_comfort_address: - description: KNX address for switching on/off comfort mode. + description: KNX address for switching on/off comfort mode. *DPT 1* required: false type: string operation_mode_standby_address: - description: KNX address for switching on/off standby mode. + description: KNX address for switching on/off standby mode. *DPT 1* required: false type: string operation_modes: @@ -214,7 +208,7 @@ operation_modes: required: false type: list on_off_address: - description: KNX address for switching the climate device on/off. + description: KNX address for switching the climate device on/off. *DPT 1* required: false type: string on_off_invert: @@ -223,7 +217,7 @@ on_off_invert: default: false type: boolean on_off_state_address: - description: KNX address for gathering the current state (on/off) of the climate device. + description: KNX address for gathering the current state (on/off) of the climate device. *DPT 1* required: false type: string min_temp: diff --git a/source/_integrations/cover.knx.markdown b/source/_integrations/cover.knx.markdown index 95649599339..c44d06f8374 100644 --- a/source/_integrations/cover.knx.markdown +++ b/source/_integrations/cover.knx.markdown @@ -8,15 +8,9 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` cover platform is used as an interface to KNX covers. -To use your KNX covers in your installation, add the following to your `configuration.yaml` file: +To use your KNX covers in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -39,31 +33,31 @@ name: default: KNX Cover type: string move_long_address: - description: KNX group address for moving the cover full up or down. + description: KNX group address for moving the cover full up or down. *DPT 1* required: false type: string move_short_address: - description: KNX group address for moving the cover short time up or down. + description: KNX group address for moving the cover short time up or down. *DPT 1* required: false type: string stop_address: - description: KNX group address for stopping the current movement from the cover. + description: KNX group address for stopping the current movement from the cover. *DPT 1* required: false type: string position_address: - description: KNX group address for moving the cover to the dedicated position. + description: KNX group address for moving the cover to the dedicated position. *DPT 5.001* required: false type: string position_state_address: - description: Separate KNX group address for requesting the current position of the cover. + description: Separate KNX group address for requesting the current position of the cover. *DPT 5.001* required: false type: string angle_address: - description: KNX group address for moving the cover to the dedicated angle. + description: KNX group address for moving the cover to the dedicated angle. *DPT 5.001* required: false type: string angle_state_address: - description: Separate KNX group address for requesting the current angle of cover. + description: Separate KNX group address for requesting the current angle of cover. *DPT 5.001* required: false type: string travelling_time_down: diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 58a7fe3dd6c..a13d3f3c764 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -35,7 +35,7 @@ There is currently support for the following device types within Home Assistant: - [Weather](/integrations/weather.knx) -## Configuration +## Basic Configuration To use your KNX bus in your installation, add the following lines to your `configuration.yaml` file: @@ -90,7 +90,7 @@ knx: {% configuration %} host: - description: Host of the KNX/IP tunneling device. + description: IP address of the KNX/IP tunneling device. type: string required: true port: @@ -98,7 +98,7 @@ port: type: integer required: false local_ip: - description: IP of the local interface. + description: IP address of the local interface. type: string required: false {% endconfiguration %} @@ -113,7 +113,7 @@ knx: {% configuration %} local_ip: - description: The local IP address of interface (which should be used for multicasting). + description: The local IP address of the interface that shall be used to send multicast packets. type: string required: true {% endconfiguration %} @@ -141,7 +141,7 @@ state_updater: type: boolean {% endconfiguration %} -### Services +## Services In order to directly interact with the KNX bus, you can use the following service: @@ -156,17 +156,16 @@ address: description: KNX group address type: string payload: - description: Payload, either an integer or an array of integers + description: Payload to send to the bus. When `type` is not set, raw bytes are sent. Integers are then treated as DPT 1/2/3 payloads. For DPTs > 6 bits send a list. Each value represents 1 octet (0-255). Pad with 0 to DPT byte length. type: [integer, list] type: - description: If set, the payload will not be sent as raw bytes, but encoded as given DPT. KNX sensor types are valid values. - required: false - type: string + description: If set, the payload will not be sent as raw bytes, but encoded as given DPT. KNX sensor types are valid values - see table in [KNX Sensor](/integrations/sensor.knx). + type: [string, integer, float] {% endconfiguration %} You can also use the `homeassistant.update_entity` service call to issue GroupValueRead requests for all `*state_address` of a device. -### Exposing entity states, entity attributes or time to KNX bus +## Exposing entity states, entity attributes or time to KNX bus KNX integration is able to expose entity states or attributes to KNX bus. The integration will broadcast any change of the exposed value to the KNX bus and answer read requests to the specified group address. It is also possible to expose the current time. @@ -208,13 +207,13 @@ entity_id: type: string required: false attribute: - description: Attribute of the entity that shall be sent to the KNX bus. If not set (or `None`) the state will be sent. + description: Attribute of the entity that shall be sent to the KNX bus. If not set (or `None`) the state will be sent. Eg. for a light the state is eigther "on" or "off" - with attribute you can expose its "brightness". type: string required: false default: - description: Default value to send to the bus if the state or attribute value is `None`. - Eg. a light with state "off" has no brightness attribute so a default value of `0` could be used. + description: Default value to send to the bus if the state or attribute value is `None`. + Eg. a light with state "off" has no brightness attribute so a default value of `0` could be used. If not set (or `None`) no value would be sent to the bus and a GroupReadRequest to the address would return the last known value. type: [boolean, string, integer, float] default: None diff --git a/source/_integrations/light.knx.markdown b/source/_integrations/light.knx.markdown index 3208f1440af..22cf1510fc7 100644 --- a/source/_integrations/light.knx.markdown +++ b/source/_integrations/light.knx.markdown @@ -8,12 +8,6 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx light` integration is used as an interface to control KNX actuators for lighting applications such as: - switching actuators @@ -23,7 +17,7 @@ The `knx light` integration is used as an interface to control KNX actuators for ## Configuration -To use your KNX light in your installation, add the following lines to your `configuration.yaml` file: +To use your KNX light in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry diff --git a/source/_integrations/notify.knx.markdown b/source/_integrations/notify.knx.markdown index 71145cfcd4f..2b8f344ba40 100644 --- a/source/_integrations/notify.knx.markdown +++ b/source/_integrations/notify.knx.markdown @@ -8,17 +8,11 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` notify platform allows you to send notifications to [KNX](https://www.knx.org/) devices. ## Configuration -To use your KNX switch in your installation, add the following lines to your `configuration.yaml` file: +To use your KNX switch in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml knx: @@ -29,7 +23,7 @@ knx: {% configuration %} address: - description: KNX group address of the notification. + description: KNX group address of the notification. *DPT 16.000* required: true type: string name: diff --git a/source/_integrations/scene.knx.markdown b/source/_integrations/scene.knx.markdown index 5f1602cde5b..4a99b63ba86 100644 --- a/source/_integrations/scene.knx.markdown +++ b/source/_integrations/scene.knx.markdown @@ -7,17 +7,11 @@ ha_release: 0.63 ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` scenes platform allows you to trigger [KNX](https://www.knx.org/) scenes. ## Configuration -To use your KNX scence in your installation, add the following to your `configuration.yaml` file: +To use your KNX scence in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -30,7 +24,7 @@ knx: {% configuration %} address: - description: KNX group address for the scene. + description: KNX group address for the scene. *DPT 17.001* required: true type: string scene_number: diff --git a/source/_integrations/sensor.knx.markdown b/source/_integrations/sensor.knx.markdown index ad8d19cd880..935204d6b85 100644 --- a/source/_integrations/sensor.knx.markdown +++ b/source/_integrations/sensor.knx.markdown @@ -8,20 +8,14 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- -The `knx` sensor platform allows you to monitor [KNX](https://www.knx.org/) sensors. +The `knx` sensor platform allows you to monitor [KNX](https://www.knx.org/) sensors. Sensors are read-only. To write to the knx-bus configure an exposure [KNX Integration - Expose](/integrations/knx/#exposing-sensor-values-or-time-to-knx-bus). ## Configuration -To use your KNX sensor in your installation, add the following lines to your `configuration.yaml` file: +To use your KNX sensor in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -39,7 +33,7 @@ knx: sensor: - name: Heating.Valve1 state_address: '2/0/0' - sync_state: 30 + sync_state: expire 30 ``` {% configuration %} @@ -52,7 +46,7 @@ name: required: false type: string sync_state: - description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. You can also define in seconds between 2 and 1440 how often the state update should take place. + description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire ` to read the state from the KNX bus when no telegram was received for \ or `every ` to update it regularly every \. Maximum value for \ is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `True` which is interpreted as "expire 60". required: false type: [boolean, string, integer] default: True @@ -210,9 +204,10 @@ knx: sensor: - name: Heating.Valve1 state_address: '2/0/0' + sync_state: init type: 'percent' - name: Kitchen.Temperature state_address: '6/2/1' - sync_state: False + sync_state: every 60 type: 'temperature' ``` diff --git a/source/_integrations/switch.knx.markdown b/source/_integrations/switch.knx.markdown index f57826d8084..2ba783165c6 100644 --- a/source/_integrations/switch.knx.markdown +++ b/source/_integrations/switch.knx.markdown @@ -8,17 +8,11 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` switch platform is used as an interface to switching actuators. ## Configuration -To use your KNX switch in your installation, add the following to your `configuration.yaml` file: +To use your KNX switch in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml knx: @@ -29,7 +23,7 @@ knx: {% configuration %} address: - description: KNX group address for switching the switch on/off. + description: KNX group address for switching the switch on/off. *DPT 1* required: true type: string name: @@ -38,7 +32,7 @@ name: default: KNX Switch type: string state_address: - description: Separate KNX group address for retrieving the switch state. + description: Separate KNX group address for retrieving the switch state. *DPT 1* required: false type: string {% endconfiguration %} diff --git a/source/_integrations/weather.knx.markdown b/source/_integrations/weather.knx.markdown index c6f6d35ddf7..a0ee0c13288 100644 --- a/source/_integrations/weather.knx.markdown +++ b/source/_integrations/weather.knx.markdown @@ -8,15 +8,9 @@ ha_iot_class: Local Push ha_domain: knx --- -
- -The `knx` integration must be configured correctly to use this integration, see [KNX Integration](/integrations/knx). - -
- The `knx` weather platform is used as an interface to KNX weather stations. -To use your KNX weather station in your installation, add the following lines to your top level KNX configuration key in `configuration.yaml`: +To use your KNX weather station in your installation, add the following lines to your top level [KNX Integration](/integrations/knx) configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry