Skip to content

OTA Command Reference

All commands are sent to the commands.swupdate.req NATS subject (or the HTTP endpoint).

Note

The vs field contains a JSON-encoded string, not a direct JSON object. The inner payload dict must be serialised to a string before being placed in vs.

Commands

Command Description Valid from states
GetOTAStatus Retrieve current OTA status Any
NotifyOTAUpdate Signal an available update updated, update_available
StartOTADownload Begin downloading the update package update_available, download_failed
PauseOTADownload Pause an in-progress download downloading
ResumeOTADownload Resume a paused download paused
InstallOTAUpdate Install the downloaded update update_ready, update_failed
AbortOTAUpdate Recover from a failed download or install download_failed, update_failed
ClearOTAUpdate Clear a pending update and return to updated update_available
CancelOTAUpdate Cancel an in-progress or paused operation downloading, paused, update_ready
ResetOTAState Discard any pending update, clean up any in-flight download, remove the checkpoint, and re-detect state — resolving to updated Any except update_successful

Payload Schemas

NotifyOTAUpdate

{
  "id": "swupdate",
  "fw_name": "firmware",
  "fw_version": "1.2.3",
  "url": "https://example.com/firmware/v1.2.3.swu",
  "dest": "/data/tolomeo/ota.pkg"
}
Field Required Description
id Yes Plugin identifier (always "swupdate")
fw_name Yes Firmware name
fw_version Yes Firmware version, in Semantic Versioning 2.0.0
url Yes Download URL
dest No Download path (defaults to /data/tolomeo/ota.pkg)

fw_version is compared with the installed firmware's BUILD_VERSION by Semantic Versioning precedence (build metadata is ignored), to prevent a rollback:

  • Newer — accepted: the pending update is set and the state moves to update_available.
  • Older — ignored: the state and any pending update are left untouched, and the command still returns {"result": "success", "status": <current state>}.
  • Equal — ignored like an older version, unless the plugin's allow_same_version option is true.

A fw_version that is not valid Semantic Versioning 2.0.0 is rejected with "result": "error", again without changing the state.

StartOTADownload

{"id": "swupdate", "dest": "/data/tolomeo/ota.pkg"}

url is optional if previously set via NotifyOTAUpdate.

All other commands

{"id": "swupdate"}

Message Format

[{"bn": "<base_name>", "t": <unix_timestamp>, "n": "<CommandName>", "vs": "<json_string>"}]
  • bn — base name (NATS only, optional)
  • t — Unix timestamp in seconds (NATS only, optional)
  • n — command name
  • vs — JSON-encoded string payload

Event Messages (events.infos)

{
  "fwName": "firmware",
  "fwVersion": "1.2.3",
  "otaStatus": "downloading",
  "pendingFwName": "firmware",
  "pendingFwVersion": "1.3.0",
  "timestamp": 1700000010
}

pendingFwName and pendingFwVersion are only present when an update is pending.

Status Values

Status Description
updated Running latest firmware
update_available An update has been detected
downloading Artifact download is in progress
paused Download is paused
download_failed Download failed
update_ready Download complete, ready to install
updating Installation in progress
update_failed Installation failed
update_successful Update completed (final state)

See also