Deploy System Updates

Deploy a published system image to a device, track an update channel, and inspect the result in Nexigon. A device-side updater installs the image; Nexigon stores the release, selects the desired version, and records progress.

Before You Start

You need a connected device with a system update integration and a release published to a repository in the format that integration expects. For Rugix, use the release workflow so the published bundle filename and image-version metadata match the device.

For a private repository, link it to the device’s project under Project Settings → Repositories so the device can download its software. To choose the package of a device in the web interface, link its repository even if it is public.

If your image does not yet include an updater, follow Set Up Rugix OTA Updates for Rugix Bakery or Yocto. For RAUC, use the meta-nexigon-rauc Yocto layer from meta-nexigon; its Kas examples provide reference configurations.

A custom integration must implement the OTA update contract.

How the Update Is Coordinated

The update integration connects four parts of Nexigon. The protected dev.nexigon.ota.config property records the desired update source. The device publishes its installed version and progress in dev.nexigon.ota.status. The nexigon.ota.check command requests a check, and events record what happened during the update. The web interface, Nexigon CLI, and fleet operations use these same interfaces, so the deployment workflow can work with different device-side updaters.

A deployment changes the desired state. The device’s updater resolves the selected repository version, downloads its files, installs them, and reports the result. A successful configuration write therefore does not establish that installation succeeded. Check the reported version and device health to confirm the outcome. Update Model explains this approach in detail.

Deploying an Update to a Device

A package groups releases of the same system. A version contains the files and metadata for one release; a tag is a name that resolves to a version. Tracking a floating tag such as stable follows new versions when that tag is reassigned. Pinning selects one version until you change the configuration. Use a channel when devices should follow promotions, and pin a version when you need to hold a device at a particular release.

1. Open a device that reports the dev.nexigon.ota.status property.
2. Choose Configure Updates in the device header.
3. If the device reports no package, choose one under Update Package. The list contains the packages of the repositories linked to the device’s project.
4. Under Release, enter the tag to follow or search for the version to pin. The tag field suggests the package’s tags and the version each one points to. The version search matches version names, IDs, and tags. Choose Follow or Pin.
5. Monitor the device’s update status.

Once the device reports the chosen package, the panel offers the releases of that package. To choose another package, choose Use Default Release and wait for the device’s next update check.

The panel writes dev.nexigon.ota.config and requests an immediate check through nexigon.ota.check when that command is available.

Configuring Updates for a Device Profile

A device profile sets property values on all devices that apply it, including dev.nexigon.ota.config. To configure the updates of these devices in one place:

1. Open the profile under Project Settings → Profiles.
2. Open its System Updates page and choose Configure System Updates.
3. Choose the settings the profile should set, for example a tag to follow or a version to pin, and choose Save Settings.

Saving creates a new revision of the profile. A setting that the profile leaves at Not set by this profile comes from the device’s other profiles or from the defaults built into its image. A value that a device sets itself takes precedence over its profiles.

Change the Update Channel with Nexigon CLI

For example, set a per-device override from a configured workstation:

nexigon-cli devices properties set --protected=true <device-id> dev.nexigon.ota.config \
  '{"path": "my-repo/my-package/beta"}'

The path has the format <repository>/<package>/<version>, where <version> is a tag or a version ID. In this example, the device follows the beta channel of my-repo/my-package. The protected property keeps the operator’s selection separate from the status that the device reports. The updater reads it on its next check.

To restore the defaults built into the image, remove the override:

nexigon-cli devices properties remove <device-id> dev.nexigon.ota.config

Control When a Device Updates

Configure Updates also controls when the device installs updates. Each setting is part of dev.nexigon.ota.config:

• Hold Updates keeps the device on its current version until you resume updates. An update already in progress completes.
• Maintenance Window restricts updates to time ranges in the device’s local time.
• Retries limits failed attempts and sets the delays between them.
• Spread delays updates by the device’s position in a spread. Devices that share a spread update one after another over its period, or only up to its share of devices.

The panel offers only the settings that the device’s integration supports and names the others. Windows and Retries and Spread describe the behavior in detail.

Staged Rollouts

For a rollout with per-device progress and advancement guards, use Run a Fleet Operation. A property-driven update operation sets dev.nexigon.ota.config and waits for dev.nexigon.ota.status.currentVersion to report the expected build. Pin a version ID in the configured path, so that each stage only updates the devices it reaches. See Rollouts.

A canary channel lets a small group exercise a release before the rest of the fleet follows it. Promoting a tag changes what devices resolve on their next check; it does not require rebuilding or uploading the same release again.

For example, a simple channel-based rollout is:

1. Publish a release and tag it canary.

2. Point test devices at that tag with per-device overrides.

3. Check update status, device events, and application health.

4. Reassign stable to the tested version:

   nexigon-cli repositories versions tag <version-id> --tag stable,reassign

Devices tracking stable pick up the version on their next check.

Monitoring Update Progress

The device header shows the reported firmware version and update state. During an update, inspect the target version and state, such as installing or rebooting. After reboot, confirm the expected installed version and device health.

On failure, inspect the error in the status badge and the device’s event log. Configure Updates shows the failure count and the next attempt. When the integration reports it, it also shows the update system with its version and slots, including the slot that the device boots next and whether the running system awaits its commit. Retry Update resets the failure count and requests a check when the check command is available. Events include structured version and error data; dedicated instances can also use OTLP export.

Troubleshooting