Components

Components represent gr-satellite’s way of decomposing the decoding process in high-level blocks. The decoding chain is broken into a series of steps which pass their output to the input of the next step. These are the following:

  • Data sources. These produce the input of the decoding chain, which typically consists of RF signal samples.

  • Demodulators. These turn RF samples into soft symbols. They filter the signal, recover the transmit clock and carrier if necessary, etc. An example is a BPSK demodulator, which turns RF samples of a BPSK signal into a stream of soft symbols.

  • Deframers. Deframers implement the lower layer protocols related to frame boundary detection, descrambling, deinterleaving, FEC, error checking with a CRC code, etc. The output of a deframer are PDUs with the frames. Some examples are an AX.25 deframer and a CCSDS concatenated code deframer.

  • Transports. Transports implement higher layer protocols that might be needed to get to the useful information inside the frames. For example, if frames are fragmented, a transport will handle defragmentation. An example is a KISS transport, whose input are frames that contain bytes of a KISS stream, and its output are the packets contained in that KISS stream, regardless of how they are split between different frames.

  • Data sinks. Data sinks are the consumers of packets. They might store them, send them to another software, or parse telemetry values.

All the component blocks support Command line options in the same way as the satellite decoder block. The set of available options for each component block is different. It is possible to use the "--help" as the options of a particular block in order to print out the available options for that block.

Below, the main component blocks in each category are described.

Data sources

Data source components can be found under Satellites > Data sources in GNU Radio companion. Currently, the only data source is the “KISS File Source” block. This block will read a file in KISS format, and output the frames in the file as PDUs.

The usual operations involving reading RF samples from an SDR or recording can be achieved easily with default GNU Radio blocks, so there are no specific data sources for these. Advanced users can look at the setup_input() method of the class gr_satellites_top_block in apps/gr_satellites to see how the gr_satellites command line tools sets up its different inputs using default GNU Radio blocks.

Demodulators

Demodulator components can be found under Satellites > Demodulators in GNU Radio companion. There are currently three demodulator component blocks:

  • BPSK demodulator

  • FSK demodulator

  • AFSK demodulator

They take RF signal samples as input, and output soft symbols, as a stream of float normalized with amplitude one. The input can be either real or IQ (complex). See Real or IQ input for more information.

The demodulator blocks and their parameters are described below.

BPSK demodulator

The BPSK demodulator expects an input which consists of RF samples of a BPSK signal, and outputs the demodulated BPSK soft symbols. The BPSK signal can optionally be DBPSK or Manchester encoded.

The figure below shows the example flowgraph which can be found in examples/components/bpsk_demodulator.grc. This reads a WAV file from satellite-recordings which contains some BPSK packets from LilacSat-1 and uses the BPSK demodulator to obtain the symbols. The “Skip Head” and “Head” blocks are used to select a portion of the output, which is then plotted using the “QT GUI Time Sink”.

Usage of BPSK demodulator in a flowgraph

Usage of BPSK demodulator in a flowgraph

When this example flowgraph is run, it displays the output shown in the figure below. There we can see the start of the BPSK packet. On the left side of the plot we have noise, before the packet starts, then the packet starts, and the clock and carrier recovery take some time to sync. After this, the symbols are demodulated properly. This can be seen because the +1 and -1 symbols are well separated.

Output of the BPSK demodulator example flowgraph

Output of the BPSK demodulator example flowgraph

The figure below shows the options allowed by the BPSK demodulator block. The Baudrate option is used to set the baudrate in symbols per second. The Sample rate option specifies the sample rate of the input. The Frequency offset specifies at which frequency the BPSK signal is centred (see Frequency offsets for BPSK).

The Differential option enables differential decoding of DBPSK. For differential decoding, the phase recovery using a Costas loop is disabled and non-coherent demodulation is used.

The Manchester option enables Manchester decoding. A Manchester encoded BPSK signal is decoded as if it had twice the baudrate, and then the phase of the Manchester clock is searched in the symbols and the Manchester clock is “wiped-off”, multiplying symbols by the clock and accumulating them by pairs.

The IQ input option enables IQ (complex) input.

Options of BPSK demodulator

Options of BPSK demodulator

FSK demodulator

The FSK demodulator expects an input which consists of RF samples of an FSK signal, and outputs the demodulated FSK soft symbols. Both real and IQ (complex) input are suported, but the semantics are different: with real input, the FSK demodulator expects an FM-demodulated signal; with IQ input, the FSK demodulator expects the signal before FM demodulation (see FSK demodulation and IQ input).

The figure below shows the example flowgraph which can be found in examples/components/fsk_demodulator.grc. This reads a WAV file from satellite-recordings which contains a single FSK packet from AAUSAT-4 and uses the FSK demodulator to obtain the symbols. The output is plotted using the “QT GUI Time Sink”.

Usage of FSK demodulator in a flowgraph

Usage of FSK demodulator in a flowgraph

When this example flowgraph is run, it displays the output shown in the figure below. There we can see the FSK packet, surrounded by noise on both sides.

Output of the FSK demodulator example flowgraph

Output of the FSK demodulator example flowgraph

The figure below shows the options allowed by the FSK demodulator block. The Baudrate option is used to set the baudrate in symbols per second. The Sample rate option specifies the sample rate of the input. The IQ input option enables IQ (complex) input. The signal is expected to be centred at baseband (0Hz) when IQ input is selected. The Subaudio option enables subaudio demodulation, which is intended for subaudio telemetry under FM voice and includes an additional lowpass filter to filter out the voice signal.

Options of FSK demodulator

Options of FSK demodulator

AFSK demodulator

The APSK demodulator expects an input which consists of RF samples of an AFSK signal, and outputs the demodulated AFSK soft symbols. Both real and IQ (complex) input are suported, but the semantics are different: with real input, the AFSK demodulator expects an FM-demodulated signal; with IQ input, the AFSK demodulator expects the signal before FM demodulation (see FSK demodulation and IQ input).

The figure below shows the example flowgraph which can be found in examples/components/afsk_demodulator.grc. This reads a WAV file from satellite-recordings which contains a single AFSK packet from GOMX-1 and uses the AFSK demodulator to obtain the symbols. The “Head” block is used to select a portion of the output, which is then plotted using the “QT GUI Time Sink”.

Usage of AFSK demodulator in a flowgraph

Usage of AFSK demodulator in a flowgraph

When this example flowgraph is run, it displays the output shown in the figure below. There we can see the AFSK packet, surrounded by noise on both sides.

Output of the AFSK demodulator example flowgraph

Output of the AFSK demodulator example flowgraph

The figure below shows the options allowed by the AFSK demodulator block. The Baudrate option is used to set the baudrate in symbols per second. The Sample rate option specifies the sample rate of the input.

The AF carrier option specifies the audio frequency in Hz on which the FSK tones are centred. The Deviation option specifies the separation in Hz between each of the tones and the AF carrier. If the deviation is positive, the high tone is interpreted as representing the symbol 1, while the low tone is interpreted as representing the symbol 0 (or -1 in bipolar representation). If the deviation is negative, the low tone is interpreted as representing the symbol 1 and the high tone is interpreted as representing the symbol 0.

In this example, the AF carrier is 3600 Hz and the deviation is -1200 Hz. This means that the tone representing 1 is at 2400 Hz, while the tone representing 0 is at 4800 Hz (the signal is actually 4800 baud GMSK).

The IQ input option enables IQ (complex) input.

Options of AFSK demodulator

Options of AFSK demodulator

Deframers

Deframer components can be found under Satellites > Deframers in GNU Radio companion. There is a large number of deframer component blocks, since many satellites use ad-hoc protocols for framing, so a custom deframer is used for those satellites.

Deframers take soft symbols, produced as the output of one of the demodulator components, and detect frame boundaries, perform as necessary descrambling, deinterleaving, FEC decoding, CRC checking, etc.

Here, the most popular deframers are described. For ad-hoc deframers that are used in few satellites, the reader is referred to the documentation of each of the blocks in GNU Radio companion.

AX.25 deframer

The AX.25 deframer implements the AX.25 protocol. It performs NRZ-I decoding, frame boundary detection, bit de-stuffing, and CRC-16 checking. Optionally, it can also perform G3RUH descrambling. G3RUH scrambling is typically used for faster baudrates, such as 9k6 FSK packet radio, but not for slower baudrates, such as 1k2 AFSK packet radio.

The figure below shows an example flowgraph of the AX.25 deframer block. This example can be found in examples/components/ax25_deframer.grc. The example reads a WAV file from satellite-recordings containing 9k6 FSK AX.25 packets from US01, demodulates them with the FSK demodulator block, deframes tham with AX.25 deframer, and prints the output with the Message Debug block.

Usage of AX.25 deframer in a flowgraph

Usage of AX.25 deframer in a flowgraph

The AX.25 deframer block has a single option that indicates whether G3RUH descrambling should be performed or not.

GOMspace AX100 deframer

The GOMspace AX100 deframer implements two different protocols used by the popular GOMspace NanoCom AX100 transceiver. These two protocols are:

  • ASM+Golay. This uses a header encoded with a Golay(24,12) code that indicates the packet length. The payload is Reed-Solomon encoded with a (255,223) CCSDS code and scrambled with the CCSDS synchronous scrambler.

  • Reed Solomon. This uses a G3RUH asynchronous scrambler. The first byte of the packets indicates the length of the payload and is sent unprotected. The packet payload is Reed-Solomon encoded with a (255,223) CCSDS code.

The figure below shows an example flowgraph of the AX100 deframer block running in both modes. This example can be found in examples/components/ax100_deframer.grc. For ASM+Golay decoding the example reads a WAV file from satellite-recordings containing packets from 1KUNS-PF. For Reed Solomon decoding the example reads a WAV file from satellite-recordings which contains packets from TW-1B. The output frames are printed with Message Debug blocks.

Usage of AX100 deframer in a flowgraph

Usage of AX100 deframer in a flowgraph

In Reed Solomon mode, the AX100 deframer only has two options: the Mode option indicates the mode, as described above, and the Syncword threshold option specifies how many bit errors are allowed in the detection of the 32 bit syncword. In ASM+Golay mode, the AX100 deframer has an additional option: Scrambler, which can be used to enable or disable the CCSDS synchronous scrambler.

GOMspace U482C deframer

The GOMsace U482C deframer implements the protocol used by the GOMspace NanoCom U482C tranceiver, which is an older transceiver from GOMspace that is still seen in some satellites.

The protocol used by the U482C is similar to the ASM+Golay mode used by the AX100. The packet payload can be optionally:

  • Encoded with the CCSDS r=1/2, k=7 convolutional encoder

  • Scrambled with the CCSDS synchronous scrambler

  • Encoded with a CCSDS (255,223) Reed-Solomon code

The packet header has flags that indicate which of these options are in use, in addition to the length field.

The U482C modem uses AFSK with a 4800 baud audio-frequency GMSK waveform.

The figure below shows an example flowgraph of the U482C deframer block. This example can be found in examples/components/u482c_deframer.grc. The example reads a WAV file from satellite-recordings containing a packet from GOMX-1. The packet is demodulated and deframed, and the output is printed in hex using the Message Debug block.

Usage of U482C deframer in a flowgraph

Usage of U482C deframer in a flowgraph

The U482C deframer has a single option, which indicates the number of bit errors that are allowed in the syncword detection.

AO-40 FEC deframer

The AO-40 FEC deframer implements the protocol designed by Phil Karn KA9Q for the AO-40 FEC beacon. This protocol is currently used in the FUNcube satellites and others.

The FEC is based on CCSDS recommendations and uses a pair of interleaved Reed-Solomon (160,128) codes, the CCSDS synchronous scrambler, the CCSDS r=1/2, k=7 convolutional code, interleaving and a distributed syncword.

The figure below shows an example flowgraph of the AO-40 FEC deframer block. This example can be found in examples/components/ao40_fec_deframer.grc. It reads a WAV file from satellite-recordings containing a packet from AO-73 (FUNcube-1). The packet is first BPSK demodulated and then deframed with the AO-40 FEC deframer. The output is printed out using the Message Debug block.

Usage of AO-40 FEC deframer in a flowgraph

Usage of AO-40 FEC deframer in a flowgraph

The AO-40 FEC deframer block has two options. The Syncword threshold option indicates the number of bit errors to allow in the syncword detection. The Use short frames option toggles the usage of short frames. This is a variant of the AO-40 FEC protocol which is based on a single Reed-Solomon codeword and is used by SMOG-P and ATL-1.

CCSDS deframers

The CCSDS Uncoded deframer, CCSDS Concatenated deframer, and CCSDS Reed-Solomon deframer blocks implement some of the CCSDS protocols defined in the TM Synchronization and Channel Coding Blue Book (see the CCSDS Blue Books).

The CCSDS Uncoded deframer implements uncoded TM frames.

The CCSDS Reed-Solomon deframer implements Reed-Solomon TM frames, which use a Reed-Solmon (255, 223) code (or a shortened version of this code) and the CCSDS synchronous scrambler. There is support for several interleave Reed-Solomon codewords.

The CCSDS Concatenated deframer implements concatenated TM frames, which add an r=1/2, k=7 convolutional code as an inner coding to the Reed-Solomon frames.

The usage of all three of these deframers is very similar.

The figure below shows an example flowgraph of the CCSDS Concatenated deframer block. This example can be found in examples/components/ccsds_deframer.grc. It reads a WAV file from satellite-recordings containing some packets from BY70-1. These are concatenated TM frames with a frame size of 114 bytes and differential encoding (to solve the BPSK phase ambiguity). The packet is first BPSK demodulated and then deframed. The output is printed using the Message Debug block.

Usage of CCSDS Concatenated deframer in a flowgraph

Usage of CCSDS Concatenated deframer in a flowgraph

The figure below shows the options used by the CCSDS Concatenated deframer. The CCSDS Reed-Solomon deframer block allows exactly the same options, except for the Convolutional code option, since all the other options refer to the Reed-Solomon outer code.

The Frame size option indicates the size of the frame in bytes (after Reed-Solomon decoding). The Precoding option can be used enable a differential decoder before the Reed-Solomon decoder. This is often used to solve the BPSK 180º phase ambiguity. The Reed-Solomon basis option can be used to toggle between the conventional and dual basis definitions of the Reed-Solomon code. The CCSDS standard specifies the dual basis, but the conventional basis is frequently used. The Reed-Solomon interleve depth option can be used to enable decoding of interleaved Reed-Solomon codewords. The Scrambler option can be used to enable or disable the CCSDS synchronous scrambler. The Syncword threshold option can be used to choose the number of bit errors that are allowed in the detection of the syncword.

Options of CCSDS Concatenated deframer

Options of CCSDS Concatenated deframer

Transports

Transport components can be found under Satellites > Transports in GNU Radio companion. Transports are designed to implement upper layer protocols. They take as input the output of a demodulator, which contains physical layer or link layer frames and process it to obtain upper layer packets. Some of the typical functionalities implemented by these upper layer protocols include fragmentation/defragmentation.

The only transport available so far in gr-satellites is the KISS transport.

KISS transport

The KISS tranport implements fragmentation/defragmentation according to the KISS protocol for packet boundary detection. Its input should be PDUs containing the bytes of a KISS stream. The frames are joined and the KISS stream is followed, detecting packet boundaries and extracting the packets. The packets are output as PDUs.

The figure below shows an example flowgraph of the KISS transport, which can be found in examples/components/kiss_transport.grc. It is based on the CCSDS Concatenated deframer example described above. BY70-1 sends frames which contain the bytes of a KISS stream, so the KISS transport can be used to extract the packets from this stream. There are two Message Debug blocks that can be enabled or disabled in order to see the input or the output of the KISS transport block.

Usage of KISS transport in a flowgraph

Usage of KISS transport in a flowgraph

When the example is run, the frames at the input of the input of the KISS transport look like the one below. We see that there is a single packet embedded into the 114 byte Reed-Solomon frame, using c0 KISS idle bytes for padding.

pdu_length = 114
contents =
0000: c0 b8 64 3d 00 12 00 00 00 00 c8 3a 00 80 00 00
0010: 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32
0020: 32 32 32 32 32 32 32 32 32 32 32 32 32 32 ff c4
0030: 00 1f 00 00 01 05 01 01 01 01 01 01 00 00 00 00
0040: 00 00 00 00 01 02 03 04 05 06 07 08 09 0a 0b ff
0050: 18 21 00 00 db dc 4b f7 07 c0 c0 c0 c0 c0 c0 c0
0060: c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0 c0
0070: c0 c0

The frames at the output of the KISS transport look like the following. We see that the c0 KISS idle bytes have been stripped. The KISS transport can also handle the case when a packet is longer than 114 bytes and has been fragmented into several 114 byte frames.

pdu_length = 87
contents =
0000: b8 64 3d 00 12 00 00 00 00 c8 3a 00 80 00 00 32
0010: 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32
0020: 32 32 32 32 32 32 32 32 32 32 32 32 32 ff c4 00
0030: 1f 00 00 01 05 01 01 01 01 01 01 00 00 00 00 00
0040: 00 00 00 01 02 03 04 05 06 07 08 09 0a 0b ff 18
0050: 21 00 00 c0 4b f7 07

The KISS transport has a single option, called Expect control byte. When it is set to True, the first byte before the packet payload is interpreted as a control byte according to the KISS protocol. If it is set to False, it is assumed that there is no control byte preceeding the packet payload. When using KISS as a means to fragment/defragment upper layer packets it is more common not to use control bytes.

Data sinks

Data sink components are the final consumers of the PDUs that contain the decoded frames. They can be used for several things, such as printing telemetry values, saving frames to a file, sending frames to an online telemetry database server, and reassembling files and images. The different data sinks available in gr-satellites are described below.

Telemetry parser

The telemetry parser uses construct to parse a PDU containing a telemetry frame into the different fields and prints the parsed values to the standard output or a file.

The parser uses telemetry definitions, which are either Construct objects (typically a Struct) or any other object supporting the parse() method in case more complex parsing behaviour is needed. The list of available telemetry definitions can be seen in python/telemetry/__index__.py, or by calling import satellites.telemetry; help(satellites.telemetry) in python3.

The figure below shows an example flowgraph of the Telemetry parser block, which can be found in examples/components/telemetry_paser.grc. It is based on the U482C example described above. The packets sent by GOMX-1 are deframed and the the Telemetry parser is used to print out the telemetry values to the standard output.

Usage of Telemetry parser in a flowgraph

Usage of Telemetry parser in a flowgraph

The beginning of the ouptut produced by the Telemetry parser block can be seen below.

Container:
 csp_header = Container:
     priority = 2
     source = 1
     destination = 10
     destination_port = 30
     source_port = 0
     reserved = 0
     hmac = False
     xtea = False
     rdp = False
     crc = False
 beacon_time = 2015-03-31 20:57:01
 beacon_flags = 121
 beacon = Container:
     obc = Container:
         boot_count = 573
         temp = ListContainer:
             -6.0
             -4.0
         panel_temp = ListContainer:
             0.0
             -28.5
             -26.75
             -13.25
             -28.25
             -20.0

The options used by the Telemetry parser are the following. The Telemetry definition option indicates the telemetry definition object, which must be an object in the satellites.telemetry module as described above. The Output drop down list can be used to select the standard output or a file as the destination for the parser’s output. If a file is selected, an additional option to select the file path appears.

Telemetry submit

The telemetry submit block implements Telemetry submission to several different online telemetry servers. Its input consists of PDUs with frames, which are then submitted to the selected telemetry server.

This block uses the gr-satellites config file located in ~/.gr_satellites/config.ini to configure the different options of the telemetry servers, such as the login credentials. See the information regarding the command line tool for how to set up this configuration file.

The telemetry submit block has only one option, which is a drop down list that is used to select the telemetry server to use.

Hexdump sink

The hexdump sink prints PDUs in hex to the standard output. It is a wrapper over the Message Debug standard GNU Radio block, so it uses the same output format. This block is used internally by the gr_satellites command line tool (see Hex dump), and can also be used in custom flowgraphs instead of Message Debug.

KISS file sink

The KISS file sink can be used to store PDUs in a file using the KISS protocol. This protocol is a simple format to mark frame boundaries. Files containing frames with the KISS protocol can then be read with the KISS file datasource (see Data sources) and with the gr_satellites command line tool (see Specifying the input source), as well as with external tools.

The KISS file sink block has two options. The File option is used to select the path of the output file. The Append file option can be used to overwrite or append to the output file.

The KISS files produced by the KISS file sink store timestamps as described in the KISS output of the gr_satellites command line tool.

KISS server sink

The KISS server sink spawns a TCP server that sends decoded PDUs to connected clients using the KISS protocol. A number of tools can act as clients using this protocol.

The KISS file sink block has a Port option to specify the TCP port to listen on.

The KISS server sink sends timestamps as described in the KISS output of the gr_satellites command line tool.

File and Image receivers

The File and Image receiver blocks are used to reassemble files transmitted in chunks, using a variety of different formats. The only difference between the File receiver and the Image receiver is that the Image receiver is able to display image files in realtime using feh as they are being received.

These receiver blocks use FileReceiver definitions, which are classes derived from FileReceiver. The list of available definitions can be seen in python/filereceiver/__index__.py, or by calling import satellites.filereceiver; help(satellites.filereceiver) in python3. Classes used by the Image receiver must be derived from ImageReceiver.

The figure below shows an example flowgraph of the Image receiver block, which can be found in examples/components/image_receiver.grc. The example reads a WAV file from satellite-recordings containing an image transfer from LilacSat-1. The WAV file is played back in real time using the Throttle block. The Satellite decoder block is used to demodulate and deframe the packets. Since these packets contain a KISS stream, the KISS transport is used to obtain the image packets. These are sent into the Image receiver block, which will print some information to the standard output and when the beginning of the image is receive, will launch feh to display the image.

Usage of Image receiver in a flowgraph

Usage of Image receiver in a flowgraph

The figure below shows the options of the Image receiver block. The option ImageReceiver class indicates the definition to use for reassembling the image (which is implemented by a class derived from ImageReceiver). The Path option specifies the path of the directory where received files are saved to. The names of the files depend on metadata in the image packets. The Verbose option enables printing information to the standard output, such as the frames being received. The Display option enables the use of feh to display the image. The Fullscreen option is used to run feh in fullscreen.

Options of Image receiver

Options of Image receiver

The options of the File receiver block are the same as those of the Image receiver block, except for the Display and Fullscreen options, which are specific to image reception.

Codec2 UDP sink

The Codec2 UDP sink is used internally by the gr_satellites command line tool when decoding LilacSat-1. The LilacSat-1 decoder supports outputting Codec2 digital voice frames by UDP. These frames can then be fed into the Codec2 command line decoder.

The Codec2 frames are 7 bytes long, and each is sent in a different UDP packet to ensure minimum latency.

The Codec2 UDP sink has two options, which indicate the IP and port to send the frames to. By default, address 127.0.0.1 and port 7000 are used.

The Codec2 frames can be decoded and played in real time by the Codec2 decoder as shown here.

$ nc -lu 7000 | c2dec 1300 - -  | play -t raw -r 8000 -e signed-integer -b 16 -c 1 -

The c2dec command line decoder can be obtained by building from source the codec2 library