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 类：

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 类。

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 类。

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 类。

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 类。

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

内容

• KNXnet/IP Frames

• Discovering KNXnet/IP Servers

• Creating Extended Search Requests

• Creating and Maintaining Communication Channels

• Sending Service Requests

• KNXnet/IP Endpoints

• Routing

• List of KNXnet/IP Classes