From 9b08846451246cd3beb44749c093c0a2a7bc25aa Mon Sep 17 00:00:00 2001 From: farmio Date: Tue, 12 Feb 2019 00:23:00 +0100 Subject: [PATCH] update light.knx for xknx 0.9.4 (#7979) * update light.knx for xknx 0.9.3 * remove white_value; add color_temperature_mode reflect changes from https://github.com/XKNX/xknx/pull/165 * added note for tunable white added note poiniting out Kelvin/Mireds relationship * :pencil2: Tweaks --- source/_components/light.knx.markdown | 103 ++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 13 deletions(-) diff --git a/source/_components/light.knx.markdown b/source/_components/light.knx.markdown index 2fc2af1508c..b2c833b750a 100644 --- a/source/_components/light.knx.markdown +++ b/source/_components/light.knx.markdown @@ -13,10 +13,14 @@ ha_release: 0.44 ha_iot_class: "Local Polling" --- +The `knx light` component is used as an interface to control knx actuators for lighting applications such as: -The `knx` light component is used as in interface to switching/light actuators. +- switching actuators +- dimming actuators +- LED controllers +- DALI gateways -The `knx` component must be configured correctly, see [KNX Component](/components/knx). +The `knx` component must be configured correctly to use this component, see [KNX Component](/components/knx). ## {% linkable_title Configuration %} @@ -31,34 +35,107 @@ light: {% configuration %} address: - description: KNX group address for switching the light on and off. + description: KNX group address for switching the light on and off. *DPT 1.001* required: true type: string +state_address: + description: KNX group address for retrieving the switch state of the light. *DPT 1.001* + required: false + type: string name: description: A name for this device used within Home Assistant. required: false type: string brightness_address: - description: KNX group address for dimming light. - required: false - type: string -state_address: - description: separate KNX group address for retrieving the switch state of the light. + description: KNX group address for setting the brightness of the light in percent (absolute dimming). *DPT 5.001* required: false type: string brightness_state_address: - description: separate KNX group address for retrieving the dimmed state of the light. + description: KNX group address for retrieving the brightness of the light in percent. *DPT 5.001* required: false type: string color_address: - description: separate KNX group address for setting the color of the light. + description: KNX group address for setting the RGB color of the light. *DPT 232.600* required: false type: string color_state_address: - description: separate KNX group address for retrieving the color of the light. + description: KNX group address for retrieving the RGB color of the light. *DPT 232.600* required: false type: string +color_temperature_address: + description: KNX group address for setting the color temperature of the light. *DPT 5.001 or 7.600 based on color_temperature_mode* + required: false + type: string +color_temperature_state_address: + description: KNX group address for retrieving the color temperature of the light. *DPT 5.001 or 7.600 based on color_temperature_mode* + required: false + type: string +color_temperature_mode: + description: Color temperature group address data type. + keys: + absolute: + description: color temperature in Kelvin. *color_temperature_address -> DPT 7.600* + relative: + description: color temperature in percent cold white (0% warmest; 100% coldest). *color_temperature_address -> DPT 5.001* + required: false + type: string + default: absolute +min_kelvin: + 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*) + required: false + type: integer + default: 6000 {% 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. -For switching/light actuators that are only controlled by a single group address and can't change their state internally, you don't have to configure the state address. +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 switch 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`. + +*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. + +## {% linkable_title 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' +```