gr-satellites v3 is a large refactor of the gr-satellites codebase that I introduced in September. Since then, I have been working and releasing alphas to showcase the new features and get feedback from the community. Today I have released the third alpha in the series: v3-alpha2.
Each of the alphas has focused on a different topic or feature, and v3-alpha2 focuses on extending the number of satellites supported and bringing back most of the satellites supported in gr-satellites v2. Whereas previous alphas supported only a few different satellites, this alpha supports a large number. Therefore, I think that this is the first gr-satellites v3 release that is really useful. I expect that interested people will be able to use v3-alpha2 as a replacement of gr-satellites v2 in their usual activities.
In this post, I explain the main features that this alpha brings. For the basic usage of gr-satellites v3, please refer to the post about the second alpha.
Supported satellites
Regarding compatibility with the different satellites, there is a table here. For each of the satellites supported in gr-satellites v2, it shows the status of the decoder in v3-alpha2. This can be any of the following:
- Unsupported. This means that there is no decoder in v3-alpha2 yet. Most of the satellites in this category depend on the beesat-sdr out-of-tree module, which hasn’t been ported to GNU Radio 3.8 yet, so even though the decoder exists in gr-satellites v2, it doesn’t really work. Besides these, we have EQUiSat, which depends on gr-equisat_decoder, which isn’t available for GNU Radio 3.8 either, the TANUSHA-3 phase modulation decoder, which was part of a small experiment, and QB50 UA01 PolyITAN-2-SAU, which implements AX.25 incorrectly. In a few days I’ll handle these two last satellites: the TANUSHA-3 decoder will go under
examples/(instead of making a specific demodulator for phase modulation), and I will make a custom deframer for UA01. Regarding beesat-sdr and gr-equisat_decoder I will have to check with their authors on how to proceed to get these ported to GNU Radio 3.8. - Partially supported. This means that there is a decoder in v3-alpha2, but this decoder doesn’t have some feature that exists in the v2 decoder. Most of the missing features are AX.25 address checks, CSP CRC checks and image decoding. I will speak in more detail about this features below.
- Fully supported. This means that the decoder in v3-alpha2 has at least the same functionality that the decoder in v2. Some of these are untested, which means that I don’t have a recording in satellite-recordings to test the decoder or the recording I have is not good enough to give decodes.
Let us review the main new features available in v3-alpha2.
Deframers
The deframer components take soft symbols (after BPSK or FSK demodulation) and produce PDUs with frames by performing packet boundary detection, descrambling, FEC decoding, CRC checking, etc. A large number of deframers have been added in v3-alpha2. The full list of available deframers can be seen in the figure below.
When deciding how to go about adding deframers to support all the different satellites, I reckon that there are many cases in which a satellite uses and ad-hoc framing. Therefore, I decided to have specific deframers for these satellites. The alternative is to try to have more general deframers and specify the specifics used by each satellite in its YAML file. However, I didn’t see a good way to make this approach work.
Whereas most of the deframers in the list above are specific to one or a few very similar satellites, there are also some deframers that are re-used in several different satellites, because they implement popular protocols or modems. These can be interesting for anyone that wants to use gr-satellites as a set of building blocks to implement a decoder for their new satellite, as ESA has recently done for OPS-SAT with gr-opssat. Note that if you do so, it is encouraged that you contribute you changes back to gr-satellites. Now it could be as easy as writing an appropriate SatYAML file.
The deframers which can be interesting to other people are the following. There are the AX.25 deframer and GOMspace NanoCom AX100 deframer that I introduced in v3-alpha0. Now there is also a deframer for the older GOMspace NanoCom U482C radio.
There are a couple of decoders for CCSDS TM frames, as described in the TM Synchronization and Channel Coding blue book. These are shown below.
The Reed-Solomon Deframer implements detection of the CCSDS syncword, descrambling with the CCSDS synchronous descrambler, and CCSDS Reed-Solomon decoding. There is the option to perform differential decoding as a preliminary step. The Concatenated Deframer first performs Viterbi decoding of the CCSDS convolutional code and then acts as the Reed-Solomon Deframer. The frame size is the size of the frame after FEC decoding, so 223 is used for a full (255,223) Reed-Solomon frame.
Another interesting deframer is the following, which implements the AO-40 FEC protocol. This is a very nice protocol that uses a distributed syncword, interleaved CCSDS convolutional coding, CCSDS scrambling, and two interleaved CCSDS Reed-Solomon codewords per frame. It is used in the FUNcube family of satellites and works really well. It is definitely something you should look at if you are trying to choose which modem to use for your new satellite. The deframer has the option to decode short frames, which are used by SMOG-P.
Transports
In the design of the gr-satellites refactor, Transport Components where thought as a way to get from the output of the of Deframers to the actual data (telemetry frames, image chunks, etc.). Since many satellites implement ad-hoc protocols, it is hard to speak formally about network layers. In many cases, the output of the deframer is already the actual data, but it is foreseen that in other cases there will be “upper layer” protocols, such as (possibly fragmented) CCSDS Space Packets carried on top of TM Space Data Link frames. These upper layers protocols should be implemented by transports.
In making v3-alpha2, I have only found the need to implement a single transport, the KISS Transport.
This handles the case in which the frames output by the deframer are chunks of a KISS stream. The input to the KISS transport are chunks of the KISS stream. The KISS Transport follows the KISS stream and outputs KISS frames. The “expect control byte” parameter can be used to specify whether the KISS stream includes a control byte before each packet or not (often this should be set to “False”). This kind of KISS transport is often used in satellites from Harbin Institute of Technology.
The way to specify to specify a KISS transport in a SatYAML file can be seen in the example below.
name: BY70-1
norad: 41909
data:
&tlm Telemetry:
telemetry: by70_1
transports:
&kiss KISS:
protocol: KISS no control byte
data:
- *tlm
transmitters:
9k6 BPSK downlink:
frequency: 436.200e+6
modulation: BPSK
baudrate: 9600
framing: CCSDS Concatenated differential
frame size: 114
transports:
- *kiss
With SatYAML, currently it is only possible to put a single transport between the deframer and the datasink, as shown above. However, it would be easy to implement the chaining of an arbitrary number of transports by adding a transports: field to the transport entry to specify that the output should be directed to another transport instead of a datasink.
Additional data
LilacSat-1 gave an interesting special case that was not foreseen when the refactor was designed. Its low latency decoder, which should be implemented as a deframer, produces two kinds of data: chunks of a KISS stream (which should be sent to a KISS transport) and Codec2 digital voice frames (which are usually sent by UDP to a Codec2 decoder).
I didn’t see a way to handle this cleanly, so I added the concept of “additional data”. Whereas usually a deframer will have a single output port (called out), it is now possible for a deframer to have additional output ports which can be identified by their name. In the case of LilacSat-1, the out port writes PDUs with chunks of the KISS stream, while there is an additional output port called codec2 which outputs PDUs with Codec2 frames. These additional output ports can be connected to datasinks in the SatYAML file by using the additional_data field, as the example below shows.
name: LilacSat-1
alternative_names:
- CN02
- QB50 CN02
- LO-90
norad: 42725
data:
&tlm Telemetry:
telemetry: by70_1
&codec2 Codec2:
decoder: codec2_udp_sink
transports:
&kiss KISS:
protocol: KISS no control byte
data:
- *tlm
transmitters:
9k6 BPSK downlink:
frequency: 436.510e+6
modulation: BPSK
baudrate: 9600
framing: LilacSat-1
transports:
- *kiss
additional_data:
- codec2: *codec2
BME telemetry submitter
In the maint-3.8 branch of gr-satellites I have added a telemetry submitter to send telemetry from ATL-1 and SMOG-P (and SMOG-1 in the future) to the BME telemetry server. This has also been added to the Telemetry Submit Datasink in v3-alpha2. See the post about v3-alpha1 for instructions on how this is configured. The BME telemetry submitter adds a new section to the configuration file. The easiest way to perform the configuration is to remove the existing configuration file and then run gr_satellites, which will create a new configuration file with default values, including the new section to configure the BME telemetry server. This default configuration can be edited to enter station and login information.
Testing
To help me in testing, I have made a very crude script called test.sh that runs the different decoders with the recordings from satellite-recordings. Each of the tests should produce some valid decodes. You can use this test script to check that your setup is working or as an example about how to run the gr_satellites command line tool.
Roadmap
Compared to gr-satellites v2, one of the most important shortcomings of v3 is the current lack of image decoders. This is the first thing I want to address in the next alpha. Currently there is a lot of repeated code in the image decoders, so I want to take this opportunity to make a general file receiver that receives and reassembles files sent in chunks. The image decoders will be a special case of this file receiver, in which also the image will be shown in realtime using feh. Another use case for the file receiver will be the SMOG-P spectrum data. This will be the subject of v3-alpha3.
After this alpha, I want to improve the performance of the demodulators. As you can see in the test script, some of the recordings need specifying manually some of the decoding parameters (loop bandwidths, etc.), since the default values won’t give decodes. This is specially important with AX.25, where the lack of FEC will prevent decoding unless the quality of the demodulation is excellent.
I want to use the Symbol Sync block introduced by Andy Walls in his GRcon17 talk and do some general testing and fine-tuning to find what parameters work best in most cases. This will be released in v3-alpha4. It is important that v3-alpha4 gets good on-air testing,
Besides these topics, there are a few left overs that I have mentioned above. First, there is AX.25 address checking. Honestly, I’m not so sure how to go about it. The reason why it was introduced in gr-satellites in the first place comes from Mike Rupprecht DK3WN‘s Online telemetry forwarder. This software received telemetry frames from a decoder and sent them to the PE0SAT telemetry database (which was eventually superseded by SatNOGS DB, to which Mike’s forwarder can also send telemetry). Mike’s software used some heuristics, such as checking the AX.25 callsigns, to detect which satellite had originated the frames in order to submit to the database using the correct satellite.
In gr-satellites, this was not necessary, since each satellite has a different flowgraph which already knows how to submit to the database using the correct satellite NORAD ID. However, as a safety precaution against people using the decoder of one satellite to decode a second different satellite (but using a compatible protocol, say AX.25), the AX.25 address checking was implemented.
This made sense back in the day because many satellites used AX.25 and the rest of them tended to use completely different protocols. However, these days there are many satellites using the same non-AX.25 protocols (the AX100 protocols, for example), and there is no easy way to know which satellite produced each frame. Therefore, the usefulness of AX.25 address checking is somewhat limited, and I am tempted not to implement it in gr-satellites v3. I’m open for suggestions, though. So I will probably implement it if someone convinces me that it’s still useful.
Regarding CSP CRC checking, this is something that I think is useful and I want to include in v3 at some point. However, there is a lot of variability in how each satellite implements the CRC (mainly regarding endianness, and whether the CSP header is included in the CRC or not). Also, many satellites that use CSP don’t use a CRC, and sometimes the CRC flag in the CSP header is wrong. Therefore, I need to think of a good way to fit this variability into the SatYAML schema.
Another interesting idea concerns AX.25 satellites. gr-satellites had never supported FSK AX.25 satellites, since there are too many of them and there are already good decoders such as direwolf. However, at some point I added some “generic AX.25 decoders”, and some people are using them often. In v3 it is really easy to add SatYAML files for these FSK AX.25 satellites (the QB50 US01 file is already an example), so it makes sense to have a different SatYAML file for each of these satellites (if only, as documentation on satellites and frequencies). There are many of these satellites, so writing these by hand would be very cumbersome. However, I have the idea to pull the data from SatNOGS DB and write the SatYAML files automatically. This huge list of new satellites will probably come soon enough.
Once all this is handled I expect to have a gr-satellites v3 that already has all the functionality of v2, both using the gr_satellites command line tool and the component blocks to build custom flowgraphs in GNU Radio companion. I will make some clean up to remove the deprecated older blocks (for instance most of the telemetry parser blocks are now superseded by the Telemetry Parser datasink), and try to organise all the older Python code better. It will also be the time to add some documentation. After that, probably I will release gr-satellites v3.0.0 as the new stable version of gr-satellites, and the development of the v2 branch will stop.
This is not the end of the story. There are other features I am interested in that will be perhaps be added in future versions in the v3 branch. For example, there is the idea to add optional GUI elements to allow the user to view the spectrum and symbols in real time. I am interested in hearing from you to see what other features you would find useful.
2 comments