gr_satellites command line tool¶
gr_satellites command line tool is a complete solution that can decode
frames using either real-time RF samples from an SDR or conventional radio, or a
gr_satellites can be run from a terminal after gr-satellites has been
installed. If run without any arguments,
gr_satellites will only print some
basic information about the arguments it allows.
$ gr_satellites usage: gr_satellites satellite [-h] [--version] [--list_satellites] [--ignore_unknown_args] (--wavfile WAVFILE | --rawfile RAWFILE | --rawint16 RAWINT16 | --audio [DEVICE] | --udp | --kiss_in KISS_IN) [--samp_rate SAMP_RATE] [--udp_ip UDP_IP] [--udp_port UDP_PORT] [--iq] [--udp_raw] [--input_gain INPUT_GAIN] [--start_time START_TIME] [--throttle] [--kiss_out KISS_OUT] [--kiss_append] [--kiss_server [PORT]] [--kiss_server_address KISS_SERVER_ADDRESS] [--zmq_pub [ADDRESS]] [--hexdump] [--dump_path DUMP_PATH]
Specifying the satellite¶
The arguments that
gr_satellites allows depend on the satellite that has
been selected. Therefore, to use
gr_satellites it is always necessary to
satellite to be used as an argument immediately following
gr_satellites. There are three different ways to specify the satellite:
Using the satellite name, such as FUNcube-1 or LilacSat-2. This can be used with any satellite officially supported by gr-satellites, and it is the most simple way of specifying a satellite.
$ gr_satellites FUNcube-1
A satellite may have several different names, known as alternative names. For example, FUNcube-1 is both known as AO-73 and FUNcube-1.
Using the satellite NORAD ID. This can bue used with any satellite officially supported by gr-satellites, and it can be useful when interfacing
gr_satelliteswith other tools that use NORAD IDs to classify satellites.
Below we show
gr_satellitesrunning with NORAD ID 39444, which corresponds to FUNcube-1.
$ gr_satellites 39444
Using a path to an
.ymlSatYAML file. SatYAML files are used by gr-satellites to specify the decoding parameters and configuration corresponding to each different satellite. They are described in more detail in the SatYAML files section.
gr-satellites comes bundled with a large number of SatYAML files corresponding to all the officially supported satellites. They can be found in the
Specifying the path of a SatYAML file is useful if the user has modified some of the files bundled with gr-satellites or has created their own ones.
$ gr_satellites python/satyaml/AO-73.yml
Specifying the input source¶
Besides specifying the satellite to use for decoding, it is mandatory to specify the input source by using exactly one of the following options:
--wavfilecan be used to read a recording in WAV/OGG/FLAC format. This uses libsndfile through the GNU Radio WAV File Source block, so any format supported by libsndfile can be used. The sample rate is obtained from the file header, but it can be overriden using the the
--samp_rateargument if necessary.
By default, the WAV/OGG/FLAC file is interpreted as a one-channel file containing real RF samples. To read a two-channel file containing IQ RF samples, the
--iqargument needs to be specified.
All the sample recordings in the
satellite-recordings/are real 48kHz WAV files and can be read with the
--wavfile file --samp_rate 48e3arguments.
For example, this will decode some frames from FUNcube-1:
$ gr_satellites FUNcube-1 --wavfile satellite-recordings/ao73.wav
--rawfilecan be used to read a recording in
float32format (depending on whether the
--iqargument is used or not). The sample rate of the recording needs to be specified with the
complex64format contain a sequence of 32-bit floating point numbers in IEEE 754 format. The sequence alternates between the I (in-phase) and Q (quadrature) componentes of a stream of IQ samples. This format is used by the GNU Radio File Source and File Sink blocks when their type is set to complex.
float32format contain a sequence of 32-bit floating point numbers in IEEE 754 format. The sequence contains the elements of a stream of real samples. This format is used by the GNU Radio File Source and File Sink blocks when their type is set to float.
--rawint16can be used to read a recording in
int16format. The file is interpreted as IQ or real data according as to whether the
--iqargument is used or not. The sample rate of the recording needs to be specified with the
int16format contain a sequence of 16-bit integers in host endianness. This format is used by GNU Radio File Source and File Sink blocks when their type is set to short.
--audiocan be used to read samples from the soundcard, using GNU Radio’s Audio Source. This can be used to receive audio from a conventional radio by using the soundcard or from another application via a “virtual audio cable”.
The sample rate to use needs to be specified with the
--samp_rateargument. A sample rate of 48000 is typical with audio devices.
Both real samples (by default) and IQ samples (using the
--iqargument) are supported. IQ samples use two audio channels (stereo).
--audioargument can optionally be followed by the name of the audio device to use. Details about how to specify the device name vary between plaform and are described in the Audio Source documentation. If no device name is entered, the default audio device will be chosen.
--udpcan be used to received RF samples streamed in real-time. The sample rate of the recording needs to be specified with the
The streaming format is the same as for the
--rawint16and both real samples (by default) and IQ samples (using the
--iqargument) are supported. If the
--udp_rawis used the format will be the same as for
gr_satelliteswill listen on the IP address
::(all addresses) and the UDP port 7355. A different IP address or port can be specified using the parameters
$ gr_satellites FUNcube-1 --udp --samp_rate 48e3
This is recommended as a simple way of interfacing
gr_satelliteswith SDR hardware for beginner users.
It is also possible to use the example GNU Radio companion flographs in gr-frontends to stream samples by UDP from different sources.
For more advanced users,
nccan also be a very useful tool for streaming.
--kiss_incan be used to process a file containing already decoded frames in KISS format. All the demodulation steps are skipped and only telemetry parsing, file receiving, etc. are done.
This can be useful to view the telemetry stored in files previously decoded with gr-satellites or other software.
gr_satellites prints a detailed description of all the allowed arguments by
--help argument. Note that a satellite needs to be
specified, since the set of allowed arguments depends on the decoders used by
For example, this shows all the options allowed by the FUNcube-1 decoder:
$ gr_satellites FUNcube-1 --help usage: gr_satellites satellite [-h] [--version] [--list_satellites] (--wavfile WAVFILE | --rawfile RAWFILE | --rawint16 RAWINT16 | --audio [DEVICE] | --udp | --kiss_in KISS_IN) [--samp_rate SAMP_RATE] [--udp_ip UDP_IP] [--udp_port UDP_PORT] [--iq] [--input_gain INPUT_GAIN] [--start_time START_TIME] [--throttle] [--kiss_out KISS_OUT] [--kiss_append] [--kiss_server [PORT]] [--kiss_server_address KISS_SERVER_ADDRESS] [--zmq_pub [ADDRESS]] [--hexdump] [--dump_path DUMP_PATH] [--telemetry_output TELEMETRY_OUTPUT] [--f_offset F_OFFSET] [--rrc_alpha RRC_ALPHA] [--disable_fll] [--fll_bw FLL_BW] [--clk_bw CLK_BW] [--clk_limit CLK_LIMIT] [--costas_bw COSTAS_BW] [--manchester_history MANCHESTER_HISTORY] [--syncword_threshold SYNCWORD_THRESHOLD] [--verbose_rs] gr-satellites - GNU Radio decoders for Amateur satellites optional arguments: -h, --help show this help message and exit --version show program's version number and exit --list_satellites list supported satellites and exit --ignore_unknown_args Treat unknown arguments as warning input: --wavfile WAVFILE WAV/OGG/FLAC input file (using libsndfile) --rawfile RAWFILE RAW input file (float32 or complex64) --rawint16 RAWINT16 RAW input file (int16) --audio [DEVICE] Soundcard device input --udp Use UDP input --kiss_in KISS_IN KISS input file --samp_rate SAMP_RATE Sample rate (Hz) --udp_ip UDP_IP UDP input listen IP [default='::'] --udp_port UDP_PORT UDP input listen port [default='7355'] --iq Use IQ input --input_gain INPUT_GAIN Input gain (can be negative to invert signal) [default=1] --start_time START_TIME Recording start timestamp --throttle Throttle recording input to 1x speed output: --kiss_out KISS_OUT KISS output file --kiss_append Append to KISS output file --kiss_server [PORT] Enable KISS server [default port=8100] --kiss_server_address KISS_SERVER_ADDRESS KISS server bind address [default='127.0.0.1'] --zmq_pub [ADDRESS] Enable ZMQ PUB socket [default address=tcp://127.0.0.1:5555] --hexdump Hexdump instead of telemetry parse --dump_path DUMP_PATH Path to dump internal signals demodulation: --f_offset F_OFFSET Frequency offset (Hz) [default=1500 or 12000] --rrc_alpha RRC_ALPHA RRC roll-off (Hz) [default=0.35] --disable_fll Disable FLL --fll_bw FLL_BW FLL bandwidth (Hz) [default=25] --clk_bw CLK_BW Clock recovery bandwidth (relative to baudrate) [default=0.06] --clk_limit CLK_LIMIT Clock recovery limit (relative to baudrate) [default=0.02] --costas_bw COSTAS_BW Costas loop bandwidth (Hz) [default=50] --manchester_history MANCHESTER_HISTORY Manchester recovery history (symbols) [default=32] deframing: --syncword_threshold SYNCWORD_THRESHOLD Syncword bit errors [default=8] --verbose_rs Verbose RS decoder data sink: --telemetry_output TELEMETRY_OUTPUT Telemetry output file [default=stdout] The satellite parameter can be specified using name, NORAD ID or path to YAML file
gr_satellites will “do its best” to show the user the output
for the decoded frames. If the telemetry format for the satellite is implemented
in gr-satellites, the telemetry frames will be printed to the standard output in
human-readable format. Otherwise, the raw frames will be printed out in hex
format to the standard output.
File decoding, image decoding and other special output options of some particular satellites are enabled by default.
Customization of the ouput options is described in the Ouput options subsection below.
This subsection explains in detail the different output options that can be used
gr_satellites command line tool. The default behaviour when no
options are specified has been described in the Output subsection above.
By using the option
--hexdump, it is possible to make
print the received frames in hexadecimal format, regardless of whether there is
a telemetry decoder available or not. The format used to print the frames is the
same as used by the GNU Radio block Message Debug
An example of the use of this option can be seen here:
$ gr_satellites FUNcube-1 --wavfile ~/gr-satellites/satellite-recordings/ao73.wav \ --hexdump * MESSAGE DEBUG PRINT PDU VERBOSE * () 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 0020: 5c 8f 34 23 f3 ba 0b 5d 62 74 51 c7 ea fa 69 4a 0030: 9a 9f 00 09 ef a0 1f f4 a7 ea 4a c6 8f 11 40 11 0040: 1e 10 f7 01 3e 20 64 00 d7 8b f8 d7 94 c8 93 a8 0050: 2a da 52 a6 0e 58 0e c8 0f 4e 01 1d 20 5a 00 db 0060: 94 a8 aa 8a 98 13 ac 69 0a a6 a8 10 e6 10 92 0f 0070: b8 01 50 20 64 00 d7 96 a8 c1 8b 48 25 ab a9 ca 0080: ce 9d 10 76 0f c9 10 55 01 3a 20 5a 00 d7 97 29 0090: 08 8c 48 4f a9 6a 5a f2 a4 10 39 0f 7b 0f 86 01 00a0: 49 20 64 00 d7 94 08 d0 8a d8 2a ad 6a 5a 7e b4 00b0: 0e 53 0e 9b 0e b7 01 09 20 5a 00 db 99 a8 f2 8f 00c0: e8 38 af aa 8a c2 9e 0e de 0f 48 0e 31 01 31 20 00d0: 5a 00 ce 9b c8 ff 88 68 1b b2 6a 5a ca a7 0f c3 00e0: 0e 74 0e 58 01 34 20 5a 00 d7 9b 39 1b 97 b8 c5 00f0: b0 2b 3a d6 b5 01 6b 00 6a 02 9e 00 03 20 13 00 ***********************************
Decoded frames can be saved to a file in KISS format. This is a simple format that serves to delimit frames stored in a file or sent over a serial bus, and it is frequently used to store telemetry frames.
To enable KISS output, the
--kiss_out parameter followed by the path of the
output file should be used. By default
gr_satellites will overwrite the
file if it already exists. To append to the file instead, the option
--kiss_append can be used in addition to the
option. Appending can be used to concatenate frames obtained in several decoding
Files in KISS format can be read with
gr_satellites as indicated above or
with other software tools.
KISS files produced with
gr_satellites use an extension proposed by Mike
Rupprecht to store the reception timestamp of the frames. Before each
data frame, a KISS control frame using the control byte
0x09 and storing
a timestamp with UNIX timestamp in milliseconds stored as a big-endian 64 bit
integer is included in the file.
Some software, including the decoders by Mike Rupprecht, will be able to read and use these timestamps. Other software that processes KISS will ignore the timestamps.
A KISS TCP server can be enabled with the
optionally followed by the TCP port to listen on (by default port 8100 is
used). This allows other applications to connect to
receive decoded frames using the KISS protocol.
By default the KISS server will only bind on
127.0.0.1 and listen to
requests from localhost only. If access from other computers on the network is
--kiss_server_address parameter can be used to specify the
address to bind to. For instace, if
--kiss_server_address '' or
--kiss_server_address 0.0.0.0 is used, the server will bind to 0.0.0.0 and
listen to requests from all addresses.
ZMQ PUB socket¶
Decoded frames can also be sent to other applications by using a ZeroMQ PUB socket. Several applications can connect to the PUB socket using SUB sockets. The frames are sent using the ZMQ PUB Message Sink GNU Radio block, and can be received using the ZMQ SUB Message Source GNU Radio block.
The ZMQ PUB socket is enabled using the
--zmq_pub parameter, optionally
followed by the socket endpoint to use. By default, the endpoint
tcp://127.0.0.1:5555 is used. This means that the ZMQ PUB socket will only
listen to connections from localhost. If desired, the endpoint
can be used to listen on all addresses.
For satellites supporting telemetry parsing,
gr_satellites will default to
printing the decoded telemetry values to the standard output. It is possible to
write these messages to a file instead by using the
parameter followed by the path of the output file.
Dump internal signals¶
For advanced users and developers, the demodulators used in
can dump the internal signals used inside the demodulator. This option can be
enabled by using the
--dump_path parameter followed by a path to the
directory where the different files are created. It is recommended to use this
option with a short recording, to avoid creating very large files. The details
of each of these files are best studied in the Python source code of the
The following example show how to use
--dump_path to plot the symbols with
Numpy and Matplotlib and optimize the decoding parameters for a particular
recording. We first run the following to dump to the path
internal signals produced by decoding a sample recording of AU02.
$ mkdir -p /tmp/fsk $ gr_satellites AU02 --wavfile satellite-recordings/au02.wav \ --dump_path /tmp/fsk
We see that we do not get any decoded packets. Then, we can plot the FSK symbols with the following Python code:
import numpy as np import matplotlib.pyplot as plt x = np.fromfile('/tmp/fsk/clock_recovery_out.f32', dtype = 'float32') plt.plot(x, '.') plt.show()
This produces the figure below, which shows that there has been a clock cycle slip mid packet, which prevents correct decoding.
We can run
gr_satellites again adding the parameter
--clk_bw 0.1 to
increase the clock recovery loop bandwidth. With this parameter we get a
successful decode and if we plot the FSK symbols again, we get the figure below,
which shows that the clock recovery is working much better than before.
gr_satellites command line tool can be used to submit decoded telemetry
to an online database server, such as SatNOGS DB and these others servers used by
certain satellite projects:
- FUNcube Warehouse, which is used by the FUNcube payloads on FUNcube-1, UKube-1, Nayif-1 and JY1Sat.
- PW-Sat2 Groundstation, which is used by PW-Sat2.
- The BME telemetry server, which is used by SMOG-P, ATL-1 and SMOG-1.
- Harbin Institute of Technology, which connects to the telemetry proxy included in gr-lilacsat and gr-dslwp.
- Any custom server using the SIDS protocol. The SIDS protocol is an HTTP-based protocol that was first developed by the ESTCube team and later used by the UWE-3 team. It is the basis of the SatNOGS DB server and other telemetry servers.
To enable telemetry submission, it is necessary to edit some parameters in
gr_satellites’s config file, which is located in
~/.gr_satellites/config.ini. If this file does not exist, it will be created
with a template when
gr_satellites is first run. The template looks like
To enable telemetry submission, the
submit_tlm parameter must be set to
yes. Additionally, the receiving stations
callsign as well as its
longitude) need to be set, since some of the
servers need these parameters. Once this is done, telemetry submission to
SatNOGS DB will be enabled for all satellites.
To enable telemetry submission to the FUNcube warehouse, it is necessary to fill
auth_code. These can be obtained by
registering in the warehouse.
To enable telemetry submission to the PW-Sat2 server, it is necessary to enter
the path to the credentials file in the
credentials_file parameter. This
file is a JSON file that is generated and downloaded in the
“Your credentials” section of the server web interface. It is necessary to
have an account registered in the server to obtain the credentials file.
To enable telemetry submission to the BME server, it is necessary to
register an account in the BME server. The user and password should be
entered into the gr-satellites
To use the Harbin Institute of Technology proxy to submit telemetry, the proxy
needs to be run and started in the local computer before running
gr_satellites. The command line tool will connect to the correct port where
the proxy is listening (this is specified in the SatYAML file of each
satellite). All the configuration regarding the station and the operator is done
in the proxy itself. When
gr_satellites starts, it will attempt to connect
to the proxy, and print a warning if unable (in which case telemetry submission
through the proxy is disabled for this run).
The Harbin Institute of Technology proxy is a Python2 application that uses
PyQt4. Users having more modern sytems may find useful the PyQt5 version that
can be found in the pyqt5 branch of gr-lilacsat. This requires
4.5.3. It will not work with more recent versions of
No special configuration needs to be done to enable submission to custom SIDS servers, since these use the same protocol and configuration as SatNOGS DB.
For some telemetry servers, including SatNOGS DB, the frames are submitted
together with a timestamp of reception. This timestamp is taken from the
computer’s clock by
gr_satellites at the moment when it decodes the
frame. This means that, in order to use telemetry submission appropriately, the
computer’s clock should be set accurately and a live signal rather than a
recording should be decoded.
File and image receiver¶
Some satellites transmit files (especially image files) by splitting the files
into many telemetry packets. The
gr_satellites decoder supports reassembling
and storing these files into a directory. Additionally, image files are automatically
displayed in real time as they are being received, using feh.
Currently the satellites that have decoders supporting file reception are ATL-1 and SMOG-P (they transmit RF spectrum data), and the satellites that have decoders supporting image reception are 1KUNS-PF, BY70-1, D-SAT, LilacSat-1, Lucky-7 and Światowid.
For satellites supporting file reception, the
can be used to set the directory that is used to store received files. The
filenames of the received files will be automatically created using metadata or
a counter (if no metadata is transmitted). By default, received files are stored
--verbose_file_receiver parameter can be used to enable additional
debugging information about the functionality of the file receiver.
This subsection deals with other topics which are relevant to the usage of
Real or IQ input¶
gr_satellites command line tool supports both real (one-channel) input
and IQ input (which consists of two channels: in-phase and quadrature). A
detailed description of these two ways to represent a signal is out of the scope
of this document. This subsection gives some practical advice regarding the
difference between real and IQ input.
gr_satellites will assume that its input is real. To use IQ
--iq option must be used.
When using the audio output of either a conventional radio or an SDR software
performing SSB or FM demodulation,
gr_satellites should be used with the
real input option. Likewise, recordings produced from this kind of audio output, such
as one-channel WAV recordings should also be used with the real input option.
However, most SDR softwares will also have an option to save raw samples to a
file. These files are almost always IQ, and can be either a two-channel WAV file
or a file in raw format. The IQ input option must be used when using
gr_satellites to read these files. Additionally, some
SDR software may support streaming IQ data by UDP. This can also be used in
gr_satellites with the IQ input option.
FSK demodulation and IQ input¶
When using an AFSK or FSK demodulator, the usage of the
--iq option has an
additional effect. Since (A)FSK is a mode based on frequency modulation, it is
common to use either a conventional FM radio or an SDR software performing FM
demodulation to receive (A)FSK. Audio recordings obtained in this manner are also
common. Therefore, when
gr_satellites is run without the
--iq signal, it
will expect that (A)FSK signals have already been FM-demodulated in this way.
--iq option is used,
gr_satellites expects an (A)FSK signal that
has not been FM-demodulated, and so it will perform FM-demodulation first. This
is the kind of procedure that should be employed with inputs such as raw IQ
recordings of an SDR, since the (A)FSK signals present in this kind of recordings
have not been FM-demodulated.
The output of the radio or SDR software when running in FM mode to
receive an FSK signal is actually an NRZ signal. Therefore, when
gr_satellites is run without the
--iq option, it will expect an NRZ
signal instead of an FSK signal. When
gr_satellites is run with the
option, it will expect an FSK signal.
Similarly, the output of the radio or SDR software when running in FM mode to
receive an AFSK signal is actually an audio-frequency FSK signal. Therefore,
gr_satellites is run without the
--iq option, it will expect an
audio-frequency FSK signal instead of an AFSK signal. When
is run with the
--iq option, it will expect an AFSK signal.
Note that this behaviour is what the user wants in most cases, but it also
means that it is not possible to run
gr_satellites directly on an (A)FSK signal which
is represented in intermediate frequency as a real signal.
Frequency offsets for BPSK¶
A usual way of receiving a BPSK signal is to use either a conventional radio or an SDR software in SSB mode (USB mode, normally) and tune the BPSK signal in the middle of the audio passband. Audio recordings obtained in this manner are also common.
The SSB filter of a conventional radio is often approximately 3kHz wide. For this reason, only BPSK signals with a baudrate of 2400 baud or lower can be received with a conventional SSB radio. For BPSK signals with larger baudrate, an SDR receiver should be used.
gr_satellites command line tool needs to know the frequency at which the
BPSK signal is tuned within the audio passband. If necessary, this can be specified with the
--f_offset parameter, followed by the frequency in Hz. There are the
- For signals with a baudrate of 2400 baud or less, a frequency offset of 1500 Hz is used. This follows the common practice of using a regular 3kHz SSB bandwidth and tuning the signal in the middle of the passband.
- For signals with a baudrate larger than 2400, a frequency offset of 12000 Hz is used. The rationale is that, for best results, a passband of 24000 Hz should be used, since this is the largest that fits in a 48kHz audio signal, and the signal should be tuned in the middle of this 24000 Hz passband. This kind of usage is sometimes called “wide SSB mode”.
These settings only apply for a real input. When
gr_satellites is used with
IQ input, the default is to expect the BPSK signal tuned at 0Hz (i.e., at
baseband). A different frequency can still be selected with the
FSK signal polarity¶
A conventional FM radio, or even an SDR software running in FM mode might invert the polarity of the output signal, since the polarity is not relevant for audio signals. However, the polarity is relevant when receiving an FSK signal that does not use differential coding.
An input with the inverted polarity will cause decoding to fail. In this case,
the input can be inverted again by using the
--input_gain -1 parameter,
which has the effect of multiplying the input signal by -1 before it is
processed, thus restoring the correct polarity.
Some satellites have multiple transmitters (or different types of signals)
declared in their SatYAML files. When run for these satellites,
gr_satellites command line tool will run decoders for all the
transmitters or signal types in parallel. Therefore, it is not necessary or
possible to specify the transmitter to use.
In the case when it is necessary to run only the decoder for a single
transmitter, the easiest solution is to make a copy of the SatYAML file for that
satellite, edit the copy to leave out only the desired transmitter, and then
gr_satellites and indicating it to use the modified SatYAML file.
Getting correct timestamps with recordings¶
One of the difficulties with working with recordings is obtaining correct
timestamps for each of the decoded packets. These timestamps are included in
KISS files and telemetry submissions to some servers, such as SatNOGS DB. To
produced correct timestamps
gr_satellites will play back the recording at 1x
speed and count the clock time elapsed since the beginning of the execution, it
will then add that time to a timestamp specified by the user, which should
correspond to the start of the recording.
To use this functionality it is necessary to use the
--throttle parameter to
limit playback speed to 1x and use the
--start_time parameter followed by the
timestamp in ISO 8601 format (
YYYY-MM-DDTHH:MM:SS) to indicate the start time
of the recording.
Treating unknown args as warning¶
Using the argument
--ignore_unknown_args will change the behaviour on unknown
arguments to a warning instead of exiting with an error. This can be useful when
running in automated scripts and some options may not be available on that satellite.
For example the