Second alpha for gr-satellites 3

Following the first alpha, I have released today v3-alpha1, the second alpha for gr-satellites 3. As I introduced in September, gr-satellites 3 will be a large refactor of gr-satellites, bringing many UI and under-the-hood changes. I am releasing a series of alphas during the development to get feedback from users. Each of the alphas focuses on a different aspect.

The second alpha is focused on input and output formats. New functionality has been implemented to allow the user to choose the input and output in a flexible way. This post describes the main features added.

Running gr_satellites

There is an important change in the usage of the gr_satellites command line tool with respect to alpha0. The syntax for running gr_satellites is now

gr_satellites SATELLITE [additional arguments]

This means that the satellite needs to be specified first, by using either its name, its NORAD ID, or a path to a satellite YAML file, as explained in my post about alpha0.

The reason for this change is that now there are some arguments that depend on the satellite you choose. For example, if the satellite uses FSK, you will get arguments relevant for FSK demodulation, whereas if the satellite uses BPSK, you will get arguments relevant for BPSK demodulation.

In this way, if you just run

gr_satellites -h

you will get a brief summary of options which are applicable to all satellites. However, if you run

gr_satellites GOMX-3 -h

you will get all the options which can be used with GOMX-3.

Input formats

There are two new features regarding input formats in alpha1. The first is IQ input, which is enabled with the --iq argument. Until now, gr-satellites has used real input. This new option allows the use of IQ both with the UDP input and with the WAV file input.

There is an important semantics change when using IQ input with FSK and similar frequency modulation modes. When using real input, gr-satellites assumes that the input is already FM-demodulated (this is indicated in the gr-satellites README by saying “You must use FM mode to receive this satellite”). With IQ input, gr-satellites assumes that the input is not FM-demodulated (as it should be the case with a normal IQ recording), and performs FM demodulation.

For BPSK (which is now implemented in alpha1), there are slightly different semantics between IQ input and real input. For IQ input the signal is assumed to be centred at 0Hz, while for real input the signal is assumed to be centred at 1500Hz for baudrates smaller than 2400baud and at 12000Hz for baudrates larger than 2400baud (these are the well known “narrow SSB” and “wide SSB” modes from gr-satellites 1). This can be changed by using the --f_offset argument.

The second new feature is KISS input. Instead of using an input consisting of RF samples, it is also possible to use a file with frames in KISS format. This is useful to decode and show telemetry already recorded to a KISS file, or maybe to submit telemetry to a server from a KISS file. This option is enabled with the --kiss_in argument.

Output formats

The main focus for this alpha is on flexibility in output formats, which was one of my main goals for the gr-satellites refactor. Let us review the output options that are available in this alpha.

By default, gr_satellites will use as output the thing that makes more sense for the satellite selected. If a telemetry definition written in construct is available, the parsed frames will be printed to the standard output. If there is only partial information about the telemetry transmitted by the satellite (perhaps only the headers but not the payload format is known), this will be used to print the data. If there is no information at all, gr_satellites will resort to printing the packets in hex. The output can be redirected to a file instead by using the --telemetry_output argument.

Additionally, if the satellite transmits other data, such as images, gr_satellites will process this data by default (storing and displaying images, for example).

It is possible to switch to hexdump output instead, using the --hexdump parameters. This will print all the packets in hex to the standard output.

In addition to being printed to the screen, the decoded frames can be stored to a KISS file by using the --kiss_out parameters. The file is overwritten, unless --kiss_append is used.

Another kind of output that happens in background is submission to the telemetry servers. gr_satellites always tries to send telemetry to all the applicable servers. These are SatNOGS DB for all satellites, the FUNcube warehouse, for FUNcube satellites, and the PW-Sat2 server for PW-Sat2.

Information needed to submit to these servers is stored in the gr-satellites config file, which is a new appearance in this alpha. This file is located in ~/.gr_satellites/config.ini and its default contents are

[Groundstation]
callsign = 
latitude = 0
longitude = 0
submit_tlm = yes

[FUNcube]
site_id = 
auth_code = 

[PW-Sat2]
credentials_file = 

For submitting to SatNOGS DB it is necessary to fill in the [Groundstation] information. The submit_tlm parameter can be set to no if the user doesn’t want to submit telemetry, in which case gr_satellites will never submit to any of the servers. For submitting to the FUNcube warehouse it is necessary to fill in the credentials in the [FUNcube] section, while for submitting to PW-Sat2, it is necessary to enter the path to the credentials JSON file in the [PW-Sat2] section.

GRC blocks

Users in interested in building their own GNU Radio companion flowgraphs will find that most of the functionality added to the gr_satellites command line tool is also available as GRC blocks in the form of “components”.

There is now a new BPSK Demodulator in the demodulator components category. Also, the demodulators can be switched between real (float) and IQ (complex) input.

Regarding data source components, there is now the KISS File Source. This can be very useful, as it will read PDUs from a KISS file.

The data sinks included in this alpha are shown below.

The hexdump sink and KISS file sink are very simple sinks that take PDUs and will print them in hex format or save them to a KISS file respectively. The Telemetry Submit sink uses the gr-satellites config file located in ~/.gr_satellites/config.ini to get the user information and credentials.

The Telemetry Parser uses the concept of “telemetry definition”. This is either a construct object or some more complex class supporting the parse() method. The telemetry definition needs to be exported by the satellites.telemetry package (see here). Currently, there are only three telemetry definitions available: gomx_3, sat_1kuns_pf and ax_25, but more will be added in the future. In the Telemetry Parser block one should enter the name of the telemetry definition. For example, ax_25.

Next alpha

There are only four satellites supported in alpha1: 1KUNS-PF and GOMX-3, which were added in alpha0, and US01 and EntrySat, which have been added in alpha1 to test and demonstrate the FSK and BPSK AX.25 decoders.

The next alpha will focus on adding enough infrastructure to support all the satellites that are available in gr-satellites 2. This will probably cause some changes to the format of the satellite YAML files, which is the main reason why I have only written a few satellite YAML files so far (to avoid having to rewrite many files if I change the format).

Interested users will find that gr-satellites alpha1 has enough tools to decode any AX.25 satellite, and may want to try using the US01 (9k6 FSK) and EntrySat (9k6 BPSK) decoders with other AX.25 satellites, or adding new YAML files to support other baudrates.