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 (M_PropRead.req and M_PropRead.con)
  • Property write (M_PropWrite.req and M_PropWrite.con)
  • Property info indication service (M_PropInfo.ind)
  • Function property command (M_FuncPropCommand.req and M_FuncPropCommand.con)
  • Function property state read (M_FuncPropStateRead.req and M_FuncPropStateRead.con)
  • Reset and restart service (M_Reset.req)

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.

Reset Services

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

QKnxDeviceManagementFrame

Represents a cEMI frame dedicated to KNXnet/IP device management

QKnxDeviceManagementFrame::Builder

QKnxDeviceManagementFrame::Builder class provides the means to create valid device management service frames

QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder

QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder class provides the means to create valid device management function property command service frames

QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder

QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder class provides the means to create valid device management function property state read service

QKnxDeviceManagementFrame::PropertyInfoBuilder

QKnxDeviceManagementFrame::PropertyInfoBuilder class provides the means to create a valid device management property info indication frame

QKnxDeviceManagementFrame::PropertyReadBuilder

QKnxDeviceManagementFrame::PropertyReadBuilder class provides the means to create valid device management property read service frames

QKnxDeviceManagementFrame::PropertyWriteBuilder

QKnxDeviceManagementFrame::PropertyWriteBuilder class provides the means to create valid device management property write service frames

QKnxDeviceManagementFrame::ResetBuilder

QKnxDeviceManagementFrame::ResetBuilder class provides the means to build valid device management reset service frames

QKnxInterfaceObjectProperty

Holds the properties of a KNX interface object

QKnxInterfaceObjectPropertyDataType

Holds information about the data type of the properties of a KNX interface object

QKnxInterfaceObjectType

Holds the type of a KNX interface object

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

QKnxNetIpDeviceManagement

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

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