[Discuss-gnuradio] USRP1 full C++ API update merged into trunk

[Johnathan Corgan]

As initially discussed here:

http://lists.gnu.org/archive/html/discuss-gnuradio/2008-12/msg00106.html

...the fully native C++ implementation of the USRP API has been merged
into the GNU Radio trunk.  This is one of the last items to be completed
for the official 3.2 release.

Prior to this change, most of the USRP and daughterboard configuration
code was written in Python, and thus was only available to use from
Python GNU Radio applications.  This update is a rewrite of all of this
code using C++ and puts it in libusrp library, which allows C++ only
applications to use the full capabilities of the USRP hardware.  Much of
this work was done by Tom Rondeau.

In spite of this significant rewrite, most Python GNU Radio users do not
have to make any changes to their code and should see no difference in
functionality. 

The USRP hardware interface is now provided in three ways:

1) libusrp, which provides the lowest-level communications services over
USB to the USRP hardware.  This is a C++ based read/write raw sample
interface and does not provide any of the streaming semantics of GNU
Radio flowgraphs.

2) libgnuradio-usrp, which provides the GNU Radio C++ signal processing
blocks for the USRP.  This is implemented on top of libusrp and provides
the streaming interface to the USRP inside GNU Radio.

3) The python usrp module.  This is now only a thin Python wrapper
around libgnuradio-usrp, and continues to provide the usrp.source_c,
usrp.sink_c, etc. blocks that most GNU Radio users have already been
using.

API CHANGES

One goal of this API update was to remain as backward compatible as
possible with existing code users have written.  Unfortunately, because
of slight incompatibilities, two functions have changed.

The way to obtain a daughterboard instance subdevice number has been to
reference the _which instance variable.  This has changed to a function
call.  This is mostly commonly seen in this snippet of code:

tr = usrp.tune(self.subdev._which, self.subdev, target_freq)

...which is now:

tr = usrp.tune(self.subdev.which(), self.subdev, target_freq)

The other change has been to the installed daughterboard instance array,
which can be but isn't normally accessed by user code:

u = usrp.source_c()
subdev = u.db[0][0]

...now also becomes a function call:

subdev = u.db(0, 0)

UPDATING YOUR GNU RADIO SOFTWARE INSTALLATION

This only applies to people using the GNU Radio trunk software via svn;
this update does not affect release 3.1.x.

As there are many filename changes in both the source tree and installed
file set, you will need to first uninstall your existing GNU Radio
installation, then clean out the build files, *before* updating your
source code tree:

$ sudo make uninstall
$ make distclean
$ svn update

Then you can proceed with building the new trunk version as usual, per
the instructions for your particular OS/distribution.

This update adds a new compile and runtime dependency.  We have already
been using the Boost shared pointer, threading and date/time libraries;
GNU Radio now also uses the Boost program options library.  These are
likely already installed if you have Boost supplied by your OS
distribution.  If you had to compile Boost from scratch, you will need
recompile and reinstall, adding 'program_options' to the list of
libraries to install.  The GNU Radio build 'configure' step will tell
you if this library is missing.  See:

http://gnuradio.org/trac/browser/gnuradio/trunk/README.building-boost

...if you need further instruction on completing this step.

KNOWN ISSUES

As of this merge, there is one known issue that needs to be resolved.
When using the RFX series of USRP daughterboards, sometimes the 'tune'
command will correctly tune the card, yet report that the tuning has
failed.  Ironically, we think this is because the new tuning code is now
faster, and doesn't wait long enough for the daughterboard PLL to
settle.  A fix is being worked on.

Any problem reports may, as usual, be sent to the mailing list or
entered into the bug database for follow up.

Thank you, and Happy Holidays to everyone from the GNU Radio team.

Johnathan Corgan
Corgan Enterprises LLC