From 566f3a509506b2bdc89d5245e030e2a5e384dd6d Mon Sep 17 00:00:00 2001 From: Matthias Alphart Date: Thu, 12 Jan 2023 20:40:11 +0100 Subject: [PATCH] Update KNX for xknx 2.3.0 (#25705) --- source/_integrations/knx.markdown | 54 +++++++++++++++++-------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 3372c82283f..9139fe6d060 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -85,16 +85,15 @@ knx: Please see the dedicated platform sections below about how to configure them correctly. - ### Group addresses Group addresses are configured as strings or integers in the format "1/2/3" for 3-level GA-structure, "1/2" for 2-level GA-structure or "1" for free GA-structure. The HA KNX integration uses configured `state_address` or `*_state_address` to update the state of a function. These addresses are read by GroupValueRead requests on startup and when there was no incoming telegram for one hour (default `sync_state`). -It is possible to configure passive/listening group addresses for all functions of every KNX platform (except `expose` and `notify`). This allows having multiple group addresses to update the state of its function (e.g., the brightness of a light). When group addresses are configured as a list of strings, the first item is the active sending or state-reading address and the rest is registered as passive addresses. This schema behaves like in ETS configuration where the first is the "sending" address and others are just for updating the communication object. +It is possible to configure passive/listening group addresses for all functions of every KNX platform (except `expose` and `notify`). This allows having multiple group addresses to update the state of its function (e.g., the brightness of a light). When group addresses are configured as a list of strings, the first item is the active sending or state-reading address and the rest is registered as passive addresses. This schema behaves like in ETS configuration where the first is the "sending" address and others are just for updating the group object. -If your KNX device provides active state communication objects it is advised to use `*_state_address` instead of passive addresses as it reduces configuration complexity and avoids wrong states (e.g., when channels are logically locked). +If your KNX device provides active state group objects it is advised to use `*_state_address` instead of passive addresses as it reduces configuration complexity and avoids wrong states (e.g., when channels are logically locked). ```yaml knx: @@ -627,7 +626,7 @@ 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 group objects the `*_state_address` can be configured with the same group address as the writeable `*_address`. The read flag for the `*_state_address` group 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`: @@ -1090,7 +1089,7 @@ entity_category: Many KNX devices can change their state internally without a message to the switch address on the KNX bus, e.g., if you configure a scene or 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` (in most cases from the light actuator), it will overwrite the state of the object. -For switching/light actuators that are only controlled by a single group address and don't have dedicated state communication objects you can set `state_address` to the same value as `address`. +For switching/light actuators that are only controlled by a single group address and don't have dedicated state group objects you can set `state_address` to the same value as `address`. *Note on tunable white:* Home Assistant uses Mireds as the unit for color temperature, whereas KNX typically uses Kelvin. The Kelvin/Mireds relationship is reciprocal, not linear, therefore the color temperature pickers (sliders) in Home Assistant may not align with ones of KNX visualizations. This is the expected behavior. @@ -1173,7 +1172,7 @@ knx: color_temperature_mode: absolute min_kelvin: 2550 max_kelvin: 6200 - # actuator without dedicated state communication object + # actuator without dedicated state group object # color mode: onoff - name: "Simple light" address: "1/0/5" @@ -1510,6 +1509,7 @@ device_class: | 8.007 | delta_time_hrs | 2 | -32768 ... 32767 | h | | 8.010 | percentV16 | 2 | -32768 ... 32767 | % | | 8.011 | rotation_angle | 2 | -32768 ... 32767 | ° | +| 8.012 | length_m | 2 | -32768 ... 32767 | m | | 9 | 2byte_float | 2 | -671088.64 ... 670760.96 | | | 9.001 | temperature | 2 | -273 ... 670760 | °C | | 9.002 | temperature_difference_2byte | 2 | -670760 ... 670760 | K | @@ -1519,6 +1519,7 @@ device_class: | 9.006 | pressure_2byte | 2 | 0 ... 670760 | Pa | | 9.007 | humidity | 2 | 0 ... 670760 | % | | 9.008 | ppm | 2 | -671088.64 ... 670760.96 | ppm | +| 9.009 | air_flow | 2 | -671088.64 ... 670760.96 | m³/h | | 9.010 | time_1 | 2 | -670760 ... 670760 | s | | 9.011 | time_2 | 2 | -670760 ... 670760 | ms | | 9.020 | voltage | 2 | -671088.64 ... 670760.96 | mV | @@ -1530,12 +1531,18 @@ device_class: | 9.026 | rain_amount | 2 | -671088.64 ... 670760.96 | l/m² | | 9.027 | temperature_f | 2 | -459.6 ... 670760 | °F | | 9.028 | wind_speed_kmh | 2 | 0 ... 670760 | km/h | +| 9.029 | absolute_humidity | 2 | 0 ... 670760 | g/m³ | +| 9.030 | concentration_ugm3 | 2 | 0 ... 670760 | μg/m³ | | 9.? | enthalpy | 2 | -671088.64 ... 670760.96 | H | | 12 | 4byte_unsigned | 4 | 0 ... 4294967295 | | +| 12.001 | pulse_4_ucount | 4 | 0 ... 4294967295 | counter pulses | +| 12.100 | long_time_period_sec | 4 | 0 ... 4294967295 | s | +| 12.101 | long_time_period_min | 4 | 0 ... 4294967295 | min | +| 12.100 | long_time_period_hrs | 4 | 0 ... 4294967295 | h | | 12.1200 | volume_liquid_litre | 4 | 0 ... 4294967295 | l | | 12.1201 | volume_m3 | 4 | 0 ... 4294967295 | m³ | | 13 | 4byte_signed | 4 | -2147483648 ... 2147483647 | | -| 13.001 | pulse_4byte | 4 | -2147483648 ... 2147483647 | pulses | +| 13.001 | pulse_4byte | 4 | -2147483648 ... 2147483647 | counter pulses | | 13.002 | flow_rate_m3h | 4 | -2147483648 ... 2147483647 | m³/h | | 13.010 | active_energy | 4 | -2147483648 ... 2147483647 | Wh | | 13.011 | apparant_energy | 4 | -2147483648 ... 2147483647 | VAh | @@ -1543,6 +1550,7 @@ device_class: | 13.013 | active_energy_kwh | 4 | -2147483648 ... 2147483647 | kWh | | 13.014 | apparant_energy_kvah | 4 | -2147483648 ... 2147483647 | kVAh | | 13.015 | reactive_energy_kvarh | 4 | -2147483648 ... 2147483647 | kVARh | +| 13.016 | active_energy_mwh | 4 | -2147483648 ... 2147483647 | MWh | | 13.100 | long_delta_timesec | 4 | -2147483648 ... 2147483647 | s | | 14 | 4byte_float | 4 | | | | 14.000 | acceleration | 4 | | m/s² | @@ -1602,11 +1610,11 @@ device_class: | 14.054 | phaseanglerad | 4 | | rad | | 14.055 | phaseangledeg | 4 | | ° | | 14.056 | power | 4 | | W | -| 14.057 | powerfactor | 4 | | cosΦ | +| 14.057 | powerfactor | 4 | | | | 14.058 | pressure | 4 | | Pa | | 14.059 | reactance | 4 | | Ω | | 14.060 | resistance | 4 | | Ω | -| 14.061 | resistivity | 4 | | Ω m | +| 14.061 | resistivity | 4 | | Ωm | | 14.062 | self_inductance | 4 | | H | | 14.063 | solid_angle | 4 | | sr | | 14.064 | sound_intensity | 4 | | W/m² | @@ -1620,11 +1628,12 @@ device_class: | 14.072 | thermal_conductivity | 4 | | W/mK | | 14.073 | thermoelectric_power | 4 | | V/K | | 14.074 | time_seconds | 4 | | s | -| 14.075 | torque | 4 | | N m | +| 14.075 | torque | 4 | | Nm | | 14.076 | volume | 4 | | m³ | | 14.077 | volume_flux | 4 | | m³/s | | 14.078 | weight | 4 | | N | | 14.079 | work | 4 | | J | +| 14.080 | apparent_power | 4 | | VA | | 16.000 | string | 14 | ASCII | | | 16.001 | latin_1 | 14 | ISO 8859-1 / Latin-1 | | | 17.001 | scene_number | 1 | 1 ... 64 | | @@ -1868,11 +1877,14 @@ logger: logs: # For most debugging needs `xnx.log` and `xknx.telegram` are a good choice. xknx: info # sets the level of all loggers + # Loggers for different layers of KNX communication xknx.log: debug # provides general information (connection, etc.) - xknx.raw_socket: warning # logs incoming UDP frames in raw hex format - xknx.knx: debug # logs incoming and outgoing KNX/IP frames at socket level + xknx.telegram: debug # logs telegrams before they are being processed or sent xknx.cemi: debug # logs incoming and outgoing CEMI frames - xknx.telegram: debug # logs telegrams before they are being processed at device level or sent to an interface + xknx.ip_secure: debug # logs IP Secure relevant information + xknx.knx: debug # logs incoming and outgoing KNX/IP frames + xknx.raw_socket: warning # logs incoming UDP/TCP frames in raw hex format at socket level + # Loggers for xknx internals xknx.state_updater: warning # provides information about the state updater ``` @@ -1888,13 +1900,14 @@ Every `*_state_address` is read on startup sequentially if not configured differ > Error: KNX bus did not respond in time (2.0 secs) to GroupValueRead request for: '1/2/3' ``` -#### No communication object (CO) assigned to the group address (GA) has the Read-Flag set in ETS +#### No group object (GO) assigned to the group address (GA) has the Read-Flag set in ETS -- Enable the read flag for *one* CO assigned to the GA. Use the one most likely to hold the current state (e.g., for a light entity's `brightness_state_address` the according CO of the dimming actuator). +- Enable the read flag for *one* GO assigned to the GA. Use the one most likely to hold the current state (e.g., for a light entity's `brightness_state_address` the according GO of the dimming actuator). #### Response telegrams are not passing a line coupler, router or other filter in the installation -- Use a dummy device in ETS for Home Assistant. These can be found in the ETS online catalog. Assign it to the line your interface connects Home Assistant to and link its communication objects to the group addresses you are using in Home Assistant. ETS will generate filter tables that are applied to your line couplers after updating their application. +- Assign the group addresses used by Home Assistant to the used interface in ETS if your interface application supports that. ETS will generate filter tables that are applied to your line couplers after updating their application. +- If your interface application doesn't support that, use a dummy device in ETS for Home Assistant. These can be found in the ETS online catalog. Assign it to the line your interface connects Home Assistant to and link its group objects to the group addresses you are using in Home Assistant. #### Unresponsive system @@ -1923,12 +1936,3 @@ The `unique_id` for KNX entities is generated based on required configuration va - weather: `address_temperature` There can not be multiple entities on the same platform sharing these exact group addresses, even if they differ in other configuration. - -### xknx.yaml configuration - -```log -> The 'config_file' option near /homeassistant/configuration.yaml:42 is deprecated, please remove it from your configuration -> Invalid config for [knx]: [config_file] is an invalid option for [knx]. Check: knx->knx->config_file. -``` - -The feature to specify a xknx configuration schema file in the Home Assistant configuration YAML file (via `config_file:`) is deprecated since Home Assistant 2021.4. You can use the [xknx.yaml config converter](https://xknx.io/config-converter/) to convert it to a Home Assistant compatible `configuration.yaml` schema.