path: root/docs/exploring-gnuradio/exploring-gnuradio.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "docbookx.dtd" [
  <!ENTITY dial_tone_example SYSTEM "dial_tone_example.xml">
  <!ENTITY fm_demod_example SYSTEM "fm_demod_example.xml">
]>

<article>
<articleinfo>
  <title>Exploring GNU Radio</title>
  <author>
     <firstname>Eric</firstname>
     <surname>Blossom</surname>
     <affiliation>
        <address>
           <email>eb@comsec.com</email>
        </address>
     </affiliation>
  </author>

<revhistory>
  <revision>
  <revnumber>v1.1</revnumber>
  <date>2004-11-29</date>
  <revremark>
    Revised and expanded.  Examples now use 2.x code base.
  </revremark>
  </revision>

  <revision>
  <revnumber>v1.0</revnumber>
  <date>2004-02-29</date>
  <revremark>
  Initial version published in Linux Journal, Issue 122, June 2004, as
  <emphasis>GNU Radio: Tools for Exploring the RF Spectrum</emphasis>.
  </revremark>
  </revision>
</revhistory>

<abstract><para>This article provides an overview of the GNU Radio
toolkit for building software radios.
</para></abstract>

</articleinfo>

<sect1 id="intro"><title>Introduction</title>

<para>Software radio is the technique of getting code as close to the
antenna as possible. It turns radio hardware problems into software
problems. The fundamental characteristic of software radio is that
software defines the transmitted waveforms, and software demodulates
the received waveforms. This is in contrast to most radios in which
the processing is done with either analog circuitry or analog
circuitry combined with digital chips. GNU Radio is a free software
toolkit for building software radios.</para>

<para>Software radio is a revolution in radio design due to its ability to
create radios that change on the fly, creating new choices for
users. At the baseline, software radios can do pretty much anything a
traditional radio can do. The exciting part is the flexibility that
software provides you. Instead of a bunch of fixed function gadgets,
in the next few years we'll see a move to universal communication
devices. Imagine a device that can morph into a cell phone and get you
connectivity using GPRS, 802.11 Wi-Fi, 802.16 WiMax, a satellite
hookup or the emerging standard of the day. You could determine your
location using GPS, GLONASS or both.</para>

<para>Perhaps most exciting of all is the potential to build decentralized
communication systems. If you look at today's systems, the vast
majority are infrastructure-based. Broadcast radio and TV provide a
one-way channel, are tightly regulated and the content is controlled
by a handful of organizations. Cell phones are a great convenience,
but the features your phone supports are determined by the operator's
interests, not yours.</para>

<para>A centralized system limits the rate of innovation. We could take some
lessons from the Internet and push the smarts out to the
edges. Instead of cell phones being second-class citizens, usable only
if infrastructure is in place and limited to the capabilities
determined worthwhile by the operator, we could build smarter
devices. These user-owned devices would generate the network. They'd
create a mesh among themselves, negotiate for backhaul and be free to
evolve new solutions, features and applications.</para>

</sect1>

<sect1 id="block-diagram"><title>The Block Diagram</title>

<para><xref linkend="block-diagram-fig"/> shows a typical block
diagram for a software radio. To understand the software part of the
radio, we first need to understand a bit about the associated
hardware. Examining the receive path in the figure,
we see an antenna, a mysterious RF front end, an analog-to-digital
converter (ADC) and a bunch of code. The analog-to-digital converter
is the bridge between the physical world of continuous analog signals
and the world of discrete digital samples manipulated by
software.</para>

<figure id="block-diagram-fig"><title>Typical software radio block diagram</title>
<mediaobject>
<imageobject><imagedata fileref="swr-block-diagram.eps" format="EPS"/></imageobject>
<imageobject><imagedata fileref="swr-block-diagram.png" format="PNG"/></imageobject>
<caption><para></para></caption>
</mediaobject>
</figure>

<para>ADCs have two primary characteristics, sampling rate and dynamic
range. Sampling rate is the number of times per second that the ADC
measures the analog signal. Dynamic range refers to the difference
between the smallest and largest signal that can be distinguished;
it's a function of the number of bits in the ADC's digital output and
the design of the converter. For example, an 8-bit converter at most
can represent 256 (2<superscript>8</superscript>) signal levels, while
a 16-bit converter represents up to 65,536 levels. Generally speaking,
device physics and cost impose trade-offs between the sample rate and
dynamic range.</para>

<para>Before we dive into the software, we need to talk about a bit of
theory. In 1927, a Swedish-born physicist and electrical engineer
named Harry Nyquist determined that to avoid aliasing when converting
from analog to digital, the ADC sampling frequency must be at least
twice the bandwidth of the signal of interest. Aliasing is what makes
the wagon wheels look like they're going backward in the old westerns:
the sampling rate of the movie camera is not fast enough to represent
the position of the spokes unambiguously.</para>

<para>Assuming we're dealing with low pass signals - signals where the
bandwidth of interest goes from 0 to f<subscript>MAX</subscript>, the
Nyquist criterion states that our sampling frequency needs to be at
least 2 * f<subscript>MAX</subscript>. But if our ADC runs at 20 MHz,
how can we listen to broadcast FM radio at 92.1 MHz? The answer is the
RF front end. The receive RF front end translates a range of
frequencies appearing at its input to a lower range at its output. For
example, we could imagine an RF front end that translated the signals
occurring in the 90 - 100 MHz range down to the 0 - 10 MHz
range.</para>

<para>Mostly, we can treat the RF front end as a black box with a single
control, the center of the input range that's to be translated. As a
concrete example, a cable modem tuner module that we've employed
successfully has the following characteristics. It translates a 6 MHz
chunk of the spectrum centered between about 50 MHz and 800 MHz down to
an output range centered at 5.75 MHz. The center frequency of the
output range is called the intermediate frequency, or IF.</para>

<para>In the simplest-thing-that-possibly-could-work category, the RF front
end may be eliminated altogether. One GNU Radio experimenter has
listened to AM and shortwave broadcasts by connecting a 100-foot piece
of wire directly to his 20M sample/sec ADC.</para>

</sect1> 

<sect1 id="software"><title>On to the Software</title>

<para>GNU Radio provides a library of signal processing blocks and the
glue to tie it all together. The programmer builds a radio by creating
a graph (as in graph theory) where the vertices are signal processing
blocks and the edges represent the data flow between them. The
signal processing blocks are implemented in C++. Conceptually,
blocks process infinite streams of data flowing from their input
ports to their output ports. Blocks' attributes include the number
of input and output ports they have as well as the type of data that
flows through each. The most frequently used types are short, float
and complex.</para>

<para>Some blocks have only output ports or input ports. These serve as
data sources and sinks in the graph. There are sources that read from
a file or ADC, and sinks that write to a file, digital-to-analog
converter (DAC) or graphical display. About 100 blocks come with
GNU Radio. Writing new blocks is not difficult.</para>

<para>Graphs are constructed and run in Python.
<!-- <xref linkend="dial_tone_ex"/> -->
Example 1
is the "Hello World" of GNU Radio. It generates two sine waves and outputs
them to the sound card, one on the left channel, one on the
right.</para>

&dial_tone_example;

<para>We start by creating a flow graph to hold the blocks and
connections between them. The two sine waves are generated by the
gr.sig_source_f calls. The f suffix indicates that the source produces
floats. One sine wave is at 350 Hz, and the other is at
440 Hz. Together, they sound like the US dial tone.</para>

<para>audio.sink is a sink that writes its input to the sound card. It
takes one or more streams of floats in the range -1 to +1 as its
input. We connect the three blocks together using the 
<methodname>connect</methodname> method of the flow graph.</para>

<para><methodname>connect</methodname> takes two parameters, the
source endpoint and the destination endpoint, and creates a connection
from the source to the destination.  An endpoint has two components: a
signal processing block and a port number.  The port number specifies
which input or output port of the specified block is to be connected.
In the most general form, an endpoint is represented as a python tuple
like this: <literal>(block, port_number)</literal>.  When
<literal>port_number</literal> is zero, the block may be used alone.
</para>

<para>These two expressions are equivalent:</para>
<programlisting>
fg.connect ((src1, 0), (dst, 1))
fg.connect (src1, (dst, 1))
</programlisting>

<para>Once the graph is built, we start it. Calling
<methodname>start</methodname> forks one or more threads to run the
computation described by the graph and returns control immediately to
the caller. In this case, we simply wait for any keystroke.</para>

</sect1>

<sect1 id="fm-receiver"><title>A Complete FM Receiver</title>

<para>
<!-- <xref linkend="fm_demod_ex"/> -->
Example 2
shows a somewhat simplified but
complete broadcast FM receiver. It includes control of the RF front
end and all required signal processing. This example uses an RF front
end built from a cable modem tuner and a 20M sample/sec
analog-to-digital converter.</para>

&fm_demod_example;

<para>Like the Hello World example, we build a graph, connect the
blocks together and start it. In this case, our source, mc4020.source,
is an interface to the Measurement Computing PCI-DAS 4020/12
high-speed ADC.  We follow it with gr.freq_xlating_fir_filter_scf, a
finite impulse response (FIR) filter that selects the FM station we're
looking for and translates it to baseband (0Hz, DC). With the 20M
sample/sec converter and cable modem tuner, we're really grabbing
something in the neighborhood of a 6 MHz chunk of the spectrum. This
single chunk may contain ten or more FM stations, and
gr.freq_xlating_fir_filter_scf allows us to select the one we
want.</para>

<para>In this case, we select the one at the exact center of the IF of
the RF front end (5.75 MHz). The output of
gr.freq_xlating_fir_filter_scf is a stream of complex samples at
160,000 samples/second. We feed the complex baseband signal into
gr.quadrature_demod_cf, the block that does the actual FM
demodulation.</para>

<para>gr.quadrature_demod_cf works by subtracting the angle of
each adjacent complex sample, effectively differentiating the
frequency. The output of gr.quadrature_demod_cf contains the
left-plus-right FM mono audio signal, the stereo pilot tone at 19kHz,
the left-minus-right stereo information centered at 38kHz and any
other sub-carriers above that. For this simplified receiver, we finish
off by low pass filtering and decimating the stream, keeping only the
left-plus-right audio information, and send that to the sound card at
32,000 samples/sec.</para>

<para>For a more indepth look at how the FM receiver
works, please see "Listening to FM, Step by Step."</para>

</sect1>

<sect1 id="gui"><title>Graphical User Interfaces</title>

<para>Graphical interfaces for GNU Radio applications are built in
Python. Interfaces may be built using any toolkit you can access from
Python; we recommend wxPython to maximize cross-platform
portability. GNU Radio provides blocks that use interprocess
communication to transfer chunks of data from the real-time C++ flow
graph to Python-land. </para>

<!-- please add more here, including example code and screen shots -->

</sect1>

<sect1 id="hardware-requirements"><title>Hardware Requirements</title>

<para>GNU Radio is reasonably hardware-independent. Today's commodity
multi-gigahertz, super-scalar CPUs with single-cycle floating-point
units mean that serious digital signal processing is possible on the
desktop. A 3 GHz Pentium or Athlon can evaluate 3 billion
floating-point FIR taps/s. We now can build, virtually all in
software, communication systems unthinkable only a few years ago.</para>

<para>Your computational requirements depend on what you're trying to do,
but generally speaking, a 1 or 2 GHz machine with at least 256 MB of RAM
should suffice. You also need some way to connect the analog world to
your computer. Low-cost options include built-in sound cards and
audiophile quality 96 kHz, 24-bit, add-in cards. With either of these
options, you are limited to processing relatively narrow band signals
and need to use some kind of narrow-band RF front end.</para>

<para>Another possible solution is an off-the-shelf, high-speed PCI
analog-to-digital board. These are available in the 20M sample/sec
range, but they are expensive, about the cost of a complete PC. For
these high-speed boards, cable modem tuners make reasonable RF front
ends.</para>

<para>Finding none of these alternatives completely satisfactory, we
designed the Universal Software Radio Peripheral, or USRP for short.
</para>

</sect1>

<sect1 id="usrp"><title>The Universal Software Radio Peripheral</title>

<para>Our preferred hardware solution is the Universal Software Radio
Peripheral (USRP). <xref linkend="usrp-block-diagram-fig"/> shows the
block diagram of the USRP. The brainchild of Matt Ettus, the USRP is
an extremely flexible USB device that connects your PC to the RF
world. The USRP consists of a small motherboard containing up to four
12-bit 64M sample/sec ADCs, four 14-bit, 128M sample/sec DACs, a
million gate-field programmable gate array (FPGA) and a programmable
USB 2.0 controller. Each fully populated USRP motherboard supports
four daughterboards, two for receive and two for transmit. RF front
ends are implemented on the daughterboards. A variety of
daughterboards is available to handle different frequency bands. For
amateur radio use, low-power daughterboards are available that receive
and transmit in the 440 MHz band and the 1.24 GHz band. A receive-only
daughterboard based on a cable modem tuner is available that covers
the range from 50 MHz to 800 MHz. Daughterboards are designed to be easy
to prototype by hand in order to facilitate experimentation.</para>

<figure id="usrp-block-diagram-fig"><title>Universal Software Radio Peripheral</title>
<mediaobject>
<imageobject><imagedata fileref="usrp-block-diagram.eps" format="EPS"/></imageobject>
<imageobject><imagedata fileref="usrp-block-diagram.png" format="PNG"/></imageobject>
<caption><para></para></caption>
</mediaobject>
</figure>

<para>The flexibility of the USRP comes from the two programmable components
on the board and their interaction with the host-side library. To get
a feel for the USRP, let's look at its boot sequence. The USRP itself
contains no ROM-based firmware, merely a few bytes that specify the
vendor ID (VID), product ID (PID) and revision. When the USRP is
plugged in to the USB for the first time, the host-side library sees
an unconfigured USRP. It can tell it's unconfigured by reading the
VID, PID and revision. The first thing the library code does is
download the 8051 code that defines the behavior of the USB peripheral
controller. When this code boots, the USRP simulates a USB disconnect
and reconnect. When it reconnects, the host sees a different device:
the VID, PID and revision are different. The firmware now running
defines the USB endpoints, interfaces and command handlers. One of the
commands the USB controller now understands is load the FPGA. The
library code, after seeing the USRP reconnect as the new device, goes
to the next stage of the boot process and downloads the FPGA
configuration bitstream.</para>

<para>FPGAs are generic hardware chips whose behavior is determined by the
configuration bitstream that's loaded into them. You can think of the
bitstream as object code. The bitstream is the output of compiling a
high-level description of the design. In our case, the design is coded
in the Verilog hardware description language. This is source code and,
like the rest of the code in GNU Radio, is licensed under the GNU
General Public License.</para>

</sect1>

<sect1 id="fpga"><title>What Goes in the FPGA?</title>

<para>An FPGA is like a small, massively parallel computer that you design
to do exactly what you want. Programming the FPGA takes a bit of
skill, and mistakes can fry the board permanently. That said, we
provide a standard configuration that is useful for a wide variety of
applications.</para>

<para>Using a good USB host controller, the USRP can sustain 32 MB/sec across
the USB. The USB is half-duplex. Based on your needs, you partition
the 32 MB/sec between the transmit and the receive directions. In the
receive direction, the standard configuration allows you to select the
part or parts of the digitized spectrum you're interested in,
translate them to baseband and decimate as required. This is exactly
equivalent to what's happening in the RF front end, only now we're
doing it on digitized samples. The block of code that performs this
function is called a digital down converter (<xref linkend="ddc-fig"/>).
One advantage of performing this function in the digital domain is we can change the
center frequency instantaneously, which is handy for frequency hopping
spread spectrum systems.</para>

<figure id="ddc-fig"><title>Digital Down Converter Block Diagram</title>
<mediaobject>
<imageobject><imagedata fileref="ddc.eps" format="EPS"/></imageobject>
<imageobject><imagedata fileref="ddc.png" format="PNG"/></imageobject>
<caption><para></para></caption>
</mediaobject>
</figure>


<para>In the transmit direction, the exact inverse is performed. The FPGA
contains multiple instances of the digital up and down
converters. These instances can be connected to the same or different
ADCs, depending on your needs. We don't have room here to cover all
the theory behind them; see the GNU Radio Wiki for more information.</para>

</sect1>

<sect1 id="apps"><title>GNU Radio Applications</title>

<para>In addition to the examples discussed above, GNU Radio comes with a
complete HDTV transmitter and receiver, a spectrum analyzer, an
oscilloscope, concurrent multichannel receiver and an ever-growing
collection of modulators and demodulators.</para>

<para>Projects under investigation or in progress include:</para>

<itemizedlist>
<listitem><para>A TiVo equivalent for radio, capable of recording multiple stations simultaneously.</para></listitem>
<listitem><para>Time Division Multiple Access (TDMA) waveforms.</para></listitem>
<listitem><para>A passive radar system that takes advantage of
broadcast TV for its signal source. For those of you with old TVs
hooked to antennas, think about the flutter you see when airplanes fly
over.</para></listitem>
<listitem><para>Radio astronomy.</para></listitem>
<listitem><para>TETRA transceiver.</para></listitem>
<listitem><para>Digital Radio Mundial (DRM).</para></listitem>
<listitem><para>Software GPS.</para></listitem>
<listitem><para>Distributed sensor networks.</para></listitem>
<listitem><para>Distributed measurement of spectrum utilization.</para></listitem>
<listitem><para>Amateur radio transceivers.</para></listitem>
<listitem><para>Ad hoc mesh networks.</para></listitem>
<listitem><para>RFID detector/reader.</para></listitem>
<listitem><para>Multiple input multiple output (MIMO) processing. </para></listitem>
</itemizedlist>

</sect1>

<sect1 id="politics"><title>Politics</title>

<para>Every revolution has its political issues. Free software for building
radios is troublesome to some people. In the US, we've run into
opposition from the Motion Picture Association of America and its
attempt with the Broadcast Flag to restrict the kinds of receivers
that can be built for over-the-air digital TV.</para>

<para>The US Federal Communications Commission has issued a Notice of
Proposed Rule Making (NPRM) concerning Cognitive Radio
Technologies and Software Defined Radios.  Several troublesome
issues are raised in the NPRM, including restricting the sale of
high-speed digital-to-analog converters, requirements for digital
signatures or similar methods to keep unauthorized software out of
software radio hardware and new restrictions on radios built for the
amateur radio market.</para>

</sect1>

<sect1 id="summary"><title>Summary</title>

<para>Software radio is an exciting field, and GNU Radio provides the tools
to start exploring. A deep understanding of software radio requires
knowledge from many domains. We're doing our best to lower the
barriers to entry.</para>
</sect1>

<!-- FIXME
<sect1 id="resource"><title>Resources</title>
<para></para>
</sect1>
-->

</article>