Qt KNX Device Management Classes
A device management connection is established between a common external message interface (cEMI) client and a cEMI server to transmit cEMI frames. A cEMI frame specifies the service to use and determines whether the frame contains a request, confirmation, or indication related to the selected service.
The application layer provides several application services that the application processes in devices can use to interoperate over different communication modes. The services that are available depend on the communication mode.
The following diagram shows the main Qt KNX module classes that enable device management:
Creating Device Management Connections
The QKnxNetIpDeviceManagement class enables the opening and handling of a device management connection from a KNXnet/IP client to a KNXnet/IP server to access management functionalities on the server. The client uses the connection to send device configuration request frames to the server.
As an alternative, the QKnxNetIpDeviceConfigurationRequestProxy class can be used to read a device configuration request from the generic QKnxNetIpFrame class and to create a device configuration request. Similarly, the QKnxNetIpDeviceConfigurationAcknowledgeProxy class can be used to create a device configuration acknowledgment to confirm the reception of the request.
Accessing Device Management Services
The QKnxDeviceManagementFrame class represents a cEMI frame that can be transferred over an established device management connection. The QKnxDeviceManagementFrame::MessageCode within the frame determines the service to use and whether the frame carries a request (.req), indication (.ind), or confirmation (.con) related to the selected service.
The following services are available for local device management:
- Property read (
- Property write (
- Property info indication service (
- Function property command (
- Function property state read (
- Reset and restart service (
Local device management services are confirmed services, which means that a read or write request frame sent by a cEMI client must be followed by a read or write confirmation frame sent by a cEMI server. The confirmation indicates whether the request was successful.
Application layer services are invoked by the transport layer frames. The same frames are used by the remote device to respond to a remote confirmed service.
The QKnxDeviceManagementFrame::Builder class can be used to construct local device management cEMI frames. The following more specialized versions of the builder are also provided, and it is recommended to prefer them over the generic version:
Property Read and Write Services
A property read or write request is used by the management client to read or write the value of a property of an interface object in the management server. The interface object is identified by an object type (QKnxInterfaceObjectType) and object instance number.
An interface object property (QKnxInterfaceObjectProperty) can be structured as an array of elements. It is addressed by a property ID, the number of elements in the array to read, and a start index, which indicates the position of the first element that the management client wants to read.
A property read or write confirmation contains the requested number of elements starting from the specified position within the property of the interface object.
If the interface object or property does not exist, or some other error occurs, the number of elements to read is set to zero and the start index of the response is set to the value received with the request.
The data field of a negative response contains information about the error as a QKnx::NetIp::CemiServer::Error value.
Function Property Services
A function property command request is used by the management client to call a property function of an interface object in the management server. The management server confirms the request with a confirmation message that contains a return code as a QKnx::NetIp::CemiServer::ReturnCode value and additional data.
A function property state read request is used by the management client to read the status of a property function. The management server confirms the request with a confirmation message that contains a return code and additional data.
If the interface object property accessed by a function property command request or state read request is not of the property datatype
PDT_Function, the confirmation message contains neither a return code field nor data.
Property Information Services
A property information indication is used by the management server to notify the client about an event, such as a changed management property value. If the data that the indication contains is relevant to the management procedures supported by the client, the client calls those procedures with the received data. If the data is not relevant, the client ignores the message.
A reset request is used by the management client to reset the management server device. The server device executes the same actions as when it is started up. When the server receives a reset request, the server software is reinitialized. Therefore, the communication on bus and cEMI side is aborted and both communication stacks are reset.
The management server sends a reset indication to the management client when the server device is reset or started up.
List of Device Management Classes
Represents a cEMI frame dedicated to KNXnet/IP device management
QKnxDeviceManagementFrame::Builder class provides the means to create valid device management service frames
QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder class provides the means to create valid device management function property command service frames
QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder class provides the means to create valid device management function property state read service
QKnxDeviceManagementFrame::PropertyInfoBuilder class provides the means to create a valid device management property info indication frame
QKnxDeviceManagementFrame::PropertyReadBuilder class provides the means to create valid device management property read service frames
QKnxDeviceManagementFrame::PropertyWriteBuilder class provides the means to create valid device management property write service frames
QKnxDeviceManagementFrame::ResetBuilder class provides the means to build valid device management reset service frames
Holds the properties of a KNX interface object
Holds information about the data type of the properties of a KNX interface object
Holds the type of a KNX interface object
The means to read a device configuration acknowledgment from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information
The means to read a device configuration request from the generic QKnxNetIpFrame class and to create a KNXnet/IP frame based on the information
Enables the opening and handling of a device management connection from a KNXnet/IP client to a KNXnet/IP server
© 2023 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.