KNX for Home Assistant (built-in integration)

About

KNX is a built-in Home Assistant integration that connects to a KNX bus over IP and works locally. It supports tunneling and routing connections, including KNX IP Secure and Data Secure with a keyring file exported from ETS. It provides entity platforms such as lights, climate, covers, sensors, switches, fans, weather and several others. Actions can send data to the bus, read group addresses, expose values to the bus, register addresses for event triggering, and reload the integration. Diagnostic sensors report connection status, connection type, individual address and telegram traffic, and a telegram device trigger can start automations. Options cover rate limiting, state reading behavior and telegram history storage, including a PostgreSQL backend, and setup is done in the UI.

Automatic summary of Home Assistant's source code. Something wrong? Get in touch

Supports

Works locally Talks to your devices on your own network. No vendor cloud in between.
Set up in the UI Add it in Settings, Devices and services. Nothing to download.
Device triggers Its devices can start automations directly.
Change settings later Its connection settings can change without removing it.
Platinum quality Home Assistant's own rating of its code and setup experience.
Updated with Home Assistant Ships and updates with every Home Assistant release.

Provides

Lights
Climate
Fans
Covers
Switches
Sensors
Weather

Setting it up

It is added under Settings, Devices and services, with Add integration.

KNX connection

KNX connection typePlease select the connection type you want to use for your KNX connection.

Tunnel endpoint

Select the tunnel endpoint used for the connection.'Automatic' selects a free tunnel endpoint for you when connecting. If you're unsure, this is the best option.

Also asked when at the tunnel endpoint step.

Tunnel settings

HostIP address or hostname of the KNX/IP tunneling device.
Local IP interfaceLocal IP or interface name used for the connection from Home Assistant. Leave blank to use auto-discovery.
PortPort used by the KNX/IP tunneling device.
Route back / NAT modeEnable if your KNXnet/IP tunneling server is behind NAT. Only applies for UDP connections.
KNX tunneling typeSelect the tunneling type of your KNX/IP tunneling device. Older interfaces may only support UDP.

Routing

Individual addressKNX address to be used by Home Assistant, e.g. 0.0.4
Local IP interfaceLocal IP or interface name used for the connection from Home Assistant. Leave blank to use auto-discovery.
Multicast groupMulticast group used by your installation. Default is 224.0.23.12
Multicast portMulticast port used by your installation. Default is 3671
KNX IP Secure RoutingSelect if your installation uses encrypted communication according to the KNX IP Secure standard. This setting requires compatible devices and configuration. You'll be prompted for credentials in the next step.

Import KNX Keyring

Keyring fileSelect a .knxkeys file. This can be exported from ETS.
Keyring passwordThe password to open the .knxkeys file was set when exporting.

Secure routing

Backbone keyCan be seen in the 'Security' report of your ETS project. Eg. 00112233445566778899AABBCCDDEEFF
Network latency toleranceShould be equal to the backbone configuration of your ETS project. Default is 1000

Secure tunneling

Device authentication passwordThis is set in the 'IP' panel of the interface in ETS.
User IDThis usually is tunnel number +1. So first tunnel in the list presented in ETS would have User-ID 2.
User passwordPassword for the specific tunnel connection set in the 'Properties' panel of the tunnel in ETS.

After setup

Rate limitMaximum outgoing telegrams per second. 0 to disable limit. Recommended: 0 or between 20 and 40
State updaterSets the default behavior for reading state addresses from the KNX Bus. When enabled, Home Assistant will monitor each group address and read it from the bus if no value has been received for one hour. When disabled, state addresses will only be read once after a bus connection is established. This behavior can be overridden for individual entities using the sync_state option.
Telegram storage backendSelect where to store KNX telegram history.
Group monitor historyNumber of hours of telegram history to load when the group monitor is opened.
Retention periodNumber of days to keep telegram history. Older telegrams are automatically deleted nightly at 3 AM. Set to 0 to delete all telegram history on every nightly run.
Database nameName of the database to store telegrams in.
HostHostname or IP address of the PostgreSQL server.
PasswordPassword for the PostgreSQL user. Leave blank to keep the current password.
PortPort the PostgreSQL server is listening on.
Use TLSEncrypt the connection to the PostgreSQL server (sslmode=require). Note that the server certificate is not verified.
UsernameUsername to authenticate with the PostgreSQL server.

Texts from Home Assistant's source code, Apache License 2.0.

Entities

SensorsConnection established, Connection type, Individual address, Telegrams, Undecodable Data Secure telegrams, Incoming telegrams, Incoming telegram errors, Outgoing telegrams, Outgoing telegram errors

Actions

Register knx_eventAdds or removes group addresses to knx_event filter for triggering knx_events. Only addresses added with this action can be removed.Fields: Group address, Remove event registration, Value type
Expose to KNX busAdds or removes exposures to KNX bus. Only exposures added with this action can be removed.Fields: Group address, Entity attribute, Default value, Entity, Remove exposure, Value type
Read from KNX busSends GroupValueRead requests to the KNX bus. Response can be used from knx_event and will be processed in KNX entities. When response data is requested, waits for the answer to a single group address and returns it.Fields: Group address
ReloadReloads the KNX integration.
Send to KNX busSends arbitrary data directly to the KNX bus.Fields: Group address, Payload, Send as Response, Value type

Troubleshooting

DiagnosticsDownloads a diagnostics file to attach to a bug report.
Repair noticesNotices it can show in Settings, Repairs:KNX Data Secure telegrams can't be decrypted, Invalid KNX entity configuration, KNX telegram storage error