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