Scroll to navigation

LABGRID-CLIENT(1) labgrid LABGRID-CLIENT(1)

NAME

labgrid-client - labgrid's client interface to control boards

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 ...


coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408)

env config file (default: value from env variable LG_ENV)

place name/alias (default: value from env variable LG_PLACE)

strategy state to switch into before command (default: value from env varibale LG_STATE)

strategy state to force into before switching to desired state

enable debug mode (show python tracebacks)


proxy connections via given ssh host

labgrid-client acquire|lock

acquire a place

usage: labgrid-client acquire|lock [--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



labgrid-client add-match

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

usage: labgrid-client add-match 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




labgrid-client allow

allow another user to access a place

usage: labgrid-client allow 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 to boot on the target

extra bootstrap arguments


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

labgrid-client cancel-reservation

cancel a reservation

usage: labgrid-client cancel-reservation [token]



labgrid-client console|con

connect to the console

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


optional resource name

keep trying to connect if the console is unavailable

do not modify local terminal, do not send input from stdin

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



labgrid-client del-match

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

usage: labgrid-client del-match 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

altsetting name or number (download, detach only)

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


output filename

output format (default: shell-export)

labgrid-client fastboot

run fastboot

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


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 ...


Flashing script

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

Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen

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

optional resource name

labgrid-client monitor

monitor events from the coordinator

usage: labgrid-client monitor


labgrid-client netns

start a network namespace with access to NetworkInterface

usage: labgrid-client netns [--name NAME] [--address ADDRESS]


                            [--mac-address MAC_ADDRESS] [--nsenter [NSENTER]]


                            ...


command to execute in the namespace. If unspecified, $SHELL is invoked

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

assign address to interface (CIDR notation)

assign MAC address to interface

create nsenter wrapper script

labgrid-client places|p

list available places

usage: labgrid-client places|p [-a] [-r] [--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}



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


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]


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 ...]


required tags

wait until the reservation is allocated

format output as shell variables

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]





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


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

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


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

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}



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

labgrid-client set-comment

update the place comment

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



labgrid-client set-tags

update the place tags

usage: labgrid-client set-tags 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


remote path on the target

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}




labgrid-client tmc cmd|c

execute raw command

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



labgrid-client tmc query|q

execute raw query

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



labgrid-client tmc screen

show or save a screenshot

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



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}



--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]


select a video quality (use 'list' to show options)

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]



labgrid-client who

list acquired places by user

usage: labgrid-client who [-e]


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 file(s) to copy

destination file name for SOURCE

storage poll timeout in seconds

partition number to mount or 0 to mount whole disk (default: 1)

copy all SOURCE files into DIRECTORY (default: partition root)

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 to boot on the target


partition number to write to

skip n 512-sized blocks at start of input

skip n 512-sized blocks at start of output

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


SEE ALSO

labgrid-exporter(1)

AUTHOR

Jan Luebbe, Rouven Czerwinski

COPYRIGHT

2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski

2025