Utilities

Besides gr_satellites, gr-satellites installs two helper programs for specific satellites, and the repository contains a few scripts and example flowgraphs that are useful on their own. This page documents each of them: what it does, its arguments, its output, and its pitfalls.

Program Installed Purpose
gr_satellites_ssdv Yes Extract and decode SSDV images from KISS files (JY1SAT, ERMINAZ, DSLWP).
smog_p_spectrum Yes Plot spectrum measurements received from SMOG-P, ATL-1 and SMOG-1.
tools/waveform_plot.py No (repository only) Plot float32 signal dumps.
Doppler and delay scripts No (examples) Generate input files for the Doppler Correction and Time Dependent Delay blocks.

The installed programs also have man pages (docs/gr_satellites.1, docs/gr_satellites_ssdv.1, docs/smog_p_spectrum.1) when CMake's ENABLE_MANPAGES option is on.

gr_satellites_ssdv

Some satellites send images in the SSDV format (originally from high-altitude balloons) inside their telemetry frames. gr_satellites_ssdv reads a KISS file of frames saved with gr_satellites --kiss_out, extracts the SSDV packets, groups them by image, sorts them by sequence number, and calls the external ssdv decoder for each image.

gr_satellites JY1-Sat --wavfile jy1sat.wav --kiss_out jy1sat.kss
gr_satellites_ssdv --satellite JY1SAT jy1sat.kss /tmp/jy1sat

Arguments

Argument Meaning
--satellite {JY1SAT,ERMINAZ,DSLWP} Which frame format to expect. Effectively required (see below).
input KISS file containing frames. It may hold several images from several passes.
output Prefix for output files.

What it does per satellite

Satellite Frame selection ssdv arguments
JY1SAT 256-byte frames with frame ID 0xE0/0xE1 and 0x10 in the second byte; payload from byte 56; packets starting 55 68. -d -J
ERMINAZ CCSDS TM frames on virtual channel 4, after the primary header and 2 more bytes. -d -l <packet length>
DSLWP Short TM frames on virtual channel 1, after the header. -d -D

For each image ID found it writes <output>_<id>.ssdv (the sorted SSDV packets) and runs ssdv to produce <output>_<id>.jpg, printing Calling SSDV decoder for image 0x.. first. If no SSDV packets are found it exits silently.

Requirements and pitfalls

  • An ssdv program that supports the JY1SAT format must be on the PATH. The upstream documentation points to a fork of ssdv by the gr-satellites author for this.
  • --satellite has no default. Without it, the tool crashes with a KeyError as soon as the file contains frames.
  • The upstream documentation still calls this tool jy1sat_ssdv.py; the installed name is gr_satellites_ssdv and it now supports three satellites.

smog_p_spectrum

SMOG-P, ATL-1 and SMOG-1 transmit RF spectrum measurements, which the smogp/smog1 file receivers save as files named like spectrum_start_<start>_step_<step>_rbw_<rbw>_measid_<id>. smog_p_spectrum plots one of them:

smog_p_spectrum spectrum_start_824000000_step_24000_rbw_6_measid_312

It reads the file as unsigned bytes (one PSD value per frequency bin), computes the frequency of bin n as start + step × n, and saves spectrum_<id>.png (here spectrum_312.png) in the same directory as the input file, with the frequency axis in MHz. It does not open a window.

  • Exactly one argument is accepted; otherwise it prints Usage: <program> input_file and exits with status 1.
  • The file name must match the pattern exactly (the program parses it). A renamed file makes it fail with an AttributeError.
  • Requires NumPy and Matplotlib.

waveform_plot.py

tools/waveform_plot.py plots a raw float32 file, such as the .f32 files written by --dump_path, next to a histogram of its values. Well-demodulated symbols show two narrow peaks in the histogram.

python3 tools/waveform_plot.py /tmp/fsk/clock_recovery_out.f32
python3 tools/waveform_plot.py --lines /tmp/fsk/waveform.f32

--lines draws lines only and skips the histogram, which is much faster for large files. The script is not installed; run it from a clone of the repository.

Doppler Correction and Time-Dependent Delay

The Doppler Correction block (Satellites > Doppler) corrects (or simulates) Doppler shift from a text file of time frequency pairs: timestamps in seconds (typically UNIX time), frequencies in Hz, one pair per line separated by a space. Its Start time parameter is the timestamp of the first sample. The Time Dependent Delay block (Satellites > Delay) uses the same file format with delays in seconds instead of frequencies.

examples/doppler_correction/tle_to_doppler_file.py and examples/time_dependent_delay/tle_to_delay_file.py generate such files from a TLE using skyfield:

python3 examples/doppler_correction/tle_to_doppler_file.py \
    --tle-file sat.tle --output-file doppler.txt \
    --unix-timestamp 1709296496 --time-step 0.1

Run the script with --help for its other options. Example flowgraphs are in the same directories.

Other Examples

The examples/ directory has more flowgraphs worth knowing:

Directory Contents
examples/ax25/ AX.25 packet radio transceivers: 1k2 AFSK, 9k6 FSK and BPSK.
examples/ber/ BER tests of the LilacSat-1 demodulator.
examples/ccsds/ The CCSDS TM/TC Space Data Link and Space Packet blocks (see CCSDS_README.md).
examples/components/ One example per main component, referenced throughout these docs.
examples/qo100-multimedia-beacon/ A complete receiver for the QO-100 multimedia beacon, with a WebSocket server.
examples/satellite_decoder/ The Satellite decoder block.
examples/satellites/ Flowgraphs for satellites or functions not covered by the standard decoder (HADES-D, K2SAT images, and others).

See Also