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:

• QKnxNetIpConfigDibProxy or QKnxNetIpConfigDibProxy::Builder for reading the IP configuration of a KNXnet/IP device
• QKnxNetIpCurrentConfigDibProxy or QKnxNetIpCurrentConfigDibProxy::Builder for reading the current IP configuration of a KNXnet/IP device
• QKnxNetIpKnxAddressesDibProxy or QKnxNetIpKnxAddressesDibProxy::Builder for reading all assigned individual addresses of a KNXnet/IP device
• QKnxNetIpManufacturerDibProxy or QKnxNetIpManufacturerDibProxy::Builder for reading manufacturer specific device information
• QKnxNetIpServiceFamiliesDibProxy or QKnxNetIpServiceFamiliesDibProxy::Builder for reading the service families and versions supported by a KNXnet/IP device

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