Update Handler State Machine

Introduction

This page documents the state machine of the FOTA Update Manager (UM) — the external process responsible for applying firmware updates to system-level components such as rootfs, bootloader, or hardware-specific firmware. Each UM registers with the Communication Manager (CM) over gRPC and receives commands that drive it through a well-defined set of states. Understanding this state machine is essential for OEMs implementing custom Update Managers for their hardware platforms.

The UM state machine is defined in the updatemanager/v2 protocol and consists of four states driven by four CM commands. The protocol uses bidirectional gRPC streaming: the UM reports its current state, and CM sends commands to advance the update.

State Machine Diagram

loading...

States

The Update Manager reports its current state to CM via the UpdateStatus message. The UpdateState enum defines four possible states:

State	Value	Description
IDLE	0	No update in progress. The UM is registered and waiting for commands from CM. This is the initial state after registration and the terminal state after a successful update or recovery.
PREPARED	1	The UM has successfully downloaded and verified all component images specified in the PrepareUpdate command. The firmware is staged and ready to be applied.
UPDATED	2	The firmware update has been applied but not yet committed permanently. The system is running the new firmware and can still be reverted to the previous version.
FAILED	3	The update operation failed. The UM reports an error describing what went wrong. CM may send RevertUpdate to recover.

CM Commands

CM drives the UM through its state machine by sending commands via the CMMessages stream. Each command triggers a state transition:

PrepareUpdate

Instructs the UM to download and prepare firmware component images for installation.

Field	Type	Description
components	repeated PrepareComponentInfo	List of components to prepare

Each PrepareComponentInfo contains:

Field	Type	Description
component_id	string	Unique identifier for the component
component_type	string	Type of component (e.g., "rootfs", "bootloader")
version	string	Target version to install
annotations	string	Additional metadata for the UM
url	string	Download URL for the component image
sha256	bytes	SHA-256 digest for integrity Verification
size	uint64	Expected size in bytes

Expected behavior: The UM downloads each component image from the provided URL, verifies its SHA-256 digest and size, and stages it for installation. On success, the UM transitions to PREPARED. On failure, it transitions to FAILED with an error description.

StartUpdate

Instructs the UM to apply the prepared firmware images to the target components.

Expected behavior: The UM writes the staged firmware to the appropriate storage (flash partition, disk image, etc.). This operation may require a system reboot. On success, the UM transitions to UPDATED. On failure, it transitions to FAILED.

The system must remain revertible after StartUpdate — the previous firmware version is preserved so that RevertUpdate can restore it if needed.

ApplyUpdate

Instructs the UM to commit the update permanently. After this command, rollback to the previous version is no longer possible.

Expected behavior: The UM marks the new firmware as the permanent active version (e.g., updates the boot partition flag, removes the previous image). The UM transitions back to IDLE, ready for the next update cycle.

RevertUpdate

Instructs the UM to roll back to the previous firmware version. This command can be sent when:

• StartUpdate failed and the UM is in FAILED state
• The system needs to recover from a partially applied update
• CM determines the update should be abandoned (e.g., new desired state received)

Expected behavior: The UM restores the previous firmware version (e.g., switches back to the previous boot partition). The UM transitions back to IDLE.

State Transitions

The complete set of valid state transitions:

From State	Trigger	To State	Description
(initial)	UM registers via RegisterUM	IDLE	UM connects and begins streaming status
IDLE	CM sends PrepareUpdate (success)	PREPARED	Components downloaded and verified
IDLE	CM sends PrepareUpdate (failure)	FAILED	Download or Verification error
PREPARED	CM sends StartUpdate (success)	UPDATED	Firmware applied, revertible
PREPARED	CM sends StartUpdate (failure)	FAILED	Apply operation failed
UPDATED	CM sends ApplyUpdate	IDLE	Update committed permanently
UPDATED	CM sends RevertUpdate	IDLE	Rolled back to previous version
FAILED	CM sends RevertUpdate	IDLE	Recovered from failure

Registration Protocol

The UM registers with CM using the UMService.RegisterUM RPC — a bidirectional streaming call:

service UMService {
    rpc RegisterUM(stream UpdateStatus) returns (stream CMMessages) {}
}

• UM → CM stream (UpdateStatus): The UM continuously reports its current state, including the Node ID, priority, overall UpdateState, per-component status, and any error information.
• CM → UM stream (CMMessages): CM sends commands (PrepareUpdate, StartUpdate, ApplyUpdate, RevertUpdate) to drive the state machine.

UpdateStatus Message

The UM sends UpdateStatus messages whenever its state changes:

Field	Type	Description
node_id	string	Identifier of the Node this UM manages
priority	uint32	Update priority (used by CM to order multi-UM updates)
update_state	UpdateState	Current state (IDLE, PREPARED, UPDATED, FAILED)
components	repeated ComponentStatus	Per-component state details
error	ErrorInfo	Error information (populated in FAILED state)

Per-Component Status

Each component reports its individual state via ComponentStatus:

Component State	Value	Description
INSTALLED	0	Component is at the target version
INSTALLING	1	Component update is in progress
ERROR	2	Component update failed

Multi-UM Coordination

A Unit may have multiple Update Managers registered — for example, one for rootfs updates and another for MCU firmware. CM coordinates them using the priority field in UpdateStatus:

1. CM sends PrepareUpdate to all UMs that have components in the desired state
2. CM waits for all UMs to reach PREPARED state
3. CM sends StartUpdate to UMs in priority order (lower priority value = higher precedence)
4. CM waits for each UM to reach UPDATED before proceeding to the next
5. Once all UMs report UPDATED, CM sends ApplyUpdate to commit all updates

If any UM reports FAILED, CM sends RevertUpdate to all UMs that have already applied their updates, ensuring the system returns to a consistent state.

Reboot Handling

Firmware updates often require a system reboot. The UM protocol handles this transparently:

1. The UM applies the firmware and initiates a reboot
2. After reboot, the UM process restarts and re-registers with CM via RegisterUM
3. The UM reports its current state — if the firmware was applied successfully, it reports UPDATED
4. CM recognizes the UM has completed its StartUpdate and proceeds with the flow

The UM is responsible for persisting enough state to know whether it was in the middle of an update when the reboot occurred. CM identifies the UM by its node_id in the UpdateStatus message.

Error Handling

When an error occurs during any phase, the UM:

1. Transitions to FAILED state
2. Populates the error field in UpdateStatus with an ErrorInfo message containing:
   • Error code
   • Human-readable error message
3. Reports per-component status showing which components succeeded and which failed

CM responds to a FAILED state by:

1. Logging the error for diagnostic purposes
2. Sending RevertUpdate to recover the UM to a known-good state
3. Reporting the failure to AosCloud as part of the Unit status

Implementation Notes for OEMs

When implementing a custom Update Manager for your hardware platform:

Concern	Guidance
Registration	Connect to CM's gRPC endpoint and call RegisterUM. Begin streaming UpdateStatus immediately with state IDLE.
Download	Use the URL and SHA-256 from PrepareComponentInfo to download and verify images. Report FAILED if integrity check fails.
Atomicity	Ensure StartUpdate is atomic or can be safely retried — partial writes must not leave the system unbootable.
Revertibility	After StartUpdate, the previous firmware must remain available until ApplyUpdate commits the new version. Use A/B partition schemes or similar mechanisms.
Reboot	If a reboot is required, persist your state before rebooting. After restart, re-register and report the correct state.
Priority	Set the priority field based on your component's update ordering requirements. Lower values are processed first.
Error reporting	Provide meaningful error messages in ErrorInfo — these are surfaced to the cloud for remote diagnostics.

Related Pages

• Deployment Flows — section overview with deployment architecture and SOTA vs FOTA comparison
• Update Flow Overview — end-to-end update sequence showing how CM orchestrates the full deployment
• SOTA vs FOTA — detailed comparison of software and firmware update mechanisms

• Rollback and Recovery — how failed updates are detected, reverted, and reported

• Update Manager (CM module) — internal architecture of the CM Update Manager that sends commands to UMs
• Communication Manager — CM component overview including the Update Manager module