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" }
]
}
}
| Key | Meaning |
|---|---|
sdk | SDK image tag x.y.z. Use the firmware version the app runs on. |
manifest | uwm 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. |
build | Shell command, run with bash -c in /src (the repo) inside the SDK image. CC, CFLAGS, LDFLAGS and the sysroot come from the SDK environment. |
files | Bundle file name -> repo path after the build. Must contain the manifest exec, and defaultConfig, configSchema and configTemplate when set. |
out | Output directory, default out. Add it to .gitignore. |
secrets | Secrets server for BUILDSIGN_TOKEN, as in project.json. Default https://secrets.ntl.dev. |
buildsign | Signing server and pinned public key (base64, 32 bytes), as sw.buildsign in project.json. |
license | Optional. Enables app license. |
license keys:
| Key | Meaning |
|---|---|
format | Value of the format line, default 1. |
product | Value of the product line. |
editions | Allowed values of the edition line. |
public_key | Key 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. |
fields | App 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 ` |
Reserved field names: format, product, edition, key_id, signature, verify, output, sign_timeout.
Commands
buildhive app init
| Flag | Default | Description |
|---|---|---|
--manifest | uwm_manifest.json | Manifest path written to the config. |
--sdk | newest shipped hive-m template version | SDK version. |
Takes secrets and buildsign from the newest hive-m template. Fails if buildhive-app.json exists.
buildhive app build
| Flag | Default | Description |
|---|---|---|
--sdk | sdk | SDK version for this build only. |
--version | manifest version | App version written into the bundled manifest and the package. |
--no-build | off | Skip build, pack the existing files. |
--no-sign | off | Skip signing. uwm does not install unsigned packages. |
--sign-timeout | 3600 | Seconds to wait for the approval. |
-v, --verbose | off | Show 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/:
| File | Content |
|---|---|
<name>-app-<version>.tar.gz | App bundle: manifest.json + files. exec mode 0755, the rest 0644, owner 0:0. At most 512 MiB. |
<name>-update-<version>.tar.gz | Update package: manifest.json (version, buildDate, restartRequired: false, fileMappings: [{src: <bundle>, dest: "app"}]) + bundle. |
signed_<name>-update-<version>.bin | Signature (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
| Flag | Description |
|---|---|
--edition | Edition. Default when editions has one entry. |
--<field> | One option per license.fields entry, _ written as - (--device-id). |
-o, --output | License file. Default out/<product>_<device_id>.lic, out/<product>.lic without a device_id field. Existing files are not overwritten. |
--verify FILE | Verify instead of create. Given --<field> values must match. |
--sign-timeout | Seconds 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,\nline ends. - Line order:
format,product,edition,license.fieldsin 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:
- Split at
signature=. Base64-decode the signature. - Verify Ed25519 over
"NTL-LICENSE-v1"followed by the 32-byte sha256 of the payload. - Check
format,product,edition,key_idand the app fields, e.g.device_idagainst 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.