Pushbutton IQ Recorder with descriptive filenames

From GNU Radio
Jump to navigation Jump to search


When doing field work, capturing Raw I/Q for post processing is a helpful way to get the best signal quality of a capture while spending minimal time in a non-lab environment. Changing filenames manually for every capture can be laborious and subject to user error. Furthermore, starting and stopping a flowgraph can be tricky if we are tuning the SDR frontend parameters to find optimal level/frequency/sample rate. If a non-descriptive filename is used such as capture_file.cfile it does nothing to describe the situation to the user during the analysis stage as it doesn't include any information about the RF samples we've captured. This is critical to the post-analysis process.

  • What was the sample rate?
  • What was the Center Frequency?
  • When was it recorded?
  • What gain setting did we use?
  • What were we even trying to capture?

These are all questions we ask after the fact, especially if a lot of time has gone by since we did the recordings.

Including those pieces of information in the filename is one way to address this is.


  • GNURadio 3.10+
  • directory /home/<username>/data/iq_captures is present on filesystem (the flowgraph will automatically find your /home/<username> path).


Create a File Sink with Dynamic Information in the Filename[edit]

  • timestamp of recording
  • radio parameters
  • User Input Note for clarity

Only Record the file on an User Input Trigger[edit]

  • Define User Input as Momentary Switch in GUI
  • Set Conditional Statement in File Sink Block


The flowgraph for this tutorial is shown below along with the GRC file needed if you would like to test it out. This flowgraph is intended for use by anyone with GNURadio 3.10+ installed. It does not use an actual SDR frontend which allows users to test without hardware, but that also means that the values for center frequency and gain are merely representative so, when changed at runtime they won't be reflected in the synthetic spectrum when running the flowgraph. The aim of this tutorial is merely to demonstrate the mechanism. For an example that uses real SDR hardware, try https://github.com/muaddib1984/wavetrap

Pushbutton iq recorder whole graph.png

Pushbutton IQ Recorder

Create Synthetic Spectrum for the Flowgraph[edit]

This screenshot shows the blocks used to generate some synthetic spectrum with intermittent narrowband carriers:

Pushbutton synth signal.png

This is what the simulated spectrum looks like when running in GNURadio:

Synth spectrum plot.gif

Create a File Sink with Dynamic Information in the Filename[edit]

In the following example we will: Use some Pythonic syntax to leverage the Runtime Callbacks in our flowgraph and allow the filenames to change dynamically based on timestamp and radio parameters.

We will need to import the appropriate modules to get the user's home directory and create a date/timestamp

Variables and imports.png

The filesink contains the filename variable and appends the properly formatted date/timestamp. Since we may want to trigger multiple recordings after starting the flowgraph, the date/timestamp needs to be generated each time the user triggers a recording, so the syntax must be expressed inside block. If we didn't do this, the date/timestamp would only be set once during the initial setup of the flowgraph.


Then we will use two different variable blocks to define first, the top-level directory (/home/<username>) and second, the appropriate subdirectory data/iq_captures for the recordings. This can be changed to your preference.

Top level variable.png Subdir variable.png

SDR Frontend Information[edit]

We then create the first part of the filename which contains the SDR Frontend parameters and a user note to describe the capture. These will be updated at runtime in the filename if they are changed.

Filename variable.png

This section of the flowgraph is shown here:


If a different format for timestamps is needed the syntax can be modified to suit your needs. The current format is:


This can be tested in a python interactive terminal and adjusted to preference. The necessary code to do this is:

import time
from datetime import datetime

Full Filename and Path[edit]

The below python syntax is put in the "file" parameter of the file sink block. It includes the radio parameters with the date/timestamp. This is incomplete however, as it would record constantly from the time the flowgraph starts. When recording raw IQ we need to be mindful of disk space as raw IQ can take up space fast. In the next section we will show how to trigger the recording with a momentary pushbutton as a safety for our disk space and to keep our recordings limited to only the signals we want to record.


In our current example, using the initial parameters, the filename would be: "RECORDING_NOTE_915000000Hz_1000000sps_50dB_2023_01_04_01_02_39.cfile"

User Input Note to Describe the Capture[edit]

  • We use the QT Entry Widget block to put an editable text field in our flowgraph's GUI
  • NOTE: once the text is changed, the user must hit the ENTER key to update the note

Entry widget parameters.png


Only Trigger Recording on User Input[edit]

Using python conditional statement, we can send the I/Q samples to /dev/null until the record button is pressed (and held). When the record button is pressed, the I/Q samples will begin streaming to a file with a timestamp and radio parameters of the flowgraph's state at the time the button was pressed. When released it will send the samples back to /dev/null

Momentary record button parameters.png

We will also add a QT GUI LED Indicator to turn red when we are recording to disk, it will be green when sending samples to /dev/null.

LED parameters.png

/dev/Null or Filename with Python Conditional Statement[edit]

  • We will send the IQ samples to /dev/null until the trigger event occurs, at that time the expression will be evaluated to switch the path to the predefined path from the flowgraph.

Below is the full python expression to insert in the 'filename' parameter of the file sink block. Note that we simply add a conditional at the end, which is based on the momentary pushbutton's state.

filename+str(datetime.fromtimestamp(time.time()).strftime('%Y_%m_%d_%H_%M_%S'))+".cfile" if rec_button == 1 else "/dev/null"

File sink parameters.png

Here is a brief demo of the flowgraph in action showing the subdirectory adding new timestamped files as we click and hold the momentary pushbutton:

Pushbutton iq demo.gif

NOTE: we use the command watch ls -l in the subdirectory to show the updating file names