UWM apps

buildhive builds uwm apps in their own repo. No Hive-M project is needed. The build runs in the SDK image of one firmware version (ghcr.io/nettimelogic/hive-m-sdk:<sdk>), so the binary links against the glibc and libraries of that firmware. App format and runtime contract: docs/src/deployment/apps.md in the uwm repo.

buildhive-app.json

At the repo root. buildhive app init writes a skeleton. With this file in the current directory, the app build, app sign and app license commands exist.

{
    "sdk": "2026.2.0",
    "manifest": "integration/uwm_manifest.json",
    "build": "make BUILD=release mcs_advanced",
    "files": {
        "mcs_advanced": "mcs_advanced",
        "config.default.json": "integration/uwm_config.default.json"
    },
    "out": "out",
    "secrets": { "url": "https://secrets.ntl.dev", "role": "dev" },
    "buildsign": { "url": "https://sign.ntl.dev/api", "public_key": "wLh+..." },
    "license": {
        "format": "1",
        "product": "multisync",
        "editions": ["advanced"],
        "public_key": null,
        "fields": [
            { "name": "device_id", "type": "hex" },
            { "name": "serial" },
            { "name": "customer" },
            { "name": "issued", "type": "date", "default": "today" },
            { "name": "maintenance", "type": "date", "default": "issued+1y", "not_before": "issued" }
        ]
    }
}
KeyMeaning
sdkSDK image tag x.y.z. Use the firmware version the app runs on.
manifestuwm app manifest in the repo. Checked with the same rules as uwm at install time. Unknown fields fail. Copied into the bundle as manifest.json.
buildShell command, run with bash -c in /src (the repo) inside the SDK image. CC, CFLAGS, LDFLAGS and the sysroot come from the SDK environment.
filesBundle file name -> repo path after the build. Must contain the manifest exec, and defaultConfig, configSchema and configTemplate when set.
outOutput directory, default out. Add it to .gitignore.
secretsSecrets server for BUILDSIGN_TOKEN, as in project.json. Default https://secrets.ntl.dev.
buildsignSigning server and pinned public key (base64, 32 bytes), as sw.buildsign in project.json.
licenseOptional. Enables app license.

license keys:

KeyMeaning
formatValue of the format line, default 1.
productValue of the product line.
editionsAllowed values of the edition line.
public_keyKey the app verifies licenses with (base64, 32 bytes). null = buildsign.public_key. app build writes it as PEM to out/license_public.pem and sets LICENSE_PUBKEY to that path in the build container. The app does not need its own copy of the key.
fieldsApp fields in file order. type: text (default, not empty, no control characters), date (YYYY-MM-DD), hex (lower case, 0x removed). default: used when the option is not given. For dates: today, or `+<d

Reserved field names: format, product, edition, key_id, signature, verify, output, sign_timeout.

Commands

buildhive app init

FlagDefaultDescription
--manifestuwm_manifest.jsonManifest path written to the config.
--sdknewest shipped hive-m template versionSDK version.

Takes secrets and buildsign from the newest hive-m template. Fails if buildhive-app.json exists.

buildhive app build

FlagDefaultDescription
--sdksdkSDK version for this build only.
--versionmanifest versionApp version written into the bundled manifest and the package.
--no-buildoffSkip build, pack the existing files.
--no-signoffSkip signing. uwm does not install unsigned packages.
--sign-timeout3600Seconds to wait for the approval.
-v, --verboseoffShow the build output. Without it, the last 15 lines are shown on failure.

Pulls the SDK image if it is not local. A failed pull needs docker login ghcr.io, or build the image in a Hive-M project with buildhive export sw --image --version <sdk>. On Linux the container runs with your uid and gid.

Writes to out/:

FileContent
<name>-app-<version>.tar.gzApp bundle: manifest.json + files. exec mode 0755, the rest 0644, owner 0:0. At most 512 MiB.
<name>-update-<version>.tar.gzUpdate package: manifest.json (version, buildDate, restartRequired: false, fileMappings: [{src: <bundle>, dest: "app"}]) + bundle.
signed_<name>-update-<version>.binSignature (64 bytes) + update package. Upload under Settings > System update.

buildhive app sign

Signs the newest *-update-*.tar.gz in out/. --sign-timeout as above. Signing flow and token: updates.md.

buildhive app license

FlagDescription
--editionEdition. Default when editions has one entry.
--<field>One option per license.fields entry, _ written as - (--device-id).
-o, --outputLicense file. Default out/<product>_<device_id>.lic, out/<product>.lic without a device_id field. Existing files are not overwritten.
--verify FILEVerify instead of create. Given --<field> values must match.
--sign-timeoutSeconds to wait for the approval.

Sends sha256 of the payload to buildsign with purpose: license and the license file name. After approval it checks the signature against license.public_key, then writes the file.

License format

format=1
product=multisync
edition=advanced
device_id=1234
serial=12345678
customer=test
issued=2026-11-09
maintenance=2027-11-09
key_id=01c67b9470364240
signature=<base64, 64 bytes>
  • Payload: every byte before the signature= line, UTF-8, \n line ends.
  • Line order: format, product, edition, license.fields in config order, key_id.
  • key_id: first 16 hex digits of sha256 over the raw 32-byte public key.
  • Signature: Ed25519 over "NTL-LICENSE-v1" || sha256(payload). Update packages use "UWM-UPDATE-v1", so one signature is never valid for the other.

App side check:

  1. Split at signature=. Base64-decode the signature.
  2. Verify Ed25519 over "NTL-LICENSE-v1" followed by the 32-byte sha256 of the payload.
  3. Check format, product, edition, key_id and the app fields, e.g. device_id against the FPGA ID.

buildsign must support purpose: license. A server without it signs with the update prefix. app license then fails with does not support 'license' signing requests yet and writes no file.

Makefiles in the SDK

The SDK exports CC, CFLAGS and LDFLAGS. A Makefile with CFLAGS ?= -Wall -Werror ... then skips its own flags. Use CFLAGS += ... for flags the build needs. Libraries the app links, e.g. -lcrypto, must be in the SDK sysroot and in the firmware image.