Documentation

Integrate the agent, produce a signed image, run a campaign.

Agent

#include <fieldwire.h>

fw_config cfg = {
    .device_id   = provisioned_id(),
    .fleet       = "sensor-v3",
    .pubkey      = FW_ROOT_PUBKEY,
    .apply_hook  = my_apply_gate,   /* return false to defer */
};
fw_init(&cfg);
fw_poll();   /* call from your main loop or a timer */

Bootloader

The bootloader verifies the signature over the slot before handing over. If verification fails, or if the application does not confirm a successful boot within the watchdog window, the previous slot is restored.

The confirmation call is the part teams forget. A device that boots and never calls fw_confirm() will roll back on the next reset, which looks like a mysterious downgrade three days later.

Image format

Section	Contents	Notes
Header	magic, version, slot layout	32 bytes
Manifest	component digests, dependencies	signed
Payload	full image or delta	compressed
Signature	Ed25519 over the manifest	verified in bootloader

Signing

Signing happens offline, ideally on a machine that has never been on a network. The build pipeline produces an unsigned manifest; a human signs it; the signed manifest is uploaded.

bash

# on the build machine
fw build --input ./rootfs.img --fleet sensor-v3 \
  --version 2026.8.1 --out manifest.unsigned

# on the signing machine (offline)
fw sign --key /media/hsm/release.key \
  manifest.unsigned --out manifest.signed

# back online
fw publish manifest.signed ./rootfs.img

Campaign API

Method	Path	Purpose
`POST`	`/v1/campaigns`	create a staged campaign
`GET`	`/v1/campaigns/{id}`	progress and guard state
`POST`	`/v1/campaigns/{id}/hold`	halt promotion
`POST`	`/v1/campaigns/{id}/resume`	resume
`POST`	`/v1/campaigns/{id}/rollback`	revert the fleet
`GET`	`/v1/fleets/{id}/versions`	version distribution