Tutorials

Contents

• Recording a spectrogram

Recording a spectrogram

In this tutorial, we'll use the Spectre command line interface (CLI) tool to record and visualise spectrogram data. The program is receiver-agnostic, and we can use the same basic commands to record data from any receiver.

Note: No extra hardware is required to follow this tutorial.

1. Explore supported receivers
   Start by listing the receivers supported by Spectre:

   spectre get receivers

   Each receiver supports different operating modes. For example, a receiver might collect I/Q samples at a fixed centre frequency, or sweep the centre frequency over a range to capture a wider spectrum. In this tutorial, we'll use the signal_generator receiver operating in the cosine_wave mode. To confirm this is an available operating mode, we can inspect the output of:

   spectre get modes --receiver signal_generator

2. Create a config
   Next, we'll create a configuration file which describes what data we want to record:

   spectre create config --receiver signal_generator \
                         --mode cosine_wave \
                         --tag my-config

   The --tag flag provides a unique identifier. We didn't ask for any parameters in particular, so it gets created with sensible defaults.

   To verify that the config has been created:

   spectre get configs

   Then, we can read its contents:

   spectre get config --tag my-config

   For more detail about what each parameter means, and the values it can take, we can inspect the corresponding model:

   spectre get model --receiver signal_generator \
                     --mode cosine_wave

3. Update the config
   Once the config is created, we can customise the parameters. To increase the amplitude of the cosine wave:

   spectre update config --tag my-config \
                         --param amplitude=3.0

   Spectre performs some sanity checks to ensure the config parameters are valid. This helps prevent undefined behaviour. To test this, try and update the sample rate to be negative:

   spectre update config --tag my-config \
                         --param sample_rate=-100

4. Recording I/Q samples
   We're ready to start capturing data. To record I/Q samples, run:

   spectre record signal --tag my-config \
                         --duration 10

   In this case, the --tag flag indicates which config we want to use. Once complete, view the newly created data files:

   spectre get files

   Files with the .fc32 extension are binary files containing interleaved single-precision complex I/Q samples (32 bits per component). We can download any resources listed in the output by clicking the links, using curl or using the --export flag on supported commands.

5. Recording spectrograms
   To record spectrograms, simply run:

   spectre record spectrograms --tag my-config \
                               --duration 10

   Once complete, view the newly created data files:

   spectre get files --extension fits

   Here, we have filtered for the spectrograms which are stored in the FITS file format. In this format, they cannot be directly visualised.

   To create an image of the spectrogram, use the command:

   spectre create plot --tag my-config \
                       --obs-date 2025-07-05 \
                       --start-time 17:23:00 \
                       --end-time 17:24:00 

   Note: We'll need to update the datetime flags based on the data we've collected.

   Finally, export the files to your local filesystem:

   spectre get files --export data/

   This will create a directory called data in your current working directory. Find the png file and view the spectrogram.

6. Next steps
   We can use the same basic commands to record data from any receiver. Explore all the available commands, starting with:

   spectre --help