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

* ✏️ Tweaks
This commit is contained in:
farmio 2019-02-12 00:23:00 +01:00 committed by Franck Nijhof
parent 8461d74947
commit 9b08846451

View File

@ -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'
```