ControlPort

ControlPort

ControlPort is a new interface for standardizing remote procedure calls in GNU Radio:

• Remote control and visualization.
• Use of ControlPort to enable debugging without requiring extra debug streams.
• Abstracted interface for different back-end solutions.
• No additional CPU usage while no monitoring is occurring.
• Can connect multiple remotes to same GNU Radio application.
• Can also have single ControlPort app control multiple GR apps.

Each block defines interfaces to control data members.

Defines ‘get’ and ‘set’ interface to query and update values of blocks.

Currently, we are using the Apache Thrift project for the ControlPort backend. See below for details.

Use preference files to control the state of ControlPort:

• Edit section [ControlPort] in gnuradio-runtime.conf.
  • on: Set to True/On/1 or False/Off/0. Default=False.
  • edges_list: toggle exporting list of flowgraph edges (used by gr-perf-monitorx).

Comes with a generic utility to allow you to see all interfaces of a flowgraph (make sure firewalls are set up to allow the connection):

• gr-ctrlport-monitor <ip address or host name> <port>
  • Tables lists all interfaces.
  • Update time defaults to 1 second and can be changed through the top menu.
  • Double clicking will open up an interfaces default GUI style handler (if it doesn't, no default exists).
  • Right click on an item will pop up a menu to select which type of plot to use.
  • Drag-and-drop any item on an existing graph to plot multiple items.
  • 'Tile' button or Ctrl-t will tile all open windows.

• gr-perf-monitorx <ip address or host name> <port>
  • Shows graph of the remote flowgraph.
    • Blue nodes are blocks, and the size is proportional to the 'work time' performance counter.
    • Red edges are buffers, and the size and darkness are proportional to the '% output buffer full" performance counter.
  • Updates every 1 second.
  • Change type of performance counter statistic: instantaneous, average, or variance.
  • Change the clock used in the performance counters.
    • Thread is how much compute time is spent in a block's work function.
    • Monotonic is how much wall clock time has passed between entering and exiting work.
  • Can open Runtime and Buffer Tables to see table or bar graphs of percent of each perf counter.
  • Can drag-and-drop blocks around the canvas to reorganize the display.
  • Reset button resets the performance counter stats.
  • Pause button stops the remote flowgraph; click again to restart.
  • 'Tile' button or Ctrl-t will tile all open windows.

Apache Thrift

ControlPort requires a Thrift version of 0.9.2 or greater. On many systems, this is not the default version shipped with the OS, so we will need to install it. The PyBOMBS recipe builds an acceptable version.

To manually install the required version of Thrift on Ubuntu 14.04:

• Install some additional dependencies:
  • apt-get install bison flex libevent-dev
  • Install "python-twisted" package (it provide the "trial" package that thrift requires and it fails silently if it does not find it...)
  • I also had to install "openssl-devel" (it contains the "libcrypto" library that thrift requires) on Fedora
  • Install libtool (if not already present on your system)
• Clone the repo and check out version 0.9.2:
  • git clone https://github.com/apache/thrift.git thrift
  • cd thrift
  • git checkout 0.9.2
• Configure:
  • ./bootstrap
  • ./configure --prefix=$prefix PY_PREFIX=$prefix --with-cpp --with-python CXXFLAGS="-DNDEBUG"
• Make sure C++ and Python Libraries are supported.
• Build and install:
  • make
  • sudo make install

Normally, you can install using $prefix=/usr. If using anything other than that, you also need the PY_PREFIX set because Thrift ignores the normal --prefix for Python installations and this forces the issue.

Depending on your linux distribution, thrift's configure system fails to set the suffixes for Boost's unittest library correctly. You can fix that by hand, or work around it by disabling tests. Similar issues arise from the tutorials being built, lua and perl bindings; PyBOMBS disables those. To make thrift build without modification, I had to disable all this on a fedora 21:

/configure --prefix=/home/marcus/.usrlocal --disable-tests --with-lua=no --disable-tutorial --with-perl=no

This installs the Python files into $prefix/lib/python2.7/site-packages, which may not be in PYTHONPATH, so add it:

• export PYTHONPATH=$PYTHONPATH:/usr/lib/python2.7/site-packages

Or, to make it sticky between reboots, add the same line to your .bashrc file. If using pybombs, consider "source-ing" a generated environment file (pybombs env) ala

• source $prefix/setup_env.sh

Thrift 0.9.2 Shutdown Patch

Iff you run into problems with segfaults during shutdown, we might have a patch that fixes that in Thrift itself. You can find it in the source code:

source:gnuradio-runtime/lib/controlport/thrift/thrift-codebase-shutdown-patch.diff

And there is a README in that directory as well to explain a bit about the situation. I suspect this will not affect most people, and for anyone who comes across it, you'll only see it when shutting down your application.

Building GNU Radio

When building GNU Radio, make sure that the build script is picking up Thrift and running everything properly. When cmake finishes, it prints out a list of enabled components, and you should see this:

-- ######################################################
-- # Gnuradio enabled components                         
-- ######################################################
--   * python-support
--   * testing-support
--   * gnuradio-runtime
--   * gr-ctrlport
--   * * thrift
.... (more components)

If you don't see the "* * thrift" at this stage, cmake did not find the necessary C++ and Python support. Look back at the full cmake output to find the section on ControlPort. A successful configuration looks like:

-- Configuring gr-ctrlport support...
--   Dependency Boost_FOUND = 1
--   Dependency SWIG_FOUND = TRUE
--   Dependency SWIG_VERSION_CHECK = TRUE
--   Dependency ENABLE_GNURADIO_RUNTIME = ON
--   Enabling gr-ctrlport support.
--   Override with -DENABLE_GR_CTRLPORT=ON/OFF
-- Loading build date Thu, 06 Aug 2015 16:47:33 into constants...
-- Loading version 3.7.8 into constants...
-- 
-- Python checking for Thrift
-- Python checking for Thrift - found
-- Found and enabling Thrift backend to ControlPort
-- Running thrift to build C++ bindings

If you have installed GNU Radio already, you can check to see what components are available and look for "* thrift" in this list:

gnuradio-config-info --enabled-components
python-support;testing-support;volk;gnuradio-runtime;gr-ctrlport;* thrift;... (more components)