DUT Configuration

Device under Test (DUT)

This configuration dut.yaml describes every aspect of a DUT. Below are the key components:

Branch scope: Each DUT belongs to a single branch of the project (see the Branches reference), alongside that branch’s workflows and storage. One physical device therefore appears once per branch that uses it, and FirmwareCI knows those entries are the same hardware — see Disabling a Device.

Required Fields

Attribute	Type	Description
name	`string`	Unique name of dut.
label	`string`	Label that identifies the devices group.
reservation-system	`string`	Reservation backend for this DUT. One of `dutctl`, `HWaaS`, `virtual`, `mock`. See below.

Optional Fields

Attribute	Type	Description
attributes	`object`	Attributes of the DUT.

DUT Attributes

The attributes field accepts any key-value combination to describe properties of your DUT. Common attributes include host addresses, port numbers, hardware capabilities, or any device-specific configuration.

These attributes can be referenced in test files using the attributes templating syntax: [[attributes.KeyName]]. This allows tests to access DUT-specific configuration without hardcoding values.

For complete details on templating syntax, see Templating and Variables.

Reservation System

reservation-system selects the backend used to reserve the hardware before a job runs and release it afterwards. The chosen backend determines which attributes are required:

reservation-system	Required attributes	Notes
`dutctl`	`Agent`, `Device`	Reserves through a DUT-Control agent. `Agent` is the agent endpoint, `Device` the device name on that agent.
`HWaaS`	`HwaaSHost`, `Version`	Reserves through a Hardware-as-a-Service orchestrator. `HwaaSHost` is the orchestrator address, `Version` the API revision. The optional `Platform` attribute selects which machine on that host to reserve; it defaults to `device`.
`virtual`	—	Virtual DUT; no external reservation.
`mock`	—	No-op reservation, for testing configuration.

Example

name: Prodrive-Hermes
label: prodrivehermes
reservation-system: dutctl
attributes:
  Agent: <dutagent-endpoint>
  Device: <device-name>
  Host: <host-address>
  Flasher: <flasher-address>

Device Status

A device that exists is not necessarily one a job can run on. The device list and device page show which of these applies:

Status	What it means
Idle	Free, and the next matching job may take it.
Busy	A job is running on it right now. It frees itself when that job finishes.
Unavailable	FirmwareCI cannot reach the device — usually the agent is stopped or the address is wrong. It checks periodically, so a stopped agent shows up within about a minute, and the status clears itself once the device answers again. The reason is shown on the device page.
Disabled	Somebody deliberately took it out of the pool. See below.

Disabling a Device

Disable a device when you do not want CI to schedule onto it — the hardware is broken and you are tired of watching jobs fail on it, or you want to borrow the board by hand for an afternoon.

Open the device and choose Disable. You are asked for two things:

A reason. It is shown to whoever finds the device out of the pool, so write what the next person needs to know (“PSU replaced, waiting for parts”).
How long. Pick one of the presets, type your own (90m, 2h, 1d12h), or — as an admin — leave it disabled indefinitely.

To put it back, open the device and choose Enable.

It applies to the hardware, not to one branch

The same physical device is declared once per branch that uses it. Disabling acts on the device, so every one of those entries is covered at once and you do not have to go hunting through branches. The confirmation dialog tells you how many entries are affected before you commit.

For the same reason, disabling is not part of your repository configuration: pushing a change to dut.yaml will not quietly re-enable a device somebody took out of the pool.

A job already running on the device is left alone — disabling is about the next job. If you need the board immediately, abort the running job as well.

Who may disable what

The duration is the permission: a device that comes back on its own is safe for anyone to take, one that does not is an admin’s call.

Role	With a duration	Indefinitely
Organization admin	yes, any duration	yes
Organization user	yes, up to 4 hours	no
Viewer	no	no

A device you disabled can be enabled again by you or by an admin — a colleague cannot pull a board out from under you mid-debug, and only an admin can return broken hardware to the pool.

Devices come back by themselves when the time is up; nothing is left holding hardware because somebody forgot. The record of who disabled it, why, and when it came back is kept.

Optional Files

Pre-Stage

This configuration pre.yaml describes the setup process of a DUT. Below are the key components:

Pre-Stage Required Fields

Attribute	Type	Description
pre-stage	`array`	List of test step commands (see Commands)

Pre-Stage Example

pre-stage:
  - cmd: dutctl
    name: Shutdown the DUT.
    parameters:
      host: "[[attributes.Flasher]]"
      command: power
      args: ["off"]

  - cmd: dutctl
    name: Flash the provided binary.
    parameters:
      host: "[[attributes.Flasher]]"
      command: flash
      args: [write, "[[input.Binary]]"]

  - cmd: dutctl
    name: Turn the DUT on
    parameters:
      host: "[[attributes.Flasher]]"
      command: power
      args: ["hardreset"]
    options:
      timeout: 2m

  - cmd: ping
    name: Wait for the device to become online.
    options:
      timeout: 4m
    parameters:
      host: "[[attributes.Host]]"

Post-Stage

This configuration post.yaml describes the teardown process of a DUT. Below are the key components:

Post-Stage Required Fields

Attribute	Type	Description
post-stage	`array`	List of test step commands (see Commands)

Post-Stage Example

post-stage:
  - cmd: dutctl
    name: Clean up. Shutdown the DUT.
    parameters:
      host: "[[attributes.Flasher]]"
      command: power
      args: ["off"]