Introduction

KNX bus driver is part of the HumanOS® Runtime. It allows to integrate KNX topology into the smart platforms.

This document explicitly describes the KNX driver. For common description on HumanOS® Runtime, Software Design and device information files, see the [Operation Manual].

Driver Configuration

The driver configuration file is named “settings.json” located in: <install directory>\Config\HumanOS.UHAL.KnxBusDriver\

Example of default device configuration:

{
  "Disabled": false,
  "Devices": [
    {
      "MainTaskProcessor": {
        "Name": "Main TaskProcessor",
        "ProcessingPriority": "Normal",
        "MaxSchedulingTimeSlice": 200,
        "MinSchedulingTimeSlice": 10
      }
    }
  ]
}

Device Information File

Each device information file addresses a IP coupler in a KNX topology. Multiple IP couplers can be integrated in the same HumanOS IoT Gateway instance, each one having its own device description and overlapping KNX device addresses.

In the following example, two IP routers (internal address 1.0.0 and 2.0.0) can be integrated in HumanOS with two separate device information files:

The KNX Bus Driver information file contains

• Data Access Points
• Alarm Sources (AlarmEvent Tasks)
• Commands

Detailed reference for device information files, see the HumanOS Operation Manual chapter “Device Information File”.

Connection Address

Use the Ip-address for KNX IP routers to access them:

Name	Description	Example
Ethernet	Connection over ethernet (IP tunneling). The address is {IP-Address}:{port}	192.168.28.20:3671

CAUTION

USB connections are not supported in the current version

Example connecting over KNX ip tunneling:

{
  "Name": "BuildingA",
  "Id": "3228f878-e1f3-4f62-84af-d9b6b0a18182",
  "DriverId": "2C42F493-2FF8-4E59-9A82-FAAC966992CF",
  "Address": "192.168.28.20:8271",
  "DataNodes": [ ]
}

Commands

Pinging a Device

The command "Knx.PingDevice" can be used to detect if a device is online.

Input Arguments:

Name	Description	Data Type
Address	Address of the device, e.g. "1.3.2"	System.String

Output Argument:

Name	Description	Data Type
Result	Flag if ping has been responded.	System.Boolean

IMPORTANT

Note that a device - even if it exists - may not be reachable and thus not reported by this method. Reasons for this include:

• Battery-driven devices are not reachable when in energy-saving mode
• When a device is connected to the wrong segment, or when couplers between ETS and the device are not commissioned correctly, the communication across couplers may not work

Example:

{
  "Id": "A7AE5AD1-4A42-4425-94FD-966B1A2A21CD",
  "Name": "PingDevice",
  "Type": "CommandNode",
  "Address": "Knx.PingDevice",
  "Arguments": [
    {
      "Name": "Address",
      "Type": "Input",
      "DataType": "System.String",
      "Description": "Device address"
    },
    {
      "Name": "Result",
      "Type": "Output",
      "DataType": "System.Boolean",
      "Description": "Ping return"
    }
  ]
}

Writing Group Values

The command "Knx.WriteGroupValue" allows to write values to a group of devices.

Input Arguments:

Name	Description	Data Type
Address	Address of the group, e.g. "1/4/3"	System.String
Value	Value to write	System.Byte[]

Output Argument:

No output. Check the command return state to check if the value has bee written to the device.

Example:

{
  "Id": "A7AE5AD1-4A42-4425-94FD-966B1A2A21CD",
  "Name": "WriteGroupValue",
  "Type": "CommandNode",
  "Address": "Knx.WriteGroupValue",
  "Arguments": [
    {
      "Name": "Address",
      "Type": "Input",
      "DataType": "System.String",
      "Description": "Group address"
    },
    {
      "Name": "Value",
      "Type": "Input",
      "DataType": "System.Byte[]",
      "Description": "Data"
    }
  ]
}

Read Group Values

The command "Knx.ReadGroupValue" allows to read values from a group of devices.

Input Arguments:

Name	Description	Data Type
Address	Address of the group, e.g. "1/4/3"	System.String

Output Argument:

Name	Description	Data Type
Value	Value from KNX Bus	System.Byte[]

Example:

{
  "Id": "A7AE5AD1-4A42-4425-94FD-966B1A2A21CD",
  "Name": "ReadGroupValue",
  "Type": "CommandNode",
  "Address": "Knx.ReadGroupValue",
  "Arguments": [
    {
      "Name": "Address",
      "Type": "Input",
      "DataType": "System.String",
      "Description": "Group address"
    },
    {
      "Name": "Value",
      "Type": "Output",
      "DataType": "System.Byte[]",
      "Description": "Data from knx"
    }
  ]
}

Memory Addresses

This chapter outlines all possible native addresses. These addresses must be configured within the device configuration.

Format

A native KNX address has following format:

{DeviceAddress}@{MemoryType}.{DataType}:{address}

Device Address

The device address points to the KNX device holding the registers for reading or writing. The KNX device address is made of three bytes:

• Byte 0: Area
• Byte 1: Line
• Byte 2: Address

The plugin supports the string notation: <Byte0>.<Byte1>.<Byte2>

Example to read 10 bytes out of memory register 0x4000 from device 1.1.1:

1.1.1@Memory.Uint8[10]:4000

Some reading or writing supports also the group address format, e.g. 1/2/9.

1/2/9@Group.Uint8:0

Data Types

Each memory is natively read as byte-array. However, the byte array can be converted to other primitive data types. Memory reading supports following data types:

Data Type	Description
Bool	1-bit value
Uint8	8-bit unsigned integer
Uint16	16-bit unsigned integer
Uint32	32-bit unsigned integer
Uint64	64-bit unsigned integer
Int8	8-bit signed integer
Int16	16-bit signed integer
Int32	32-bit signed integer
Int64	64-bit signed integer
Float32	32-bit floating point number
Float64	64-bit floating point number

For each data type can also be declared as an array, e.g. Uint32[100] declares an array of 100 32-bit values.

Reading System Variables

Address	Description	DataType
Global@System.Bool:Available	Available flag. 0 = Connection offline, 1 = online	System.Boolean
Global@System.Int32:SignalOfLife	Signal of Life; Alternates in 1 Hz if connection is online	System.Int32

Reading Memory

The memory of a KNX device can be read. There exist following memory types:

Memory Types

Memory Type	Description
Memory	Default memory of device (readonly)
RouterMemory	Router memory of device (readonly)
RoutingTableMemory	Routing table memory (readonly)
UserMemory	User memory of the device (readonly)

Example reading user memory:

{
  "Id": "A3C14B6D-9365-494E-BE12-72435C18EAAC",
  "Name": "UserMemory1",
  "DataClass": "Event",
  "DataType": "System.Int32",
  "Address": "1.1.1@UserMemory.Int32:8112",
  "Access": {
    "Read": true,
    "Receive": true
  }
}

Reading and Writing Properties

Properties of KNX devices can be individually read or written.

Memory Type	Description
Property	Reads or writes a property value

Simple Property

The property address contains {ObjectIndex}:{PropertyId}

Example reading/writing a property 9 from object 12:

1.1.1@Property.Int32:12:9

Example:

{
  "Id": "5726E1AF-DA14-43B3-A971-57FBA302C2F6",
  "Name": "Property_X",
  "DataClass": "Event",
  "DataType": "System.Int32",
  "Address": "1.1.1@Property.Int32:2:8",
  "Access": {
    "Read": true,
    "Receive": true,
    "Write" : true
  }
}

Array Properties

To read array properties, additional offset information must be added to the address.

The property address contains {ObjectIndex}:{PropertyId}:{Offset}

Example reading a property 9 from object 12. The property is read as an array of 12 bytes and an offset of 5 bytes in the original array in the device register.

1.1.1@Property.Uint8[12]:12:9:5

Example reading two Uint32 values with offset 0

1.1.1@Property.Uint32[2]:12:9:0

info

NOTE: The element length depends directly on the data type byte size. For instance, Uint32 automatically uses element length of 4 bytes.

Example:

{
  "Id": "115E2C45-63AE-4763-9EAB-8D5EF02DB97D",
  "Name": "Property_A",
  "DataClass": "Event",
  "DataType": "System.Byte[]",
  "Address": "1.1.1@Property.Uint8[4]:1:7:0",
  "Access": {
    "Read": true,
    "Receive": true
  }
}

Reading or Writing Group Values

The drivers supports to read and write values from groups.

Memory Type	Description
Group	Reads or writes a group values

NOTE

Use commands Knx.WriteGroupValue or Knx.ReadGroupValue for flexible writing or reading values.

Example

{
  "Id": "93DEE416-DF8C-4F89-8BCE-EB21EF4963A9",
  "Name": "GroupValue",
  "DataClass": "Event",
  "DataType": "System.Byte",
  "Address": "1/2/3@Group.Uint8:0",
  "Access": {
    "Read": true,
    "Receive": true
  }
}