Common Use Cases

This page provides quick reference examples for typical workflows with adi-labgrid-plugins. Each example shows both configuration and Python usage.

Basic Power Control

Turn on/off a device using a smart outlet:

Configuration:

targets:
  mydevice:
    resources:
      VesyncOutlet:
        outlet_names: 'Device Power'
        username: 'your_email@example.com'
        password: 'your_password'
        delay: 5.0

    drivers:
      VesyncPowerDriver: {}

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("mydevice")
power = target.get_driver("VesyncPowerDriver")

power.on()      # Turn on
power.off()     # Turn off
power.cycle()   # Power cycle (off, delay, on)

Serial Console Access

Connect to a device’s serial console for interactive shell commands:

Configuration:

targets:
  serial_device:
    resources:
      SerialPort:
        port: '/dev/ttyUSB0'
        baudrate: 115200

    drivers:
      ADIShellDriver:
        console: SerialPort
        prompt: 'root@.*:.*#'
        login_prompt: 'login:'
        username: 'root'
        password: 'analog'
        login_timeout: 60

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("serial_device")
shell = target.get_driver("ADIShellDriver")
target.activate(shell)

# Run commands
output = shell.run_command("uname -a")
print(output)

# Interactive: send command and wait for output
shell.sendline("ls -la")
shell.console.expect("root@.*:.*#")

File Transfer via XMODEM

Upload/download files using XMODEM protocol over serial:

Configuration:

targets:
  xmodem_device:
    resources:
      SerialPort:
        port: '/dev/ttyUSB0'
        baudrate: 115200

    drivers:
      ADIShellDriver:
        prompt: 'root@.*:.*#'
        login_prompt: 'login:'
        username: 'root'
        password: 'analog'

Upload file to device:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("xmodem_device")
shell = target.get_driver("ADIShellDriver")
target.activate(shell)

# Upload file using XMODEM
shell.send_xmodem(
    local_path="/path/to/local/file.bin",
    remote_path="/tmp/file.bin"
)

Download file from device:

# Download file using XMODEM
shell.recv_xmodem(
    remote_path="/tmp/output.dat",
    local_path="/path/to/local/output.dat"
)

Automated Boot Sequences

Boot a device to shell using a strategy:

Configuration:

targets:
  bootable_device:
    resources:
      VesyncOutlet:
        outlet_names: 'Device Power'
        username: 'your_email@example.com'
        password: 'your_password'
        delay: 5.0

      SerialPort:
        port: '/dev/ttyUSB0'
        baudrate: 115200

      MassStorageDevice:
        path: '/dev/sda1'

      KuiperRelease:
        version: '2024.r1'

    drivers:
      VesyncPowerDriver: {}
      ADIShellDriver:
        prompt: 'root@.*:.*#'
        login_prompt: 'login:'
        username: 'root'
        password: 'analog'
      MassStorageDriver: {}
      KuiperDLDriver: {}

    strategies:
      BootFPGASoC:
        reached_linux_marker: 'analog'
        update_image: false

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("bootable_device")
strategy = target.get_strategy("BootFPGASoC")

# Boot to shell (goes through all intermediate states)
strategy.transition("shell")

# Device is now ready for testing
shell = target.get_driver("ADIShellDriver")
shell.run_command("echo 'Device booted successfully'")

# Cleanup
strategy.transition("soft_off")

SD Card Management

Mount SD card, copy files, prepare for device boot:

Configuration:

targets:
  sd_device:
    resources:
      MassStorageDevice:
        path: '/dev/sda1'

    drivers:
      MassStorageDriver:
        device: MassStorageDevice

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("sd_device")
mass_storage = target.get_driver("MassStorageDriver")
target.activate(mass_storage)

# Mount partition
mass_storage.mount_partition()

# Copy files to SD card
mass_storage.copy_file("/path/to/local/boot.bin", "/")
mass_storage.copy_file("/path/to/local/devicetree.dtb", "/")

# Verify files
mass_storage.list_files("/")

# Unmount
mass_storage.unmount_partition()

Kuiper Release Download

Download and manage Kuiper release boot files:

Configuration:

targets:
  kuiper_device:
    resources:
      KuiperRelease:
        version: '2024.r1'
        cache_dir: '/tmp/kuiper_cache'

    drivers:
      KuiperDLDriver:
        kuiper_release: KuiperRelease

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("kuiper_device")
kuiper = target.get_driver("KuiperDLDriver")
target.activate(kuiper)

# Download and extract release
kuiper.download_release()

# Get boot files paths
boot_files = kuiper.get_boot_files_from_release()
print(f"Boot files: {boot_files}")

# Access individual files
for file_path in kuiper._boot_files:
    print(f"File: {file_path}")

Testing Pattern with pytest

Integration with pytest for automated testing:

conftest.py:

import pytest
from labgrid import Environment

@pytest.fixture(scope="session")
def env():
    """Load labgrid environment once per test session."""
    return Environment("target.yaml")

@pytest.fixture(scope="function")
def target(env):
    """Get target for each test."""
    return env.get_target("mydevice")

@pytest.fixture(autouse=True)
def setup_teardown(target):
    """Boot device before test, power off after."""
    strategy = target.get_strategy("BootFPGASoC")
    try:
        strategy.transition("shell")
        yield
    finally:
        try:
            strategy.transition("soft_off")
        except:
            pass

test_device.py:

def test_device_boots(target):
    """Verify device boots to shell."""
    strategy = target.get_strategy("BootFPGASoC")
    assert strategy.status.name == "shell"

def test_kernel_version(target):
    """Verify kernel version."""
    shell = target.get_driver("ADIShellDriver")
    output = shell.run_command("uname -r")
    assert len(output) > 0

def test_iio_devices(target):
    """Verify IIO devices are present."""
    shell = target.get_driver("ADIShellDriver")
    output = shell.run_command("ls /sys/bus/iio/devices/")
    assert "iio:device0" in output

Multi-Device Coordination

Manage multiple devices in a single test session:

Configuration:

targets:
  device_a:
    resources:
      VesyncOutlet:
        outlet_names: 'Device A Power'
        username: 'your_email@example.com'
        password: 'your_password'
        delay: 5.0

      SerialPort:
        port: '/dev/ttyUSB0'
        baudrate: 115200

    drivers:
      VesyncPowerDriver: {}
      ADIShellDriver:
        prompt: 'root@.*:.*#'
        login_prompt: 'login:'
        username: 'root'
        password: 'analog'

  device_b:
    resources:
      VesyncOutlet:
        outlet_names: 'Device B Power'
        username: 'your_email@example.com'
        password: 'your_password'
        delay: 5.0

      SerialPort:
        port: '/dev/ttyUSB1'
        baudrate: 115200

    drivers:
      VesyncPowerDriver: {}
      ADIShellDriver:
        prompt: 'root@.*:.*#'
        login_prompt: 'login:'
        username: 'root'
        password: 'analog'

Usage:

from labgrid import Environment

env = Environment("target.yaml")
device_a = env.get_target("device_a")
device_b = env.get_target("device_b")

# Power on both devices
device_a.get_driver("VesyncPowerDriver").on()
device_b.get_driver("VesyncPowerDriver").on()

# Boot both to shell
device_a.get_strategy("BootFPGASoC").transition("shell")
device_b.get_strategy("BootFPGASoC").transition("shell")

# Run commands on both
shell_a = device_a.get_driver("ADIShellDriver")
shell_b = device_b.get_driver("ADIShellDriver")

output_a = shell_a.run_command("hostname")
output_b = shell_b.run_command("hostname")

print(f"Device A: {output_a}")
print(f"Device B: {output_b}")

# Cleanup
device_a.get_strategy("BootFPGASoC").transition("soft_off")
device_b.get_strategy("BootFPGASoC").transition("soft_off")

CyberPower PDU Control

Control power via CyberPower PDU with SNMP:

Configuration:

targets:
  cyberpower_device:
    resources:
      CyberPowerOutlet:
        hostname: '192.168.1.100'
        outlet_number: 1
        snmp_version: '2c'
        community: 'public'

    drivers:
      CyberPowerDriver: {}

Usage:

from labgrid import Environment

env = Environment("target.yaml")
target = env.get_target("cyberpower_device")
power = target.get_driver("CyberPowerDriver")
target.activate(power)

# Control power
power.on()      # Turn on outlet
power.off()     # Turn off outlet
power.cycle()   # Reboot (off, delay, on)

# Check power status (if supported)
if hasattr(power, 'get_state'):
    state = power.get_state()
    print(f"Outlet state: {state}")

See Also