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:

• QKnxDeviceManagementFrame::PropertyReadBuilder
• QKnxDeviceManagementFrame::PropertyWriteBuilder
• QKnxDeviceManagementFrame::PropertyInfoBuilder
• QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder
• QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder
• QKnxDeviceManagementFrame::ResetBuilder

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