API Reference

The self update agent (SUA) is a component responsible for the OS Update process SUA is communicating on MQTT interface via usage of defined messages. Internally, SUA uses RAUC to perform the update

Following sequence diagram shows the happy path example of communication between components.

Process Overview

sequenceDiagram participant m as MQTT Broker participant s as SUA participant r as RAUC s -->> m: connect loop Wait for OTA trigger Note left of s: Initial start s ->> m: Current state (installed version from booted partition) Note left of s: Trigger for OTA m ->> s: Desired state request (new version and url to bundle) s ->> m: Feedback (update actions are identified) Note left of s: Command for Download m ->> s: Download command s ->> s: Download bundle s ->> m: Feedback (downloading/downloaded/failed) Note left of s: Command for Update m ->> s: Update command s ->> r: Flash image to partition r ->> r: Flashing... s ->> m: Feedback (updating with percentage) r ->> s: Flash completed/failed s ->> m: Feedback (updated/failed) Note left of s: Command for Activate m ->> s: Activate command s ->> r: Switch partitions (booted <-> other) r ->> s: Switch completed/failed s ->> m: Feedback (activated/failed) Note left of s: Command for Cleanup m ->> s: Cleanup command s ->> s: Remove temporary files s ->> m: Cleanup completed + status from previously failed state
(completed/failed) end
stateDiagram Uninitialized --> Connected: Connected Connected --> Identified: Start (OTA trigger) Identified --> Downloading: Command download Identified --> Failed: If OTA trigger is invalid Downloading --> Updating: Command update Downloading --> Failed: If download has failed Updating --> Activate: Command activate Updating --> Failed: If update has failed Activate --> Cleanup: Command cleanup Activate --> Failed: If activate has failed Failed --> Cleanup: Command cleanup Cleanup --> Idle

Important: Uninitialized state is the default entry state or state in case connection is lost. To simplify reading of the diagram arrows from other states to Unitialized have been removed.

MQTT communication is done over 5 MQTT topics:

Trigger OTA

Topic Direction Description
selfupdate/desiredstate IN This message triggers the update process
The payload shall contain all data necessary to obtain the update bundle and to install it

Trigger self-update step/action

Topic Direction Description
selfupdate/desiredstate/command IN This message triggers the single step in update process (download/flash/activate/cleanup)

Report current state

Topic Direction Description
selfupdate/currentstate OUT This message is being sent either once on SUA start or as an answer to response received by selfupdate/currentstate/get
It contains information about the currently installed OS version

Get current state

Topic Direction Description
selfupdate/currentstate/get IN This message can be received at any point of time
Indicates that SUA should send back the version of the installed OS as current state.

Report status of self-update process

Topic Direction Description
selfupdate/desiredstatefeedback OUT This message is being sent by SUA to share the current progress of the triggered update process
This is the OUT counterpart of selfupdate/desiredstate input message

Checkout

SUA links to some 3rd party libraries, which are fetched as submodules, therefore the cloning shall be performed with recursive option:

git clone --recursive https://github.com/eclipse-leda/leda-contrib-self-update-agent.git

or if was cloned non recursively

git submodule init
git submodule update