PothosUtilGuide

PothosUtil guide table of contents

Introduction

PothosUtil (or PothosUtil.exe for windows) is the Swiss army knife of command line applications for Pothos. It comes installed with the main Pothos library, and provides a number of utilities to both the user, and internally to the library itself. In this guide we will document and explain the various capabilities of PothosUtil.

Querying system info

Query various information about the Pothos install, like directories and versions: :

PothosUtil --system-info
API Version: 0.2.0
ABI Version: 0.2-2
Root Path: /opt/usr
Data Path: /opt/usr/share/Pothos
User Data: /home/jblum/.local/share/Pothos
User Config: /home/jblum/.config/Pothos
Runtime Library: /opt/usr/lib/libPothosd.so
Util Executable: /opt/usr/bin/PothosUtil
Dev Include Path: /opt/usr/include
Dev Library Path: /opt/usr/lib

Viewing the plugin tree

The plugin tree is a directory-like structure containing Pothos plugins loaded from modules at initialization time. Plugins can be any thing from unit tests, to data type converters, to processing blocks, just to name a few. The entire tree or sub-paths of the tree can be viewed from the command line with PothosUtil.

View the entire plugin tree: :

PothosUtil --plugin-tree
/
/managed {N6Pothos8CallableE}
/managed/Pothos
/managed/Pothos/System
/managed/Pothos/System/Logger {N6Pothos12ManagedClassE}
/managed/Pothos/System/HostInfo {N6Pothos12ManagedClassE}
/managed/Pothos/System/NumaInfo {N6Pothos12ManagedClassE}
...... and so on  .......

View a plugin sub-tree: :

PothosUtil --plugin-tree=/proxy/environment
/proxy/environment
/proxy/environment/managed {N6Pothos8CallableE}
/proxy/environment/java {N6Pothos8CallableE} [/opt/usr/lib/Pothos/modules/proxy/environment/libJavaSupport.so]
/proxy/environment/python {N6Pothos8CallableE} [/opt/usr/lib/Pothos/modules/proxy/environment/libPythonSupport.so]

Querying device info

Many device support packages register an information query call into the plugin tree. This allows Pothos to query a JSON structure about arbitrary device information and present it to the user. This is used in the graphical tool to query information on each of the available hosts. PothosUtil will query device information for the host that the command is run on.

Query available device information plugins: :

PothosUtil --device-info

>>> Specify --device-info=deviceType for more information...
>>> Available device types in the plugin tree are: 
  * audio
  * sdr
  * opencl

Query a specific device information plugin: :

PothosUtil --device-info=sdr
>>> Querying device info: /devices/sdr/info

{
    "SDR Device" : [
        {
            "driver" : "rtl",
            "label" : "Realtek RTL2838UHIDIR SN: 00000001",
            "rtl" : "0"
        }
    ],
    "SoapySDR info" : {
        "ABI Version" : "0.1-3",
        "API Version" : "0.1.0",
        "Factories" : "bladerf, hackrf, null, rfspace, rtl, uhd",
        "Install Root" : "\/opt\/usr"
    }
}

Or dump that information to file for scripting purposes: :

PothosUtil --device-info=sdr --output=/tmp/sdr_info.json
>>> Querying device info: /devices/sdr/info

>>> Dumping info: /tmp/sdr_info.json

Running a proxy server

The proxy server is used for the remote topology feature to interact with object on a remote host. You can read more about the proxy server on the Remote Control Guide wiki page.

Spawn the proxy server on the default port, bind to all interfaces: :

PothosUtil --proxy-server=""

Spawn the proxy server, specify port, and bind address: :

PothosUtil --proxy-server="tcp://10.10.10.1:12345"

Running unit tests

Unit tests are registered into the plugin tree with the POTHOS_TEST_BLOCK() macro from Pothos/Testing.hpp. PothosUtil can run all unit tests in the tree, a sub-tree of unit tests, or individual unit tests. PothosUtil --self-tests is used to run multiple unit tests in the plugin tree. This option runs each unit test in a sub-process so if a unit test crashes the process, then the rest of the unit tests will continue to run. The PothosUtil --self-test1 us used to run a single unit test in the same process as the PothosUtil application itself. Users can see prints to stdout/stderr and run gdb on this invocation to debug the test.

Running all available unit tests: :

PothosUtil --self-tests
Testing /object/tests/test_object_equals... success!
Testing /object/tests/test_object_value... success!
Testing /object/tests/test_object_throw... success!
Testing /object/tests/test_object_mutable... success!
Testing /object/tests/test_object_mutable_copy_assigns... success!
Testing /object/tests/test_convert_numbers... success!
Testing /object/tests/test_convert_complex... success!
...... and so on  .......

Running unit tests from a sub-tree: :

PothosUtil --self-tests=/proxy/python
Testing /proxy/python/tests/test_basic_types... success!
Testing /proxy/python/tests/test_compare_to... success!
Testing /proxy/python/tests/test_containers... success!
Testing /proxy/python/tests/test_call_module... success!
Testing /proxy/python/tests/test_serialization... success!
Testing /proxy/python/tests/python_module_import... success!
Testing /proxy/python/tests/test_python_module... success!
Testing /proxy/python/tests/test_python_block... success!
Testing /proxy/python/tests/test_signals_and_slots... success!

All 9 tests passed!

Running a single unit test: :

PothosUtil --self-test1=/proxy/python/tests/test_serialization
Testing /proxy/python/tests/test_serialization... 
serialization::archive
Pothos::Object<Pothos::Proxy>pythoniishisbye0
success!

Running a single unit test with GDB: :

gdb --args PothosUtil --self-test1=/proxy/python/tests/test_serialization
#type run at the (gdb) prompt...

Running a JSON topology

PothosUtil can create and execute a topology from a JSON description, and even dump performance metrics to file. The format for the JSON description is documented in the Pothos/Topology.hpp header file.

Run a topology from file: :

PothosUtil --run-topology ~/Desktop/benchmark.json
>>> Create Topology: /home/jblum/Desktop/benchmark.json
>>> Running topology, press CTRL+C to exit

Run a topology for a fixed duration: :

PothosUtil --run-duration=20 --run-topology ~/Desktop/benchmark.json
>>> Create Topology: /home/jblum/Desktop/benchmark.json
>>> Running topology for 20 seconds

Dump the performance metrics to file: :

PothosUtil --run-duration=20 --output=/tmp/stats.json --run-topology ~/Desktop/benchmark.json
>>> Create Topology: /home/jblum/Desktop/benchmark.json
>>> Running topology for 20 seconds
>>> Dumping stats: /tmp/stats.json

Block description parser

Processing blocks generally have inline Block Description Markup within their code to document the functionality, and to describe its features to the graphical tools. PothosUtil can parse this inline markup into a structured JSON format for consumption by the graphical tools. This capability of PothosUtil is automatically called by the POTHOS_MODULE_UTIL() CMake function, and the user will probably not directly encounter it. However, it is documented here:

The doc-parse option takes a list of files and writes JSON to stdout: :

PothosUtil --doc-parse source1.hpp source2.cpp

[
    {
        "args" : [
            "dtype",
            "operation"
        ],
        "calls" : [
            {
...... and so on  .......

Or specify an output file for the JSON markup: :

PothosUtil --doc-parse source1.hpp source2.cpp --output=/tmp/desc.json

Or specify a plugin registry CPP source: :

PothosUtil --doc-parse source1.hpp source2.cpp --output=/tmp/pluginDocs.cpp