BuildHive

CLI tool for building and managing Linux systems on NTL hardware. All builds run in Docker containers; build state persists in named Docker volumes.

Documentation

• Command reference - every command, flag, prerequisite
• GUI - pages, what each button runs, settings location
• Project configuration - project.json schema
• Hive-S internals - HW/SW/flash build flow
• Hive-M internals - Yocto flow, kernel development
• Update system - RAUC bundles, update archives, signing, legacy migration
• Secure boot - key generation, boot chain, eFUSE provisioning
• Development - repo layout, release process, template update mechanism

Installation

Windows

Run BuildHive_<x.y.z>_Setup.exe from the newest buildhive_v<x.y.z> release. Installs per user, optionally adds buildhive to PATH. Later versions: buildhive upgrade or the update button in the GUI.

Requirements

• Docker running (WSL backend on Windows) - required by almost every command
• Vivado on PATH - Hive-S only (build hw, deploy flash)
• VS Code with code CLI on PATH - only for buildhive code
• Company SSO account - build secrets (BUILDSIGN_TOKEN, SSTATE_MIRROR_AUTH) come from the secrets server (secrets in project.json), browser login on first use; env vars of the same name override
• NTL VPN - only for signing update archives

Command names accept unique prefixes: buildhive dep fl = buildhive deploy flash.

Hive-S quickstart

[!IMPORTANT] Requires AMD/Xilinx Vivado in your PATH.

buildhive create -n PROJECT_NAME -t hive-s
cd PROJECT_NAME

buildhive build hw          # generate SoC + IP cores (output: ip/)
# generate bitstream in Vivado, then:
buildhive configure bitstream -f PATH_TO_BITSTREAM   # copies to images/bitstream.bin

buildhive build sw          # UWM + Buildroot (kernel, rootfs, u-boot, opensbi)
buildhive build flash       # assemble images/flash.bin
buildhive deploy flash      # program SPI flash via Vivado/JTAG (device connected)

If multiple devices are connected, you are prompted to select one.

Hive-M quickstart

buildhive create -n PROJECT_NAME -t hive-m
cd PROJECT_NAME

# optional: replace hardware description
buildhive configure xsa -f PATH_TO_XSA          # extracts .bit from XSA
buildhive configure bitstream -f PATH_TO_BIT    # or supply .bit directly
buildhive configure dts -f PATH_TO_DTSI         # custom device tree include

# optional: kernel / u-boot menuconfig
buildhive configure linux
buildhive configure uboot

buildhive build sw          # bitbake aionyx-image-minimal -> images/sd.wic
buildhive build update      # update archive + RAUC bundle, signed -> images/

Kernel development (Hive-M)

Fast out-of-tree module and kernel builds without full bitbake runs:

buildhive build kernel-devsrc        # export kernel source + toolchain to Docker volume (once)

buildhive build module ntl_tsu       # build one NTL driver out-of-tree -> oot/ntl_tsu/*.ko
buildhive build module ntl_tsu --clean

buildhive build kernel-oot           # rebuild kernel Image without bitbake -> images/Image
buildhive build kernel-oot --clean

buildhive shell                      # interactive shell in build container
buildhive shell --module ntl_tsu     # shell with kernel env, cd oot/ntl_tsu

buildhive code                       # VS Code attached to dev container
buildhive code --stop

Dev container mounts: /kernel-devsrc (kernel source + build tree, case-sensitive volume), /oot (host oot/), /drivers (host sources/drivers/).

Command reference

Commands are resolved against the project in the current working directory (project.json, not searched upward). Without a project, only the common commands exist. With one, the template field selects the Hive-S or Hive-M command set.

Any command segment may be abbreviated to a unique prefix (buildhive dep fl = buildhive deploy flash). Exact matches win over prefixes; ambiguous prefixes error.

Overview

Common commands

buildhive create

Creates ./<name>/: copies the default template, then the chosen template, writes project.json, hash manifest (.buildhive_manifest.json) and merge baseline (.buildhive_baseline/). Fails if the directory already contains a project.

buildhive gui

Launches the desktop GUI (PySide6); running the exe without arguments does the same. Pages, button-to-command mapping and settings location: gui.md.

buildhive login / buildhive logout

login: OIDC login to the secrets server from project.json secrets.url (see configuration.md). Opens the browser (company SSO), waits for the callback on http://localhost:8250/oidc/callback, caches the OpenBao token in the OS config dir (token.json, plain text, next to gui.json). Builds log in on demand when a secret is needed and no valid token is cached, so an explicit login is only needed to switch users. logout: deletes the cached token. BAO_TOKEN env (CI machine token) bypasses both.

buildhive upgrade

Looks up the newest buildhive_v<x.y.z> release in NetTimeLogic/Tools (draft and pre-release skipped). The repo is private: the GitHub token comes from GITHUB_TOKEN env or the secrets server (buildhive/github, key GITHUB_TOKEN; browser login if no token is cached, no project needed). Newer release: downloads BuildHive_<x.y.z>_Setup.exe to the temp dir and starts it two seconds after the CLI exits, so the installer can replace bin/. The installer removes the old version and installs per user, no admin. Up to date: OK: BuildHive x.y.z is up to date. Linux/macOS: prints the releases page. Exit 1 on token, network or download errors. The GUI has the same check at start plus an update button, see gui.md.

buildhive info secrets

Prints the secrets server, the logged-in email and, per secret (SSTATE_MIRROR_AUTH, BUILDSIGN_TOKEN), the source a build would use: environment variable, <mount>/users/<email>/<secret>, <mount>/<secret> or not available (<reason>). Never prints values, never opens the browser.

buildhive info project

Prints name, ID, BuildHive version, template. Hive-S: Buildroot repo/branch. Hive-M: Yocto manifest repo/branch and additional clone repos.

buildhive configure project

Hive-S commands

buildhive build hw

Generates the LiteX/VexRiscv SoC in the HW container (make.py <hw.args>), rewrites the generated Vivado tcl to host paths, runs vivado -mode batch to build IP, copies the IP repo to ip/.

buildhive build sw

Clones and builds UWM (out/hive-s_full_tls → images/uwm.xz, uwm-loader into the rootfs overlay), then Buildroot (ntl_defconfig) → kernel Image.lzma, rootfs.cpio.xz, u-boot.bin, opensbi.bin in images/.

buildhive build flash

No Docker. Wraps each flash mapping entry with a length+CRC32 header (.fbi), builds mapping_table.bin, assembles images/flash.bin (bitstream at offset 0, components at their src offsets, mapping table at 0x3F0000). See hive-s.md.

buildhive info flash

Prints the flash mapping table and image structure (offsets/sizes from .fbi files in images/).

buildhive configure linux / configure buildroot

Interactive make linux-menuconfig / make menuconfig inside the SW container.

buildhive configure bitstream

buildhive deploy flash

Runs vivado -mode gui -source tools/flash_device.tcl to program the SPI flash over JTAG. Requires Vivado on PATH and a connected device.

buildhive clean

Removes and recreates the HW and SW Docker volumes. Fails if a container is using them.

Hive-M commands

All container-based Hive-M commands run an init script first: repo init/sync of the Yocto manifests (first run), source edf-init-build-env, layer sync, machine generation from the SDT, copy of sw/meta-ntl-hive into the build tree, secure-boot config toggle. Repos from sw.clone are pulled in parallel unless --no-update is given. See hive-m.md.

buildhive build sw

bitbake aionyx-image-minimal → images/sd.wic.

buildhive build kernel

bitbake linux-xlnx → images/Image.

buildhive build kernel-devsrc

Builds linux-xlnx, resolves source/build paths via bitbake -e, copies kernel source, build artifacts and .config into the case-sensitive kdevsrc Docker volume, writes env.sh (ARCH, CROSS_COMPILE, toolchain PATH). Prerequisite for kernel-oot, module, shell --module, code.

buildhive build kernel-oot

Rebuilds the kernel Image directly from /kernel-devsrc (make -j Image modules), no bitbake → images/Image.

buildhive build module <name>

Scaffolds oot/<name>/Makefile if absent, cross-compiles the module against /kernel-devsrc → oot/<name>/*.ko.

buildhive build update

Selecting the bitstream/dtbo component (via --include/--select) without the matching flag opens a file-picker dialog instead; conversely, a given flag adds its component to the selection automatically.

bitbake update-archive → images/update.raucb + images/hive-m-update-<version>.tar.gz, then remote-signs the archive → images/signed_hive-m-update-<version>.bin. See updates.md.

buildhive export sw

bitbake aionyx-image-minimal -c populate_sdk - builds the cross SDK and copies the installer (*.sh) plus Image to images/.

See hive-m.md for the image layout and usage.

buildhive configure xsa

buildhive configure bitstream

buildhive configure dts

buildhive configure linux / configure uboot

Interactive bitbake virtual/kernel|virtual/bootloader -c menuconfig; the resulting diffconfig fragment is saved as a timestamped user_*.cfg in meta-ntl-hive so it persists across builds.

buildhive packages list / add <name>... / remove <name>...

Edit IMAGE_INSTALL:append in sw/meta-ntl-hive/conf/layer.conf. Names: lowercase letters, digits, + . _ -. The block is rewritten in the template layout, the rest of the file is untouched, so info project updates still 3-way merge it. Applied on the next build sw.

buildhive packages index

Scans every .bb under /work/sources in the SW container (name, layer, SUMMARY, DESCRIPTION, SECTION, RDEPENDS, fields also taken from required .inc files) and writes build/recipe-index.json. Host-only recipes are skipped: *-native, *-cross*, nativesdk-* and anything inheriting native, nativesdk, cross, crosssdk, cross-canadian, image, core-image. Re-run after changing the Yocto manifest.

buildhive packages search [term]

Case-insensitive search over the index, ranked: exact name, term as a whole word in RDEPENDS (gcc lists packagegroup-core-buildessential right after gcc), name prefix, whole word in summary/description, substrings. Lists recipes, not split runtime packages. The GUI Configure page has the same list/search under "Image packages".

buildhive secure-boot keygen

Generates keys/ (gitignored): psk.pem, ssk.pem (RSA-4096, BOOT.bin auth), fit.key/fit.crt (RSA-2048, FIT signing). See secure-boot.md.

buildhive secure-boot ppk-hash

Runs bootgen -efuseppkbits against the deployed FSBL → images/ppk0_hash.txt for eFUSE provisioning. Requires keys and a prior build sw.

buildhive shell

Interactive bash in the SW container with the Yocto environment sourced.

buildhive code

Starts a detached dev container (/kernel-devsrc, oot/, sources/drivers/ mounted) and attaches VS Code to it. Requires the code CLI on PATH.

buildhive clean

Removes and recreates the project SW volume.

GUI

PySide6 desktop front end for the CLI. Same features as the command line except the interactive targets (configure linux|uboot|buildroot, shell, code), plus recipe search and in-place project updates.

Starting

The most recently opened project opens at start. Docker Desktop is needed for builds, indexing and create, not for opening the GUI, editing packages or updating a project.

Window

Output panel

Every button that runs a command spawns buildhive <command> in the project directory and streams its output line by line into the panel. The line $ buildhive ... marks the start.

One command at a time. While one runs, the Project, Configure and Build & Deploy pages are disabled; Settings stays usable. Closing the window stops a running command first.

Project

Project update

Opening a project whose buildhive_version is older than the tool opens a dialog. Cancel keeps the project closed. Yes runs the template update in the GUI (no terminal), the same merge the CLI does on the next command in the project directory.

Finish update is enabled once no file contains merge markers. Resolve the markers in an editor, then Re-check. Finish writes the tool version into project.json and adds sections newer templates need. Cancel after a merge leaves the merged files in place, the version stays old and the dialog appears again on the next open.

A project created by a newer BuildHive than the installed one is refused with a message to update BuildHive.

Configure

hive-m

Boot bitstream and device tree. Inputs for Build SW image. The bitstream ends up in BOOT.bin and the SD image, so this is what a device boots from the card.

Browse fills the field, Apply runs the command. For a device already in the field use the Update archive on Build & Deploy instead, which imports the bitstream at runtime.

Image packages. Edits IMAGE_INSTALL:append in sw/meta-ntl-hive/conf/layer.conf directly, no command. Applied on the next Build SW image. Same file as buildhive packages, see commands.md.

The index lists recipes, not the split runtime packages a recipe produces (gcc is listed, gcc-symlinks is not). Host-only recipes (-native, -cross, nativesdk-, images) are excluded.

Kernel, U-Boot and Buildroot menuconfig are terminal-only: buildhive configure linux | uboot | buildroot.

hive-s

Bitstream: configure bitstream -f <file>, copied into the project and used by Build flash image.

Build & Deploy

Builds run with -v so the container output shows in the panel. Output files land in images/.

hive-m

Build

Update archive. Builds images/update.raucb from the last Build SW image for devices in the field, see updates.md.

Signing needs the buildsign token from the secrets server or from Settings.

hive-s

Clean artifacts

buildhive clean after confirmation. Deletes the Docker build volumes, so the next build starts from scratch. Sources, images/ and the sstate cache stay (clean --all for the sstate cache is CLI-only).

Settings

BuildHive updates

Releases: NetTimeLogic/Tools, tags buildhive_v<x.y.z>, asset BuildHive_<x.y.z>_Setup.exe. The repo is private, so the GUI reads a GitHub token with Contents: read from the secrets server (buildhive/github, key GITHUB_TOKEN; GITHUB_TOKEN in the environment overrides it).

Same from a terminal: buildhive upgrade (commands.md).

Settings file: gui.json in the OS config dir, %LOCALAPPDATA%\buildhive\ on Windows, ~/.config/buildhive/ on Linux. Plain text: the credential overrides and the recent project list.

Troubleshooting

Implementation

buildhive.spec produces two exes from one analysis: buildhive.exe (console) and buildhive-gui.exe (console=False). Both run main.py; without arguments it starts the GUI, which spawns the console exe for commands. The windowed exe has no stdout or stderr, so nothing on the GUI path may exit on a failed print or on a missing Docker daemon: state.connect() runs only on the CLI path, stop_container() is a no-op without a connection.

Project configuration

Files in the project root

project.json is loaded from the current working directory only (no upward search). A directory counts as a project if project.json exists, parses as a JSON object and has a name key. Optional fields with value null are omitted on save (exclude_none).

Common fields (both templates)

Git object used below: { "url": string, "branch": string }.

Hive-S schema

{
    "name": "...",
    "template": "hive-s",
    "sw": {
        "buildroot": { "url": "...", "branch": "..." },
        "uwm":       { "url": "...", "branch": "..." }
    },
    "hw": {
        "args": "--cpu-count=1 --with-rvc",
        "debug_args": "--ntl-debug --with-privileged-debug --hardware-breakpoints 4"
    },
    "flash": {
        "opensbi.bin": { "src": "0x...", "dst": "0x..." }
    }
}

Hive-M schema

{
    "name": "...",
    "template": "hive-m",
    "secrets": {
        "url": "https://secrets.ntl.dev",
        "role": "dev"
    },
    "sw": {
        "yocto_manifests": { "url": "...", "branch": "..." },
        "clone": {
            "uwm":     { "url": "...", "branch": "master" },
            "udm":     { "url": "...", "branch": "master" },
            "drivers": { "url": "...", "branch": "master" }
        },
        "buildsign": {
            "url": "https://sign.ntl.dev/api",
            "public_key": "<base64 Ed25519 key>"
        },
        "secure_boot": false,
        "sstate_mirror": {
            "url": "https://sstate.ntl.dev",
            "hashserv": "wss://hashserv.ntl.dev"
        }
    }
}

Constants

Hive-S internals

LiteX/VexRiscv RISC-V soft-SoC on Artix-7. Buildroot rootfs, UWM firmware, single SPI flash image.

Project layout

Docker volumes: ntl_buildhive_hw_<name>_<id> and ntl_buildhive_sw_<name>_<id>. Host mounts: images/, hw/ (ro, HW container), buildroot/ (ro, SW container).

build hw

1. HW container: pulls LiteX + VexRiscv sources, runs ./make.py <hw.args> - generates gateware sources and the device tree (rv32.dtb).
2. Rewrites paths in the generated aionyx_hive_s.tcl from container to host paths.
3. Host: vivado -mode batch -source aionyx_hive_s.tcl builds the IP cores, copied to ip/.

Bitstream generation itself is manual in Vivado; import the result with buildhive configure bitstream -f <file> (→ images/bitstream.bin).

build sw

SW container, two stages:

1. UWM - clone sw.uwm into sources/uwm, make out/hive-s_full_tls → images/uwm.xz + uwm-loader; loader also copied into buildroot/rootfs_overlay/opt/ntl.
2. Buildroot - clone sw.buildroot, make ntl_defconfig (BR2_EXTERNAL=/buildroot), make -j → images/: Image.lzma, rootfs.cpio.xz, u-boot.bin, u-boot.dtb, opensbi.bin, rv32.dtb.

Flash image

build flash runs on the host, no Docker:

• Each flash mapping entry is wrapped as .fbi: 4-byte length + 4-byte CRC32 + data.
• mapping_table.bin holds the sorted (src, dst) address pairs.
• images/flash.bin layout: bitstream at offset 0, each component at src − 0x01000000, mapping table at 0x3F0000.

At boot the SoC firmware walks the mapping table and copies each blob from its flash src to its RAM dst. Entries without dst (e.g. uwm.xz) stay in flash. info flash prints the table and the assembled layout.

deploy flash

vivado -mode gui -source tools/flash_device.tcl - programs the SPI flash over JTAG. Prompts for device selection if several are connected.

Hive-M internals

Xilinx ZynqMP, Yocto build (aionyx-image-minimal), RAUC A/B rootfs, uwm updater.

Project layout

Docker volumes

Bind mounts: sw/ → /sw (ro), sources/sdt → /custom_sources/sdt, keys/ → /keys (ro, if present), each clone repo → /custom_sources/<name>.

Init script

Prepended to every containerized hive-m command:

1. Exports BUILDHIVE_VERSION (tool version) via BB_ENV_PASSTHROUGH_ADDITIONS - default version for update/migration archives.
2. First run: repo init -u <yocto_manifests.url> -b <branch>, repo sync.
3. source edf-init-build-env.
4. Reconciles conf/bblayers.conf with layers on disk (removes stale, adds missing).
5. First run only: sets SSTATE_DIR/DL_DIR in local.conf, runs gen-machine-conf parse-sdt --hw-description /custom_sources/sdt --machine-name zynqmp-ntl-hive-m-sdt, creates+adds meta-ntl-hive, sets MACHINE ??= ntl-hive-m.
6. Every run: re-copies /sw/meta-ntl-hive/* into ../sources/meta-ntl-hive/ - layer edits in the project take effect on the next build.
7. Adds/removes the secure-boot.conf require line in local.conf per sw.secure_boot.
8. Rewrites the # >>> buildhive sstate mirror block in local.conf per sw.sstate_mirror; credentials from SSTATE_MIRROR_AUTH env or the secrets server, written to ~/.netrc. Mirror misses fall back to the local ntl_buildhive_sstate cache and a normal build.
9. Rewrites the # >>> buildhive rm_work block: INHERIT += "rm_work" with RM_WORK_EXCLUDE += "linux-xlnx aionyx-image-minimal". Work dirs are deleted after packaging (tmp/ shrinks several times), so devshell/tmp/work inspection only works for the excluded recipes; kernel-devsrc and export sdk (busybox from the image rootfs/) keep working. Existing projects reclaim space on the next build.

Repos in sw.clone are pulled in parallel before the container starts; --no-update skips this.

meta-ntl-hive layer

conf/layer.conf: priority 7, compatible scarthgap, depends on aionyx-hive. IMAGE_INSTALL:append adds extra packages to the image (template: ptp4l-config); edit with buildhive packages add|remove or the GUI Configure page, see commands.md.

conf/machine/ntl-hive-m.conf requires the SDT-generated machine and backs /etc, /opt/ntl, /usr/lib/firmware overlays with /data.

Serial console lock

recipes-bsp/u-boot/u-boot-xlnx/console.cfg + patch 0002-configs-zynqmp-restrict-stored-env-*. Contract consumed by uwm (docs/src/security/serial-console.md in the uwm repo).

FSBL, PMUFW, ATF and U-Boot still print on UART0. Output only, no input path. JTAG not covered.

New password:

SALT=$(openssl rand -hex 4); printf '%s%s' "$SALT" "$PASSWORD" | sha256sum | awk -v s="$SALT" '{print s":"$1}'

Put the result in CONFIG_AUTOBOOT_STOP_STR_SHA256, rebuild u-boot. At the prompt type the password (no echo) during the delay.

SDK image

export sw --image wraps the populate_sdk installer into a standalone container for application developers: no Yocto tree, no buildhive.

Build context is a temp dir under images/ holding only sdk/ and the installer (hardlinked when possible), so the wic files never reach the docker daemon. aionyx-image-minimal.bbappend sets TOOLCHAIN_HOST_TASK (+nativesdk-cmake/ninja/pkgconfig, makes the env script export CMAKE_TOOLCHAIN_FILE), TOOLCHAIN_TARGET_TASK (+kernel-devsrc) and SDKIMAGE_FEATURES = "dev-pkgs" (no dbg-pkgs/src-pkgs, ~1 GB less).

Kernel module: make -C $SDKTARGETSYSROOT/usr/src/kernel M=$PWD modules, see /opt/ntl-sdk/examples/hello-module. Module vermagic matches the kernel of the build the SDK came from; keep SDK version and firmware version paired. kernel-devsrc has no git metadata, so the Dockerfile derives the -g<sha>[-dirty] suffix from usr/lib/modules/<release> and passes it as LOCALVERSION to make prepare (exported in the profile too), failing the build on mismatch.

Usage:

docker run --rm -it -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1          # shell
docker run --rm -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1 make          # one-shot
docker run --rm -v "$PWD":/src ghcr.io/nettimelogic/hive-m-sdk:0.5.1     sh -c 'cmake -B build -G Ninja && cmake --build build'

GitHub Actions (container: jobs skip the entrypoint, use a login shell):

jobs:
  build:
    runs-on: ubuntu-latest
    container: ghcr.io/nettimelogic/hive-m-sdk:0.5.1
    defaults: { run: { shell: bash -leo pipefail {0} } }
    steps:
      - uses: actions/checkout@v4
      - run: cmake -B build -G Ninja && cmake --build build && ctest --test-dir build

Publish flow: buildhive export sw --push (or --no-build --push on an existing installer) after docker login ghcr.io. Match --version to the firmware release the SDK was built from.

recipes-kernel/linux/linux-xlnx/qemu.cfg adds virtio-mmio/pci, virtio-net/blk/console, 9p and PCI_HOST_GENERIC to the Hive-M kernel. Inert on the board, lets ntl-shell share /src and network under -M virt; virtio-blk is the path to booting sd.wic in qemu later. export sw also copies rootfs/usr/bin/busybox to images/busybox for the guest shell.

Disk layout (rauc-zynqmp.wks)

Kernel development

build kernel-devsrc   ->  /kernel-devsrc volume: kernel source + build tree + env.sh
build module <name>   ->  oot/<name>/*.ko   (scaffolds Kbuild Makefile, builds against /kernel-devsrc)
build kernel-oot      ->  images/Image     (make -j Image modules, no bitbake)
shell --module <name> ->  bash with env.sh sourced, cwd oot/<name>
code                  ->  VS Code attached to dev container (/kernel-devsrc, /oot, /drivers)

env.sh sets ARCH, CROSS_COMPILE and the toolchain PATH. Module sources live in sources/drivers/staging/ntl/<name>/ (from the drivers clone repo). Re-run build kernel-devsrc after kernel config changes.

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.

Secure boot (Hive-M)

Full chain: eFUSE PPK hash → RSA-signed BOOT.bin (FSBL, PMUFW, ATF, u-boot, dtb via bootgen) → signed FIT (kernel + dtb) verified by u-boot → RAUC-signed rootfs → buildsign-signed update archives.

Detailed device-side documentation: sw/SECURE_BOOT.md in a hive-m project (template: src/templates/hive-m/sw/SECURE_BOOT.md).

Setup

buildhive secure-boot keygen        # generate keys/ (once)
# set "secure_boot": true in project.json (sw section)
buildhive build sw
buildhive secure-boot ppk-hash      # -> images/ppk0_hash.txt for eFUSE provisioning

Keys (keys/, gitignored)

keygen --force overwrites - devices fused to the old PSK become unbootable.

Effect of sw.secure_boot: true

• Build fails if keys/psk.pem is missing.
• require .../meta-ntl-hive/conf/secure-boot.conf added to local.conf. That conf sets SECURE_BOOT=1, the bootgen BIF (bh_auth_enable so signed images still boot unfused silicon; per-partition RSA authentication; bitstream deliberately unauthenticated), kernel-fitimage, UBOOT_SIGN_ENABLE=1, FIT_SIGN_ALG=rsa2048.
• device-tree.bbappend injects the FIT public key into u-boot's control dtb with required="conf" - u-boot rejects unsigned FITs.
• Update archive component set switches to raucb fitimage bootscr bootbin (signed FIT replaces raw Image/dtb).

sw.secure_boot: false strips the require line from local.conf on the next run.

eFUSE provisioning

secure-boot ppk-hash runs bootgen (-efuseppkbits) against the deployed FSBL and the PSK → images/ppk0_hash.txt. Burn PPK0 hash + RSA_EN per the device documentation. After RSA_EN is fused, the device only boots BOOT.bin images signed with the matching PSK/SSK.

Development

Repo layout

Release process

The version lives in one place: src/constants.py (VERSION). Everything else derives from it:

• setup.iss parses it at compile time (ISPP reads the first line of constants.py).
• Hive-M containers export it as BUILDHIVE_VERSION through BB_ENV_PASSTHROUGH_ADDITIONS; update-archive.bb and legacy-migration-update.bb default UPDATE_VERSION/MIGRATION_VERSION from it (fallback 0.0.0 for manual bitbake).
• project.json buildhive_version is stamped on save; a mismatch with the running tool triggers the update flow.
• upgrade and the GUI compare it against the newest GitHub release tag.

Release:

1. Bump VERSION in src/constants.py.
2. make build (PyInstaller, dist/buildhive/), then compile setup.iss → dist/BuildHive_Setup.exe.
3. GitHub release in NetTimeLogic/Tools: tag buildhive_v<x.y.z>, asset uploaded as BuildHive_<x.y.z>_Setup.exe. Drafts and pre-releases are ignored by the update check; the asset name must match BuildHive_*_Setup.exe.

The installer (setup.iss) installs per user into %APPDATA%\NTL\BuildHive\bin, no admin. Same AppId on every version: Setup replaces the uninstall entry itself and deletes the old bin/ before copying, so an upgrade needs no separate uninstall. The upgrade command starts the downloaded installer two seconds after the CLI exits so bin/ is not in use. Uninstall removes the PATH entry and the app directory.

Documentation

docs/ is an mdBook. README.md is the front page: the workflow copies it to docs/README.md with docs/ stripped from its links (docs/README.md and docs/book/ are gitignored). Build locally:

sed 's#](docs/#](#g' README.md > docs/README.md
mdbook build docs      # or: mdbook serve docs

.github/workflows/buildhive-docs.yml builds on every push to master touching buildhive/docs/** or buildhive/README.md and deploys to GitHub Pages (repository setting Pages > Source: GitHub Actions). New pages go into docs/SUMMARY.md.

GUI screenshots: python tools/gui_screenshots.py on a desktop session, no Docker needed. Rerun after visible GUI changes.

Template update mechanism

State per project: .buildhive_manifest.json (SHA-256 of every template file at last sync) and .buildhive_baseline/ (pristine text-file copies).

On version mismatch where the project is older than the tool, the user is prompted to update. Per file, three hashes decide (old manifest, new template, current disk):

images/ and project.json are never touched. Unresolved conflicts keep their old manifest hash, so they are re-prompted on the next update. buildhive_version is bumped only after all conflicts are resolved - an aborted update prompts again.

If the project is newer than the tool, no files are modified; the tool asks you to upgrade BuildHive.

Template edits during development: hive-m copies sw/meta-ntl-hive into the Yocto build tree on every container start, so layer changes in a project take effect on the next build without any sync step. Changes to src/templates/ reach existing projects only through the version-mismatch update flow.