From 53309fb1675698196207bf3a34890ad6c425abc1 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Thu, 6 Nov 2025 15:39:43 +0100 Subject: [PATCH 1/7] doc/conf: avoid name conflict for `version` We should not import importlib.metadata.version as `version` because it clashes with sphinx config.version. import metadata and use metadata.version() for clarity. Signed-off-by: Jonas Rebmann --- doc/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 29ff581b9..ade05c7b7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,7 +21,7 @@ import sys sys.path.insert(0, os.path.abspath('..')) -from importlib.metadata import version +from importlib import metadata # Import read_the_docs theme import sphinx_rtd_theme @@ -65,7 +65,7 @@ # built documents. # # The full version, including alpha/beta/rc tags. -release = version('labgrid') +release = metadata.version('labgrid') # The short X.Y version. version = '.'.join(release.split('.')[:2]) From 667ec11dd16509a1db3983491f57f32316fb7cac Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 13:56:53 +0200 Subject: [PATCH 2/7] man: Migrate to doc/ As sphinx supports generating manpages, use it to simplify the process and drop the dependency on rst2man. All manpages are now tracked in doc/man. The Makefile in man/ remains for forward compatibility. Keep tracking manpages themselves in troff format so sphinx is not required for packaging, slightly update Documentation to reflect the changes requirements for manpage generation. Signed-off-by: Jonas Rebmann [bst: hide Debian-internal `labgrid-pytest` in documentation, but still generate man page (same behavior as before)] Signed-off-by: Bastian Krause --- .github/pull_request_template.md | 2 +- README.rst | 5 + doc/conf.py | 23 +- doc/man.rst | 3 +- doc/man/client.rst | 263 ++++++++++++++++- doc/man/coordinator.rst | 36 ++- doc/man/device-config.rst | 241 +++++++++++++++- doc/man/exporter.rst | 105 ++++++- man/labgrid-pytest.rst => doc/man/pytest.rst | 13 +- .../man/suggest.rst | 15 +- man/Makefile | 16 +- man/labgrid-client.1 | 35 +-- man/labgrid-client.rst | 272 ------------------ man/labgrid-coordinator.1 | 23 +- man/labgrid-coordinator.rst | 48 ---- man/labgrid-device-config.5 | 81 +++--- man/labgrid-device-config.rst | 253 ---------------- man/labgrid-exporter.1 | 31 +- man/labgrid-exporter.rst | 117 -------- man/labgrid-pytest.7 | 25 +- man/labgrid-suggest.1 | 25 +- 21 files changed, 777 insertions(+), 855 deletions(-) rename man/labgrid-pytest.rst => doc/man/pytest.rst (62%) rename man/labgrid-suggest.rst => doc/man/suggest.rst (74%) delete mode 100644 man/labgrid-client.rst delete mode 100644 man/labgrid-coordinator.rst delete mode 100644 man/labgrid-device-config.rst delete mode 100644 man/labgrid-exporter.rst diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index cfcdc7503..58484d536 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,7 +33,7 @@ Did you test the change locally? If yes, best to mention how you did it in the d ---> - [ ] PR has been tested - [ ] Man pages have been regenerated diff --git a/README.rst b/README.rst index 2ae9aafda..5cf33889b 100644 --- a/README.rst +++ b/README.rst @@ -135,6 +135,11 @@ Tests can now run via: venv $ python -m pytest --lg-env +To install sphinx and the dependencies needed for generating man pages and documentation run: + +.. code-block:: bash + + venv $ pip install '.[doc]' .. |license| image:: https://img.shields.io/badge/license-LGPLv2.1-blue.svg :alt: LGPLv2.1 diff --git a/doc/conf.py b/doc/conf.py index ade05c7b7..37797a76e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -156,7 +156,19 @@ # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'labgrid', 'labgrid Documentation', - [author], 1) + [author], 1), + ('man/client', 'labgrid-client', 'labgrid\'s client interface to control boards', + [author], 1), + ('man/coordinator', 'labgrid-coordinator', 'managing labgrid resources and places', + [author], 1), + ('man/device-config', 'labgrid-device-config', 'test configuration files', + [author], 5), + ('man/exporter', 'labgrid-exporter', 'interface to control boards', + [author], 1), + ('man/pytest', 'labgrid-pytest', 'labgrid integration for pytest', + [author], 7), + ('man/suggest', 'labgrid-suggest', 'generator for YAML config files', + [author], 1), ] @@ -185,7 +197,10 @@ autodoc_mock_imports = ['onewire', 'gi', 'gi.repository', - 'vxi11'] + 'vxi11', + 'pysnmp', + 'kasa', + 'kasa.iot'] # -- Options for autosection ---------------------------------------------- autosectionlabel_prefix_document = True @@ -203,6 +218,10 @@ def run_apidoc(app): main(cmd) def setup(app): + # Make version and date stable when generating manpages as they will be tracked in git + if app.outdir.parts[-1] == "man": + app.config.version = "" + app.config.today_fmt = "%Y" app.connect('builder-inited', run_apidoc) app.connect('doctree-read', write_literal_blocks) diff --git a/doc/man.rst b/doc/man.rst index e6d6f6360..0f173b19e 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -3,6 +3,7 @@ Manual Pages .. toctree:: man/client + man/coordinator man/device-config man/exporter - man/coordinator + man/suggest diff --git a/doc/man/client.rst b/doc/man/client.rst index bb9ce9f67..76cbb0b04 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,2 +1,263 @@ .. _labgrid-client: -.. include:: ../../man/labgrid-client.rst + +================ + labgrid-client +================ + +labgrid-client interface to control boards +========================================== + +SYNOPSIS +-------- + +``labgrid-client`` ``--help`` + +``labgrid-client`` -p + +``labgrid-client`` ``places|resources`` + +DESCRIPTION +----------- +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. + +OPTIONS +------- +-h, --help + display command line help +-p PLACE, --place PLACE + specify the place to operate on +-x ADDRESS, --coordinator ADDRESS + coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` +-c CONFIG, --config CONFIG + set the configuration file +-s STATE, --state STATE + set an initial state before executing a command, requires a configuration + file and strategy +-i INITIAL_STATE, --initial-state INITIAL_STATE + strategy state to force into before switching to desired state, requires a + desired state (``-s``/``--state``/``LG_STATE``) +-d, --debug + enable debugging +-v, --verbose + increase verbosity +-P PROXY, --proxy PROXY + proxy connections over ssh + +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. + +LABGRID-CLIENT COMMANDS +----------------------- +``monitor`` Monitor events from the coordinator + +``resources (r)`` List available resources + +``places (p)`` List available places + +``who`` List acquired places by user + +``show`` Show a place and related resources + +``create`` Add a new place (name supplied by -p parameter) + +``delete`` Delete an existing place + +``add-alias`` ``[alias]`` Add an alias to a place + +``del-alias`` ``[alias]`` Delete an alias from a place + +``set-comment`` ``[comment]`` Update or set the place comment + +``set-tags`` ``[key=value]`` Set place tags (key=value) + +``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES + +``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES + +``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place + +``acquire (lock)`` Acquire a place + +``allow`` ``[user]`` Allow another user to access a place + +``release (unlock)`` Release a place + +``release-from`` ``[host/user]`` 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. + +``env`` Generate a labgrid environment file for a place + +``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle + +``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get + +``console (con)`` ``[name]`` Connect to the console + +``dfu`` ``[arg]`` Run dfu commands + +``fastboot`` ``[arg]`` Run fastboot with argument + +``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device + +``bootstrap`` ``[filename]`` Start a bootloader + +``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off + +``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device + +``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. + +``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) + +``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) + +``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs + +``forward`` Forward local port to remote target + +``telnet`` Connect via telnet + +``video`` Start a video stream + +``audio`` Start an audio stream + +``tmc`` ``[command]`` Control a USB TMC device + +``write-files`` ``[filename(s)]`` Copy files onto mass storage device + +``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) + +``reserve`` ``[filter]`` Create a reservation + +``cancel-reservation`` ``[token]`` Cancel a pending reservation + +``wait`` ``[token]`` Wait for a reservation to be allocated + +``reservations`` List current reservations + +``export`` ``[filename]`` Export driver information to file (needs environment with drivers) + +``version`` Print the labgrid version + +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: + +.. code-block:: bash + + $ 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: + +.. code-block:: bash + + $ labgrid-client -p acquire + +Open a console to the acquired place: + +.. code-block:: bash + + $ labgrid-client -p console + +Add all resources with the group "example-group" to the place example-place: + +.. code-block:: bash + + $ labgrid-client -p example-place add-match */example-group/*/* + +SEE ALSO +-------- + +``labgrid-exporter``\(1) diff --git a/doc/man/coordinator.rst b/doc/man/coordinator.rst index c1c7afbd7..c89eccad4 100644 --- a/doc/man/coordinator.rst +++ b/doc/man/coordinator.rst @@ -1,2 +1,34 @@ -.. _labgrid-coordinator: -.. include:: ../../man/labgrid-coordinator.rst +===================== + labgrid-coordinator +===================== + +labgrid-coordinator managing labgrid resources and places +========================================================= + +SYNOPSIS +-------- + +``labgrid-coordinator`` ``--help`` + +DESCRIPTION +----------- +Labgrid is a scalable infrastructure and test architecture for embedded (linux) +systems. + +This is the man page for the coordinator. Clients and exporters connect to the +coordinator to publish resources, manage place configuration and handle mutual +exclusion. + +OPTIONS +------- +-h, --help + display command line help +-l ADDRESS, --listen ADDRESS + make coordinator listen on host and port +-d, --debug + enable debug mode + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-exporter``\(1) diff --git a/doc/man/device-config.rst b/doc/man/device-config.rst index dcf1a4427..d0e5ff914 100644 --- a/doc/man/device-config.rst +++ b/doc/man/device-config.rst @@ -1,2 +1,241 @@ .. _labgrid-device-config: -.. include:: ../../man/labgrid-device-config.rst + +======================= + labgrid-device-config +======================= + +labgrid test configuration files +================================ + +SYNOPSIS +-------- + +``*.yaml`` + +DESCRIPTION +----------- +To integrate a device into a labgrid test, labgrid needs to have a description +of the device and how to access it. + +This manual page is divided into section, each describing one top-level yaml key. + + +TARGETS +------- +The ``targets:`` top key configures a ``target``, it's ``drivers`` and ``resources``. + +The top level key is the name of the target, it needs both a ``resources`` and +``drivers`` subkey. The order of instantiated ``resources`` and ``drivers`` is +important, since they are parsed as an ordered dictionary and may depend on a +previous driver. + +For a list of available resources and drivers refer to +https://labgrid.readthedocs.io/en/latest/configuration.html. + +OPTIONS +------- +The ``options:`` top key configures various options such as the coordinator_address. + +OPTIONS KEYS +~~~~~~~~~~~~ + +``coordinator_address`` + takes as parameter the coordinator ``HOST[:PORT]`` to connect to. + Defaults to ``127.0.0.1:20408``. + +.. _labgrid-device-config-images: + +IMAGES +------ +The ``images:`` top key provides paths to access preconfigured images to flash +onto the board. The image paths can be either relative to the YAML file or +absolute. + +IMAGE KEYS +~~~~~~~~~~ + +The subkeys consist of image names as keys and their paths as values. The +corresponding name can than be used with the appropriate tool found under TOOLS. + +IMAGE EXAMPLE +~~~~~~~~~~~~~~ +Two configured images, one for the root filesystem, one for the bootloader: + +:: + + images: + root: "platform-v7a/images/root.img" + boot: "platform-v7a/images/barebox.img" + +TOOLS +----- +The ``tools:`` top key provides paths to binaries such as fastboot. + +TOOLS KEYS +~~~~~~~~~~ + +``dfu-util`` + Path to the dfu-util binary, used by the DFUDriver. + See: https://dfu-util.sourceforge.net/ + +``dpcmd`` + Path to the dpcmd binary, used by the DediprogFlashDriver. + See: https://github.com/DediProgSW/SF100Linux + +``fastboot`` + Path to the fastboot binary, used by the AndroidFastbootDriver. + See: https://developer.android.com/studio/releases/platform-tools + +``flashrom`` + Path to the flashrom binary, used by the FlashromDriver. + See: https://www.flashrom.org/ + +``imx_usb`` + Path to the imx_usb binary, used by the BDIMXUSBDriver. + See: https://github.com/boundarydevices/imx_usb_loader + +``imx-usb-loader`` + Path to the imx-usb-loader binary, used by the IMXUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c + +``jtagconfig`` + Path to the jtagconfig binary, used by the QuartusHPSDriver. + See: https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html + +``mxs-usb-loader`` + Path to the mxs-usb-loader binary, used by the MXSUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0 + +``openocd`` + Path to the openocd binary, used by the OpenOCDDriver. + See: https://openocd.org/ + +``quartus_hps`` + Path to the quartus_hps binary, used by the QuartusHPSDriver. + See: https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html + +``rk-usb-loader`` + Path to the rk-usb-loader binary, used by the RKUSBDriver. + See: https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c + +``rsync`` + Path to the rsync binary, used by the SSHDriver. + See: https://github.com/rsyncproject/rsync + +``scp`` + Path to the scp binary, used by the SSHDriver. + See: https://github.com/openssh/openssh-portable + +``sd-mux-ctrl`` + Path to the sd-mux-ctrl binary, used by the USBSDWireDriver. + See: https://git.tizen.org/cgit/tools/testlab/sd-mux/ + +``sispmctl`` + Path to the sispmctl binary, used by the SiSPMPowerDriver. + See: https://sispmctl.sourceforge.net/ + +``ssh`` + Path to the ssh binary, used by the SSHDriver. + See: https://github.com/openssh/openssh-portable + +``sshfs`` + Path to the sshfs binary, used by the SSHDriver. + See: https://github.com/libfuse/sshfs + +``uhubctl`` + Path to the uhubctl binary, used by the USBPowerDriver. + See: https://github.com/mvp/uhubctl + +``usbmuxctl`` + Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. + https://github.com/linux-automation/usbmuxctl + +``usbsdmux`` + Path to the usbsdmux tool, used by the USBSDMuxDriver. + See: https://github.com/linux-automation/usbsdmux + +``uuu-loader`` + Path to the uuu-loader binary, used by the UUUDriver. + See: https://github.com/nxp-imx/mfgtools + +``ykushcmd`` + Path to the ykushcmd binary, used by the YKUSHPowerDriver. + See: https://github.com/Yepkit/ykush + +The QEMUDriver expects a custom key set via its ``qemu_bin`` argument. +See https://www.qemu.org/ + +TOOLS EXAMPLE +~~~~~~~~~~~~~~ +Configure the tool path for ``imx-usb-loader``: + +:: + + tools: + imx-usb-loader: "/opt/labgrid-helper/imx-usb-loader" + +IMPORTS +------- +The ``imports`` key is a list of files or python modules which +are imported by the environment after loading the configuration. +Paths relative to the configuration file are also supported. +This is useful to load drivers and strategy which are contained in your +testsuite, since the import is done before instantiating the targets. + +IMPORTS EXAMPLE +~~~~~~~~~~~~~~~ +Import a local ``myfunctions.py`` file: + +:: + + imports: + - myfunctions.py + +EXAMPLES +-------- +A sample configuration with one ``main`` target, accessible via SerialPort +``/dev/ttyUSB0``, allowing usage of the ShellDriver: + +:: + + targets: + main: + resources: + RawSerialPort: + port: "/dev/ttyUSB0" + drivers: + SerialDriver: {} + ShellDriver: + prompt: 'root@[\w-]+:[^ ]+ ' + login_prompt: ' login: ' + username: 'root' + +A sample configuration with ``RemotePlace``, using the tools configuration and +importing the local ``mystrategy.py`` file. The ``MyStrategy`` strategy is contained +in the loaded local python file: + +:: + + targets: + main: + resources: + RemotePlace: + name: test-place + drivers: + SerialDriver: {} + ShellDriver: + prompt: 'root@[\w-]+:[^ ]+ ' + login_prompt: ' login: ' + username: 'root' + IMXUSBDriver: {} + MyStrategy: {} + tools: + imx-usb-loader: "/opt/lg-tools/imx-usb-loader" + imports: + - mystrategy.py + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-exporter``\(1) + diff --git a/doc/man/exporter.rst b/doc/man/exporter.rst index cc995a55f..c30ca3180 100644 --- a/doc/man/exporter.rst +++ b/doc/man/exporter.rst @@ -1,2 +1,105 @@ .. _labgrid-exporter: -.. include:: ../../man/labgrid-exporter.rst + +================== + labgrid-exporter +================== + +labgrid-exporter interface to control boards +============================================ + +SYNOPSIS +-------- + +``labgrid-exporter`` ``--help`` + +``labgrid-exporter`` ``*.yaml`` + +DESCRIPTION +----------- +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. + +This is the man page for the exporter, supporting the export of serial ports, +USB devices and various other controllers. + +OPTIONS +------- +-h, --help + display command line help +-x, --coordinator + coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` +-i, --isolated + enable isolated mode (always request SSH forwards) +-n, --name + the public name of the exporter +--hostname + hostname (or IP) published for accessing resources +--fqdn + use fully qualified domain name as default for hostname +-d, --debug + enable debug mode + +-i / --isolated +~~~~~~~~~~~~~~~ +This option enables isolated mode, which causes all exported resources being +marked as requiring SSH connection forwarding. +Isolated mode is useful when resources (such as NetworkSerialPorts) are not +directly accessible from the clients. +The client will then use SSH to create a port forward to the resource when +needed. + +-n / --name +~~~~~~~~~~~ +This option is used to configure the exporter name under which resources are +registered with the coordinator, which is useful when running multiple +exporters on the same host. +It defaults to the system hostname. + +--hostname +~~~~~~~~~~ +For resources like USBSerialPort, USBGenericExport or USBSigrokExport, the +exporter needs to provide a host name to set the exported value of the "host" +key. +If the system hostname is not resolvable via DNS, this option can be used to +override this default with another name (or an IP address). + +--fqdn +~~~~~~ +In some networks the fully qualified domain name may be needed to reach resources +on an exporter. This option changes the default to fqdn when no --hostname is +explicitly set. + +CONFIGURATION +------------- +The exporter uses a YAML configuration file which defines groups of related +resources. +See +for more information. + +ENVIRONMENT VARIABLES +--------------------- +The following environment variable can be used to configure labgrid-exporter. + +LG_COORDINATOR +~~~~~~~~~~~~~~ +This variable can be used to set the default coordinator in the format +``HOST[:PORT]`` (instead of using the ``-x`` option). + +EXAMPLES +-------- + +Start the exporter with the configuration file ``my-config.yaml``: + +.. code-block:: bash + + $ labgrid-exporter my-config.yaml + +Same as above, but with name ``myname``: + +.. code-block:: bash + + $ labgrid-exporter -n myname my-config.yaml + +SEE ALSO +-------- + +``labgrid-client``\(1), ``labgrid-device-config``\(5) diff --git a/man/labgrid-pytest.rst b/doc/man/pytest.rst similarity index 62% rename from man/labgrid-pytest.rst rename to doc/man/pytest.rst index 04956ca92..69bda443c 100644 --- a/man/labgrid-pytest.rst +++ b/doc/man/pytest.rst @@ -1,3 +1,5 @@ +:orphan: + ================ labgrid-pytest ================ @@ -5,17 +7,6 @@ labgrid-pytest labgrid integration for pytest ============================================= -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 7 -:Manual group: embedded testing - SYNOPSIS -------- diff --git a/man/labgrid-suggest.rst b/doc/man/suggest.rst similarity index 74% rename from man/labgrid-suggest.rst rename to doc/man/suggest.rst index dae73b67f..d79055405 100644 --- a/man/labgrid-suggest.rst +++ b/doc/man/suggest.rst @@ -5,19 +5,6 @@ labgrid-suggest generator for YAML config files =============================================== - -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - SYNOPSIS -------- @@ -46,7 +33,7 @@ EXAMPLES For a device that has an ``ID_SERIAL_SHORT`` key with a unique ID embedded in the USB-serial converter, ``labgrid-suggest`` shows two alternatives: -.. code-block:: yaml +.. code-block:: === added device === USBSerialPort for /devices/pci0000:00/0000:00:01.3/0000:02:00.0/usb1/1-3/1-3.1/1-3.1:1.0/ttyUSB0/tty/ttyUSB0 diff --git a/man/Makefile b/man/Makefile index 83189ca5c..c683d6ac0 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,17 +1,19 @@ PAGES := labgrid-client.1 labgrid-coordinator.1 labgrid-exporter.1 labgrid-device-config.5 labgrid-pytest.7 labgrid-suggest.1 COMPRESSED := labgrid-client.1.gz labgrid-coordinator.1.gz labgrid-exporter.1.gz labgrid-device-config.5.gz labgrid-pytest.7.gz labgrid-suggest.1.gz -%.1 %.5 %.7: %.rst - rst2man $< >$@.tmp - mv -f $@.tmp $@ +all: $(PAGES) -%.gz : % - gzip $< +compressed: $(COMPRESSED) +$(PAGES): %: ../doc/.build/man/% + cp $< $@ -all: $(PAGES) +../doc/.build/man/%: + $(MAKE) -C ../doc man + +%.gz : % + gzip $< -compressed: $(COMPRESSED) .PHONY: clean clean: diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 index 630511c34..ba9f4b79b 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -27,22 +27,23 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-CLIENT" "1" "" "0.0.1" "embedded testing" +.TH "LABGRID-CLIENT" "1" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-client \- labgrid-client interface to control boards -.SH SYNOPSIS +labgrid-client \- labgrid's client interface to control boards +.SH LABGRID-CLIENT INTERFACE TO CONTROL BOARDS +.SS SYNOPSIS .sp \fBlabgrid\-client\fP \fB\-\-help\fP .sp \fBlabgrid\-client\fP \-p .sp \fBlabgrid\-client\fP \fBplaces|resources\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. .sp This is the client to control a boards status and interface with it on remote machines. -.SH OPTIONS +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -74,10 +75,10 @@ increase verbosity .BI \-P \ PROXY\fR,\fB \ \-\-proxy \ PROXY proxy connections over ssh .UNINDENT -.SH CONFIGURATION FILE +.SS CONFIGURATION FILE .sp The configuration file follows the description in \fBlabgrid\-device\-config\fP(5). -.SH ENVIRONMENT VARIABLES +.SS ENVIRONMENT VARIABLES .sp Various labgrid\-client commands use the following environment variable: .SS LG_PLACE @@ -128,14 +129,14 @@ unspecified, defaults to 30 seconds. .sp Add a prefix to \fB\&.labgrid_agent_{agent_hash}.py\fP allowing specification for where on the exporter it should be uploaded to. -.SH MATCHES +.SS MATCHES .sp 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. -.SH LABGRID-CLIENT COMMANDS +.SS LABGRID\-CLIENT COMMANDS .sp \fBmonitor\fP Monitor events from the coordinator .sp @@ -234,7 +235,7 @@ not at all. \fBexport\fP \fB[filename]\fP Export driver information to file (needs environment with drivers) .sp \fBversion\fP Print the labgrid version -.SH ADDING NAMED RESOURCES +.SS ADDING NAMED RESOURCES .sp 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 \fImatch\fP taken by @@ -245,7 +246,7 @@ given. .sp If one of the resources should be used by default when no resource name is explicitly specified, it can be named \fBdefault\fP\&. -.SH EXAMPLES +.SS EXAMPLES .sp To retrieve a list of places run: .INDENT 0.0 @@ -287,18 +288,12 @@ $ labgrid\-client \-p example\-place add\-match */example\-group/*/* .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-client.rst b/man/labgrid-client.rst deleted file mode 100644 index 59f43c5a6..000000000 --- a/man/labgrid-client.rst +++ /dev/null @@ -1,272 +0,0 @@ -================ - labgrid-client -================ - -labgrid-client interface to control boards -========================================== - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - -SYNOPSIS --------- - -``labgrid-client`` ``--help`` - -``labgrid-client`` -p - -``labgrid-client`` ``places|resources`` - -DESCRIPTION ------------ -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. - -OPTIONS -------- --h, --help - display command line help --p PLACE, --place PLACE - specify the place to operate on --x ADDRESS, --coordinator ADDRESS - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --c CONFIG, --config CONFIG - set the configuration file --s STATE, --state STATE - set an initial state before executing a command, requires a configuration - file and strategy --i INITIAL_STATE, --initial-state INITIAL_STATE - strategy state to force into before switching to desired state, requires a - desired state (``-s``/``--state``/``LG_STATE``) --d, --debug - enable debugging --v, --verbose - increase verbosity --P PROXY, --proxy PROXY - proxy connections over ssh - -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. - -LABGRID-CLIENT COMMANDS ------------------------ -``monitor`` Monitor events from the coordinator - -``resources (r)`` List available resources - -``places (p)`` List available places - -``who`` List acquired places by user - -``show`` Show a place and related resources - -``create`` Add a new place (name supplied by -p parameter) - -``delete`` Delete an existing place - -``add-alias`` ``[alias]`` Add an alias to a place - -``del-alias`` ``[alias]`` Delete an alias from a place - -``set-comment`` ``[comment]`` Update or set the place comment - -``set-tags`` ``[key=value]`` Set place tags (key=value) - -``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES - -``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES - -``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place - -``acquire (lock)`` Acquire a place - -``allow`` ``[user]`` Allow another user to access a place - -``release (unlock)`` Release a place - -``release-from`` ``[host/user]`` 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. - -``env`` Generate a labgrid environment file for a place - -``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle - -``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get - -``console (con)`` ``[name]`` Connect to the console - -``dfu`` ``[arg]`` Run dfu commands - -``fastboot`` ``[arg]`` Run fastboot with argument - -``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device - -``bootstrap`` ``[filename]`` Start a bootloader - -``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off - -``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device - -``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. - -``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) - -``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) - -``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs - -``forward`` Forward local port to remote target - -``telnet`` Connect via telnet - -``video`` Start a video stream - -``audio`` Start an audio stream - -``tmc`` ``[command]`` Control a USB TMC device - -``write-files`` ``[filename(s)]`` Copy files onto mass storage device - -``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) - -``reserve`` ``[filter]`` Create a reservation - -``cancel-reservation`` ``[token]`` Cancel a pending reservation - -``wait`` ``[token]`` Wait for a reservation to be allocated - -``reservations`` List current reservations - -``export`` ``[filename]`` Export driver information to file (needs environment with drivers) - -``version`` Print the labgrid version - -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: - -.. code-block:: bash - - $ 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: - -.. code-block:: bash - - $ labgrid-client -p acquire - -Open a console to the acquired place: - -.. code-block:: bash - - $ labgrid-client -p console - -Add all resources with the group "example-group" to the place example-place: - -.. code-block:: bash - - $ labgrid-client -p example-place add-match */example-group/*/* - -SEE ALSO --------- - -``labgrid-exporter``\(1) diff --git a/man/labgrid-coordinator.1 b/man/labgrid-coordinator.1 index 0595b3098..f3a31faee 100644 --- a/man/labgrid-coordinator.1 +++ b/man/labgrid-coordinator.1 @@ -27,13 +27,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-COORDINATOR" "1" "" "0.0.1" "embedded testing" +.TH "LABGRID-COORDINATOR" "1" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-coordinator \- labgrid-coordinator managing labgrid resources and places -.SH SYNOPSIS +labgrid-coordinator \- managing labgrid resources and places +.SH LABGRID-COORDINATOR MANAGING LABGRID RESOURCES AND PLACES +.SS SYNOPSIS .sp \fBlabgrid\-coordinator\fP \fB\-\-help\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. @@ -41,7 +42,7 @@ systems. This is the man page for the coordinator. Clients and exporters connect to the coordinator to publish resources, manage place configuration and handle mutual exclusion. -.SH OPTIONS +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -53,18 +54,12 @@ make coordinator listen on host and port .B \-d\fP,\fB \-\-debug enable debug mode .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-coordinator.rst b/man/labgrid-coordinator.rst deleted file mode 100644 index 9b651e9e7..000000000 --- a/man/labgrid-coordinator.rst +++ /dev/null @@ -1,48 +0,0 @@ -===================== - labgrid-coordinator -===================== - -labgrid-coordinator managing labgrid resources and places -========================================================= - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``labgrid-coordinator`` ``--help`` - -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) -systems. - -This is the man page for the coordinator. Clients and exporters connect to the -coordinator to publish resources, manage place configuration and handle mutual -exclusion. - -OPTIONS -------- --h, --help - display command line help --l ADDRESS, --listen ADDRESS - make coordinator listen on host and port --d, --debug - enable debug mode - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-exporter``\(1) diff --git a/man/labgrid-device-config.5 b/man/labgrid-device-config.5 index 459756b9c..affe55b59 100644 --- a/man/labgrid-device-config.5 +++ b/man/labgrid-device-config.5 @@ -27,19 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-DEVICE-CONFIG" "5" "" "0.0.1" "embedded testing" +.TH "LABGRID-DEVICE-CONFIG" "5" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-device-config \- labgrid test configuration files -.SH SYNOPSIS +labgrid-device-config \- test configuration files +.SH LABGRID TEST CONFIGURATION FILES +.SS SYNOPSIS .sp \fB*.yaml\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp To integrate a device into a labgrid test, labgrid needs to have a description of the device and how to access it. .sp This manual page is divided into section, each describing one top\-level yaml key. -.SH TARGETS +.SS TARGETS .sp The \fBtargets:\fP top key configures a \fBtarget\fP, it\(aqs \fBdrivers\fP and \fBresources\fP\&. .sp @@ -49,8 +50,8 @@ important, since they are parsed as an ordered dictionary and may depend on a previous driver. .sp For a list of available resources and drivers refer to - \&. -.SH OPTIONS +\X'tty: link https://labgrid.readthedocs.io/en/latest/configuration.html'\fI\%https://labgrid.readthedocs.io/en/latest/configuration.html\fP\X'tty: link'\&. +.SS OPTIONS .sp The \fBoptions:\fP top key configures various options such as the coordinator_address. .SS OPTIONS KEYS @@ -60,7 +61,7 @@ The \fBoptions:\fP top key configures various options such as the coordinator_ad takes as parameter the coordinator \fBHOST[:PORT]\fP to connect to. Defaults to \fB127.0.0.1:20408\fP\&. .UNINDENT -.SH IMAGES +.SS IMAGES .sp The \fBimages:\fP top key provides paths to access preconfigured images to flash onto the board. The image paths can be either relative to the YAML file or @@ -82,7 +83,7 @@ images: .EE .UNINDENT .UNINDENT -.SH TOOLS +.SS TOOLS .sp The \fBtools:\fP top key provides paths to binaries such as fastboot. .SS TOOLS KEYS @@ -90,95 +91,95 @@ The \fBtools:\fP top key provides paths to binaries such as fastboot. .TP .B \fBdfu\-util\fP Path to the dfu\-util binary, used by the DFUDriver. -See: +See: \X'tty: link https://dfu-util.sourceforge.net/'\fI\%https://dfu\-util.sourceforge.net/\fP\X'tty: link' .TP .B \fBdpcmd\fP Path to the dpcmd binary, used by the DediprogFlashDriver. -See: +See: \X'tty: link https://github.com/DediProgSW/SF100Linux'\fI\%https://github.com/DediProgSW/SF100Linux\fP\X'tty: link' .TP .B \fBfastboot\fP Path to the fastboot binary, used by the AndroidFastbootDriver. -See: +See: \X'tty: link https://developer.android.com/studio/releases/platform-tools'\fI\%https://developer.android.com/studio/releases/platform\-tools\fP\X'tty: link' .TP .B \fBflashrom\fP Path to the flashrom binary, used by the FlashromDriver. -See: +See: \X'tty: link https://www.flashrom.org/'\fI\%https://www.flashrom.org/\fP\X'tty: link' .TP .B \fBimx_usb\fP Path to the imx_usb binary, used by the BDIMXUSBDriver. -See: +See: \X'tty: link https://github.com/boundarydevices/imx_usb_loader'\fI\%https://github.com/boundarydevices/imx_usb_loader\fP\X'tty: link' .TP .B \fBimx\-usb\-loader\fP Path to the imx\-usb\-loader binary, used by the IMXUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx\-usb\-loader.c\fP\X'tty: link' .TP .B \fBjtagconfig\fP Path to the jtagconfig binary, used by the QuartusHPSDriver. -See: +See: \X'tty: link https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html'\fI\%https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html\fP\X'tty: link' .TP .B \fBmxs\-usb\-loader\fP Path to the mxs\-usb\-loader binary, used by the MXSUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs\-usb\-loader.c?h=v2017.03.0\fP\X'tty: link' .TP .B \fBopenocd\fP Path to the openocd binary, used by the OpenOCDDriver. -See: +See: \X'tty: link https://openocd.org/'\fI\%https://openocd.org/\fP\X'tty: link' .TP .B \fBquartus_hps\fP Path to the quartus_hps binary, used by the QuartusHPSDriver. -See: +See: \X'tty: link https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html'\fI\%https://www.intel.com/content/www/us/en/docs/programmable/683039/22\-3/hps\-flash\-programmer.html\fP\X'tty: link' .TP .B \fBrk\-usb\-loader\fP Path to the rk\-usb\-loader binary, used by the RKUSBDriver. -See: +See: \X'tty: link https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c'\fI\%https://git.pengutronix.de/cgit/barebox/tree/scripts/rk\-usb\-loader.c\fP\X'tty: link' .TP .B \fBrsync\fP Path to the rsync binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/rsyncproject/rsync'\fI\%https://github.com/rsyncproject/rsync\fP\X'tty: link' .TP .B \fBscp\fP Path to the scp binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/openssh/openssh-portable'\fI\%https://github.com/openssh/openssh\-portable\fP\X'tty: link' .TP .B \fBsd\-mux\-ctrl\fP Path to the sd\-mux\-ctrl binary, used by the USBSDWireDriver. -See: +See: \X'tty: link https://git.tizen.org/cgit/tools/testlab/sd-mux/'\fI\%https://git.tizen.org/cgit/tools/testlab/sd\-mux/\fP\X'tty: link' .TP .B \fBsispmctl\fP Path to the sispmctl binary, used by the SiSPMPowerDriver. -See: +See: \X'tty: link https://sispmctl.sourceforge.net/'\fI\%https://sispmctl.sourceforge.net/\fP\X'tty: link' .TP .B \fBssh\fP Path to the ssh binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/openssh/openssh-portable'\fI\%https://github.com/openssh/openssh\-portable\fP\X'tty: link' .TP .B \fBsshfs\fP Path to the sshfs binary, used by the SSHDriver. -See: +See: \X'tty: link https://github.com/libfuse/sshfs'\fI\%https://github.com/libfuse/sshfs\fP\X'tty: link' .TP .B \fBuhubctl\fP Path to the uhubctl binary, used by the USBPowerDriver. -See: +See: \X'tty: link https://github.com/mvp/uhubctl'\fI\%https://github.com/mvp/uhubctl\fP\X'tty: link' .TP .B \fBusbmuxctl\fP Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. - +\X'tty: link https://github.com/linux-automation/usbmuxctl'\fI\%https://github.com/linux\-automation/usbmuxctl\fP\X'tty: link' .TP .B \fBusbsdmux\fP Path to the usbsdmux tool, used by the USBSDMuxDriver. -See: +See: \X'tty: link https://github.com/linux-automation/usbsdmux'\fI\%https://github.com/linux\-automation/usbsdmux\fP\X'tty: link' .TP .B \fBuuu\-loader\fP Path to the uuu\-loader binary, used by the UUUDriver. -See: +See: \X'tty: link https://github.com/nxp-imx/mfgtools'\fI\%https://github.com/nxp\-imx/mfgtools\fP\X'tty: link' .TP .B \fBykushcmd\fP Path to the ykushcmd binary, used by the YKUSHPowerDriver. -See: +See: \X'tty: link https://github.com/Yepkit/ykush'\fI\%https://github.com/Yepkit/ykush\fP\X'tty: link' .UNINDENT .sp The QEMUDriver expects a custom key set via its \fBqemu_bin\fP argument. -See +See \X'tty: link https://www.qemu.org/'\fI\%https://www.qemu.org/\fP\X'tty: link' .SS TOOLS EXAMPLE .sp Configure the tool path for \fBimx\-usb\-loader\fP: @@ -191,7 +192,7 @@ tools: .EE .UNINDENT .UNINDENT -.SH IMPORTS +.SS IMPORTS .sp The \fBimports\fP key is a list of files or python modules which are imported by the environment after loading the configuration. @@ -210,7 +211,7 @@ imports: .EE .UNINDENT .UNINDENT -.SH EXAMPLES +.SS EXAMPLES .sp A sample configuration with one \fBmain\fP target, accessible via SerialPort \fB/dev/ttyUSB0\fP, allowing usage of the ShellDriver: @@ -260,18 +261,12 @@ imports: .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-device-config.rst b/man/labgrid-device-config.rst deleted file mode 100644 index aad5bb402..000000000 --- a/man/labgrid-device-config.rst +++ /dev/null @@ -1,253 +0,0 @@ -======================= - labgrid-device-config -======================= - -labgrid test configuration files -================================ - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 5 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``*.yaml`` - -DESCRIPTION ------------ -To integrate a device into a labgrid test, labgrid needs to have a description -of the device and how to access it. - -This manual page is divided into section, each describing one top-level yaml key. - - -TARGETS -------- -The ``targets:`` top key configures a ``target``, it's ``drivers`` and ``resources``. - -The top level key is the name of the target, it needs both a ``resources`` and -``drivers`` subkey. The order of instantiated ``resources`` and ``drivers`` is -important, since they are parsed as an ordered dictionary and may depend on a -previous driver. - -For a list of available resources and drivers refer to -https://labgrid.readthedocs.io/en/latest/configuration.html. - -OPTIONS -------- -The ``options:`` top key configures various options such as the coordinator_address. - -OPTIONS KEYS -~~~~~~~~~~~~ - -``coordinator_address`` - takes as parameter the coordinator ``HOST[:PORT]`` to connect to. - Defaults to ``127.0.0.1:20408``. - -.. _labgrid-device-config-images: - -IMAGES ------- -The ``images:`` top key provides paths to access preconfigured images to flash -onto the board. The image paths can be either relative to the YAML file or -absolute. - -IMAGE KEYS -~~~~~~~~~~ - -The subkeys consist of image names as keys and their paths as values. The -corresponding name can than be used with the appropriate tool found under TOOLS. - -IMAGE EXAMPLE -~~~~~~~~~~~~~~ -Two configured images, one for the root filesystem, one for the bootloader: - -:: - - images: - root: "platform-v7a/images/root.img" - boot: "platform-v7a/images/barebox.img" - -TOOLS ------ -The ``tools:`` top key provides paths to binaries such as fastboot. - -TOOLS KEYS -~~~~~~~~~~ - -``dfu-util`` - Path to the dfu-util binary, used by the DFUDriver. - See: https://dfu-util.sourceforge.net/ - -``dpcmd`` - Path to the dpcmd binary, used by the DediprogFlashDriver. - See: https://github.com/DediProgSW/SF100Linux - -``fastboot`` - Path to the fastboot binary, used by the AndroidFastbootDriver. - See: https://developer.android.com/studio/releases/platform-tools - -``flashrom`` - Path to the flashrom binary, used by the FlashromDriver. - See: https://www.flashrom.org/ - -``imx_usb`` - Path to the imx_usb binary, used by the BDIMXUSBDriver. - See: https://github.com/boundarydevices/imx_usb_loader - -``imx-usb-loader`` - Path to the imx-usb-loader binary, used by the IMXUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/imx/imx-usb-loader.c - -``jtagconfig`` - Path to the jtagconfig binary, used by the QuartusHPSDriver. - See: https://www.intel.com/content/www/us/en/docs/programmable/683689/current/jtagconfig.html - -``mxs-usb-loader`` - Path to the mxs-usb-loader binary, used by the MXSUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/mxs-usb-loader.c?h=v2017.03.0 - -``openocd`` - Path to the openocd binary, used by the OpenOCDDriver. - See: https://openocd.org/ - -``quartus_hps`` - Path to the quartus_hps binary, used by the QuartusHPSDriver. - See: https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html - -``rk-usb-loader`` - Path to the rk-usb-loader binary, used by the RKUSBDriver. - See: https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c - -``rsync`` - Path to the rsync binary, used by the SSHDriver. - See: https://github.com/rsyncproject/rsync - -``scp`` - Path to the scp binary, used by the SSHDriver. - See: https://github.com/openssh/openssh-portable - -``sd-mux-ctrl`` - Path to the sd-mux-ctrl binary, used by the USBSDWireDriver. - See: https://git.tizen.org/cgit/tools/testlab/sd-mux/ - -``sispmctl`` - Path to the sispmctl binary, used by the SiSPMPowerDriver. - See: https://sispmctl.sourceforge.net/ - -``ssh`` - Path to the ssh binary, used by the SSHDriver. - See: https://github.com/openssh/openssh-portable - -``sshfs`` - Path to the sshfs binary, used by the SSHDriver. - See: https://github.com/libfuse/sshfs - -``uhubctl`` - Path to the uhubctl binary, used by the USBPowerDriver. - See: https://github.com/mvp/uhubctl - -``usbmuxctl`` - Path to the usbmuxctl tool, used by the LXAUSBMuxDriver. - https://github.com/linux-automation/usbmuxctl - -``usbsdmux`` - Path to the usbsdmux tool, used by the USBSDMuxDriver. - See: https://github.com/linux-automation/usbsdmux - -``uuu-loader`` - Path to the uuu-loader binary, used by the UUUDriver. - See: https://github.com/nxp-imx/mfgtools - -``ykushcmd`` - Path to the ykushcmd binary, used by the YKUSHPowerDriver. - See: https://github.com/Yepkit/ykush - -The QEMUDriver expects a custom key set via its ``qemu_bin`` argument. -See https://www.qemu.org/ - -TOOLS EXAMPLE -~~~~~~~~~~~~~~ -Configure the tool path for ``imx-usb-loader``: - -:: - - tools: - imx-usb-loader: "/opt/labgrid-helper/imx-usb-loader" - -IMPORTS -------- -The ``imports`` key is a list of files or python modules which -are imported by the environment after loading the configuration. -Paths relative to the configuration file are also supported. -This is useful to load drivers and strategy which are contained in your -testsuite, since the import is done before instantiating the targets. - -IMPORTS EXAMPLE -~~~~~~~~~~~~~~~ -Import a local ``myfunctions.py`` file: - -:: - - imports: - - myfunctions.py - -EXAMPLES --------- -A sample configuration with one ``main`` target, accessible via SerialPort -``/dev/ttyUSB0``, allowing usage of the ShellDriver: - -:: - - targets: - main: - resources: - RawSerialPort: - port: "/dev/ttyUSB0" - drivers: - SerialDriver: {} - ShellDriver: - prompt: 'root@[\w-]+:[^ ]+ ' - login_prompt: ' login: ' - username: 'root' - -A sample configuration with ``RemotePlace``, using the tools configuration and -importing the local ``mystrategy.py`` file. The ``MyStrategy`` strategy is contained -in the loaded local python file: - -:: - - targets: - main: - resources: - RemotePlace: - name: test-place - drivers: - SerialDriver: {} - ShellDriver: - prompt: 'root@[\w-]+:[^ ]+ ' - login_prompt: ' login: ' - username: 'root' - IMXUSBDriver: {} - MyStrategy: {} - tools: - imx-usb-loader: "/opt/lg-tools/imx-usb-loader" - imports: - - mystrategy.py - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-exporter``\(1) - diff --git a/man/labgrid-exporter.1 b/man/labgrid-exporter.1 index 074b51db2..93c8b1a54 100644 --- a/man/labgrid-exporter.1 +++ b/man/labgrid-exporter.1 @@ -27,21 +27,22 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-EXPORTER" "1" "" "0.0.1" "embedded testing" +.TH "LABGRID-EXPORTER" "1" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-exporter \- labgrid-exporter interface to control boards -.SH SYNOPSIS +labgrid-exporter \- interface to control boards +.SH LABGRID-EXPORTER INTERFACE TO CONTROL BOARDS +.SS SYNOPSIS .sp \fBlabgrid\-exporter\fP \fB\-\-help\fP .sp \fBlabgrid\-exporter\fP \fB*.yaml\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. .sp This is the man page for the exporter, supporting the export of serial ports, USB devices and various other controllers. -.SH OPTIONS +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -91,20 +92,20 @@ override this default with another name (or an IP address). In some networks the fully qualified domain name may be needed to reach resources on an exporter. This option changes the default to fqdn when no \-\-hostname is explicitly set. -.SH CONFIGURATION +.SS CONFIGURATION .sp The exporter uses a YAML configuration file which defines groups of related resources. -See < > +See <\X'tty: link https://labgrid.readthedocs.io/en/latest/configuration.html#exporter-configuration'\fI\%https://labgrid.readthedocs.io/en/latest/configuration.html#exporter\-configuration\fP\X'tty: link'> for more information. -.SH ENVIRONMENT VARIABLES +.SS ENVIRONMENT VARIABLES .sp The following environment variable can be used to configure labgrid\-exporter. .SS LG_COORDINATOR .sp This variable can be used to set the default coordinator in the format \fBHOST[:PORT]\fP (instead of using the \fB\-x\fP option). -.SH EXAMPLES +.SS EXAMPLES .sp Start the exporter with the configuration file \fBmy\-config.yaml\fP: .INDENT 0.0 @@ -125,18 +126,12 @@ $ labgrid\-exporter \-n myname my\-config.yaml .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-client\fP(1), \fBlabgrid\-device\-config\fP(5) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-exporter.rst b/man/labgrid-exporter.rst deleted file mode 100644 index 72b08fcd7..000000000 --- a/man/labgrid-exporter.rst +++ /dev/null @@ -1,117 +0,0 @@ -================== - labgrid-exporter -================== - -labgrid-exporter interface to control boards -============================================ - - -:Author: Rouven Czerwinski -:organization: Labgrid-Project -:Copyright: Copyright (C) 2016-2025 Pengutronix. This library is free software; - you can redistribute it and/or modify it under the terms of the GNU - Lesser General Public License as published by the Free Software - Foundation; either version 2.1 of the License, or (at your option) - any later version. -:Version: 0.0.1 -:Manual section: 1 -:Manual group: embedded testing - - - -SYNOPSIS --------- - -``labgrid-exporter`` ``--help`` - -``labgrid-exporter`` ``*.yaml`` - -DESCRIPTION ------------ -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. - -This is the man page for the exporter, supporting the export of serial ports, -USB devices and various other controllers. - -OPTIONS -------- --h, --help - display command line help --x, --coordinator - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --i, --isolated - enable isolated mode (always request SSH forwards) --n, --name - the public name of the exporter ---hostname - hostname (or IP) published for accessing resources ---fqdn - use fully qualified domain name as default for hostname --d, --debug - enable debug mode - --i / --isolated -~~~~~~~~~~~~~~~ -This option enables isolated mode, which causes all exported resources being -marked as requiring SSH connection forwarding. -Isolated mode is useful when resources (such as NetworkSerialPorts) are not -directly accessible from the clients. -The client will then use SSH to create a port forward to the resource when -needed. - --n / --name -~~~~~~~~~~~ -This option is used to configure the exporter name under which resources are -registered with the coordinator, which is useful when running multiple -exporters on the same host. -It defaults to the system hostname. - ---hostname -~~~~~~~~~~ -For resources like USBSerialPort, USBGenericExport or USBSigrokExport, the -exporter needs to provide a host name to set the exported value of the "host" -key. -If the system hostname is not resolvable via DNS, this option can be used to -override this default with another name (or an IP address). - ---fqdn -~~~~~~ -In some networks the fully qualified domain name may be needed to reach resources -on an exporter. This option changes the default to fqdn when no --hostname is -explicitly set. - -CONFIGURATION -------------- -The exporter uses a YAML configuration file which defines groups of related -resources. -See -for more information. - -ENVIRONMENT VARIABLES ---------------------- -The following environment variable can be used to configure labgrid-exporter. - -LG_COORDINATOR -~~~~~~~~~~~~~~ -This variable can be used to set the default coordinator in the format -``HOST[:PORT]`` (instead of using the ``-x`` option). - -EXAMPLES --------- - -Start the exporter with the configuration file ``my-config.yaml``: - -.. code-block:: bash - - $ labgrid-exporter my-config.yaml - -Same as above, but with name ``myname``: - -.. code-block:: bash - - $ labgrid-exporter -n myname my-config.yaml - -SEE ALSO --------- - -``labgrid-client``\(1), ``labgrid-device-config``\(5) diff --git a/man/labgrid-pytest.7 b/man/labgrid-pytest.7 index 0d0c263a5..a7aed7100 100644 --- a/man/labgrid-pytest.7 +++ b/man/labgrid-pytest.7 @@ -27,13 +27,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-PYTEST" "7" "" "0.0.1" "embedded testing" +.TH "LABGRID-PYTEST" "7" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-pytest \- labgrid-pytest labgrid integration for pytest -.SH SYNOPSIS +labgrid-pytest \- labgrid integration for pytest +.SH LABGRID-PYTEST LABGRID INTEGRATION FOR PYTEST +.SS SYNOPSIS .sp \fBpytest \-\-lg\-env\fP \fB*.yaml\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid ships a pytest plugin to integrate with the pytest infrastructure. It is activated if the \fI\-\-lg\-env\fP parameter is supplied to the pytest command. @@ -42,8 +43,8 @@ The labgrid plugin parses the supplied configuration yaml file as described in \fBlabgrid\-device\-config\fP(5) and allows the usage of the target and environment fixtures. The complete documentation is available at - \&. -.SH EXAMPLES +\X'tty: link https://labgrid.readthedocs.io/en/latest/usage.html#pytest-plugin'\fI\%https://labgrid.readthedocs.io/en/latest/usage.html#pytest\-plugin\fP\X'tty: link'\&. +.SS EXAMPLES .sp Start tests with \fBmyconfig.yaml\fP and directory \fBtests\fP: .INDENT 0.0 @@ -54,18 +55,12 @@ $ pytest \-\-lg\-env myconfig.yaml tests .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-device\-config\fP(5) .SH AUTHOR -Rouven Czerwinski - -Organization: Labgrid-Project +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . diff --git a/man/labgrid-suggest.1 b/man/labgrid-suggest.1 index a4305acca..34babce21 100644 --- a/man/labgrid-suggest.1 +++ b/man/labgrid-suggest.1 @@ -27,22 +27,23 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-SUGGEST" "1" "" "0.0.1" "embedded testing" +.TH "LABGRID-SUGGEST" "1" "Nov 05, 2025" "" "labgrid" .SH NAME -labgrid-suggest \- labgrid-suggest generator for YAML config files -.SH SYNOPSIS +labgrid-suggest \- generator for YAML config files +.SH LABGRID-SUGGEST GENERATOR FOR YAML CONFIG FILES +.SS SYNOPSIS .sp \fBlabgrid\-suggest\fP \fB\-\-help\fP .sp \fBlabgrid\-suggest\fP \fB\-\-debug\fP -.SH DESCRIPTION +.SS DESCRIPTION .sp Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. .sp This is the man page for a helper tool which will output the proper YAML formatted snippets for udev scanned devices. The snippets can be added under the resource key in an environment configuration. -.SH OPTIONS +.SS OPTIONS .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help @@ -51,7 +52,7 @@ display command line help .B \-d\fP,\fB \-\-debug enable debug mode .UNINDENT -.SH EXAMPLES +.SS EXAMPLES .sp For a device that has an \fBID_SERIAL_SHORT\fP key with a unique ID embedded in the USB\-serial converter, \fBlabgrid\-suggest\fP shows two alternatives: @@ -80,16 +81,12 @@ USBSerialPort: .EE .UNINDENT .UNINDENT -.SH SEE ALSO +.SS SEE ALSO .sp \fBlabgrid\-device\-config\fP(5) - -Organization: Labgrid-Project +.SH AUTHOR +Jan Luebbe, Rouven Czerwinski .SH COPYRIGHT -Copyright (C) 2016-2025 Pengutronix. This library is free software; -you can redistribute it and/or modify it under the terms of the GNU -Lesser General Public License as published by the Free Software -Foundation; either version 2.1 of the License, or (at your option) -any later version. +2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski .\" Generated by docutils manpage writer. . From bb4edb0a6918487bad815850cc72bdf02cb01460 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 11:06:53 +0200 Subject: [PATCH 3/7] remote/client: separate ArgumentParser() definition This is an idiomatic way of setting up argument parsers and allows the parser to be re-used for manpage/documentation generation. Signed-off-by: Jonas Rebmann [bst: rebased] Signed-off-by: Bastian Krause --- labgrid/remote/client.py | 75 ++++++++++++++++++++++++------------- man/labgrid-client.1 | 2 +- man/labgrid-coordinator.1 | 2 +- man/labgrid-device-config.5 | 2 +- man/labgrid-exporter.1 | 2 +- man/labgrid-pytest.7 | 2 +- man/labgrid-suggest.1 | 2 +- 7 files changed, 54 insertions(+), 33 deletions(-) diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py index 9b6e602da..a9f00298b 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1758,25 +1758,7 @@ def __str__(self): return self.value -def main(): - import inspect - - basicConfig( - level=logging.WARNING, - stream=sys.stderr, - ) - - StepLogger.start() - processwrapper.enable_logging() - - # Support both legacy variables and properly namespaced ones - place = os.environ.get("PLACE", None) - place = os.environ.get("LG_PLACE", place) - state = os.environ.get("STATE", None) - state = os.environ.get("LG_STATE", state) - initial_state = os.environ.get("LG_INITIAL_STATE", None) - token = os.environ.get("LG_TOKEN", None) - +def get_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser() parser.add_argument( "-x", @@ -1789,24 +1771,19 @@ def main(): "-c", "--config", type=str, - default=os.environ.get("LG_ENV"), help="env config file (default: value from env variable LG_ENV)", ) - parser.add_argument( - "-p", "--place", type=str, default=place, help="place name/alias (default: value from env variable LG_PLACE)" - ) + parser.add_argument("-p", "--place", type=str, help="place name/alias (default: value from env variable LG_PLACE)") parser.add_argument( "-s", "--state", type=str, - default=state, help="strategy state to switch into before command (default: value from env varibale LG_STATE)", ) parser.add_argument( "-i", "--initial-state", type=str, - default=initial_state, help="strategy state to force into before switching to desired state", ) parser.add_argument( @@ -2120,11 +2097,11 @@ def main(): subparser.set_defaults(func=ClientSession.create_reservation) subparser = subparsers.add_parser("cancel-reservation", help="cancel a reservation") - subparser.add_argument("token", type=str, default=token, nargs="?" if token else None) + subparser.add_argument("token", type=str, nargs="?") subparser.set_defaults(func=ClientSession.cancel_reservation) subparser = subparsers.add_parser("wait", help="wait for a reservation to be allocated") - subparser.add_argument("token", type=str, default=token, nargs="?" if token else None) + subparser.add_argument("token", type=str, nargs="?") subparser.set_defaults(func=ClientSession.wait_reservation) subparser = subparsers.add_parser("reservations", help="list current reservations") @@ -2147,6 +2124,30 @@ def main(): subparser = subparsers.add_parser("version", help="show version") subparser.set_defaults(func=ClientSession.print_version) + return parser + + +def main(): + import inspect + + basicConfig( + level=logging.WARNING, + stream=sys.stderr, + ) + + StepLogger.start() + processwrapper.enable_logging() + + # Support both legacy variables and properly namespaced ones + place = os.environ.get("PLACE", None) + place = os.environ.get("LG_PLACE", place) + state = os.environ.get("STATE", None) + state = os.environ.get("LG_STATE", state) + initial_state = os.environ.get("LG_INITIAL_STATE", None) + token = os.environ.get("LG_TOKEN", None) + + parser = get_parser() + # make any leftover arguments available for some commands args, leftover = parser.parse_known_args() if args.command not in ["ssh", "rsync", "forward"]: @@ -2154,6 +2155,26 @@ def main(): else: args.leftover = leftover + # handle dynamic defaults + if args.config is None: + args.config = os.environ.get("LG_ENV") + + if args.place is None: + args.place = place + + if args.state is None: + args.state = state + + if args.initial_state is None: + args.initial_state = initial_state + + if args.command in ["cancel-reservation", "wait"] and args.token is None: + if token: + args.token = token + else: + print("Please provide a token", file=sys.stderr) + exit(1) + if args.verbose: logging.getLogger().setLevel(logging.INFO) if args.verbose > 1: diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 index ba9f4b79b..025985936 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-CLIENT" "1" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-CLIENT" "1" "2025" "" "labgrid" .SH NAME labgrid-client \- labgrid's client interface to control boards .SH LABGRID-CLIENT INTERFACE TO CONTROL BOARDS diff --git a/man/labgrid-coordinator.1 b/man/labgrid-coordinator.1 index f3a31faee..e99c30f93 100644 --- a/man/labgrid-coordinator.1 +++ b/man/labgrid-coordinator.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-COORDINATOR" "1" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-COORDINATOR" "1" "2025" "" "labgrid" .SH NAME labgrid-coordinator \- managing labgrid resources and places .SH LABGRID-COORDINATOR MANAGING LABGRID RESOURCES AND PLACES diff --git a/man/labgrid-device-config.5 b/man/labgrid-device-config.5 index affe55b59..0755927de 100644 --- a/man/labgrid-device-config.5 +++ b/man/labgrid-device-config.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-DEVICE-CONFIG" "5" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-DEVICE-CONFIG" "5" "2025" "" "labgrid" .SH NAME labgrid-device-config \- test configuration files .SH LABGRID TEST CONFIGURATION FILES diff --git a/man/labgrid-exporter.1 b/man/labgrid-exporter.1 index 93c8b1a54..92619f4d1 100644 --- a/man/labgrid-exporter.1 +++ b/man/labgrid-exporter.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-EXPORTER" "1" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-EXPORTER" "1" "2025" "" "labgrid" .SH NAME labgrid-exporter \- interface to control boards .SH LABGRID-EXPORTER INTERFACE TO CONTROL BOARDS diff --git a/man/labgrid-pytest.7 b/man/labgrid-pytest.7 index a7aed7100..8b62ad8ce 100644 --- a/man/labgrid-pytest.7 +++ b/man/labgrid-pytest.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-PYTEST" "7" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-PYTEST" "7" "2025" "" "labgrid" .SH NAME labgrid-pytest \- labgrid integration for pytest .SH LABGRID-PYTEST LABGRID INTEGRATION FOR PYTEST diff --git a/man/labgrid-suggest.1 b/man/labgrid-suggest.1 index 34babce21..e37d84fd2 100644 --- a/man/labgrid-suggest.1 +++ b/man/labgrid-suggest.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "LABGRID-SUGGEST" "1" "Nov 05, 2025" "" "labgrid" +.TH "LABGRID-SUGGEST" "1" "2025" "" "labgrid" .SH NAME labgrid-suggest \- generator for YAML config files .SH LABGRID-SUGGEST GENERATOR FOR YAML CONFIG FILES From 47125aac7381813e0a744faffdaaa9734994e75e Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 13:30:22 +0200 Subject: [PATCH 4/7] doc: man: Generate labgrid-client manpage using autoprogram The old process was to manually duplicate information between the argparse struct in labgrid/remote/client.py and man/labgrid-client.rst which would then be translated to a manpage in man/labgrid-client.1 using rst2man and also tracked in version control. The man/labgrid-client.rst file was also sourced in doc/man/client.rst for sphinx to build html documentation of the labgrid-client cli documentation. Due to this duplication, labgrid-client command documentation was incomplete and inconsistend with argparse documentation accessible via the -h switch. Use the autoprogram sphinx extension to generate usage info from the argparse struct returned by get_parser() in labgrid/remote/client.py as part of doc/man/client.rst. Move documentation missing from the argparse struct from man/labgrid-client.1 to doc/man/client.rst. Generate both html cli documentation as well as the manpage from that. Future changes in subcommands and arguments of labgrid-client need only be documented in the argparse struct but more expansive documentation that includes markup can be added to the manpage, even to specific subcommands via the rst in doc/man. Signed-off-by: Jonas Rebmann --- doc/conf.py | 4 +- doc/man/client.rst | 155 +---- man/labgrid-client.1 | 1537 ++++++++++++++++++++++++++++++++++++++---- pyproject.toml | 1 + 4 files changed, 1420 insertions(+), 277 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 37797a76e..9cfa65022 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -40,6 +40,7 @@ 'sphinx.ext.napoleon', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', + 'sphinxcontrib.autoprogram', 'sphinx.ext.autosectionlabel', 'sphinx_rtd_theme'] @@ -200,7 +201,8 @@ 'vxi11', 'pysnmp', 'kasa', - 'kasa.iot'] + 'kasa.iot', + ] # -- Options for autosection ---------------------------------------------- autosectionlabel_prefix_document = True diff --git a/doc/man/client.rst b/doc/man/client.rst index 76cbb0b04..38af2f2b7 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -1,55 +1,23 @@ .. _labgrid-client: -================ - labgrid-client -================ +labgrid-client CLI +================== -labgrid-client interface to control boards -========================================== - -SYNOPSIS --------- - -``labgrid-client`` ``--help`` +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. -``labgrid-client`` -p +This is the client to control a boards status and interface with it on remote machines. -``labgrid-client`` ``places|resources`` +.. currentmodule:: labgrid.remote.client -DESCRIPTION ------------ -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. +.. autoprogram:: labgrid.remote.client:get_parser() + :prog: labgrid-client -OPTIONS -------- --h, --help - display command line help --p PLACE, --place PLACE - specify the place to operate on --x ADDRESS, --coordinator ADDRESS - coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408`` --c CONFIG, --config CONFIG - set the configuration file --s STATE, --state STATE - set an initial state before executing a command, requires a configuration - file and strategy --i INITIAL_STATE, --initial-state INITIAL_STATE - strategy state to force into before switching to desired state, requires a - desired state (``-s``/``--state``/``LG_STATE``) --d, --debug - enable debugging --v, --verbose - increase verbosity --P PROXY, --proxy PROXY - proxy connections over ssh - -CONFIGURATION FILE +Configuration File ------------------ The configuration file follows the description in ``labgrid-device-config``\(5). -ENVIRONMENT VARIABLES +Environment Variables --------------------- Various labgrid-client commands use the following environment variable: @@ -112,7 +80,7 @@ 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 +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 @@ -120,104 +88,7 @@ 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. -LABGRID-CLIENT COMMANDS ------------------------ -``monitor`` Monitor events from the coordinator - -``resources (r)`` List available resources - -``places (p)`` List available places - -``who`` List acquired places by user - -``show`` Show a place and related resources - -``create`` Add a new place (name supplied by -p parameter) - -``delete`` Delete an existing place - -``add-alias`` ``[alias]`` Add an alias to a place - -``del-alias`` ``[alias]`` Delete an alias from a place - -``set-comment`` ``[comment]`` Update or set the place comment - -``set-tags`` ``[key=value]`` Set place tags (key=value) - -``add-match`` ``[match]`` Add one (or multiple) match pattern(s) to a place, see MATCHES - -``del-match`` ``[match]`` Delete one (or multiple) match pattern(s) from a place, see MATCHES - -``add-named-match`` ``[match]`` ``[name]`` Add one match pattern with a name to a place - -``acquire (lock)`` Acquire a place - -``allow`` ``[user]`` Allow another user to access a place - -``release (unlock)`` Release a place - -``release-from`` ``[host/user]`` 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. - -``env`` Generate a labgrid environment file for a place - -``power (pw)`` ``[action]`` Change (or get) a place's power status, where action is one of get, on, off, cycle - -``io`` ``[action]`` ``[name]`` Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get - -``console (con)`` ``[name]`` Connect to the console - -``dfu`` ``[arg]`` Run dfu commands - -``fastboot`` ``[arg]`` Run fastboot with argument - -``flashscript`` ``[script]`` ``[arg]`` Run arbitrary script with arguments to flash device - -``bootstrap`` ``[filename]`` Start a bootloader - -``sd-mux`` ``[action]`` Switch USB SD Muxer, where action is one of dut (device-under-test), host, off - -``usb-mux`` ``[action]`` Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device - -``ssh`` ``[command]`` Connect via SSH. Additional arguments are passed to ssh. - -``scp`` ``[source]`` ``[destination]`` Transfer file via scp (use ':dir/file' for the remote side) - -``rsync`` ``[source]`` ``[destination]`` Transfer files via rsync (use ':dir/file' for the remote side) - -``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs - -``forward`` Forward local port to remote target - -``telnet`` Connect via telnet - -``video`` Start a video stream - -``audio`` Start an audio stream - -``tmc`` ``[command]`` Control a USB TMC device - -``write-files`` ``[filename(s)]`` Copy files onto mass storage device - -``write-image`` ``[filename]`` Write images onto block devices (USBSDMux, USB Sticks, …) - -``reserve`` ``[filter]`` Create a reservation - -``cancel-reservation`` ``[token]`` Cancel a pending reservation - -``wait`` ``[token]`` Wait for a reservation to be allocated - -``reservations`` List current reservations - -``export`` ``[filename]`` Export driver information to file (needs environment with drivers) - -``version`` Print the labgrid version - -ADDING NAMED RESOURCES +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 @@ -229,7 +100,7 @@ given. If one of the resources should be used by default when no resource name is explicitly specified, it can be named ``default``. -EXAMPLES +Examples -------- To retrieve a list of places run: @@ -257,7 +128,7 @@ Add all resources with the group "example-group" to the place example-place: $ labgrid-client -p example-place add-match */example-group/*/* -SEE ALSO +See Also -------- ``labgrid-exporter``\(1) diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 index 025985936..af374e34d 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -30,55 +30,1423 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .TH "LABGRID-CLIENT" "1" "2025" "" "labgrid" .SH NAME labgrid-client \- labgrid's client interface to control boards -.SH LABGRID-CLIENT INTERFACE TO CONTROL BOARDS -.SS SYNOPSIS .sp -\fBlabgrid\-client\fP \fB\-\-help\fP +Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. +.sp +This is the client to control a boards status and interface with it on remote machines. +.SH LABGRID-CLIENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client [\-h] [\-x ADDRESS] [\-c CONFIG] [\-p PLACE] [\-s STATE] [\-i INITIAL_STATE] [\-d] [\-v] [\-P PROXY] COMMAND ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-x
, \-\-coordinator
+coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408) +.UNINDENT +.INDENT 0.0 +.TP +.B \-c , \-\-config +env config file (default: value from env variable LG_ENV) +.UNINDENT +.INDENT 0.0 +.TP +.B \-p , \-\-place +place name/alias (default: value from env variable LG_PLACE) +.UNINDENT +.INDENT 0.0 +.TP +.B \-s , \-\-state +strategy state to switch into before command (default: value from env varibale LG_STATE) +.UNINDENT +.INDENT 0.0 +.TP +.B \-i , \-\-initial\-state +strategy state to force into before switching to desired state +.UNINDENT +.INDENT 0.0 +.TP +.B \-d, \-\-debug +enable debug mode (show python tracebacks) +.UNINDENT +.INDENT 0.0 +.TP +.B \-v, \-\-verbose +.UNINDENT +.INDENT 0.0 +.TP +.B \-P , \-\-proxy +proxy connections via given ssh host +.UNINDENT +.SS labgrid\-client acquire +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client acquire [\-h] [\-\-allow\-unmatched] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-allow\-unmatched +allow missing resources for matches when locking the place +.UNINDENT +.SS labgrid\-client add\-alias +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-alias [\-h] alias +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B alias +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client add\-match +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-match [\-h] PATTERN [PATTERN ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client add\-named\-match +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client add\-named\-match [\-h] PATTERN NAME +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.INDENT 0.0 +.TP +.B name +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client allow +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client allow [\-h] user +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B user +/ +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client audio +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client audio [\-h] [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client bootstrap +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client bootstrap [\-h] [\-w WAIT] [\-\-name NAME] filename ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B filename +filename to boot on the target +.UNINDENT +.INDENT 0.0 +.TP +.B arg +extra bootstrap arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-w , \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client cancel\-reservation +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client cancel\-reservation [\-h] [token] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B token +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client complete +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client complete [\-h] {resources,places,matches,match\-names} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B type +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client console +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client console [\-h] [\-l] [\-o] [\-\-logfile FILE] [name] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B name +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-l, \-\-loop +keep trying to connect if the console is unavailable +.UNINDENT +.INDENT 0.0 +.TP +.B \-o, \-\-listenonly +do not modify local terminal, do not send input from stdin +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-logfile +Log output to FILE +.UNINDENT +.SS labgrid\-client console +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client console [\-h] [\-l] [\-o] [\-\-logfile FILE] [name] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B name +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-l, \-\-loop +keep trying to connect if the console is unavailable +.UNINDENT +.INDENT 0.0 +.TP +.B \-o, \-\-listenonly +do not modify local terminal, do not send input from stdin +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-logfile +Log output to FILE +.UNINDENT +.SS labgrid\-client create +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client create [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client del\-alias +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client del\-alias [\-h] alias +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B alias +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client del\-match +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client del\-match [\-h] PATTERN [PATTERN ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pattern +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client delete +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client delete [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client dfu +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client dfu [\-h] [\-\-wait WAIT] [\-\-name NAME] {download,detach,list} [altsetting] [filename] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +action +.UNINDENT +.INDENT 0.0 +.TP +.B altsetting +altsetting name or number (download, detach only) +.UNINDENT +.INDENT 0.0 +.TP +.B filename +file to write into device (download only) +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client env +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client env [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client export +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client export [\-h] [\-\-format {shell,shell\-export,json}] filename +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B filename +output filename +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-format {shell,shell\-export,json} +output format (default: shell\-export) +.UNINDENT +.SS labgrid\-client fastboot +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client fastboot [\-h] [\-\-wait WAIT] [\-\-name NAME] ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B arg +fastboot arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client flashscript +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client flashscript [\-h] [\-\-name NAME] script ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B script +Flashing script +.UNINDENT +.INDENT 0.0 +.TP +.B arg +script arguments +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client forward +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client forward [\-h] [\-\-name NAME] [\-\-local [LOCAL:]REMOTE] [\-\-remote REMOTE:LOCAL] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-local, \-L +Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-remote, \-R +Forward remote port REMOTE to local port LOCAL +.UNINDENT +.SS labgrid\-client help +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client help [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client io +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client io [\-h] {high,low,get} [name] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +action +.UNINDENT +.INDENT 0.0 +.TP +.B name +optional resource name +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client acquire +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client acquire [\-h] [\-\-allow\-unmatched] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-allow\-unmatched +allow missing resources for matches when locking the place +.UNINDENT +.SS labgrid\-client monitor +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client monitor [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client places +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client places [\-h] [\-a] [\-r] [\-\-sort\-last\-changed] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-r, \-\-released +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-last\-changed +sort by last changed date (oldest first) +.UNINDENT +.SS labgrid\-client places +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client places [\-h] [\-a] [\-r] [\-\-sort\-last\-changed] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-r, \-\-released +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-last\-changed +sort by last changed date (oldest first) +.UNINDENT +.SS labgrid\-client power +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client power [\-h] [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-t , \-\-delay +wait time in seconds between off and on during cycle +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client power +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client power [\-h] [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-t , \-\-delay +wait time in seconds between off and on during cycle +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client resources +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client resources [\-h] [\-a] [\-e EXPORTER] [\-\-sort\-by\-matched\-place\-change] [match] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B match +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-e , \-\-exporter +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-by\-matched\-place\-change +sort by matched place\(aqs changed date (oldest first) and show place and date +.UNINDENT +.SS labgrid\-client release +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client release [\-h] [\-k] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-k, \-\-kick +release a place even if it is acquired by a different user +.UNINDENT +.SS labgrid\-client release\-from +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client release\-from [\-h] HOST/USER +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B host/user +User and host to match against when releasing +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client reservations +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client reservations [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client reserve +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client reserve [\-h] [\-\-wait] [\-\-shell] [\-\-prio PRIO] KEY=VALUE [KEY=VALUE ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B key=value +required tags +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-wait +wait until the reservation is allocated +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-shell +format output as shell variables +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-prio +priority relative to other reservations (default 0) +.UNINDENT +.SS labgrid\-client resources +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client resources [\-h] [\-a] [\-e EXPORTER] [\-\-sort\-by\-matched\-place\-change] [match] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B match +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-a, \-\-acquired +.UNINDENT +.INDENT 0.0 +.TP +.B \-e , \-\-exporter +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sort\-by\-matched\-place\-change +sort by matched place\(aqs changed date (oldest first) and show place and date +.UNINDENT +.SS labgrid\-client rsync +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client rsync [\-h] [\-\-name NAME] src dst +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B src +source path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B dst +destination path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.sp +Additional arguments are passed to the rsync subprocess. +.SS labgrid\-client scp +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client scp [\-h] [\-\-name NAME] src dst +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B src +source path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B dst +destination path (use :dir/file for remote side) +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client sd\-mux +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client sd\-mux [\-h] [\-\-name NAME] {dut,host,off,client,get} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client set\-comment +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client set\-comment [\-h] comment [comment ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B comment +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client set\-tags +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client set\-tags [\-h] KEY=VALUE [KEY=VALUE ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B key=value +use an empty value for deletion +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client show +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client show [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client ssh +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client ssh [\-h] [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.sp +Additional arguments are passed to the ssh subprocess. +.SS labgrid\-client sshfs +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client sshfs [\-h] [\-\-name NAME] path mountpoint +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B path +remote path on the target +.UNINDENT +.INDENT 0.0 +.TP +.B mountpoint +local path +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client telnet +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client telnet [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc [\-h] [\-\-name NAME] SUBCOMMAND ... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client tmc cmd +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc cmd [\-h] command [command ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B command +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc channel +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client tmc channel [\-h] channel {info,values} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B channel +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc cmd +.INDENT 0.0 +.INDENT 3.5 .sp -\fBlabgrid\-client\fP \-p +.EX +usage: labgrid\-client tmc cmd [\-h] command [command ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B command +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc query +.INDENT 0.0 +.INDENT 3.5 .sp -\fBlabgrid\-client\fP \fBplaces|resources\fP -.SS DESCRIPTION +.EX +usage: labgrid\-client tmc query [\-h] query [query ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B query +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc query +.INDENT 0.0 +.INDENT 3.5 .sp -Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. +.EX +usage: labgrid\-client tmc query [\-h] query [query ...] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B query +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client tmc screen +.INDENT 0.0 +.INDENT 3.5 .sp -This is the client to control a boards status and interface with it on remote machines. -.SS OPTIONS +.EX +usage: labgrid\-client tmc screen [\-h] {show,save} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B action +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client release +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client release [\-h] [\-k] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-k, \-\-kick +release a place even if it is acquired by a different user +.UNINDENT +.SS labgrid\-client usb\-mux +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client usb\-mux [\-h] [\-\-name NAME] {off,dut\-device,host\-dut,host\-device,host\-dut+host\-device} +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B links +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client version +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client version [\-h] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client video +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client video [\-h] [\-q QUALITY] [\-c CONTROLS] [\-\-name NAME] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-q , \-\-quality +select a video quality (use \(aqlist\(aq to show options) +.UNINDENT +.INDENT 0.0 +.TP +.B \-c , \-\-controls +configure v4l controls (such as \(aqfocus_auto=0,focus_absolute=40\(aq) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client wait +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client wait [\-h] [token] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B token +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.SS labgrid\-client who +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client who [\-h] [\-e] +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-e, \-\-show\-exporters +show exporters currently used by each place +.UNINDENT +.SS labgrid\-client write\-files +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client write\-files [OPTION]... \-T SOURCE DEST + labgrid\-client write\-files [OPTION]... [\-t DIRECTORY] SOURCE... +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B source +source file(s) to copy +.UNINDENT +.INDENT 0.0 +.TP +.B dest +destination file name for SOURCE +.UNINDENT +.INDENT 0.0 +.TP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 +.TP +.B \-w , \-\-wait +storage poll timeout in seconds +.UNINDENT +.INDENT 0.0 +.TP +.B \-p {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255}, \-\-partition {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255} +partition number to mount or 0 to mount whole disk (default: 1) +.UNINDENT +.INDENT 0.0 +.TP +.B \-t , \-\-target\-directory +copy all SOURCE files into DIRECTORY (default: partition root) +.UNINDENT +.INDENT 0.0 +.TP +.B \-T +copy SOURCE file and rename to DEST +.UNINDENT .INDENT 0.0 .TP -.B \-h\fP,\fB \-\-help -display command line help +.B \-\-name , \-n +optional resource name +.UNINDENT +.SS labgrid\-client write\-image +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: labgrid\-client write\-image [\-h] [\-w WAIT] [\-p PARTITION] [\-\-skip SKIP] [\-\-seek SEEK] [\-\-mode {dd,bmaptool}] [\-\-name NAME] filename +.EE +.UNINDENT +.UNINDENT +.INDENT 0.0 .TP -.BI \-p \ PLACE\fR,\fB \ \-\-place \ PLACE -specify the place to operate on +.B filename +filename to boot on the target +.UNINDENT +.INDENT 0.0 .TP -.BI \-x \ ADDRESS\fR,\fB \ \-\-coordinator \ ADDRESS -coordinator \fBHOST[:PORT]\fP to connect to, defaults to \fB127.0.0.1:20408\fP +.B \-h, \-\-help +show this help message and exit +.UNINDENT +.INDENT 0.0 .TP -.BI \-c \ CONFIG\fR,\fB \ \-\-config \ CONFIG -set the configuration file +.B \-w , \-\-wait +.UNINDENT +.INDENT 0.0 .TP -.BI \-s \ STATE\fR,\fB \ \-\-state \ STATE -set an initial state before executing a command, requires a configuration -file and strategy +.B \-p , \-\-partition +partition number to write to +.UNINDENT +.INDENT 0.0 .TP -.BI \-i \ INITIAL_STATE\fR,\fB \ \-\-initial\-state \ INITIAL_STATE -strategy state to force into before switching to desired state, requires a -desired state (\fB\-s\fP/\fB\-\-state\fP/\fBLG_STATE\fP) +.B \-\-skip +skip n 512\-sized blocks at start of input +.UNINDENT +.INDENT 0.0 .TP -.B \-d\fP,\fB \-\-debug -enable debugging +.B \-\-seek +skip n 512\-sized blocks at start of output +.UNINDENT +.INDENT 0.0 .TP -.B \-v\fP,\fB \-\-verbose -increase verbosity +.B \-\-mode {dd,bmaptool} +Choose tool for writing images (default: dd) +.UNINDENT +.INDENT 0.0 .TP -.BI \-P \ PROXY\fR,\fB \ \-\-proxy \ PROXY -proxy connections over ssh +.B \-\-name , \-n +optional resource name .UNINDENT -.SS CONFIGURATION FILE +.SH CONFIGURATION FILE .sp The configuration file follows the description in \fBlabgrid\-device\-config\fP(5). -.SS ENVIRONMENT VARIABLES +.SH ENVIRONMENT VARIABLES .sp Various labgrid\-client commands use the following environment variable: .SS LG_PLACE @@ -129,113 +1497,14 @@ unspecified, defaults to 30 seconds. .sp Add a prefix to \fB\&.labgrid_agent_{agent_hash}.py\fP allowing specification for where on the exporter it should be uploaded to. -.SS MATCHES +.SH MATCHES .sp 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. -.SS LABGRID\-CLIENT COMMANDS -.sp -\fBmonitor\fP Monitor events from the coordinator -.sp -\fBresources (r)\fP List available resources -.sp -\fBplaces (p)\fP List available places -.sp -\fBwho\fP List acquired places by user -.sp -\fBshow\fP Show a place and related resources -.sp -\fBcreate\fP Add a new place (name supplied by \-p parameter) -.sp -\fBdelete\fP Delete an existing place -.sp -\fBadd\-alias\fP \fB[alias]\fP Add an alias to a place -.sp -\fBdel\-alias\fP \fB[alias]\fP Delete an alias from a place -.sp -\fBset\-comment\fP \fB[comment]\fP Update or set the place comment -.sp -\fBset\-tags\fP \fB[key=value]\fP Set place tags (key=value) -.sp -\fBadd\-match\fP \fB[match]\fP Add one (or multiple) match pattern(s) to a place, see MATCHES -.sp -\fBdel\-match\fP \fB[match]\fP Delete one (or multiple) match pattern(s) from a place, see MATCHES -.sp -\fBadd\-named\-match\fP \fB[match]\fP \fB[name]\fP Add one match pattern with a name to a place -.sp -\fBacquire (lock)\fP Acquire a place -.sp -\fBallow\fP \fB[user]\fP Allow another user to access a place -.sp -\fBrelease (unlock)\fP Release a place -.sp -\fBrelease\-from\fP \fB[host/user]\fP Atomically release a place, but only if acquired by a specific user. -.INDENT 0.0 -.INDENT 3.5 -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. -.UNINDENT -.UNINDENT -.sp -\fBenv\fP Generate a labgrid environment file for a place -.sp -\fBpower (pw)\fP \fB[action]\fP Change (or get) a place\(aqs power status, where action is one of get, on, off, cycle -.sp -\fBio\fP \fB[action]\fP \fB[name]\fP Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get -.sp -\fBconsole (con)\fP \fB[name]\fP Connect to the console -.sp -\fBdfu\fP \fB[arg]\fP Run dfu commands -.sp -\fBfastboot\fP \fB[arg]\fP Run fastboot with argument -.sp -\fBflashscript\fP \fB[script]\fP \fB[arg]\fP Run arbitrary script with arguments to flash device -.sp -\fBbootstrap\fP \fB[filename]\fP Start a bootloader -.sp -\fBsd\-mux\fP \fB[action]\fP Switch USB SD Muxer, where action is one of dut (device\-under\-test), host, off -.sp -\fBusb\-mux\fP \fB[action]\fP Switch USB Muxer, where action is one of off, dut\-device, host\-dut, host\-device, host\-dut+host\-device -.sp -\fBssh\fP \fB[command]\fP Connect via SSH. Additional arguments are passed to ssh. -.sp -\fBscp\fP \fB[source]\fP \fB[destination]\fP Transfer file via scp (use \(aq:dir/file\(aq for the remote side) -.sp -\fBrsync\fP \fB[source]\fP \fB[destination]\fP Transfer files via rsync (use \(aq:dir/file\(aq for the remote side) -.sp -\fBsshfs\fP \fB[remotepath]\fP \fB[mountpoint]\fP Mount a remote path via sshfs -.sp -\fBforward\fP Forward local port to remote target -.sp -\fBtelnet\fP Connect via telnet -.sp -\fBvideo\fP Start a video stream -.sp -\fBaudio\fP Start an audio stream -.sp -\fBtmc\fP \fB[command]\fP Control a USB TMC device -.sp -\fBwrite\-files\fP \fB[filename(s)]\fP Copy files onto mass storage device -.sp -\fBwrite\-image\fP \fB[filename]\fP Write images onto block devices (USBSDMux, USB Sticks, …) -.sp -\fBreserve\fP \fB[filter]\fP Create a reservation -.sp -\fBcancel\-reservation\fP \fB[token]\fP Cancel a pending reservation -.sp -\fBwait\fP \fB[token]\fP Wait for a reservation to be allocated -.sp -\fBreservations\fP List current reservations -.sp -\fBexport\fP \fB[filename]\fP Export driver information to file (needs environment with drivers) -.sp -\fBversion\fP Print the labgrid version -.SS ADDING NAMED RESOURCES +.SH ADDING NAMED RESOURCES .sp 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 \fImatch\fP taken by @@ -246,7 +1515,7 @@ given. .sp If one of the resources should be used by default when no resource name is explicitly specified, it can be named \fBdefault\fP\&. -.SS EXAMPLES +.SH EXAMPLES .sp To retrieve a list of places run: .INDENT 0.0 @@ -288,7 +1557,7 @@ $ labgrid\-client \-p example\-place add\-match */example\-group/*/* .EE .UNINDENT .UNINDENT -.SS SEE ALSO +.SH SEE ALSO .sp \fBlabgrid\-exporter\fP(1) .SH AUTHOR diff --git a/pyproject.toml b/pyproject.toml index bf43cada4..476808f3b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,6 +58,7 @@ dynamic = ["version"] # via setuptools_scm doc = [ "sphinx_rtd_theme>=1.0.0", "Sphinx>=2.0.0", + "sphinxcontrib-autoprogram>=0.1.9", ] docker = ["docker>=5.0.2"] graph = ["graphviz>=0.17.0"] From b1e6af37921fb585292984c09ef8d70d45e038fb Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 16:40:44 +0200 Subject: [PATCH 5/7] doc: Limit toc depth to 2 on manpage overview Doesn't look good if every Arguments list of every subcommand of every command is listed here for the manpages generated from argparse. Signed-off-by: Jonas Rebmann --- doc/man.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/man.rst b/doc/man.rst index 0f173b19e..86984cd4c 100644 --- a/doc/man.rst +++ b/doc/man.rst @@ -2,6 +2,8 @@ Manual Pages ============ .. toctree:: + :maxdepth: 2 + man/client man/coordinator man/device-config From a562c69a30f766cad504fc685e782cc172904400 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Fri, 25 Jul 2025 17:35:25 +0200 Subject: [PATCH 6/7] remote/client: sphinx autoprogram workarounds Hide intentionally undocumented subcommands and overlong lists of choices. Work around shortcomings of autoprogram's subcommand handling: - Don't show the --help, -h option for each subparser - Display aliases as `command subcommand|alias --option` - Show the "help" message of the subparser - Don't show ranges in "choices" Signed-off-by: Jonas Rebmann [bst: renamed for_manpage -> auto_doc_mode, switched its default to False, autoprogram now calls "labgrid.remote.client:get_parser(auto_doc_mode=True)", replaced monkey-patched _SubParsersAction.add_parser() with _ActionWrapper class, don't show `range` in `choices` generically, adjust commit message] Signed-off-by: Bastian Krause --- doc/man/client.rst | 2 +- labgrid/remote/client.py | 64 +++- man/labgrid-client.1 | 699 ++++++++++----------------------------- 3 files changed, 225 insertions(+), 540 deletions(-) diff --git a/doc/man/client.rst b/doc/man/client.rst index 38af2f2b7..309e36365 100644 --- a/doc/man/client.rst +++ b/doc/man/client.rst @@ -10,7 +10,7 @@ This is the client to control a boards status and interface with it on remote ma .. currentmodule:: labgrid.remote.client -.. autoprogram:: labgrid.remote.client:get_parser() +.. autoprogram:: labgrid.remote.client:get_parser(auto_doc_mode=True) :prog: labgrid-client Configuration File diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py index a9f00298b..1ae75e5dd 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1758,8 +1758,58 @@ def __str__(self): return self.value -def get_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser() +class AutoProgramArgumentParser(argparse.ArgumentParser): + """Works around sphinxcontrib.autoprogram shortcomings.""" + + class _ActionWrapper: + """ + Wraps argparse's special private action object registered for "parsers", see: + https://docs.python.org/3.14/library/argparse.html#argparse.ArgumentParser.add_subparsers + https://docs.python.org/3.13/library/argparse.html#argparse.ArgumentParser.register + """ + + def __init__(self, action): + self.action = action + + def add_parser(self, name, **kwargs): + # aliases are not supported by autoprogram, they lead to duplicate entries, so + # show them as "command subcommand|alias --option" instead + aliases = kwargs.pop("aliases", []) + if aliases: + name = "|".join([name] + list(aliases)) + + # "help" text is ignored by autoprogram, move to "description" instead + if "description" not in kwargs and "help" in kwargs: + kwargs["description"] = kwargs.pop("help") + + # add_parser() is the only part of the action object that's not an implementation detail + return self.action.add_parser(name, **kwargs) + + def __init__(self, *args, **kwargs): + # print help texts in fixed width + os.environ["COLUMNS"] = "80" + + # hide --help, -h + kwargs.setdefault("add_help", False) + + super().__init__(*args, **kwargs) + + def add_subparsers(self, **kwargs): + action = super().add_subparsers(**kwargs) + return self._ActionWrapper(action) + + def add_argument(self, *args, **kwargs): + # do not show ranges + if isinstance(kwargs.get("choices"), range): + del kwargs["choices"] + + return super().add_argument(*args, **kwargs) + + +def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArgumentParser": + # use custom parser for sphinxcontrib.autoprogram + parser = AutoProgramArgumentParser() if auto_doc_mode else argparse.ArgumentParser() + parser.add_argument( "-x", "--coordinator", @@ -1797,11 +1847,13 @@ def get_parser() -> argparse.ArgumentParser: metavar="COMMAND", ) - subparser = subparsers.add_parser("help") + # if the argparse object is to be used for manpage generation, hide some subcommands + if not auto_doc_mode: + subparser = subparsers.add_parser("help") - subparser = subparsers.add_parser("complete") - subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"]) - subparser.set_defaults(func=ClientSession.complete) + subparser = subparsers.add_parser("complete") + subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"]) + subparser.set_defaults(func=ClientSession.complete) subparser = subparsers.add_parser("monitor", help="monitor events from the coordinator") subparser.set_defaults(func=ClientSession.do_monitor) diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 index af374e34d..9dccb06d7 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -39,17 +39,14 @@ This is the client to control a boards status and interface with it on remote ma .INDENT 3.5 .sp .EX -usage: labgrid\-client [\-h] [\-x ADDRESS] [\-c CONFIG] [\-p PLACE] [\-s STATE] [\-i INITIAL_STATE] [\-d] [\-v] [\-P PROXY] COMMAND ... +usage: labgrid\-client [\-x ADDRESS] [\-c CONFIG] [\-p PLACE] [\-s STATE] + [\-i INITIAL_STATE] [\-d] [\-v] [\-P PROXY] + COMMAND ... .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-x
, \-\-coordinator
coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408) .UNINDENT @@ -87,31 +84,30 @@ enable debug mode (show python tracebacks) .B \-P , \-\-proxy proxy connections via given ssh host .UNINDENT -.SS labgrid\-client acquire +.SS labgrid\-client acquire|lock +.sp +acquire a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client acquire [\-h] [\-\-allow\-unmatched] +usage: labgrid\-client acquire|lock [\-\-allow\-unmatched] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-allow\-unmatched allow missing resources for matches when locking the place .UNINDENT .SS labgrid\-client add\-alias +.sp +add an alias to a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client add\-alias [\-h] alias +usage: labgrid\-client add\-alias alias .EE .UNINDENT .UNINDENT @@ -119,17 +115,14 @@ usage: labgrid\-client add\-alias [\-h] alias .TP .B alias .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client add\-match +.sp +add one (or multiple) match pattern(s) to a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client add\-match [\-h] PATTERN [PATTERN ...] +usage: labgrid\-client add\-match PATTERN [PATTERN ...] .EE .UNINDENT .UNINDENT @@ -137,17 +130,14 @@ usage: labgrid\-client add\-match [\-h] PATTERN [PATTERN ...] .TP .B pattern .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client add\-named\-match +.sp +add one match pattern with a name to a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client add\-named\-match [\-h] PATTERN NAME +usage: labgrid\-client add\-named\-match PATTERN NAME .EE .UNINDENT .UNINDENT @@ -159,17 +149,14 @@ usage: labgrid\-client add\-named\-match [\-h] PATTERN NAME .TP .B name .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client allow +.sp +allow another user to access a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client allow [\-h] user +usage: labgrid\-client allow user .EE .UNINDENT .UNINDENT @@ -178,36 +165,30 @@ usage: labgrid\-client allow [\-h] user .B user / .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client audio +.sp +start a audio stream .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client audio [\-h] [\-\-name NAME] +usage: labgrid\-client audio [\-\-name NAME] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client bootstrap +.sp +start a bootloader .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client bootstrap [\-h] [\-w WAIT] [\-\-name NAME] filename ... +usage: labgrid\-client bootstrap [\-w WAIT] [\-\-name NAME] filename ... .EE .UNINDENT .UNINDENT @@ -223,11 +204,6 @@ extra bootstrap arguments .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-w , \-\-wait .UNINDENT .INDENT 0.0 @@ -236,81 +212,28 @@ show this help message and exit optional resource name .UNINDENT .SS labgrid\-client cancel\-reservation -.INDENT 0.0 -.INDENT 3.5 .sp -.EX -usage: labgrid\-client cancel\-reservation [\-h] [token] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B token -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client complete +cancel a reservation .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client complete [\-h] {resources,places,matches,match\-names} +usage: labgrid\-client cancel\-reservation [token] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B type -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit +.B token .UNINDENT -.SS labgrid\-client console -.INDENT 0.0 -.INDENT 3.5 +.SS labgrid\-client console|con .sp -.EX -usage: labgrid\-client console [\-h] [\-l] [\-o] [\-\-logfile FILE] [name] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B name -optional resource name -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-l, \-\-loop -keep trying to connect if the console is unavailable -.UNINDENT -.INDENT 0.0 -.TP -.B \-o, \-\-listenonly -do not modify local terminal, do not send input from stdin -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-logfile -Log output to FILE -.UNINDENT -.SS labgrid\-client console +connect to the console .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client console [\-h] [\-l] [\-o] [\-\-logfile FILE] [name] +usage: labgrid\-client console|con [\-l] [\-o] [\-\-logfile FILE] [name] .EE .UNINDENT .UNINDENT @@ -321,11 +244,6 @@ optional resource name .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-l, \-\-loop keep trying to connect if the console is unavailable .UNINDENT @@ -340,25 +258,24 @@ do not modify local terminal, do not send input from stdin Log output to FILE .UNINDENT .SS labgrid\-client create +.sp +add a new place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client create [\-h] +usage: labgrid\-client create .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client del\-alias +.sp +delete an alias from a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client del\-alias [\-h] alias +usage: labgrid\-client del\-alias alias .EE .UNINDENT .UNINDENT @@ -366,17 +283,14 @@ usage: labgrid\-client del\-alias [\-h] alias .TP .B alias .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client del\-match +.sp +delete one (or multiple) match pattern(s) from a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client del\-match [\-h] PATTERN [PATTERN ...] +usage: labgrid\-client del\-match PATTERN [PATTERN ...] .EE .UNINDENT .UNINDENT @@ -384,31 +298,26 @@ usage: labgrid\-client del\-match [\-h] PATTERN [PATTERN ...] .TP .B pattern .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client delete +.sp +delete an existing place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client delete [\-h] +usage: labgrid\-client delete .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client dfu +.sp +communicate with device in DFU mode .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client dfu [\-h] [\-\-wait WAIT] [\-\-name NAME] {download,detach,list} [altsetting] [filename] +usage: labgrid\-client dfu [\-\-wait WAIT] [\-\-name NAME] + {download,detach,list} [altsetting] [filename] .EE .UNINDENT .UNINDENT @@ -429,11 +338,6 @@ file to write into device (download only) .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-wait .UNINDENT .INDENT 0.0 @@ -442,25 +346,24 @@ show this help message and exit optional resource name .UNINDENT .SS labgrid\-client env +.sp +generate a labgrid environment file for a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client env [\-h] +usage: labgrid\-client env .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client export +.sp +export driver information to a file (needs environment with drivers) .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client export [\-h] [\-\-format {shell,shell\-export,json}] filename +usage: labgrid\-client export [\-\-format {shell,shell\-export,json}] filename .EE .UNINDENT .UNINDENT @@ -471,20 +374,17 @@ output filename .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-format {shell,shell\-export,json} output format (default: shell\-export) .UNINDENT .SS labgrid\-client fastboot +.sp +run fastboot .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client fastboot [\-h] [\-\-wait WAIT] [\-\-name NAME] ... +usage: labgrid\-client fastboot [\-\-wait WAIT] [\-\-name NAME] ... .EE .UNINDENT .UNINDENT @@ -495,11 +395,6 @@ fastboot arguments .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-wait .UNINDENT .INDENT 0.0 @@ -508,11 +403,13 @@ show this help message and exit optional resource name .UNINDENT .SS labgrid\-client flashscript +.sp +run flash script .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client flashscript [\-h] [\-\-name NAME] script ... +usage: labgrid\-client flashscript [\-\-name NAME] script ... .EE .UNINDENT .UNINDENT @@ -528,30 +425,23 @@ script arguments .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client forward +.sp +forward local port to remote target .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client forward [\-h] [\-\-name NAME] [\-\-local [LOCAL:]REMOTE] [\-\-remote REMOTE:LOCAL] +usage: labgrid\-client forward [\-\-name NAME] [\-\-local [LOCAL:]REMOTE] + [\-\-remote REMOTE:LOCAL] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT @@ -565,26 +455,14 @@ Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbi .B \-\-remote, \-R Forward remote port REMOTE to local port LOCAL .UNINDENT -.SS labgrid\-client help -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -usage: labgrid\-client help [\-h] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client io +.sp +change (or get) a digital IO status .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client io [\-h] {high,low,get} [name] +usage: labgrid\-client io {high,low,get} [name] .EE .UNINDENT .UNINDENT @@ -598,87 +476,30 @@ action .B name optional resource name .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client acquire -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -usage: labgrid\-client acquire [\-h] [\-\-allow\-unmatched] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-allow\-unmatched -allow missing resources for matches when locking the place -.UNINDENT .SS labgrid\-client monitor -.INDENT 0.0 -.INDENT 3.5 .sp -.EX -usage: labgrid\-client monitor [\-h] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client places +monitor events from the coordinator .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client places [\-h] [\-a] [\-r] [\-\-sort\-last\-changed] +usage: labgrid\-client monitor .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-a, \-\-acquired -.UNINDENT -.INDENT 0.0 -.TP -.B \-r, \-\-released -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-sort\-last\-changed -sort by last changed date (oldest first) -.UNINDENT -.SS labgrid\-client places +.SS labgrid\-client places|p +.sp +list available places .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client places [\-h] [\-a] [\-r] [\-\-sort\-last\-changed] +usage: labgrid\-client places|p [\-a] [\-r] [\-\-sort\-last\-changed] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-a, \-\-acquired .UNINDENT .INDENT 0.0 @@ -690,40 +511,14 @@ show this help message and exit .B \-\-sort\-last\-changed sort by last changed date (oldest first) .UNINDENT -.SS labgrid\-client power -.INDENT 0.0 -.INDENT 3.5 +.SS labgrid\-client power|pw .sp -.EX -usage: labgrid\-client power [\-h] [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B action -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-t , \-\-delay -wait time in seconds between off and on during cycle -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-name , \-n -optional resource name -.UNINDENT -.SS labgrid\-client power +change (or get) a place\(aqs power status .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client power [\-h] [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} +usage: labgrid\-client power|pw [\-t DELAY] [\-\-name NAME] {on,off,cycle,get} .EE .UNINDENT .UNINDENT @@ -733,11 +528,6 @@ usage: labgrid\-client power [\-h] [\-t DELAY] [\-\-name NAME] {on,off,cycle,get .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-t , \-\-delay wait time in seconds between off and on during cycle .UNINDENT @@ -746,95 +536,58 @@ wait time in seconds between off and on during cycle .B \-\-name , \-n optional resource name .UNINDENT -.SS labgrid\-client resources +.SS labgrid\-client release\-from +.sp +atomically release a place, but only if locked by a specific user .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client resources [\-h] [\-a] [\-e EXPORTER] [\-\-sort\-by\-matched\-place\-change] [match] +usage: labgrid\-client release\-from HOST/USER .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B match -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-a, \-\-acquired -.UNINDENT -.INDENT 0.0 -.TP -.B \-e , \-\-exporter -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-sort\-by\-matched\-place\-change -sort by matched place\(aqs changed date (oldest first) and show place and date +.B host/user +User and host to match against when releasing .UNINDENT -.SS labgrid\-client release +.SS labgrid\-client release|unlock +.sp +release a place .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client release [\-h] [\-k] +usage: labgrid\-client release|unlock [\-k] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-k, \-\-kick release a place even if it is acquired by a different user .UNINDENT -.SS labgrid\-client release\-from -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -usage: labgrid\-client release\-from [\-h] HOST/USER -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B host/user -User and host to match against when releasing -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client reservations +.sp +list current reservations .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client reservations [\-h] +usage: labgrid\-client reservations .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client reserve +.sp +create a reservation .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client reserve [\-h] [\-\-wait] [\-\-shell] [\-\-prio PRIO] KEY=VALUE [KEY=VALUE ...] +usage: labgrid\-client reserve [\-\-wait] [\-\-shell] [\-\-prio PRIO] + KEY=VALUE [KEY=VALUE ...] .EE .UNINDENT .UNINDENT @@ -845,11 +598,6 @@ required tags .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-wait wait until the reservation is allocated .UNINDENT @@ -863,12 +611,16 @@ format output as shell variables .B \-\-prio priority relative to other reservations (default 0) .UNINDENT -.SS labgrid\-client resources +.SS labgrid\-client resources|r +.sp +list available resources .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client resources [\-h] [\-a] [\-e EXPORTER] [\-\-sort\-by\-matched\-place\-change] [match] +usage: labgrid\-client resources|r [\-a] [\-e EXPORTER] + [\-\-sort\-by\-matched\-place\-change] + [match] .EE .UNINDENT .UNINDENT @@ -878,11 +630,6 @@ usage: labgrid\-client resources [\-h] [\-a] [\-e EXPORTER] [\-\-sort\-by\-match .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-a, \-\-acquired .UNINDENT .INDENT 0.0 @@ -895,11 +642,13 @@ show this help message and exit sort by matched place\(aqs changed date (oldest first) and show place and date .UNINDENT .SS labgrid\-client rsync +.sp +transfer files via rsync .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client rsync [\-h] [\-\-name NAME] src dst +usage: labgrid\-client rsync [\-\-name NAME] src dst .EE .UNINDENT .UNINDENT @@ -915,22 +664,19 @@ destination path (use :dir/file for remote side) .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .sp Additional arguments are passed to the rsync subprocess. .SS labgrid\-client scp +.sp +transfer file via scp .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client scp [\-h] [\-\-name NAME] src dst +usage: labgrid\-client scp [\-\-name NAME] src dst .EE .UNINDENT .UNINDENT @@ -946,20 +692,17 @@ destination path (use :dir/file for remote side) .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client sd\-mux +.sp +switch USB SD Muxer or get current mode .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client sd\-mux [\-h] [\-\-name NAME] {dut,host,off,client,get} +usage: labgrid\-client sd\-mux [\-\-name NAME] {dut,host,off,client,get} .EE .UNINDENT .UNINDENT @@ -969,20 +712,17 @@ usage: labgrid\-client sd\-mux [\-h] [\-\-name NAME] {dut,host,off,client,get} .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client set\-comment +.sp +update the place comment .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client set\-comment [\-h] comment [comment ...] +usage: labgrid\-client set\-comment comment [comment ...] .EE .UNINDENT .UNINDENT @@ -990,17 +730,14 @@ usage: labgrid\-client set\-comment [\-h] comment [comment ...] .TP .B comment .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client set\-tags +.sp +update the place tags .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client set\-tags [\-h] KEY=VALUE [KEY=VALUE ...] +usage: labgrid\-client set\-tags KEY=VALUE [KEY=VALUE ...] .EE .UNINDENT .UNINDENT @@ -1009,52 +746,43 @@ usage: labgrid\-client set\-tags [\-h] KEY=VALUE [KEY=VALUE ...] .B key=value use an empty value for deletion .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client show +.sp +show a place and related resources .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client show [\-h] +usage: labgrid\-client show .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client ssh +.sp +connect via ssh (with optional arguments) .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client ssh [\-h] [\-\-name NAME] +usage: labgrid\-client ssh [\-\-name NAME] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .sp Additional arguments are passed to the ssh subprocess. .SS labgrid\-client sshfs +.sp +mount via sshfs (blocking) .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client sshfs [\-h] [\-\-name NAME] path mountpoint +usage: labgrid\-client sshfs [\-\-name NAME] path mountpoint .EE .UNINDENT .UNINDENT @@ -1070,71 +798,44 @@ local path .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client telnet +.sp +connect via telnet .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client telnet [\-h] +usage: labgrid\-client telnet .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client tmc +.sp +control a USB TMC device .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client tmc [\-h] [\-\-name NAME] SUBCOMMAND ... +usage: labgrid\-client tmc [\-\-name NAME] SUBCOMMAND ... .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT -.SS labgrid\-client tmc cmd -.INDENT 0.0 -.INDENT 3.5 -.sp -.EX -usage: labgrid\-client tmc cmd [\-h] command [command ...] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B command -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client tmc channel +.sp +use a channel .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client tmc channel [\-h] channel {info,values} +usage: labgrid\-client tmc channel channel {info,values} .EE .UNINDENT .UNINDENT @@ -1146,17 +847,14 @@ usage: labgrid\-client tmc channel [\-h] channel {info,values} .TP .B action .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client tmc cmd +.SS labgrid\-client tmc cmd|c +.sp +execute raw command .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client tmc cmd [\-h] command [command ...] +usage: labgrid\-client tmc cmd|c command [command ...] .EE .UNINDENT .UNINDENT @@ -1164,35 +862,14 @@ usage: labgrid\-client tmc cmd [\-h] command [command ...] .TP .B command .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client tmc query -.INDENT 0.0 -.INDENT 3.5 +.SS labgrid\-client tmc query|q .sp -.EX -usage: labgrid\-client tmc query [\-h] query [query ...] -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B query -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client tmc query +execute raw query .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client tmc query [\-h] query [query ...] +usage: labgrid\-client tmc query|q query [query ...] .EE .UNINDENT .UNINDENT @@ -1200,54 +877,30 @@ usage: labgrid\-client tmc query [\-h] query [query ...] .TP .B query .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client tmc screen -.INDENT 0.0 -.INDENT 3.5 .sp -.EX -usage: labgrid\-client tmc screen [\-h] {show,save} -.EE -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B action -.UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.SS labgrid\-client release +show or save a screenshot .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client release [\-h] [\-k] +usage: labgrid\-client tmc screen {show,save} .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP -.B \-k, \-\-kick -release a place even if it is acquired by a different user +.B action .UNINDENT .SS labgrid\-client usb\-mux +.sp +switch USB Muxer .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client usb\-mux [\-h] [\-\-name NAME] {off,dut\-device,host\-dut,host\-device,host\-dut+host\-device} +usage: labgrid\-client usb\-mux [\-\-name NAME] + {off,dut\-device,host\-dut,host\-device,host\-dut+host\-device} .EE .UNINDENT .UNINDENT @@ -1257,44 +910,33 @@ usage: labgrid\-client usb\-mux [\-h] [\-\-name NAME] {off,dut\-device,host\-dut .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-\-name , \-n optional resource name .UNINDENT .SS labgrid\-client version +.sp +show version .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client version [\-h] +usage: labgrid\-client version .EE .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client video +.sp +start a video stream .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client video [\-h] [\-q QUALITY] [\-c CONTROLS] [\-\-name NAME] +usage: labgrid\-client video [\-q QUALITY] [\-c CONTROLS] [\-\-name NAME] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-q , \-\-quality select a video quality (use \(aqlist\(aq to show options) .UNINDENT @@ -1309,11 +951,13 @@ configure v4l controls (such as \(aqfocus_auto=0,focus_absolute=40\(aq) optional resource name .UNINDENT .SS labgrid\-client wait +.sp +wait for a reservation to be allocated .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client wait [\-h] [token] +usage: labgrid\-client wait [token] .EE .UNINDENT .UNINDENT @@ -1321,31 +965,25 @@ usage: labgrid\-client wait [\-h] [token] .TP .B token .UNINDENT -.INDENT 0.0 -.TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT .SS labgrid\-client who +.sp +list acquired places by user .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client who [\-h] [\-e] +usage: labgrid\-client who [\-e] .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-e, \-\-show\-exporters show exporters currently used by each place .UNINDENT .SS labgrid\-client write\-files +.sp +copy files onto mass storage device .INDENT 0.0 .INDENT 3.5 .sp @@ -1367,17 +1005,12 @@ destination file name for SOURCE .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-w , \-\-wait storage poll timeout in seconds .UNINDENT .INDENT 0.0 .TP -.B \-p {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255}, \-\-partition {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255} +.B \-p <0\-255>, \-\-partition <0\-255> partition number to mount or 0 to mount whole disk (default: 1) .UNINDENT .INDENT 0.0 @@ -1396,11 +1029,16 @@ copy SOURCE file and rename to DEST optional resource name .UNINDENT .SS labgrid\-client write\-image +.sp +write an image onto mass storage .INDENT 0.0 .INDENT 3.5 .sp .EX -usage: labgrid\-client write\-image [\-h] [\-w WAIT] [\-p PARTITION] [\-\-skip SKIP] [\-\-seek SEEK] [\-\-mode {dd,bmaptool}] [\-\-name NAME] filename +usage: labgrid\-client write\-image [\-w WAIT] [\-p PARTITION] [\-\-skip SKIP] + [\-\-seek SEEK] [\-\-mode {dd,bmaptool}] + [\-\-name NAME] + filename .EE .UNINDENT .UNINDENT @@ -1411,11 +1049,6 @@ filename to boot on the target .UNINDENT .INDENT 0.0 .TP -.B \-h, \-\-help -show this help message and exit -.UNINDENT -.INDENT 0.0 -.TP .B \-w , \-\-wait .UNINDENT .INDENT 0.0 From 6e0f1733b004574cb4e42de1570ea101e1878c08 Mon Sep 17 00:00:00 2001 From: Jonas Rebmann Date: Mon, 28 Jul 2025 17:09:52 +0200 Subject: [PATCH 7/7] doc: man: Add some details to subcommands The subcommands descriptions for create, release-from and flashscript had some extra details in the old rst manpages, not available in the argparse/cli help. Migrate these descriptions into argparse. Signed-off-by: Jonas Rebmann --- labgrid/remote/client.py | 12 +++++++++--- man/labgrid-client.1 | 6 ++++-- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py index 1ae75e5dd..576e172fc 100755 --- a/labgrid/remote/client.py +++ b/labgrid/remote/client.py @@ -1884,7 +1884,10 @@ def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArg subparser = subparsers.add_parser("show", help="show a place and related resources") subparser.set_defaults(func=ClientSession.print_place) - subparser = subparsers.add_parser("create", help="add a new place") + subparser = subparsers.add_parser( + "create", + help="add a new place with the name specified via --place or the LG_PLACE environment variable", + ) subparser.set_defaults(func=ClientSession.add_place) subparser = subparsers.add_parser("delete", help="delete an existing place") @@ -1932,7 +1935,10 @@ def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArg subparser.set_defaults(func=ClientSession.release) subparser = subparsers.add_parser( - "release-from", help="atomically release a place, but only if locked by a specific user" + "release-from", + help="atomically release a place, but only if locked by a specific user", + epilog="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.", ) subparser.add_argument("acquired", metavar="HOST/USER", help="User and host to match against when releasing") subparser.set_defaults(func=ClientSession.release_from) @@ -1982,7 +1988,7 @@ def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArg subparser.add_argument("--name", "-n", help="optional resource name") subparser.set_defaults(func=ClientSession.fastboot) - subparser = subparsers.add_parser("flashscript", help="run flash script") + subparser = subparsers.add_parser("flashscript", help="Run arbitrary script with arguments to flash device") subparser.add_argument("script", help="Flashing script") subparser.add_argument("script_args", metavar="ARG", nargs=argparse.REMAINDER, help="script arguments") subparser.add_argument("--name", "-n", help="optional resource name") diff --git a/man/labgrid-client.1 b/man/labgrid-client.1 index 9dccb06d7..fdc62be72 100644 --- a/man/labgrid-client.1 +++ b/man/labgrid-client.1 @@ -259,7 +259,7 @@ Log output to FILE .UNINDENT .SS labgrid\-client create .sp -add a new place +add a new place with the name specified via \-\-place or the LG_PLACE environment variable .INDENT 0.0 .INDENT 3.5 .sp @@ -404,7 +404,7 @@ optional resource name .UNINDENT .SS labgrid\-client flashscript .sp -run flash script +Run arbitrary script with arguments to flash device .INDENT 0.0 .INDENT 3.5 .sp @@ -552,6 +552,8 @@ usage: labgrid\-client release\-from HOST/USER .B host/user User and host to match against when releasing .UNINDENT +.sp +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. .SS labgrid\-client release|unlock .sp release a place