System Updates

This guide walks you through deploying, managing, and monitoring over-the-air (OTA) updates on your devices.

Under the hood, OTA updates are built from the same primitives that power the rest of the platform. Device properties carry configuration and status, repositories store versioned artifacts, and events provide observability. A script on the device composes these primitives into the update lifecycle. This works with Rugix, RAUC, SWUpdate, or any custom update mechanism. For convenience, we provide ready-made integrations with Rugix and RAUC.

Ready-Made Integrations

For Yocto, we provide meta-nexigon with Yocto layers for both Rugix (meta-nexigon-rugix) and RAUC (meta-nexigon-rauc). See the Kas example configurations for reference setups.

For Rugix Bakery, we provide the nexigon-rugix repository with ready-made Rugix Bakery recipes. See OTA System Updates with Rugix for setup instructions.

How OTA Updates Work

Primitive	Name	Purpose
Configuration	dev.nexigon.ota.config property	Where to look for updates (repository path)
Status	dev.nexigon.ota.status property	Installed version, update state, and errors
Trigger	nexigon.ota.check command	Forces an immediate update check
Artifacts	Nexigon repositories	Versioned storage for update bundles

Because the entire workflow is expressed through properties, events, and repositories, you can observe, override, and extend it without fighting a framework. The configuration is a JSON value you can set per device. The status is a JSON value you can query across your fleet. The events flow into the same telemetry pipeline as everything else.

For the full specification of the update properties, see the System Updates reference.

Per-Device Configuration

Each device can be individually configured to track a different update channel or pin to a specific release. This is done by setting the dev.nexigon.ota.config property on the device, either through the UI or the CLI:

# Point a device at a different channel.
nexigon-cli devices properties set <device-id> dev.nexigon.ota.config \
  '{"path": "my-repo/my-package/beta"}'

# Reset to the defaults baked into the image.
nexigon-cli devices properties remove <device-id> dev.nexigon.ota.config

The path field is a version path in the format <repository>/<package>/<version-tag>. When the property is removed, the update script falls back to the defaults configured during image build.

Deploying an Update to a Device

When a device has OTA updates configured (exposes the status property), the Nexigon UI shows a Deploy Update button. Clicking it opens a dialog where you can:

• Track a version tag (e.g., stable, beta, v2.0). The device automatically updates wherever the tag moves.
• Pin to a specific version. The device stays on that exact version until you change it.

Under the hood, the dialog simply sets the OTA update configuration property to the selected tag/version and then triggers an immediate check via the nexigon.ota.check command (if available).

Staged Rollouts

You can use version tags to implement staged rollouts:

1. Build and upload your release to the repository.
2. Tag it as canary and point a few test devices at the canary channel via per-device config overrides.
3. Monitor the test devices in the UI. Check their update status, events, and health.
4. Promote to stable by reassigning the stable tag to the new version.
5. All devices tracking stable update automatically.

# Promote the canary version to stable.
nexigon-cli repositories versions tag <version-id> --tag stable,reassign

Monitoring Update Progress

The device header shows the current firmware version, update state, and any errors at a glance. When an update is in progress, you will see the target version and a state badge (e.g., "installing", "rebooting").

If an update fails, the UI shows:

• The failure count (e.g., "failed (3x)")
• The error message (hover over the badge for details)
• A Retry Update button to trigger an immediate retry

Update events are recorded in the device's event log, providing a full audit trail with structured attributes (current version, target version, error details). These events can be routed to your existing observability stack via OTLP export.

Troubleshooting

Device doesn't pick up the new version. Check that the device is online and the OTA service is running. Verify the version tag exists in the repository. Use the "Check Now" button to force an immediate check.

Update keeps failing. Check the error message in the status badge. Common causes: insufficient disk space, network issues downloading the bundle, or a missing/invalid bundle signature. The device's event log has detailed error information.

Device is stuck in "installing" or "rebooting". This can happen if the device lost power during an update. On the next boot, the script should detect the inconsistency and either commit the new version or report a failure. If the device doesn't recover, connect via remote terminal to investigate.