Qt KNX Tunneling Classes

Tunneling refers to point-to-point exchange of KNX telegrams over an IP network between a KNXnet/IP server and a KNXnet/IP client for configuration and diagnostics. KNX frames are encapsulated inside IP datagrams. A tunnel is created when Engineering Tool Software (ETS) sends a single KNX frame in a KNXnet/IP frame and waits until the response arrives or a time-out is reached.

Tunneling is implemented at the KNX data link layer by transferring link layer frames. The KNX application service and data are encapsulated in the transport protocol data unit (TPDU) included in the frame.

The following diagram shows the main Qt KNX module classes that enable tunneling:

Creating Tunneling Connections

The QKnxNetIpTunnel class is used to establish a functional connection from a KNXnet/IP client to the endpoint of a KNXnet/IP server for sending a KNX frame. For more information, see Tunnel Client Example.

As an alternative, the QKnxNetIpTunnelingRequestProxy class can be used to read a tunneling request from the generic QKnxNetIpFrame class and to create a KNXnet/IP tunneling request frame. Similarly, the QKnxNetIpTunnelingAcknowledgeProxy class can be used to create a KNXnet/IP tunneling acknowledgment frame to confirm the reception of the request.

Sending Frames Through Tunnels

QKnxLinkLayerFrame objects are sent to the KNX devices on the bus, behind the KNXnet/IP server. In accordance with the KNXnet/IP tunneling specifications, only the QKnxLinkLayerFrame::MessageCode values listed below are valid link layer frame message codes to be sent via a KNXnet/IP tunnel connection:

  • DataRequest (L_Data.req)
  • DataConfirmation (L_Data.con)
  • DataIndication (L_Data.ind)
  • BusmonitorIndication (L_Busmon.ind)
  • RawRequest (L_Raw.req)
  • RawIndication (L_Raw.ind)
  • RawConfirmation (L_Raw.con)
  • ResetRequest (M_Reset.req)

Each KNXnet/IP tunneling connection corresponds to a KNX individual address (QKnxAddress) that is assigned to the connection by the server. The individual address must be unique within the open tunneling connections of the device. A server cannot open two or more tunneling connections with the same individual address.

The individual address is returned in a connection response data (CRD) structure with the connect response QKnxNetIpFrame. The CRD structure is constructed from the generic QKnxNetIpCrd class by using the QKnxNetIpCrdProxy class. The contents of the KNXnet/IP frame can be read by using the QKnxNetIpConnectResponseProxy view class.

If the KNXnet/IP server has no free addresses available, the connection response contains the error code QKnx::NetIp::NoMoreUniqueConnections.

In addition to the individual address, link layer frames contain the KNX application service the client wants to use (QKnxTpdu::ApplicationControlField) and the data (QKnxDatapointType, for write services).

The QKnxLinkLayerFrame::Builder class can be used to create valid link layer frames. It is set up with default values to create a common external message interface (cEMI) group value read frame, except for the destination address, which needs to be specified during the creation of the frame.

List of Tunneling Classes


Enables the opening and handling of a KNXnet/IP client connection to a KNXnet/IP server


The means to read a tunneling acknowledgment from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information


The means to read a tunneling request from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information


Frame that is sent over a communication channel established between a KNXnet/IP client and a KNXnet/IP server


QKnxLinkLayerFrame::Builder class provides the means to create a KNX link layer frame


Represents a TPDU, which is the part of a link layer frame to be read by the network, transport, and application layers

© 2018 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.