Update documentation of KNX integration (#14299)

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

source/_integrations/binary_sensor.knx.markdown

@@ -22,10 +22,12 @@ 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
+knx:
   binary_sensor:
-  - platform: knx
+    - name: sensor1
       state_address: '6/0/2'
 ```
 
@@ -64,9 +66,9 @@ You can also attach actions to binary sensors (e.g., to switch on a light when a
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   binary_sensor:
-  - platform: knx
+    - name: Livingroom.3Switch3
-    name: Livingroom.3Switch3
       state_address: '5/0/26'
       automation:
         - counter: 1

source/_integrations/climate.knx.markdown

@@ -16,13 +16,13 @@ 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
+knx:
   climate:
-   - platform: knx
+    - name: HASS-Kitchen.Temperature
-     name: HASS-Kitchen.Temperature
       temperature_address: '5/1/1'
       setpoint_shift_address: '5/1/2'
       setpoint_shift_state_address: '5/1/3'
@@ -35,9 +35,9 @@ Alternatively, if your device has dedicated binary group addresses for frost/nig
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   climate:
-  - platform: knx
+    - name: HASS-Kitchen.Temperature
-    name: HASS-Kitchen.Temperature
       temperature_address: '5/1/1'
       setpoint_shift_address: '5/1/2'
       setpoint_shift_state_address: '5/1/3'
@@ -54,9 +54,9 @@ to the configuration in this case.:
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   climate:
-  - platform: knx
+    - name: HASS-Kitchen.Temperature
-    name: HASS-Kitchen.Temperature
       temperature_address: '5/1/2'
       target_temperature_address: '5/1/4'
       target_temperature_state_address: '5/1/1'
@@ -64,13 +64,40 @@ climate:
       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:
+setpoint_shift_mode:
-  description: Defines the step size in Kelvin for each step of setpoint_shift.
+  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,11 +20,12 @@ To use your KNX covers in your installation, add the following to your `configur
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   cover:
-  - platform: knx
+    - name: "Kitchen.Shutter"
-    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
@@ -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,8 +27,9 @@ To use your KNX light in your installation, add the following lines to your `con
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   light:
-  - platform: knx
+    - name: 'kitchen'
       address: '1/0/9'
 ```
 
@@ -103,18 +104,17 @@ For switching/light actuators that are only controlled by a single group address
 ## Extended configuration example
 
 ```yaml
+knx:
   light:
     # dimmable light
-  - platform: knx
+    - name: Bedroom-Light-1
-    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
-    name: Bathroom-Light-1
       address: '1/0/9'
       state_address: '1/1/9'
       brightness_address: '1/2/9'
@@ -123,8 +123,7 @@ light:
       color_state_address: '1/5/9'
     #
     # tunable white light
-  - platform: knx
+    - name: Office-Light-1
-    name: Office-Light-1
       address: '1/0/21'
       state_address: '1/1/21'
       brightness_address: '1/2/21'
@@ -136,8 +135,7 @@ light:
       max_kelvin: 6200
     #
     # actuator without dedicated state communication object
-  - platform: knx
+    - name: Cellar-Light-1
-    name: Cellar-Light-1
       address: '1/0/5'
       state_address: '1/0/5'
 ```

source/_integrations/notify.knx.markdown

@@ -21,9 +21,9 @@ 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
+knx:
   notify:
-  - platform: knx
+    - name: Alarm
-    name: Alarm
       address: '5/1/10'
 ```
 

source/_integrations/scene.knx.markdown

@@ -21,9 +21,9 @@ To use your KNX scence in your installation, add the following to your `configur
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   scene:
     - name: Romantic
-    platform: knx
       address: 8/8/8
       scene_number: 23
 ```

source/_integrations/sensor.knx.markdown

@@ -25,12 +25,23 @@ To use your KNX sensor in your installation, add the following lines to your `co
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   sensor:
-  - platform: knx
+    - name: Heating.Valve1
-    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 %}
 state_address:
   description: KNX group address of the sensor.
@@ -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,13 +206,12 @@ type:
 
 ```yaml
 # Example configuration.yaml entry
+knx:
   sensor:
-  - platform: knx
+    - name: Heating.Valve1
-    name: Heating.Valve1
       state_address: '2/0/0'
       type: 'percent'
-  - platform: knx
+    - name: Kitchen.Temperature
-    name: Kitchen.Temperature
       state_address: '6/2/1'
       sync_state: False
       type: 'temperature'

source/_integrations/switch.knx.markdown

@@ -21,9 +21,9 @@ 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
+knx:
   switch:
-  - platform: knx
+    - name: Kitchen.Coffee
-    name: Kitchen.Coffee
       address: '1/1/6'
 ```