Control Unit Metadata is the way the Control Unit's interface is presented to the RM and is mandatory in order to work in any way with a Control Unit (device or component).

The MQTT Device Adapter Package provides several methods for sending Metadata to the RM – via a REST call by sending a message via MQTT (this method is used primarily for sending components' Metadata, because it requires an established connection between a device and the RM, i.e. the device must have already provided its Metadata by another method) and by providing the Metadata in the initial configuration folder.

The concept of "Metadata" is also related to Control Units' icons so this section also contains instructions on how to provide icons for a specific Control Unit or its actions to the RM.+

REST

Metadata

Request URL: http://<rm ip>:<rm port>/rspi/mqtt/{deviceType}/metadata/{cuType}/{version}?isAbstract={boolean}&isDeviceType={boolean}

Request method: POST

Request headers:

• "Accept: application/json"

• "Content-Type: application/xml"

• "Authorization: Basic <credentials>"

Request payload: <metadata xml content>

Icon

Request URL: http://<rm ip>:<rm port>/rspi/mqtt/{deviceType}/{deviceId}/metadata/{cuType}/{version}/icons/{ocdId}/{size}

Request method: POST

Request headers:

• "Accept: application/json"

• "Content-Type: application/octet-stream"

• "Authorization: Basic <credentials>"

Request payload: <icon as byte[]>

• {ocdId} stands for "object class definition id" – for detailed explanation see the Control Unit Metatyping page.

• {size} is the size of the icon in pixels

MQTT

Metadata

Request

Topic

Payload

• "token" - this field is mandatory and is part of the security concept for the messaging protocol. For more information check the Security section in the MQTT Device Management Model page.

• "requestId" and "needAck" - these fields are required if:

  • message delivery acknowledgment is required;

  • confirmation of successful request is required (success is defined as an absence of error);

  • data is expected as a result of the request;

    Note that if the fields are omitted no response of any kind will be sent by the backend and if an error has occurred the device won't be notified of it.

• "metadata" - this field is mandatory and must contain the Metadata xml

• "isAbstract" - this field is mandatory and must be set to true if the Control Unit type is abstract

• "isDeviceType" - this field is mandatory and must be set to true if the Control Unit is a device

Response

Topic

Payload

• "requestId" - this field will be included only if it was present in the request message and its value will match the value sent with the request.

• "error" - this field will be included only if an error occurred during the fulfilling of the request. Note that if the field is present, the payload will not contain any other fields, except for "requestId".

Icon

Request

Topic

• <ocd Id> stands for "object class definition id" – for detailed explanation see the Control Unit Metatyping page.

• <size> is the size of the icon in pixels

Payload

• "token" – this field is mandatory and is part of the security concept for the messaging protocol. For more information check the Security section in the MQTT Device Management Model page.

• "requestId" and "needAck" – these fields are required if:

  • message delivery acknowledgment is required;

  • confirmation of successful request is required (success is defined as an absence of error);

  • data is expected as a result of the request;

    Note that if the fields are omitted no response of any kind will be sent by the backend and if an error has occurred the device won't be notified of it.

• icon - this field is mandatory and must contain image file bytes

Response

Topic

Payload

• "requestId" – this field will be included only if it was present in the request message and its value will match the value sent with the request.

• "error" – this field will be included only if an error occurred during the fulfilling of the request. Note that if the field is present, the payload will not contain any other fields, except for "requestId".

Initial Configuration

This method for providing Metadata is only available for on-premise deployment.

In order to load required Metadata on RM startup, the following steps must to be completed:

• First, a configuration xml, containing information about the actual Control Unit Metadata, should be created and placed in the initial_config/mqttcu folder.

Examples

• Second, the Control Unit Metadata xml must be placed in the folder, defined in the <metadata-location> element (usually initial_config/mqttcu/mqttdm/cu-mtp).

Example for Metadata

Generic REST call -/rspi/mqtt/{deviceType}/metadata/{cuType}/{version}?isAbstract={boolean}&isDeviceType={boolean}

The {cuType} field should be the same as the <id> field in the Metadata.

Example REST call for the Metadata below:

Since we are importing Metadata for a device the {deviceType} and {cuType} fields should be the same and the isDeviceType should be true.

Metadata: