OTA State Machine¶

State Diagram¶

States¶

State	Value	Description
`bootstrapping`	`bootstrapping`	Initial state on startup. Resolves to the correct runtime state by reading the checkpoint file.
`updated`	`updated`	System is running the latest firmware. Normal idle state.
`update_available`	`update_available`	An update has been signalled via `NotifyOTAUpdate`.
`downloading`	`downloading`	The update artifact is being downloaded.
`paused`	`paused`	Download is paused. Resumed via `ResumeOTADownload`.
`download_failed`	`download_failed`	Download encountered an error.
`update_ready`	`update_ready`	Artifact downloaded and ready for installation.
`updating`	`updating`	The update is being installed.
`update_failed`	`update_failed`	Installation failed.
`update_successful`	`update_successful`	Update installed successfully. Terminal state.

Transitions¶

Trigger	From	To
`notify`	`updated`, `update_available`	`update_available`
`download`	`update_available`, `download_failed`	`downloading`
`pause`	`downloading`	`paused`
`resume`	`paused`	`downloading`
`download_fail`	`downloading`	`download_failed`
`download_success`	`downloading`	`update_ready`
`install`	`update_ready`, `update_failed`	`updating`
`update_fail`	`updating`	`update_failed`
`update_success`	`updating`	`update_successful`
`abort`	`download_failed`, `update_failed`	`update_available`
`clear`	`update_available`	`updated`
`cancel`	`downloading`, `paused`, `update_ready`	`update_available`
`reset`	Any (except `update_successful`)	`bootstrapping`

Bootstrap Transitions (startup recovery)¶

Trigger	From	To
`detect_up_to_date`	`bootstrapping`	`updated`
`detect_update_available`	`bootstrapping`	`update_available`
`detect_download_paused`	`bootstrapping`	`paused`
`detect_update_ready`	`bootstrapping`	`update_ready`
`detect_download_error`	`bootstrapping`	`download_failed`
`detect_update_error`	`bootstrapping`	`update_failed`

A checkpointed pending update that would roll the firmware back — older than the installed version, equal to it unless allow_same_version is set, or not valid Semantic Versioning — is dropped, and bootstrapping resolves with detect_up_to_date.

Error Recovery Paths¶

Failure	Correct recovery command
Download failed	`AbortOTAUpdate` → returns to `update_available`
Installation failed	`AbortOTAUpdate` → returns to `update_available`
Cancel in-progress download	`CancelOTAUpdate` → returns to `update_available`
Full reset	`ResetOTAState` → returns to `bootstrapping` → resolves to `updated`