gr-satellites: turning Amateur satellite downlink into readable telemetry

What gr-satellites decodes, and who the project is for

gr-satellites exists to turn a noisy radio recording into telemetry you can actually read. It is a GNU Radio out-of-tree module, so its decoders arrive as blocks that you drop into a GNU Radio flowgraph rather than as a separate program with its own menu. The project started in 2015 with an explicit goal: provide telemetry decoders for all the satellites that transmit on the Amateur radio bands.

The audience is narrow and technical. Amateur radio operators running ground stations are the core case, satellite teams building their own receivers come next, and the project describes itself as a set of building blocks for decoders for other satellites or for other groundstation solutions. Some of the low level blocks are described as useful for other kinds of RF communications protocols, which widens the use beyond spacecraft telemetry without turning the project into a general purpose demodulator library.

From RF samples to hex frames: the decode chain

Decoding here is a chain of stages that map onto familiar receiver tasks. The module performs demodulation and forward error correction, and the result is presented as decoded frames. Those frames can be saved to a file or displayed in hex format, which is the first real checkpoint for a new user. If the bytes look wrong at that point, no higher layer parsing will rescue them.

The protocol coverage is broad and specific. The project lists AX.25, the GOMspace NanoCom U482C and AX100 modems, an important part of the CCSDS stack, the AO-40 protocol used in the FUNcube satellites, and several ad-hoc protocols used in other satellites. A short look at the physical layers involved:

AX.25
AX100
AO-40

The examples tree is organised by protocol and by problem, with folders named ax25, ber, ccsds, doppler_correction, qo100-multimedia-beacon, satellite_decoder, satellites and time_dependent_delay, plus a kiss_submitter.grc flowgraph. Working through one of those flowgraphs is the fastest way to learn how a frame gets from the radio front end into a readable output.

Telemetry format definitions and real-time JPEG reassembly

Frame decoding is only half of the job for most operators. gr-satellites also carries telemetry format definitions for some satellites, which lets it print decoded telemetry frames as human-readable values such as bus voltages and currents instead of leaving you to interpret a hex dump by hand. The coverage here is explicitly partial. The format definition is included for some satellites and not for others, so a pass can produce perfectly good frames and still leave you needing your own decoding knowledge.

The second capability is file recovery. Some satellites transmit files such as JPEG images, and gr-satellites can reassemble those files and even display the images in real time as they are being received. That is the feature that turns a receiver into something more than a telemetry terminal. It is also the feature most exposed to mission specific behaviour, since a file transfer on one spacecraft rarely matches the one on the next, so the reassembly path is where per-satellite work tends to land.

Which branch to use, and what the GNU Radio version split costs

Version pinning is the operational reality of an out-of-tree module, and gr-satellites tracks GNU Radio releases explicitly. The current v5.x.y series supports GNU Radio 3.10 and is published from the maint-3.10 branch, while main is where the active development happens. Earlier lines were frozen on 2025-07-31, which ended support for GNU Radio 3.9 in the v4.x.y series and for GNU Radio 3.8 in the v3.x.y series.

The branch layout makes the compatibility mapping easy to read:

main
maint-3.10
maint-3.9
maint-3.8
maint-3.8-v2
maint-3.7

The v2.x.y and v1.x.y lines are closed to new changes. The v1.x.y series was the original, compatible with GNU Radio 3.7, and development stopped there in September 2019 when v2.x.y appeared, although some bugfix releases were published afterwards. The v3.x.y series came out of a large refactor that started in September 2019 and finished in May 2020, and that refactor is where most of the newer functionality came from. If your flowgraphs were written for 3.8 or 3.9, moving to v5 means moving to 3.10 as well, so the GNU Radio upgrade is part of the cost rather than a separate decision. The last push to the repository was on 2026-09-22, and the newest release is v5.9.0, published on 2025-12-14.

Installing gr-satellites and running a first flowgraph

Installing gr-satellites is not a one-line affair, and the project says so plainly. The README describes the installation procedure as roughly the usual of a GNU Radio out-of-tree module, and defers the details on required dependencies and on how to build and install to the project documentation hosted on readthedocs. A conda-forge package is also advertised, under this distribution name:

gnuradio-satellites

The first real use follows the out-of-tree pattern. Install GNU Radio 3.10 for the current release line, obtain the gr-satellites source for the branch that matches your GNU Radio version, build it, and then open one of the example flowgraphs from the examples tree in GNU Radio Companion. The signal chain worth verifying first is the one for the protocol your satellite actually uses, because the examples are split per satellite and per protocol rather than gathered into a single generic decoder flowgraph. The doppler_correction and time_dependent_delay folders are the two to look at when the frame output looks inconsistent, since a satellite pass does not sit still in the spectrum and a plain fixed-frequency decoder will show that.

The CCSDS layer as reusable building blocks

Above the satellite decoders sits a separate and more general layer: a collection of blocks covering several CCSDS blue books, covering the CCSDS TM and TC Space Datalink and SpacePacket. These were contributed by Athanasios Theocharis under ESA Summer of Code in Space 2019, and their documentation lives in a dedicated file at the root of the repository.

The layout supports the picture of a two layer project. Sources sit in include/, lib/ and python/, flowgraph definitions in grc/, command line tools in tools/, higher level applications in apps/, and tests plus a test.sh script at the top level. There is also a docs/ directory, a debian/ directory for packaging, and a satellite-recordings/ directory that points to recorded passes being kept for offline work.

The reuse argument is explicit in the project description: gr-satellites can serve as a set of building blocks to implement decoders for other satellites or other groundstation solutions, and some low level blocks suit other RF communications protocols. That is the case for embedding these blocks in your own pipeline instead of running the bundled tools end to end. The Space Datalink blocks are the pieces most likely to travel that way, since space links outlive any single amateur mission.

Where gr-satellites stops: coverage, policy and support

gr-satellites is not the right tool for every receiver, and the project is candid about the boundaries. Satellite coverage is decided per mission, and the description speaks of ad-hoc protocols for some satellites, which means the decoder set grows satellite by satellite rather than covering a class of spacecraft. A mission whose telemetry format is not included leaves you with hex frames and the job of interpreting them yourself.

Policy limits exist as well. A dedicated note describes how the project handles code contributions that add support for commercial satellite missions, and a separate note addresses satellite teams building groundstation solutions, with a specific caution for teams that will be using Amateur radio spectrum. Support runs through GitHub issues and GitHub discussions only, by choice, so that answers stay public instead of arriving over private channels such as email. The repository also carries an LLM usage policy, a changelog, a code of conduct and a contributing guide, and the LLM policy is the one to read before you contribute code.

Editorial conclusion

gr-satellites fits amateur ground stations that need working decoders for AX.25, AO-40, CCSDS or NanoCom payloads, and it fits engineers who want the demodulation and forward error correction blocks for their own pipeline. It does not fit commercial mission work, and it does not fit an operator who needs a decoder for a satellite the project has not covered, because the telemetry format definitions and the ad-hoc protocols are decided per mission. Before adopting it, check which GNU Radio version your current setup runs, confirm that your satellite and protocol appear in the examples tree, and read the two policy notes on commercial missions and on satellite teams. The last push was on 2026-09-22, and the current v5.x.y series targets GNU Radio 3.10.

Frequently asked questions

Official sources

1. daniestevez/gr-satellites on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases