KNX

The KNX Connector connects KNX-based devices to ThingsBoard, letting the gateway read telemetry and attributes from KNX group addresses and send RPC commands to KNX automation systems.

To enable this connector, add it to the connectors list in tb_gateway.json — see the General Configuration reference.

The connector reads its settings from a JSON file. Below is a full example:

{
  "logLevel": "INFO",
  "client": {
    "type": "AUTOMATIC",
    "addressFormat": "LONG",
    "localIp": "127.0.0.1",
    "localPort": 3671,
    "autoReconnect": true,
    "autoReconnectWait": 3,
    "gatewaysScanner": {
      "enabled": true,
      "scanPeriod": 3,
      "stopOnFound": false
    }
  },
  "devices": [
    {
      "deviceInfo": {
        "deviceNameDataType": "string",
        "deviceNameExpressionSource": "expression",
        "deviceNameExpression": "Device ${1/0/5}",
        "deviceProfileDataType": "none",
        "deviceProfileExpressionSource": "constant",
        "deviceProfileNameExpression": "default"
      },
      "pollPeriod": 5000,
      "attributes": [
        {
          "type": "temperature",
          "key": "temperature",
          "groupAddress": "1/0/6"
        }
      ],
      "timeseries": [
        {
          "type": "humidity",
          "key": "humidity",
          "groupAddress": "1/0/7"
        }
      ]
    }
  ],
  "attributeUpdates": [
    {
      "deviceNameFilter": ".*",
      "dataType": "percent_U8",
      "groupAddress": "1/0/9",
      "key": "brightness"
    }
  ],
  "serverSideRpc": [
    {
      "requestType": "read",
      "deviceNameFilter": ".*",
      "method": "get_name",
      "dataType": "string",
      "groupAddress": "1/0/5"
    },
    {
      "requestType": "write",
      "deviceNameFilter": ".*",
      "method": "set_name",
      "dataType": "string",
      "groupAddress": "1/0/5"
    }
  ]
}

Configures the KNX client responsible for communication with the KNX router.

Address format values:

• SHORT — two-part address, e.g. 1/34 (no middle group)
• LONG — three-part address, e.g. 1/2/34 (with middle group)
• FREE — integer or hex representation

Connection type values:

• AUTOMATIC — scans the network using GatewayScanner to find KNX/IP devices automatically
• ROUTING — KNX/IP multicast routing
• TUNNELING — UDP connection to a specific KNX/IP tunneling device
• TUNNELING_TCP — TCP connection to a KNX/IP tunneling v2 device
• TUNNELING_TCP_SECURE — secure TCP connection to a KNX/IP tunneling v2 device

Example:

"client": {
  "type": "AUTOMATIC",
  "addressFormat": "LONG",
  "localIp": "127.0.0.1",
  "localPort": 3671,
  "autoReconnect": true,
  "autoReconnectWait": 3
}

KNX security provides three complementary protection mechanisms:

• KNX IP Secure — encrypts communication between KNX IP devices (routers and interfaces) over IP networks
• KNX Data Secure — encrypts communication at the telegram level, protecting any medium (TP, RF, or IP)
• KNX Secure Tunneling — authenticates and encrypts tunneling sessions between a client and a KNX Secure IP interface

Configure the desired mechanism by adding a security subsection inside client:

"security": {
  "backbone_key": "secret",
  "latency_ms": 100
}

"security": {
  "knxkeys_file_path": "/path/to/knxkeys.knxkeys",
  "knxkeys_password": "password"
}

"security": {
  "backbone_key": "secret",
  "latency_ms": 100,
  "user_id": "user",
  "device_authentication_password": "password",
  "user_password": "password"
}

Scans the local network for KNX routers — useful when the router IP address is not known in advance. Detected IP addresses are printed to the gateway log.

"gatewaysScanner": {
  "enabled": true,
  "scanPeriod": 3,
  "stopOnFound": false
}

Example log output when a gateway is discovered:

Found KNX gateway:
- Calimero test network 1.1.0
  192.168.1.160:3671
  Tunneling: TCP
  Routing: Yes

Configures polling and data mapping for each KNX device. Each entry in the array defines:

"devices": [
  {
    "deviceInfo": { ... },
    "pollPeriod": 5000,
    "attributes": [ ... ],
    "timeseries": [ ... ]
  }
]

Sets the device name and profile that will be created in ThingsBoard.

"deviceInfo": {
  "deviceNameDataType": "string",
  "deviceNameExpressionSource": "expression",
  "deviceNameExpression": "Device ${1/0/5}",
  "deviceProfileDataType": "none",
  "deviceProfileExpressionSource": "constant",
  "deviceProfileNameExpression": "default"
}

Map KNX group addresses to ThingsBoard attributes and time-series telemetry. Both sections use the same field structure:

"attributes": [
  {
    "type": "temperature",
    "key": "temperature",
    "groupAddress": "1/0/6"
  }
],
"timeseries": [
  {
    "type": "humidity",
    "key": "humidity",
    "groupAddress": "1/0/7"
  }
]

Optional. Writes ThingsBoard shared attribute updates to KNX group addresses, pushing remote configuration changes to connected KNX devices.

"attributeUpdates": [
  {
    "deviceNameFilter": ".*",
    "dataType": "percent_U8",
    "groupAddress": "1/0/9",
    "key": "brightness"
  }
]

Optional. Maps ThingsBoard RPC method calls to KNX read or write operations.

"serverSideRpc": [
  {
    "requestType": "read",
    "deviceNameFilter": ".*",
    "method": "get_name",
    "dataType": "string",
    "groupAddress": "1/0/5"
  }
]

Every attribute and telemetry entry also has a built-in set RPC method available automatically — no manual serverSideRpc entry required. See the Reserved RPC methods guide for details.