/gnu-radio-conference-2012/I've (finally) pushed the ControlPort work out to my public repo on Github. The repo is:
git://github.com/trondeau/gnuradio.git
And the branch with ControlPort is, amazingly enough, 'controlport.'
For those reading this who are unfamiliar with ControlPort, we announced it and I demo'd it at GRCon12. You can find my presentation here. ControlPort is a new set of hooks into GNU Radio to allow a remote client to attach to a running GNU Radio program and get and set parameters. It's quite a powerful concept with an SDR application, and we think that there are tons of ways to use this to improve on current work and to think of entirely new ways of using SDR.
When you look at the source code of the branch, and right now that's by far the best way to learn anything since we haven't spent any time on documenting its use, you'll see a few new things. First, there is a new top-level component called gr-ctrlport. This is where all of the code that goes into mechanics of ControlPort live. Second, you can look at a couple of other components for how ControlPort is used and tied into the build system, specifically gr-digital, gr-filter, and gr-channels.
One of the driving concepts behind ControlPort is that it is only an add-on to GNU Radio and not a requirement. We do not want to force people to build this and the required dependencies (we are using ZeroC's ICE for the communications backend) to continue doing their other GNU Radio work. So everything had to be made as separate as possible with the ability to test for ControlPort before being able to use it. So when you look at the directories like gr-digital, you will see that the CMakeLists.txt files check for ENABLE_GR_CTRLPORT before linking against the library or using ControlPort as a dependency. There are other checks that are internal to each block that uses ControlPort for the same purpose.
ControlPort's main focus is to create an external interface to a running GNU Radio application that will advertise parameters that you can set and get remotely. Much of the structure of gr-ctrlport is designed to make this interface simple and generic. Each block is responsible for exporting the variables as either gettable, settable, or both. The two blocks that showcase these capabilities are gr::digital::pfb_clock_sync_ccf and gr::channels::channel_model. You can look at these files to see how we've implemented the exposure of the various block's parameters.
But keep in mind that the interface will likely change. We are even now talking about ways to simplify the declaration of the parameters to be accessible over ControlPort. Hopefully, when we're done, the code will be even more readable.
There are still lots of details to be discussed and documentation of the use and development of ControlPort to come. This is just a general announcement of it's public availability and a brief taste of what we're doing and where we're going.
As a way to get started, the 'controlport' branch includes an example that uses ControlPort (there is a WXGUI and a QTGUI based version of this, actually). In gr-ctrlport/examples you can open the pfb_sync_test[-qt].grc in GNU Radio Companion. This simply simulates a QPSK signal going through a channel model and begin recovered using the PFB clock sync and a Costas Loop. Since the channel model and clock sync blocks both export parameters over control port, we can dynamically alter the simulation from a remote client.
When looking at the GRC canvas, you'll see a couple of ControlPort-specific items. As part of the graph, we have a 'Complex Probe (fixed len)'. This is one of the few blocks in gr-ctrlport. It exposes a vector of samples so that we can access them remotely, such as to plot. The other one is 'CtrlPort Monitor', which is up in the top left near the 'Options' block. This monitor is an application that we wrote to provide access to the items available over ControlPort. First, it looks for exposed endpoints from the running flowgraph, and if found, it will attach itself. Below is a screenshot of this application. You can see that it's a table of parameters with some properties. The key is the parameter name, defined as the name of the block and its unique ID number (unique within the running graph). You then get the current value, any units if they were specified, and a more detailed description.
When you double click on one of the rows, it will pop up with a graph to display that parameter. This is true if a) the block has set a 'get' function for this parameter (which is true here since the application only displays those parameters that are gettable) and b) a default display type was declared when the variable was exported. If no display type was given, nothing will happen. However, right-clicking will bring up a menu where you can select the type of plot to use.
Below is a screenshot of double-clicking on the 'probe2_c1::constellation row. This shows the IQ plot of the samples gathered by the probe in the flowgraph.
If a variable is settable like 'channel_model14::noise, you can right-click and bring up the properties window. This will give you an edit box and a slider to set the value.
Since ControlPort is really meant to be used across a network, this GRC example isn't any more exciting than just hinting at what's possible. But we can easily transform this example into such a remote operation. First, in the GRC graph, bring up the properties of the 'CtrlPort Monitor' block and turn 'Enabled' from True to False. Now, when we run the program, it will not automatically start the monitor application.
In the GRC console window, notice that the application now announces that it has created an endpoint that should be something like "Ice Radio Endpoint: gnuradio -t:tcp -h <local IP> -p <Port #>". This is the Ice endpoint that we connect to. Using a terminal on the local machine or another machine where this GNU Radio branch has been built and installed, you can use the gr-ctrlport-monitor application to connect to the running flowgraph:
gr-ctrlport-monitor 192.168.1.1 12345
Just make sure you're firewall settings allow you to use that particular port.
There will be a lot more said about ControlPort as we continue to develop it. I'll post more here, but we will be producing more structured documentation for how to use and develop with ControlPort.