Update Model

Nexigon updates devices by reconciliation. For each device, Nexigon Hub stores the desired state: which software the device should run and under which conditions it may install it. The device compares the desired state with what it runs, works toward it on its own, and reports its progress. This page explains the model and why Nexigon uses it, how devices identify versions, and how rollouts and optional features build on the model. For the exact property formats, see the OTA update reference.

Desired and Actual State

Two device properties carry an update:

• dev.nexigon.ota.config holds the desired state. Operators write it through the web interface, Nexigon CLI, the API, or a fleet operation.
• dev.nexigon.ota.status holds the actual state. The device writes it.

For example, an operator points a device at the stable tag of the acme/gateway-os package:

{ "path": "acme/gateway-os/stable" }

The device reports which version it runs, which version it is installing, and what it is doing:

{
  "currentVersion": "2.1",
  "currentVersionId": "pkg_v_7Hq2mWbXc9RtLpZ3sNfE1k",
  "targetVersionId": "pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
  "nextVersionId": "pkg_v_3sLgP9eKd7XwHn2QaRt5Zm",
  "state": "installing"
}

On the device, an update integration implements its side of the model. An integration reads the desired state, drives an updater such as Rugix Ctrl or RAUC, and publishes the actual state. Nexigon Agent includes integrations for Rugix and RAUC, described in Set Up Rugix OTA Updates and enabled by the meta-nexigon Yocto layers. You can write your own for any other updater.

The Check Cycle

The integration runs a check periodically, after boot, and when someone runs the nexigon.ota.check device command, for example with Check Now in the web interface. Each check performs the same steps:

1. Read the desired state by merging dev.nexigon.ota.config over the defaults built into the image.
2. Determine the running version.
3. Finish an update in progress: commit a newly booted version, or record a rollback as a failure.
4. Resolve the configured path to the version the device should run, and decide which version to install next.
5. Install and activate that version, unless a spread, a maintenance window, or a retry policy defers it.
6. Publish the actual state.

When the device already runs the desired version, a check changes nothing, so checks can run as often as needed.

Why Reconciliation

Many update systems use a job model instead. The server creates an update job for each device, and the device fetches and executes its pending jobs. The state a device should end up in is then implicit in its job history. Nexigon stores that state directly, which has several consequences:

• Devices catch up after any outage. Intermittent connectivity is normal for embedded devices. A device reaches the desired state with its first check after it reconnects, without jobs that expire or pile up while it is offline.
• The latest decision wins. Changing the desired state replaces the previous decision. There are no jobs in flight that have to be cancelled or ordered.
• The device decides when it is safe. Only the device knows whether it is in use, whether its local time is inside the maintenance window, and whether the new version booted correctly. Reconciliation leaves these decisions on the device instead of modeling them on the server.
• Every client uses the same interface. The web interface, Nexigon CLI, scripts using the API, and fleet operations all deploy software by writing the same property.
• Any updater works. The contract between Nexigon and an integration consists of two properties and a command. An integration is a thin layer around an existing updater, and Nexigon Hub does not need to know which updater a device uses.

The model has two trade-offs. First, writing the desired state does not mean that the device installed the update. Check the reported status, or use a fleet operation that waits for the expected version. Second, the configuration property holds only the current decision. The history of an update lives in the device’s events, which integrations emit at each step.

Identifying Versions

Devices install software from repositories. A package holds the releases of one system, such as an operating system image. Each release is a package version with an ID, for example pkg_v_7Hq2mWbXc9RtLpZ3sNfE1k, and optional tags.

Tracking and Pinning

The last segment of the configured path is either a tag or a version ID:

• acme/gateway-os/stable tracks the floating tag stable. When the tag moves to another version, the device installs that version on its next check.
• acme/gateway-os/pkg_v_3sLgP9eKd7XwHn2QaRt5Zm pins one version. The device keeps it until the configuration changes.

The Running Version

Each image contains a version string, such as 2.1 or build-20260401120000-abc1234, for example as IMAGE_VERSION in /etc/os-release. The integration reports it as currentVersion. By convention, the package version of each release carries a locked tag equal to this string. The integration looks up currentVersion as a tag in the configured package and reports the resulting ID as currentVersionId.

With the ID, the web interface links the running version to its package version, shows its tags, such as stable, and enables one-click deployments from the device header. Checkpoint releases also rely on the ID.

The integration derives the running version from the image instead of recording which version it installed. The result is correct even if an image was installed without Nexigon, for example by factory flashing or a manual installation.

A release pipeline follows the convention by creating the version with a locked tag and building the image with the same version string. For example:

nexigon-cli repositories versions create acme/gateway-os --tag 2.1,locked

The release scripts of the Nexigon template for Rugix Bakery follow this convention with generated build tags.

Target and Next Version

The configured path resolves to the target version, which the device reports as targetVersionId. The version the device installs is the next version, reported as nextVersionId. Usually, both are the same. Some releases require that a device first runs a specific earlier version, a checkpoint. In that case, the next version is the checkpoint. Checkpoint Releases explains how devices plan such paths.

Rollouts

A rollout brings a release to a growing set of devices, for example first a few canary devices, then a tenth of the fleet, and then all devices. Nexigon supports three approaches, from simple to fully controlled:

• Moving a floating tag. Moving stable to a tested version updates every device tracking the tag on its next check.
• Spreading. A spread releases an update to a growing share of devices, either automatically over a configured duration after the tag moves, or up to a percentage that you raise manually. The devices determine on their own whether they are released.
• Fleet operations. Fleet operations set dev.nexigon.ota.config in explicit stages and wait for each device to report the expected version before advancing.

Fleet operations pin a version ID. If the stages tracked a floating tag instead, every device tracking that tag would follow as soon as the tag moves, regardless of its stage. A pinned version ID changes only for the devices the rollout has reached.

Integrations and Capabilities

Nexigon defines the contract, and integrations decide how to implement it on the device. A minimal integration reports only its running version and its state. Holds, maintenance windows, retry policies, spreading, and checkpoints are optional features. An integration lists the features it supports in the capabilities field of its status and ignores the settings of other features. Clients such as the Nexigon Hub web interface offer the corresponding settings only for devices that support them.

Holding Updates, Maintenance Windows and Retries, Spreading Updates, and Checkpoint Releases describe the optional features. The OTA update reference lists the requirements for an integration.