First alpha for gr-satellites 3

In my last post, I introduced my plans to do a large refactor of gr-satellites, which when ready will originate a version 3.0.0 running on GNU Radio 3.8. During the development of this refactor, I intend to release alpha versions showing important new concepts or functionalities. The main goal of this is both to test if my ideas work well in practice and that interested people can start testing the new software and give feedback.

I have now published the first alpha release, which is called v3-alpha0. In this post I describe the functionality implemented in this alpha and how to use the software.

Satellite YAML files

One of the main changes in gr-satellites 3 is that each satellite will no longer have its own GNU Radio companion flowgraph in the apps folder. Instead, each satellite will have a YAML file describing several parameters of the satellite, modulation and protocols used, and the flowgraph will be generated dynamically using the information in that file.

Satellite YAML files live in the python/satyaml folder and get installed with the rest of the Python files comprising the satellites Python module. The alpha release only has YAML files for two satellites: 1KUNS-PF and GOMX-3. This is enough to showcase the basic structure of these files and to test the rest of the software in the alpha.

This is what a satellite YAML file looks like:

name: 1KUNS-PF
alternative_names:
norad: 43466
data:
  &tlm Telemetry:
    decoder: sat_1kuns_pf_telemetry_parser
  &image JPEG Images:
    decoder: sat_1kuns_pf_image_decoder
transmitters:
  1k2 FSK downlink:
    frequency: 437.300e+6
    modulation: FSK
    baudrate: 1200
    framing: AX100 ASM+Golay
    data:
    - *tlm
    - *image
  9k6 FSK downlink:
    frequency: 437.300e+6
    modulation: FSK
    baudrate: 9600
    framing: AX100 ASM+Golay
    data:
    - *tlm
    - *image

The name and norad fields can be used to search for a satellite matching a particular name or NORAD ID, or when submitting telemetry to SatNOGS DB, which uses the NORAD ID to identify each satellite. The alternative_names field can be empty or absent, but can also list additional names to match the satellites (think AO-73 and FUNcube-1).

The data section lists the different types of data (understood in a general sense) that the satellite transmits. So far, only an appropriate decoder (if available) is listed for each type of data, but more details will probably be added to this section in the future.

The transmitters section lists each of the different transmitters, modulations or signals used by the satellite. Each comes with a frequency and baudrate, a modulation (which identifies the demodulator component to be used), a framing (which identifies the deframer component to be used), and a list of the different data types transmitted by the signal.

Command line tool

It is expected that most end users will use gr-satellites through the gr_satellites command line tool, which is a Python executable. This tool is a command line application that allows the user to choose different parameters for the decoding. The help gives an idea of what functionality is available in the current version:

$ gr_satellites -h
 usage: gr_satellites [-h] [--wavfile WAVFILE] --samp_rate SAMP_RATE
                      [--udp [UDP]] [--udp_ip UDP_IP] [--udp_port UDP_PORT]
                      satellite
 gr-satellites - GNU Radio decoders for Amateur satellites
 positional arguments:
   satellite             Satellite description (name, NORAD ID or YAML file)
 optional arguments:
   -h, --help            show this help message and exit
   --wavfile WAVFILE     WAV input file
   --samp_rate SAMP_RATE
                         Sample rate (Hz)
   --udp [UDP]           Use UDP input
   --udp_ip UDP_IP       UDP input listen IP [default='::']
   --udp_port UDP_PORT   UDP input listen port [default='7355']

The main argument is the satellite to use for decoding. This can be specified in three ways:

• As a path to a YAML file anywhere in the filesystem. This allows the user to customize their own satellite YAML files or get them from someone else’s.
• As a satellite name, which is searched in the YAML files bundled with gr-satellites
• As a NORAD ID, which is searched in the YAML files bundled with gr-satellites

The satellite parameter is interpreted automatically depending on its format (path to YAML file if it ends with .yml, NORAD ID if it is a number, satellite name in other cases).

This version support two different input sources: UDP realtime samples (as in the current versions of gr-satellites) and a WAV recording, which is processed as fast as possible. The format for the UDP samples is the same as in the current versions of gr-satellites, and the WAV recording should be 1 channel real data, but the sample rate is no longer fixed to 48ksps and can be specified with the --samp_rate parameter (both for UDP and WAV input). More input options will come in the future, including the option to use IQ data instead of real data.

For an easy test of the decoder, it can be run as

gr_satellites --wavfile satellite-recordings/1kuns_pf.wav \
  --samp_rate 48e3 1KUNS-PF

gr_satellites --wavfile satellite-recordings/gomx_3.wav \
  --samp_rate 48e3 GOMX-3

to process the sample files in satellite-recordings. It can also be run as

gr_satellites --udp --samp_rate 48e3 1KUNS-PF

to use the UDP realtime input as the current versions of gr-satellites.

This examples show well the kind of user interface I want to achieve for the final gr_satellites command line tool: simple to use for basic use cases, and efficient to process existing recordings.

Currently the decoders for 1KUNS-PF and GOMX-3 print telemetry data to the screen, and the 1KUNS-PF also performs image decoding. Configuration of output options (data sink components) will come in future alphas.

Satellite decoder GRC block

Advanced users that want more customization than what is possible with the gr_satellites command line tool can use the “Satellite decoder” GNU Radio companion block to include the core functionality of gr-satellites into their own flowgraphs.

This satellite decoder allows the selection of a satellite in the same way as gr_satellites, using its name, NORAD ID or YAML file. It gets real samples as input and gives PDUs with the decoded frames as output. The user can then process the frames however they want. The figure below shows an example of the use of this block.

As in the case of the gr_satellites command line tool, additional input options such as IQ input will be added to this block in the future.

Perhaps additional output ports will be added to the Satellite decoder block in the future. For example, an output port with the demodulator output can be useful to users that want to use GUI elements to monitor the signal.

Components

The concept of components was introduced in my previous post. They form the basis of gr-satellites (decoder flowgraphs are built from satellite YAML files by connecting suitable components) and can be employed by advanced users as a library of blocks to build their own flowgraphs.

In this alpha, only an FSK demodulator component and components to deframe the GOMspace AX100 radio (both in Reed Solomon and ASM+Golay modes) and the AX.25 protocol are provided.

As an example of what is possible using the components and satellite YAML files approach, even though no FSK AX.25 satellite has been defined in this alpha, it should be easy to add one just by writing a YAML file (using AX.25 or AX.25 G3RUH in the framing field).

Future alphas will concentrate on adding data sink components to perform various tasks with the frames: saving to KISS file, sending through the network, submitting to SatNOGS, printing in hex format, etc.