PothosUtilGuide
PothosUtil guide table of contents
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.
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
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]
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
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"
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...
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
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
