software

The software driver gives you a peripheral with no physical bus behind it. You supply a container image and a few shell scripts. The bench runs the container and calls your scripts for each read and write.

Use it for anything you can reach from a script but that has no driver of its own: a DUT behind a vendor CLI, a network socket, or a lab tool. Each operation runs a separate docker exec, so expect a few hundred milliseconds of overhead per call. Use a hardware driver when speed matters.

Property	Value
kind	software
Interfaces	software
location	A container image, such as ghcr.io/acme/dut-tools:latest

Example

dut_bridge:
  kind: software
  name: "DUT serial bridge"
  description: "Ad-hoc bridge to the DUT via a helper container"
  location: ghcr.io/acme/dut-tools:latest
  interfaces:
    - type: software
      channel: 0
      config:
        env:
          DUT_HOST: dut.local
          DUT_PORT: "23"
        open: "socat -d pty,link=/var/run/dut.pty,raw tcp:$DUT_HOST:$DUT_PORT & echo ready"
        read: "cat /var/run/dut.out"
        write: "cat >> /var/run/dut.in"
        health: "test -e /var/run/dut.pty"
        shell: "/bin/sh"
        timeout_ms: 30000

Location

The location is a container image reference. It can be a public image or one you push to your organization's MIMICK registry with mimick runbook image push. The bench pulls the image the first time the peripheral opens, and it shows as missing until the pull finishes.

The image must include a shell (/bin/sh unless you set shell), date, sleep, and a writable temporary directory. Minimal images with no shell don't work.

How the container runs

When the peripheral opens, the bench starts one long-lived container from the image and runs your open script in it once. It then runs read and write in that same container, one at a time. State carries over between calls, so a file one write creates is still there for the next read.

The bench replaces the image's own startup:

• The image's ENTRYPOINT and CMD don't run. Put any startup work in open.
• The image's HEALTHCHECK is ignored. Use health instead.
• The container uses the bench's network directly.

Editing anything inside config recreates the container when you deploy, and the container's state is lost with it.

Software interface

A peripheral has exactly one software interface.

Key	Required	Default	Description
read	Yes		A script whose standard output is returned as the data read.
write	Yes		A script that receives the written data on standard input.
open	No		A script that runs once after the container starts. A non-zero exit leaves the peripheral missing, and the bench retries later.
health	No		A script the bench runs about every 30 seconds. A non-zero exit marks the peripheral missing. Without it, the bench checks that the container is still responsive.
env	No		Environment variables for the container, as a map. Names use letters, digits, and underscores, and don't start with a digit.
shell	No	/bin/sh	The shell that runs your scripts.
timeout_ms	No	30000	How long each script may run, in milliseconds.
privileged	No	false	Gives the container access to every device on the bench, such as USB adapters.

A script's exit code comes back with its output, so a failing script is a result you can check, not a lost connection.

warning

Don't put secrets in env or in a script. The file is stored in plain text on the bench and in the Cloud, and anyone in your organization can read it.

Privileged containers

Set privileged: true only when your scripts need hardware plugged into the bench. The container can then reach every device on the bench, so treat its scripts as having full control of the bench. Don't point a privileged container at a device that another peripheral entry already uses. The two compete for the device, and nothing arbitrates between them.

Use it

mimick software dut_bridge read
mimick software dut_bridge write --data "reboot"
echo -n "reboot" | mimick software dut_bridge write

The CLI exits with your script's exit code. Add --timeout 10s to override timeout_ms for one call.