Recipes

Ready-to-adapt gr_satellites command lines for common situations: live decoding from SDR software, IQ recordings, correct timestamps, feeding other programs, batch processing, and running a single transmitter. Each recipe explains why the options are needed. Replace satellite names and file names with your own.

On this page:

Live Decoding from GQRX

GQRX can stream its demodulated audio as 16-bit samples at 48 kHz to UDP port 7355, the defaults of --udp:

gr_satellites FUNcube-1 --udp --samp_rate 48e3

Use FM mode for FSK/AFSK satellites and USB mode for BPSK. For BPSK at 1200 baud, tune so the signal is centred at about 1500 Hz in the audio, or tell gr_satellites where it is with --f_offset. The input is real (no --iq), because GQRX sends audio.

Decode a Raw IQ Recording

A recording made with a GNU Radio File Sink of type complex (or any complex64 file), centred on the satellite:

gr_satellites AU03 --rawfile pass.c64 --iq --samp_rate 96e3

With --iq, FSK and AFSK satellites are FM-demodulated internally and BPSK is expected at 0 Hz. If the signal is not centred, shift it with --f_offset (BPSK only) or pre-process the file. For int16 IQ use --rawint16 instead of --rawfile.

Decode a Two-Channel IQ WAV File

Many SDR programs save IQ as stereo WAV. The repository's test.sh decodes NuSat 1 this way:

gr_satellites "NuSat 1" --wavfile nusat.wav --iq --samp_rate 192e3

Fix Inverted FSK

FM receivers may invert the polarity of the audio. Non-differential FSK protocols then fail. Multiply the input by −1:

gr_satellites "Astrocast 0.1" --wavfile astrocast_9k6.wav --input_gain -1 --clk_limit 0.05

(This line is from test.sh, which also widens --clk_limit for that recording.)

9k6 BPSK in Wide SSB

For BPSK above 2400 baud with real input, the default --f_offset is 12000 Hz: tune the SDR's USB passband to 24 kHz wide and centre the signal in it. If your passband or tuning differs, set the offset explicitly:

gr_satellites LilacSat-1 --udp --samp_rate 48e3 --f_offset 11000

Remember that --f_offset applies to every BPSK transmitter of the satellite. For a satellite with both 1k2 and 9k6 BPSK downlinks (such as PW-Sat2), an explicit offset moves both demodulators, whereas the defaults give each its own (1500 Hz and 12000 Hz).

Archive a Pass with Correct Timestamps

To process a recording as if it were live (for correct KISS timestamps or SatNOGS submission), play it at real speed and give its start time:

gr_satellites FUNcube-1 --wavfile 2024-03-01_1234.wav \
    --throttle --start_time 2024-03-01T12:34:00Z \
    --kiss_out 2024-03-01_1234.kss

--start_time accepts ISO 8601; a time without a timezone is taken as UTC. For SigMF recordings with a single capture segment, core:datetime is used automatically.

Feed Frames to Another Program

KISS over TCP, which many telemetry viewers support:

gr_satellites AU03 --udp --samp_rate 48e3 --kiss_server

Clients connect to 127.0.0.1:8100. To allow other machines:

gr_satellites AU03 --udp --samp_rate 48e3 --kiss_server 8100 --kiss_server_address 0.0.0.0

ZeroMQ, for GNU Radio flowgraphs with a ZMQ SUB Message Source:

gr_satellites AU03 --udp --samp_rate 48e3 --zmq_pub tcp://127.0.0.1:5555

Re-Read Old Data Without Submitting It

If telemetry submission is enabled in your configuration, re-reading a KISS file would submit old frames with the current time. Disable submission for that run:

GR_SATELLITES_SUBMIT_TLM=0 gr_satellites AU03 --kiss_in old_pass.kss

Batch-Decode Many Recordings

A shell loop over recordings of different satellites, with options that not every satellite has:

export GR_SATELLITES_SUBMIT_TLM=0
for f in recordings/*.wav; do
    sat=$(basename "$f" .wav)
    gr_satellites "$sat" --wavfile "$f" --clk_bw 0.08 --use_agc \
        --ignore_unknown_args --kiss_out "kiss/$sat.kss"
done

--ignore_unknown_args turns options such as --use_agc (FSK only) into a warning for BPSK satellites instead of an error.

Decode Only One Transmitter

When a satellite has several transmitters, gr_satellites runs all of them in parallel and you cannot select one on the command line. To run just one (for example to dump internal signals or use different settings):

  1. Copy the bundled SatYAML file (see Adding a Satellite).
  2. Delete the other entries under transmitters.
  3. Run the copy by path:
gr_satellites ./1KUNS-PF-9k6.yml --wavfile 1kuns_pf.wav --dump_path /tmp/dump

The file name must end in .yml.

Keep Per-Satellite Settings

Put the options that work for each satellite in ~/.gr_satellites/sat.cfg, keyed by NORAD ID:

39444 --f_offset 1600
42731 --clk_bw 0.1

and add --satcfg to the command line:

gr_satellites AU03 --udp --samp_rate 48e3 --satcfg

Options typed on the command line override the file. See Configuration for the format's limitations.

Listen to LilacSat-1 Codec2 Voice

LilacSat-1 transmits Codec2 digital voice. Its decoder sends each 7-byte Codec2 frame in its own UDP packet to 127.0.0.1:7000 (change with --codec2_ip and --codec2_port). Decode and play it in real time with the c2dec program from the codec2 library and SoX's play:

nc -lu 7000 | c2dec 1300 - - | play -t raw -r 8000 -e signed-integer -b 16 -c 1 -

and in another terminal:

gr_satellites LilacSat-1 --udp --samp_rate 48e3

See Also