Difference between revisions of "Talk:FAQ"

From GNU Radio
Jump to navigation Jump to search
(add section 5)
 
(4 intermediate revisions by one other user not shown)
Line 3: Line 3:
<hr>
<hr>


<b>DRAFT REVISIONS TO FAQ</b><br>
== Future Edits: Hardware support ==
<b>Frequently Asked Questions</b>


== Getting Started ==
After inclusion of gr-soapy in an official release, as well as gr-iio: Needs to state something like


=== What is GNU Radio? ===


Check out our page [[WhatIsGR|What is GNU Radio?]] for an introduction to what GNU Radio is and why you would want to use it.
== Does GNU Radio support my SDR hardware? ==


=== How do I get / install GNU Radio? ===
If you've got a


We strongly encourage you to use your distro package manager. Debian/Ubuntu and Fedora/RedHat as well as many of the other popular Linux distros keep these packages well up to date. For Mac OS X, using Macports is strongly encouraged. See [[InstallingGR]] for details.
* Ettus / National Instruments USRP: yes, through the included `gr-uhd` module (use the `USRP Sink` / `USRP Source`)
* a IIO device like the ADALM Pluto SDR: yes, through the included `gr-iio` module (GNU Radio version 3.x.y.z upwards)
* Any other device (e.g. RTL-SDR dongles): if there's a soapysdr plugin [Link to Soapysdr] for it, then it can be used through gr-soapy (GNU Radio version 3.a.b.c upwards)


=== Which operating systems are supported? Does GNU Radio run on Windows or Mac OS X? What about 32, 64 Bits? ===
Generally, gr-soapy is an abstraction that unifies access to many different SDRs. This means your flow graph might also work for others with different hardware, but especially for the more complex hardware (e.g. USRPs), this means you don't get access to all the functionality of your device.
 
We mostly develop under Linux, and we've gotten GNU Radio to run under most current Linux distros. The best support will be for the latest supported versions of Ubuntu (their Long Term Support versions) and Fedora. Other common distros like Debian are well-maintained and will generally work fine. For Redhat and CentOS, you may find yourself needing to install some dependencies by hand. We highly recommend the use of PyBOMBS with these distros.
 
GNU Radio is also maintained on OS X. We have installation instructions and can help doing source builds on OS X. However, we highly recommend that you use the Macports installation of GNU Radio to make sure all of the dependencies are taken care of properly.
 
GNU Radio will build and run under Windows. However, we don't have direct, maintained support for Windows and few of us can help you with Windows issues. We hope to have better support in the future, but in the meantime, there are plenty of people with various levels of success working under Windows that you can contact through the discuss-gnuradio Mailing List.
 
GNU Radio supports both 32- and 64-bit operating systems.
 
For processor support, we generally develop and build on Intel x86 architectures. These processors have the best support for features and speed. However, we are actively developing our support and capabilities on ARM processors, currently only those running the ARMv7 instruction set. Older ARM processors with ARMv6 support have been known to work, but we have no direct support for them. They tend to be severely underpowered for math and signal processing for any serious GNU Radio app. We will be developing support for ARMv8. We also have a [[Embedded|limited list of embedded devices and development kits]] that we are able to support.
 
=== What are the system requirements (minimum power, etc.)? ===
 
GNU Radio in its core is C++ with lots of user functionality relying on [http://python.org Python]. So basically, as long as there is a feasible compiler for your platform, it '''can''' work.
 
'''Hardware requirements''' basically depend on what you want to do. A modern PC/laptop computer is usually up to most tasks such as receiving broadcast signals, doing audio frequency processing, and many narrowband digital signals.
 
When dealing with telecommunication signals, however, sample rates of over 5 Msamples/s are not uncommon. The average embedded ARM platform is generally not up to that task. Even rather modern hardware often meets its limits when it comes to doing things in realtime; '''it all depends on your processing requirements''', GNU Radio is only the platform to perform these computationally intensive tasks.
 
=== I installed GNU Radio, but some components seem to be missing. ===
 
Missing components are usually seen because blocks are missing from GRC. This usually only happens when you did a source build. After running cmake, you might see something like this at the end of CMake's output (this list is heavily cropped for simplicity, it is much longer in reality):
 
<pre>-- ######################################################
-- # Gnuradio enabled components                       
-- ######################################################
--  * python-support
--  * testing-support
--  * volk
--  * doxygen
--  * gnuradio-runtime
--  * gr-blocks
--  * gnuradio-companion
--  * gr-fec
--  * gr-fft
--  * gr-filter
--  * [...]
--
-- ######################################################
-- # Gnuradio disabled components                       
-- ######################################################
--  * gr-ctrlport
--  * gr-dtv
--  * gr-atsc
--  * gr-wxgui</pre>
If the components you are missing are listed under the 'disabled' components, there's your problem.<br />
There are two reasons why components are disabled:<br />
- You disabled them yourself, e.g. by supplying a `-DENABLE_GR_DTV=OFF` switch to CMake.<br />
- The component was automatically enabled because CMake could not find certain dependencies.
 
In both cases, you can read the CMake output to see what the reason is. If dependencies are missing, you might have to install developer packages for something (on Debian and Ubuntu systems, these are packages ending with -dev, on Fedora, they end with -devel). Consult the build manual for which dependencies are required.
 
If you don't understand or know how to do this, consider installing precompiled binaries. Usually, they will pull in all the required dependencies.
 
=== Which Radio Hardware is supported? ===
 
There is a growing list of radio front ends for software radio uses. It is difficult to keep up with, and support for a particular radio front end in GNU Radio is generally left to the hardware manufacturer. The Ettus Research USRP product line, supported by UHD, is the exception since the USRP and GNU Radio have had a long history of developing and working together. See also [[Hardware]].
 
=== Can you suggest any reading material for DSP/SDR/Digital Comms? ===
 
We have a wiki page for this: [[SuggestedReading]]
 
<!-- Marker section 2 -->
== Using GNU Radio ==
 
=== How do I start? What's the first thing to do after installation? ===
 
Start with our [[Tutorials]] to learn your way around GNU Radio. They are divided into levels of user experience.
 
=== Where can I find a list of GNU Radio blocks? ===
 
All GNU Radio blocks are listed in [https://wiki.gnuradio.org/index.php/Category:Block_Docs Block Docs]. When using GNU Radio Companion, blocks are also listed in the ''Block Tree'' sidebar. You can use the search feature of GNU Radio Companion (a magnifying glass) to find blocks by name.
 
=== What does ''sample rate'' mean in GNU Radio? ===
 
First off: You need to understand the general principle of "Sampling Rate" and the sampling theorem before you do anything with GNU Radio. See [[SuggestedReading]].
 
For a tutorial on sample rate, see [[Sample_Rate_Tutorial]].
 
=== My flowgraph is too slow. What can I do to make it faster? My hardware signals underflows, overflows or dropped samples. ===
 
The most common answer to that question is: It's as fast as it ''can'' run. If your signal processing application really needs that much computing, you need more computational power.
 
There are, however, some cases where your problems can be helped:
 
# If your signal processing relies on a bandwidth that is substantially smaller than your nyquist bandwidth (in case of complex sampling: sampling rate, in case of real sampling: 0.5 * sampling rate) use a lower sampling rate as early as possible. Often, you could also tell your hardware to produce a lower sample rate.
# If your signal processing could as well be done offline (instead of in realtime), write your signal to file (using file_sink) and load it from there in another flowgraph (using file_source)
 
=== When do I use a throttle block? ===
 
GNU Radio is written and designed for real-time streaming signal processing that interfaces with real hardware systems. A GNU Radio application attempts to source data from a hardware source and sink data to a hardware sink as quickly as possible. That means that we are rate limited by the hardware, which will either provide or allow us to push data between GNU Radio and the hardware system based on the rate of the hardware.
 
For other cases, see [[Sample_Rate_Tutorial#When_there_is_no_hardware_block]].
 
=== What is the file format of a file_sink? How can I read files produced by a file sink? ===
 
All files are in pure binary format. Just bits. That's it. A floating point data stream is saved as 32 bits in the file, one after the other. A complex signal has 32 bits for the real part and 32 bits for the imaginary part. Reading back a complex number means reading in 32 bits, saving that to the real part of a complex data structure, and then reading in the next 32 bits as the imaginary part of the data structure. And just keep reading the data.
 
Take a look at the Octave and Python files in gr-utils for reading data using Octave and Python's Scipy module.
 
The exception to the format is when using the metadata file format. These files are produced by the <code>File Meta Sink</code>: http://gnuradio.org/doc/doxygen/classgr_1_1blocks_1_1file_''meta''_sink.html block and read by the [http://gnuradio.org/doc/doxygen/classgr_1_1blocks_1_1file__meta__source.html File Meta Source] block. See the manual page on the [http://gnuradio.org/doc/doxygen/page_metadata.html metadata file format] for more information about how to deal with these files.
 
A one-line Python command to read the entire file into a numpy array is:
 
f = scipy.fromfile(open("filename"), dtype=scipy.uint8)
 
Replace the dtype with <code>scipy.int16</code>, <code>scipy.int32</code>, <code>scipy.float32</code>, <code>scipy.complex64</code> or whatever type you were using.
 
<!-- Marker section 3 -->
== GNU Radio Companion ==
 
For a tutorial on GRC, see [[Guided_Tutorial_GRC]].
 
=== How do I change the canvas size? ===
 
It's in the 'Options' block of your flow graph. The dimensions are in pixels, e.g. canvas (1536,1024)
 
=== How do I make the text larger on a HiDPI display like a Retina MacBook? ===
 
Please see [[Tips for MacBooks and other HiDPI displays]].
 
<!-- Marker section 4 -->
== About GNU Radio (Internal, Structure...) ==
 
=== How is the GNU Radio source tree structured? ===
 
Basically, GNU Radio consists of the runtime scheduler and the main block class structure that lives in gnuradio-runtime. Outside of gnuradio-runtime are our top-level (or in-tree) components that consist mostly of blocks for building GNU Radio flow graphs as well as supporting code and quality assurance (QA) code for the blocks.
 
The top level component structures are all the same, and only gnuradio-runtime looks different, though there are similar structural aspects to the code. A top-level component also shares the same basic structure as any Out of Tree (OOT) module we would create to build a project that works with GNU Radio (<code>gr_modtool</code> works for in-tree components as well as OOTs).
 
=== How is a GNU Radio application structured? ===
 
A GNU Radio program is structured as a <code>flowgraph</code> that consists of blocks. As mentioned, the blocks can be found in the GNU Radio top-level components and any OOT modules you've installed alongside GNU Radio. We first create a top_block that's the object that contains the full flowgraph. Blocks are then connected together by connecting streaming outputs to inputs or connecting message ports together.
 
=== What are "items" in a flowgraph? ===
 
GNU Radio blocks work off a concept of "items". We are tempted to think of signal processing applications in terms of "samples", but this isn't expressive enough for all of the different situations we work with in GNU Radio. Sometimes, a block may be operating off samples, symbols, bits, bytes, packets, frames, or other types of data structures. We generalize this into the name <code>items</code>. Blocks process items. We have to know what those items mean to each block.
 
The block is generalized such that it either knows what type of item it deals with (like a multiply_cc block works explicitly off complex data streams) or we tell it what data type to use, like a file source or sink. The block is interested in two things. First, the data type itself if it's doing operations directly on the data. The complex multiply block needs to know the data type of the stream because doing complex multiplies is very different than  floating point multiplies. In other situations, like the file sink and source blocks, they just need to know how many bytes to write or read from a file. They don't care about the data structure, just the size of the data structure. So we can tell them the size, in bytes, of the item type. In the case of reading from a complex file, we give it the size of a complex item, which is 64 bits.
 
=== Why use Python? It's so slow! ===
 
It's not really that bad. In fact, good Python programming practices are as good as and sometimes better than naive C/C++ programming. Working harder at the C++ code, however, is still going to be better, obviously.
 
More importantly, this isn't the right question to ask. GNU Radio uses Python as a scripting language, not (usually) for runtime signal processing (see the question on Python blocks, too). All of GNU Radio blocks and the scheduler are written in C++. We export the interface into Python to allow us to use that as a scripting language to make it easy to put flowgraphs together. At runtime, Python gets out of the way unless you've programmed something yourself in Python, which is common for user interface, controls, and interaction.
 
=== What is a Python Block? Can I write actual processing blocks in Python? ===
 
There is a facility to write and use a block in Python, which we call Python blocks. There's an interface between the Python domain and the runtime flow graph which allows us to write our blocks in Python and connect them to other GNU Radio blocks. Using this feature can be nice for quick prototyping, demos, and debugging. Using good Python programming techniques such as relying on Numpy and Scipy routines will help a lot here. But don't expect a Python block to be your deployed runtime version of the code unless the data rates are very low. You will probably want to translate this block into a C++ block. The exceptions are for slower parts of the graph, such as control, measurements, or even packet-level processing operating on chunks of bytes instead of samples. Measurements and profiling are your friend.
 
=== What's the logic behind GNU Radio versions? ===
 
We use a standard version numbering scheme in GNU Radio: Major.API.Minor.Patch. Please see the explanation on our [[ChangeSets]] page.
 
=== Why can't we do loops? ===
 
A lot of users come into the project looking to experiment, including building known algorithms like phase-locked loops (PLLs). GNU Radio comes with each of the blocks to build your own PLL in a flowgraph, like a multiplier, lowpass filter, and VCO. But you try to put it together and GNU Radio tells you it won't work. That the flow graphs don't allow you to do loops. Why? PLLs are fundamental to radio and signal processing! How can it be that I can't build loops into a flow graph?
 
You can't perform loops in the flowgraph, but you can still do loops in GNU Radio. Let's first explore why we can't do loops in the way we might want. Data flow between blocks happens in chunks. While we might want to think of a continuous stream of samples going through a block, what really happens is a block is passed a large chunk of data from the previous block. This block processes this chunk of data in its work function and then passes it onto the next block. Data movement is a costly event, and so we want to minimize data movement to focus on data processing. To handle feedback, we must only process one sample at a time, otherwise, the feedback loop won't work. Processing a single sample means maximizing the data movement overhead and is unworkable.
 
Instead, let's look into a block to handle loops. Within a block, we can handle the data stream how we need to in order to look at the next sample. These algorithms like PLLs and other similar loops are common enough and fundamental enough that they probably belong in their own block, anyways. In fact, if you look at the list of GNU Radio blocks, you'll see a number of these loops already written. You can look at these for examples on how to set yourself up to perform loops like this.
 
Another way to handle loops is to use the asynchronous message passing interface. Messages can be sent from one block to any other block in the flow graph, in front or behind it in the data stream. Just remember that these messages are, as they are named, asynchronous. So the message doesn't arrive at any specific time relative to the data stream. So this would not be the way to implement a PLL-type loop, but another control-level loop not directly tied to the data would work fine.
 
=== Which license does GNU Radio use? ===
 
GNU Radio is licensed GPLv3 or later. All code in the GNU Radio project is copyrighted by the Free Software Foundation. If you have questions about working with the license in your organization, there is a lot of material out there. The [http://www.linuxfoundation.org/publications/compliance Linux Foundation has a webpage] dedicated to helping understand this issue.
 
When developing your own project off GNU Radio, this code is obviously your own and not owned by the FSF. When contributing code to the core GNU Radio project, we need a copyright assignment for that code. Please read our [[Development]] wiki page for how to work with us in developing code and more information about the copyright assignment.
 
<!-- Marker section 5 -->
== Developing with GNU Radio ==
 
=== How can I add my own functionality to GNU Radio? ===
 
This depends. In most cases, you want to write your own module (an "out of tree" module, because it won't live inside the GNU Radio source code).  Have a look at the [[OutOfTreeModules|tutorial on how to do this]]. If you think your block is an important DSP component or something else that should be part of the GNU Radio core, have a look at the [[Development|contributor guide]].
 
=== How does the history work? ===
 
The history is the number of items a block needs to calculate 1 output item. For a filter, this is equal to the number of taps.<br />
For a simple differentiator (y(n) = x(n) - x(n-1)), the history equals 2. Obviously, the smallest value for the history is 1.
 
In the work function, the number of items in your input buffer equals the number of input items plus the history minus one.<br />
Here is an example for an accumulator that outputs the sum of the last N items:
 
<pre>for (int i = 0; i < noutput_items; i++) {
    out[i] = 0;
    for (int k = 0; k < history(); k++) {
        out[i] += in[i+k];
    }
}</pre>
As you can see, <code>noutput_items</code> items of out[] are written, whereas <code>noutput_items + history() - 1</code> items of in[] are read from.
 
If the history has the value N, the first N-1 items are "old" items, i.e. they were available in the previous call to <code>work()</code> (when <code>work()</code> is called the first time, they are set to zero).
 
=== In my OOT Module, I'm trying to use a GNU Radio block or class but get an ImportError "undefined symbol". What do I do? ===
 
You need to tell your OOT module to link against the right set of GNU Radio libraries. Instructions are found in our [[OutOfTreeModulesConfig]] page.
 
Basically, an OOT module is only told to link against RUNTIME, or libgnuradio-runtime.so. If you're using a class or block from another GNU Radio component, you'll need to add that component for proper linking. In your CMakeLists.txt file in the top-level directory of the OOT project, make sure to add whatever components you might need with this line:
 
<code>set(GR_REQUIRED_COMPONENTS RUNTIME <YOUR COMPONENTS>)</code>
 
such as PMT, BLOCKS, FILTER, FFT, ANALOG, DIGITAL, etc.
 
=== How can I reconfigure a flow graph? How do I use lock(), unlock()? ===
 
A running flow graph is static, and can't be changed. There are two ways to implement reconfigurability:
 
* Use lock() / unlock()
* Create blocks that react dynamically
 
Using lock() and unlock(), you will actually stop the flow graph, and can then disconnect and re-connect blocks. In the following example, the flow graph will run for a second, the stop the execution (lock), disconnect the source, connect a different one, and resume. The resulting file will first have data from the vector source, then lots of zeros.
 
<syntaxhighlight lang="python">
#!/usr/bin/env python
import time
from gnuradio import gr
from gnuradio import blocks
 
def main():
    tb = gr.top_block()
    src1 = blocks.vector_source_f(range(16), repeat=True)
    throttle = blocks.throttle(gr.sizeof_float, 1e6)
    sink = blocks.file_sink(gr.sizeof_float, 'out.dat')
    tb.connect(src1, throttle, sink)
    tb.start()
    time.sleep(1)
    print "Locking flowgraph..."
    tb.lock()
    tb.disconnect(src1)
    src2 = blocks.null_source(gr.sizeof_float)
    tb.connect(src2, throttle)
    print "Unlocking flowgraph..."
    tb.unlock()
    time.sleep(2)
    tb.stop()
    tb.wait()
 
if __name__ == "__main__":
    main()
</syntaxhighlight>
 
Note that this is not meant for sample-precision timing, but rather for situations where time does not really matter.
 
If sample-timing is an issue, use general blocks to react to certain events. In the following example, we assume that you have written a general block which stops reading from the first sink at a given time, and then seamlessly switches over to the second input:
 
<syntaxhighlight lang="python">
#!/usr/bin/env python
import time
from gnuradio import gr
from gnuradio import blocks
import my_awesome_oot_module as myoot # This is your custom module
 
def main():
    tb = gr.top_block()
    src1 = blocks.vector_source_f(range(16), repeat=True)
    src2 = blocks.null_source(gr.sizeof_float)
    switch = myoot.switch() # This is your custom block
    throttle = blocks.throttle(gr.sizeof_float, 1e6)
    sink = blocks.file_sink(gr.sizeof_float, 'out.dat')
    tb.connect(src1, switch, throttle, sink)
    tb.connect(src2, (switch, 1))
    tb.start()
    time.sleep(2)
    tb.stop()
    tb.wait()
 
if __name__ == "__main__":
    main()
</syntaxhighlight>

Latest revision as of 14:12, 21 May 2021

NOTE: This page is not a support forum.


Future Edits: Hardware support[edit]

After inclusion of gr-soapy in an official release, as well as gr-iio: Needs to state something like


Does GNU Radio support my SDR hardware?[edit]

If you've got a

  • Ettus / National Instruments USRP: yes, through the included `gr-uhd` module (use the `USRP Sink` / `USRP Source`)
  • a IIO device like the ADALM Pluto SDR: yes, through the included `gr-iio` module (GNU Radio version 3.x.y.z upwards)
  • Any other device (e.g. RTL-SDR dongles): if there's a soapysdr plugin [Link to Soapysdr] for it, then it can be used through gr-soapy (GNU Radio version 3.a.b.c upwards)

Generally, gr-soapy is an abstraction that unifies access to many different SDRs. This means your flow graph might also work for others with different hardware, but especially for the more complex hardware (e.g. USRPs), this means you don't get access to all the functionality of your device.