Basic Usage

gr_satellites is the main entry point of gr-satellites: a command line tool that builds a complete decoder for one satellite and runs it on a live signal or a recording. This page explains how it parses its arguments, how the satellite is selected, how to get help, how default arguments from sat.cfg work, and what exit codes to expect.

Command Syntax

gr_satellites satellite <input source> [options]

satellite is mandatory and must be the first argument. It can be a name, a NORAD ID, or the path of a SatYAML file.
Exactly one input source option is required: --wavfile, --rawfile, --rawint16, --audio, --udp, --kiss_in or --sigmf (see Input Sources).
The remaining options depend on the satellite, because each demodulator, deframer and data sink adds its own options.

Running gr_satellites with no arguments prints the usage line to standard error and exits with status 1.

Why the Satellite Comes First

The set of valid options is not fixed. gr_satellites first loads the SatYAML file for the satellite in sys.argv[1], then asks each component used by that satellite to register its options (for example, only BPSK satellites get --f_offset and --costas_bw), and only then parses the rest of the command line. That is why:

gr_satellites --help does not print help. Since the first argument starts with -, the tool prints the usage line and exits with status 1.
gr_satellites FUNcube-1 --help prints the full help for FUNcube-1, including demodulation and deframing options.
An option valid for one satellite can be rejected for another (unrecognized arguments), unless you use --ignore_unknown_args.

The only exceptions are --version and --list_satellites, which also work without a satellite when they are the first argument.

Specifying the Satellite

The first argument is interpreted with these rules, in order:

Argument	Interpreted as	Example
Ends with `.yml` (case-insensitive)	Path to a SatYAML file	`gr_satellites ./my_sat.yml ...`
Only digits	NORAD ID	`gr_satellites 39444 ...`
Anything else	Satellite name or alternative name	`gr_satellites FUNcube-1 ...`

By name

Names are matched against the name and alternative_names of every bundled SatYAML file. Before comparing, both sides are case-folded and all punctuation and whitespace are removed, so FUNcube-1, funcube1 and FUNCUBE 1 are equivalent. Names that contain spaces must be quoted in the shell:

gr_satellites "Reaktor Hello World" --wavfile reaktor_hello_world.wav

By NORAD ID

gr_satellites 39444 --wavfile ao73.wav

NORAD IDs are convenient when another program (a scheduler or a tracking tool) passes the satellite to gr_satellites.

By SatYAML file

gr_satellites python/satyaml/AO-73.yml --wavfile ao73.wav

Use a path when you have edited a copy of a bundled file or written your own (see SatYAML Format).

Note: Only the .yml extension is recognized. A file named my_sat.yaml is treated as a satellite name and fails with Satellite my_sat.yaml not found.

Errors

Situation	Message	Exit status
Name or NORAD ID not found	`Satellite <arg> not found`	1
`.yml` file cannot be opened	`Could not open SatYAML file:` followed by the OS error	1

If two bundled files share a name or NORAD ID, the first file found by a directory glob wins. The glob order is not sorted, so do not rely on it.

Getting Help

gr_satellites FUNcube-1 --help

The help is grouped into sections:

Group	Contents
(general)	`-h/--help`, `--version`, `--list_satellites`, `--ignore_unknown_args`, `--satcfg`
`input`	Input sources, `--samp_rate`, `--udp_port`, `--udp_ipv4_only`, `--iq`, `--udp_raw`, `--input_gain`, `--start_time`, `--throttle`
`output`	`--kiss_out`, `--kiss_append`, `--kiss_server`, `--kiss_server_address`, `--zmq_pub`, `--hexdump`, `--dump_path`
`demodulation`	Options of the demodulators used by this satellite
`deframing`	Options of the deframers used by this satellite
`data sink`	Options of the data sinks, such as `--telemetry_output` or `--file_output_path`

The help printed by the version on main is more accurate than older copies of the upstream documentation; for example the current Manchester option is --manchester_block_size and the default --clk_limit is 0.004.

Listing Satellites

gr_satellites --list_satellites

Prints every bundled satellite sorted by name (case-insensitive), with its NORAD ID and, for each transmitter, the frequency in MHz, the modulation and the framing. This reads every SatYAML file, so it takes a moment.

Abbreviated Options

gr_satellites uses Python's argparse with abbreviations enabled, so any unambiguous prefix of a long option works. The repository's own test.sh uses --wav for --wavfile. Two options are exceptions because the tool also looks for them as exact strings before parsing:

--satcfg must be spelled out in full to load sat.cfg.
--ignore_unknown_args must be spelled out in full to switch to lenient parsing.

An abbreviation of these is accepted by the parser but has no effect.

Ignoring Unknown Arguments

gr_satellites 39444 --wavfile ao73.wav --deviation 3000 --ignore_unknown_args

With --ignore_unknown_args, options that the selected satellite does not define are not fatal. They are reported on standard error:

Warning: unknown arguments passed ['--deviation', '3000']

This is useful in scripts that call gr_satellites with the same options for many satellites, for example --f_offset (BPSK only) or --use_agc (FSK only). Note that a value-taking option is split into two "unknown" items as shown above.

Default Arguments from sat.cfg

With --satcfg, gr_satellites reads ~/.gr_satellites/sat.cfg and inserts the arguments configured for the selected satellite's NORAD ID before the arguments you typed:

39444 --f_offset 12000
46276 --disable_dc_block --deviation 500 --clk_bw 0.15
35933 --clk_bw 0.3

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

Because the file's arguments come first, an option you type on the command line overrides the same option from sat.cfg (argparse keeps the last value). The format and its limitations are described in Configuration.

Running and Stopping

When the input is a file (--wavfile, --rawfile, --rawint16, --kiss_in, --sigmf), gr_satellites normally exits once the file has been read. File inputs are processed as fast as the CPU allows unless you add --throttle. Live inputs (--audio, --udp) run until interrupted.

SIGINT (Ctrl+C) and SIGTERM are handled: the flowgraph is stopped, buffered data is flushed and the tool exits with status 0.

Exit Codes

Status	When
`0`	Normal end of a file, `--version`, `--list_satellites`, `--help`, or SIGINT/SIGTERM.
`1`	No arguments or first argument starting with `-`; satellite not found; SatYAML file not openable; `--samp_rate` missing (`Need to specify --samp_rate unless --wavfile or --kiss_in or --sigmf is used`); SigMF errors.
`2`	argparse errors: missing input source, two input sources, unknown option, invalid value.

Exceptions raised while building the flowgraph (for example a broken custom SatYAML file) end with a Python traceback and status 1.