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

   The files with the .bin extension are binary files containing the raw 64-bit complex I/Q samples (32 bits for each component). The files with the .hdr extension are binary files containing metadata about the raw I/Q samples. We can download any resources listed in the output, either by clicking the links, or by using curl.

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 have to update the datetime flags according to the data we've collected.

   We should see two horizontal white stripes in 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