Skip to main content
Version: 1.1.1

Restart Operation

thin-edge.io defines a restart operation to restart a device, being the main device or a child device.

  • A restart is typically triggered by a mapper on behalf of a cloud operator.
  • A restart can also be triggered from another operation (as a software update) or service (detecting for instance some anomalies requesting a reboot).
  • tedge-agent is the reference implementation of the restart operation.
  • However, a custom restart plugin implementation can be installed on a device with specific requirements.

MQTT API

The restart operation API follows the generic thin-edge.io rules for operations:

  • The te/<device-topic-id>/cmd/restart topic is used to tell the device <device-topic-id> can be restarted.
  • Each restart request is given a <command-id> and a dedicated topic te/<device-topic-id>/cmd/restart/<command-id>, where all the subsequent states of the restart command are published during its execution.
  • The workflow is generic with "init", "executing", "successful" and "failed" statuses.

restart registration

The registration message of the restart operation on a device is an empty JSON object {}.

tedge mqtt pub -r 'te/device/child001///cmd/restart' '{}'

init state

To trigger a restart operation on a device, the requester has no information to provide. It only has to create a new restart command instance topic.

tedge mqtt pub -r 'te/device/child001///cmd/restart/c8y-2023-09-08T18:13:00' '{
"status": "init"
}'

executing state

When ready, but before actually restarting the device, the agent or the restart plugin publishes the new state of the command.

tedge mqtt pub -r 'te/device/child001///cmd/restart/c8y-2023-09-08T18:13:00' '{
"status": "executing"
}'

successful state

After a successful reboot, the agent or the restart plugin publishes the new state of the command.

tedge mqtt pub -r 'te/device/child001///cmd/restart/c8y-2023-09-08T18:13:00' '{
"status": "successful"
}'

failed state

In case the reboot failed for some reason, the agent or the restart plugin publishes the new state of the command, adding a reason text field with the error.

tedge mqtt pub -r 'te/device/child001///cmd/restart/c8y-2023-09-08T18:13:00' '{
"status": "failed",
"reason": "The device has not restarted within 5 minutes"
}'

Command cleanup

As for all commands, the responsibility of closing a restart is on the requester. This is done by publishing an empty retained message on the command topic.

tedge mqtt pub -r 'te/device/child001///cmd/restart/c8y-2023-09-08T18:13:00' ''

Implementation Contract

The restart agent state must survive a device restart.

  • The executing state must be published before a reboot is scheduled.
  • The successful state is published after the reboot when the agent resumes an ongoing restart command.
  • The agent needs to differentiate between a simple process restart vs the actual device restart itself.
  • A simple process restart is considered as a failed restart.