Hardware Control

Control and manage hardware devices including DUTs, PiKVM interfaces, and QEMU virtual machines.

DUTCTL

Run DUTCTL for the DUT. This command can power-cycle and flash the DUT as well as read the serial of the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`dutctl`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`options`	`OptionsObject`	No		Additional command options
`parameters`	`DUTCTLOptions`	Yes		Options passed into the `dutctl` cmd

DUTCTL Options

Attribute	Type	Required	Description
`host`	`string`	Yes	Hostname or IP address of the device.
`command`	`string`	Yes	Command to execute on the device. Available commands: `power`, `flash`, `serial`.
`args`	`[]string`	No	Arguments for the command. Arguments depend on the command that is executed.
`input`	`string`	No	Input for the command, used only if command is set to `serial`.
`uart`	`integer`	No	UART number to use for serial communication.

DUTCTL Expect Options

Attribute	Type	Required	Default	Description
`regex`	`string`	Yes	`expect`	Regular expression to match against the output of the device for the `serial` command.

DUTCTL Example

- 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

PiKVM

Manage PiKVM operations.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`pikvm`	Command name.
`name`	`string`	Yes		Unique identifier for the teststep.
`options`	`OptionsObject`	No		Additional command options.
`parameters`	`PiKVMOptions`	Yes		Parameters for the `pikvm` command.

PiKVM Options

Attribute	Type	Required	Description
`command`	`string`	Yes (must be one of: `image`, `screenshot`, `keyboard`)	Operation to perform via the PiKVM interface.
`host`	`string`	Yes	Hostname or IP address of the PiKVM (format: “https://hostname”).
`auth`	`object`	Yes (must include `username` and `password`)	Authentication details for the PiKVM API.
`image`	`object`	Conditionally required when `command` is `image`	Image configuration. Contains a `path` property with the image file path to upload and mount.
`keyboard`	`object`	Conditionally required when `command` is `keyboard`	Keyboard input configuration. Use either the `keys` (array of key sequences) or `text` (string) property.

PiKVM Examples

Image mounting:

cmd: pikvm
name: Mount OS Image via PiKVM
parameters:
  command: image
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  image:
    path: "[[storage.Image]]/nixos.img"

Screenshot:

cmd: pikvm
name: Capture PiKVM Screenshot
parameters:
  command: screenshot
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root

Keyboard input:

cmd: pikvm
name: Send Keyboard Input via PiKVM
parameters:
  command: keyboard
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  keyboard:
    text: "INPUTTEXT"

cmd: pikvm
name: Send Keyboard Input via PiKVM
parameters:
  command: keyboard
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  keyboard:
    keys: ["CTRL + C", "I", "N", "P", "U", "T", "ENTER"]

Qemu

Manage QEMU virtual machines.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`qemu`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`options`	`OptionsObject`	No		Additional command options
`parameters`	`QemuOptions`	Yes		Options passed into the `qemu` cmd

Qemu Options

Attribute	Type	Required	Description
`mode`	`string`	Yes	Supported modes are start, run and stop.
`executable`	`string`	Conditional (see below)	The executable that should be executed.
`firmware`	`string`	Conditional (see below)	The firmware that should be used.
`image`	`string`	No	The image that should be booted.
`nproc`	`integer`	No	The number of processors that should be used.
`mem`	`integer`	No	The amount of memory that should be used.
`variable`	`string`	Conditional (see below)	Name a variable to store the qemu PID for later session return.
`serial`	`QemuStepsOptions`	Yes	Steps to interact with during test execution.

Behavior and semantics

The run mode can be used to attach to an already running QEMU instance. In this case, variable must be set to the PID of the QEMU process.
If variable is not set, the run mode will behave like the start mode, launching a new QEMU instance.
The stop mode will send a termination signal to the QEMU process identified by variable.

Conditional rules:

start: requires executable, firmware, and variable. The step launches QEMU and stores its PID in variable. If QEMU prints a PTY path it is stored in <variable>_pty.
run: if variable is provided the step attaches to the recorded PID/PTY and runs serial steps; if variable is empty, run requires both executable and firmware and will launch QEMU and run serial steps.
stop: requires variable and must not include executable, args, firmware or serial.

Qemu Serial Options

Attribute	Type	Required	Description
`send`	`string`	No	A string that should be sent as input.
`timeout`	`string`	No	Timeout for the interaction. Format: h for hours, m for minutes, s for seconds (e.g., 1h30m20s).
`expect`	`QemuExpectOptions`	No	Expectation for the interaction output.

Qemu Expect Options

Attribute	Type	Required	Default	Description
`regex`	`string`	Yes	`expect`	Regular expression that should be matched against the output of the interaction.