Skip to content

Py ToloMEO

OTA Command Reference

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
`url`	Yes	Download URL
`dest`	No	Download path (defaults to `/data/tolomeo/ota.pkg`)

`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