1.. _module-pw_target_runner: 2 3---------------- 4pw_target_runner 5---------------- 6The target runner module implements a gRPC server designed to run executables 7in parallel. These executables may be run directly on the host, or flashed to 8one or more attached targets. 9 10Overview 11-------- 12The target runner server is responsible for processing requests to distribute 13executables among a pool of workers that run in parallel. This allows things 14like unit tests to be run across multiple devices simultaneously, greatly 15reducing the overall time it takes to run a collection of tests. 16 17Additionally, the server allows many executables to be queued up at once and 18scheduled across available devices, making it possible to automatically run unit 19tests from a Ninja build after code is updated. This integrates nicely with the 20``pw watch`` command to re-run all affected unit tests after modifying code. 21 22The target runner is implemented as a library in various programming languages. 23This library provides the core gRPC server and a mechanism through which worker 24routines can be registered. Code using the library instantiates a server with 25some custom workers for the desired target to run passed executables. 26 27The ``pw_target_runner`` module also provides a standalone 28``pw_target_runner_server`` program which runs the server with configurable 29workers that launch external processes to execute passed binaries. This 30program should be sufficient to quickly get unit tests running in a simple 31setup, such as multiple devices plugged into a development machine. 32 33Standalone executable 34--------------------- 35This section describes how to use the ``pw_target_runner_server`` program to 36set up a simple unit test server with workers. 37 38Configuration 39^^^^^^^^^^^^^ 40The standalone server is configured from a file written in Protobuf text format 41containing a ``pw.target_runner.ServerConfig`` message as defined in 42``//pw_target_runner/pw_target_runner_server_protos/exec_server_config.proto``. 43 44At least one ``worker`` message must be specified. Each of the workers refers to 45a script or program which is invoked with the path to an executable file as a 46positional argument. Other arguments provided to the program must be options/ 47switches. 48 49For example, the config file below defines two workers, each connecting to an 50STM32F429I Discovery board with a specified serial number. 51 52**server_config.txt** 53 54.. code:: text 55 56 runner { 57 command: "stm32f429i_disc1_unit_test_runner" 58 args: "--openocd-config" 59 args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg" 60 args: "--serial" 61 args: "066DFF575051717867013127" 62 } 63 64 runner { 65 command: "stm32f429i_disc1_unit_test_runner" 66 args: "--openocd-config" 67 args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg" 68 args: "--serial" 69 args: "0667FF494849887767196023" 70 } 71 72 73Running the server 74^^^^^^^^^^^^^^^^^^ 75To start the standalone server, run the ``pw_target_runner_server`` program and 76point it to your config file. 77 78.. code:: text 79 80 $ pw_target_runner_server -config server_config.txt -port 8080 81 82 83Sending requests 84^^^^^^^^^^^^^^^^ 85To request the server to run an executable, run the ``pw_target_runner_client``, 86specifying the path to the executable through a ``-binary`` option. 87 88.. code:: text 89 90 $ pw_target_runner_client -host localhost -port 8080 -binary /path/to/my/test.elf 91 92This command blocks until the executable has finished running. Multiple 93requests can be scheduled in parallel; the server will distribute them among its 94available workers. 95 96Library APIs 97------------ 98To use the target runner library in your own code, refer to one of its 99programming language APIs below. 100 101.. toctree:: 102 :maxdepth: 1 103 104 go/docs 105