labgrid-client CLI

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.

labgrid-client

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

-x <address>, --coordinator <address>: coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408)

-c <config>, --config <config>: env config file (default: value from env variable LG_ENV)

-p <place>, --place <place>: place name/alias (default: value from env variable LG_PLACE)

-s <state>, --state <state>: strategy state to switch into before command (default: value from env varibale LG_STATE)

-i <initial_state>, --initial-state <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 <proxy>: proxy connections via given ssh host

labgrid-client acquire|lock

acquire a place

usage: labgrid-client acquire|lock [--allow-unmatched]

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

labgrid-client add-alias

add an alias to a place

usage: labgrid-client add-alias alias

alias

labgrid-client add-match

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

usage: labgrid-client add-match PATTERN [PATTERN ...]

pattern

labgrid-client add-named-match

add one match pattern with a name to a place

usage: labgrid-client add-named-match PATTERN NAME

pattern

name

labgrid-client allow

allow another user to access a place

usage: labgrid-client allow user

user: <host>/<username>

labgrid-client audio

start a audio stream

usage: labgrid-client audio [--name NAME]

--name <name>, -n <name>: optional resource name

labgrid-client bootstrap

start a bootloader

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

filename: filename to boot on the target

arg: extra bootstrap arguments

-w <wait>, --wait <wait>

--name <name>, -n <name>: optional resource name

labgrid-client cancel-reservation

cancel a reservation

usage: labgrid-client cancel-reservation [token]

token

labgrid-client console|con

connect to the console

usage: labgrid-client console|con [-l] [-o] [--logfile FILE] [name]

name: optional resource name

-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 <file>: Log output to FILE

labgrid-client create

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

usage: labgrid-client create

labgrid-client del-alias

delete an alias from a place

usage: labgrid-client del-alias alias

alias

labgrid-client del-match

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

usage: labgrid-client del-match PATTERN [PATTERN ...]

pattern

labgrid-client delete

delete an existing place

usage: labgrid-client delete

labgrid-client dfu

communicate with device in DFU mode

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

action: action

altsetting: altsetting name or number (download, detach only)

filename: file to write into device (download only)

--wait <wait>

--name <name>, -n <name>: optional resource name

labgrid-client env

generate a labgrid environment file for a place

usage: labgrid-client env

labgrid-client export

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

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

filename: output filename

--format {shell,shell-export,json}: output format (default: shell-export)

labgrid-client fastboot

run fastboot

usage: labgrid-client fastboot [--wait WAIT] [--name NAME] ...

arg: fastboot arguments

--wait <wait>

--name <name>, -n <name>: optional resource name

labgrid-client flashscript

Run arbitrary script with arguments to flash device

usage: labgrid-client flashscript [--name NAME] script ...

script: Flashing script

arg: script arguments

--name <name>, -n <name>: optional resource name

labgrid-client forward

forward local port to remote target

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

--name <name>, -n <name>: 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

labgrid-client io

change (or get) a digital IO status

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

action: action

name: optional resource name

labgrid-client monitor

monitor events from the coordinator

usage: labgrid-client monitor

labgrid-client places|p

list available places

usage: labgrid-client places|p [-a] [-r] [--sort-last-changed]

-a, --acquired

-r, --released

--sort-last-changed: sort by last changed date (oldest first)

labgrid-client power|pw

change (or get) a place’s power status

usage: labgrid-client power|pw [-t DELAY] [--name NAME] {on,off,cycle,get}

action

-t <delay>, --delay <delay>: wait time in seconds between off and on during cycle

--name <name>, -n <name>: optional resource name

labgrid-client release-from

atomically release a place, but only if locked by a specific user

usage: labgrid-client release-from HOST/USER

host/user: User and host to match against when releasing

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|unlock

release a place

usage: labgrid-client release|unlock [-k]

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

labgrid-client reservations

list current reservations

usage: labgrid-client reservations

labgrid-client reserve

create a reservation

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

key=value: required tags

--wait: wait until the reservation is allocated

--shell: format output as shell variables

--prio <prio>: priority relative to other reservations (default 0)

labgrid-client resources|r

list available resources

usage: labgrid-client resources|r [-a] [-e EXPORTER]
                                  [--sort-by-matched-place-change]
                                  [match]

match

-a, --acquired

-e <exporter>, --exporter <exporter>

--sort-by-matched-place-change: sort by matched place’s changed date (oldest first) and show place and date

labgrid-client rsync

transfer files via rsync

usage: labgrid-client rsync [--name NAME] src dst

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

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

--name <name>, -n <name>: optional resource name

Additional arguments are passed to the rsync subprocess.

labgrid-client scp

transfer file via scp

usage: labgrid-client scp [--name NAME] src dst

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

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

--name <name>, -n <name>: optional resource name

labgrid-client sd-mux

switch USB SD Muxer or get current mode

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

action

--name <name>, -n <name>: optional resource name

labgrid-client set-comment

update the place comment

usage: labgrid-client set-comment comment [comment ...]

comment

labgrid-client set-tags

update the place tags

usage: labgrid-client set-tags KEY=VALUE [KEY=VALUE ...]

key=value: use an empty value for deletion

labgrid-client show

show a place and related resources

usage: labgrid-client show

labgrid-client ssh

connect via ssh (with optional arguments)

usage: labgrid-client ssh [--name NAME]

--name <name>, -n <name>: optional resource name

Additional arguments are passed to the ssh subprocess.

labgrid-client sshfs

mount via sshfs (blocking)

usage: labgrid-client sshfs [--name NAME] path mountpoint

path: remote path on the target

mountpoint: local path

--name <name>, -n <name>: optional resource name

labgrid-client telnet

connect via telnet

usage: labgrid-client telnet

labgrid-client tmc

control a USB TMC device

usage: labgrid-client tmc [--name NAME] SUBCOMMAND ...

--name <name>, -n <name>: optional resource name

labgrid-client tmc channel

use a channel

usage: labgrid-client tmc channel channel {info,values}

channel

action

labgrid-client tmc cmd|c

execute raw command

usage: labgrid-client tmc cmd|c command [command ...]

command

labgrid-client tmc query|q

execute raw query

usage: labgrid-client tmc query|q query [query ...]

query

labgrid-client tmc screen

show or save a screenshot

usage: labgrid-client tmc screen {show,save}

action

labgrid-client usb-mux

switch USB Muxer

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

links

--name <name>, -n <name>: optional resource name

labgrid-client version

show version

usage: labgrid-client version

labgrid-client video

start a video stream

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

-q <quality>, --quality <quality>: select a video quality (use ‘list’ to show options)

-c <controls>, --controls <controls>: configure v4l controls (such as ‘focus_auto=0,focus_absolute=40’)

--name <name>, -n <name>: optional resource name

labgrid-client wait

wait for a reservation to be allocated

usage: labgrid-client wait [token]

token

labgrid-client who

list acquired places by user

usage: labgrid-client who [-e]

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

labgrid-client write-files

copy files onto mass storage device

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

source: source file(s) to copy

dest: destination file name for SOURCE

-w <wait>, --wait <wait>: storage poll timeout in seconds

-p <0-255>, --partition <0-255>: partition number to mount or 0 to mount whole disk (default: 1)

-t <directory>, --target-directory <directory>: copy all SOURCE files into DIRECTORY (default: partition root)

-T: copy SOURCE file and rename to DEST

--name <name>, -n <name>: optional resource name

labgrid-client write-image

write an image onto mass storage

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

filename: filename to boot on the target

-w <wait>, --wait <wait>

-p <partition>, --partition <partition>: partition number to write to

--skip <skip>: skip n 512-sized blocks at start of input

--seek <seek>: skip n 512-sized blocks at start of output

--mode {dd,bmaptool}: Choose tool for writing images (default: dd)

--name <name>, -n <name>: optional resource name

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/*/*