Qt KNX Overview

KNX is a standard for controlling home and building management equipment, such as: lighting, blinds and shutters, security systems, energy management, heating, ventilation and air-conditioning systems, signaling and monitoring systems, interfaces to service and building control systems, remote control, metering, audio and video control.

Qt KNX implements the client side of a connection between a client and a KNXnet/IP server. This connection enables sending messages to the KNX bus and controlling the functionalities of the KNX devices. Only local device management procedures and KNX application services working with group addressing are fully supported.

KNXnet/IP Server Communication

The first step in the communication process between a client and a KNXnet/IP server is to discover the KNXnet/IP server. This can be done using the class QKnxNetIpServerDiscoveryAgent. If the description of the server during the discovery is not enough, it is possible to learn more about a particular server using the class QKnxNetIpServerDescriptionAgent.

Creating Connections

Once the server is discovered, in order to send messages to the KNX devices, a connection must be established with the server data endpoints. The client requests this connection by using the server's control endpoint.

Depending on the client's goal, different connections have to be opened. If the client wants to access the management functionalities of the KNXnet/IP server, the class QKnxNetIpDeviceManagement takes care of opening and maintaining the connection. If the client wants to access the functionalities of a KNX device on the bus behind the KNXnet/IP server, the class QKnxNetIpTunnel takes care of the connection.

For more information, see Qt KNX Device Management Classes and Qt KNX Tunneling Classes.

Sending Frames

Frames can be sent to the KNXnet/IP server by using QKnxNetIpTunnel or QKnxNetIpDeviceManagement. With the former, QKnxLinkLayerFrame objects are sent and with the latter, QKnxDeviceManagementFrame objects are sent.

To help build the frames, the following classes are provided:

• QKnxLinkLayerFrame::Builder
• QKnxDeviceManagementFrame::Builder
• QKnxDeviceManagementFrame::PropertyReadBuilder
• QKnxDeviceManagementFrame::PropertyWriteBuilder
• QKnxDeviceManagementFrame::PropertyInfoBuilder
• QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder
• QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder
• QKnxDeviceManagementFrame::ResetBuilder

QKnxDeviceManagementFrame objects are dedicated to the KNXnet/IP device management. Sending those frames allows access to the server's interface objects. The QKnxInterfaceObjectType holds the type of an interface object. The objects themselves hold the properties and functionalities of the server. The client can use QKnxDeviceManagementFrame to read and write the values in the server's interface objects.

QKnxLinkLayerFrame objects are sent to the KNX devices on the bus, behind the KNXnet/IP server. To build the frames, the following are needed:

• The address that the frame has to be sent to, represented by QKnxAddress.
• The KNX application service the client wants to use. For a list of available services, see QKnxTpdu::ApplicationControlField.
• The data. Needed if a write service is being triggered.

Link Layer Frame Addresses

The link layer frame destination address QKnxAddress can be individual or a group (see QKnxAddress::Type). An individual address targets a specific device on the bus. A group address targets one or several instances of a datapoint.

A datapoint represents a device functionality. Datapoint types are held by QKnxDatapointType. To be grouped under the same group address, datapoint instances, also called group objects, must be of the same type. The group addresses and the group objects they represent are defined in the KNX project file.

KNX Application Service

The KNX application service and data are encapsulated in the QKnxTpdu part of QKnxLinkLayerFrame.

Datapoints

The data is the representation of the device functionality. It is the bits corresponding to a given group object or interface object property.

If the client is addressing a group object, the QKnxByteArray data is easily built using the appropriate QKnxDatapointType type. The group object is a realization of a datapoint at the level of the device. To create data corresponding to a given datapoint, one must know the type of the datapoint.

The datapoint type is found in the KNX project file where the group address is described. The main and sub-number of the datapoint indicate its type. The class QKnxDatapointTypeFactory can create the QKnxDatapointType corresponding to those two numbers.

Example

For example, a client has a tunnel connection in place and wants to turn on a lamp. From the KNX project file, the client knows the switch of the lamp is linked to the group address 2/6/4 and that the main- and sub-number of the corresponding datapoint type are 1.1.

QKnxNetIpTunnel connection;
connection.connectToHost(QHostAddress(...), port);

QKnxLinkLayerFrame frame = QKnxLinkLayerFrame::builder()
    .setDestinationAddress({ QKnxAddress::Type::Group, QLatin1String("2/6/4") })
    .setTpdu({
        QKnxTpdu::TransportControlField::DataGroup,
        QKnxTpdu::ApplicationControlField::GroupValueWrite,
        QKnxSwitch(QKnxSwitch::State::On).bytes()
    }).create();

connection.sendFrame(frame);