KNX

The KNX integration for Home Assistant allows you to connect to KNX/IP devices.

The integration requires a local KNX/IP interface or router. Through this, it will establish a 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
• Fan
• Light
• Notify
• Number
• Scene
• Select
• Sensor
• Switch
• Weather

Configuration

Adding KNX to your Home Assistant instance can be done via the user interface, by using this My button:

Basic Configuration

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. See Splitting up the configuration.

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 communication object.

If your KNX device provides active state communication 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 set up when adding the integration and can be changed from the Integrations panel.

Use route back if your tunneling server is located on a different network.

KNX Secure

The KNX integration currently supports IP secure tunneling. IP secure via routing and data secure are currently not supported.

In order to use IP Secure you will have to chose “Tunneling” -> “TCP with IP Secure” in the config flow.

You can configure the IP Secure credentials either manually or by providing a .knxkeys file, which you can obtain by exporting the keyring in ETS as seen in the screenshot below.

The .knxkeys file has to be placed in config/.storage/knx/yourfile.knxkeys.

If you decide to configure IP Secure manually you will need the user ID, the user password and the device authentication password.

The user id 0 is reserved and the user id 1 is used for management tasks, thus you will need to specify a user id that is 2 or higher according to the tunneling channel you would like to use.

The following screenshot will show how you can get the device authentication password in ETS.

The user password can be obtained almost the same way as seen in the below screenshot.

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.

Services

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

Send

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

Read

You can use the homeassistant.update_entity service call to issue GroupValueRead requests for all *state_address of an entity. To manually send GroupValueRead requests use the knx.read service. The response can be used from knx_event and will be processed in KNX entities.

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

# Example automation to update a cover position after 10 seconds of movement initiation
automation:
  - trigger:
      - platform: event
        event_type: knx_event
        event_data:
          # Cover move trigger
          destination: "0/4/20"
    action:
      - delay: 0:0:10
      - service: knx.read
        data:
          # Cover position address
          address: "0/4/21"

  - trigger:
      - platform: homeassistant
        event: start
    action:
      # Register the group address to trigger a knx_event
      - service: knx.event_register
        data:
          # Cover move trigger
          address: "0/4/20"
      - service: knx.read
        data:
          # Cover position address
          address: "0/4/21"

Register Event

The knx.event_register service 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.yaml cannot be unregistered. See knx_event

Register Exposure

The knx.exposure_register service can be used to register (or unregister) exposures to the KNX bus. Exposures defined in configuration.yaml 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.

# Example configuration.yaml entry
knx:
  expose:
    - type: temperature
      entity_id: sensor.owm_temperature
      address: "0/0/2"
    - 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: time
      address: "0/0/1"
    - type: datetime
      address: "0/0/23"

Binary Sensor

The KNX binary sensor platform allows you to monitor KNX binary sensors.

Binary sensors are read-only. To write to the KNX bus configure an exposure KNX Integration Expose.

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

Support for automations

You can use a built in event in order to trigger an automation (e.g. to switch on a light when a switch was pressed).

Let’s pretend you have a binary sensor with the name Livingroom.Switch and you want to switch one light on when the button was pressed once and two other lights when the button was pressed twice. context_timeout has to be configured in order for this to work.

# Example automation.yaml entry
automation:
  - trigger:
      platform: numeric_state
      entity_id: binary_sensor.livingroom_switch
      attribute: counter
      above: 0
      below: 2
    condition: 
      - condition: state
        entity_id: binary_sensor.cover_abstell
        state: "on"
    action:
      - entity_id: light.hue_color_lamp_1
        service: light.turn_on
  - trigger:
      platform: numeric_state
      entity_id: binary_sensor.livingroom_switch
      attribute: counter
      above: 1
      below: 3
    condition:
      - condition: state
        entity_id: binary_sensor.cover_abstell
        state: "on"
    action:
      - entity_id: light.hue_bloom_1
        service: homeassistant.turn_on
      - entity_id: light.hue_bloom_2
        service: homeassistant.turn_on

Button

The KNX button platform allows to send concurrent predefined values via the frontend or a platform service. 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.yaml:

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

• DPT6002 (for 1 byte signed integer)
• 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. 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)

The following values are valid for the Home Assistant 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_MODE_HEAT within Home Assistant)
• Cool (maps internally to HVAC_MODE_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 Home Assistant 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)

Cover

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

To use your KNX covers in your installation, add the following lines to your top level KNX Integration configuration key in configuration.yaml:

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

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

# 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

To use your KNX light in your installation, add the following lines to your top level KNX Integration configuration key in configuration.yaml:

# Example configuration.yaml entry
knx:
  light:
    - name: "Kitchen"
      address: "1/0/9"

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

Extended configuration examples

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 communication 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"

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 with its current state.

# 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 with its current state.

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

Sensors are read-only. To write to the KNX bus configure a Number, an exposure KNX Integration Expose or use the knx.send service.

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

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

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

The optional state_address can be used to inform Home Assistant about state changes not triggered by a telegram to the address e.g., if you configure a timer on a channel. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object.

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

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

# 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

Troubleshooting / Common issues

Logs for the KNX integration

xknx, the library used for KNX communication, provides various logging handlers for monitoring and debug purposes. Add the following lines to your Home Assistant configuration.yaml to activate them:

logger:
  default: warning
  logs:
    # For most debugging needs `xnx.log` and one of `xknx.knx` or `xknx.telegram` are a good choice.
    xknx: debug  # sets the level of all loggers
    xknx.log: debug  # provides general information (connection, etc.)
    xknx.raw_socket: debug  # logs incoming UDP frames in raw hex format
    xknx.knx: debug  # logs incoming and outgoing KNX/IP frames at socket level
    xknx.telegram: debug  # logs telegrams before they are being processed at device level or sent to an interface
    xknx.state_updater: debug  # provides information about the state updater

You can use the service logger.set_level 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 communication object (CO) assigned to the group address (GA) has the Read-Flag set in ETS

• Enable the read flag for one CO 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 CO of the dimming actuator).

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

• 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 communication objects to the group addresses you are using in Home Assistant. ETS will generate filter tables that are applied to your line couplers after updating their application.

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.

xknx.yaml configuration

> The 'config_file' option near /homeassistant/configuration.yaml:42 is deprecated, please remove it from your configuration
> Invalid config for [knx]: [config_file] is an invalid option for [knx]. Check: knx->knx->config_file.

The feature to specify a xknx configuration schema file in the Home Assistant configuration YAML file (via config_file:) is deprecated since Home Assistant 2021.4. You can use the xknx.yaml config converter to convert it to a Home Assistant compatible configuration.yaml schema.