Update Manager

Introduction

The Update Manager is a core library module running within the Communication Manager (CM) process. It is responsible for processing desired-state messages received from AosCloud, determining what changes are needed, and orchestrating the update workflow to converge the Unit toward its target state.

This page documents the Update Manager's architecture, its internal state machine, and how it coordinates with other CM modules to execute software (SOTA) and firmware (FOTA) updates.

Architecture

The Update Manager (aos::cm::updatemanager::UpdateManager) is composed of two internal handlers:

Handler	Responsibility
DesiredStatusHandler	Processes incoming desired-state deltas, drives the update state machine, coordinates image downloads and instance launches
UnitStatusHandler	Aggregates current Unit status from all sources (Nodes, instances, Deployable Items) and reports it back to AosCloud

Dependencies

The Update Manager integrates with several other CM modules:

Interface	Purpose
ImageManagerItf	Downloads and installs Deployable Item images (OCI layers, firmware components)
LauncherItf	Starts and stops service instances across Nodes
NodeHandlerItf	Pauses and resumes Nodes as directed by the desired state
UnitConfigItf	Applies Unit-level configuration changes
CloudConnectionItf	Monitors cloud connection state for status reporting
SenderItf	Sends aggregated Unit status messages to AosCloud
StorageItf	Persists update state and desired status for crash recovery
NodeInfoProviderItf	Tracks registered Nodes and their capabilities
IdentProviderItf	Provides identity and subject information for status reporting

Desired State Processing

When AosCloud sends a desired-state message, it contains the complete target state for the Unit:

• Node states — which Nodes should be active (provisioned) or paused
• Unit configuration — target configuration version
• Deployable Items — service images and firmware components with their versions and OCI index digests
• Instances — which services to run, how many instances, on which subjects, and with what priority
• Subjects — identity information for service instances
• Certificates — TLS certificates and chains needed for image Verification

The Update Manager compares this desired state against the current state and determines whether an update is required. An update is triggered if any of the following differ from the current state:

1. Node states need to change (pause or resume)
2. Unit configuration version differs
3. Deployable Item versions differ from what is currently installed
4. Instance configuration differs from what is currently running

If the desired state matches the current state, no action is taken.

Update State Machine

The DesiredStatusHandler drives updates through a sequential state machine:

┌──────────────┐
│     None     │ ← idle, no update in progress
└──────┬───────┘
       │ new desired state received
       ▼
┌──────────────┐
│ Downloading  │ ← downloading Deployable Item images via ImageManager
└──────┬───────┘
       │ downloads complete
       ▼
┌──────────────┐
│   Pending    │ ← ready to proceed with installation
└──────┬───────┘
       │ (immediate transition)
       ▼
┌──────────────┐
│  Installing  │ ← applying Node states and Unit configuration
└──────┬───────┘
       │ installation complete
       ▼
┌──────────────┐
│  Launching   │ ← starting service instances via Launcher
└──────┬───────┘
       │ instances launched
       ▼
┌──────────────┐
│WaitingActive │ ← waiting for all instances to reach Active state
└──────┬───────┘
       │ all instances active (or timeout after 10 minutes)
       ▼
┌──────────────┐
│  Finalizing  │ ← committing Deployable Items as installed via ImageManager
└──────┬───────┘
       │ finalization complete
       ▼
┌──────────────┐
│     None     │ ← update complete, full Unit status sent to cloud
└──────────────┘

State Descriptions

None — No update is in progress. The handler waits for a new desired-state message.

Downloading — The Image Manager downloads all required Deployable Item images (OCI manifests, layers, firmware blobs). Downloads include integrity Verification using certificates provided in the desired-state message.

Pending — Downloads are complete and the system is ready to proceed. This state transitions immediately to Installing.

Installing — The handler applies Node state changes (pause/resume) and Unit configuration updates. Node state changes are sent to the IAM Node Handler. Unit configuration is validated and applied through the Unit Config module.

Launching — The Launcher receives run-instance requests for all desired service instances. Each request includes the Deployable Item ID, version, subject, priority, number of instances, and placement labels.

WaitingActive — The handler polls instance statuses and waits for all launched instances to transition from activating to active. A 10-minute timeout prevents indefinite blocking.

Finalizing — The Image Manager commits the downloaded Deployable Items as the installed set. This marks the update as successfully applied.

Error Handling

If any state action fails, the state machine resets to None and a full Unit status (including error information) is sent to AosCloud. The cloud can then decide whether to retry or take corrective action.

Cancellation

If a new desired-state message arrives while an update is in progress, the current update is cancelled:

1. If in Downloading or Installing state, the Image Manager's cancel operation is invoked
2. The state machine resets to Downloading with the new desired state
3. The previous update is abandoned and the new one begins

This ensures the Unit always converges toward the most recent desired state from the cloud.

Crash Recovery

The Update Manager persists its state to survive process restarts:

• The current UpdateState is stored via the StorageItf on every state transition
• The full DesiredStatus is stored when a new update begins

On startup, the DesiredStatusHandler checks for a persisted update state. If one exists (not None), it resumes the update from the stored state with the stored desired status. This prevents partial updates from leaving the Unit in an inconsistent state.

Unit Status Reporting

The UnitStatusHandler aggregates status from multiple sources and sends it to AosCloud:

Source	Information
Node Info Provider	Node IDs, capabilities, connection status
Image Manager	Deployable Item statuses (installed versions, download progress)
Instance Status Provider	Running instance states and errors
IAM Identity Provider	Subject information
Unit Config	Current configuration version and status

Status is sent:

• On connect — full Unit status is sent when the cloud connection is established
• On change — incremental updates when Node info, item statuses, instance statuses, or subjects change
• Periodically — a configurable timeout (mUnitStatusSendTimeout) triggers periodic full status sends
• After update completion — a full status is sent when the update state machine returns to None

Update Scheduler Interface

CM exposes the UpdateSchedulerService gRPC API (defined in communicationmanager/v3/updatescheduler.proto) for external systems to trigger and monitor updates:

RPC	Purpose
StartFOTAUpdate	Triggers a firmware update cycle
StartSOTAUpdate	Triggers a software update cycle
SubscribeNotifications	Streams real-time update progress notifications

Notification Messages

The SubscribeNotifications stream delivers SchedulerNotifications containing either:

• UpdateSOTAStatus — software update progress including:

  • Current UpdateState (NO_UPDATE, DOWNLOADING, READY_TO_UPDATE, UPDATING)
  • Unit configuration version being applied
  • Services being installed or removed (ID and version)
  • Layers being installed or removed (ID, digest, version)
  • Whether a rebalance is requested
  • Error information if the update failed

• UpdateFOTAStatus — firmware update progress including:

  • Current UpdateState
  • Components being updated (ID, type, version)
  • Error information if the update failed

SOTA vs FOTA

The Update Manager handles both update types through the same state machine, but they differ in what is being updated:

Aspect	SOTA (Software)	FOTA (Firmware)
Target	Service images and layers	System components (firmware, bootloader)
Deployable Items	OCI container images	Firmware blobs
Instance impact	Services are relaunched with new versions	Node may require reboot
Scope	Individual services on specific Nodes	System-level components

Both types flow through the same Downloading → Pending → Installing → Launching → WaitingActive → Finalizing sequence. The Image Manager handles the type-specific download and installation logic.

Related Pages

• Communication Manager — parent overview of CM architecture and all subcomponents
• Architecture Overview — high-level view of all AosCore components
• Cloud Communication — how desired-state messages arrive from AosCloud

• SM Controller — how CM distributes deployment commands to SM instances

• Unit Configuration — Unit-level configuration handling referenced during Installing state

• Key Concepts — terminology definitions for Unit, Node, Deployable Item, Deployment Bundle, Verification
• Unit and Node Model — how Units and Nodes relate