This section details the main part of the MQTT Device Adapter messaging protocol - the data transfer functionality. Three general methods are defined - "set data", "get data" and "delete data", and also several helper methods with trimmed down payload for more specific requests.

Data could be sent for a device, for its components, for a single component or even for a small entity like a single state variable. The same applies for data transfer from the backend to a device. For every operation a session-based data transfer model could be implemented.

Set Data

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.

• "sessionId" - this field is optional and is used for session-based communication - for more information see Session Management.

• "resetOldCUData" - this field is optional and can be used for deleting all existing Control Units (in the scope of the device) and their data.

• "closeSession" - this field is optional and is also related to the concept of session-based data transfer - for more information see Session Management.

• "cuEvents" - this field is mandatory and must contain an array of objects with the following fields:

  • "cu" - this field is mandatory and must contain an object with the following fields:

    • "cuType" - this field is mandatory

    • "cuId" - this field is mandatory

  • "parents" - this field is mandatory only for sub-components. In the context of the RM, only sub-components, i.e. components of components, can have parents, which are explicitly declared in the Control Unit's Metadata xml (see Metadata). The field, if required, must contain an array of the same objects as the "cu" field, containing each parent's information.

  • "event" - this field is mandatory and must be one of the following: "CU_ADDED", "CU_REMOVED", "STATE_VARIABLE_CHANGED", "HIERARCHY_ATTACHED", "HIERARCHY_DETACHED".

  • "state" - this field is mandatory only for "CU_ADDED" and "STATE_VARIABLE_CHANGED" events and must contain a map, where each state variable id is a key, and the corresponding value should be an object with the following fields:

    • "value" - this field is mandatory and must contain the actual value of the state variable

    • "timeStamp" - this field is mandatory and must contain the time of the last change

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".

Set State

This is a helper method for sending specific Control Unit state, i.e. sending only its state variables. It provides the same functionality as a Set Data request with "STATE_VARIABLE_CHANGED" event, but with trimmed down payload and only for one Control Unit per message.

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.

• "sessionId" - this field is optional and is used for session-based communication - for more information see Session Management.

• "resetOldCUData" - this field is optional and can be used for deleting all existing Control Units (in the scope of the device) and their data.

• "closeSession" - this field is optional and is also related to the concept of session-based data transfer - for more information see Session Management.

• "cuEvents" - this field is mandatory and must contain an array of one object with the following field:

  • "state" - this field is mandatory and must contain a map, where each state variable id is a key, and the corresponding value should be an object with the following fields:

    • "value" - this field is mandatory and must contain the actual value of the state variable

    • "timeStamp" - this field is mandatory and must contain the time of the last change

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".

Set State Variable

This is a helper method for sending specific Control Unit state variable. It provides the same functionality as a Set Data request with "STATE_VARIABLE_CHANGED" event, but with trimmed down payload and only for one Control Unit and one state variable per message.

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.

• "sessionId" - this field is optional and is used for session-based communication - for more information see Session Management.

• "closeSession" - this field is optional and is also related to the concept of session-based data transfer - for more information see Session Management.

• "value" - this field is mandatory and must contain an object with the following fields:

  • "value" - this field is mandatory and must contain the actual value of the state variable

  • "timeStamp" - this field is mandatory and must contain the time of the last change

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".

Get Data

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.

• "types" - this field is optional and it can contain the types of the Control Units, whose data is required. If omitted, data for every Control Unit in the scope of the device, including the device itself, will be returned.

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".

• "cuData" - this field will always be included and it will contain an array of objects with the following fields:

  • "cu" - this field will always be included and will contain an object with the following fields:

    • "cuType" - this field will always be included

    • "cuId" - this field will always be included

  • "stateVars" - this field will always be included and will contain a map, where every state variable id of the Control Unit will be a key, and the value of the corresponding state variable will be the value.

Get State

This is a helper method for receiving specific Control Unit state, i.e. receiving only its state variables. It provides the same functionality as a Get Data request with the specific Control Unit type in the "types" field, but with trimmed down payload and only for one Control Unit per message.

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.

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".

• "cuData" - this field will always be included and it will contain an array of a single object with the following fields:

  • "cu" - this field will always be included and will contain an object with the following fields:

    • "cuType" - this field will always be included

    • "cuId" - this field will always be included

  • "stateVars" - this field will always be included and will contain a map, where every state variable id of the Control Unit will be a key, and the value of the corresponding state variable will be the value.

Get State Variable

This is a helper method for receiving specific Control Unit state variable. It provides the same functionality as a Get Data request with the specific Control Unit type in the "types" field, but with trimmed down payload and only for one Control Unit and one state variable per message.

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.

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".

• "value" - this field will always be included and will contain an object with the following fields:

  • "value" - this field will always be included and will contain the actual value of the state variable

  • "timeStamp" - this field will always be included and will contain the time of the last change

Delete Data

This is a helper method for deleting specific component Control Unit. It provides the same functionality as a Set Data request with "CU_REMOVED" event, but with trimmed down payload and only for one Control Unit per message.

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.

• "sessionId" - this field is optional and is used for session-based communication - for more information see Session Management.

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".