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

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

start a network namespace with access to NetworkInterface

    usage: labgrid-client netns [--name NAME] [--address ADDRESS]
                                [--mac-address MAC_ADDRESS] [--nsenter [NSENTER]]
                                ...

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

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

--address <address>, -a <address>
    assign address to interface (CIDR notation)

--mac-address <mac_address>
    assign MAC address to interface

--nsenter <nsenter>, -e <nsenter>
    create nsenter wrapper script

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

SEE ALSO

labgrid-exporter(1)

AUTHOR
Jan Luebbe, Rouven Czerwinski

COPYRIGHT
2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski