Update documentation of KNX integration (#14299)

Co-authored-by: Matthias Alphart <farmio@alphart.net>

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 %}

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

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

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.

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'
 ```

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 %}

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 %}

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'
 ```

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 %}