How does one convert a block diagram concept of a signal processing circuit to DSP software for an SDR? DSP software is key to working effectively with SDRs at the practical level to which amateurs are accustomed with traditional analog technology and the soldering iron.
Introduction to GNU Radio
The ability to create and work with software for SDR projects is a new skill for many hams. Professional programmers have many options to pursue. For hams without a programming background, now available software packages, are a gateway for ordinary hams to build custom DSP software. The software packages feature graphically based interfaces and offer useful DSP functions included in DSP libraries. Software authoring is vastly simplified. This section introduces the combination of GNU Radio and GRC package as a powerful, ‘ham friendly’, open source DSP library and application environment for SDR projects. The GNU Radio open source DSP software library was conceived as a development tool for advanced level educational programs, and industrial product development labs. With little effort hobbyists can use these tools as well. GNU Radio can be used as a simulation tool to study DSP without being connected to an SDR and also used to develop practical and operationally satisfying DSP software for SDR transmitters, receivers, and transceivers as well as test equipment. See Publications and Presentations in this website for additional background material.
The user option of the graphical interface GNU Radio Companion (GRC), an integral part of GNU Radio, makes DSP authoring accessible for all levels of users. While the foundational GNU Radio DSP library is accessed with character-based command line entries, GRC is a fully functional graphical overlay to the GNU Radio DSP library. The graphical user interface GRC emulates the command line entries and represents each DSP function as a graphical icon. (For the sake of completeness not all of the programming is graphical. A very few of the GRC DSP parameters are expressed as simple Python code commands. These python commands are covered later in Learning Resources: DSP Competency and GNU Radio)
The visual arrangement of DSP icons and digital data links on screen is termed a flow graph. When executed, “deep deep down”, the GRC flow graph is compiled to a Python code file, which itself is a wrapper for C++ executable DSP code. This artful layered construction, like a set of nesting dolls, provides both a high level, user friendly, graphical interface for DSP authoring with the speed and efficiency of lower level code for DSP process speed and efficiency. More information from the developers about the construction of this DSP library environment is available at https://wiki.gnuradio.org/index.php/What_is_GNU_Radio%3F
General Flow Graph Structure: ‘blocks’, ‘logical processing’, ‘parameters’, and ‘DSP data links’
GRC, the easy to use graphical interface makes this DSP library particularly appealing to many ham users. Reduced to the basics, the step by step design of a functional DSP begins with envisioning a block diagram pattern of a traditional analog signal processing circuit. Once the general signal processing pattern is conceived, select the desired DSP function(s) or ‘blocks’ from the DSP library, (filter, mixer, oscillator, amplifier, etc.), arrange the DSP function(s) as graphical blocks in the work screen to follow a ‘logical processing’ pattern, add ‘parameters’ into each block, connect the blocks with an appropriate ‘DSP data type‘, and execute the program. The details for constructing a DSP flow graph are covered later in the Success with GNU Radio: tool competency section and in the on-line tutorials included in the Learning Resources: DSP Competency and GNU Radio segment. The process is simple overall.
The ‘Block’ level:
Let’s examine the GRC work environment and flow graph composition at the highest level, the ‘block’ level. The GRC work environment consists of 4 parts: the work area, the control bar, the library, and the console.
Figure 1 illustrates the GRC user graphic user interface (GUI). The DSP is authored in the work area in the center of the GUI screen. The GRC control bar is located across the top of the work area. The GNU Radio DSP library runs along the right margin. The operating console is located at the very bottom of the work environment and becomes active when a DSP is executed.
The ‘Logical Processing’ level:
Figure 1 above, depicts in the work area six DSP blocks which, in aggregate, constitute a DSP flow graph. The flow graph is arranged with the signal source on the left edge of the work area with the remainder of the flow graph blocks continuing to the right in the ‘logical’ order that the data should flow to output tot the speakers and to FFT display. The flow graph implements, in DSP, a 1 kHz audio tone output to both an audio sink (computer speaker) and to an FFT panadapter display (on screen) once the flow graph has been executed.
Note the signal spike is accurately centered at 1 kHz on the FFT display and the 1 kHz tone would be heard via the computer sound card.
The ‘parameter’ level:
Continuing to the’ parameter’ level, each DSP library item is displayed as a rectangular shaped ‘block’ with input / output ports. Each block must be ‘opened’ with a right mouse click to gain access to the parameter fields that define that DSP function. Each parameter has a field where the values are either added or selected from a menu.
Figure 3 displays the parameter screen for a low pass filter DSP block. Note how the digital data type (FIR Type), sample rate, filter bandwidth and filter shape, and other parameters can be selected or specified. Some parameter values are intuitive, direct carryovers from analog design. For example, the bandwidth and shape factor parameters for a DSP filter block are specified in the same way an analog filter is specified, in Hz.
The ‘DSP data type’ level:
Other parameter values are not as intuitive and refer to parameters unique to DSP. Examples of these parameters are the DSP Sample Rate and FIR Type choices. More detail about the most commonly used DSP blocks and appropriate parameter choices are explained in greater detail: The Rest of the Story: Basic DSP Theory applied to a flow graph
Figure 4 depicts a more complex flow graph of an SDR broadcast FM receiver. This flow graph uses a RTL-SDR as the receiver Source. Other SDR receiver hardware can be substituted easily. Learn more later in GNU Radio, Radio Hardware, and UHD. The blocks are arranged in a ‘logical’ order from the receiver (Source) on the left to the filter, WBFM demodulator, to another filter, audio volume control and speaker output. The RTL-SDR is represented by the RTL-SDR Source block on the left. The Audio Sink on the right outputs the audio sound. The WX GUI FFT Sink in the center outputs a panadapter display. The chain of DSP blocks in the center of the work screen perform the filtering and signal demodulation functions for this radio. Compare this flow graph with a block diagram for any simple analog FM receiver to appreciate the fundamental similarity. Note some of the ‘blocks’ have blue colored terminals and some have orange colored terminals. The terminal colors reflect the ‘DSP data type’ necessary to interconnect the DSP blocks. The receiver outputs floating point data (blue terminal) to the WBFM demodulator which converts the floating point data to complex I and Q data output (orange terminal). The complex ‘DSP data type’ connections continue through the remaining DSP process to the ultimate speaker output.
Figure 5 illustrates the operating receiver GUI which appears when the flow graph is executed. Shown are the radio tuning controls for frequency and audio output, and the FFT panadapter display of an FM broadcast station.
Step by Step to Flow Graph Success
How does one begin DSP flow graph using the GNU Radio GRC graphical interface? Four steps are required to construct any flow graph: the ‘block’ step, the ‘parameter’ step, the ‘logical interconnection’ step, and the ‘DSP’ step. Each step is explained below.
Step 1, the Blocks: The first step in flow graph construction is the ‘block’ step. Arrange the appropriate DSP blocks from the GRC library to form a diagram of the desired circuit in the work area. See Figure 1 of the example flow graph and where it is place in the work area.
Step 2, the Parameters: The second step is the ‘parameter’ step. To perform the desired DSP function, each DSP block requires user specified parameters. In the parameter step, right click each block, select Properties, and enter the parameter values in the available fields. Each block in the flow graph diagram is opened in turn and the desired parameters are entered in each block. Typical parameters are familiar values such as gain, frequency, bandwidth, etc. and some less familiar values such as Sample Rate and Output Type. The Sample Rate and Output Type parameter values are unique to DSP to be discussed below. These DSP parameters are set by default in many flow graphs and automatically propagated into every DSP block. For one to
meaningfully change these default parameters, a basic understanding of DSP theory is required. (See Step 4, DSP Parameters.)
Step 3, the Logical Interconnections: The third step is the ‘logical interconnection’ step. Each DSP block must be connected to the other blocks by a data link arrow in a logical manner. The data links begin with the ‘input’ or Source location in the flow graph end with the ‘output’ or Sink in the flow graph.
Step 4, DSP Parameters: The fourth step is to enter DSP parameter values. It is in this fourth, and final step, that DSP issues enter the authoring a flow graph. Let’s begin with the special Variable block located in the left-hand corner of the work area. That block is automatically present whenever GRC is opened for programming. The Variable block is the location for the base line Sample Rate parameter for each block in the DSP. The default parameter is 32,000 samples per second (SPS). That default parameter is automatically propagated to the Sample Rate field in each DSP block in the flow graph work area. The default Sample Rate value is a good starting place for many DSP flow graphs and can be used as a default for many designs. Advanced DSP designs may require different sample rates and may require adjustments to the sample rate parameter in the DSP blocks.
Another default DSP parameter is the Output Type parameter for each DSP block. The default parameter is termed Complex or I and Q. This default parameter is useful for many, but
not all radio related DSPs. The flow graph example described below illustrates a flow graph where the default Output Type must be changed for the simple flow graph to function.
Executing the flow graph
In practice, the above outlined flow graph is created in the work area of the GRC. To operationalize the flow graph, inspect the tool bar above the work area. If the red ‘stop light’ icon is glowing, you have made a mistake in your flow graph. The program will not compile and execute. Look for error messages and review your work. When the green arrow is brightly visible, and the red button grayed out, Execute flow graph by left clicking on the green arrow. After the software compiles, the DSP will spring to life. The operational GUI appears on the screen with the control functions displayed as displayed on the right side of Figure 1.
Specific Flow Graph Example: Simple Audio Oscillator that outputs a tone
Step 1, the Blocks: Examine Figure 1. This figure is a screen capture of the audio oscillator example flow graph. The operating GUI is superimposed on the right side of the figure. The operating GUI only appears only after the Execute flow graph is selected from the tool bar.
The flow graph blocks are selected from the library off the right-hand edge depicted Figure 1 and placed in the work area. At a glance, the flow graph block diagram is constructed to look essentially the same as a traditional analog radio block diagram with the same circuits of this sort have been published in the ARRL Handbook for generations. A traditional circuit block diagram for a simple sine wave oscillator with audio output, would consist of series of blocks linked by lines; an oscillator block, a frequency control, an audio amplifier, an audio volume control, all connected one after the other, to an audio output block. In this audio oscillator example, the signal processing pattern is the same for the traditional analog and the GNU Radio digital implementation. With a DSP, the inter-connections between blocks are no longer signal links (wires in traditional circuits) but are digital data links. See Step 3, Logical Interconnections and The Rest of the Story: Basic DSP Theory applied to a flow graph
Step 2, the Parameters: Upon close examination most of the parameters for each DSP block are visible in Figure 1. Examine the parameters of each block, with a right click on the block, and select Properties. Right click the QT GUI Range control block with the ID audio_tone located at the top of the work space. This block is the control block for the oscillator frequency or audio tone. Note the block ID, audio_tone, and the tone tuning range from 250 Hz to 4 kHz in 1 Hz steps. This block connects to and controls the Signal Source DSP block output frequency, audio oscillator tone in this example. The ID audio_tone comprises the software link between the control block and the Signal Source DSP block. The term audio_tone is entered into both the Signal Source frequency parameter field and the QT GUI Range ID field thereby connecting the two blocks with software. In the same manner, the audio volume control is linked via software to the audio amplifier. Select Properties in the QT GUI Range control block with the ID audio_amplitude. The multiplication values range from 0 to 10. These numbers are factors that tell the Multiply Const DSP block to multiply the digital data stream amplitude for audio volume control. The ID audio_amplitude, denotes the software link to the Multiply Const DSP block.
components. The diagram and component content reflect standard signal processing practice. Diagrams and That ID is entered in the constant parameter field in the Multiply Const DSP block. The two blocks are linked in the same way as the audio tone frequency is linked to the audio oscillator.
The Sample Rate value from the Variable block, 32k, is automatically propagated to the other DSP blocks but not to the two control blocks
Step 3, the Logical Interconnections: To complete the basic DSP flow graph, each block is logically interconnected to the others. Additional attention to details are important in this step. Not appreciated in the screen capture, is how the Multiply Const DSP block became configured to have only single input and single output ports. This block and many other blocks from the DSP library are pre-configured for multiple input and output ports. When placed in the GRC work area, pre-configured blocks from the library are re-configured for the desired number of ports to fit the flow graph. To reconfigure the number of ports, right click the block, select Properties and enter a value for the number of desired ports in the appropriate port parameter field. In this example, the number 1 was entered in the Input Port field of the Multiply Const DSP block. Select OK, the window closes, and the block appears on screen ready to use with a single input and single output port.
Once the block ports are configured, the DSP blocks must be linked with the data stream. To form these data stream links, left click on the output port of the Signal Source DSP block, followed by a left click on the input port of the Multiply Const DSP block. A data link arrow appears, and those two blocks are digitally connected. The output of the Multiply Const DSP
block connects in a similar manner to the input port of the Audio Sink DSP block. The flow graph is almost complete. The two control blocks have no visible data link arrows. They are automatically connected via the software ID parameters described above. Next, we consider the DSP parameter step.
Step 4, DSP parameters: The audio oscillator flow graph functions fine with the default Sample Rate parameter in conjunction with modern computer sound cards. No attention is needed to the Sample Rate parameter. The Output Type parameter is different and must be changed from the default setting for this flow graph to function. The Output Type parameter for each DSP block is displayed in a drop-down menu, found by selecting Properties for that DSP block. The Output Type is also visually displayed in the flow graph by the color of the input and output port tabs on the blocks. (This color code is a useful bug fix hint with advanced DSP programing and not central for this description. The change in color is only visible when viewing the screen capture or flow graph on a computer screen.) The desired Output Type for this flow graph is ‘Float’ or digital data using floating-point numbers. The Output Type parameter for each DSP block in this example must be the same, ‘Float’. Right click and select Properties for each DSP block in the flow graph navigate to the Output Type parameter and select ‘Float’ from the drop-down menu. The two control blocks don’t require any DSP parameters.
Once all steps are completed, the flow graph is ready to be executed. Upon execution, a new GUI appears on the screen with the controls displayed. That GUI screen is superimposed in the upper right-hand corner of the screen capture. Listen for the 250 Hz audio tone in the speaker. Adjust the audio volume and audio frequency with the GUI controls. You can also experiment with adjusting the sample rate in the Variable block, or parameter values in any block and
observe the effect these changes have on the operation of the flow graph. The GRC flow graph for this example is attached as File 1. The file can be executed in the GNU Radio application.
The Rest of the Story: Basic DSP Theory applied to a flow graph
To better understand this DSP flow graph example and to aid authoring more advanced DSP flowgraphs, basic information about the relationship of sample rate, data stream output type, and DSP is important.
Sampling is a foundational aspect of DSP. DSP comes into action after the A/D converter where an analog sinusoid becomes converted to a digital data stream. The DSP acts to manipulate the series of data points, instantaneous digital pictures, a replica, of the A/D conversion of the sinusoid signal. The signal, as an ordinary signal, no longer exists in the DSP. Instead, what exists in the DSP is the sampled replica, the multiple digital pictures, of the original signal. The replicated signal exists as the digital data stream. The greater the number of samples, the more closely the replicated digital data corresponds to the original sinusoid signal prior to A/D conversion. The digital data stream, the series of instantaneous digital pictures of the signal, can be reconstructed, after digital processing, to generate familiar analog sound or radio signals with a D/A converter.
Connecting the sampling concept to a functioning flow graph, each DSP block in the flow graph must function with a compatible sample rate parameter. GRC automatically enters the default sample rate for each DSP block which is fine for many DSP processes. Advanced DSP techniques using GNU Radio and GRC call for a wide range of sample rate parameters beyond the default value. The sample rate parameters can also be individually adjusted for each DSP block in the flow graph. These sample rate changes are accomplished using Resampler DSP blocks. Sample rate adjustments within a single flow graph are termed “multi-rate” sampling and a common practice with advanced DSPs such as those for SDR applications.
Another foundational concept regarding DSP is to understand that the sole purpose of each DSP block is to mathematically manipulate the digital data stream. Fortunately, with GNU Radio and the GRC graphical approach to programming, the user is not required to understand the underlying mathematics. The DSP functions in GNU Radio DSP library are preloaded with the necessary mathematical algorithms to perform their intended DSP function. The data stream math algorithms are unique in each DSP block. The mathematical operation can be single purpose as the Multiply Constant DSP block which functions as an amplifier or attenuator by multiplication of the digital data stream amplitude. Other DSP blocks provide filtering or mixing functions and frequently combinations of these functions. All operations are performed mathematically based on algorithms programed by the developers into each DSP block. Not only is the data stream is manipulated in a mathematically determined manner, but the mathematical structure of the digital data stream has an impact on how a flow graph can function. I’ll explain.
Back to the flow graph: The Output Type DSP parameter reflects the structure of the digital data stream that communicates amongst the DSP blocks. The mathematically processed digital data stream Output Type can be customized as necessary for advanced DSP processes. As a practical matter, the default Output type digital data structure for most GNU Radio DSP blocks
are set by default to ‘Complex’ or I and Q data. The default setting, ‘Complex’, is the preferred data type for many, if not most, ordinary radio related DSP applications. Some DSP flow graphs, such as those employing Phasing techniques and the audio oscillator example in this case, require an Output Type, different from the default ‘Complex’. In addition, some SDR hardware digital data output types are derived from different math conversions and require a non-default data stream structure conversion in the flow graph as well. In other words, one type of digital data stream doesn’t fit all. The Output Type data stream parameter can be quite specific for the some SDR hardware and quite specific for some DSP process. Mastering the details of Output Type for your flow graph constructions will come with more in-depth understanding of DSP fundamentals.
For further information on sampling rate choices and Output Type digital data streams, review the information on the GNU Radio website.
Learning Resources: ‘DSP Competency’ and GNU Radio
This introduction to GNU Radio, GRC and flow graph construction presents DSP on a high-level, the block and parameter levels, consistent with GNU Radios high-level graphical environment. But that is only the beginning of a journey into the world of DSP. The DSP and SDR Fundamentals 8.1ff , SDR Receiver 12.3, and the GNU Radio 14.5 chapters of the 2018 ARRL Handbook contain much useful information about achieving DSP competency. That
information offers important background and context to more in-depth understanding of DSP to apply to GNU Radio although not all are specific to GNU Radio.
DSP competency is readily facilitated using GNU Radio as a tool for experiments and simulation. A great learning resources are the on-line educational resources specific to GNU Radio. Detailed examples of DSP applications and parameter selection, awkward and sometimes confusing in a text format, are much more easily understood via on-line video tutorials. The Ettus Corporation-sponsored series of DSP tutorials: http://files.ettus.com/tutorials/labs/Lab_1-5.pdf and the related video series: http://www.youtube.com/playlist?list=PL618122BD66C8B3C4 are highly recommended for this learning format.
For a more academic treatment of DSP consider both the DSP and SDR Fundamentals 8.1 chapter of the 2018 ARRL Handbook and the DSP texts by Richard Lyons. The Lyons texts provide a particularly ‘ham friendly’, intuitive, approach to understanding DSP. See: GNU Radio Reference Material
Installing GNU Radio
The very first step for a new user is to review the GNU Radio web portal for authoritative information: https://wiki.gnuradio.org/index.php/Main_Page The GNU Radio developers have published a rich source of detailed information to help the new user to get started using GNU Radio. From that portal page one can link to installation instructions, tutorials, latest news, and in-depth information about the software development process. Refer to it frequently, since the content changes with the ongoing software development.
To get started with GNU Radio, a particularly appealing option is to use the GNU Radio Live SDR Environment: https://wiki.gnuradio.org/index.php/GNU_Radio_Live_SDR_Environment The Live Environment allows the user to implement GNU Radio without installing GNU Radio on the computer hard drive. The latest versions of the Ubuntu operating system and GNU Radio software are downloaded from the Internet to a storage medium (e.g. DVD or USB memory stick) as an executable file. Upon executing from the medium, the Live Environment opens in a complete Ubuntu operating system with GNU Radio application pre-installed. GNU Radio and GRC can be immediately executed to run at essentially full capability.
To install GNU Radio directly to a computer hard drive, installation from the official Source, the “build-gnuradio script” approach is far and away the most dependable and highly recommended: https://wiki.gnuradio.org/index.php/InstallingGRFromSource Installing GNU Radio from Source with the build-gnuradio script automatically installs the most recent GNU Radio version, all add on’s, and the latest driver for compatible SDR hardware, the Universal Hardware Driver (UHD). The build-gnuradio script is a preferred method for initial installation and subsequent updates of GNU Radio and UHD as needed. Step by Step, “ham friendly” help with the installation process is also available at: http://www.w7fu.com/
Getting the most out of GNU Radio
Support for GNU Radio is available on-line via the ‘discuss-gnuradio’ message reflector: https://lists.gnu.org/mailman/listinfo/discuss-gnuradio Questions can be posted on the reflector and the GNU Radio developers respond via email. The reflector is very active and a rich source of information.
The most efficient and user-friendly approach to get full benefit of what GNU Radio has to offer is to implement GNU Radio in the Linux Ubuntu operating system. The GNU Radio developers develop and maintain GNU Radio in Ubuntu. Potential cross platform bugs and incompatibilities are avoided by adopting the same Ubuntu operating system that the developers use. GNU Radio is reported to operate on Windows and Mac OSX, but there are challenges with full implementation with these operating systems which make them best avoided by beginners. Computer users unfamiliar with Linux operating systems shouldn’t be intimidated by using Linux Ubuntu operating system. Ubuntu has the look and feel and straight forward ease of use as MS Windows. The Ubuntu operating system is open source, downloadable via the Internet and can easily be installed in a separate hard drive partition if necessary. Installing Ubuntu via the Internet is straight forward and quick. The official Ubuntu website provides the latest downloadable Ubuntu versions and instructions for using Ubuntu (www.ubuntu.com/download/desktop).
GNU Radio is a dynamic application with version updates on an irregular but frequent basis. It is important to keep abreast of the changes via the web portal and learn to update the application re-using the build-gnuradio script as necessary. Follow the ‘Latest news’ for updates and other information: https://wiki.gnuradio.org/index.php/Main_Page
.For serious DSP authoring and most SDR projects, avoid installing the Linux ‘distribution’ versions of GNU Radio. The ‘distribution’ versions of GNU Radio are built into the Ubuntu operating version at the time of that operating system release. These ‘distribution’ versions can be installed easily from within the Ubuntu version. Because GNU Radio is built into the Ubuntu version at the time of initial release, these GNU Radio versions are typically out of date, have
outdated UHD drivers and are installed differently within the file system from the versions downloaded from the official Source. The UHD might not work with newer SDR hardware. Updating and adding DSP blocks to, distribution, versions is not possible. For these reasons it is best to avoid installing a ‘distribution’ version of GNU Radio instead install a full installation of the current GNU Radio version.
A capable computer is necessary to use GNU Radio to its full real-time DSP potential. The developers recommend a dual-core CPU at the Intel i3 level or above to users. Single core and early Core duo CPUs lack the speed and capacity for many ham DSPs.
GNU Radio DSP, Radio Hardware, and UHD
To implement real-time SDR radio projects with GNU Radio, it is necessary to use compatible SDR hardware. The Universal Hardware Driver (UHD) is a dedicated software package to interface GNU Radio and compatible SDR hardware. Of late, there have appeared a new generation of SDRs that interface with a multi-layered PPA system of GNU Radio packages or a suite of applications. The documentation for compatible hardware will refer to the GNU Radio UHD capability or to a PPA GNU Radio package. Given the popularity of GNU Radio with the DSP developer community, UHD or the GNU Radio PPA is commonly specified for modern SDR hardware.
The latest version of UHD is installed automatically whenever GNU Radio is installed via the build-gnuradio script from Source. The GNU Radio PPA requires a separate and additional installation. The ever-expanding list of compatible hardware is published https://wiki.gnuradio.org/index.php/Hardware An additional point is that searches of the
Internet and close reading of the specifications can sometimes find UHD-compatible SDR hardware that hasn’t yet reached the official list.
GNU Radio Reference Material
- Petrich, W7FU, “Digital Signal Processing and GNU Radio Companion,” Jul/Aug 2017, QEX, pp. 41-46.