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" 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 %} ## {% linkable_title Configuration %}
@ -31,34 +35,107 @@ light:
{% configuration %} {% configuration %}
address: 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 required: true
type: string type: string
state_address:
description: KNX group address for retrieving the switch state of the light. *DPT 1.001*
required: false
type: string
name: name:
description: A name for this device used within Home Assistant. description: A name for this device used within Home Assistant.
required: false required: false
type: string type: string
brightness_address: brightness_address:
description: KNX group address for dimming light. description: KNX group address for setting the brightness of the light in percent (absolute dimming). *DPT 5.001*
required: false
type: string
state_address:
description: separate KNX group address for retrieving the switch state of the light.
required: false required: false
type: string type: string
brightness_state_address: 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 required: false
type: string type: string
color_address: 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 required: false
type: string type: string
color_state_address: 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 required: false
type: string 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 %} {% 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. 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 can't change their state internally, you don't have to configure the state address.
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'
```