Satellite Decoder Block

The Satellite decoder block brings the decoder built by gr_satellites into GNU Radio Companion (GRC). You feed it samples from any GNU Radio source and get decoded frames out as PDUs, which you can process however you like. This page explains its parameters, what it does and does not include compared with the command line tool, how to pass options, and some design patterns.

It is found under Satellites > Core > Satellite decoder. An example flowgraph is in examples/satellite_decoder/satellite_decoder.grc: a WAV File Source feeds the decoder, and a Message Debug block prints the frames.

Parameters

Parameter Type Default Meaning
Satellite definition enum Satellite name How to choose the satellite: Satellite name, NORAD ID or YAML file.
Satellite name string Name or alternative name (shown when the definition is Satellite name). Matching ignores case, spaces and punctuation.
NORAD ID int 0 NORAD ID (shown for NORAD ID).
File file SatYAML file path (shown for YAML file).
Sample Rate float samp_rate Sample rate of the input stream.
IQ input bool False Complex (IQ) input when true, float (real) input otherwise.
Command line options string "" Options in gr_satellites syntax, as a Python string expression.

The input port is a stream of float or complex depending on IQ input, with the same semantics as the command line tool (see Real or IQ Input). The output is a message port out with one PDU per decoded frame.

The generated Python code is:

satellites.core.gr_satellites_flowgraph(
    name='FUNcube-1', samp_rate=samp_rate, grc_block=True, iq=False,
    options="")

What the Block Includes

With grc_block=True, the block builds only the receive chain: for each transmitter in the SatYAML file, a demodulator and a deframer, plus a tagger that adds the transmitter name to the PDU metadata (key transmitter). All transmitters run in parallel and their frames are merged on the out port.

It does not include:

  • data sinks (telemetry parsing, file and image receivers, Codec2 output),
  • transports (KISS extraction and similar),
  • KISS output, KISS server, ZMQ, hex dump, telemetry submission,
  • the additional_data outputs (for example LilacSat-1's Codec2 port).

Add the corresponding data sink and transport blocks yourself after the decoder. For a satellite like LilacSat-1, whose telemetry and images are inside a KISS stream, connect the decoder to a KISS Transport block (with Expect control byte set to False), and the transport to the Telemetry Parser and Image Receiver blocks. The examples/components/image_receiver.grc flowgraph does exactly that.

Command Line Options

The Command line options parameter takes the same syntax as gr_satellites, written as a Python string:

"--clk_bw 0.1 --syncword_threshold 2"

The string is split with shlex.split() and parsed with a parser that contains only the demodulation, deframing and data sink option groups for the chosen satellite. Input and output options such as --wavfile, --iq, --kiss_out or --hexdump are not accepted here; use block parameters and other blocks instead.

To see the available options, set the parameter to "--help" and run the flowgraph: it prints the help for the satellite and stops. If the options are invalid, it prints the usage and stops when the flowgraph is started. The program name in these messages is gr_satellites_flowgraph.

Usage Ideas

  • Any SDR or file format. Use the standard GNU Radio sources (SDR hardware blocks, File Source, UDP Source) instead of the fixed set of inputs of the command line tool.
  • Channelize a wideband receiver. Use Frequency Xlating FIR Filter blocks to cut several narrow channels out of one wideband stream, each feeding its own Satellite decoder. Combine with Doppler correction (for example from the separate gr-gpredict-doppler project, or gr-satellites' own Doppler Correction block).
  • Custom handling of frames. Filter frames by transmitter using the metadata, store them, forward them over TCP or ZeroMQ with standard GNU Radio blocks, or implement upper-layer protocols in the flowgraph.

Differences from the Command Line Tool

Aspect gr_satellites Satellite decoder block
Input Built-in sources Any GNU Radio source
Input gain, throttle --input_gain, --throttle Use Multiply Const and Throttle blocks
Data sinks and transports Built automatically from SatYAML Add blocks yourself
Telemetry submission From config.ini / env var Add Telemetry Submit blocks
--satcfg, --ignore_unknown_args Supported Not available
Output stdout, files, sockets PDUs on out

See Also