labgrid-client

Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems.

This is the client to control a boards status and interface with it on remote machines.

usage: labgrid-client [-h] [-x ADDRESS] [-c CONFIG] [-p PLACE] [-s STATE]
                      [-i INITIAL_STATE] [-d] [-v] [-P PROXY]
                      COMMAND ...

Named Arguments

-x, --coordinator: coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408)
-c, --config: env config file (default: value from env variable LG_ENV)
-p, --place: place name/alias (default: value from env variable LG_PLACE)
-s, --state: strategy state to switch into before command (default: value from env varibale LG_STATE)
-i, --initial-state: strategy state to force into before switching to desired state
-d, --debug: enable debug mode (show python tracebacks)
-v, --verbose
-P, --proxy: proxy connections via given ssh host

Sub-commands

monitor

monitor events from the coordinator

labgrid-client monitor [-h]

resources (r)

list available resources

labgrid-client resources [-h] [-a] [-e EXPORTER]
                         [--sort-by-matched-place-change]
                         [match]

Positional Arguments

match

Named Arguments

-a, --acquired
-e, --exporter
--sort-by-matched-place-change: sort by matched place’s changed date (oldest first) and show place and date

places (p)

list available places

labgrid-client places [-h] [-a] [-r] [--sort-last-changed]

Named Arguments

-a, --acquired
-r, --released
--sort-last-changed: sort by last changed date (oldest first)

who

list acquired places by user

labgrid-client who [-h] [-e]

Named Arguments

-e, --show-exporters: show exporters currently used by each place

show

show a place and related resources

labgrid-client show [-h]

create

add a new place with the name specified via --place or the LG_PLACE environment variable.

labgrid-client create [-h]

delete

delete an existing place

labgrid-client delete [-h]

add-alias

add an alias to a place

labgrid-client add-alias [-h] alias

Positional Arguments

alias

del-alias

delete an alias from a place

labgrid-client del-alias [-h] alias

Positional Arguments

alias

set-comment

update the place comment

labgrid-client set-comment [-h] comment [comment ...]

Positional Arguments

comment

set-tags

update the place tags

labgrid-client set-tags [-h] KEY=VALUE [KEY=VALUE ...]

Positional Arguments

KEY=VALUE: use an empty value for deletion

add-match

add one (or multiple) match pattern(s) to a place

labgrid-client add-match [-h] PATTERN [PATTERN ...]

Positional Arguments

PATTERN

del-match

delete one (or multiple) match pattern(s) from a place

labgrid-client del-match [-h] PATTERN [PATTERN ...]

Positional Arguments

PATTERN

add-named-match

add one match pattern with a name to a place

labgrid-client add-named-match [-h] PATTERN NAME

Positional Arguments

PATTERN
NAME

acquire (lock)

acquire a place

labgrid-client acquire [-h] [--allow-unmatched]

Named Arguments

--allow-unmatched: allow missing resources for matches when locking the place

release (unlock)

release a place

labgrid-client release [-h] [-k]

Named Arguments

-k, --kick: release a place even if it is acquired by a different user

release-from

Atomically release a place, but only if acquired by a specific user.

Note that this command returns success as long as the specified user no longer owns the place, meaning it may be acquired by another user or not at all.

labgrid-client release-from [-h] HOST/USER

Positional Arguments

HOST/USER: User and host to match against when releasing

allow

allow another user to access a place

labgrid-client allow [-h] user

Positional Arguments

user: <host>/<username>

env

generate a labgrid environment file for a place

labgrid-client env [-h]

power (pw)

change (or get) a place’s power status

labgrid-client power [-h] [-t DELAY] [--name NAME] {on,off,cycle,get}

Positional Arguments

action: Possible choices: on, off, cycle, get

Named Arguments

-t, --delay: wait time in seconds between off and on during cycle
--name, -n: optional resource name

io

change (or get) a digital IO status

labgrid-client io [-h] {high,low,get} [name]

Positional Arguments

action

Possible choices: high, low, get

action

name

optional resource name

console (con)

connect to the console

labgrid-client console [-h] [-l] [-o] [--logfile FILE] [name]

Positional Arguments

name: optional resource name

Named Arguments

-l, --loop: keep trying to connect if the console is unavailable
-o, --listenonly: do not modify local terminal, do not send input from stdin
--logfile: Log output to FILE

dfu

communicate with device in DFU mode

labgrid-client dfu [-h] [--wait WAIT] [--name NAME]
                   {download,detach,list} [altsetting] [filename]

Positional Arguments

action

Possible choices: download, detach, list

action

altsetting

altsetting name or number (download, detach only)

filename

file to write into device (download only)

Named Arguments

--wait
--name, -n: optional resource name

fastboot

run fastboot

labgrid-client fastboot [-h] [--wait WAIT] [--name NAME] ...

Positional Arguments

ARG: fastboot arguments

Named Arguments

--wait
--name, -n: optional resource name

flashscript

Run arbitrary script with arguments to flash device

labgrid-client flashscript [-h] [--name NAME] script ...

Positional Arguments

script: Flashing script
ARG: script arguments

Named Arguments

--name, -n: optional resource name

bootstrap

start a bootloader

labgrid-client bootstrap [-h] [-w WAIT] [--name NAME] filename ...

Positional Arguments

filename: filename to boot on the target
ARG: extra bootstrap arguments

Named Arguments

-w, --wait
--name, -n: optional resource name

sd-mux

switch USB SD Muxer or get current mode

labgrid-client sd-mux [-h] [--name NAME] {dut,host,off,client,get}

Positional Arguments

action: Possible choices: dut, host, off, client, get

Named Arguments

--name, -n: optional resource name

usb-mux

switch USB Muxer

labgrid-client usb-mux [-h] [--name NAME]
                       {off,dut-device,host-dut,host-device,host-dut+host-device}

Positional Arguments

links: Possible choices: off, dut-device, host-dut, host-device, host-dut+host-device

Named Arguments

--name, -n: optional resource name

ssh

connect via ssh (with optional arguments)

labgrid-client ssh [-h] [--name NAME]

Named Arguments

--name, -n: optional resource name

Additional arguments are passed to the ssh subprocess.

scp

transfer file via scp

labgrid-client scp [-h] [--name NAME] src dst

Positional Arguments

src: source path (use :dir/file for remote side)
dst: destination path (use :dir/file for remote side)

Named Arguments

--name, -n: optional resource name

rsync

transfer files via rsync

labgrid-client rsync [-h] [--name NAME] src dst

Positional Arguments

src: source path (use :dir/file for remote side)
dst: destination path (use :dir/file for remote side)

Named Arguments

--name, -n: optional resource name

Additional arguments are passed to the rsync subprocess.

sshfs

mount via sshfs (blocking)

labgrid-client sshfs [-h] [--name NAME] path mountpoint

Positional Arguments

path: remote path on the target
mountpoint: local path

Named Arguments

--name, -n: optional resource name

forward

forward local port to remote target

labgrid-client forward [-h] [--name NAME] [--local [LOCAL:]REMOTE]
                       [--remote REMOTE:LOCAL]

Named Arguments

--name, -n: optional resource name
--local, -L: Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen
--remote, -R: Forward remote port REMOTE to local port LOCAL

telnet

connect via telnet

labgrid-client telnet [-h]

video

start a video stream

labgrid-client video [-h] [-q QUALITY] [-c CONTROLS] [--name NAME]

Named Arguments

-q, --quality: select a video quality (use ‘list’ to show options)
-c, --controls: configure v4l controls (such as ‘focus_auto=0,focus_absolute=40’)
--name, -n: optional resource name

audio

start a audio stream

labgrid-client audio [-h] [--name NAME]

Named Arguments

--name, -n: optional resource name

tmc

control a USB TMC device

labgrid-client tmc [-h] [--name NAME] SUBCOMMAND ...

Named Arguments

--name, -n: optional resource name

Sub-commands

cmd (c)

execute raw command

labgrid-client tmc cmd [-h] command [command ...]

Positional Arguments

command

query (q)

execute raw query

labgrid-client tmc query [-h] query [query ...]

Positional Arguments

query

screen

show or save a screenshot

labgrid-client tmc screen [-h] {show,save}

Positional Arguments

action: Possible choices: show, save

channel

use a channel

labgrid-client tmc channel [-h] channel {info,values}

Positional Arguments

channel
action: Possible choices: info, values

write-files

copy files onto mass storage device

labgrid-client write-files [OPTION]... -T SOURCE DEST
       labgrid-client write-files [OPTION]... [-t DIRECTORY] SOURCE...

Positional Arguments

SOURCE: source file(s) to copy
DEST: destination file name for SOURCE

Named Arguments

-w, --wait: storage poll timeout in seconds
-p, --partition: partition number to mount or 0 to mount whole disk (default: 1)
-t, --target-directory: copy all SOURCE files into DIRECTORY (default: partition root)
-T: copy SOURCE file and rename to DEST
--name, -n: optional resource name

write-image

write an image onto mass storage

labgrid-client write-image [-h] [-w WAIT] [-p PARTITION] [--skip SKIP]
                           [--seek SEEK] [--mode {dd,bmaptool}] [--name NAME]
                           filename

Positional Arguments

filename: filename to boot on the target

Named Arguments

-w, --wait

-p, --partition

partition number to write to

--skip

skip n 512-sized blocks at start of input

--seek

skip n 512-sized blocks at start of output

--mode

Possible choices: dd, bmaptool

Choose tool for writing images (default: dd)

--name, -n

optional resource name

reserve

create a reservation

labgrid-client reserve [-h] [--wait] [--shell] [--prio PRIO]
                       KEY=VALUE [KEY=VALUE ...]

Positional Arguments

KEY=VALUE: required tags

Named Arguments

--wait: wait until the reservation is allocated
--shell: format output as shell variables
--prio: priority relative to other reservations (default 0)

cancel-reservation

cancel a reservation

labgrid-client cancel-reservation [-h] [token]

Positional Arguments

token

wait

wait for a reservation to be allocated

labgrid-client wait [-h] [token]

Positional Arguments

token

reservations

list current reservations

labgrid-client reservations [-h]

export

export driver information to a file (needs environment with drivers)

labgrid-client export [-h] [--format {shell,shell-export,json}] filename

Positional Arguments

filename: output filename

Named Arguments

--format

Possible choices: shell, shell-export, json

output format (default: shell-export)

version

show version

labgrid-client version [-h]

Configuration File

The configuration file follows the description in labgrid-device-config(5).

Environment Variables

Various labgrid-client commands use the following environment variable:

LG_PLACE

This variable can be used to specify a place without using the -p option, the -p option overrides it.

LG_TOKEN

This variable can be used to specify a reservation for the wait command and for the + place expansion.

LG_STATE

This variable can be used to specify a state which the device transitions into before executing a command. Requires a configuration file and a Strategy specified for the device.

LG_INITIAL_STATE

This variable can be used to specify an initial state the device is known to be in. This is useful during development. The Strategy used must implement the force() method. A desired state must be set using LG_STATE or -s/--state.

LG_ENV

This variable can be used to specify the configuration file to use without using the --config option, the --config option overrides it.

LG_COORDINATOR

This variable can be used to set the default coordinator in the format HOST[:PORT] (instead of using the -x option).

LG_PROXY

This variable can be used to specify a SSH proxy hostname which should be used to connect to the coordinator and any resources which are normally accessed directly.

LG_HOSTNAME

Override the hostname used when accessing a resource. Typically only useful for CI pipelines where the hostname may not be consistent between pipeline stages.

LG_USERNAME

Override the username used when accessing a resource. Typically only useful for CI pipelines where the username may not be consistent between pipeline stages.

LG_SSH_CONNECT_TIMEOUT

Set the connection timeout when using SSH (The ConnectTimeout option). If unspecified, defaults to 30 seconds.

LG_AGENT_PREFIX

Add a prefix to .labgrid_agent_{agent_hash}.py allowing specification for where on the exporter it should be uploaded to.

Matches

Match patterns are used to assign a resource to a specific place. The format is: exporter/group/cls/name, exporter is the name of the exporting machine, group is a name defined within the exporter, cls is the class of the exported resource and name is its name. Wild cards in match patterns are explicitly allowed, * matches anything.

Adding Named Resources

If a target contains multiple Resources of the same type, named matches need to be used to address the individual resources. In addition to the match taken by add-match, add-named-match also takes a name for the resource. The other client commands support the name as an optional parameter and will inform the user that a name is required if multiple resources are found, but no name is given.

If one of the resources should be used by default when no resource name is explicitly specified, it can be named default.

Examples

To retrieve a list of places run:

$ labgrid-client places

To access a place, it needs to be acquired first, this can be done by running the acquire command and passing the placename as a -p parameter:

$ labgrid-client -p <placename> acquire

Open a console to the acquired place:

$ labgrid-client -p <placename> console

Add all resources with the group “example-group” to the place example-place:

$ labgrid-client -p example-place add-match */example-group/*/*