A Dictionary of the GNU Radio blocks

A dictionary of the GNU Radio blocks. This article takes a tour around the most frequently used blocks, explaining the syntax and how to use them.

1  Introduction

When we use Matlab to do simulation, it is believed that in order to write the code cleanly and efficiently, we need to memorize a number of Matlab built-in functions and tool boxes well and use them skillfully. The same applies to GNU Radio. About 100 frequently used blocks come with GNU Radio. For a certain number of applications, we can complete the designing using these existing blocks, programming only on the Python level, without the need to write our own blocks. So in this article, we will take a tour around the GNU Radio blocks. A good way to go through the blocks is to study the two GNU Radio documentations generated by Doxygen. They will be generated when you install gnuradio-core and usrp packages, assuming you have Doxygen installed. They are located at:
/usr/local/share/doc/gnuradio-core-x.xcvs/html/index.html
/usr/local/share/doc/usrp-x.xcvs/html/index.html
You may like to bookmark them in your web browser. The first one is also available on-line. A block is actually a class implemented in C++. For example, in the FM receiver example, we use the block gr.quadrature_demod_cf. This block corresponds to the class gr_quadrature_demod_cf implemented in C++. The SWIG creates its interface to Python. The SWIG does some magic work so that from Python''s point of view, the block becomes a class called quadrature_demod_cf defined in the module gr, so that we can access to the block using gr.quadrature_demod_cf in Python. When you look at the Doxygen documentations, the prefix such as gr, qa, usrp corresponds to the module name in Python and the part after the prefix is the real name of the block in that module, such as quadrature_demod_cf, fir_filter_fff. So if we talk about a block named `A_B_C_...'', we will use it as `A.B_C_...'' in Python.

2  Signal Sources

2.1  Sinusoidal and constant sources

Block: gr.sig_source_X. Usage:
gr.sig_source_c [f, i, s]   ( double sampling_freq,
                              gr_waveform_t waveform,
                              double frequency,
                              double amplitude,
                              gr_complex [float, integer, short] offset )
Notes: The suffix X indicates the data type of the signal source. It can be c (complex), f (float), i (4 byte integer) or s (2 byte short integer). The offset argument is the same type as the signal. The waveform argument indicates the type of the wave form. gr_waveform_t is an enumeration type defined in gr_sig_source_waveform.h. Its value can be:
    gr.GR_CONST_WAVE
    gr.GR_COS_WAVE
    gr.GR_SIN_WAVE
When you use gr.GR_CONST_WAVE, the output will be a constant voltage, which is the amplitude plus the offset.

2.2  Noise sources

Block: gr.noise_source_X. Usage:
gr.noise_source_c [f, i, s] ( gr_noise_type_t type,
                              float amplitude,
                              long seed )
Notes: The suffix X indicates the data type of the signal source. It can be c (complex), f (float), i (4 byte integer) or s (2 byte short integer). The type argument indicates the type of the noise. gr_noise_type_t is an enumeration type defined in gr_noise_type.h. Its value can be:
    GR_UNIFORM
    GR_GAUSSIAN
    GR_LAPLACIAN
    GR_IMPULSE
Choosing GR_UNIFORM generates uniformly distributed signal between [-amplitude, amplitude]. GR_GAUSSIAN gives us normally distributed deviate with zero mean and variance amplitude2. Similarly, GR_LAPLACIAN and GR_IMPLUSE represent a Laplacian distribution and a impulse distribution respectively. All these noise source blocks are based on the pseudo random number generator block gr.random. You may take a look at /gnuradio-core/src/lib/general/gr_random.h(cc) to see how to generate a random number following various distributions.

2.3  Null sources

Block: gr.null_source. Usage:
gr.null_source ( size_t  sizeof_stream_item )
Notes: gr.null_source produces constant zeros. The argument sizeof_stream_item specifies the data type of the zero stream, such as gr_complex, float, integer and so on.

2.4  Vector sources

Block: gr.vector_source_X. Usage:
gr.vector_source_c [f, i, s, b] ( const std::vector< gr_complex > & data,
                                  bool    repeat = false )

(gr_complex can be replaced by float, integer, short, unsigned char)
Notes: The suffix X indicates the data type of the signal source. It can be c (complex), f (float), i (4 byte integer), s (2 byte short integer), or b (1 byte unsigned char). These sources get their data from a vector. The argument repeat decides whether the data in the vector is sent repeatedly. As an example, we can use the block in this way in Python:
        src_data = (-3, 4, -5.5, 2, 3)
        src = gr.vector_source_f (src_data)

2.5  File sources

Block: gr.file_source Usage:
gr.file_source ( size_t