dutagent-config.md

DUT Agent Configuration

The DUT Agent is configured by a YAML configuration file.

The configuration mainly consists of a list of devices connected to an agent and a list of the Commands available for those devices. Commands are meant to be the high-level tasks you want to perform on the device, e.g. "Flash the firmware with the given image." To achieve this high-level task, commands can be built up of one or multiple Modules. Modules represent the basic operations and represent the actual implementation for the hardware interaction. The implementation of a Module determines its capabilities and also exposes information on how to use and configure it.

The DUT Control project offers a collection of Module implementations but also allows for easy integration of custom modules. Often a Command can consist of only one Module to get the job done, e.g., power cycles the device. But in some cases like the flash example mentioned earlier, eventually it is mandatory to toggle some GPIOs before doing the actual SPI flash operation. In this case the command is built up of a Module dealing with GPIO manipulation and a Module performing a flash writing with a specific programmer. See the second device in the example down below on what this could look like. Commands support three approaches for arguments: static values, passthrough modules that receive all runtime arguments directly, and command-level argument templating that distributes named arguments to modules via template syntax (see Command Argument Templating).

DUT Agent Configuration Schema

Attribute	Type	Default	Description	Mandatory
version	string		Version of this config schema	yes
devices	[] Device		List of devices-under-test (DUTs) connected to this agent	yes

Device

Attribute	Type	Default	Description	Mandatory
description	string		Device description. May be used to state technical details which are important when working with this DUT.	no
commands	[] Command		List of available device commands. Commands are the high level tasks that can be performed on the device.	no

Commands

Attribute	Type	Default	Description	Mandatory
description	string		Command description	no
uses	[] Module		A command may be composed of multiple steps to achieve its purpose. The list of modules represent these steps. The order of this list is important. At most one module may be set as the passthrough module. If a passthrough module is present, all arguments to the command are passed to it, and its usage information is used as the command help text.	yes
args	[]Argument		Named arguments that can be passed to the command at runtime and distributed to modules via template syntax. Arguments are mapped positionally in declaration order. Cannot be used with passthrough modules - use one or the other.	no

Command Arguments

Command arguments define named parameters that can be passed at runtime and distributed to modules via template syntax.

Attribute	Type	Default	Description	Mandatory
name	string		Argument name (used in templates)	yes
desc	string		Human-readable argument description	yes

Module

Attribute	Type	Default	Description	Mandatory
module	string		The module's name also serves as its identifier and must be unique.	yes
passthrough	bool	false	Marks this module as the passthrough module. All runtime arguments to a command are passed to its passthrough module. The passthrough module's usage information is also used as the command help text.	0 or 1 times per command
args	[]string	nil	If a module is not a command's passthrough module, it does not get any arguments passed at runtime, instead arguments can be passed here.	no, only applies if passthrough is not set
with	map[string]any		A module can be configured via key-value pairs. The type of the value is generic and depends on the implementation of the module.	yes

Important

Refer to with keys of a module in all-lowercase representation of the module's exported fields. See the respective module's documentation for details.

Example config file

See dutagent-cfg-example.yaml