agentOS

agentOS is Blue Clover’s Linux distribution for the Blue Clover Test Agent PER-101 that acts alongside a PLT during production testing. agentOS exposes a USB-CDC console, a USB Mass Storage RAMDISK, and a USB network interface. The PLT drives it with the agentCfg - Configure Agent and agentExec - Execute command on Agent commands.

See also

Capabilities

An agentOS image presents itself to the PLT as a composite USB gadget:

  • USB-CDC console (/dev/ttyGS0 on the SBC) — 1,000,000 baud 8N1, with autologin as the pltagent user. Any shell command issued with agentExec - Execute command on Agent runs on the Test Agent.

  • USB Mass Storage RAMDISK — files sent from the PLT with agentCfg’s with: list appear on the SBC at /run/pltagent/mnt, so a test plan can hand firmware images, archives, or scripts to Test Agent for execution. The RAMDISK is 256 MB and FAT16-formatted.

  • USB network interface — a USB Ethernet (CDC-ECM) function with link-local addressing. See USB network interface.

Build info (/etc/buildinfo) is reported back to the PLT so the agent’s DISTRO_VERSION shows up alongside test results.

USB identity

USB descriptor

Value

VID:PID

6666:8001

Manufacturer

Blue Clover Devices

Product

per-101 running: <distro> ver: <version>

Serial number

The Test Agent’s board serial number

Changed in version agentOS: v2.0.2 The product string reports the distribution name and version from /etc/buildinfo, so the agentOS version can be read from the host without opening a console session.

USB network interface

Added in version agentOS: v2.0.2

The Test Agent presents a USB Ethernet (CDC-ECM) function next to the console and the RAMDISK. All three are part of the same USB configuration, so test plans that use the console and RAMDISK keep working unchanged.

  • On the Test Agent the interface is named usb0.

  • usb0 is configured with link-local addressing for both IPv4 (169.254.0.0/16) and IPv6 (fe80::/10).

  • The Test Agent announces itself with mDNS on usb0 only, as per101-<serial>.local, where <serial> is the board serial number that is also reported as the USB serial number.

The board serial number is available in a console session as the OTP_ID environment variable:

$ echo "per101-${OTP_ID}.local"

Included tools

The tools below are part of the agentOS image as of agentOS v2.0.3 and can be run with agentExec - Execute command on Agent without installing anything.

Blue Clover commands

Command

Purpose

flashr-flash

Program a .hex, .elf, or .bin image into a target through an attached Flashr.

flashr-update

Upload a firmware update to an attached Flashr.

pltagent-msc-present, pltagent-msc-mount

Detect and mount a USB Mass Storage device exposed by a DUT. See NXP i.MX RT685 EVK and Microchip Explorer 16/32 for worked examples.

pltagent-cam [auto|fixed] [<outputFile>]

Capture a still image with libcamera-still. auto (default) uses automatic exposure and gain; fixed uses a fixed shutter time, gain, and white balance for repeatable captures. The image is written to /tmp/capture.jpg unless outputFile is given.

nrf52_flash.py

Recover, erase, program, verify, and reset an nRF52 through nrfutil. Options include --hex <file>, --recover, --erase, --verify, and --sn <serialNumber>. The last line of output is always nrf52_flash:DONE:<exitCode>:<message>.

led-act on|off, led-pwr on|off

Switch the Test Agent’s ACT and PWR LEDs, for example as an operator indicator. Run with sudo.

Vendor tools

Command

Notes

nrfutil

Nordic nRF Util with the device command installed. The command on the path is a wrapper that always passes --json --log-output stdout, so output reaches the console. See Nordic nRF Util.

JLinkExe

SEGGER J-Link Commander V9.16a, also available as /opt/SEGGER/JLink/JLinkExe. See Segger J-Link Software.

Open-source tools

Purpose

Tools

Programming

openocd, stm32flash, flashrom, mcumgr, rpiboot, mtd-utils, srecord

Buses and I/O

i2c-tools, spitools, canutils, picocom, sigrok-cli, mbpoll, pymodbus (Python)

Display and camera

edid-decode, read-edid, libcamera-apps

Storage

parted, dosfstools, squashfs-tools, blkid

Network

atftp, dnsmasq, usbip, openssh

System

lsusb, lshw, vcgencmd, vcmailbox, rpi-eeprom, python3

Environment

  • Commands run as the pltagent user. sudo works without a password.

  • The root file system is read-only. Write temporary files to /tmp or to the RAMDISK at /run/pltagent/mnt; to install additional software, remount the root file system read-write first, as shown in Segger J-Link Software.

Usage

An agentOS SBC is set up with agentCfg - Configure Agent, then any command line is executed on it with agentExec - Execute command on Agent. The default USB VID:PID for an agentOS device is 6666:8001.

title: "Test DUT using an agentOS SBC"
suite:

 - title: "Setup SBC"
   steps:
    - command: agentCfg AGENT
      with:
       - myscript.py

 - title: "Power DUT"
   steps:
    - command: ground all
    - command: power 3V3 on

 - title: "Test DUT with SBC"
   steps:
    - command: agentExec AGENT "python3 /run/pltagent/mnt/myscript.py"

Examples

Sample test plans that exercise agentOS:

See also