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.

Please note, the knx platform does not support KNX Secure.

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

Configuration

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

knx:

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'

Configuration Variables

config_filestring(Optional)

The path for XKNX configuration file. See xknx.io for details

rate_limitinteger(Optional, default: 20)

Defines the maximum number of telegrams to be sent to the bus per second (range 1-100).

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'

Configuration Variables

hoststringRequired

Host of the KNX/IP tunneling device.

portinteger(Optional)

Port of the KNX/IP tunneling device.

local_ipstring(Optional)

IP of the local interface.

Explicit connection to a KNX/IP routing device:

knx:
  routing:
     local_ip: '192.168.2.109'

Configuration Variables

local_ipstringRequired

The local IP address of interface (which should be used for multicasting).

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

Configuration Variables

fire_eventboolean(Inclusive, default: false)

If set to True, platform will write all received KNX messages to event bus

fire_event_filterlist | string(Inclusive)

If fire_event is set fire_event_filter has to be specified. fire_event_filter defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the Home Assistant event bus.

state_updaterboolean(Optional, default: true)

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.

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}

Configuration Variables

addressstring

KNX group address

payloadinteger | list

Payload, either an integer or an array of integers

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'

Configuration Variables

typestringRequired

Type of the exposed value. Either ‘binary’, ‘time’, ‘date’, ‘datetime’ or any supported type of KNX Sensor (e.g., “temperature” or “humidity”).

entity_idstring(Optional)

Entity id to be exposed. Not needed for types time, date and datetime.

attributestring(Optional)

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

defaultboolean | string | integer | float(Optional, default: None)

Default value to send to the bus if the state or attribute value is None. Eg. a light with state “off” has no brightness attribute so a default value of 0 could be used. If not set (or None) no value would be sent to the bus and a GroupReadRequest to the address would return the last known value.

addressstringRequired

KNX group address.