Skip to main content
Version: v1.1

Update Flow Overview

Introduction​

This page documents the complete end-to-end update flow in AosCore — the sequence of operations that occurs when AosCloud sends a new desired state to a Unit. The flow covers both SOTA (software) and FOTA (firmware) deployments, showing how the Communication Manager (CM) orchestrates image downloads, configuration changes, service launches, and status reporting.

Understanding this flow is essential for OEMs who need to predict deployment timing, diagnose update failures, or integrate external Update Managers for firmware components.

Update Flow Sequence​

The following diagram shows the end-to-end update flow as a sequence across the participating components:

loading...

Flow Phases​

The update flow proceeds through six sequential phases, each corresponding to a state in the CM Update Manager's state machine. The state is persisted to storage on every transition, enabling crash recovery.

1. Trigger (Cloud → CM)​

The flow begins when AosCloud sends a desired-state message to the Unit over the WebSocket JSON connection. The desired state contains the complete target configuration:

FieldContent
NodesTarget state for each Node (provisioned or paused)
Unit configTarget configuration version
Deployable ItemsService images and firmware components with versions and OCI index digests
InstancesWhich services to run, how many, with priority and placement labels
CertificatesTLS certificates needed for image Verification

The CM Update Manager receives the desired state via ProcessDesiredStatus() and compares it against the current state. If differences are detected, an update cycle begins. If the desired state matches the current state, no action is taken.

If a new desired state arrives while an update is already in progress, the current update is cancelled and the new one begins — the Unit always converges toward the most recent target.

2. Downloading​

State: Downloading

The CM Update Manager instructs the Image Manager to download all required Deployable Item images that are not already present locally:

  1. The Image Manager resolves each item's OCI index digest to determine which layers need downloading
  2. Layers are downloaded from the URLs specified in the desired state
  3. Each downloaded layer is verified against its SHA-256 digest
  4. Successfully downloaded images are stored in the local image store

If any download fails (network error, integrity check failure, insufficient storage), the update transitions to an error state and the failure is reported to AosCloud.

3. Pending​

State: Pending

All required images have been downloaded and verified. The system is ready to proceed with the actual update. This state exists as a checkpoint — the Update Manager confirms all prerequisites are met before making changes to the running system.

4. Installing​

State: Installing

The CM applies configuration changes that must take effect before launching new service instances:

  • Node state changes — Nodes are transitioned to their target state (provisioned or paused)
  • Unit configuration — If the desired state includes a new Unit configuration version, it is applied through the Unit Config module

These changes prepare the environment for the new service instances.

5. Launching​

State: Launching

This is where the actual deployment happens. The behavior differs between SOTA and FOTA:

SOTA (Software Updates)​

The CM sends a RunInstances command to each Service Manager (SM) via gRPC. The command contains:

FieldPurpose
servicesService images to make available (ID, version, URL, SHA-256, size)
layersOCI layers required by the services
instancesSpecific instances to run (identity, UID, priority, storage paths, network config)
force_restartWhether to force-restart already-running instances

The SM receives this command and:

  1. Stops instances that are no longer in the desired set
  2. Downloads any service images or layers it doesn't have locally (using URLs from the command)
  3. Starts new instances with the specified configuration
  4. Reports per-instance status back to CM via RunInstancesStatus

FOTA (Firmware Updates)​

For firmware components, the CM communicates with registered external Update Managers (UMs) through the UMService gRPC protocol:

  1. CM sends PrepareUpdate with component information (ID, type, version, URL, SHA-256, size)
  2. The UM downloads and prepares the firmware image
  3. The UM reports UpdateStatus with state PREPARED
  4. CM sends StartUpdate to apply the firmware
  5. The UM applies the update (may require reboot)
  6. The UM reports UpdateStatus with state UPDATED

6. WaitingActive​

State: WaitingActive

After launching, the CM waits for all instances and components to reach their target state:

  • SOTA: The CM monitors RunInstancesStatus messages from each SM, waiting for all instances to report a running state
  • FOTA: The CM monitors UpdateStatus messages from each UM, waiting for all components to report INSTALLED state

This phase has a 10-minute timeout. If not all components reach their target state within this window, the update is considered failed.

7. Finalizing​

State: Finalizing

Once all instances and components are active:

  1. The installed Deployable Items are committed as the current set in the database
  2. The full Unit status (all nodes, services, instances, components) is assembled
  3. The UnitStatus message is sent to AosCloud over the WebSocket connection
  4. The update state resets to None (idle)

The Unit is now running the new desired state and is ready for the next update cycle.

Error Handling​

If any phase fails, the update flow handles the error as follows:

Failure PointBehavior
Download failureUpdate cancelled; error reported to cloud; system remains on previous state
Configuration failureUpdate cancelled; error reported to cloud
SM launch failureInstance error reported; CM waits for timeout then reports failure
UM prepare/start failureUM reports FAILED state with error; CM may send RevertUpdate
Timeout in WaitingActiveUpdate considered failed; error status reported to cloud

For FOTA updates, the CM can send a RevertUpdate command to the UM if StartUpdate fails, allowing the firmware to roll back to the previous version before ApplyUpdate commits it permanently.

Crash Recovery​

The CM Update Manager persists its state to the database on every state transition using the StorageItf interface:

  • StoreUpdateState() — saves the current state machine position
  • StoreDesiredStatus() — saves the desired status being processed

If the CM process crashes and restarts, it reads the persisted state and desired status from the database and resumes the update from the last completed phase. This prevents partial deployments from leaving the Unit in an inconsistent state.

Cancellation​

If a new desired state arrives while an update is in progress:

  1. The current update is marked for cancellation (mCancelCurrentUpdate)
  2. The update thread detects the cancellation flag at the next state transition
  3. The pending desired status is stored and becomes the new target
  4. A new update cycle begins from the Downloading phase with the latest desired state

This ensures the Unit always converges toward the most recently received desired state from AosCloud.

Update Scheduler API​

External systems can trigger and monitor updates through the UpdateSchedulerService gRPC API (proto version 3):

RPCPurpose
StartSOTAUpdateTriggers a software update cycle using the last received desired state
StartFOTAUpdateTriggers a firmware update cycle using the last received desired state
SubscribeNotificationsStreams real-time progress notifications with per-component status

Notifications include UpdateSOTAStatus and UpdateFOTAStatus messages with the current UpdateState (NO_UPDATE, DOWNLOADING, READY_TO_UPDATE, UPDATING) and details about affected services, layers, and components.

  • Deployment Flows — section overview with deployment architecture and SOTA vs FOTA comparison
  • SOTA vs FOTA — detailed comparison of software and firmware update mechanisms