From b198523e93e7801869cb0dc70c9472788cc6765f Mon Sep 17 00:00:00 2001 From: Philip Allgaier Date: Sat, 30 Jan 2021 23:51:31 +0100 Subject: [PATCH] Minor tweaks to KNX docs (#16362) Co-authored-by: Marvin Wichmann --- source/_integrations/knx.markdown | 113 +++++++++++++++--------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 594d5d9c05a..c05ab9b4863 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -52,8 +52,7 @@ 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: +In order to make use of the various platforms that KNX offers you will need to add the relevant configuration sections to your setup. This could either all be in the Home Assistant main `configuration.yaml` file, or in a separate YAML file that you include in the main file or even be split into multiple dedicated files as shown below: ```yaml knx: @@ -62,13 +61,14 @@ knx: sensor: !include knx_sensor.yaml cover: !include knx_cover.yaml light: !include knx_light.yaml + climate: !include knx_climate.yaml notify: !include knx_notify.yaml scene: !include knx_scene.yaml ``` -Please check the dedicated platform documentation about how to configure them correctly. +Please see the dedicated platform sections below 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: +Alternatively, if you want to use the [XKNX](https://xknx.io/) library abstraction (e.g., to re-use the configuration also for other scripted tools outside of Home Assistant): ```yaml knx: @@ -77,7 +77,7 @@ knx: {% configuration %} config_file: - description: The path for XKNX configuration file. See [xknx.io](https://xknx.io/configuration) for details + description: The path for XKNX configuration file. See [xknx.io](https://xknx.io/configuration) for details. required: false type: string rate_limit: @@ -86,7 +86,7 @@ rate_limit: default: 20 type: integer individual_address: - description: The KNX individual address that shall be used for routing or if a tunnelling server doesn't assign an IA at connection. + description: The KNX individual address (IA) that shall be used for routing or if a tunnelling server doesn't assign an IA at connection. required: false type: string default: "15.15.250" @@ -102,7 +102,7 @@ multicast_port: default: 3671 {% endconfiguration %} -If the auto detection of the KNX/IP device does not work you can specify IP and port of the tunneling device: +If the auto detection of the KNX/IP device does not work, you can specify IP and port of the tunneling device: ```yaml knx: @@ -150,7 +150,7 @@ knx: {% configuration %} fire_event: - description: If set to True, platform will write all received KNX messages to event bus + description: If set to `true`, platform will write all received KNX messages to event bus. required: inclusive type: boolean default: false @@ -159,7 +159,7 @@ fire_event_filter: required: inclusive type: [list, string] state_updater: - description: The integration 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. + description: The integration 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 @@ -177,7 +177,7 @@ Service Data: {"address": "1/0/15", "payload": 0, "type": "temperature"} {% configuration %} address: - description: KNX group address + description: KNX group address. type: string payload: 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. @@ -209,7 +209,7 @@ knx: - type: 'binary' entity_id: 'light.office' address: '0/3/0' - default: False + default: false - type: 'percentU8' entity_id: 'light.office' attribute: 'brightness' @@ -223,16 +223,16 @@ knx: {% configuration %} type: - description: Type of the exposed value. Either 'binary', 'time', 'date', 'datetime' or any supported type of [KNX Sensor](#sensor) (e.g., "temperature" or "humidity"). + description: Type of the exposed value. Either `binary`, `time`, `date`, `datetime` or any supported type of [KNX Sensor](#sensor) (e.g., "temperature" or "humidity"). type: string required: true entity_id: - description: Entity id to be exposed. Not needed for types time, date and datetime. + description: Entity ID to be exposed. Not needed for types `time`, `date` and `datetime`. 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. - Eg. for a light the state is eigther "on" or "off" - with attribute you can expose its "brightness". + Eg. for a light the state is eigther "on" or "off". With `attribute` you can expose its "brightness". type: string required: false default: @@ -274,30 +274,30 @@ 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. `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". + 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 + 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 reset_after: - description: Reset back to OFF state after specified seconds. + description: Reset back to "off" state after specified seconds. required: false type: float invert: description: Invert the telegrams payload before processing. This is applied before `context_timeout` or `reset_after` is evaluated. required: false type: boolean - default: False + default: false ignore_internal_state: description: Specifies if telegrams should ignore the internal state and always trigger a Home Assistant state update. required: false type: boolean - default: False + default: false context_timeout: - description: The time in seconds between multiple identical telegram payloads would count towards the internal counter that is used for automations. Ex. You have automations in place that trigger your lights on button press and another set of lights if you click that button twice. This setting defines the time that a second button press would count toward, so if you set this 3.0 you can take up to 3 seconds in order to trigger the second button press. If set `ignore_internal_state` will be set to `True` internally. Maximum value is 10.0. + description: The time in seconds between multiple identical telegram payloads would count towards the internal counter that is used for automations. Ex. You have automations in place that trigger your lights on button press and another set of lights if you click that button twice. This setting defines the time that a second button press would count toward, so if you set this 3.0 you can take up to 3 seconds in order to trigger the second button press. If set `ignore_internal_state` will be set to `true` internally. Maximum value is 10.0. required: false type: float default: None @@ -400,8 +400,7 @@ knx: ``` 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` -attributes of the climate device to avoid issues with exceeding valid temperature values in the frontend. Please do also make sure to add the `target_temperature_address` -to the configuration in this case.: +attributes of the climate device to avoid issues with exceeding valid temperature values in the frontend. Please do also make sure to add the `target_temperature_address` to the configuration in this case.: ```yaml # Example configuration.yaml entry @@ -442,29 +441,29 @@ knx: ``` `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. +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) +- `0` (cooling) +- `1` (heating) -The following values are valid for the `hvac_mode` attribute: +The following values are valid for the Home Assistant [Climate](/integrations/climate/) `hvac_mode` attribute. Supported values for your KNX thermostats can be specified via `controller_modes` configuration variable: -- Off (maps internally to HVAC_MODE_OFF within Home Assistant) -- Auto (maps internally to HVAC_MODE_AUTO within Home Assistant) -- Heat (maps internally to HVAC_MDOE_HEAT within Home Assistant) -- Cool (maps internally to HVAC_MDOE_COOL within Home Assistant) -- Fan only (maps internally to HVAC_MODE_FAN_ONLY within Home Assistant) -- Dry (maps internally to HVAC_MODE_DRY within Home Assistant) +- `Off` (maps internally to `HVAC_MODE_OFF` within Home Assistant) +- `Auto` (maps internally to `HVAC_MODE_AUTO` within Home Assistant) +- `Heat` (maps internally to `HVAC_MDOE_HEAT` within Home Assistant) +- `Cool` (maps internally to `HVAC_MDOE_COOL` within Home Assistant) +- `Fan only` (maps internally to `HVAC_MODE_FAN_ONLY` within Home Assistant) +- `Dry` (maps internally to `HVAC_MODE_DRY` within Home Assistant) -The following presets are valid for the `preset_mode` attribute: +The following presets are valid for the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute. Supported values for your KNX thermostats can be specified via `operation_modes` configuration variable: -- Auto (maps internally to PRESET_NONE within Home Assistant) -- Comfort (maps internally to PRESET_COMFORT within Home Assistant) -- Standby (maps internally to PRESET_AWAY within Home Assistant) -- Night (maps internally to PRESET_SLEEP within Home Assistant) -- Frost Protection (maps internally to PRESET_ECO within Home Assistant) +- `Auto` (maps internally to `PRESET_NONE` within Home Assistant) +- `Comfort` (maps internally to `PRESET_COMFORT` within Home Assistant) +- `Standby` (maps internally to `PRESET_AWAY` within Home Assistant) +- `Night` (maps internally to `PRESET_SLEEP` within Home Assistant) +- `Frost` Protection (maps internally to `PRESET_ECO` within Home Assistant) {% configuration %} name: @@ -500,7 +499,6 @@ setpoint_shift_state_address: setpoint_shift_mode: description: Defines the internal device DPT used. Either 'DPT6010' or 'DPT9002'. required: false - default: 0.5 type: string default: DPT6010 setpoint_shift_min: @@ -534,7 +532,7 @@ controller_mode_address: required: false type: string controller_mode_state_address: - description: KNX address for reading HVAC Control Mode. *DPT 20.105* + description: KNX address for reading HVAC control mode. *DPT 20.105* required: false type: string heat_cool_address: @@ -657,12 +655,12 @@ travelling_time_up: default: 25 type: integer invert_position: - description: Set this to true if your actuator report fully closed as 0% in KNX. + 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 0% in KNX. + description: Set this to `true` if your actuator reports tilt fully closed as 0% in KNX. required: false default: false type: boolean @@ -676,8 +674,8 @@ device_class: The `knx light` integration is used as an interface to control KNX actuators for lighting applications such as: -- switching actuators -- dimming actuators +- Switching actuators +- Dimming actuators - LED controllers - DALI gateways @@ -744,12 +742,12 @@ color_temperature_mode: type: string default: absolute min_kelvin: - description: Warmest possible color temperature in Kelvin. (Used in combination with *color_temperature_address*) + description: Warmest possible color temperature in Kelvin. Used in combination with `color_temperature_address`. required: false type: integer default: 2700 max_kelvin: - description: Coldest possible color temperature in Kelvin. (Used in combination with *color_temperature_address*) + description: Coldest possible color temperature in Kelvin. Used in combination with `color_temperature_address`. required: false type: integer default: 6000 @@ -825,6 +823,7 @@ name: required: false type: string {% endconfiguration %} + The `knx` scenes platform allows you to trigger [KNX](https://www.knx.org/) scenes. ## Scene @@ -848,7 +847,7 @@ address: required: true type: string scene_number: - description: KNX scene number to be activated. ( 1 ... 64 ) + description: KNX scene number to be activated (range 1..64 ). required: true type: integer name: @@ -897,10 +896,10 @@ 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. `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". + 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 + 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. required: true @@ -909,7 +908,7 @@ always_callback: description: Defines if telegrams with equal payload as the previously received telegram should trigger a state update within Home Assistant. required: false type: boolean - default: False + default: false {% endconfiguration %} | KNX DPT | type | size in byte | range | unit | @@ -1101,7 +1100,7 @@ invert: description: Invert the telegrams payload before processing or sending. required: false type: boolean - default: False + default: false {% 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. @@ -1130,8 +1129,8 @@ knx: address_day_night: "7/0/8" address_air_pressure: "7/0/9" address_humidity: "7/0/10" - expose_sensors: False - sync_state: True + expose_sensors: false + sync_state: true ``` {% configuration %} @@ -1189,13 +1188,13 @@ address_humidity: required: false type: string expose_sensors: - description: If true, exposes all sensor values as dedicated sensors to HA. + description: If true, exposes all sensor values as dedicated sensors to Home Assistant. required: false type: boolean - default: False + default: false 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. required: false type: boolean - default: True + default: true {% endconfiguration %}