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.

The Qt KNX module contains a set of proxy classes that 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.

Note: In most programs, these classes will not be used directly. Instead, the QKnxNetIpTunnel or QKnxNetIpDeviceManagement class is used to establish a functional connection to a KNXnet/IP server.

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

Discovering KNXnet/IP Servers

To discover KNXnet/IP servers, a KNXnet/IP client sends a search request frame (QKnxNetIpSearchRequestProxy) via multicast using its discovery endpoint. All servers that receive the request immediately send a search response (QKnxNetIpSearchResponseProxy) 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 (QKnxNetIpHpai) for all further communication.

Before communicating with a KNXnet/IP server, the KNXnet/IP client sends a description request (QKnxNetIpDescriptionRequestProxy) 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) that contains the requested information.

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

Creating and Maintaining Communication Channels

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

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

The 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.

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) 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).

Sending Service Requests

Once the communication channel is established, the KNXnet/IP client can send tunneling requests (QKnxNetIpTunnelingRequestProxy) and device configuration requests (QKnxNetIpDeviceConfigurationRequestProxy) to the KNXnet/IP server. The server responds with a tunneling acknowledgment (QKnxNetIpTunnelingAcknowledgeProxy) or a device configuration acknowledgment (QKnxNetIpDeviceConfigurationRequestProxy), 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) 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 (created by using the QKnxNetIpHpaiProxy) 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.

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.

Routing

A routing indication is sent by a KNXnet/IP router or device to transmit KNX link layer frames over IP networks. The QKnxNetIpRoutingIndicationProxy 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 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 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

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

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

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

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

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

QKnxNetIpFrame

Represents the base for all KNXnet/IP related communication

QKnxNetIpFrameHeader

KNXnet/IP frame header

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

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

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

QKnxNetIpServerDescriptionAgent

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

QKnxNetIpServerDiscoveryAgent

Discovers KNXnet/IP servers by multicasting 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

QKnxServiceInfo

Contains the supported service and the corresponding service family version

QKnxNetIpCrd

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

QKnxNetIpCri

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

QKnxNetIpDib

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

QKnxNetIpHpai

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

QKnxNetIpStruct

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

QKnxNetIpStructHeader

KNXnet/IP structure header

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

QKnxNetIpTunnelingRequestProxy

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

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