Call for testers: USRP1 and daughterboard API update


#1

As part of an overall transition to make the use of Python optional for
GNU
Radio application development, we are “pushing down” into C++ the API
for
those things that were previously only possible from Python. One of
these
areas is the USRP1 operation and daughterboard control. With this
latest
development, it is now possible to write C++ only GNU Radio applications
that use the USRP1 without hacking one’s own daughterboard interface
driver.

However, since access from Python is still needed for Python users, the
Python API for the USRP has been re-created using the SWIG wrapper
generator, in the same way we do this for the rest of the GNU Radio C++
API. This has necessitated a couple very minor changes (see below) to
user’s Python code.

When this code is merged into the development trunk, it will replace the
entire USRP Python API. As such, it is critical that this get
widespread
testing on all the platforms that GNU Radio supports.

INSTALLATION OF TEST BRANCH

The testing feature branch may be checked out from:

http://gnuradio.org/svn/gnuradio/branches/features/cppdb-test

Building this branch follows the same process as building the GNU Radio
trunk, with some caveats:

  • Do not try to install this “over” an existing GNU Radio installation.
    If
    you have compiled the GNU Radio trunk or official release from an svn
    checkout or tarball, and still have the source tree, perform a “sudo
    make
    uninstall” to remove the system installation before building the test
    branch. If you have installed from binary packages, uninstall these
    using
    your package manager. The key is to ensure all of an existing GNU Radio
    is
    removed from the system directories. If you know what you are doing, it
    is
    possible to maintain multiple installations of GNU Radio using
    environment
    variables and/or symlinks; this would continue to work for this testing
    version.

  • The test branch adds a new dependency. We are already using the Boost
    shared pointer, threading and date/time libraries; this branch also now
    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.

CHANGES IN THE TEST BRANCH

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)

The few occasions where these changes are needed in the GNU Radio
examples
directory have already been changed on the branch, and testers may need
to
modify their code to accommodate.

TESTING AREAS/PRIORITIES

First and foremost is to make sure we haven’t broken anything. This
applies
both to daughterboard operation (tuning, gain, etc.) and API
compatibility.
So please run all your usual USRP Python code and examples to make sure
it
all works the same.

Secondly, there are two new C++ applications which mirror the
usrp_siggen.py
and usrp_rx_cfile.py Python applications. These do not get installed,
but
may be found in the source tree after compilation at:

http://gnuradio.org/svn/gnuradio/branches/features/cppdb-test/gr-usrp/apps

These are examples of how to write C++ only applications in GNU Radio,
and
operate in a similar fashion to their Python counterparts. One
difference
is that we haven’t implemented the SI unit command line parsing yet, so
instead of something like ‘-f 16M’ you’ll need to put ‘-f 16e6’.

Finally, the new daughterboard API has actually been pushed all the way
down
into the non-GNU Radio libusrp library. So anyone using this library
for
USRP use can try out the new daughterboard code instead of what they
themselves have hacked togther.

SUCESS/BUG REPORTING

Success reports should be posted to the list. Expect lots of bugs,
especially in the beginning. If you run into difficulties, please post
here
on the list first, and include details about your setup and relevant
code.
If it is a bonafide new bug and we don’t fix it immediately, feel free
to
create a new ticket in the bug system:

http://gnuradio.org/trac/query

You will need to login to do so. The user name is ‘guest’, the password
‘gnuradio’.

This is one of the few remaining items pending for the official 3.2
release. Your help in shaking this feature out will be greatly
appreciated.

Johnathan C.
Corgan Enterprises LLC


#2

A question out of curiosity: you write “non-GNU Radio libusrp library”.
This
library is built when I download and compile the trunk. Isn’t it a part
of
GNU Radio ? Does python applications use this library ?

I am looking forward to test when my schedule allows!

BR/
Per


#3

On Mon, Dec 8, 2008 at 1:48 AM, Per Z.
removed_email_address@domain.invalid wrote:

A question out of curiosity: you write “non-GNU Radio libusrp library”. This
library is built when I download and compile the trunk. Isn’t it a part of
GNU Radio ? Does python applications use this library ?

To clarify, it would have been more accurate to say “non-GNU Radio
framework”. Both the USRP and USRP2 have low-level C++ libraries
(libusrp and libusrp2) which provide the lowest level communications
to the hardware. These provide a generic read/write API and don’t use
the GNU Radio runtime themselves. Some people have written
applications which only use this interface.

The GNU Radio source and sink blocks for the USRP and USRP2 (in
gr-usrp and gr-usrp2) are wrappers around this low-level interface and
provide the high-level streaming GNU Radio flowgraph semantics for C++
and Python GNU Radio applications.

Currently, much of the auxiliary USRP configuration and all of the
daughterboard handling code is written in Python, and thus can only be
used from Python. The new API code in cppdb-test rewrites all this in
C++ and puts it in libusrp. Thus, now C+±only GNU Radio applications
and libusrp-only applications can also use the full range of USRP
functionality.

Our eventual goal is to have 100% of the GNU Radio feature set
available in C++, with the Python API being a pure wrapper around it.
We’re nearly there; the USRP daughterboard handling was the largest
chunk of what is left.

-Johnathan