Skip to main content

Unit status handler

The unit status handler (unitstatushandler) performs two main functions:

  • Collecting and sending the unit status to AosCloud.
  • Managing the SOTA/FOTA update.
  • Trigger run service instances

unitstatushandler consists of the following main instances:

  • The unit status handler — collects, forms, and sends unit status messages.
  • The software manager — performs the SOTA update (updating services and layers).
  • The firmware manager — performs the FOTA update (updating system components and the board configuration).

Sending unit status​

The unit status incapsulates statuses of all system items: services, layers, and components. The communication Manager (CM) sends the whole status with a special unit status message.

After a successful connection to AosCloud, CM immediately sends the current unit status message. The unit status handler gets the current status from the software and firmware managers, forms the unit status message and sends it to AosCloud. In runtime item statuses may change frequently. To use internet traffic less intensively, the unit status handler stores all item status changes, aggregates them into one unit status message and sends it to AosCloud not more often than a specified period of time (30 seconds by default). This period can be configured in the CM configuration file.

Updating the state from the cloud​

SM contollerSM contollerSoftware managerSoftware managerFirmware managerFirmware managerUnit status handlerUnit status handlerCloudCloudConnectionGet board config status.board config statusGet components status.components statusGet services statusservices statusGet layers status.layers statusinstances statusUnit Status messageService status changedStart unit status timerService status changedLayer status changedUnit status timeoutUnit Status message

SOTA/FOTA update procedure​

The SOTA/FOTA update procedure is as follows:

  • AosCloud indicates which services, layers, and their versions, count of service instances to be run together with component versions are to be installed on the target unit with a desired status message.
  • CM defines which services and layers are to be installed, removed, or updated, run instances, as well as which components are to be updated by comparing the current unit status to the received desired status message. Installing, removing, and updating services and layers is related to the SOTA update, whereas updating components and the board configuration is related to the FOTA update. Depending on unit usage and customer requirements, the SOTA/FOTA update can be performed immediately, by a schedule, or per request. Along with the desired SOTA/FOTA items, the desired status message contains also SOTA/FOTA update type:
    • force — SOTA/FOTA updates apples immediately after receiving the desired status.
    • timetable — SOTA/FOTA update should be performed in allowed by the timetable time slots, the timetable is sent in the desired status as well.
    • trigger — unit waits for a trigger (special notification) from a third-party service to start the update procedure.
  • SOTA update is handled by softwareManager (SOTA manager) instance and FOTA update is handled by firmwareManager (FOTA manager) which are parts of unitstatushandler module.
  • SOTA manager directs SM to update services and layers through smcontroller.
  • FOTA manager sends components update to UM using uncontroller.
  • SOTA/FOTA managers utilize downloader to download update artifacts.
  • Unit status handler sends the unit status message and receives the desired status message through amqphandler.
  • cmserver implements a gRPC server, which provides an API for external services to receive current the SOTA/FOTA update status and to trigger the SOTA/FOTA update.
loading...

From the implementation point of view, softwareManager and firmwareManager have similar designs. They implement the following state machine:

SOTA/FOTA manager states:

  • No update — no update is in progress.
  • Downloading — the manager is downloading update image.
  • Ready to update — update is successfully downloaded and ready to be applied.
  • Updating — the manager is applying the current update.

SOTA/FOTA manager events:

  • Start download — is generated when a new desired status message is received and SOTA/FOTA update in No update state or when there is the pending SOTA/FOTA update. The pending SOTA/FOTA update is created from a new desired status message which is received when another SOTA/FOTA update is in progress. The new update should be different from the current update. If the same desired status is received during another update, it is ignored.
  • Finish download — is generated when all requested update artifacts are successfully downloaded otherwise Cancel event with occurred error is generated.
  • Cancel — is generated to cancel the current update in case another different from the currently processed desired status is received. The new update is stored as pending and starts to be processed once the manager switches to No update state.
  • Start update — is generated based on the update type: immediately for force update, when the trigger command is received by cmserver for trigger update, and when the current time is within available time slot from the timetable for timetable update.
  • Finish update — is generated when all items are updated successfully otherwise Cancel event with occurred error is generated.

The unit status handler sends the current SOTA/FOTA update status to external services using CM gRPC server (cmserver). The update status is used to notify the external service about SOTA/FOTA update progress, update errors, and the right time to trigger the update. The triggered update can be triggered only in Ready to update state else the external service will get the appropriate error.