KNX

Overview

The BlueRange Gateway is enabled to use the KNXnet/IP protocol by default but you must have a compatible KNX/IP gateway to connect to your KNX installation.

Requirements

To connect BlueRange to a KNX Network, at least one KNXnet/IP Interface (or KNXnet/IP Router) has to be available in the KNX network. The number of Interfaces is bound to the number of connections one Interface can handle and the number of installed BlueRange Gateways, that need a KNX connection.

For a setup, where the number of BlueRange Gateways exceeds the limits of the available KNXnet/IP Interfaces, it is possible to route the communication through a virtualized KNX-Router.

Setting up the KNX Environment and Enrolling Devices

To set up the configuration navigate to > Networks > "Your Network" > Devices and click Add devices.

network add devices

You can now chose to configure KNX devices and you will be required to either insert or upload a configuration in JSON format as detailed below. You KNX devices will be configured according to this list and you can chose to modify a previously uploaded configuration if you want to add or remove devices later on.

network configure knx

The configuration consists of two parts:

gateway: The hostname or IP and port of the KNXnet/IP interface or router
devices: The list of devices, that should be enrolled, to be manageable individually.
1. A device consists of a name (should be unique),
2. a policy – that refers to the name of an existing configuration, which will be applied to the device on enrollment,
3. and an addressMap – that lists all available KNX addresses, which can be read/written. Its key is the type of the actuator/sensor.

Example KNX configuration

{
  "gateway": {
    "hostname": "10.11.12.13",
    "port": 3671
  },
  "devices": [
    {
      "name": "KNX DemoDevice_1",
      "policy": "KNX-PolicyName",
      "addressMap": {
        "SLAT_POSITION": "1/1/2",
        "SLAT_ANGLE": "1/1/3",
        "DRIVE_UP_DOWN": "1/1/4"
      }
    },
    {
      "name": "KNX DemoDevice_2",
      "policy": "KNX-PolicyName",
      "addressMap": {
        "SLAT_POSITION": "1/2/2",
        "SLAT_ANGLE": "1/2/3",
        "DRIVE_UP_DOWN": "1/2/4"
      }
    }
  ]
}

Example Setting

The corresponding settings matching the above example of the KNX configuration can be seen below. To set it up in the BlueRange Server, head over to Configurations and the Device Catalog

The most important values are:

module: which has to be knx
dataType: defining the translated dataType of the KNX data point
length: has to match the length of the dataType
offset: has to be 0
type: the name of data point, which needs to match the key of the addressMap in the KNX configuration

Optional values:

component: value is irrelevant for KNX devices, unless a low level raw IO communication is needed
register: value is irrelevant for KNX devices, unless a low level raw IO communication is needed
index: is used to identify different values of the same type of the same device, default is 0
scale: can be used to transform the value
min: can be used to transform the value
max: can be used to transform the value

Example KNX actuator configuration

{
  "archetype": "BLIND",
  "actuatorModule": [
    {
      "module": "knx",
      "component": 0,
      "register": 1,
      "offset": 0,
      "length": 1,
      "type": "DRIVE_UP_DOWN",
      "index": 0,
      "dataType": "INT8",
      "scale": 1,
      "min": 0,
      "max": 1
    }
  ]
}

Example KNX sensor configuration

{
  "archetype": "BLIND",
  "sensorModule": [
    {
      "module": "knx",
      "component": 0,
      "register": 0,
      "offset": 0,
      "length": 1,
      "type": "SLAT_POSITION",
      "index": 0,
      "dataType": "UINT8",
      "scale": 0.39215686274,
      "min": 0,
      "max": 100,
      "unit": "PERCENT"
    },
    {
      "module": "knx",
      "component": 0,
      "register": 1,
      "offset": 0,
      "length": 1,
      "type": "SLAT_ANGLE",
      "index": 0,
      "dataType": "UINT8",
      "scale": 0.39215686274,
      "min": 0,
      "max": 100,
      "unit": "PERCENT"
    }
  ]
}

After setting up the configuration, choose the BlueRange Gateway of that Network and apply the Action Start KNX Enrollment. This will create the defined devices within the Network, apply the Configuration and connect to the specified KNX Network, ready to be used.

KNX data types translation

KNX data types can be translated into BlueRange data types mapped by the KNX format. The following table shows the translation for the abstract KNX types of the x.yyy notation, where x is the format and encoding and yyy is the value range and unit. Only x is responsible for the BlueRange data type, so only these are listed. To translate the unit, head over to Device Catalog for the list of available BlueRange units.

Table 1. Supported KNX data types
KNX data type	KNX format	BlueRange data type	BlueRange length	Example control
1.yyy	boolean	UINT8	1	switching, move up/down, step
5.yyy	8-bit unsigned value	UINT8	1	dim value (0..100%), blinds position (0..100%)
7.yyy	2 x 8-bit unsigned value	UINT16	2	pulse counter
9.yyy	16-bit float	HALF	2	temperature
12.yyy	4 x 8-bit unsigned value	UINT32	4	pulse counter
14.yyy	32-bit float	FLOAT	4	temperature

KNX address validation

Once everything has been set up, the applied configuration can be validated in the Portal 2.0 in the device details of the enrolled KNX device. The applied KNX policy configuration is matched against the KNX configuration using the type. This allows to validate, if every actuator or sensor is backed by a KNX group address.

knx device address

Connectivity to the KNX network

The Portal 2.0 extends the device details view of the BlueRange Gateway, to validate if it is able to connect to the KNXnet/IP Interface. Here the configured hostname and port is shown, as well as the connection status.

knx gateway config status

Virtualized KNX-Router

The virtualized KNX-Router is an alternative to a hardware KNX-Router, if there are more BlueRange Gateways than possible connections the hardware provides. It provides the functionality to route all BlueRange Gateways KNX communication through this KNX-Router, which is connected to a single KNXnet/IP Interface. It can be requested as containerized image, to be run e.g. in the docker engine.