From 1d1fe64d7dcffa3eb1ef08e68d150e7624ad9386 Mon Sep 17 00:00:00 2001 From: Marvin Wichmann Date: Mon, 31 Aug 2020 10:57:35 +0200 Subject: [PATCH] Update documentation of KNX integration (#14299) Co-authored-by: Matthias Alphart --- .../_integrations/binary_sensor.knx.markdown | 44 ++++--- source/_integrations/climate.knx.markdown | 123 ++++++++++++------ source/_integrations/cover.knx.markdown | 29 +++-- source/_integrations/knx.markdown | 22 +++- source/_integrations/light.knx.markdown | 78 ++++++----- source/_integrations/notify.knx.markdown | 8 +- source/_integrations/scene.knx.markdown | 10 +- source/_integrations/sensor.knx.markdown | 42 +++--- source/_integrations/switch.knx.markdown | 8 +- 9 files changed, 222 insertions(+), 142 deletions(-) diff --git a/source/_integrations/binary_sensor.knx.markdown b/source/_integrations/binary_sensor.knx.markdown index 89ceea46cb0..0f36a5cace0 100644 --- a/source/_integrations/binary_sensor.knx.markdown +++ b/source/_integrations/binary_sensor.knx.markdown @@ -22,11 +22,13 @@ Binary sensors are read-only. To write to the knx-bus configure an exposure [KNX 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`: + ```yaml -# Example configuration.yaml entry -binary_sensor: - - platform: knx - state_address: '6/0/2' +knx: + binary_sensor: + - name: sensor1 + state_address: '6/0/2' ``` {% configuration %} @@ -64,23 +66,23 @@ You can also attach actions to binary sensors (e.g., to switch on a light when a ```yaml # Example configuration.yaml entry -binary_sensor: - - platform: knx - name: Livingroom.3Switch3 - state_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 +knx: + binary_sensor: + - name: Livingroom.3Switch3 + state_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 ``` {% configuration %} diff --git a/source/_integrations/climate.knx.markdown b/source/_integrations/climate.knx.markdown index 96f14c4eb97..85ab0f5b742 100644 --- a/source/_integrations/climate.knx.markdown +++ b/source/_integrations/climate.knx.markdown @@ -16,36 +16,36 @@ The `knx` integration must be configured correctly to use this integration, see 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 `configuration.yaml` file: +To use your KNX thermostats in your installation, add the following lines to your top level KNX configuration key in `configuration.yaml`: ```yaml # Example configuration.yaml entry -climate: - - platform: knx - name: HASS-Kitchen.Temperature - temperature_address: '5/1/1' - setpoint_shift_address: '5/1/2' - setpoint_shift_state_address: '5/1/3' - target_temperature_state_address: '5/1/4' - operation_mode_address: '5/1/5' - operation_mode_state_address: '5/1/6' +knx: + climate: + - name: HASS-Kitchen.Temperature + temperature_address: '5/1/1' + setpoint_shift_address: '5/1/2' + setpoint_shift_state_address: '5/1/3' + target_temperature_state_address: '5/1/4' + operation_mode_address: '5/1/5' + operation_mode_state_address: '5/1/6' ``` Alternatively, if your device has dedicated binary group addresses for frost/night/comfort mode: ```yaml # Example configuration.yaml entry -climate: - - platform: knx - name: HASS-Kitchen.Temperature - temperature_address: '5/1/1' - setpoint_shift_address: '5/1/2' - setpoint_shift_state_address: '5/1/3' - target_temperature_state_address: '5/1/4' - operation_mode_frost_protection_address: '5/1/5' - operation_mode_night_address: '5/1/6' - operation_mode_comfort_address: '5/1/7' - operation_mode_state_address: '5/1/8' +knx: + climate: + - name: HASS-Kitchen.Temperature + temperature_address: '5/1/1' + setpoint_shift_address: '5/1/2' + setpoint_shift_state_address: '5/1/3' + target_temperature_state_address: '5/1/4' + operation_mode_frost_protection_address: '5/1/5' + operation_mode_night_address: '5/1/6' + operation_mode_comfort_address: '5/1/7' + operation_mode_state_address: '5/1/8' ``` If your device doesn't support setpoint_shift calculations (i.e., if you don't provide a `setpoint_shift_address` value) please set the `min_temp` and `max_temp` @@ -54,23 +54,50 @@ to the configuration in this case.: ```yaml # Example configuration.yaml entry -climate: - - platform: knx - name: HASS-Kitchen.Temperature - temperature_address: '5/1/2' - target_temperature_address: '5/1/4' - target_temperature_state_address: '5/1/1' - operation_mode_frost_protection_address: '5/1/5' - operation_mode_night_address: '5/1/6' - operation_mode_comfort_address: '5/1/7' - operation_mode_state_address: '5/1/8' - min_temp: 7.0 - max_temp: 32.0 +knx: + climate: + - name: HASS-Kitchen.Temperature + temperature_address: '5/1/2' + target_temperature_address: '5/1/4' + target_temperature_state_address: '5/1/1' + operation_mode_frost_protection_address: '5/1/5' + operation_mode_night_address: '5/1/6' + operation_mode_comfort_address: '5/1/7' + operation_mode_state_address: '5/1/8' + operation_mode_standby_address: '5/1/9' + min_temp: 7.0 + max_temp: 32.0 ``` -`operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` are not necessary if `operation_mode_address` is specified. +`setpoint_shift_mode` allows the two following DPTs to be used: + +- DPT6.002 (for 1 byte signed integer) +- DPT9.002 (for 2 byte float) + +Example: + +```yaml +# Example configuration.yaml entry +knx: + climate: + - name: HASS-Kitchen.Temperature + temperature_address: '5/1/1' + setpoint_shift_address: '5/1/2' + setpoint_shift_state_address: '5/1/3' + setpoint_shift_mode: 'DPT9002' + target_temperature_state_address: '5/1/4' + operation_mode_address: '5/1/5' + operation_mode_state_address: '5/1/6' +``` + +`operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` / `operation_mode_standby_address` are not necessary if `operation_mode_address` is specified. If the actor doesn't support explicit state communication objects the *_state_address can be configured with the same group address as the writeable *_address. The Read-Flag for the *_state_address communication object has to be set in ETS to support initial reading e.g., when starting Home Assistant. +The following values are valid for the `heat_cool_address` and the `heat_cool_state_address`: + +- 0 (cooling) +- 1 (heating) + The following values are valid for the `hvac_mode` attribute: - Off (maps internally to HVAC_MODE_OFF within Home Assistant) @@ -97,6 +124,11 @@ temperature_address: description: KNX group address for reading current room temperature from KNX bus. *DPT 9.001* required: true type: string +temperature_step: + description: Defines the step size in Kelvin for each step of setpoint_shift. + required: false + type: float + default: 0.1 target_temperature_address: description: KNX group address for setting target temperature. *DPT 9.001* required: false @@ -106,18 +138,19 @@ target_temperature_state_address: required: true type: string setpoint_shift_address: - description: KNX address for setpoint_shift. *DPT 6.010* + description: KNX address for setpoint_shift. *DPT 6.010 or 9.001 based on setpoint_shift_mode* required: false type: string setpoint_shift_state_address: - description: KNX address for reading setpoint_shift. *DPT 6.010* + description: KNX address for reading setpoint_shift. *DPT 6.010 or 9.001 based on setpoint_shift_mode* required: false type: string -setpoint_shift_step: - description: Defines the step size in Kelvin for each step of setpoint_shift. +setpoint_shift_mode: + description: Defines the internal device DPT used. required: false default: 0.5 - type: float + type: string + default: DPT6010 setpoint_shift_min: description: Minimum value of setpoint shift. required: false @@ -152,6 +185,14 @@ controller_mode_state_address: description: KNX address for reading HVAC Control Mode. *DPT 20.105* required: false type: string +heat_cool_address: + description: KNX address for switching between heat/cool mode. *DPT 1.100* + required: false + type: string +heat_cool_state_address: + description: KNX address for reading heat/cool mode. *DPT 1.100* + required: false + type: string operation_mode_frost_protection_address: description: KNX address for switching on/off frost/heat protection mode. required: false @@ -164,6 +205,10 @@ operation_mode_comfort_address: description: KNX address for switching on/off comfort mode. required: false type: string +operation_mode_standby_address: + description: KNX address for switching on/off standby mode. + required: false + type: string operation_modes: description: Overrides the supported operation modes. Provide the supported `hvac_mode` and `preset_mode` values for your device. required: false diff --git a/source/_integrations/cover.knx.markdown b/source/_integrations/cover.knx.markdown index a3d38d4b279..95649599339 100644 --- a/source/_integrations/cover.knx.markdown +++ b/source/_integrations/cover.knx.markdown @@ -20,15 +20,16 @@ To use your KNX covers in your installation, add the following to your `configur ```yaml # Example configuration.yaml entry -cover: - - 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 +knx: + cover: + - name: "Kitchen.Shutter" + move_long_address: '3/0/0' + move_short_address: '3/0/1' + stop_address: '3/0/4' + position_address: '3/0/3' + position_state_address: '3/0/2' + travelling_time_down: 51 + travelling_time_up: 61 ``` {% configuration %} @@ -42,7 +43,11 @@ move_long_address: 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. + description: KNX group address for moving the cover short time up or down. + required: false + type: string +stop_address: + description: KNX group address for stopping the current movement from the cover. required: false type: string position_address: @@ -72,12 +77,12 @@ travelling_time_up: default: 25 type: integer invert_position: - description: Set this to true if your actuator report fully closed as 100%. + description: Set this to true if your actuator report fully closed as 0% in KNX. required: false default: false type: boolean invert_angle: - description: Set this to true if your actuator reports tilt fully closed as 100%. + description: Set this to true if your actuator reports tilt fully closed as 0% in KNX. required: false default: false type: boolean diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 95d3beb9a07..ca5884d4b4e 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -40,6 +40,22 @@ To use your KNX bus in your installation, add the following lines to your `confi knx: ``` +In order to make use of the various platforms KNX offers you will need to have the following configuration inside `configuration.yaml` depending on what +platforms you intend to use: + +```yaml +knx: + binary_sensor: !include knx_binary_sensor.yaml + switch: !include knx_switch.yaml + sensor: !include knx_sensor.yaml + cover: !include knx_cover.yaml + light: !include knx_light.yaml + notify: !include knx_notify.yaml + scene: !include knx_scene.yaml +``` + +Please check the dedicated platform documentation about how to configure them correctly. + Optional, or if you want to use the XKNX abstraction also for other scripted tools outside of Home Assistant: ```yaml @@ -129,7 +145,7 @@ In order to directly interact with the KNX bus, you can use the following servic ```txt Domain: knx Service: send -Service Data: {"address": "1/0/15", "payload": 0} +Service Data: {"address": "1/0/15", "payload": 0, "type": "temperature"} ``` {% configuration %} @@ -139,6 +155,10 @@ address: payload: description: Payload, either an integer or an array of integers 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 {% endconfiguration %} You can also use the `homeassistant.update_entity` service call to issue GroupValueRead requests for all `*state_address` of a device. diff --git a/source/_integrations/light.knx.markdown b/source/_integrations/light.knx.markdown index 05caf7841c1..3208f1440af 100644 --- a/source/_integrations/light.knx.markdown +++ b/source/_integrations/light.knx.markdown @@ -27,9 +27,10 @@ To use your KNX light in your installation, add the following lines to your `con ```yaml # Example configuration.yaml entry -light: - - platform: knx - address: '1/0/9' +knx: + light: + - name: 'kitchen' + address: '1/0/9' ``` {% configuration %} @@ -103,41 +104,38 @@ For switching/light actuators that are only controlled by a single group address ## Extended configuration example ```yaml -light: - # dimmable light - - platform: knx - name: Bedroom-Light-1 - address: '1/0/9' - state_address: '1/1/9' - brightness_address: '1/2/9' - brightness_state_address: '1/3/9' - # - # RGB light - - platform: knx - name: Bathroom-Light-1 - address: '1/0/9' - state_address: '1/1/9' - brightness_address: '1/2/9' - brightness_state_address: '1/3/9' - color_address: '1/4/9' - color_state_address: '1/5/9' - # - # tunable white light - - platform: knx - name: Office-Light-1 - address: '1/0/21' - state_address: '1/1/21' - brightness_address: '1/2/21' - brightness_state_address: '1/3/21' - color_temperature_address: '1/4/21' - color_temperature_state_address: '1/5/21' - color_temperature_mode: absolute - min_kelvin: 2550 - max_kelvin: 6200 - # - # actuator without dedicated state communication object - - platform: knx - name: Cellar-Light-1 - address: '1/0/5' - state_address: '1/0/5' +knx: + light: + # dimmable light + - name: Bedroom-Light-1 + address: '1/0/9' + state_address: '1/1/9' + brightness_address: '1/2/9' + brightness_state_address: '1/3/9' + # + # RGB light + - name: Bathroom-Light-1 + address: '1/0/9' + state_address: '1/1/9' + brightness_address: '1/2/9' + brightness_state_address: '1/3/9' + color_address: '1/4/9' + color_state_address: '1/5/9' + # + # tunable white light + - name: Office-Light-1 + address: '1/0/21' + state_address: '1/1/21' + brightness_address: '1/2/21' + brightness_state_address: '1/3/21' + color_temperature_address: '1/4/21' + color_temperature_state_address: '1/5/21' + color_temperature_mode: absolute + min_kelvin: 2550 + max_kelvin: 6200 + # + # actuator without dedicated state communication object + - name: Cellar-Light-1 + address: '1/0/5' + state_address: '1/0/5' ``` diff --git a/source/_integrations/notify.knx.markdown b/source/_integrations/notify.knx.markdown index 770735557d1..71145cfcd4f 100644 --- a/source/_integrations/notify.knx.markdown +++ b/source/_integrations/notify.knx.markdown @@ -21,10 +21,10 @@ The `knx` notify platform allows you to send notifications to [KNX](https://www. 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' +knx: + notify: + - name: Alarm + address: '5/1/10' ``` {% configuration %} diff --git a/source/_integrations/scene.knx.markdown b/source/_integrations/scene.knx.markdown index bc82cb9e5cc..5f1602cde5b 100644 --- a/source/_integrations/scene.knx.markdown +++ b/source/_integrations/scene.knx.markdown @@ -21,11 +21,11 @@ To use your KNX scence in your installation, add the following to your `configur ```yaml # Example configuration.yaml entry -scene: - - name: Romantic - platform: knx - address: 8/8/8 - scene_number: 23 +knx: + scene: + - name: Romantic + address: 8/8/8 + scene_number: 23 ``` {% configuration %} diff --git a/source/_integrations/sensor.knx.markdown b/source/_integrations/sensor.knx.markdown index b626fec2618..ad8d19cd880 100644 --- a/source/_integrations/sensor.knx.markdown +++ b/source/_integrations/sensor.knx.markdown @@ -25,10 +25,21 @@ To use your KNX sensor in your installation, add the following lines to your `co ```yaml # Example configuration.yaml entry -sensor: - - platform: knx - name: Heating.Valve1 - state_address: '2/0/0' +knx: + sensor: + - name: Heating.Valve1 + state_address: '2/0/0' +``` + +In order to actively read the sensor data from the bus all 30 seconds you can add the following lines to your `configuration.yaml`: + +```yaml +# Example configuration.yaml entry +knx: + sensor: + - name: Heating.Valve1 + state_address: '2/0/0' + sync_state: 30 ``` {% configuration %} @@ -41,9 +52,9 @@ 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. You can also define in seconds between 2 and 1440 how often the state update should take place. required: false - type: boolean + type: [boolean, string, integer] default: True type: description: A type from the following table must be defined. The DPT of the group address should match the expected KNX DPT to be parsed correctly. @@ -195,14 +206,13 @@ type: ```yaml # Example configuration.yaml entry -sensor: - - platform: knx - name: Heating.Valve1 - state_address: '2/0/0' - type: 'percent' - - platform: knx - name: Kitchen.Temperature - state_address: '6/2/1' - sync_state: False - type: 'temperature' +knx: + sensor: + - name: Heating.Valve1 + state_address: '2/0/0' + type: 'percent' + - name: Kitchen.Temperature + state_address: '6/2/1' + sync_state: False + type: 'temperature' ``` diff --git a/source/_integrations/switch.knx.markdown b/source/_integrations/switch.knx.markdown index ce529244208..f57826d8084 100644 --- a/source/_integrations/switch.knx.markdown +++ b/source/_integrations/switch.knx.markdown @@ -21,10 +21,10 @@ The `knx` switch platform is used as an interface to switching actuators. To use your KNX switch in your installation, add the following to your `configuration.yaml` file: ```yaml -switch: - - platform: knx - name: Kitchen.Coffee - address: '1/1/6' +knx: + switch: + - name: Kitchen.Coffee + address: '1/1/6' ``` {% configuration %}