Preview

You're viewing the Next docs — a rolling preview of in-development changes. The current release docs may differ.

OTA Updates

This reference defines the contract between Nexigon and the update integrations on devices: the dev.nexigon.ota.config and dev.nexigon.ota.status properties, the nexigon.ota.check command, and the requirements for an integration. For the concepts behind the contract, read Update Model. To deploy an update, follow Deploy System Updates.

The contract is unstable and may still change in incompatible ways.

Interface

Name	Kind	Usage	Purpose
`dev.nexigon.ota.config`	Protected property	Written by operators	Desired state of the device
`dev.nexigon.ota.status`	Property	Written by the device	Actual state of the device
`nexigon.ota.check`	Device command	Registered by the device, run by operators	Requests an immediate check

Configuration Property

dev.nexigon.ota.config overrides the update configuration built into the device image. The integration applies the property to the image defaults as a JSON merge patch: objects merge recursively, null removes a default, and any other value, including an array, replaces the default. When the property is removed, the image defaults apply again. For example, { "window": null } removes a maintenance window built into the image.

dev.nexigon.ota.config

{
  "path": "acme/gateway-os/stable",
  "window": {
    "ranges": [{ "start": "02:00", "end": "05:00" }]
  },
  "retry": {
    "maxAttempts": 3,
    "initialDelaySecs": 900,
    "maxDelaySecs": 3600,
    "cooldownSecs": 86400
  },
  "spread": { "durationSecs": 604800 }
}

Field	Description
`path`	Version path in the format `<repository>/<package>/<version>`. `<version>` is a tag, which the device tracks, or a version ID, which pins the version.
`hold`	Holds the device at its current version while `true`. Defaults to `false`.
`window`	Maintenance window restricting activation. Without a window, updates can be activated at any time.
`retry`	Retry policy with `maxAttempts`, `initialDelaySecs`, `maxDelaySecs`, and `cooldownSecs`.
`spread`	Spread with `durationSecs`, `startAt`, and `percentage`, all optional. Without a spread, devices update without waiting.

Every write to the property increments its version, even if the value is unchanged. Integrations that support retries reset the failure count when the version changes, so writing the property again requests new attempts.

Holding Updates

Setting hold to true keeps a device at its current version, for example to stop a faulty release from spreading further or to keep a device unchanged while you investigate a problem:

dev.nexigon.ota.config

{ "path": "acme/gateway-os/stable", "hold": true }

While held, the device starts no new update. It reports the state blocked with the code hold and without nextAttemptAt. An update in progress completes, including its reboot and commit, so a hold never leaves a device halfway between two versions. Removing the hold, or setting it to false, lets the device continue toward the target on its next check.

A hold does not stop the clock of a spread. Devices whose turn passed during the hold update once it is removed.

Integrations that do not list the hold capability ignore the setting. Check the capabilities of a device before relying on a hold.

Status Property

The integration publishes dev.nexigon.ota.status to report the effective configuration, the running version, and the progress of an update. It updates the property on every state change.

dev.nexigon.ota.status

{
  "capabilities": ["window", "retry", "checkpoints"],
  "config": {
    "path": "acme/gateway-os/stable",
    "window": { "ranges": [{ "start": "02:00", "end": "05:00" }] },
    "retry": {
      "maxAttempts": 3,
      "initialDelaySecs": 900,
      "maxDelaySecs": 3600,
      "cooldownSecs": 86400
    }
  },
  "configVersion": 7,
  "currentVersion": "2.1",
  "currentVersionId": "pkg_v_7Hq2mWbXc9RtLpZ3sNfE1k",
  "state": "failed",
  "targetVersion": "2.2",
  "targetVersionId": "pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
  "nextVersionId": "pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
  "failureCount": 1,
  "lastError": "rugix-ctrl update install failed",
  "nextAttemptAt": "2026-10-16T00:15:00Z",
  "updater": {
    "name": "rugix",
    "version": "1.3.0",
    "bootedSlot": "a",
    "primarySlot": "a",
    "awaitingCommit": false,
    "slots": [
      { "name": "a", "state": "booted" },
      { "name": "b", "state": "inactive" }
    ]
  }
}

Field	Description
`capabilities`	Optional features that the integration supports.
`config`	Effective configuration, including the defaults that the integration applies.
`configVersion`	Version of `dev.nexigon.ota.config` that the integration last read, as returned with the property. Absent when the property does not exist.
`currentVersion`	Version string of the running system, as built into the image. By convention, a locked tag of the corresponding package version.
`currentVersionId`	Package version of the running system, resolved by looking up `currentVersion` as a tag in the configured package. Absent when the tag does not resolve.
`state`	State of the update process.
`blocked`	Present when `state` is `blocked`. Contains a code and an optional human-readable `message`.
`targetVersion`	Version string of the target version, as built into its image. Integrations read it from the version’s metadata, such as `imageVersion` in the Rugix integration.
`targetVersionId`	Package version that the configured path resolves to.
`nextVersionId`	Package version that the device installs next. Differs from the target when the device must install a checkpoint first.
`failureCount`	Consecutive failed attempts for the next version. Resets when the next version or `configVersion` changes, when the retry cooldown ends, or when an update succeeds.
`lastError`	Error message of the last failure.
`nextAttemptAt`	Earliest time of the next attempt while the device waits for a spread, its maintenance window, a retry delay, or a retry cooldown. Absent when the time is unknown.
`updater`	Update system that installs versions on the device, with its version and slots.

The schema marks every field as optional, so that clients can handle partial reports from older or simpler integrations. Clients treat absent fields as unknown. The requirements define which fields an integration must report.

States

The state field reports where the device is in the update lifecycle. Nexigon Hub does not enforce transitions between states.

State	Meaning
`idle`	No path is configured, or no update has been attempted yet.
`installing`	The device is downloading and installing a version.
`rebooting`	The device is rebooting into the new version.
`committing`	The device is committing the new version after a successful boot.
`completed`	The last update completed successfully, or the device already runs the target.
`failed`	The last attempt failed.
`blocked`	An update is available but cannot proceed yet. `blocked` explains why.
`rollback`	The device is rolling back to the previous version.

The resting states are idle, completed, failed, and blocked. An integration does not have to use every state. A simple integration might report only idle, installing, completed, and failed.

Blocked Codes

A blocked update reports a machine-readable code in kebab case and an optional human-readable message:

{
  "code": "awaiting-approval",
  "message": "Waiting for approval on the local display."
}

Nexigon defines the following codes. Integrations may define their own codes for conditions specific to the device, as in the example. Clients display the message, or the code if the message is absent.

Code	Meaning
`hold`	The configuration holds the device at its current version.
`spread`	A spread has not released the device yet. `nextAttemptAt` holds the release time, if known.
`window`	The device waits for its maintenance window. `nextAttemptAt` holds its start.
`no-update-path`	The target is unreachable without going back across a checkpoint.
`unknown-current-version`	The target has a base version, but `currentVersion` does not resolve to a package version.

Capabilities

An integration lists the optional features that it supports in capabilities. It ignores configuration fields for features that it does not list. Clients offer settings only for listed features.

Capability	Meaning
`window`	Honors `window` as described in Maintenance Windows.
`retry`	Honors `retry` and reports `configVersion` as described in Retries.
`hold`	Honors `hold` as described in Holding Updates.
`spread`	Honors `spread` as described in Spreading Updates.
`checkpoints`	Plans update paths through base versions as described in Checkpoint Releases.

Update System

The updater field describes the update system that installs versions on the device, such as Rugix Ctrl or RAUC:

Field	Description
`name`	Name of the update system, such as `rugix` or `rauc`.
`version`	Version of the update system.
`bootedSlot`	Slot that the running system booted from.
`primarySlot`	Slot that the device boots next. Differs from `bootedSlot` while a version is on trial or after an installation.
`awaitingCommit`	Whether the running system awaits its commit.
`slots`	Slots that hold bootable systems, each with its `name` and, if known, its `state`, its `health`, and the installed `version`.

Slot names, states, and health values are those of the update system. The Rugix integration reports boot groups as slots. The RAUC integration reports the slots that have a boot name, with the state and boot status that RAUC reports. The web interface shows this information under Status in Configure Updates.

Check Command

An integration registers the device command nexigon.ota.check to run a check on request. The web interface recognizes this exact name. It runs the command for Check Now and after deploying an update. Retry Update writes dev.nexigon.ota.config again and then runs the command.

Implementing an Integration

An integration can use any updater and any language. A check typically performs these steps:

Read dev.nexigon.ota.config and merge it over the image defaults.
Read the version string from the image and resolve it as a tag in the configured package to obtain currentVersionId.
If the previously published status shows an update in progress, check whether the device runs the version it installed, nextVersionId. Commit the version if it does. Otherwise, record the rollback as a failed attempt.
Resolve the configured path to the target version. If the device already runs it, report completed.
Determine the next version. With checkpoint support, plan the path as described in Checkpoint Releases. Otherwise, the next version is the target.
Check whether the device may attempt the update now. While held, report blocked with the code hold. Until a spread releases the device, report blocked with the code spread. During a retry delay or cooldown, keep the state failed. Otherwise, if the maintenance window is closed, report blocked with the code window. Set nextAttemptAt whenever the time of the next attempt is known.
Install and activate the next version, reporting each state change.

An integration must:

Publish dev.nexigon.ota.status with at least currentVersion and state.
List only the capabilities that it implements, and ignore the settings of other features.

An integration should also:

Report the effective configuration in config, including its own defaults for supported features, so that clients can show how the device behaves.
Report currentVersionId, targetVersionId, and nextVersionId, so that clients can link the versions to the repository.
Report the update system in updater, so that operators can see which slot the device boots and diagnose failed updates.
Emit events in the ota category at each step, so that the history of an update is visible in the device’s event log.
Delay scheduled checks by a random amount, so that devices whose checks are due at the same time, for example when a shared maintenance window opens, do not reach Nexigon Hub at once.

Nexigon Agent provides the commands an integration needs:

Command	Purpose
`nexigon-agent device id`	Output the device ID, for example to compute a spread turn.
`nexigon-agent device properties get <name>`	Read the configuration and the previously published status.
`nexigon-agent device properties set <name> <value>`	Publish the status.
`nexigon-agent repositories versions resolve <path>`	Resolve a version path, such as the running version’s tag.
`nexigon-agent repositories versions info <path-or-id>`	Read a version’s assets, metadata, tags, and base version.
`nexigon-agent repositories issue-url <asset-path>`	Issue a download URL for an asset.
`nexigon-agent events emit`	Emit an event.

The Rugix and RAUC integrations of Nexigon Agent implement the complete check cycle. Their source code can guide your own integration.

Repository Fields

Two fields of package versions support the OTA update contract:

Base versions. Checkpoints rely on the base version of each package version. Version details and version lists include it as baseVersionId. repositories_CreateVersion accepts baseVersionId, and repositories_SetVersionBase changes or clears it. Managing Base Versions describes the rules and the corresponding Nexigon CLI commands.
Tag assignment times. Each tag in the version details and version lists includes assignedAt, the time at which the tag was assigned to the version. Spreads start at this time unless the configuration sets startAt.

Sidex Schema

The properties Sidex schema defines the property formats:

schema`properties`

Types related to device properties.

record

`OtaUpdateConfig`

Unstable (feature ota_updates)

OTA update configuration (dev.nexigon.ota.config).

Desired state of a device. Integrations apply the property to defaults built into the image as a JSON merge patch (RFC 7396): objects merge recursively, null removes a default, and any other value, including an array, replaces the default.

Fields (JSON object)

pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version.

string
assetoptional
Filename of the asset that the device installs from a version.

Defaults to <system>.<extension>, where <system> is the name of the running system and the update system determines the extension, such as rugixb for Rugix Ctrl and raucb for RAUC.

string
holdoptional
Hold the device at its current version.

While set, the device starts no new update. An update in progress completes, including its activation. Defaults to false.

boolean
windowoptional
Maintenance window restricting when updates are activated.

Updates can be activated at any time when absent.
OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts.
OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates across devices.

Devices update without waiting when absent.
OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the configuration, which starts a new round of attempts on devices whose attempts failed.

integer

record

`OtaUpdateWindow`

Unstable (feature ota_updates)

Maintenance window in the device's local time.

The window restricts activation, the step that interrupts the device's operation, such as the reboot into the new version. Integrations may download and install an update outside the window if doing so does not interrupt operation.

Fields (JSON object)

rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.
array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string

record

`OtaUpdateWindowRange`

Unstable (feature ota_updates)

Recurring time range of a maintenance window.

Fields (JSON object)

daysoptional
Days on which the range starts.

Defaults to every day.
array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string

wrapper

`TimeOfDay`

Unstable (feature ota_updates)

Time of day in the format HH:MM (24-hour clock).

Transparent wrapper — the JSON shape is the wrapped type.

string

variant

`Weekday`

Unstable (feature ota_updates)

Day of the week.

Casesexternally

Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"

record

`OtaUpdateRetryPolicy`

Unstable (feature ota_updates)

Retry policy for failed update attempts.

An attempt starts when the device begins downloading a version. Failures before that, such as an unreachable Nexigon Hub, do not count as attempts. The delay between attempts starts at initial_delay_secs and doubles after each failed attempt, up to max_delay_secs.

Fields (JSON object)

maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer

record

`OtaUpdateSpread`

Unstable (feature ota_updates)

Spreading of updates across devices.

Each device derives its position u from the SHA-256 hash of <device-id>/<target-version-id>: the first 8 bytes, read as a big-endian unsigned integer n, give u = floor(n / 2^11) / 2^53, which a double-precision number represents exactly. A device may start updating to the target once both of the following hold:

With duration_secs, its turn has begun at start + floor(duration_secs * sqrt(u)). The share of eligible devices thus grows quadratically from 0 at the start to 1 after duration_secs.
With percentage, its position is below percentage / 100.

Fields (JSON object)

durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number

record

`OtaUpdateStatus`

Unstable (feature ota_updates)

OTA update status (dev.nexigon.ota.status).

Actual state of a device, published by its update integration.

The integration writes the status with the version it read last (compare-and-swap), so that it does not overwrite concurrent changes. Other writers may only clear failure_count and next_attempt_at, which requests a new attempt.

Fields (JSON object)

capabilitiesoptional
Optional features of the OTA update contract that the integration supports.
array<OtaUpdateCapability>
Items
OtaUpdateCapability
Casesexternally
Window→ "window"
The integration honors config.window.

Value: "window"
Retry→ "retry"
The integration honors config.retry and resets the failure count when the configuration is written.

Value: "retry"
Checkpoints→ "checkpoints"
The integration installs checkpoints according to base versions.

Value: "checkpoints"
Spread→ "spread"
The integration honors config.spread.

Value: "spread"
Hold→ "hold"
The integration honors config.hold.

Value: "hold"
Asset→ "asset"
The integration honors config.asset.

Value: "asset"
configoptional
Effective configuration, including the defaults the integration applies.
OtaUpdateConfig
Fields (JSON object)
pathoptional
Version path in the format <repository>/<package>/<version>.

<version> is a tag or a version ID. A tag tracks the version the tag points to. A version ID pins a single version.

string
assetoptional
Filename of the asset that the device installs from a version.

Defaults to <system>.<extension>, where <system> is the name of the running system and the update system determines the extension, such as rugixb for Rugix Ctrl and raucb for RAUC.

string
holdoptional
Hold the device at its current version.

While set, the device starts no new update. An update in progress completes, including its activation. Defaults to false.

boolean
windowoptional
Maintenance window restricting when updates are activated.

Updates can be activated at any time when absent.

OtaUpdateWindow
Fields (JSON object)
rangesrequired
Time ranges in which updates can be activated.

An empty list never allows activation.

array<OtaUpdateWindowRange>
Items
OtaUpdateWindowRange
Fields (JSON object)
daysoptional
Days on which the range starts.

Defaults to every day.

array<Weekday>
Items
Weekday
Casesexternally
Monday→ "monday"
Value: "monday"
Tuesday→ "tuesday"
Value: "tuesday"
Wednesday→ "wednesday"
Value: "wednesday"
Thursday→ "thursday"
Value: "thursday"
Friday→ "friday"
Value: "friday"
Saturday→ "saturday"
Value: "saturday"
Sunday→ "sunday"
Value: "sunday"
startrequired
Start of the range (inclusive).

TimeOfDay
Wraps
string
endrequired
End of the range (exclusive).

An end at or before the start lies on the following day. A range whose end equals its start therefore spans 24 hours.

TimeOfDay
Wraps
string
retryoptional
Retry policy for failed update attempts.

OtaUpdateRetryPolicy
Fields (JSON object)
maxAttempts(from max_attempts)optional
Maximum number of failed attempts for a version.

Unlimited when absent.

integer
initialDelaySecs(from initial_delay_secs)optional
Delay before the first retry in seconds.

integer
maxDelaySecs(from max_delay_secs)optional
Maximum delay between attempts in seconds.

integer
cooldownSecs(from cooldown_secs)optional
Time in seconds after reaching max_attempts before the failure count resets and a new round of attempts begins.

Without a cooldown, the device stops attempting the version until the version of the configuration changes or the failure count is cleared.

integer
spreadoptional
Spreading of updates across devices.

Devices update without waiting when absent.

OtaUpdateSpread
Fields (JSON object)
durationSecs(from duration_secs)optional
Time over which updates are spread, in seconds.

integer
startAt(from start_at)optional
Start of the spread over time.

Defaults to the time at which the tag in the configured path was assigned to its current version. Without an explicit start, updates to versions configured by version ID are not spread over time.

Timestamp
percentageoptional
Share of devices that may update, in percent.

Raising the percentage only adds devices. Without duration_secs, it releases the update to the given share right away. With duration_secs, it caps the share of the spread over time.

number
rolloutoptional
Rollout number.

Integrations ignore its value. Changing it changes the configuration, which starts a new round of attempts on devices whose attempts failed.

integer
configVersion(from config_version)optional
Version of the dev.nexigon.ota.config property that the integration last read.

Absent when the property does not exist. The version changes with every write to the device's own value and whenever a profile revision that sets the property is applied to the device, even with an unchanged value.

integer (i64)
currentVersion(from current_version)optional
Version string of the running system, as built into the image.

By convention, a locked tag of the corresponding package version.

string
currentVersionId(from current_version_id)optional
Package version of the running system.

Resolved by looking up current_version as a tag in the configured package. Absent when the tag does not resolve.

PackageVersionIdstring
stateoptional
Current state of the update process.
OtaUpdateState
Casesexternally
Idle→ "idle"
No path is configured, or no update has been attempted yet.

Value: "idle"
Installing→ "installing"
An update is being installed.

Value: "installing"
Rebooting→ "rebooting"
The device is rebooting into the new version.

Value: "rebooting"
Committing→ "committing"
Committing the new version after a successful reboot.

Value: "committing"
Completed→ "completed"
The last update completed successfully, or the device already runs the target.

Value: "completed"
Failed→ "failed"
The last update failed.

Value: "failed"
Blocked→ "blocked"
An update is available but cannot proceed yet. See blocked for the reason.

Value: "blocked"
Rollback→ "rollback"
The device is rolling back to the previous version.

Value: "rollback"
blockedoptional
Why the update is blocked. Present when state is blocked.
OtaUpdateBlocked
Fields (JSON object)
coderequired
Machine-readable reason in kebab case.

Nexigon defines these codes:

hold: The configuration holds the device at its current version.

spread: The device waits for its turn in a spread or is outside the released percentage.

window: The device waits for its maintenance window.

no-update-path: The target is unreachable without going back across a checkpoint.

unknown-current-version: The target has a base version, but current_version does not resolve to a package version.

no-asset: The next version has no available asset with the filename in config.asset.

Integrations may define their own codes for conditions specific to the device, such as awaiting-approval.

string
messageoptional
Human-readable explanation.

string
targetVersion(from target_version)optional
Version string of the target version, as built into its image.

string
targetVersionId(from target_version_id)optional
Package version that the configured path resolves to.

PackageVersionIdstring
nextVersionId(from next_version_id)optional
Package version that the device installs next.

Differs from target_version_id when the device must install a checkpoint before the target.

PackageVersionIdstring
failureCount(from failure_count)optional
Number of consecutive failed attempts for the next version.

Resets to zero when the next version or config_version changes, when the retry cooldown ends, when an update succeeds, or when another writer clears it.

integer
lastError(from last_error)optional
Error message of the last failure, if any.

string
nextAttemptAt(from next_attempt_at)optional
Earliest time of the next attempt.

Set while the device waits for a spread, a maintenance window, a retry delay, or a retry cooldown. Absent when the time of the next attempt is unknown or no further attempt is scheduled.

Timestamp
updateroptional
Update system that installs versions on the device.
OtaUpdater
Fields (JSON object)
namerequired
Name of the update system, such as rugix or rauc.

string
versionoptional
Version of the update system.

string
bootedSlot(from booted_slot)optional
Slot that the running system booted from.

string
primarySlot(from primary_slot)optional
Slot that the device boots from next.

Differs from booted_slot when the device runs a version on trial or has installed a version that it has not booted yet.

string
awaitingCommit(from awaiting_commit)optional
Whether the running system awaits its commit.

boolean
slotsoptional
Slots that the update system installs versions into.

array<OtaUpdaterSlot>
Items
OtaUpdaterSlot
Fields (JSON object)
namerequired
Name of the slot.

string
stateoptional
State of the slot, such as booted or inactive.

string
healthoptional
Health of the slot, such as good or bad.

string
versionoptional
Version installed in the slot, if the update system records it.

string

variant

`OtaUpdateCapability`

Unstable (feature ota_updates)

Optional feature of the OTA update contract.

Casesexternally

Window→ "window"
The integration honors config.window.

Value: "window"
Retry→ "retry"
The integration honors config.retry and resets the failure count when the configuration is written.

Value: "retry"
Checkpoints→ "checkpoints"
The integration installs checkpoints according to base versions.

Value: "checkpoints"
Spread→ "spread"
The integration honors config.spread.

Value: "spread"
Hold→ "hold"
The integration honors config.hold.

Value: "hold"
Asset→ "asset"
The integration honors config.asset.

Value: "asset"

variant

`OtaUpdateState`

Unstable (feature ota_updates)

OTA update state.

The resting states are idle, completed, failed, and blocked. The integration remains in one of these until the next check begins or the blocking condition clears.

Casesexternally

Idle→ "idle"
No path is configured, or no update has been attempted yet.

Value: "idle"
Installing→ "installing"
An update is being installed.

Value: "installing"
Rebooting→ "rebooting"
The device is rebooting into the new version.

Value: "rebooting"
Committing→ "committing"
Committing the new version after a successful reboot.

Value: "committing"
Completed→ "completed"
The last update completed successfully, or the device already runs the target.

Value: "completed"
Failed→ "failed"
The last update failed.

Value: "failed"
Blocked→ "blocked"
An update is available but cannot proceed yet. See blocked for the reason.

Value: "blocked"
Rollback→ "rollback"
The device is rolling back to the previous version.

Value: "rollback"

record

`OtaUpdateBlocked`

Unstable (feature ota_updates)

Information about a blocked update.

Fields (JSON object)

coderequired
Machine-readable reason in kebab case.

Nexigon defines these codes:
- hold: The configuration holds the device at its current version.
- spread: The device waits for its turn in a spread or is outside the released percentage.
- window: The device waits for its maintenance window.
- no-update-path: The target is unreachable without going back across a checkpoint.
- unknown-current-version: The target has a base version, but current_version does not resolve to a package version.
- no-asset: The next version has no available asset with the filename in config.asset.
Integrations may define their own codes for conditions specific to the device, such as awaiting-approval.
string
messageoptional
Human-readable explanation.

string

record

`OtaUpdater`

Unstable (feature ota_updates)

Update system that installs versions on a device, such as Rugix Ctrl or RAUC.

Slot names, states, and health values are those of the update system.

Fields (JSON object)

namerequired
Name of the update system, such as rugix or rauc.

string
versionoptional
Version of the update system.

string
bootedSlot(from booted_slot)optional
Slot that the running system booted from.

string
primarySlot(from primary_slot)optional
Slot that the device boots from next.

Differs from booted_slot when the device runs a version on trial or has installed a version that it has not booted yet.

string
awaitingCommit(from awaiting_commit)optional
Whether the running system awaits its commit.

boolean
slotsoptional
Slots that the update system installs versions into.
array<OtaUpdaterSlot>
Items
OtaUpdaterSlot
Fields (JSON object)
namerequired
Name of the slot.

string
stateoptional
State of the slot, such as booted or inactive.

string
healthoptional
Health of the slot, such as good or bad.

string
versionoptional
Version installed in the slot, if the update system records it.

string

record

`OtaUpdaterSlot`

Unstable (feature ota_updates)

Slot of an update system.

Fields (JSON object)

namerequired
Name of the slot.

string
stateoptional
State of the slot, such as booted or inactive.

string
healthoptional
Health of the slot, such as good or bad.

string
versionoptional
Version installed in the slot, if the update system records it.

string

Edit this page

PreviousRun a Fleet Operation NextUpdate Model

OTA Updates

Interface

Configuration Property

Holding Updates

Status Property

States

Blocked Codes

Capabilities

Update System

Check Command

Implementing an Integration

Repository Fields

Sidex Schema

schemaproperties

schema`properties`