Skip to content

Trigger OTA Updates via NATS

This guide shows how to send OTA commands to a running Py ToloMEO service using NATS. For a complete command reference including all payload fields, see OTA Commands.

Prerequisites

  • NATS CLI installed and configured with server credentials
  • A Py ToloMEO service running with an OTAPlugin registered

Typical Update Flow

1. Notify the system of an available update

timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"NotifyOTAUpdate","vs":"{\"id\":\"swupdate\", \"fw_name\":\"firmware\", \"fw_version\":\"1.2.3\", \"url\":\"https://example.com/firmware/v1.2.3.swu\"}"}]'

2. Start the download

timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"StartOTADownload","vs":"{\"id\":\"swupdate\"}"}]'

3. Install the update

timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"InstallOTAUpdate","vs":"{\"id\":\"swupdate\"}"}]'

Check the Current Status

timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"GetOTAStatus","vs":"{\"id\":\"swupdate\"}"}]'

With synchronous reply-to

Subscribe to events.params in a separate terminal:

nats sub "events.params"

Then publish with a unique --reply identifier:

timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
  --reply "<unique-id>" \
  '[{"bn":"", "t":'"$timestamp"',"n":"GetOTAStatus","vs":"{\"id\":\"swupdate\"}"}]'

The response arrives on events.params with the reply field set to the same <unique-id>, allowing you to correlate it with the originating request.

Pause and Resume a Download

# Pause
timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"PauseOTADownload","vs":"{\"id\":\"swupdate\"}"}]'

# Resume
timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"ResumeOTADownload","vs":"{\"id\":\"swupdate\"}"}]'

Recover from Failures

Warning

AbortOTAUpdate and CancelOTAUpdate discard the in-flight download and return the FSM to update_available. The pending update must be re-downloaded before it can be installed.

# After download_failed → return to update_available
timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"AbortOTAUpdate","vs":"{\"id\":\"swupdate\"}"}]'

# After update_failed → return to update_available
timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"AbortOTAUpdate","vs":"{\"id\":\"swupdate\"}"}]'

# Cancel from downloading/paused/update_ready → return to update_available
timestamp=$(date +%s.%3N)
nats pub commands.swupdate.req \
'[{"bn":"", "t":'"$timestamp"',"n":"CancelOTAUpdate","vs":"{\"id\":\"swupdate\"}"}]'

Subscribe to OTA Status Events

nats sub events.infos

Events are published as JSON with fields fwName, fwVersion, otaStatus, and optionally pendingFwName/pendingFwVersion.

See also