Qt KNXnet/IP Connection Classes

The integration of KNX protocol implementations on top of internet protocol (IP) networks is called KNXnet/IP. The Qt KNX module implements the client side of a connection between KNX devices connected to an IP network, called KNXnet/IP devices. The IP network provides a fast backbone for KNX installations.

To communicate with a KNXnet/IP server, the KNXnet/IP client must first discover the server by using the QKnxNetIpServerDiscoveryAgent class. If necessary, the QKnxNetIpServerDescriptionAgent and QKnxNetIpServerInfo classes can be used to obtain additional information about a particular server.

Once the KNXnet/IP server is discovered, the KNXnet/IP client uses the server endpoints to establish a communication channel to the server for transferring KNXnet/IP frames. Usually, the QKnxNetIpTunnel or QKnxNetIpDeviceManagement class is used to establish a functional connection to a KNXnet/IP server.

KNXnet/IP Frames

The body of every KNXnet/IP frame (QKnxNetIpFrame) sent over an established communication channel starts with a data field that contains additional general information about the data connection (QKnxNetIpConnectionHeader). The amount of this data and what type of information is included there in particular is determined by several options during the connection phase of a communication channel.

To deal with the high number of specializations needed for the KNXnet/IP frame, the proxy pattern was introduced. The proxy classes provide the means to read a request, response, or acknowledgment from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information.

For example, the following code sample illustrates how to use the QKnxNetIpSearchRequestProxy class to read the search request information sent by a KNXnet/IP client:

auto netIpFrame = QKnxNetIpFrame::fromBytes(...);

QKnxNetIpSearchRequestProxy searchRequest(netIpFrame);
if (!searchRequest.isValid())
    return;

QKnxNetIpHpai hpai = searchRequest.discoveryEndpoint();
// ...

Because the frame is a structure that has many fields, having to know the exact order of parameters that can be passed to the constructor makes it difficult to use correctly. To make this easier, the builder pattern was introduced. The builder classes enable the encapsulation of the construction, and thus provide a more flexible solution.

The following code sample illustrates how to create a search request using the QKnxNetIpSearchRequestProxy::Builder class:

auto hpai = QKnxNetIpHpaiProxy::builder().create();

auto netIpFrame = QKnxNetIpSearchRequestProxy::builder()
    .setDiscoveryEndpoint(hpai)
    .create();

The following sections describe the process of establishing a communication channel between a KNXnet/IP client and a KNXnet/IP server using the proxy or builder classes.

Similar proxy and builder patterns are available for constructing KNXnet/IP device information block (DIB), connection request information (CRI), and connection response data (CRD) structures from generic classes that are based on the QKnxNetIpStruct class. These data structures can be encapsulated in a KNXnet/IP frame. The QKnxNetIpStructHeader class specifies the type of the data structure.

Discovering KNXnet/IP Servers

To discover KNXnet/IP servers, a KNXnet/IP client sends a search request frame (QKnxNetIpSearchRequestProxy or QKnxNetIpSearchRequestProxy::Builder) or an extended search request frame (QKnxNetIpSearchRequestProxy::ExtendedBuilder) using its discovery endpoint.

All servers that receive the search request immediately send a search response (QKnxNetIpSearchResponseProxy or QKnxNetIpSearchResponseProxy::Builder) using the host address protocol information (HPAI) of the client's discovery endpoint. The search response frame contains the HPAI of the server's control endpoint for all further communication.

Before communicating with a KNXnet/IP server, the KNXnet/IP client sends a description request (QKnxNetIpDescriptionRequestProxy or QKnxNetIpDescriptionRequestProxy::Builder) through a unicast or point-to-point connection to all control endpoints of the server to check that the server supports the requested connection type and options. The server replies by sending a description response frame (QKnxNetIpDescriptionResponseProxy or QKnxNetIpDescriptionResponseProxy::Builder) that contains the requested information.

Search and description response frames contain information about the KNXnet/IP server as a KNXnet/IP DIB structure. A DIB structure is constructed by using the QKnxNetIpDeviceDibProxy or QKnxNetIpDeviceDibProxy::Builder class to read the device information from the generic QKnxNetIpDib class. The following proxy and builder classes can be used to read other types of device information from the class:

Creating Extended Search Requests

An extended search request (QKnxNetIpSearchRequestProxy::ExtendedBuilder) contains a search request parameter (SRP) block that indicates whether a particular server should respond to the request. Specialized builder classes can be used to create SRP blocks of each SRP type:

  • The QKnxNetIpSrpProxy::MacAddress class provides the means to create a Select By MAC Address SRP. It indicates that the KNXnet/IP client is interested only in responses from the KNXnet/IP server with the given MAC address.
  • The QKnxNetIpSrpProxy::ProgrammingMode class provides the means to create a Select By Programming Mode SRP. It indicates that the client is interested only in responses from servers in which Programming Mode is currently enabled.
  • The QKnxNetIpSrpProxy::SupportedFamily class provides the means to create a Select By Service SRP. It indicates that the client is interested only in responses from servers supporting the given service family in at least the given version.
  • The QKnxNetIpSrpProxy::RequestDibs class provides the means to create a Request DIBs SRP. It indicates that the client is interested in the listed description information blocks (DIBs).

Creating and Maintaining Communication Channels

To establish a communication channel to a KNXnet/IP server, a KNXnet/IP client sends a connection request (QKnxNetIpConnectRequestProxy or QKnxNetIpConnectRequestProxy::Builder). The connection request provides information needed for different types of communication channels to fulfill a connection request as a KNXnet/IP CRI structure. A CRI structure is constructed from the generic QKnxNetIpCri class by using the QKnxNetIpCriProxy or QKnxNetIpCriProxy::Builder class.

In response, the KNXnet/IP server sends a connection response frame (QKnxNetIpConnectResponseProxy or QKnxNetIpConnectResponseProxy::Builder) that returns the group address or individual address (QKnxAddress) that is assigned to the connection by the server.

The address is returned in a CRD structure with the connect response QKnxNetIpFrame. The CRD structure is constructed from the generic QKnxNetIpCrd class by using the QKnxNetIpCrdProxy or QKnxNetIpCrdProxy::Builder class.

If the server accepted the request, the frame also contains the identifier and HPAI of the data endpoint that the server prepared for the communication channel.

A KNXnet/IP client reqularly sends a connection state request frame (QKnxNetIpConnectionStateRequestProxy or QKnxNetIpConnectionStateRequestProxy::Builder) to the KNXnet/IP server's control endpoint to check the state of a connection established to the server. The server responds immediately with a connection state response frame (QKnxNetIpConnectionStateResponseProxy or QKnxNetIpConnectionStateResponseProxy::Builder).

Sending Service Requests

Once the communication channel is established, the KNXnet/IP client can send tunneling requests (QKnxNetIpTunnelingRequestProxy or QKnxNetIpTunnelingRequestProxy::Builder) and device configuration requests (QKnxNetIpDeviceConfigurationRequestProxy or QKnxNetIpDeviceConfigurationRequestProxy::Builder) to the KNXnet/IP server. The server responds with a tunneling acknowledgment (QKnxNetIpTunnelingAcknowledgeProxy or QKnxNetIpTunnelingAcknowledgeProxy::Builder) or a device configuration acknowledgment (QKnxNetIpDeviceConfigurationRequestProxy or QKnxNetIpDeviceConfigurationRequestProxy::Builder), respectively.

If the KNXnet/IP client does not receive an acknowledgment within a specified timeout, or the status of a received acknowledgment frame indicates that errors occurred, the client repeats the request frame the specified number of times and then terminates the connection by sending a disconnection request (QKnxNetIpDisconnectRequestProxy or QKnxNetIpDisconnectRequestProxy::Builder) to the server's control endpoint.

For more information about device management and tunneling, see Qt KNX Device Management Classes and Qt KNX Tunneling Classes.

KNXnet/IP Endpoints

The HPAI structure (read from the generic QKnxNetIpHpai class by using QKnxNetIpHpaiProxy or QKnxNetIpHpaiProxy::Builder) contains the IP address and port number needed to send a KNXnet/IP frame to another device. Different types of endpoints provide logical views of a HPAI to access devices for a particular purpose.

Each KNXnet/IP device supports one device-related, bi-directional, and connectionless discovery endpoint for device discovery and another one for control. In addition, each device supports one connection-oriented endpoint for service type related data transmission.

The control endpoint uniquely identifies a KNXnet/IP server that provides at least one type of KNXnet/IP service.

Routing

KNXnet/IP routing is defined as a set of KNXnet/IP routers communicating over a one-to-many communication relationship (multicast), in which KNX data is transferred from one device to one or more other devices simultaneously over an IP network. A set of KNXnet/IP routers can replace KNX line and backbone couplers and connected main lines, allowing usage of existing cabling (such as Ethernet) and faster transmission times (and simultaneousness) between KNX subnets. The IP network acts as a fast backbone that connects KNX subnets and is a high-speed replacement for the KNX backbone.

The QKnxNetIpRouter class enables sending and receiving routing KNXnet/IP packets to and from other KNXnet/IP routers.

A routing indication is sent by a KNXnet/IP router or device to transmit KNX link layer frames over IP networks. The QKnxNetIpRoutingIndicationProxy and QKnxNetIpRoutingIndicationProxy::Builder class provides the means to read a routing indication from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information.

Depending on the configuration, a KNXnet/IP router or device can receive more datagrams than it can forward to the KNX subnetwork. This can lead to an overflow of the datagram queue and subsequent loss of one or more KNXnet/IP telegrams, because they could not be transferred from the network buffer to the queue to the underlying KNX subnetwork.

Flow control is implemented by means of sending router busy messages to avoid the loss of datagrams due to overflowing queues in routers and devices. Router busy messages are created by using the QKnxNetIpRoutingBusyProxy or QKnxNetIpRoutingBusyProxy::Builder class.

A routing-lost message is multicast by a KNXnet/IP router to notify that KNXnet/IP routing indication frames were lost. The message contains the state of the router or device (QKnx::NetIp::DeviceState) and the number of lost frames. The messages are created by using the QKnxNetIpRoutingLostMessageProxy or QKnxNetIpRoutingLostMessageProxy::Builder class.

List of KNXnet/IP Classes

QKnxNetIpConfigDibProxy

The means to read the IP configuration from the generic QKnxNetIpDib class and to create a KNXnet/IP current IP configuration (DIB) structure based on the information

QKnxNetIpConnectRequestProxy

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

QKnxNetIpConnectResponseProxy

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

QKnxNetIpConnectionHeader

KNXnet/IP frame connection header

QKnxNetIpConnectionStateRequestProxy

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

QKnxNetIpConnectionStateResponseProxy

The means to read a KNXnet/IP connection state response from the generic QKnxNetIpFrame class and to create a connection state response frame based on the information

QKnxNetIpCrd

Stores the data block returned with a KNXnet/IP connection request frame

QKnxNetIpCrdProxy

The means to read the KNXnet/IP connection response data (CRD) from the generic QKnxNetIpCrd class and to create a KNXnet/IP CRD structure based on the information

QKnxNetIpCri

Stores the additional information needed by communication channels to fulfill a connection request

QKnxNetIpCriProxy

The means to read the connection request information (CRI) from the generic QKnxNetIpCri class and to create a KNXnet/IP CRI structure based on the information

QKnxNetIpCurrentConfigDibProxy

The means to read the current IP configuration from the generic QKnxNetIpDib class and to create a KNXnet/IP current IP configuration (DIB) structure based on the information

QKnxNetIpDescriptionRequestProxy

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

QKnxNetIpDescriptionResponseProxy

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

QKnxNetIpDeviceConfigurationAcknowledgeProxy

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

QKnxNetIpDeviceConfigurationRequestProxy

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

QKnxNetIpDeviceDibProxy

The means to read the device information of a KNXnet/IP device from the generic QKnxNetIpDib class and to create a KNXnet/IP device information block (DIB) structure

QKnxNetIpDeviceManagement

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

QKnxNetIpDib

Stores a specific block of device information that is used when responding to a KNXnet/IP description request

QKnxNetIpDisconnectResponseProxy

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

QKnxNetIpEndpointConnection

Serves as base class for derived classes to enable the opening and handling of a client connection to a KNXnet/IP server

QKnxNetIpExtendedDeviceDibProxy

The means to read the extended device information of a KNXnet/IP device from the generic QKnxNetIpDib class and to create a KNXnet/IP extended device information block (DIB) structure

QKnxNetIpFrame

Represents the base for all KNXnet/IP related communication

QKnxNetIpFrameHeader

KNXnet/IP frame header

QKnxNetIpHpai

Stores the address information required to uniquely identify a communication channel on the host protocol

QKnxNetIpHpaiProxy

The means to read the KNXnet/IP host address protocol information (HPAI) from the generic QKnxNetIpHpai class and to create such a structure

QKnxNetIpKnxAddressesDibProxy

The means to read all assigned individual addresses of a KNXnet/IP device from the generic QKnxNetIpDib class and to create a KNXnet/IP addresses device information block (DIB) structure

QKnxNetIpManufacturerDibProxy

The means to read the manufacturer specific device information from the generic QKnxNetIpDib class and to create a KNXnet/IP manufacturer specific device information block (DIB) structure

QKnxNetIpRouter

Enables sending and receiving routing KNXnet/IP packets to and from other KNXnet/IP routers

QKnxNetIpRoutingBusyProxy

The means to read a router busy message from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information

QKnxNetIpRoutingIndicationProxy

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

QKnxNetIpRoutingLostMessageProxy

The means to read a routing-lost message from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information

QKnxNetIpRoutingSystemBroadcastProxy

The means to introspect a generic routing system broadcast QKnxNetIpFrame and to create a KNXnet/IP frame based on the information

QKnxNetIpSearchRequestProxy

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

QKnxNetIpSearchResponseProxy

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

QKnxNetIpSecureWrapperProxy

The means to introspect secure wrapper data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP secure wrapper frame from provided data

QKnxNetIpSecuredServiceFamiliesDibProxy

The means to introspect the supported service families and required security version inside the generic QKnxNetIpDib class and to create a KNXnet/IP device information block (DIB) structure based on the information

QKnxNetIpServerDescriptionAgent

Establishes a point-to-point connection with a KNXnet/IP server and requests its description

QKnxNetIpServerDiscoveryAgent

Discovers KNXnet/IP servers by sending a search request in the network that the client is connected to

QKnxNetIpServerInfo

Stores information about a KNXnet/IP server

QKnxNetIpServiceFamiliesDibProxy

The means to read the supported service families and versions from the generic QKnxNetIpDib class and to create a KNXnet/IP device information block (DIB) structure based on the information

QKnxNetIpSessionAuthenticateProxy

The means to introspect session authentication data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP session authentication frame from provided data

QKnxNetIpSessionRequestProxy

The means to introspect session request data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP session request frame from provided data

QKnxNetIpSessionResponseProxy

The means to introspect session response data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP session response frame from provided data

QKnxNetIpSessionStatusProxy

The means to introspect secure session status data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP secure session status frame from provided data

QKnxNetIpSrp

Stores an extended search request parameter (SRP)

QKnxNetIpStruct

Represents a generic data structure encapsulated in a KNXnet/IP frame

QKnxNetIpStructHeader

KNXnet/IP structure header

QKnxNetIpTimerNotifyProxy

The means to introspect timer notify data inside the generic QKnxNetIpFrame class and to create a KNXnet/IP timer notify frame from provided data

QKnxNetIpTunnel

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

QKnxNetIpTunnelingAcknowledgeProxy

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

QKnxNetIpTunnelingFeatureGetProxy

The means to access the information carried by a generic tunneling feature-get service QKnxNetIpFrame frame and to create a KNXnet/IP frame based on the information

QKnxNetIpTunnelingFeatureInfoProxy

The means to access the information carried by a generic tunneling feature-info service QKnxNetIpFrame frame and to create a KNXnet/IP frame based on the information

QKnxNetIpTunnelingFeatureResponseProxy

The means to access the information carried by a generic tunneling feature-response service QKnxNetIpFrame frame and to create a KNXnet/IP frame based on the information

QKnxNetIpTunnelingFeatureSetProxy

The means to access the information carried by a generic tunneling feature-set service QKnxNetIpFrame frame and to create a KNXnet/IP frame based on the information

QKnxNetIpTunnelingInfoDibProxy

The means to read the maximum ADPU length supported by a KNXnet/IP tunneling interface and tunneling slot information from the generic QKnxNetIpDib class and to create a KNXnet/IP tunneling information block (DIB) structure

QKnxNetIpTunnelingRequestProxy

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

QKnxNetIpTunnelingSlotInfo

Contains information about the individual address that is currently assigned to the tunneling slot as well as the current state of the tunneling slot

QKnxSecuredServiceInfo

Contains the supported service family and the corresponding required security version

QKnxServiceInfo

Contains the supported service and the corresponding service family version

© 2024 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.