# Devices and firmware

> Commissioning, device tokens, fleets, component types, firmware, desired state.

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](https://dev.buildtrace.eu/docs/guides/device-check-in.md).

## 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:

1. Draft: created with `createFirmwareVersion`.
2. Released: you upload the binary, and the version is final.
3. Deprecated: `deprecateFirmwareVersion`. A deprecated release is still served to devices already assigned to it, but can't be newly assigned.
4. 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](https://dev.buildtrace.eu/docs/guides/device-check-in.md).

See also [Serials](https://dev.buildtrace.eu/docs/concepts/serials.md).