This is the gr-qtgui package. It contains various QT-based graphical user interface blocks that add graphical sinks to a GNU Radio flowgraph. The Python namespaces is in gnuradio.qtgui, which would be normally imported as:
See the Doxygen documentation for details about the blocks available in this package. The relevant blocks are listed in the QT Graphical Interfaces group.
A quick listing of the details can be found in Python after importing by using:
There are a number of available QTGUI blocks for different plotting purposes. These include:
The time domain, frequency domain, and waterfall have both a complex and a floating point block. The constellation plot only makes sense with complex inputs. The time raster plots accept bits and floats.
Because the time raster plots are designed to show structure over time in a signal, frame, packet, etc., they never drop samples. This is a
fairly taxing job and performance can be an issue. Since it is expected that this block will work on a frame or packet structure, we tend to be at the lowest possible rate at this point, so that will help. Expect performance issues at high data rates.
Note: There seem to be extra performance issue with the raster plotters in QWT version 5 that were fixed with QWT version 6. As such, the time raster plots have incredibly poor performance with QWT5 to the point of almost being unusable. In the future, we may restrict compilation and installation of these plots only if QWT6 or higher is discovered. For now, just be aware of this limitation.
All QTGUI sinks have interactive capabilities.
Each type of graph has a different set of menu items in the context menu. Most have some way to change the appearance of the lines or surfaces, such as changing the line width color, marker, and transparency. Other common features can set the sampling rate, turn a grid on an off, pause and unpause (stop/start) the display update, and save the current figure. Specific feature are things like setting the number of points to display, setting the FFT size, FFT window, and any FFT averaging.
The time plots have triggering capabilities. Triggering can happen when the signal of a specific channel crosses (positive or negative slope) a certain level threshold. Or triggering can be done off a specific stream tag such that whenever a tag of a given key is found, the scope will trigger.
In the signal level mode, the trigger can be either 'auto' or 'normal' where the latter will only trigger when the even is seen. The 'auto' mode will trigger on the event or every so often even if no trigger is found. The 'free' mode ignores ignores triggering and continuously plots.
By default, the triggers plot the triggering event at the x=0 (i.e., the left-most point in the plot). A delay can be set to delay the signal along the x-axis to observe any signal before the triggering event. The delay feature works the same for both level and tag triggers. The delay is set according to time in seconds, not samples. So the delay can be calculated as the number of samples divided by the sample rate given to the block.
All trigger settings (mode, slope, level, delay, channel, and tag key) are settable in the GRC properties boxes to easily set up a repeatable environment.
A note on the trigger delay setting. This value is limited by the buffer size and/or the number of points being display. It is capped by the minimum of these two values. The buffer size issue is generally only a problem when plotting a large number of samples. However, if the delay is set large to begin with (in the GRC properties box or before top_block.start() is called), then the buffers are resized accordingly offering more freedom. This should be a problem in a limited number of scenarios, but a log INFO level message is produced when asking for the delay outside of the available range.
The QT GUI blocks require the following dependencies.
To use the qtgui interface, a bit of boiler-plate lines must be included. First, the sink is defined, then it must be exposed from C++ into Python using the "sip.wrapinstance" command, and finally, the "show" method is run on the new Python object. This sets up the QT environment to show the widget, but the qApplication must also be launched.
In the "main" function of the code, the qApp is retrieved. Then, after the GNU Radio top block is started (remember that start() is a non-blocking call to launch the main thread of the flowgraph), the qapp's "exec_()" function is called. This function is a blocking call while the GUI is alive.
There are graphical controls in all but the combined plotting tools. In the margins of the GUIs (that is, not on the canvas showing the signal itself), right-clicking the mouse will pull up a drop-down menu that will allow you to change difference parameters of the plots. These include things like the look of the lines (width, color, style, markers, etc.), the ability to start and stop the display, the ability to save to a file, and other plot-specific controls (FFT size for the frequency and waterfall plots, etc.).
There is currently a single configuration option in the preferences files to set the rendering engine of the QTGUI sinks. Located in etc/gnuradio/conf.d/gr-qtgui.conf:
[qtgui] style = raster
The available styles are:
We default this setting to raster for the mix of performance and usability. When using QTGUI sinks through an X-forwarding session over SSH, switch to using 'native' for a significant speed boost on the remote end.
We can also set a QT Style Sheet (QSS) file to adjust the look of our plotting tools. Set the 'qss' option of the 'qtgui' section in our configuration file to a QSS file. An example QSS file is distributed with the QTGUI examples found in share/gnuradio/examples/qt-gui/dark.qss.