KNX Connector Configuration

• Connector configuration: knx.json
  • Section “Client”
    • Subsection “Security”
    • Subsection “Gateways Scanner”
  • Section “Devices”
    • Subsection “Device Info”
    • Subsection “Attributes” and “Timeseries”
  • Section “Attribute Updates”
  • Section “RPC”
• Next steps

This guide will help you get familiar with KNX Connector configuration for ThingsBoard IoT Gateway. Use general configuration guide to enable this Connector. The purpose of this Connector is to connect KNX-based devices to ThingsBoard, allowing to process data from KNX devices and control KNX automation systems.

We will describe the connector configuration file below.

Connector configuration: knx.json

Connector configuration is a JSON file that contains information on how to connect to KNX device, process the data and other service features. Let’s review the format of the configuration file using the example below.

Example of KNX Connector config file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "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"
    }
  ]
}

Section “Client”

Configuration in this section is used to set up the KNX client, that is responsible for communication with KNX router.

Address format:

• SHORT - representation like “1/34” without middle groups;
• LONG - representation like “1/2/34” with middle groups;
• FREE - integer or hex representation.

Type of connection:

• AUTOMATIC - using GatewayScanner for searching and finding KNX/IP devices in the network;
• ROUTING - using KNX/IP multicast routing;
• TUNNELING - connecting to a specific KNX/IP tunneling device via UDP;
• TUNNELING_TCP - connecting to a specific KNX/IP tunneling v2 device via TCP;
• TUNNELING_TCP_SECURE - connecting to a specific KNX/IP tunneling v2 device via secure TCP.

Example:

1
2
3
4
5
6
7
8
"client": {
  "type": "AUTOMATIC",
  "addressFormat": "LONG",
  "localIp": "127.0.0.1",
  "localPort": 3671,
  "autoReconnect": true,
  "autoReconnectWait": 3,
},

Subsection “Security”

By default, the connector uses an unsecured connection.

KNX protocol security consists of two primary security mechanisms designed to protect communication in KNX systems:

• KNX IP Secure - encrypts and secures communication between KNX IP devices (routers and interfaces) over IP networks;
• KNX Data Secure - encrypts communication at the telegram (data) level to prevent unauthorized control or reading of KNX group addresses;
• KNX Secure Tunneling (Extended KNX IP Secure) - encrypts communication between a KNX Secure IP interface and a client.

To enable security, you need to set the following parameters in the “security” subsection of the “client” section:

1
2
3
4
"security": {
    "backbone_key": "secret",
    "latency_ms": 100
}

1
2
3
4
"security": {
    "knxkeys_file_path": "/path/to/knxkeys.knxkeys",
    "knxkeys_password": "password"
}

1
2
3
4
5
6
7
"security": {
    "backbone_key": "secret",
    "latency_ms": 100,
    "user_id": "user",
    "device_authentication_password": "password",
    "user_password": "password"
}

Subsection “Gateways Scanner”

Gateways Scanner is helpful when you don’t know the IP address of the KNX router. It scans the network for KNX routers and prints the detected IP addresses in the log.

These parameters are available for configuration in the “gatewaysScanner” subsection:

This subsection in the configuration file looks like:

1
2
3
4
5
"gatewaysScanner": {
  "enabled": true,
  "scanPeriod": 3,
  "stopOnFound": false
}

Example output:

1
2
3
4
5
Found KNX gateway:
- Calimero test network 1.1.0
  192.168.1.160:3671
  Tunneling: TCP
  Routing: Yes

Section “Devices”

This section is used to configure devices polling period and data processing. The section consists of the array of objects, where each object contains the following fields:

• deviceInfo - device name and profile configuration.
• pollPeriod - polling period in milliseconds.
• attributes - array of objects that contains the configuration of attributes.
• timeseries - array of objects that contains the configuration of time series.

General view of the device configuration looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"devices": [
  {
    "deviceInfo": {
    ...
    },
    "pollPeriod": 5000,
    "attributes": [
    ...
    ],
    "timeseries": [
    ...
    ]        
  }
]

Subsection “Device Info”

This subsection is used to configure the device name and profile that will create on ThingsBoard. These parameters are available for configuration in the “deviceInfo” subsection of the device object:

This subsection in the configuration file looks like:

1
2
3
4
5
6
7
8
"deviceInfo": {
  "deviceNameDataType": "string",
  "deviceNameExpressionSource": "expression",
  "deviceNameExpression": "Device ${1/0/5}",
  "deviceProfileDataType": "none",
  "deviceProfileExpressionSource": "constant",
  "deviceProfileNameExpression": "default"
},

Subsection “Attributes” and “Timeseries”

These subsections are used to configure the telemetry and attributes that will be sent to ThingsBoard and provide the settings for processing data from KNX devices.

The table below describes the attributes and time series parameters:

Example of the attributes section:

1
2
3
4
5
6
7
"attributes": [
  {
    "type": "temperature",
    "key": "temperature",
    "groupAddress": "1/0/6"
  }
],

Example of timeseries section:

1
2
3
4
5
6
7
"timeseries": [
  {
    "type": "humidity",
    "key": "humidity",
    "groupAddress": "1/0/7"
  }
]

Section “Attribute Updates”

This configuration section is optional.

ThingsBoard allows the provisioning of device attributes and fetches some of them from the device application. You can treat this as a remote configuration for devices, enabling them to request shared attributes from ThingsBoard. See the user guide for more details.

The “attributeRequests” configuration allows you to configure the format of the corresponding attribute data that will be sent to the KNX device. The configuration is an array of objects, where each object contains the following fields:

This subsection in the configuration file looks like:

1
2
3
4
5
6
7
8
"attributeUpdates": [
  {
    "deviceNameFilter": ".*",
    "dataType": "percent_U8",
    "groupAddress": "1/0/9",
    "key": "brightness"
  }
],

Section “RPC”

ThingsBoard allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

The configuration provided in this section is used for sending RPC requests from ThingsBoard to device. The configuration is an array of objects, where each object contains the following fields:

This subsection in the configuration file looks like:

1
2
3
4
5
6
7
8
9
"serverSideRpc": [
  {
    "requestType": "read",
    "deviceNameFilter": ".*",
    "method": "get_name",
    "dataType": "string",
    "groupAddress": "1/0/5"
  }
]

Additionally, every telemetry and attribute parameter comes with a built-in SET RPC method out of the box, eliminating the need for manual configuration. To use them, make sure you set all the required parameters (for the KNX Connector, these include: dataType, groupAddress, and value - only if RPC method name is “set”). See the guide for more details.

Next steps

Explore guides related to main ThingsBoard features:

• Data Visualization - how to visualize collected data.
• Device attributes - how to use device attributes.
• Telemetry data collection - how to collect telemetry data.
• Using RPC capabilities - how to send commands to/from devices.
• Rule Engine - how to use rule engine to analyze data from devices.