Configuration file

peripherals.yaml declares the peripherals attached to a bench. This page lists the structure of the file and the options every driver shares. For the settings a specific driver accepts, see its page under Peripherals. To deploy the file or switch setups, see Peripherals & interfaces.

Top-level structure

The file is a YAML mapping. Every top-level key is the symbol of one peripheral, except setups, which is reserved for setups. The file has no version key or any other top-level setting. An empty file is valid and declares no peripherals.

dut_console:
  kind: linux-tty
  name: "DUT console"
  location: /dev/serial/by-id/usb-FTDI_FT232R_A50285BI-if00-port0
  interfaces:
    - type: uart
      channel: 0
      config:
        baud_rate: 115200
    - type: tty
      channel: 0
      backed_by: { type: uart, channel: 0 }

button_relay:
  kind: relay-usb
  name: "USB relay"
  location: /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
  interfaces:
    - type: relay
      channel: 0
      config:
        channels:
          - { number: 1, name: "Power button" }

Symbols

A peripheral symbol and a config symbol follow the same rules:

• It starts with a letter or an underscore.
• It holds only letters, digits, and underscores.
• It's unique among its siblings.

A network-bridge symbol has extra rules.

Peripheral fields

Field	Required	Description
kind	Yes	The driver that talks to this peripheral. See the driver list.
name	Yes, except for the two network drivers	A display name shown in the CLI and web UI.
description	No	Free text shown alongside the name.
location	Yes, except for network-bridge	Where the bench finds the hardware. The format depends on the driver. Two peripherals can't share a location, and a location can't end in /.
locations	network-bridge only	The list of network ports a bridge joins. Other drivers reject it.
interfaces	No	The interfaces to expose. A peripheral with none loads but offers nothing to use.
configs	No	Named alternative settings for the same hardware. See configs.

Interface fields

Each entry in interfaces declares one way of talking to the peripheral.

Field	Required	Description
type	Yes	The interface type: uart, chardev, tty, spi, gpio, relay, stepper, ethernet, wifi, or software.
channel	No (defaults to 0)	Which instance of this type, when a peripheral has more than one. Every current driver uses channel 0.
config	Depends on the driver	Settings for this interface. Each driver page lists the keys it accepts.
backed_by	For tty only	The interface a terminal runs on top of, as { type, channel }. It sits beside config, not inside it.

caution

The bench ignores an unknown type and any unknown key inside config, with no error. A misspelled key quietly falls back to its default, so check the spelling against the driver page when a setting doesn't take effect.

Interface addresses

The bench gives every declared interface an address built from the file:

Peripheral	Address format	Example
Without configs	<symbol>.<type><channel>	dut_console.tty0
With configs	<symbol>.<config>.<type><channel>	lan.dhcp_server.ethernet0

When a peripheral, or its config, has exactly one interface, the address without the .<type><channel> suffix also resolves to it. In the example above, button_relay and button_relay.relay0 are the same address.

The location value is never part of an address.

configs

configs is a mapping from a config symbol to one alternative set of settings for the peripheral's hardware.

Field	Required	Description
name	No	A display name for this config. Defaults to the peripheral's name.
description	No	Defaults to the peripheral's description.
interfaces	No	The interfaces this config exposes. Defaults to the peripheral's interfaces.

All configs of a peripheral share its location, and only one of them is active at a time. The setups block decides which one is active at boot.

lan:
  kind: network-interface
  name: "DUT LAN port"
  location: wired0
  configs:
    dhcp_server:
      name: "LAN DHCP server"
      interfaces:
        - type: ethernet
          config:
            mode: dhcp-server
            address: 192.168.100.1/24
            dhcp_range_start: 192.168.100.100
            dhcp_range_end: 192.168.100.200
    dhcp_client:
      name: "LAN DHCP client"
      interfaces:
        - type: ethernet
          config:
            mode: dhcp-client

setups

setups is a mapping from a setup name to a list of configs to activate together. Each list entry is <peripheral>.<config>.

setups:
  default: lab
  lab:
    - lan.dhcp_server
    - radio.ap
  field:
    - lan.dhcp_client
    - radio.sta

Key	Required	Description
default	No	The name of the setup the bench activates at boot. It must be a setup defined in this block.
Any other key	No	A setup name, with its list of <peripheral>.<config> entries.

The block follows these rules:

• default is reserved, so no setup can take the name default.
• A setup lists a peripheral at most once.
• Every entry refers to a peripheral that has configs, and to a config it defines.

tip

Make sure the default setup covers every peripheral that has configs. For a peripheral it leaves out, the bench picks one of its configs at boot, and you can't choose which.

Validation

The bench rejects the whole file, and keeps its current one, when the file:

• Isn't valid YAML
• Has an invalid peripheral or config symbol
• Has a peripheral with no kind, or with no location (no locations for a network-bridge)
• Gives two peripherals the same location
• Breaks a network-bridge membership rule
• Breaks a setups rule

Every other problem affects only the entry it's in. The bench loads the entry and marks it missing when:

• The device isn't plugged in or can't be reached
• The kind isn't a known driver
• The driver rejects a setting, such as an out-of-range pin