gr-satellites

gr-satellites is a GNU Radio out-of-tree module that decodes telemetry from hundreds of Amateur radio satellites. It takes RF samples, from a live SDR, a soundcard or a recording, and turns them into decoded frames, human-readable telemetry, reassembled files and images, or data submitted to online telemetry databases. This documentation covers the gr_satellites command line tool, the SatYAML satellite description format, the GNU Radio blocks, and how to extend the project with new satellites.

What gr-satellites Does

Small satellites that transmit on the Amateur bands use a wide variety of modulations and link-layer protocols: plain AX.25 packet radio, the GOMspace NanoCom AX100 and U482C modems, CCSDS concatenated coding, the AO-40 FEC protocol used by FUNcube, and many ad-hoc formats designed by individual satellite teams. Decoding each one by hand means building a separate GNU Radio flowgraph with the right filters, clock recovery, descrambler, FEC decoder and CRC check.

gr-satellites packages all of that knowledge. Each supported satellite is described in a small YAML file (a SatYAML file) that lists its transmitters, their modulation, baud rate and framing, and what to do with the decoded data. The gr_satellites command reads that description and assembles a complete decoder at runtime.

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

That single command demodulates 1200 baud DBPSK, decodes the AO-40 FEC (Viterbi, deinterleaving, descrambling and Reed-Solomon), and prints the FUNcube telemetry fields as text.

Key Features

  • Around 420 bundled satellite descriptions, selectable by name, alternative name, or NORAD ID. See Basic Usage.
  • Many input sources: WAV/OGG/FLAC files, raw float32/complex64/int16 recordings, SigMF recordings, soundcard input, UDP streams (for example from GQRX), and previously decoded KISS files. See Input Sources.
  • Real or IQ input, with sensible behavior for audio from conventional radios and for raw SDR samples. See Input Sources.
  • Several outputs at once: telemetry printing, hex dumps, KISS files with timestamps, a KISS TCP server and a ZeroMQ PUB socket. See Output Options.
  • Telemetry submission to SatNOGS DB, the FUNcube Warehouse, PW-Sat2, BME servers, the HIT proxy, and any SIDS server. See Telemetry Submission.
  • File and image reassembly, with live image display through feh. See Files and Images.
  • Tunable demodulators (BPSK, DBPSK, Manchester BPSK, FSK, AFSK, subaudio FSK) with options for loop bandwidths, frequency offset and syncword error thresholds. See Demodulation and Deframing Options.
  • GNU Radio Companion blocks: a Satellite decoder block that wraps the whole decoder, plus reusable demodulator, deframer and data sink components.
  • Extensible: adding a satellite that uses an existing protocol only takes a SatYAML file. See Adding a Satellite.

How It Works

The decoding chain is split into five kinds of components:

RF samples ──► Demodulator ──► Deframer ──► (Transport) ──► Data sinks
               BPSK/FSK/AFSK   AX.25,        KISS,          telemetry parser,
               soft symbols    CCSDS, ...    TM KISS        file receiver,
                               PDUs          PDUs           KISS file, ZMQ, ...
  1. A demodulator turns RF samples into soft symbols (filtering, AGC, carrier and clock recovery).
  2. A deframer finds frame boundaries in the symbol stream and performs descrambling, deinterleaving, FEC decoding and CRC checks. Its output is a PDU per valid frame.
  3. An optional transport handles higher-layer protocols, such as KISS streams split across several frames.
  4. Data sinks consume the frames: parse telemetry, reassemble files, print hex, write KISS files or submit to servers.

The SatYAML file says which component to use at each step. When a satellite has several transmitters (for example 1k2 and 9k6 downlinks), gr-satellites runs one decoder chain per transmitter in parallel on the same input. The full process is described in Architecture.

A Short Example

Decoding a recording, saving every frame to a KISS file and also serving frames to other programs over TCP:

gr_satellites AU03 --wavfile au03.wav \
    --kiss_out au03.kss --kiss_server

Re-reading the KISS file later, without demodulating again, prints the telemetry:

gr_satellites AU03 --kiss_in au03.kss

When to Use gr-satellites

Use it when you want to:

  • decode telemetry from Amateur satellites with an SDR or a radio connected to a soundcard,
  • contribute frames to SatNOGS DB or a satellite team's own telemetry server,
  • build a ground station decoder for a CubeSat that uses a common modem (AX100, U482C, CCSDS, AX.25),
  • reuse well-tested GNU Radio blocks for FEC, scrambling, KISS and HDLC in your own flowgraphs.

It is less suitable when:

  • you need to transmit: gr-satellites is mainly a receiver (a few framer and encoder blocks exist, but there is no transmit tool),
  • the satellite uses high-rate or wideband modes far beyond the rates the bundled demodulators are tuned for,
  • you need a GUI. The tool is command-line only; graphical work is done in GNU Radio Companion.

Project Status

gr-satellites is actively developed by Daniel Estévez and contributors. The main branch targets GNU Radio 3.10, and releases in the current v5.x.y series are published from the maint-3.10 branch. The v4.x.y (GNU Radio 3.9) and v3.x.y (GNU Radio 3.8) series were frozen on 2025-07-31. The latest release listed in the changelog is 5.9.0 (2025-12-14); the code on main reports version v5.10.0-git.

Support is handled only through GitHub issues and GitHub discussions, not by private email. The project is licensed under GPL-3.0-or-later.

Where to Go Next