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
• Climate
• Cover
• Light
• Notify
• Scene
• Sensor
• Switch
• Weather

Basic Configuration

To use your KNX bus in your installation, add the following lines to your configuration.yaml file:

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:

knx:
  binary_sensor: !include knx_binary_sensor.yaml
  switch: !include knx_switch.yaml
  sensor: !include knx_sensor.yaml
  cover: !include knx_cover.yaml
  light: !include knx_light.yaml
  notify: !include knx_notify.yaml
  scene: !include knx_scene.yaml

Please check the dedicated platform documentation 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:

knx:
  config_file: '/path/to/xknx.yaml'

If the auto detection of the KNX/IP device does not work you can specify IP and port of the tunneling device:

knx:
  tunneling:
    host: '192.168.2.23'
    port: 3671
    local_ip: '192.168.2.109'

Explicit connection to a KNX/IP routing device:

knx:
  routing:
     local_ip: '192.168.2.109'

knx:
  fire_event: true
  fire_event_filter: ["1/0/*", "6/2,3,4-6/*"]

Services

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

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

You can also use the homeassistant.update_entity service call to issue GroupValueRead requests for all *state_address of a device.

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'

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

Binary Sensor

To use your binary sensors please add the relevant configuration to your top level KNX Integration configuration key in configuration.yaml:

knx:
  binary_sensor:
    - name: sensor1
      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.

# 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

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: HASS-Kitchen.Temperature
      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: HASS-Kitchen.Temperature
      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: HASS-Kitchen.Temperature
      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: HASS-Kitchen.Temperature
      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 hvac_mode attribute:

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

• 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

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

Configuration

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

Extended configuration example

knx:
  light:
    # dimmable light
    - 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
    - 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
    - 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
    - name: Cellar-Light-1
      address: '1/0/5'
      state_address: '1/0/5'

Notify

The knx notify platform allows you to send notifications to KNX devices.

Configuration

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

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

The knx scenes platform allows you to trigger KNX scenes.

Scene

Configuration

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

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

Sensor

The knx sensor platform allows you to monitor KNX sensors.

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

Configuration

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

# Example configuration.yaml entry
knx:
  sensor:
    - name: Heating.Valve1
      state_address: '2/0/0'

In order to actively read the sensor data from the bus all 30 minutes you can add the following lines to your configuration.yaml:

# Example configuration.yaml entry
knx:
  sensor:
    - name: Heating.Valve1
      state_address: '2/0/0'
      sync_state: every 30

Full example

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

Switch

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

Configuration

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

knx:
  switch:
    - name: Kitchen.Coffee
      address: '1/1/6'

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

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"
      expose_sensors: False
      sync_state: True