Set Up Rugix OTA Updates

Install the Nexigon OTA integration in a Rugix image and prepare the release tooling for publishing update bundles. The device-side script installs bundles with Rugix Ctrl and reports progress through system update properties.

The integration combines Nexigon repositories for update bundles, properties for desired configuration and reported state, and events for update history. Rugix Ctrl provides bundle installation and boot-group management; the script coordinates checks, installation, and commit handling. You can adapt that policy for your device while keeping the shared Nexigon property protocol.

You need a Rugix build project with Nexigon Agent configured and a Nexigon repository for releases. Follow Getting Started with Rugix if the image does not yet include Nexigon Agent.

Two packaging options are available depending on your build system:

• Rugix Bakery: The nexigon-rugix repository provides ready-made Rugix recipes.
• Yocto: The meta-nexigon repository provides Yocto layers, including meta-nexigon-rugix for Rugix-based systems and meta-nexigon-rauc for RAUC-based systems.

Setup with Rugix Bakery

Add the Nexigon repository to your rugix-bakery.toml:

[repositories]
nexigon = { git = "https://github.com/nexigon/nexigon-rugix.git", branch = "v0.3" }

Then add the nexigon/nexigon-rugix-ota recipe to your layer alongside the agent recipes:

recipes = [
    # ...
    "nexigon/nexigon-agent",
    "nexigon/nexigon-agent-config",
    "nexigon/nexigon-rugix-ota",
    "nexigon/nexigon-rugix-watchdog",
]

The nexigon-rugix-watchdog recipe reboots the device if the system has not been committed within a timeout (default: 30 minutes), allowing it to roll back to the previous version.

The OTA recipe can read a default repository path from the .env file in your project directory. For example:

NEXIGON_HUB_URL="https://eu.nexigon.cloud"
NEXIGON_TOKEN="deployment_..."
NEXIGON_REPOSITORY="my-repo"
NEXIGON_PACKAGE="my-package"

NEXIGON_REPOSITORY and NEXIGON_PACKAGE are optional, but must be set together. When both are omitted, the OTA service remains idle until dev.nexigon.ota.config supplies a path. This is useful for generic images that are paired and assigned an update channel after flashing. An OTA check also exits cleanly while the Nexigon Agent is still unpaired.

It supports the following parameters:

The Nexigon template for Rugix Bakery provides a complete project setup with OTA updates, release scripts, and CI integration included.

Setup with Yocto

Add the meta-nexigon-rugix layer to your build. The layer depends on meta-nexigon-core, which provides the Nexigon Agent recipes.

Include the OTA recipe in your image:

IMAGE_INSTALL:append = " nexigon-rugix-ota"

The OTA configuration is baked into the image through BitBake variables. See the Kas example configurations for reference setups with both Rugix and RAUC.

Update Lifecycle

The OTA integration runs as a systemd timer that triggers a check on boot and periodically thereafter. On each cycle, the script:

1. Reads configuration. Checks dev.nexigon.ota.config for per-device overrides. If no override is set, falls back to the defaults baked into the image.
2. Checks boot state. If the active boot group differs from the default, the script commits the system to confirm that the previous update booted successfully. If the current version does not match the expected target, it records a rollback failure.
3. Resolves the target version. Queries version info from the configured repository path to determine the target version.
4. Compares versions. If the target version matches the installed version, there is nothing to do.
5. Installs the update. Downloads the Rugix bundle and installs it via rugix-ctrl update install.
6. Reboots. Reboots into the new version via rugix-ctrl system reboot --spare.

Every state transition is published through the dev.nexigon.ota.status property and emitted as a structured event under the ota category. This gives you real-time status in the Nexigon UI and a history of update events in the event log.

The update script provides the implementation for adapting this lifecycle.

Configuration

For Rugix Bakery, the .env variables NEXIGON_REPOSITORY and NEXIGON_PACKAGE combine with the tag recipe parameter (default: stable) to form the default update path baked into the image. The example above produces my-repo/my-package/stable.

This path is the image’s default update channel. The device property dev.nexigon.ota.config can override it without rebuilding the image. Removing the override restores the built-in default. Follow Deploy System Updates for the deployment procedure.

Bundle Verification

Rugix Ctrl verifies bundles before installation. The integration supports these verification inputs:

• Cryptographic signature: Rugix Ctrl’s normal verification applies when no metadata hash is used. This is recommended for production deployments.
• Hash-based verification: With use_bundle_hash enabled, the script passes rugix.bundleHash from the asset metadata to Rugix Ctrl when present. When it is absent, verification falls back to the bundle signature.

The verification mode is set locally in the image and cannot be disabled with the cloud-provided OTA configuration. Hash verification ensures that the downloaded bundle matches metadata received through the authenticated Nexigon connection, but it is not an independent publisher signature. A party that can replace both the asset and its metadata remains trusted. Configure Rugix bundle signing and a device trust root for production publisher authentication.

Release Workflow

The Nexigon template for Rugix Bakery provides release scripts. For example, in a project based on the template:

./scripts/prepare-release.sh                      # Generate version, create in Nexigon Hub
./scripts/build-release.sh customized-efi-amd64   # Build with pinned version
./scripts/upload-release.sh                       # Upload artifacts with metadata

The prepare-release.sh script generates a version identifier (e.g., build-20260401120000-abc1234), creates the version in the Nexigon repository, and writes a .release-env file that pins the version for subsequent steps. This ensures the version baked into the image matches the version uploaded to the repository.

When adapting the scripts, preserve the release contract: the package version’s metadata.imageVersion identifies the version baked into the image, and each bundle is attached as <system-name>.rugixb. The updater selects the bundle for its system name and compares the image version with its installed version. The package version’s display name and a floating channel tag serve different purposes and do not replace that image-version metadata.

Asset Metadata

The upload script attaches metadata to bundle assets:

{
  "rugix": {
    "bundleHash": "sha512-256:..."
  },
  "relations": {
    "sbom": ["customized-efi-amd64.spdx.json"]
  }
}

• rugix.bundleHash: Passed to Rugix Ctrl when use_bundle_hash is enabled. Without a metadata hash, Rugix Ctrl uses its normal signature verification.
• relations.sbom: Links the bundle to its SBOM for traceability in the UI.

CI Integration

The template includes a GitHub Actions workflow that runs the same scripts. The prepare-release job creates the version and uploads .release-env as a GitHub Actions artifact. Parallel build jobs download it, build each system variant, and upload the results.

Verify the Setup

Build and boot the configured image. Once Nexigon Agent is connected, run this command as root on the device:

systemctl is-active nexigon-rugix-ota.timer

The command should print active. After the timer’s first check, confirm that the device reports dev.nexigon.ota.status in Nexigon, with the installed image version in currentVersion and the effective configuration in config.

If the property is missing, confirm that Nexigon Agent is paired and inspect the update service’s log:

journalctl -u nexigon-rugix-ota.service -b

Once the device is connected and a release is published, follow Deploy System Updates to select a version or channel, roll out the release, and monitor progress.