KNX

The KNX integration connects Home Assistant to your KNX installation, allowing you to control KNX devices, act on telegrams and forward state changes from other integrations entities to your KNX bus.

This integration requires a local KNX/IP interface or router to establish the connection between Home Assistant and your KNX bus.

There is currently support for the following device types within Home Assistant:

• Binary sensor
• Button
• Climate
• Cover
• Date
• Fan
• Light
• Notify
• Number
• Scene
• Select
• Sensor
• Switch
• Text
• Time
• Weather

Configuration

To add the KNX hub to your Home Assistant instance, use this My button:

KNX Connection

Select the connection type to your KNX bus. The integration supports the following connection methods:

• ‘Automatic’ performs a gateway scan on start, to find a KNX IP interface. It will connect via a tunnel. This option is not available when a gateway scan at setup initiation was not successful.
• ‘Tunneling’ will connect to a specific KNX IP interface over a tunnel.
• ‘Routing’ will use Multicast to communicate with KNX IP routers.

For more information about KNX connection types see Connection.

Tunneling specific settings

You can select a specific tunnel device if multiple were found during the setup. In case no device was discovered, you can configure connection information manually.

Tunnel endpoint

Select the tunnel endpoint used for the connection. This step is only available for TCP or Secure Tunneling connection types.

Routing specific settings

KNX IP Secure specific settings

See Connection on how to get the files or keys needed for this configuration step.

Options

Options for KNX can be set via the user interface, by taking the following steps:

• Browse to your Home Assistant instance.
• Go to Settings > Devices & Services.
• If multiple instances of KNX are configured, choose the instance you want to configure.
• Select the integration, then select Configure.

Configure KNX interface

Reconfigure your connection settings. See above for more information.

Communication settings

Import KNX Keyring

Provide a (new) keyring file to be used by the integration. See KNX Secure on how to get this file.

Basic configuration

In order to make use of the various platforms offered by the KNX integration, you will need to set them up via the KNX panel or add the corresponding configuration yaml to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]. See Splitting up the configuration if you like to arrange YAML parts in dedicated files. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.

knx:
  # 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

Please see the dedicated platform sections below about how to configure them correctly.

Group addresses

Group addresses are configured as strings or integers in the format “1/2/3” for 3-level GA-structure, “1/2” for 2-level GA-structure or “1” for free GA-structure.

The HA KNX integration uses configured state_address or *_state_address to update the state of a function. These addresses are read by GroupValueRead requests on startup and when there was no incoming telegram for one hour (default sync_state).

It is possible to configure passive/listening group addresses for all functions of every KNX platform (except expose and notify). This allows having multiple group addresses to update the state of its function (e.g., the brightness of a light). When group addresses are configured as a list of strings, the first item is the active sending or state-reading address and the rest is registered as passive addresses. This schema behaves like in ETS configuration where the first is the “sending” address and others are just for updating the group object.

If your KNX device provides active state group objects it is advised to use *_state_address instead of passive addresses as it reduces configuration complexity and avoids wrong states (e.g., when channels are logically locked).

knx:
  switch:
    - name: "Switch without passive addresses"
      address: "1/1/1" # this is the address that will be sent to
      state_address: "8/8/8"  # this is the address GroupValueRead requests are sent to
    - name: "Switch with passive addresses"
      address: 
        - "1/1/1" # this is the address that will be sent to
        - "1/1/2" # this and following are passive addresses
        - "1/1/3"
      state_address: 
        - "8/8/8" # this is the address GroupValueRead requests are sent to
        - "8/8/2" # this and following are passive addresses
        - "8/8/3"

Connection

Connection parameters are configured during integration setup and can be modified later in the integrations settings.

KNX Secure

The KNX integration supports both IP Secure and Data Secure.

IP Secure

IP Secure credentials can be provided in two ways:

1. Using a .knxkeys file: This file can be exported from ETS and imported into the integration settings.
2. Manual configuration: If you are not using Data Secure, you can manually input the required IP Secure credentials in the integration settings.

Data Secure

Data Secure credentials are always sourced from a .knxkeys file. You can import or update the Keyring file from the integrations settings.

When updating secure groups, ensure all participating devices, routers, and couplers applications are updated as well. After making changes, load the updated Keyring file into Home Assistant.

Tunneling

Tunneling uses a KNX IP Interface to connect to the KNX bus. Most KNX IP Routers also support tunneling connections. This is the recommended connection type and is also used when selecting an “Automatic” connection in the integration setup.

For modern interfaces (supporting TCP or IP Secure) you can select a specific tunnel endpoint to be used. Make sure that Home Assistant is the only client connecting to this tunnel endpoint. In ETS it is recommended to connect the group addresses you want to use to the tunnel endpoint that Home Assistant uses. For secure group addresses, this is mandatory.

If you use KNX IP Secure tunneling or Data Secure, export the Keyring file from ETS and import it in the KNX integration settings.

Routing

Routing communicates with KNXnet/IP routers via IP Multicast.

When using routing:

1. Add a dummy device in ETS at the same topology level as your routers.
2. Assign this dummy device the same individual address configured in the KNX integration setup.
3. Connect all group addresses that Home Assistant will use to the dummy device. This ensures routers and couplers maintain updated filter tables and enables the use of secure group addresses in Home Assistant.
4. If you use KNX IP Secure routing or Data Secure groups, export the Keyring file from ETS and import it in the KNX integration settings.

Data updates

This integration uses the KNX/IP protocol to receive telegrams live as they appear on the bus. When the integration is loaded, it actively requests data needed to initialize the configured entities. See Group Addresses for more details.

States of diagnostic entities of the “KNX Interface” device are polledData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] every 10 seconds.

Triggers

The KNX integration provides its own trigger platform which can be used in automations.

Telegram trigger

The knx.telegram trigger can be used to trigger automations on incoming or outgoing KNX telegrams.

Available trigger data

In addition to the standard automation trigger data, the knx.telegram trigger platform has additional trigger data available for use.

• trigger.destination Destination group address
• trigger.destination_name Destination group address name
• trigger.direction Telegram direction
• trigger.dpt_main Destination group address main datapoint type number
• trigger.dpt_sub Destination group address sub datapoint type number
• trigger.dpt_name DPT value type name - see Sensor value types
• trigger.payload Raw telegram payload. DPT 1, 2, and 3 yield integers 0..255; other DPT yield lists of integers 0..255
• trigger.source Source individual address
• trigger.source_name Source name
• trigger.telegramtype APCI type of telegram
• trigger.timestamp Timestamp
• trigger.unit Unit according to group address DPT
• trigger.value Decoded telegram payload according to DPT

For values that require project data: if the information was not found, or if no project file was provided, data will be set to null.

Examples

Example automation configuration

- alias: "Single group address trigger"
  triggers:
    - trigger: knx.telegram
      destination: 1/2/3
      group_value_read: false
      outgoing: false
  conditions: "{{ trigger.value == 0 }}"
  actions: []

Example trigger data

variables:
  triggers:
    id: "0"
    idx: "0"
    alias: null
    destination: 1/2/3
    destination_name: Light office brightness
    direction: Incoming
    dpt_main: 5
    dpt_sub: 1
    dpt_name: percent
    payload:
      - 255
    source: 1.0.51
    source_name: Dimming actuator 1
    telegramtype: GroupValueWrite
    timestamp: "2024-01-09T10:38:28.447487+01:00"
    unit: "%"
    value: 100
context: null

Events

knx:
  event:
    - address:
        - "0/1/*"
    - address:
        - "1/2/*"
        - "1/3/2-4"
      type: "2byte_unsigned"
    - address:
        - "3/4/5"
      type: "2byte_float"

Every telegram that matches an address pattern with its destination field will be announced on the event bus as a knx_event event containing data attributes

• data contains the raw payload data (e.g., 1 or “[12, 55]”).
• destination the KNX group address the telegram is sent to as string (e.g., “1/2/3”).
• direction the direction of the telegram as string (“Incoming” / “Outgoing”).
• source the KNX individual address of the sender as string (e.g., “1.2.3”).
• telegramtype the APCI service of the telegram. “GroupValueWrite”, “GroupValueRead” or “GroupValueResponse” generate a knx_event.
• value contains the decoded payload value if type is configured for the address. Will be None for “GroupValueRead” telegrams.

Actions

In order to directly interact with the KNX bus, you can use the following actions:

Send

Domain: knx
Action: send
Data: {"address": "1/0/15", "payload": 0, "type": "temperature"}

# Example script to send a fixed value and the state of an entity
alias: "My Script"
sequence:
  - action: knx.send
    data:
      address: 1/1/1
      type: percent
      payload: 50
      response: false
  - action: knx.send
    data:
      address: 1/1/1
      payload: [128]  # 50 % as 1-byte raw value
      response: false
  - action: knx.send
    data:
      address: 3/3/3
      type: temperature
      payload: "{{ states('sensor.dew_point') }}"
      response: false

Read

You can use the homeassistant.update_entity action call to issue GroupValueRead requests for all *state_address of an entity. To manually send GroupValueRead requests, use the knx.read action. The response can be used in automations by the knx.telegram trigger and it will be processed in KNX entities.

Domain: knx
Action: read
Data: {"address": "1/0/15"}

# Example automation to update a cover position after 10 seconds of movement initiation
automation:
  - triggers:
      - trigger: knx.telegram
        # Cover move trigger
        destination: "0/4/20"
    actions:
      - delay: 0:0:10
      - action: knx.read
        data:
          # Cover position address
          address: "0/4/21"

  - triggers:
      - trigger: homeassistant
        event: start
    actions:
      # Register the group address to trigger a knx_event
      - action: knx.event_register
        data:
          # Cover move trigger
          address: "0/4/20"

Register event

The knx.event_register action can be used to register (or unregister) group addresses to fire knx_event Events. Events for group addresses configured in the event key in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] cannot be unregistered. See knx_event

Register exposure

The knx.exposure_register action can be used to register (or unregister) exposures to the KNX bus. Exposures defined in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] can not be unregistered. Per address only one exposure can be registered. See expose

Exposing entity states, entity attributes or time to KNX bus

KNX integration is able to expose entity states or attributes to KNX bus. The integration will broadcast any change of the exposed value to the KNX bus and answer read requests to the specified group address. It is also possible to expose the current time and date. These are sent to the bus every hour.

# Example configuration.yaml entry
knx:
  expose:
    # time and date exposures
    - type: time
      address: "0/0/1"
    # entitiy exposures
    - type: temperature
      entity_id: sensor.owm_temperature
      address: "0/0/2"
      cooldown: 600
    - type: string
      address: "0/6/4"
      entity_id: sensor.owm_weather
    - type: binary
      entity_id: binary_sensor.kitchen_window
      address: "0/6/5"
    - type: binary
      entity_id: light.office
      address: "0/3/0"
      default: false
    - type: percentU8
      entity_id: light.office
      attribute: brightness
      default: 0
      address: "0/3/1"
    - type: percent
      address: "1/1/1"
      entity_id: cover.office
      attribute: current_position
      value_template: "{{ 100 - value }}"  # invert the value
    - type: percent
      address: "2/2/2"
      entity_id: media_player.kitchen
      attribute: volume_level
      value_template: "{{ value * 100 }}"  # convert from 0..1 to percent

Binary sensor

The KNX binary sensor platform allows you to monitor KNX binary sensors like window/door contacts, motion detectors, alarms, etc.

Binary sensor entities can be created from the frontend in the KNX panel or via YAML.

knx:
  binary_sensor:
    - name: "Sensor 1"
      state_address: "6/0/2"

Automation example

Let’s pretend you have configured a binary sensor with the name Livingroom Switch and you want to toggle a light when the button was pressed once and another light when the button was pressed twice. context_timeout has to be configured in order for this to work and the switch would have to send the same payloads on each press (on - on within the time window).

automation:
  - triggers:
      - trigger: numeric_state
        entity_id: binary_sensor.livingroom_switch
        attribute: counter
        above: 0
        below: 2
    actions:
      - action: light.toggle
        entity_id: light.livingroom_ceiling_lamp
  - triggers:
      - trigger: numeric_state
        entity_id: binary_sensor.livingroom_switch
        attribute: counter
        above: 1
        below: 3
    actions:
      - action: light.toggle
        target:
          entity_id: 
            - light.livingroom_floor_lamp

Button

The KNX button platform allows to send concurrent predefined values via the frontend or an action. When a user presses the button, the assigned generic raw payload is sent to the KNX bus.

# Example configuration.yaml entry
knx:
  button:
    - name: "DPT 1 - True button"
      address: "0/0/1"
    - name: "100% button"
      address: "0/0/2"
      payload: 0xFF
      payload_length: 1
    - name: "Temperature button"
      address: "0/0/3"
      value: 21.5
      type: temperature

Climate

The KNX climate platform is used as an interface to KNX thermostats and room controllers.

To use your KNX thermostats in your installation, add the following lines to your top level KNX Integration configuration key in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
knx:
  climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      target_temperature_state_address: "5/1/4"
      operation_mode_address: "5/1/5"
      operation_mode_state_address: "5/1/6"

Alternatively, if your device has dedicated binary group addresses for frost/night/comfort mode:

# Example configuration.yaml entry
knx:
  climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      target_temperature_state_address: "5/1/4"
      operation_mode_frost_protection_address: "5/1/5"
      operation_mode_night_address: "5/1/6"
      operation_mode_comfort_address: "5/1/7"
      operation_mode_state_address: "5/1/8"

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.:

# Example configuration.yaml entry
knx:
  climate:
    - name: "Kitchen"
      temperature_address: "5/1/2"
      target_temperature_address: "5/1/4"
      target_temperature_state_address: "5/1/1"
      operation_mode_frost_protection_address: "5/1/5"
      operation_mode_night_address: "5/1/6"
      operation_mode_comfort_address: "5/1/7"
      operation_mode_state_address: "5/1/8"
      operation_mode_standby_address: "5/1/9"
      min_temp: 7.0
      max_temp: 32.0

setpoint_shift_mode allows the two following DPTs to be used:

• DPT6010 (for 1 byte signed integer with scale factor)
• DPT9002 (for 2 byte float)

Example:

# Example configuration.yaml entry
knx:
  climate:
    - name: "Kitchen"
      temperature_address: "5/1/1"
      setpoint_shift_address: "5/1/2"
      setpoint_shift_state_address: "5/1/3"
      setpoint_shift_mode: "DPT9002"
      target_temperature_state_address: "5/1/4"
      operation_mode_address: "5/1/5"
      operation_mode_state_address: "5/1/6"

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.

The following values are valid for the heat_cool_address and the heat_cool_state_address:

• 0 (cooling)
• 1 (heating)

Supported HVAC modes for your KNX thermostats are found automatically. This can be overridden by using the controller_modes configuration variable. The following values are valid controller modes:

• off
• auto
• heat
• cool
• fan_only
• dehumidification

Supported preset modes for your KNX thermostats are found automatically. This can be overridden by using the operation_modes configuration variable. The following values are valid operation modes:

• auto
• comfort
• standby
• economy
• building_protection

Cover

The KNX cover platform is used as an interface to KNX covers.

Cover entities can be created from the frontend in the KNX panel or via YAML.

# Example configuration.yaml entry
knx:
  cover:
    - name: "Kitchen shutter"
      move_long_address: "3/0/0"
      stop_address: "3/0/4"
      position_address: "3/0/3"
      position_state_address: "3/0/2"
      travelling_time_down: 51
      travelling_time_up: 61
    - name: "Bedroom blinds"
      move_long_address: "3/1/1"
      move_short_address: "3/1/4"
      position_address: "3/1/3"
      position_state_address: "3/1/2"
      angle_address: "3/1/5"
      angle_state_address: "3/1/6"
      travelling_time_down: 40
      travelling_time_up: 40

Date

The KNX date platform allows to send date values to the KNX bus and update its state from received telegrams. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  date:
    - name: "Date"
      address: "0/0/2"
      state_address: "0/0/2"

DateTime

The KNX datetime platform allows to send datetime values to the KNX bus and update its state from received telegrams. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  datetime:
    - name: "DateTime"
      address: "0/0/3"
      state_address: "0/0/4"

Fan

The KNX fan integration is used to control KNX fans. Following control types are supported:

• Percentage controlled: Fans that set the percentage directly from 0-100%.
• Step controlled: Fans which have a fixed amount of steps to set. The integration will convert percentage to step automatically. The max_step attribute is set to the number of steps of the fan, not counting the off-step. Example: A fan supports the steps 0 to 3. To use this fan the max_step attribute has to be set to 3. The integration will convert the percentage 66 % to the step 2 when sending data to KNX.

To use your KNX fan in your installation, add the following lines to your top-level KNX Integration configuration key in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
knx:
  fan:
    - name: "Ceiling fan"
      address: "9/0/1"
      state_address: "9/0/2"

Light

The KNX light integration is used as an interface to control KNX actuators for lighting applications such as:

• Switching actuators
• Dimming actuators
• LED controllers
• DALI gateways

Light entities can be created from the frontend in the KNX panel or via YAML.

knx:
  light:
    # dimmable light
    # color mode: brightness
    - name: "Dimmable light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"
      brightness_state_address: "1/3/9"
    # XYY light
    # color mode: xy
    - name: "XYY light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"  # optional - if not set brightness will be sent over the xyy data point
      brightness_state_address: "1/3/9"
      xyy_address: "1/4/9"
      xyy_state_address: "1/5/9"
    # HS light
    # color mode: hs
    - name: "HS light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"  # required for HS
      brightness_state_address: "1/3/9"
      hue_address: "1/4/8"
      hue_state_address: "1/5/8"  # required for HS
      saturation_address: "1/4/9"
      saturation_state_address: "1/5/9"  # required for HS
    # RGB light
    # color mode: rgb
    - name: "RGB light"
      address: "1/0/9"
      state_address: "1/1/9"
      brightness_address: "1/2/9"  # optional for RGB lights
      brightness_state_address: "1/3/9"
      color_address: "1/4/9"
      color_state_address: "1/5/9"
    # RGBW light
    # color mode: rgbw
    - name: "RGBW light"
      address: "0/4/83"
      state_address: "0/4/84"
      brightness_address: "0/4/85"  # optional for RGBW lights
      brightness_state_address: "0/4/86"
      rgbw_address: "0/4/87"
      rgbw_state_address: "0/4/88"
    # RGB(W) individual object light
    # color mode: rgb / rgbw
    - name: "RGBW individual light"
      address: "1/0/9"  # optional for individual color lights
      individual_colors:
        red:
          brightness_address: "0/4/61"
          brightness_state_address: "0/5/61"
        green:
          brightness_address: "0/4/62"
          brightness_state_address: "0/5/62"
        blue:
          brightness_address: "0/4/63"
          brightness_state_address: "0/5/63"
        white:
          brightness_address: "0/4/64"
          brightness_state_address: "0/5/64"
    # tunable white light
    # color mode: color_temp
    - name: "TW light"
      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 group object
    # color mode: onoff
    - name: "Simple light"
      address: "1/0/5"
      state_address: "1/0/5"

Notify

The KNX notify platform allows you to send notifications to KNX devices as DPT16 strings.

knx:
  notify:
    - name: "Alarm"
      address: "5/1/10"

Example action

action: notify.send_message
data:
  message: "Hello from HA!"
  entity_id: notify.alarm

Number

The KNX number platform allows to send generic numeric values to the KNX bus and update its state from received telegrams. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  number:
    - name: "Duration"
      address: "0/0/1"
      type: time_period_sec
    - name: "Volume"
      address: "0/0/2"
      state_address: "0/0/3"
      type: percent
    - name: "Temperature threshold"
      address: "0/0/4"
      respond_to_read: true
      type: temperature
      min: 20
      max: 24.5
      step: 0.1
      mode: slider

Scene

The KNX scenes platform allows you to trigger KNX scenes. These entities are write-only.

# Example configuration.yaml entry
knx:
  scene:
    - name: "Romantic"
      address: 8/8/8
      scene_number: 23

Select

The KNX select platform allows the user to define a list of values that can be selected via the frontend and can be used within conditions of automation. When a user selects a new item, the assigned generic raw payload is sent to the KNX bus. A received telegram updates the state of the select entity. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  select:
    - name: "DPT 2 selector"
      address: "0/0/1"
      payload_length: 0
      options:
        - option: "No control"
          payload: 0
        - option: "Control On"
          payload: 0b10
        - option: "Control Off"
          payload: 0b11
    - name: "DHWMode"
      address: "0/0/2"
      state_address: "0/0/3"
      payload_length: 1
      options:
        - option: "Auto"
          payload: 0
        - option: "LegioProtect"
          payload: 1
        - option: "Normal"
          payload: 2
        - option: "Reduced"
          payload: 3
        - option: "Off/FrostProtect"
          payload: 4

Sensor

The KNX sensor platform allows you to monitor KNX sensors.

# Example configuration.yaml entry
knx:
  sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      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.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
knx:
  sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      type: percent
      sync_state: every 30

Value types

More examples

# Example configuration.yaml entry
knx:
  sensor:
    - name: "Heating Valve 1"
      state_address: "2/0/0"
      sync_state: init
      type: percent
    - name: "Kitchen Temperature"
      state_address: "6/2/1"
      sync_state: every 60
      type: temperature
      state_class: measurement

Switch

The KNX switch platform is used as an interface to switching actuators.

Switch entities can be created from the frontend in the KNX panel or via YAML.

Switch entities without a state_address will restore their last known state after Home Assistant was restarted. Switches that have a state_address configured request their current state from the KNX bus.

knx:
  switch:
    - name: "Kitchen coffee maker"
      address: "1/1/6"

Text

The KNX text platform allows to send text values to the KNX bus and update its state from received telegrams. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  text:
    - name: "Info"
      address: "0/0/1"
    - name: "ASCII Info"
      address: "0/0/2"
      state_address: "0/0/3"
      type: string
    - name: "Greeting"
      address: "0/0/4"
      respond_to_read: true

Time

The KNX time platform allows to send time values to the KNX bus and update its state from received telegrams. It can optionally respond to read requests from the KNX bus.

# Example configuration.yaml entry
knx:
  time:
    - name: "Time"
      address: "0/0/2"
      state_address: "0/0/2"

Weather

The KNX weather platform is used as an interface to KNX weather stations.

To use your KNX weather station in your installation, add the following lines to your top-level KNX Integration configuration key in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
knx:
  weather:
    - name: "Home"
      address_temperature: "7/0/0"
      address_brightness_south: "7/0/1"
      address_brightness_west: "7/0/2"
      address_brightness_east: "7/0/3"
      address_brightness_north: "7/0/11"
      address_wind_speed: "7/0/4"
      address_rain_alarm: "7/0/5"
      address_frost_alarm: "7/0/6"
      address_wind_alarm: "7/0/7"
      address_day_night: "7/0/8"
      address_air_pressure: "7/0/9"
      address_humidity: "7/0/10"
      sync_state: true

Known limitations

• The integration aims to be compatible with a wide variety of KNX devices from different manufacturers and eras. However, there are some devices that use non-standard DPT or use telegrams in a proprietary way. In these cases, you might not be able to configure entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] directly through this integration. However, you may still use Template entities with the KNX telegram trigger to work around this.

• USB bus interfaces are not directly supported by the underlying xknx library. However, you could try to run a software KNX router such as Calimero or knxd alongside Home Assistant to serve as a USB to IP bridge. For best reliability, using a certified KNX IP interface or router is recommended.

Troubleshooting / Common issues

Logs for the KNX integration

The xknx library is used for KNX communication. It provides various logging handlers for monitoring and debug purposes. Add the following lines to your Home Assistant configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] to activate them:

logger:
  default: warning
  logs:
    # For most debugging needs `xnx.log` and `xknx.telegram` are a good choice.
    xknx: info  # sets the level of all loggers
    # Loggers for different layers of KNX communication
    xknx.log: debug  # provides general information (connection, etc.)
    xknx.telegram: debug  # logs telegrams before they are being processed or sent
    xknx.cemi: debug  # logs incoming and outgoing CEMI frames
    xknx.data_secure: debug  # logs Data Secure relevant information
    xknx.ip_secure: debug  # logs IP Secure relevant information
    xknx.knx: debug  # logs incoming and outgoing KNX/IP frames
    xknx.raw_socket: warning  # logs incoming UDP/TCP frames in raw hex format at socket level
    # Loggers for xknx internals
    xknx.ga_dpt: warning  # logs when payloads can't be decoded with given project file information
    xknx.state_updater: warning  # provides information about the state updater

You can use the logger.set_level action to change the log level of a handler on a running instance.

Group address can not be read

Every *_state_address is read on startup sequentially if not configured differently. If you see the following errors in your log, a group address could not be read by a GroupValueRead request from Home Assistant in time.

> Could not sync group address '1/2/3' (Entity name - Feature)
> Error: KNX bus did not respond in time (2.0 secs) to GroupValueRead request for: '1/2/3'

No group object (GO) assigned to the group address (GA) has the Read-Flag set in ETS

• Enable the read flag for one GO assigned to the GA. Use the one most likely to hold the current state (e.g., for a light entity’s brightness_state_address the according GO of the dimming actuator).

Response telegrams are not passing a line coupler, router or other filter in the installation

• Assign the group addresses used by Home Assistant to the used interface in ETS if your interface application supports that. ETS will generate filter tables that are applied to your line couplers after updating their application.
• If your interface application doesn’t support that, use a dummy device in ETS for Home Assistant. These can be found in the ETS online catalog. Assign it to the line your interface connects Home Assistant to and link its group objects to the group addresses you are using in Home Assistant.

Unresponsive system

• The timeout for logging the errors (2 seconds) is started when the GroupValueRead request is scheduled to be sent. On systems experiencing high loads sending can be delayed (e.g., Raspberry Pi running lots of integrations at startup). Incoming response telegrams are always processed, so no information gets lost.

Duplicate entities

If you find following error in your log you seem to have a duplicated entity in your configuration.

Platform knx does not generate unique IDs. ID 1/2/3 already exists - ignoring platform.name

The unique_id for KNX entities is generated based on required configuration values.

• binary_sensor: state_address
• climate: temperature_address target_temperature_state_address target_temperature_address setpoint_shift_address
• cover: move_long_address position_address
• fan: address
• light: address or all combined brightness_address if only individual_colors is used
• notify: address
• scene: address and scene_number
• sensor: state_address
• switch: address
• weather: address_temperature

There can not be multiple entities on the same platform sharing these exact group addresses, even if they differ in other configuration.

Removing the integration

This integration can be removed by following these steps:

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three-dot menu. Then, select Delete.

In addition, remove knx: from your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].