Quick Start

This tutorial takes you from a fresh installation to decoded satellite telemetry. You will decode a sample recording of FUNcube-1 (AO-73), look at the raw frames, save them to a KISS file, re-read that file, and finally decode a live signal streamed from an SDR program. It assumes gr-satellites is already installed (see Installation).

1. Check that the tool works

gr_satellites --version

You should see a first line like gr_satellites v5.10.0-git. If you get ModuleNotFoundError: No module named 'satellites', fix your PYTHONPATH first (Installation).

2. Get a sample recording

The sample recordings live in the satellite-recordings submodule. From a clone of the repository:

cd gr-satellites
git submodule update --init
ls satellite-recordings/ao73.wav

All of these recordings are single-channel (real) 48 kHz WAV files, as produced by a radio or SDR program in USB or FM mode.

3. Find your satellite

The satellite is always the first argument. Look it up with --list_satellites:

gr_satellites --list_satellites | grep -A1 AO-73
* AO-73 (NORAD 39444)
    1k2 BPSK downlink 145.935 MHz DBPSK AO-40 FEC

AO-73 is also known as FUNcube-1 (its alternative name), so AO-73, FUNcube-1 and 39444 all select the same decoder. Name matching ignores case, spaces and punctuation, so funcube1 works too.

4. Decode the recording

gr_satellites FUNcube-1 --wavfile satellite-recordings/ao73.wav

The sample rate is read from the WAV header, so --samp_rate is not needed. Because AO-73 has a telemetry definition, each decoded frame is printed as parsed telemetry. The output looks similar to this (abridged):

-> Packet from 1k2 BPSK downlink
Frame type WO1
----------------------------------------
Realtime telemetry:
----------------------------------------
Container: 
    ...

The first line names the transmitter (from the SatYAML file) that produced the frame. The tool exits by itself when the file has been fully processed.

5. Look at the raw frames

Add --hexdump to print every frame in hex instead of parsing it:

gr_satellites FUNcube-1 --wavfile satellite-recordings/ao73.wav --hexdump

The frames are printed in the format of GNU Radio's Message Debug block, with the PDU length (256 bytes for FUNcube) and a hex dump with offsets, similar to:

pdu_length = 256
contents = 
0000: 89 00 00 00 00 00 00 00 00 1f cc 00 ce 02 d1 00 
0010: 00 07 08 09 09 00 00 05 01 01 00 40 13 2f c8 f2 
...

6. Save frames to a KISS file

gr_satellites FUNcube-1 --wavfile satellite-recordings/ao73.wav --kiss_out ao73.kss

Telemetry is still printed, and every frame is also written to ao73.kss. The file is overwritten on each run; add --kiss_append to add to it instead. Each frame is preceded by a small KISS frame holding its reception timestamp (see Output Options).

7. Re-read the KISS file

gr_satellites FUNcube-1 --kiss_in ao73.kss

Demodulation and deframing are skipped: the frames go straight to the telemetry parser. This is a fast way to re-examine data you decoded earlier, or data saved by other software in KISS format.

8. Tune the demodulator if nothing decodes

If a recording produces no output, the most common causes are a wrong input type or a demodulator setting. Check:

  • Real or IQ? Audio from a radio is real (the default). Raw SDR samples are IQ and need --iq. See Real or IQ Input.
  • BPSK frequency offset. For real input, BPSK signals at 2400 baud or less are expected at 1500 Hz in the audio passband. Use --f_offset if yours is elsewhere.
  • FSK polarity. If the radio inverted the signal, add --input_gain -1.
  • Clock recovery. Increasing --clk_bw (for example --clk_bw 0.1) helps recordings with poor timing.

Run gr_satellites FUNcube-1 --help to see every option that applies to this satellite. The full list is in Demodulation and Deframing Options.

9. Decode a live signal

Many SDR programs can stream demodulated audio over UDP. GQRX, for example, sends 48 kHz audio as 16-bit samples to UDP port 7355, which is exactly what --udp expects by default:

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

Tune GQRX to the satellite (USB mode for BPSK, centring the signal around 1500 Hz in the audio for 1200 baud BPSK), enable UDP streaming, and frames are printed as they arrive. Stop with Ctrl+C; gr_satellites handles SIGINT and SIGTERM by stopping the flowgraph cleanly.

10. Share your data

Set your callsign, location and submit_tlm = yes in ~/.gr_satellites/config.ini to submit decoded frames to SatNOGS DB automatically. See Telemetry Submission.

Next Steps