mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-06-01 07:46:49 +00:00
Minor tweaks to KNX docs (#16362)
Co-authored-by: Marvin Wichmann <marvin@fam-wichmann.de>
This commit is contained in:
Philip Allgaier
GitHub
parent
9c19ac2069
commit
b198523e93
@ -52,8 +52,7 @@ To use your KNX bus in your installation, add the following lines to your `confi
|
||||
knx:
|
||||
```
|
||||
|
||||
In order to make use of the various platforms KNX offers you will need to have the following configuration inside `configuration.yaml` depending on what
|
||||
platforms you intend to use:
|
||||
In order to make use of the various platforms that KNX offers you will need to add the relevant configuration sections to your setup. This could either all be in the Home Assistant main `configuration.yaml` file, or in a separate YAML file that you include in the main file or even be split into multiple dedicated files as shown below:
|
||||
|
||||
```yaml
|
||||
knx:
|
||||
@ -62,13 +61,14 @@ knx:
|
||||
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 check the dedicated platform documentation about how to configure them correctly.
|
||||
Please see the dedicated platform sections below about how to configure them correctly.
|
||||
|
||||
Optional, or if you want to use the XKNX abstraction also for other scripted tools outside of Home Assistant:
|
||||
Alternatively, if you want to use the [XKNX](https://xknx.io/) library abstraction (e.g., to re-use the configuration also for other scripted tools outside of Home Assistant):
|
||||
|
||||
```yaml
|
||||
knx:
|
||||
@ -77,7 +77,7 @@ knx:
|
||||
|
||||
{% configuration %}
|
||||
config_file:
|
||||
description: The path for XKNX configuration file. See [xknx.io](https://xknx.io/configuration) for details
|
||||
description: The path for XKNX configuration file. See [xknx.io](https://xknx.io/configuration) for details.
|
||||
required: false
|
||||
type: string
|
||||
rate_limit:
|
||||
@ -86,7 +86,7 @@ rate_limit:
|
||||
default: 20
|
||||
type: integer
|
||||
individual_address:
|
||||
description: The KNX individual address that shall be used for routing or if a tunnelling server doesn't assign an IA at connection.
|
||||
description: The KNX individual address (IA) that shall be used for routing or if a tunnelling server doesn't assign an IA at connection.
|
||||
required: false
|
||||
type: string
|
||||
default: "15.15.250"
|
||||
@ -102,7 +102,7 @@ multicast_port:
|
||||
default: 3671
|
||||
{% endconfiguration %}
|
||||
|
||||
If the auto detection of the KNX/IP device does not work you can specify IP and port of the tunneling device:
|
||||
If the auto detection of the KNX/IP device does not work, you can specify IP and port of the tunneling device:
|
||||
|
||||
```yaml
|
||||
knx:
|
||||
@ -150,7 +150,7 @@ knx:
|
||||
|
||||
{% configuration %}
|
||||
fire_event:
|
||||
description: If set to True, platform will write all received KNX messages to event bus
|
||||
description: If set to `true`, platform will write all received KNX messages to event bus.
|
||||
required: inclusive
|
||||
type: boolean
|
||||
default: false
|
||||
@ -159,7 +159,7 @@ fire_event_filter:
|
||||
required: inclusive
|
||||
type: [list, string]
|
||||
state_updater:
|
||||
description: The integration will collect the current state of each configured device from the KNX bus to display it correctly within Home Assistant. Set this option to False to prevent this behavior.
|
||||
description: The integration will collect the current state of each configured device from the KNX bus to display it correctly within Home Assistant. Set this option to `false` to prevent this behavior.
|
||||
required: false
|
||||
default: true
|
||||
type: boolean
|
||||
@ -177,7 +177,7 @@ Service Data: {"address": "1/0/15", "payload": 0, "type": "temperature"}
|
||||
|
||||
{% configuration %}
|
||||
address:
|
||||
description: KNX group address
|
||||
description: KNX group address.
|
||||
type: string
|
||||
payload:
|
||||
description: Payload to send to the bus. When `type` is not set, raw bytes are sent. Integers are then treated as DPT 1/2/3 payloads. For DPTs > 6 bits send a list. Each value represents 1 octet (0-255). Pad with 0 to DPT byte length.
|
||||
@ -209,7 +209,7 @@ knx:
|
||||
- type: 'binary'
|
||||
entity_id: 'light.office'
|
||||
address: '0/3/0'
|
||||
default: False
|
||||
default: false
|
||||
- type: 'percentU8'
|
||||
entity_id: 'light.office'
|
||||
attribute: 'brightness'
|
||||
@ -223,16 +223,16 @@ knx:
|
||||
|
||||
{% configuration %}
|
||||
type:
|
||||
description: Type of the exposed value. Either 'binary', 'time', 'date', 'datetime' or any supported type of [KNX Sensor](#sensor) (e.g., "temperature" or "humidity").
|
||||
description: Type of the exposed value. Either `binary`, `time`, `date`, `datetime` or any supported type of [KNX Sensor](#sensor) (e.g., "temperature" or "humidity").
|
||||
type: string
|
||||
required: true
|
||||
entity_id:
|
||||
description: Entity id to be exposed. Not needed for types time, date and datetime.
|
||||
description: Entity ID to be exposed. Not needed for types `time`, `date` and `datetime`.
|
||||
type: string
|
||||
required: false
|
||||
attribute:
|
||||
description: Attribute of the entity that shall be sent to the KNX bus. If not set (or `None`) the state will be sent.
|
||||
Eg. for a light the state is eigther "on" or "off" - with attribute you can expose its "brightness".
|
||||
Eg. for a light the state is eigther "on" or "off". With `attribute` you can expose its "brightness".
|
||||
type: string
|
||||
required: false
|
||||
default:
|
||||
@ -274,30 +274,30 @@ name:
|
||||
required: false
|
||||
type: string
|
||||
sync_state:
|
||||
description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire <minutes>` to read the state from the KNX bus when no telegram was received for \<minutes\> or `every <minutes>` to update it regularly every \<minutes\>. Maximum value for \<minutes\> is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `True` which is interpreted as "expire 60".
|
||||
description: Actively read the value from the bus. If `false` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire <minutes>` to read the state from the KNX bus when no telegram was received for \<minutes\> or `every <minutes>` to update it regularly every \<minutes\>. Maximum value for \<minutes\> is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `true` which is interpreted as "expire 60".
|
||||
required: false
|
||||
type: [boolean, string, integer]
|
||||
default: True
|
||||
default: true
|
||||
device_class:
|
||||
description: Sets the [class of the device](/integrations/binary_sensor/), changing the device state and icon that is displayed on the frontend.
|
||||
required: false
|
||||
type: string
|
||||
reset_after:
|
||||
description: Reset back to OFF state after specified seconds.
|
||||
description: Reset back to "off" state after specified seconds.
|
||||
required: false
|
||||
type: float
|
||||
invert:
|
||||
description: Invert the telegrams payload before processing. This is applied before `context_timeout` or `reset_after` is evaluated.
|
||||
required: false
|
||||
type: boolean
|
||||
default: False
|
||||
default: false
|
||||
ignore_internal_state:
|
||||
description: Specifies if telegrams should ignore the internal state and always trigger a Home Assistant state update.
|
||||
required: false
|
||||
type: boolean
|
||||
default: False
|
||||
default: false
|
||||
context_timeout:
|
||||
description: The time in seconds between multiple identical telegram payloads would count towards the internal counter that is used for automations. Ex. You have automations in place that trigger your lights on button press and another set of lights if you click that button twice. This setting defines the time that a second button press would count toward, so if you set this 3.0 you can take up to 3 seconds in order to trigger the second button press. If set `ignore_internal_state` will be set to `True` internally. Maximum value is 10.0.
|
||||
description: The time in seconds between multiple identical telegram payloads would count towards the internal counter that is used for automations. Ex. You have automations in place that trigger your lights on button press and another set of lights if you click that button twice. This setting defines the time that a second button press would count toward, so if you set this 3.0 you can take up to 3 seconds in order to trigger the second button press. If set `ignore_internal_state` will be set to `true` internally. Maximum value is 10.0.
|
||||
required: false
|
||||
type: float
|
||||
default: None
|
||||
@ -400,8 +400,7 @@ knx:
|
||||
```
|
||||
|
||||
If your device doesn't support setpoint_shift calculations (i.e., if you don't provide a `setpoint_shift_address` value) please set the `min_temp` and `max_temp`
|
||||
attributes of the climate device to avoid issues with exceeding valid temperature values in the frontend. Please do also make sure to add the `target_temperature_address`
|
||||
to the configuration in this case.:
|
||||
attributes of the climate device to avoid issues with exceeding valid temperature values in the frontend. Please do also make sure to add the `target_temperature_address` to the configuration in this case.:
|
||||
|
||||
```yaml
|
||||
# Example configuration.yaml entry
|
||||
@ -442,29 +441,29 @@ 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 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.
|
||||
|
||||
The following values are valid for the `heat_cool_address` and the `heat_cool_state_address`:
|
||||
|
||||
- 0 (cooling)
|
||||
- 1 (heating)
|
||||
- `0` (cooling)
|
||||
- `1` (heating)
|
||||
|
||||
The following values are valid for the `hvac_mode` attribute:
|
||||
The following values are valid for the Home Assistant [Climate](/integrations/climate/) `hvac_mode` attribute. Supported values for your KNX thermostats can be specified via `controller_modes` configuration variable:
|
||||
|
||||
- Off (maps internally to HVAC_MODE_OFF within Home Assistant)
|
||||
- Auto (maps internally to HVAC_MODE_AUTO within Home Assistant)
|
||||
- Heat (maps internally to HVAC_MDOE_HEAT within Home Assistant)
|
||||
- Cool (maps internally to HVAC_MDOE_COOL within Home Assistant)
|
||||
- Fan only (maps internally to HVAC_MODE_FAN_ONLY within Home Assistant)
|
||||
- Dry (maps internally to HVAC_MODE_DRY within Home Assistant)
|
||||
- `Off` (maps internally to `HVAC_MODE_OFF` within Home Assistant)
|
||||
- `Auto` (maps internally to `HVAC_MODE_AUTO` within Home Assistant)
|
||||
- `Heat` (maps internally to `HVAC_MDOE_HEAT` within Home Assistant)
|
||||
- `Cool` (maps internally to `HVAC_MDOE_COOL` within Home Assistant)
|
||||
- `Fan only` (maps internally to `HVAC_MODE_FAN_ONLY` within Home Assistant)
|
||||
- `Dry` (maps internally to `HVAC_MODE_DRY` within Home Assistant)
|
||||
|
||||
The following presets are valid for the `preset_mode` attribute:
|
||||
The following presets are valid for the Home Assistant [Climate](/integrations/climate/) `preset_mode` attribute. Supported values for your KNX thermostats can be specified via `operation_modes` configuration variable:
|
||||
|
||||
- Auto (maps internally to PRESET_NONE within Home Assistant)
|
||||
- Comfort (maps internally to PRESET_COMFORT within Home Assistant)
|
||||
- Standby (maps internally to PRESET_AWAY within Home Assistant)
|
||||
- Night (maps internally to PRESET_SLEEP within Home Assistant)
|
||||
- Frost Protection (maps internally to PRESET_ECO within Home Assistant)
|
||||
- `Auto` (maps internally to `PRESET_NONE` within Home Assistant)
|
||||
- `Comfort` (maps internally to `PRESET_COMFORT` within Home Assistant)
|
||||
- `Standby` (maps internally to `PRESET_AWAY` within Home Assistant)
|
||||
- `Night` (maps internally to `PRESET_SLEEP` within Home Assistant)
|
||||
- `Frost` Protection (maps internally to `PRESET_ECO` within Home Assistant)
|
||||
|
||||
{% configuration %}
|
||||
name:
|
||||
@ -500,7 +499,6 @@ setpoint_shift_state_address:
|
||||
setpoint_shift_mode:
|
||||
description: Defines the internal device DPT used. Either 'DPT6010' or 'DPT9002'.
|
||||
required: false
|
||||
default: 0.5
|
||||
type: string
|
||||
default: DPT6010
|
||||
setpoint_shift_min:
|
||||
@ -534,7 +532,7 @@ controller_mode_address:
|
||||
required: false
|
||||
type: string
|
||||
controller_mode_state_address:
|
||||
description: KNX address for reading HVAC Control Mode. *DPT 20.105*
|
||||
description: KNX address for reading HVAC control mode. *DPT 20.105*
|
||||
required: false
|
||||
type: string
|
||||
heat_cool_address:
|
||||
@ -657,12 +655,12 @@ travelling_time_up:
|
||||
default: 25
|
||||
type: integer
|
||||
invert_position:
|
||||
description: Set this to true if your actuator report fully closed as 0% in KNX.
|
||||
description: Set this to `true` if your actuator report fully closed as 0% in KNX.
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
invert_angle:
|
||||
description: Set this to true if your actuator reports tilt fully closed as 0% in KNX.
|
||||
description: Set this to `true` if your actuator reports tilt fully closed as 0% in KNX.
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
@ -676,8 +674,8 @@ device_class:
|
||||
|
||||
The `knx light` integration is used as an interface to control KNX actuators for lighting applications such as:
|
||||
|
||||
- switching actuators
|
||||
- dimming actuators
|
||||
- Switching actuators
|
||||
- Dimming actuators
|
||||
- LED controllers
|
||||
- DALI gateways
|
||||
|
||||
@ -744,12 +742,12 @@ color_temperature_mode:
|
||||
type: string
|
||||
default: absolute
|
||||
min_kelvin:
|
||||
description: Warmest possible color temperature in Kelvin. (Used in combination with *color_temperature_address*)
|
||||
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*)
|
||||
description: Coldest possible color temperature in Kelvin. Used in combination with `color_temperature_address`.
|
||||
required: false
|
||||
type: integer
|
||||
default: 6000
|
||||
@ -825,6 +823,7 @@ name:
|
||||
required: false
|
||||
type: string
|
||||
{% endconfiguration %}
|
||||
|
||||
The `knx` scenes platform allows you to trigger [KNX](https://www.knx.org/) scenes.
|
||||
|
||||
## Scene
|
||||
@ -848,7 +847,7 @@ address:
|
||||
required: true
|
||||
type: string
|
||||
scene_number:
|
||||
description: KNX scene number to be activated. ( 1 ... 64 )
|
||||
description: KNX scene number to be activated (range 1..64 ).
|
||||
required: true
|
||||
type: integer
|
||||
name:
|
||||
@ -897,10 +896,10 @@ name:
|
||||
required: false
|
||||
type: string
|
||||
sync_state:
|
||||
description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire <minutes>` to read the state from the KNX bus when no telegram was received for \<minutes\> or `every <minutes>` to update it regularly every \<minutes\>. Maximum value for \<minutes\> is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `True` which is interpreted as "expire 60".
|
||||
description: Actively read the value from the bus. If `false` no GroupValueRead telegrams will be sent to the bus. `sync_state` can be set to `init` to just initialize state on startup, `expire <minutes>` to read the state from the KNX bus when no telegram was received for \<minutes\> or `every <minutes>` to update it regularly every \<minutes\>. Maximum value for \<minutes\> is 1440. If just a number is configured "expire"-behaviour is used. Defaults to `true` which is interpreted as "expire 60".
|
||||
required: false
|
||||
type: [boolean, string, integer]
|
||||
default: True
|
||||
default: true
|
||||
type:
|
||||
description: A type from the following table must be defined. The DPT of the group address should match the expected KNX DPT to be parsed correctly.
|
||||
required: true
|
||||
@ -909,7 +908,7 @@ always_callback:
|
||||
description: Defines if telegrams with equal payload as the previously received telegram should trigger a state update within Home Assistant.
|
||||
required: false
|
||||
type: boolean
|
||||
default: False
|
||||
default: false
|
||||
{% endconfiguration %}
|
||||
|
||||
| KNX DPT | type | size in byte | range | unit |
|
||||
@ -1101,7 +1100,7 @@ invert:
|
||||
description: Invert the telegrams payload before processing or sending.
|
||||
required: false
|
||||
type: boolean
|
||||
default: False
|
||||
default: false
|
||||
{% 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.
|
||||
@ -1130,8 +1129,8 @@ knx:
|
||||
address_day_night: "7/0/8"
|
||||
address_air_pressure: "7/0/9"
|
||||
address_humidity: "7/0/10"
|
||||
expose_sensors: False
|
||||
sync_state: True
|
||||
expose_sensors: false
|
||||
sync_state: true
|
||||
```
|
||||
|
||||
{% configuration %}
|
||||
@ -1189,13 +1188,13 @@ address_humidity:
|
||||
required: false
|
||||
type: string
|
||||
expose_sensors:
|
||||
description: If true, exposes all sensor values as dedicated sensors to HA.
|
||||
description: If true, exposes all sensor values as dedicated sensors to Home Assistant.
|
||||
required: false
|
||||
type: boolean
|
||||
default: False
|
||||
default: false
|
||||
sync_state:
|
||||
description: Actively read the value from the bus. If `False` no GroupValueRead telegrams will be sent to the bus.
|
||||
description: Actively read the value from the bus. If `false` no GroupValueRead telegrams will be sent to the bus.
|
||||
required: false
|
||||
type: boolean
|
||||
default: True
|
||||
default: true
|
||||
{% endconfiguration %}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user