Update system (Hive-M)

Two layers: a RAUC bundle for the rootfs, wrapped in a uwm update archive that also carries boot artifacts.

RAUC bundle

recipes-core/bundles/update-bundle.bb: verity-format bundle, single slot rootfs = aionyx-image-minimal squashfs, signed with the RAUC key/cert from the layer (ntl-20260629.*). Output: update-bundle-ntl-hive-m.raucb.

Update archive

recipes-core/bundles/update-archive.bb packages the components in UPDATE_COMPONENTS plus a manifest.json into a flat hive-m-update-<version>.tar.gz applied by uwm.

Default set: raucb kernel dtb bootscr bootbin; with SECURE_BOOT=1: raucb fitimage bootscr bootbin. Overridable per build via build update --include/--select (passed through as UPDATE_COMPONENTS).

Custom bitstream / DT overlay

build update --bitstream <file.bit|.bin> [--dtbo <file.dtso|.dtbo>] (or select the bitstream/dtbo component via --include/--select without the flag — a file-picker dialog opens) stages the files into images/update-fw/ (mounted at /images/update-fw); recipes-core/bundles/update-firmware.bb deploys them, compiling a .dtso with dtc (no -@, see sources/overlay/fpga-overlay.dtso). Both components map into /data/firmware/import/, where uwm's import_staged_boot_bitstream() picks them up on next start: validates, inserts as the boot bitstream (previous boot flag cleared by DB trigger), programs the FPGA; files are deleted only after a successful import.

Constraints (uwm side): one bitstream + one overlay per archive; an overlay without a bitstream is skipped (buildhive rejects --dtbo alone); shutdownReason must not be bitstreamUpdate (default systemReboot is correct — bitstreamUpdate programs the FPGA at shutdown before the import ran and skips cold-boot programming).

manifest.json: version, buildDate, fileMappings, optional minRequiredVersion, shutdownReason.

Version: UPDATE_VERSION defaults to BUILDHIVE_VERSION, which the init script exports from the tool version (src/constants.py). Manual bitbake outside buildhive falls back to 0.0.0.

Signing

The uwm updater only installs signed archives. build update signs automatically unless --no-sign; --sign-only signs an existing archive.

Flow (src/signing.py):

1. Requires BUILDSIGN_TOKEN (env var, else secrets server, see configuration.md) and NTL VPN reachability to the buildsign.url server.
2. SHA-256 of the archive is computed locally and POSTed to /signing-requests - the artifact itself is never uploaded. Payload: hash, filename, version, size, comment, pinned public key (server refuses other key material).
3. Polls every 10 s until signed / rejected (exit 2) / timeout (default 3600 s, exit 3).
4. Signature (Ed25519, 64 bytes) is verified locally against the pinned sw.buildsign.public_key over "UWM-UPDATE-v1" + sha256. No pinned key: verification skipped with a warning.
5. Output: images/signed_hive-m-update-<version>.bin = 64-byte signature followed by the raw tar.gz.

Legacy migration (0.3.9 → RAUC layout)

build update --legacy-migration builds hive-m-migration-<version>.tar.gz via recipes-core/migration/legacy-migration-update.bb - an archive in the old uwm format (unsigned) containing: new Image, system.dtb, BOOT.bin, RAUC boot.scr, a migration boot script, the migration initramfs, the rootfs squashfs, a migration.sha256 manifest.

Sequence on device:

1. Old uwm-loader writes the mapped files to /boot, reboots.
2. Migration boot.scr boots the migration initramfs (migration-image.bb: RAM-only cpio with migration-init, sfdisk, mke2fs, dosfstools).
3. Initramfs repartitions the SD card into the RAUC layout (hive-m.md), installs slot A, reboots into the new system.

MIGRATION_VERSION defaults to BUILDHIVE_VERSION like UPDATE_VERSION.