What is GNU Radio and why do I want it?

GNU Radio is a free & open-source software development toolkit that provides signal processing blocks to
implement software radios. It can be used with readily-available low-cost external RF hardware to create
software-defined radios, or without hardware in a simulation-like environment. It is widely used in hobbyist,
academic and commercial environments to support both wireless communications research and real-world
radio systems.

What's a Software Radio?

Have a look at the Wikipedia page. In brief, a software radio is a radio system which performs the required
signal processing in software instead of using dedicated integrated circuits in hardware. The benefit is that
since software can be easily replaced in the radio system, the same hardware can be used to create many
kinds of radios for many different transmission standards; thus, one software radio can be used for a variety
of applications!

So what exactly does GNU Radio do?

GNU Radio performs all the signal processing. You can use it to write applications to receive data out of
digital streams or to push data into digital streams, which is then transmitted using hardware. GNU Radio has
filters, channel codes, synchronisation elements, equalizers, demodulators, vocoders, decoders, and many
other elements (in the GNU Radio jargon, we call these elements blocks) which are typically found in radio
systems. More importantly, it includes a method of connecting these blocks and then manages how data is
passed from one block to another. Extending GNU Radio is also quite easy; if you find a specific block that is
missing, you can quickly create and add it.
Since GNU Radio is software, it can only handle digital data. Usually, complex baseband samples are the
input data type for receivers and the output data type for transmitters. Analog hardware is then used to shift
the signal to the desired centre frequency. That requirement aside, any data type can be passed from one
block to another - be it bits, bytes, vectors, bursts or more complex data types.
GNU Radio applications are primarily written using the Python programming language, while the supplied,
performance-critical signal processing path is implemented in C++ using processor floating point extensions,
where available. Thus, the developer is able to implement real-time, high-throughput radio systems in a
simple-to-use, rapid-application-development environment.
A more in-depth explanation is given in the core concepts tutorial.

Must I be able to program to use GNU Radio?

It's extremely useful. However, there are ways to use GNU Radio without being able to code. First, there's
the GNU Radio Companion, a graphical user interface similar to Simulink. It allows you to create signal
processing applications by drag-and-drop. Also, GNU Radio comes with a set of ready-to-use tools and utility
programs. These serve to manage the most basic operations, such as recording RF signals and performing
spectrum analysis. If this has sparked your interest, perhaps have a look at the beginner's guide how to use
GNU Radio.
If you want to extend GNU Radio (i.e., add new functionality), however, then you must write code. For
creating applications that are too complex for the GNU Radio Companion, Python is the easiest way to go.
For performance-critical code, you should write C++ code.

How is GNU Radio licensed?

GNU Radio is licensed under the GNU General Public License (GPL) version 3. All of the code is copyright of
the Free Software Foundation.
What have people done with GNU Radio?
If you install GNU Radio, it comes with a lot of examples. You can find tools to transmit data digitally, receive
analog waveforms, and all kinds of other things. Others have posted code to CGRAN, a 3rd party repository
of projects. Other projects are listed on our list of projects.

Digital signal processing, baseband, synchronisation... what

does all of this mean?
If you're asking these questions, you might have some trouble working with GNU Radio.
In order to create signal processing and radio communications software, you need to know a few things about
signal processing. But, don't let this deter you!
Grab a book, start reading, write some code and see what happens. Just a piece of advice: If you're asking
something related to a signal or its processing on the mailing list, it might be a good idea to get a feeling for
complex signals first.
The GNU Radio wiki has a page on suggested reading, so if you need some book or tutorial to get you
started on digital signal processing, that's a good place to start looking.

HowToUse
From GNU Radio

Contents
[hide]

 1How do I use GNU Radio?

 1.1Using the included tools and utility programs
 1.2Graphical signal processing development: The GNU Radio Companion
(GRC)
 1.3Using Python to write powerful signal processing and radio applications
 1.4The C++ domain: Extending GNU Radio
 1.5Figuring out how stuff is done: read the examples

How do I use GNU Radio?

Even after successfully installing GNU Radio, it might not be clear what exactly GNU Radio
is capable of and what it can be used for. This article will give an overview of what you can
do with GNU Radio and how to do it.

Using the included tools and utility programs

GNU Radio comes with a large variety of tools and programs which can be used out of the
box. If you installed from source, you can find most of the source files in gr-
utils/src/python and gr-uhd/apps. If you're using Linux and installed GNU Radio from
source (e.g. by using the build-gnuradio script), these programs get installed
into /usr/local/bin or /usr/bin.

The most commonly used tools include

 uhd_fft - A very simple spectrum analyzer tool which uses a connected UHD device
(i.e., a USRP) to display the spectrum at a given frequency. This can be also used for a
waterfall plot or as an oscilloscope.
 uhd_rx_cfile - Record an I/Q sample stream using a connected UHD device. Samples
are written to a file and can be analysed off-line at a later time, using either GNU
Radio or other tools such as Octave or Matlab.
 uhd_rx_nogui - Receive and listen to incoming signals on your audio device. This tool
can demodulate AM and FM signals.
 uhd_siggen_gui - Simple signal generator, can create the most common signals (sine,
sweep, square, noise).
 gr_plot* - This is an entire suite of apps which can display pre-recorded samples saved
to a file. You can plot the spectra, PSD and time-domain representations of these
signals.

If you're using Linux, you can call all these apps from the command line. All apps include a
"-h" switch which will display a help screen. With the uhd_fft tool, this would look like this:

$ uhd_fft --help
linux; GNU C++ version 4.5.2; Boost_104200; UHD_003.003.000-d5d448e

Usage: uhd_fft.py [options]

Options:
-h, --help show this help message and exit
-a ADDRESS, --address=ADDRESS
Address of UHD device, [default=addr=192.168.10.2]
-A ANTENNA, --antenna=ANTENNA
select Rx Antenna where appropriate
-s SAMP_RATE, --samp-rate=SAMP_RATE
set sample rate (bandwidth) [default=1000000.0]
-f FREQ, --freq=FREQ set frequency to FREQ
-g GAIN, --gain=GAIN set gain in dB (default is midpoint)
-W, --waterfall Enable waterfall display
-S, --oscilloscope Enable oscilloscope display
--avg-alpha=AVG_ALPHA
Set fftsink averaging factor, default=[0.1]
--ref-scale=REF_SCALE
Set dBFS=0dB input value, default=[1.0]
--fft-size=FFT_SIZE Set number of FFT bins [default=1024]

This is what it looks when used with a USRP1 and a DBSRx daughterboard observing a GSM
downlink:

$ uhd_fft.py -a type=usrp1 -f 935M -s 2M

Graphical signal processing development: The GNU Radio
Companion (GRC)
Digital signal processing (DSP) is where GNU Radio shines; this is what it was originally
made for. GRC is a Simulink-like graphical tool to design signal processing flow graphs. If
you're comfortable dealing with FIR filters, digital modulators and other DSP concepts, using
GRC should be simple and straightforward for you.

On Linux systems, GRC is invoked by calling the gnuradio-companion command. If your

installation was fine, GRC will pop up in its own window. On the right hand side, you can
find all the available blocks (good news: adding new blocks is not terribly difficult!), which
can be dragged into the main window and connected by clicking the edges. GRC has it's own
wiki page.
Here's an example of a narrowband FM receiver, which filters a signal, FM demodulates it and passes it
to the sound card (this and other examples can be found on www.oz9aec.net.

Using Python to write powerful signal processing and radio

applications
Sometimes GRC cannot provide all the flexibility required for your application. Anything that
can be clicked together in GRC can also be written in Python, and while it is more of an effort
to code everything yourself, it also provides you with the entire power and functionality of
Python and its libraries, such as SciPy or NumPy for Python-centric processing of your
signals or your favorite widget library to create any GUI you wish.

Have a look at the Python apps tutorial to find out how to go ahead here. The tutorial also
includes an introduction to the main GNU Radio concepts, such as flow graphs.
The C++ domain: Extending GNU Radio
GNU Radio is extremely powerful and includes many kinds of signal processing blocks.
However, if you're developing something particular, chances are high that sooner or later
you'll be running into some component which is lacking; be it a specific channel code, a
segmentation algorithm or whatever. In this case, you will want to write your own blocks to
add them into GNU Radio. This is usually done in C++, in order to keep GNU Radio as fast
as it is. If this is what you need, check out the tutorial on how to write a new block.

Figuring out how stuff is done: read the examples

Starting to develop stuff using GNU Radio may seem daunting at first. GNU Radio is a
powerful but scary beast, but has a steep learning curve.
The best way to start to understand how GNU Radio works is to look at examples. Under
Linux, they usually get installed /usr/local/share/gnuradio/examples. There are literally
several hundred example files to discover, sorted by topic.

In the source tree, the examples are in the sub-directory they belong to. All examples to do
with digital modulation are in 'gr-digital/examples', all examples concerning filters (that
includes resampling etc.) are in 'gr-filter/examples' etc. GNU Radio provides examples for
Python, GNU Radio companion and C++.

Retrieved from "https://wiki.gnuradio.org/index.php?title=HowToUse&oldid=800"

 This page was last modified on 30 June 2017, at 21:35.

 Content is available under Creative Commons Attribution-ShareAlike unless otherwise
noted.

HowToUse
From GNU Radio

Contents
[hide]

 1How do I use GNU Radio?

 1.1Using the included tools and utility programs
 1.2Graphical signal processing development: The GNU Radio Companion
(GRC)
 1.3Using Python to write powerful signal processing and radio applications
 1.4The C++ domain: Extending GNU Radio
 1.5Figuring out how stuff is done: read the examples
How do I use GNU Radio?
Even after successfully installing GNU Radio, it might not be clear what exactly GNU Radio
is capable of and what it can be used for. This article will give an overview of what you can
do with GNU Radio and how to do it.

Using the included tools and utility programs

GNU Radio comes with a large variety of tools and programs which can be used out of the
box. If you installed from source, you can find most of the source files in gr-
utils/src/python and gr-uhd/apps. If you're using Linux and installed GNU Radio from
source (e.g. by using the build-gnuradio script), these programs get installed
into /usr/local/bin or /usr/bin.

The most commonly used tools include

 uhd_fft - A very simple spectrum analyzer tool which uses a connected UHD device
(i.e., a USRP) to display the spectrum at a given frequency. This can be also used for a
waterfall plot or as an oscilloscope.
 uhd_rx_cfile - Record an I/Q sample stream using a connected UHD device. Samples
are written to a file and can be analysed off-line at a later time, using either GNU
Radio or other tools such as Octave or Matlab.
 uhd_rx_nogui - Receive and listen to incoming signals on your audio device. This tool
can demodulate AM and FM signals.
 uhd_siggen_gui - Simple signal generator, can create the most common signals (sine,
sweep, square, noise).
 gr_plot* - This is an entire suite of apps which can display pre-recorded samples saved
to a file. You can plot the spectra, PSD and time-domain representations of these
signals.

If you're using Linux, you can call all these apps from the command line. All apps include a
"-h" switch which will display a help screen. With the uhd_fft tool, this would look like this:

$ uhd_fft --help
linux; GNU C++ version 4.5.2; Boost_104200; UHD_003.003.000-d5d448e

Usage: uhd_fft.py [options]

Options:
-h, --help show this help message and exit
-a ADDRESS, --address=ADDRESS
Address of UHD device, [default=addr=192.168.10.2]
-A ANTENNA, --antenna=ANTENNA
select Rx Antenna where appropriate
-s SAMP_RATE, --samp-rate=SAMP_RATE
set sample rate (bandwidth) [default=1000000.0]
-f FREQ, --freq=FREQ set frequency to FREQ
-g GAIN, --gain=GAIN set gain in dB (default is midpoint)
-W, --waterfall Enable waterfall display
-S, --oscilloscope Enable oscilloscope display
--avg-alpha=AVG_ALPHA
 Set fftsink averaging factor, default=[0.1]
--ref-scale=REF_SCALE
Set dBFS=0dB input value, default=[1.0]
--fft-size=FFT_SIZE Set number of FFT bins [default=1024]

This is what it looks when used with a USRP1 and a DBSRx daughterboard observing a GSM
downlink:

$ uhd_fft.py -a type=usrp1 -f 935M -s 2M

Graphical signal processing development: The GNU Radio

Companion (GRC)
Digital signal processing (DSP) is where GNU Radio shines; this is what it was originally
made for. GRC is a Simulink-like graphical tool to design signal processing flow graphs. If
you're comfortable dealing with FIR filters, digital modulators and other DSP concepts, using
GRC should be simple and straightforward for you.

On Linux systems, GRC is invoked by calling the gnuradio-companion command. If your

installation was fine, GRC will pop up in its own window. On the right hand side, you can
find all the available blocks (good news: adding new blocks is not terribly difficult!), which
can be dragged into the main window and connected by clicking the edges. GRC has it's own
wiki page.

Here's an example of a narrowband FM receiver, which filters a signal, FM demodulates it

and passes it to the sound card (this and other examples can be found on www.oz9aec.net.

Using Python to write powerful signal processing and radio

applications
Sometimes GRC cannot provide all the flexibility required for your application. Anything that
can be clicked together in GRC can also be written in Python, and while it is more of an effort
to code everything yourself, it also provides you with the entire power and functionality of
Python and its libraries, such as SciPy or NumPy for Python-centric processing of your
signals or your favorite widget library to create any GUI you wish.

Have a look at the Python apps tutorial to find out how to go ahead here. The tutorial also
includes an introduction to the main GNU Radio concepts, such as flow graphs.
The C++ domain: Extending GNU Radio
GNU Radio is extremely powerful and includes many kinds of signal processing blocks.
However, if you're developing something particular, chances are high that sooner or later
you'll be running into some component which is lacking; be it a specific channel code, a
segmentation algorithm or whatever. In this case, you will want to write your own blocks to
add them into GNU Radio. This is usually done in C++, in order to keep GNU Radio as fast
as it is. If this is what you need, check out the tutorial on how to write a new block.

Figuring out how stuff is done: read the examples

Starting to develop stuff using GNU Radio may seem daunting at first. GNU Radio is a
powerful but scary beast, but has a steep learning curve.
The best way to start to understand how GNU Radio works is to look at examples. Under
Linux, they usually get installed /usr/local/share/gnuradio/examples. There are literally
several hundred example files to discover, sorted by topic.

In the source tree, the examples are in the sub-directory they belong to. All examples to do
with digital modulation are in 'gr-digital/examples', all examples concerning filters (that
includes resampling etc.) are in 'gr-filter/examples' etc. GNU Radio provides examples for
Python, GNU Radio companion and C++.

Retrieved from "https://wiki.gnuradio.org/index.php?title=HowToUse&oldid=800"

 This page was last modified on 30 June 2017, at 21:35.

 Content is available under Creative Commons Attribution-ShareAlike unless otherwise
noted.

GNURadioCompanion
From GNU Radio

Contents
[hide]

 1GNU Radio Companion

 1.1New Features
 1.2Requirements
 1.2.1GRC Requirements
 1.2.2GNU Radio Requirements
 1.3Installation
 1.3.1Installing GRC
  1.3.2Installing Documentation
 1.3.3Installing Icons, Mime Type, and Menu Items
 1.4Execution
 1.4.1Executing the Flow Graph Editor
 1.5Usage Tips
 1.6Variables
 1.6.1Variable Block
 1.6.2Variable Controls
 1.6.3String Evaluation
 1.7Filter Design
 1.7.1Firdes Taps Generators
 1.7.2Firdes Window Types
 1.7.3Firdes Notes
 1.7.4Firdes Usage Example
 1.7.5Use Taps from a File
 1.8Grid Positioning
 1.8.1Example
 1.9Hierarchical Blocks
 1.9.1The Options Block
 1.9.2Parameter Blocks
 1.9.3Pad Source and Sink Blocks
 1.9.4Creating and Instantiating
 1.9.5Notes
 1.10Adding Custom Blocks
 1.10.1Creating the XML Block Definition
 1.10.2Some Example Definitions
 1.10.3Installing the XML Block Definition
 1.10.3.1Method 1: Default Hier Block Location
 1.10.3.2Method 2: Configuration File
 1.10.3.3Method 3: Environment Variable
 1.11Special Thanks
 1.12Screen Shots

GNU Radio Companion

GNU Radio Companion (GRC) is a graphical tool for creating signal flow graphs and
generating flow-graph source code. There is a GNU Radio Companion Working
Group handling the development.

New Features
What has changed in GRC since the stable 0.70 release?
 Bundled - GRC is now bundled with the gnuradio source. If all dependencies are met,
grc will be installed with gnuradio. *See the Installation and Execution section.

 Desktop Integration - GRC can be fully integrated into a desktop environment that
supports freedesktop standards (courtesy of xdg-utils): icons, mime type, and menu
items

 Code Generation - GRC no longer uses a single executable to load a *.grc.xml file and
dynamically build the flow graph. Rather, GRC uses Cheetah templates to generate
the python source code for the flow graph. GRC can generate source code for WX GUI
and non-GUI flow graphs as well as hierarchical blocks.

 Documentation - GRC can extract documentation for GNU Radio blocks directly from
the doxygen-generated xml files. You will need to configure your gnuradio installation
with doxygen support to use this feature.

 Variables - The variable editor window of past releases has been replaced with
variable blocks. Variable blocks show up in the flow graph and act like any other
block, except that they have no IO ports. The variable block maps a unique id (variable
name) to a particular value. GRC also has several graphical variable blocks that allow
one to create WX GUI flow graphs with graphical controls using sliders, text boxes,
buttons, drop downs, and radio buttons.

 Block Definitions - Every block in GRC has a corresponding xml file that contains
parameters, IO ports, and a template for code generation. The id key and file name of
each xml file matches up exactly with the name of the GNU Radio block to ensure
future portability. GRC validates all blocks definitions upon execution, and will exit
with error if any definitions fail the validation.

 File Format - Given that the variables and block definitions have changed, the internal
structure of the saved flow graph files has also changed. Fortunately, GRC can
automatically convert older saved flow graph files to the new format. Unfortunately,
the conversion cannot always be 100%.

 Block Manipulation - Ever wish that you could take a block out of your
transmit/receive chain, but not delete it? Blocks now have an enabled/disabled state.
By default, a block is enabled. When disabled, a block is grayed out in the flow graph
and will be ignored by the flow graph validator and by the source code generator. In
addition, blocks may be cut, copied, and pasted within flow graphs and into other
flow graphs.

 Hierarchical Blocks - GRC can create hierarchical blocks out of the built-in blocks. *See
the section on hierarchical blocks.
Requirements
GRC Requirements

Most (if not all) of these requirements can be found in the package manager of you linux
distribution.

 [Python 2.5 (or above) http://www.python.org/download/]

 [Python-LXML 2.0 (or above) http://codespeak.net/lxml/installation.html]

 [Cheetah Template Engine 2.0 (or

above) http://www.cheetahtemplate.org/download.html]

 [Python-GTK 2.10 (or above) http://www.pygtk.org/downloads.html]

GNU Radio Requirements

GRC is bundled with the current gnuradio trunk and will be included in the 3.2 release. I
recommend configuring your GNU Radio installation with wx-python, usrp, and audio
support. However, any configuration will work (see note). Follow the build-guide

Note: GRC will let you generate flow graphs with components that are not included in your
local install. For example, you can generate a flow graph with a usrp source, but the code will
error when executed unless GNU Radio is configured with usrp support.

Installation
Installing GRC

GRC is bundled with gnuradio, so following the installation guide should be enough to install
GRC. However, GRC will not be installed if you were missing any of the required
components. Install any missing components and re-run configure/install:

cmake ..
make
sudo make install

GRC should appear in the list of configured components; if not, read the configure verbose
for errors.
Installing Documentation

To view the blocks' documentation from inside GRC, install doxygen and configure gnuradio
with doxygen support.
Installing Icons, Mime Type, and Menu Items

If you have an operating system that supports the freedesktop.org standards (Gnome, KDE,
XFCE), then you may install the icons, mime type, and menu items bundled with GRC. After
installing GRC, run the following command:

cd /libexec/gnuradio/
sudo ./grc_setup_freedesktop install

Execution
GRC installs several executable python files into your system's path.
Executing the Flow Graph Editor

Open a terminal and enter the following:

gnuradio-companion

Usage Tips
 Add a block: double click on a block in the block selection window.

 Connect blocks: click on the port of one block, then click on the port of another block.

 Remove a connection: click on the connection, press delete, or drag the connection to
remove.

 Edit block parameters: double click on a block in the flow graph.

 Select a block, hit up/down for quick type change.

 For more short cuts, see the hot keys in the menu.

 Flow graphs that are completely simulation (without audio or usrp blocks) will
consume 100% CPU when executed, and the GUI elements will be unresponsive.
These flow graphs must include a Misc->Throttle block to throttle the rate of the
streaming data.

Variables
Variables map symbolic names to values. In GRC, a variable can define a global constant or,
a variable can be used in conjunction with a GUI to control a running flow graph.
Variable Block

The variable block is the most basic way to use a variable in GRC. The ID parameter of the
variable block is the "symbolic name". The symbolic name must be alpha-numeric
(underscores allowed) and begin with a letter. To use the variable, simply enter the symbolic
name into a parameter of another block.
Variable Controls

Certain blocks have callback methods that allow their parameters to be changed while
executing flow graph. Variable controls in GRC use variables in combination with callback
methods to modify these parameters. If a parameter has a callback method, the parameter will
be underlined in the block-properties dialog. The variable slider, variable text box, and the
variable chooser block provide graphical widgets such as sliders, text boxes, radio buttons,
and drop downs as variable controls. In addition, the variable sink block takes samples from a
gnuradio stream and writes the samples to a variable.
String Evaluation

String parameters have a two-phase evaluation. First, GRC evaluates the parameter as-is. If
the parameter does not evaluate to a string data type or the evaluation fails, then it is
understood that the parameter had implied quotation. In this case, GRC will evaluate the
parameter again with quotation marks; which will return a string with the exact code that was
typed into the parameter window.

To use a variable inside a string simply type the name of the variable into the
parameter: my_var. If the variable is not a string, cast the variable with python's str
function: str(my_var). Standard python string functionality applies: "My Var = " +
str(my_var).

 Note: String parameter types also include the file open and file save types.

Filter Design
Many blocks in gnuradio that take an array of complex or real taps as a parameter. GNU
Radio provides a package to generate all kinds of filter and window taps. See the firdes
package from the gnuradio documentation.
Firdes Taps Generators

 low_pass(gain, samp_rate, cutoff_freq, width, [window], [beta])

 high_pass(gain, samp_rate, cutoff_freq, width, [window], [beta])

 band_pass(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width, [window],

[beta])
  complex_band_pass(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width,
[window], [beta])

 band_reject(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width, [window],

[beta])

 gaussian(gain, spb, bt, int ntaps)

 hilbert(int ntaps, window, beta)

 root_raised_cosine(gain, samp_rate, symbol_rate, alpha, int ntaps)

 window(window, int ntaps, beta)

Firdes Window Types

 WIN_HAMMING

 WIN_HANN

 WIN_BLACKMAN

 WIN_RECTANGULAR

 WIN_KAISER

Firdes Notes

For the pass band functions, window defaults to the Hamming window. The beta parameter
defaults to 6.76, and only applies to the Kaiser window.
Firdes Usage Example

Create a new "import" block, and enter the following for the import parameter:

from gnuradio.filter import firdes

Note: Most blocks with a taps parameter automatically import the firdes module. You only
need to use the import block when firdes will not evaluate.

Enter the following into the taps parameter of a filter block:

firdes.low_pass(1.0, samp_rate, 1000, 100, firdes.WIN_HAMMING)

Use Taps from a File

Suppose that you have an array of filter taps stored in a file that you would like to use inside
GRC:

Create a new "import" block, and enter the following for the import parameter:

import numpy

Enter the following into the taps parameter of a filter block:

numpy.fromfile('taps file path', numpy.complex64).tolist()

This will read an entire binary file and parse every 64 bytes into a complex number. Use
numpy.float32 for real taps. See the numpy.fromfile help for more advanced usage:

Help on built-in function fromfile in numpy:

numpy.fromfile = fromfile(...)
fromfile(file=, dtype=float, count=-1, sep=_) -> array.

Required arguments:
file -- open file object or string containing file name.

Keyword arguments:
dtype -- type and order of the returned array (default float)
count -- number of items to input (default all)
sep -- separater between items if file is a text file (default "")

Return an array of the given data type from a text or binary file. The
'file' argument can be an open file or a string with the name of a file to
read from. If 'count' == -1 the entire file is read, otherwise count is the
number of items of the given type to read in. If 'sep' is "" it means to
read binary data from the file using the specified dtype, otherwise it gives
the separator between elements in a text file. The 'dtype' value is also
used to determine the size and order of the items in binary files.

Grid Positioning
GRC offers several graphical sinks and graphical controls for creating wx-gui flow graphs.
(scope sink, fft sink, number sink, waterfall sink, constellation sink, slider control, and
chooser control) Each of these graphical elements have a grid position parameter for precise
positioning.

A grid position parameter is a list of 4 integers of the form (row, column, row span, column
span). The row and column specify the position of the upper-left corner of the graphical
element. The smallest position, the (0, 0) position, specifies the upper-left corner of the grid.

If left blank, the grid parameter specifies that the graphical element will be automatically
stacked into a vertical sizer. The vertical sizer is positioned directly above the grid sizer. If
you do not want any elements to be added to the vertical sizer, leave no grid parameters
blank.

The row and column span specify the stretch, or the number of rows and columns that the
graphical element can occupy. The row span specifies the number of rows down from the row
positon, and the column span specifies the number of columns right of the column position.
Therefore, the span must be at least (1, 1) to occupy the minimum of 1 grid cell.
Example

The user wishes to place a slider, centered directly above a graphical sink. The slider will be
positioned at the 2nd column of the top row and with a column span of 2. The sink will be
positioned on the 2nd row, and with a row span of 2 and a column span of 4. Notice the grid
parameters below, and the resulting gui layout:

The Elements:

' Slider Control: (0, 1, 1, 2)'

' Graphical Sink: (1, 0, 2, 4)

The Resulting GUI:

0,0 0,1 0,2 0,3

1,0 1,1 1,2 1,3

2,0 2,1 2,2 2,3

Hierarchical Blocks
GRC can create hierarchical blocks out of the built-in blocks. Hierarchical blocks can be
instantiated inside of other grc flow graphs. The python code generated from a hierarchical
block can itself be used in non-GRC flow graphs. Four important blocks are used in the
creation of a hierarchical block: The options block, parameter blocks, and the pad source and
pad sink.
The Options Block

In order to make a hierarchical block, the parameters in the options block must be set
properly. The id of the options block sets the module name, and must be unique among the
entire library of blocks (built-in and custom). The title parameter sets the display name for the
block. The generate options must be set to "Hier Block". The category parameter sets the
category for the new block. This category can be an existing category in the block selection
window or a new category. Categories may be nested by specifying a name with slashes, ex:
Custom/Filters. To put blocks into the root category, specify a single slash "/" (a blank
category will hide your block).
Parameter Blocks

Parameter blocks specify variables in your hierarchical block that should be configurable in
the top level block. Parameter blocks work much like variable blocks with a few exceptions:
Parameters blocks cannot depend on variable blocks or other parameter blocks. Parameter
blocks have a label parameter for display purposes. Parameter blocks take the place of a
variable block, do not try to create a variable block with the same id as your parameter block.
Pad Source and Sink Blocks

The pad source and sink blocks create inputs and outputs for the hierarchical block. The pad
blocks have configurable data types, vector lengths, and number of ports. A flow graph can
have at most, one pad source, and one pad sink. A hierarchical block may have one pad sink
and no pad source or no pad sink and one pad source, but it must have at least one pad block.
Creating and Instantiating

 Start with a blank slate and create a new (empty) flow graph.

 Setup the options block as described above, with the id, title, generate options, and
category.

 Add parameter blocks for all variables you wish to configure/control outside of the
block.

 Create at most one pad source and one pad sink to match the IO type and connect
them.

 When finished, click the generate button, and close/reopen GRC.

 The hierarchical block will appear in the block selection window.

 Add the hierarchical block to a flow graph as your would any other block.

Notes

 After making changes to your hierarchical block, make sure to regenerate, and reopen
GRC before usage.

 The ID parameter of the block must be unique. If two blocks share the same ID, the
last one to be generated will overwrite the other.
  Custom hierarchical blocks may instantiate other custom hierarchical blocks. Just
don't have a block instantiate itself!

Adding Custom Blocks

Every block in GRC corresponds to an XML file that describes the block's parameters, inputs,
outputs, and other attributes. Adding a custom block into GRC is simply a matter of creating
one of these XML block definition files. A few caveats:

 The block should be accessible from the python path. Meaning that the block can be
accessed via an import statement.
 The block follows the block diagram model: it has parameters, inputs, and outputs. If
the block requires some kind of listening thread, or special callback methods to move
the data (as in the blks2 packet stuff), it cannot be used in GRC (unless this "special"
functionality can be encapsulated into a block that is block-diagram-safe).
 If GRC is missing a block definition for a block that is currently in the trunk, or one of
the block definitions is missing functionality, please mail the list. The block definitions
in the GRC trunk must stay in sync with the actual GNU Radio blocks.

Creating the XML Block Definition

The best way to learn how to create the xml file is to learn by example. See the block
definitions (source:grc/blocks) packaged with GRC, and read through a few files. Essentially,
all block definitions are structured as follows:

My Block Name
my_package_my_block_ff
Filters
from gnuradio import my_package
my_package.my_block_ff($param1, $param2)
set_param1($param1)

Parameter 1
param1
real

Parameter 2
param2
1
int

in
float
part

out
float

out
float
  The example above will make a block with 2 parameters, 1 input, and 2 outputs.
 The ordering of the tags is important, if tags are not ordered properly, the block will
fail validation. See block.dtd for specifics.
 The name tags dictate the label text for the block, parameters, and ports.
 The key tags are unique identifiers, they may not contain spaces. The block key must
be globally unique among all blocks in GRC. The parameter keys must be unique only
within the block.
 The category tag is a unix-style path that represents the location of the block inside
the block selection window. The path can be a new category (Custom), or represent a
sub-category (Filters/Custom). To put a block into the root category, just use a single
slash (/) for the root path.
 The import tag (there can be multiple) must be a valid python import statement to
the module containing your block.
 The make tag contains the code necessary to construct your block. This code is
essentially a cheetah template nested inside an xml tag. Upon code generation, the
template performs a text substitution on the "$" parameters. For more advanced
capabilities, see the cheetah template documentation.
 The callback tag registers a set-method from your custom block. Once the set-method
is registered, the set-method can be called at runtime when a variable is changed.
There can be any number of callback tags, one for each set-method of your block. Or
no callback tags if this is not applicable.
 For the param tags, the commonly used values for the type tags are: complex, real,
int, complex_vector, real_vector, int_vector, string, and raw. The raw type allows any
value to be used without performing type checking. The real type should be used for
single and double precision floating point numbers. The int type should be used for
longs, ints, shorts, and chars.
 The hide tag controls how the parameter is displayed in GRC. It's either none, part
(show in the prop dialog, not in the block on the canvas) or all.
 The sink tag represents an input port, and the source tag represents an output port.
The allowed values for the type tags are: complex, float, int, short, and byte. For ports
with a vector length, specify a vlen tag after the type tag.
 In case you want to create a block definition as done for the FECAPI, the key tag has
to start with variable_ in order to work correctly in GRC.

Some Example Definitions

 Simple Example: "Complex to Real" source:[1]

 Multiple Callbacks: "Costas Loop" source:[2]
 Vlen Example: "Throttle" source:[3]
 Advanced Make: "FFT" source:[4]
Installing the XML Block Definition

There are many methods to tell grc about your new xml file. Choose one of the following
methods...
Method 1: Default Hier Block Location

Create the _.xml_ file inside/.grc_gnuradio/* where is your home directory. If the directory does not
exist, create it: mkdir ~/.grc_gnuradio/
Method 2: Configuration File

Create or edit ~/.gnuradio/config.conf and add the following lines:

[grc]
local_blocks_path=/path/to/my/blocks

The local_blocks_path can contain multiple paths separated by colons:

local_blocks_path=/path/to/blocks1:/path/to/blocks2
Method 3: Environment Variable

Set the GRC_BLOCKS_PATH environment variable to a path that contains your custom
block wrapper. The GRC_BLOCKS_PATH can contain multiple paths separated by colons:
GRC_BLOCKS_PATH=/path/to/blocks1:/path/to/blocks2

Special Thanks
 CER Technology Fellowship: initial funding
 A. Brinton Cooper: starting the project
 Patrick Mulligan: starting the project
 William R. Kenan Jr. Fund: usrp & computers
 Patrick Strasser: the GRC icon

Screen Shots
Screen Shots

Feel free to submit your own screen shots or flow graphs.

Retrieved from
"https://wiki.gnuradio.org/index.php?title=GNURadioCompanion&oldid=4311"

 This page was last modified on 26 June 2018, at 19:59.

  Content is available under Creative Commons Attribution-ShareAlike unless otherwise
noted.

GNU Radio Companion

GRC is bundled with the gnuradio development trunk and gnuradio 3.2 release. If you wish to use
grc, follow the instructions at the GNU Radio wiki.
Please use the grc that is bundled with the current gnuradio master or the gnuradio 3.2 release. It
has a years worth of work and improvements compared to the last versioned release of grc (0.70). In
addition, the grc bundled with gnuradio is guaranteed to evolve with gnuradio; whereas the older non-
bundled grc will stagnate and cease to be compatible with newer gnuradio releases.

Get it now!
You can get the latest gnuradio and grc with this command. Make sure to follow the Build Guide.

git clone http://gnuradio.org/git/gnuradio.git

Examples
Official grc examples are in gnuradio-examples. Some of the scripts that come with gnuradio are
generated from grc flow graphs. Just run find in your gnuradio checkout to get a list of all grc files:

find -name "*.grc" -print

Old Releases
 I do not recommend using any of the old releases, but if you really need them, they are here. Please
ignore any readme files or notes. They are wayyy out of date.
All grc subversion history prior to its gnuradio integration can be found here. You will have to wind
back many revisions because the directory was removed.

Relevant Documents
Presentation for October 2009 GNU Radio Hackfest
This was my presentation for the October 2009 Hackfest. The presentation summarizes recently-
added features and possible future features.
 Download Here
Poster for Tech-Fellows Demonstration
During my sophomore year at Johns Hopkins (2006-2007), I worked with Dr. Cooper, and Patrick
Mulligan (MSE student) to create a graphical interface for gnuradio. We started with grant money from
the Technology Fellowship Grants Program.
The goal of the Tech-Fellows Grant is to use technology (aka a computer) to aid in the learning
process. In this case, Dr. Cooper used grc is his digital communication class the semester after the
presentation. I know of at least several other universities that use grc as a learning tool for digital
communication. So, I am declaring this one a success.
 Download Here

Screen Shots
 Last edited:

HowToUse
From GNU Radio

Contents
[hide]

 1How do I use GNU Radio?

 1.1Using the included tools and utility programs
 1.2Graphical signal processing development: The GNU Radio Companion
(GRC)
 1.3Using Python to write powerful signal processing and radio applications
 1.4The C++ domain: Extending GNU Radio
 1.5Figuring out how stuff is done: read the examples

How do I use GNU Radio?

Even after successfully installing GNU Radio, it might not be clear what exactly GNU Radio
is capable of and what it can be used for. This article will give an overview of what you can
do with GNU Radio and how to do it.

Using the included tools and utility programs

GNU Radio comes with a large variety of tools and programs which can be used out of the
box. If you installed from source, you can find most of the source files in gr-
utils/src/python and gr-uhd/apps. If you're using Linux and installed GNU Radio from
source (e.g. by using the build-gnuradio script), these programs get installed
into /usr/local/bin or /usr/bin.

The most commonly used tools include

 uhd_fft - A very simple spectrum analyzer tool which uses a connected UHD device
(i.e., a USRP) to display the spectrum at a given frequency. This can be also used for a
waterfall plot or as an oscilloscope.
 uhd_rx_cfile - Record an I/Q sample stream using a connected UHD device. Samples
are written to a file and can be analysed off-line at a later time, using either GNU
Radio or other tools such as Octave or Matlab.
 uhd_rx_nogui - Receive and listen to incoming signals on your audio device. This tool
can demodulate AM and FM signals.
 uhd_siggen_gui - Simple signal generator, can create the most common signals (sine,
sweep, square, noise).
 gr_plot* - This is an entire suite of apps which can display pre-recorded samples saved
to a file. You can plot the spectra, PSD and time-domain representations of these
signals.

If you're using Linux, you can call all these apps from the command line. All apps include a
"-h" switch which will display a help screen. With the uhd_fft tool, this would look like this:

$ uhd_fft --help
linux; GNU C++ version 4.5.2; Boost_104200; UHD_003.003.000-d5d448e

Usage: uhd_fft.py [options]

Options:
-h, --help show this help message and exit
-a ADDRESS, --address=ADDRESS
Address of UHD device, [default=addr=192.168.10.2]
-A ANTENNA, --antenna=ANTENNA
select Rx Antenna where appropriate
-s SAMP_RATE, --samp-rate=SAMP_RATE
set sample rate (bandwidth) [default=1000000.0]
-f FREQ, --freq=FREQ set frequency to FREQ
-g GAIN, --gain=GAIN set gain in dB (default is midpoint)
-W, --waterfall Enable waterfall display
-S, --oscilloscope Enable oscilloscope display
--avg-alpha=AVG_ALPHA
Set fftsink averaging factor, default=[0.1]
--ref-scale=REF_SCALE
Set dBFS=0dB input value, default=[1.0]
 --fft-size=FFT_SIZE Set number of FFT bins [default=1024]

This is what it looks when used with a USRP1 and a DBSRx daughterboard observing a GSM
downlink:

$ uhd_fft.py -a type=usrp1 -f 935M -s 2M

Graphical signal processing development: The GNU Radio

Companion (GRC)
Digital signal processing (DSP) is where GNU Radio shines; this is what it was originally
made for. GRC is a Simulink-like graphical tool to design signal processing flow graphs. If
you're comfortable dealing with FIR filters, digital modulators and other DSP concepts, using
GRC should be simple and straightforward for you.

On Linux systems, GRC is invoked by calling the gnuradio-companion command. If your

installation was fine, GRC will pop up in its own window. On the right hand side, you can
find all the available blocks (good news: adding new blocks is not terribly difficult!), which
can be dragged into the main window and connected by clicking the edges. GRC has it's own
wiki page.

Here's an example of a narrowband FM receiver, which filters a signal, FM demodulates it

and passes it to the sound card (this and other examples can be found on www.oz9aec.net.

Using Python to write powerful signal processing and radio

applications
Sometimes GRC cannot provide all the flexibility required for your application. Anything that
can be clicked together in GRC can also be written in Python, and while it is more of an effort
to code everything yourself, it also provides you with the entire power and functionality of
Python and its libraries, such as SciPy or NumPy for Python-centric processing of your
signals or your favorite widget library to create any GUI you wish.

Have a look at the Python apps tutorial to find out how to go ahead here. The tutorial also
includes an introduction to the main GNU Radio concepts, such as flow graphs.
The C++ domain: Extending GNU Radio
GNU Radio is extremely powerful and includes many kinds of signal processing blocks.
However, if you're developing something particular, chances are high that sooner or later
you'll be running into some component which is lacking; be it a specific channel code, a
segmentation algorithm or whatever. In this case, you will want to write your own blocks to
add them into GNU Radio. This is usually done in C++, in order to keep GNU Radio as fast
as it is. If this is what you need, check out the tutorial on how to write a new block.

Figuring out how stuff is done: read the examples

Starting to develop stuff using GNU Radio may seem daunting at first. GNU Radio is a
powerful but scary beast, but has a steep learning curve.
The best way to start to understand how GNU Radio works is to look at examples. Under
Linux, they usually get installed /usr/local/share/gnuradio/examples. There are literally
several hundred example files to discover, sorted by topic.

In the source tree, the examples are in the sub-directory they belong to. All examples to do
with digital modulation are in 'gr-digital/examples', all examples concerning filters (that
includes resampling etc.) are in 'gr-filter/examples' etc. GNU Radio provides examples for
Python, GNU Radio companion and C++.

Retrieved from "https://wiki.gnuradio.org/index.php?title=HowToUse&oldid=800"

 This page was last modified on 30 June 2017, at 21:35.

 Content is available under Creative Commons Attribution-ShareAlike unless otherwise
noted.

OtherCode
From GNU Radio

Contents
[hide]

 1GNU Radio code by 3rd parties

 1.1BBN 802.11
 1.2MRFM
 1.3GNU Radio Companion Files
 1.4GR Bluetooth stack
 1.5Jitter (GNU Ionospheric Tomography Receiver)
 1.6gr-baz
GNU Radio code by 3rd parties
Remember to also check out CGRAN!

{{>toc}}

BBN 802.11
BBN has written 802.11 code under funding from DARPA.

After GNU Radio is installed, build it using bootstrap/configure/make install to the same
prefix.

This has been tested on NetBSD, and reported to work on Linux.

The following has been reported working

 ? Mb/s transmit and receive without Barker code

 1 Mb/s receive with the Barker code

Those experimenting with the code should be familiar with both GNU Radio and 802.11; this
is not a good area for beginners.

MRFM
The UW Quantum System Engineering Laboratory has written code for Magnetic Resonance
Force Microscopy (MRFM) under funding from the Army Research Office. The code, with
explanation and instructions, is available here.

Some of the code might be useful to other GNU Radio users.

 On the FPGA side, there is a 2-stage biquad filter with 24-bit (not 16-bit) data path and
filter coefficients.
 There is also an input multiplexer and adder.
 On the host side, there is code (in Python with Scipy) that transforms transfer
functions, expressed as ratios of polynomials with floating point coefficients, into
cascaded biquad stages with scaled integer coefficients.
 The host side code acts as a server, so it can communicate with the MRFM experiment
software over TCP/IP sockets.
 There is a sample client, also in Python with Scipy.

GNU Radio Companion Files

http://www.oz9aec.net/index.php/gnu-radio/grc-examples
GR Bluetooth stack
http://gr-bluetooth.sourceforge.net/

Jitter (GNU Ionospheric Tomography Receiver)

http://www.sgo.fi/~j/jitter/web/

gr-baz
http://wiki.spench.net/wiki/Gr-baz

RTL2832 drivers, eye diagrams and other stuff

Retrieved from "https://wiki.gnuradio.org/index.php?title=OtherCode&oldid=136"

 This page was last modified on 8 March 2017, at 01:36.

 Content is available under Creative Commons Attribution-ShareAlike unless otherwise
noted.