From 51e0f5374de2c6f34f8b2dcc87f040b60b5d1ea3 Mon Sep 17 00:00:00 2001 From: Matthias Alphart Date: Tue, 23 Mar 2021 15:05:47 +0100 Subject: [PATCH] KNX yaml style and sensor value types (#17075) Co-authored-by: Franck Nijhof --- source/_integrations/knx.markdown | 120 ++++++++++++++++-------------- 1 file changed, 66 insertions(+), 54 deletions(-) diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 8b0a700733a..68cea77559d 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -68,14 +68,13 @@ In order to make use of the various platforms that KNX offers you will need to a ```yaml knx: - binary_sensor: !include knx_binary_sensor.yaml - switch: !include knx_switch.yaml + # configure platforms directly in configuration.yaml + binary_sensor: + - name: "My first binary sensor" + state_address: "1/2/3" + # etc... + # or outsource platform configuration to separate files 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 see the dedicated platform sections below about how to configure them correctly. @@ -154,6 +153,7 @@ Explicit connection via KNX/IP routing. This requires multicast communication to ```yaml knx: + routing: ``` {% configuration %} @@ -295,27 +295,27 @@ KNX integration is able to expose entity states or attributes to KNX bus. The in # Example configuration.yaml entry knx: expose: - - type: "temperature" - entity_id: "sensor.owm_temperature" + - type: temperature + entity_id: sensor.owm_temperature address: "0/0/2" - - type: "string" + - type: string address: "0/6/4" - entity_id: "sensor.owm_weather" - - type: "binary" - entity_id: "binary_sensor.kitchen_window" + entity_id: sensor.owm_weather + - type: binary + entity_id: binary_sensor.kitchen_window address: "0/6/5" - - type: "binary" - entity_id: "light.office" + - type: binary + entity_id: light.office address: "0/3/0" default: false - - type: "percentU8" - entity_id: "light.office" - attribute: "brightness" + - type: percentU8 + entity_id: light.office + attribute: brightness default: 0 address: "0/3/1" - - type: "time" + - type: time address: "0/0/1" - - type: "datetime" + - type: datetime address: "0/0/23" ``` @@ -355,7 +355,7 @@ Binary sensors are read-only. To write to the KNX bus configure an exposure [KNX ```yaml knx: binary_sensor: - - name: sensor1 + - name: "Sensor 1" state_address: "6/0/2" ``` @@ -409,7 +409,7 @@ Let's pretend you have a binary sensor with the name `Livingroom.Switch` and you automation: - trigger: platform: numeric_state - entity_id: binary_sensor.Livingroom_Switch + entity_id: binary_sensor.livingroom_switch attribute: counter above: 0 below: 2 @@ -422,7 +422,7 @@ automation: service: light.turn_on - trigger: platform: numeric_state - entity_id: binary_sensor.Livingroom_Switch + entity_id: binary_sensor.livingroom_switch attribute: counter above: 1 below: 3 @@ -468,7 +468,7 @@ To use your KNX thermostats in your installation, add the following lines to you # Example configuration.yaml entry knx: climate: - - name: HASS-Kitchen.Temperature + - name: "Kitchen" temperature_address: "5/1/1" setpoint_shift_address: "5/1/2" setpoint_shift_state_address: "5/1/3" @@ -483,7 +483,7 @@ Alternatively, if your device has dedicated binary group addresses for frost/nig # Example configuration.yaml entry knx: climate: - - name: HASS-Kitchen.Temperature + - name: "Kitchen" temperature_address: "5/1/1" setpoint_shift_address: "5/1/2" setpoint_shift_state_address: "5/1/3" @@ -501,7 +501,7 @@ attributes of the climate device to avoid issues with exceeding valid temperatur # Example configuration.yaml entry knx: climate: - - name: HASS-Kitchen.Temperature + - name: "Kitchen" temperature_address: "5/1/2" target_temperature_address: "5/1/4" target_temperature_state_address: "5/1/1" @@ -525,7 +525,7 @@ Example: # Example configuration.yaml entry knx: climate: - - name: HASS-Kitchen.Temperature + - name: "Kitchen" temperature_address: "5/1/1" setpoint_shift_address: "5/1/2" setpoint_shift_state_address: "5/1/3" @@ -700,7 +700,7 @@ To use your KNX covers in your installation, add the following lines to your top # Example configuration.yaml entry knx: cover: - - name: "Kitchen.Shutter" + - name: "Kitchen shutter" move_long_address: "3/0/0" move_short_address: "3/0/1" stop_address: "3/0/4" @@ -783,7 +783,7 @@ To use your KNX fan in your installation, add the following lines to your top le # Example configuration.yaml entry knx: fan: - - name: "ceiling fan" + - name: "Ceiling fan" address: "9/0/1" state_address: "9/0/2" ``` @@ -830,7 +830,7 @@ To use your KNX light in your installation, add the following lines to your top # Example configuration.yaml entry knx: light: - - name: "kitchen" + - name: "Kitchen" address: "1/0/9" ``` @@ -948,14 +948,14 @@ For switching/light actuators that are only controlled by a single group address knx: light: # dimmable light - - 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 - - name: Bathroom-Light-1 + - name: "Bathroom Light 1" address: "1/0/9" state_address: "1/1/9" brightness_address: "1/2/9" @@ -964,7 +964,7 @@ knx: color_state_address: "1/5/9" # # tunable white light - - name: Office-Light-1 + - name: "Office Light 1" address: "1/0/21" state_address: "1/1/21" brightness_address: "1/2/21" @@ -976,7 +976,7 @@ knx: max_kelvin: 6200 # # actuator without dedicated state communication object - - name: Cellar-Light-1 + - name: "Cellar Light 1" address: "1/0/5" state_address: "1/0/5" ``` @@ -988,7 +988,7 @@ The KNX notify platform allows you to send notifications to [KNX](https://www.kn ```yaml knx: notify: - - name: Alarm + - name: "Alarm" address: "5/1/10" ``` @@ -1011,7 +1011,7 @@ The KNX scenes platform allows you to trigger [KNX](https://www.knx.org/) scenes # Example configuration.yaml entry knx: scene: - - name: Romantic + - name: "Romantic" address: 8/8/8 scene_number: 23 ``` @@ -1041,9 +1041,9 @@ Sensors are read-only. To write to the KNX bus configure an exposure [KNX Integr # Example configuration.yaml entry knx: sensor: - - name: Heating.Valve1 + - name: "Heating Valve 1" state_address: "2/0/0" - type: "percent" + type: percent ``` In order to actively read the sensor data from the bus every 30 minutes you can add the following lines to your `configuration.yaml`: @@ -1052,9 +1052,9 @@ In order to actively read the sensor data from the bus every 30 minutes you can # Example configuration.yaml entry knx: sensor: - - name: Heating.Valve1 + - name: "Heating Valve 1" state_address: "2/0/0" - type: "percent" + type: percent sync_state: every 30 ``` @@ -1087,14 +1087,18 @@ always_callback: | KNX DPT | type | size in byte | range | unit | |--------:|-------------------------------|-------------:|:--------------------------:|----------------| +| 5 | 1byte_unsigned | 1 | 0 ... 255 | | | 5.001 | percent | 1 | 0 ... 100 | % | | 5.003 | angle | 1 | 0 ... 360 | ° | | 5.004 | percentU8 | 1 | 0 ... 255 | % | -| 5.010 | pulse | 1 | 0 ... 255 | | -| 5.010 | 1byte_unsigned | 1 | 0 ... 255 | | +| 5.005 | decimal_factor | 1 | 0 ... 255 | | +| 5.006 | tariff | 1 | 0 ... 254 | | +| 5.010 | pulse | 1 | 0 ... 255 | counter pulses | +| 6 | 1byte_signed | 1 | -128 ... 127 | | | 6.001 | percentV8 | 1 | -128 ... 127 | % | | 6.010 | counter_pulses | 1 | -128 ... 127 | counter pulses | -| 7.001 | 2byte_unsigned | 2 | 0 ... 65535 | pulses | +| 7 | 2byte_unsigned | 2 | 0 ... 65535 | | +| 7.001 | pulse_2byte | 2 | 0 ... 65535 | pulses | | 7.002 | time_period_msec | 2 | 0 ... 65535 | ms | | 7.003 | time_period_10msec | 2 | 0 ... 65535 | ms | | 7.004 | time_period_100msec | 2 | 0 ... 65535 | ms | @@ -1105,14 +1109,17 @@ always_callback: | 7.012 | current | 2 | 0 ... 65535 | mA | | 7.013 | brightness | 2 | 0 ... 65535 | lx | | 7.600 | color_temperature | 2 | 0 ... 65535 | K | -| 8.001 | 2byte_signed | 2 | -32768 ... 32767 | pulses | +| 8 | 2byte_signed | 2 | -32768 ... 32767 | | +| 8.001 | pulse_2byte_signed | 2 | -32768 ... 32767 | pulses | | 8.002 | delta_time_ms | 2 | -32768 ... 32767 | ms | +| 8.003 | delta_time_10ms | 2 | -32768 ... 32767 | ms | +| 8.004 | delta_time_100ms | 2 | -32768 ... 32767 | ms | | 8.005 | delta_time_sec | 2 | -32768 ... 32767 | s | | 8.006 | delta_time_min | 2 | -32768 ... 32767 | min | | 8.007 | delta_time_hrs | 2 | -32768 ... 32767 | h | | 8.010 | percentV16 | 2 | -32768 ... 32767 | % | | 8.011 | rotation_angle | 2 | -32768 ... 32767 | ° | -| 9.* | enthalpy | 2 | -671088.64 ... 670760.96 | H | +| 9 | 2byte_float | 2 | -671088.64 ... 670760.96 | | | 9.001 | temperature | 2 | -273 ... 670760 | °C | | 9.002 | temperature_difference_2byte | 2 | -670760 ... 670760 | K | | 9.003 | temperature_a | 2 | -670760 ... 670760 | K/h | @@ -1124,6 +1131,7 @@ always_callback: | 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 | +| 9.021 | curr | 2 | -671088.64 ... 670760.96 | mA | | 9.022 | power_density | 2 | -671088.64 ... 670760.96 | W/m² | | 9.023 | kelvin_per_percent | 2 | -671088.64 ... 670760.96 | K/% | | 9.024 | power_2byte | 2 | -671088.64 ... 670760.96 | kW | @@ -1131,8 +1139,12 @@ always_callback: | 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 | -| 12.*** | 4byte_unsigned | 4 | 0 ... 4294967295 | | -| 13.*** | 4byte_signed | 4 | -2147483648 ... 2147483647 | | +| 9.? | enthalpy | 2 | -671088.64 ... 670760.96 | H | +| 12 | 4byte_unsigned | 4 | 0 ... 4294967295 | | +| 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.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 | @@ -1141,8 +1153,8 @@ always_callback: | 13.014 | apparant_energy_kvah | 4 | -2147483648 ... 2147483647 | kVAh | | 13.015 | reactive_energy_kvarh | 4 | -2147483648 ... 2147483647 | kVARh | | 13.100 | long_delta_timesec | 4 | -2147483648 ... 2147483647 | s | +| 14 | 4byte_float | 4 | | | | 14.000 | acceleration | 4 | | m/s² | -| 14.*** | 4byte_float | 4 | | | | 14.001 | acceleration_angular | 4 | | rad/s² | | 14.002 | activation_energy | 4 | | J/mol | | 14.003 | activity | 4 | | s⁻¹ | @@ -1231,14 +1243,14 @@ always_callback: # Example configuration.yaml entry knx: sensor: - - name: Heating.Valve1 + - name: "Heating Valve 1" state_address: "2/0/0" sync_state: init - type: "percent" - - name: Kitchen.Temperature + type: percent + - name: "Kitchen Temperature" state_address: "6/2/1" sync_state: every 60 - type: "temperature" + type: temperature ``` ## Switch @@ -1248,7 +1260,7 @@ The KNX switch platform is used as an interface to switching actuators. ```yaml knx: switch: - - name: Kitchen.Coffee + - name: "Kitchen coffee maker" address: "1/1/6" ``` @@ -1286,7 +1298,7 @@ To use your KNX weather station in your installation, add the following lines to # Example configuration.yaml entry knx: weather: - - name: "home" + - name: "Home" address_temperature: "7/0/0" address_brightness_south: "7/0/1" address_brightness_west: "7/0/2"