System Updates

Nexigon manages system updates through device properties and commands. This page documents the property schemas and conventions that make up the system update protocol.

For a task-oriented walkthrough, see the System Updates guide. For the Rugix-specific integration, see OTA System Updates with Rugix.

Overview

The system update protocol uses three primitives:

Primitive	Name	Purpose
Desired state	dev.nexigon.ota.config property	Where to look for updates (repository path)
Actual state	dev.nexigon.ota.status property	Effective configuration, installed version, and update progress
Trigger	nexigon.ota.check command	Forces an immediate update check

The device-side update script reads the desired state, compares it with the installed version, converges toward it, and publishes the actual state. Any component (UI, CLI, fleet automation) can write the desired state.

Configuration Property (dev.nexigon.ota.config)

This property overrides the update configuration baked into the device image on a per-device basis. All fields are optional; only set fields override.

{
  "path": "my-repo/my-package/stable"
}

Field	Type	Description
path	string	Repository version path in the format <repository>/<package>/<version-tag>

When this property is removed, the update script reverts to the defaults baked into the image.

Status Property (dev.nexigon.ota.status)

Published by the device-side update script to report the effective configuration and update progress.

{
  "config": {
    "path": "my-repo/my-package/stable"
  },
  "currentVersion": "build-20260401120000-abc1234",
  "state": "idle",
  "targetVersion": null,
  "failureCount": 0,
  "lastError": null
}

Field	Type	Description
config	OtaUpdateConfig	Effective configuration (defaults merged with device overrides)
currentVersion	string	Currently installed version (should match a repository version tag)
state	OtaUpdateState	Current state of the update process
targetVersion	string	Target version being installed, if an update is in progress
failureCount	u32	Consecutive failed attempts for the current target (reset on success or config change)
lastError	string	Error message from the most recent failure

The config block reflects the effective configuration after merging. This allows the UI to display what the device is tracking even when no per-device override is set.

State Values

The state field reports where the device is in the update lifecycle. The Nexigon UI interprets these values to display status badges and offer appropriate actions. The transitions between states are determined by your update script — Nexigon does not enforce a particular state machine.

The following values are defined:

State	Meaning
idle	No update has been attempted yet
installing	Downloading and installing the update
rebooting	Rebooting into the new version
committing	Confirming the new version after a successful boot
completed	The last update completed successfully
failed	The last update failed
blocked	An update is available but deferred (e.g., device not in a safe state or awaiting approval)
rollback	Rolling back to the previous version

Not all values need to be used. A simpler update script might only report idle, installing, completed, and failed.

Retries

When an update fails, the update script should record failureCount and lastError in the status property. How retries are handled is up to the update script — the ready-made integrations retry on every check cycle with no limit.

Version Identification

By convention, currentVersion should match a repository version tag so the UI can resolve it back to the exact package version. For example, if the build pipeline tags versions as build-20260401120000-abc1234, baking that same string as the release version into the device image allows the UI to:

• Link the installed version to its repository entry
• Display semantic version tags (e.g., v2.1.0, stable)
• Enable one-click deploys from the device header

Implementing a Custom Update Agent

You can implement the system update protocol with any update system. The script needs to:

1. Read dev.nexigon.ota.config to determine the target version path
2. Resolve the target version from the Nexigon repository
3. Compare with the currently installed version
4. Download and install the update using your update system (RAUC, SWUpdate, etc.)
5. Publish dev.nexigon.ota.status to report progress
6. Emit events for observability

The ready-made Rugix OTA script serves as a complete reference implementation.

The key requirement is that your script publishes dev.nexigon.ota.status so the UI can display update progress and offer deploy actions. You can optionally register a device command (e.g., my-updater.check) that triggers an immediate update check, enabling the "Check Now" and "Retry" functionality in the UI.