Communicate software update statuses from a device to Bosch IoT Device Management
We assume that you already know how to Deploy a software update on your devices.
After a software update has been downloaded or installed successfully on the device, it needs to communicate this with the cloud service, so that the twin state can be updated accordingly. This means that the device has to send feedback to Bosch IoT Device Management, communicating that a particular step in the process has indeed completed. The final intention of this procedure is to update the status of the target in Bosch IoT Rollouts i.e. the software update layer of Bosch IoT Device Management from "PENDING" to "IN_SYNC".
In this page we will describe the expected flow of messages between Bosch IoT Device Management and the device after the distribution set has been assigned.
Note that the following procedure, message structure and paths apply only when using the SoftwareUpdatable 2.0.0 Vorto model and will not work as expected with SoftwareUpdatable version 1.0.0.
In addition, you may want to understand the whole software update flow described at Monitor software updates via mass management rules.
The following diagram illustrates an example of the expected communication procedure that we will explain in details below:
Once the distribution has been assigned, Bosch IoT Device Management sends the install command to the device containing the command's correlationId, which you have to use at a later stage.
See the example command format at step 1 in the diagram above. In it, forced and weight are defined during the creation of the assignment. Forced could be either true or false, while the value of weight would be a value, set by the user, or null if no value is provided.
The install command is sent to the command///req/<req-id>/<subject> topic.The device then sends a response confirming that the command has been received successfully. The command response, in this case, needs only a status code and no value, as it is declared void. For more information see SoftwareUpdatable 2.0.0 model.
When the command was received on the command///req/<req-id>/<subject> topic, then the response should be sent to command///res/<req-id>/<status_code> with the following payload format:{"topic":"<your-namespace>/<your-device-name>/things/live/messages/<subject>","headers": {"content-type":"application/json","correlation-id": <req-id>},"path":"/features/<feature.id>/inbox/messages/<subject>","status": <status_code>}You should use the <req-id> from the topic as the value of "correlation-id".
The device then starts to send telemetry messages to reflect the install command progress and its status. Here are some specifics and clarifications about the payload:
In order to display the update progress accordingly in Bosch IoT Rollouts, the features/<feature.id>/properties/status/lastOperation property on the thing's SoftwareUpdatable feature needs to be updated.
For more information look up the lastOperation description in the SoftwareUpdatable feature detailed specification and integration guide.
It is recommended to use intermediate statuses as they improve the traceability of the update process on the device. In our diagram's step 3 the device is communicating that the artifact has been successfully "DOWNLOADED" but the status could be any other. That way if a problem occurs it would be easier to understand where the process is lagging or even stuck.Find more information and all available statuses at Status transitions.
In addition, the value of message will be visible in the action history in the Bosch IoT Rollouts UI. This is why it is always recommended to write a sufficient and understandable message, like in our example "Download of Update:1.0 finished successfully".
See the payload format:{"topic":"<your-namespace>/<your-device-name>/things/twin/commands/modify","headers": {"content-type":"application/json"},"path":"/features/<feature.id>/properties/status/lastOperation","value": {"correlationId": <correlationId>,"softwareModule": {"name":"Update","version":"1.0"},"status": <status>,"message": <message>,"progress":100,"statusCode": <status_code>}}Note that correlationId is different than correlation-id from the previous command.
Here for correlationId, please use the one provided in the initial install command.Once the update has been successfully installed on the device, it should send a telemetry message where the status value is "FINISHED_SUCCESS". This will update the feature, change the status of the target in Bosch IoT Rollouts to "IN_SYNC" and thus complete the whole software update process successfully.
The format of the telemetry message is the same as the previous with only the status and message reflecting on the successful finish of the installation.