Devices and firmware

A device is a produced unit that connects to BuildTrace. BuildTrace tells it which firmware to run. You manage devices in Devices & Fleets and firmware in Firmware Versions.

All of this needs the ota feature (over-the-air updates) on your workspace’s plan. Without it, the device, fleet and firmware operations return an error, and so does a device check-in.

Commissioning

Commissioning turns a finished unit into a device. Select Commission device on Devices & Fleets, or use commissionDevice with the unit’s serial ID. The body is deviceIdentifier, the name the device uses for itself.

The unit must be AVAILABLE. A unit that is consumed, scrapped, quarantined or reserved can’t be commissioned. A unit can only be commissioned once.

The response includes the device’s token. The token is shown once: copy it from the dialog right away, because BuildTrace stores only a hash and can’t show it again. The device uses the token to authenticate. See Device check-in.

Device statuses

A device has one of these statuses:

REGISTERED: commissioned, not yet deployed.
DEPLOYED: sent to a fleet and a customer. Use deployDevice. Deploying ships the unit, so it leaves stock.
RMA: returned for repair.
DECOMMISSIONED: retired. A reason is required. Use decommissionDevice.

Separately, each device shows a connection state: never connected, online or offline. It comes from the last check-in.

Rotating a token

Select Rotate token on a device, or call rotateDeviceToken. Rotating revokes all of the device’s existing credentials and issues a new token, which is also shown once. The device must be given the new token before it can check in again. Rotate when a token leaks or when a device changes hands.

Component types

A device has one or more components that run firmware, such as a main controller or a radio. A component type names that kind of component. It has a code and a name. Create one with createComponentType, on the Component Types tab of Firmware Versions.

Firmware is versioned per component type. A firmware version for one component type can’t be assigned to another.

Firmware versions

A firmware version belongs to one component type and has a version number such as 1.0.0. It moves through these statuses:

Draft: created with createFirmwareVersion.
Released: you upload the binary, and the version is final.
Deprecated: deprecateFirmwareVersion. A deprecated release is still served to devices already assigned to it, but can’t be newly assigned.
Archived: archiveFirmwareVersion. It is hidden and no longer served. You can only archive a version that nothing is assigned to.

You can mark which part revisions a version works with, using addFirmwareCompatibility. A device is only offered firmware that is compatible with its revision.

Fleets and desired firmware

A fleet is a named group of devices. Create one with createFleet. Deploying a device puts it in a fleet.

Assign a firmware version with createFirmwareAssignment. You choose the component type, the version, and either a fleet or one device, never both. Only a released version can be assigned.

A fleet assignment sets the desired version for every device in the fleet.
A per-device assignment overrides the fleet’s for that device.

Assigning again for the same component type and target replaces the earlier assignment. A device assignment is also recorded on the unit’s timeline.

The Manifest tab shows what a fleet should run. getFleetManifest returns it. For one device, getDeviceFirmware compares the current version with the desired one for each component. A device is compliant when they match, or when nothing is assigned.

How a device updates

When a device checks in, it reports the versions it runs. BuildTrace answers with its manifest: for each component type, the version to run, a short-lived download link and a checksum. The device downloads the file, flashes it and reports the new version on its next check-in. The flash appears on the unit’s timeline as FIRMWARE_FLASHED. This is the ota flow. The full contract is in Device check-in.