brownspaceengineering/gr-equisat_decoder repository overview

⁠EQUiSat Decoder

A GNU radio Out-Of-Tree Module and custom blocks to decode EQUiSat's 4FSK transceiver

Docker Hub link⁠

⁠Dependencies

• GNU Radio⁠ (this repo is a GNU Radio "module")
• Swig⁠ (usually available in package managers; required for GNU Radio to generate Python bindings from C++)
• BrownSpaceEngineering/packetparse⁠ for extracting fields in EQUiSat's telemetry, included as a submodule (run git submodule init and git submodule update).
• See requirements.txt for additional Python dependencies (run pip install -r requirements.txt )

⁠Build and Installation

Run:

pip install -r requirements.txt # if you haven't
git submodule init
git submodule update
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig

⁠Building & Running in Mac OS

Download: (Unfortunately, there are a lot of things)

• xQuartz⁠
• GitHub desktop⁠ Clone the following into GitHub desktop:
  • gr-equisat-decoder⁠
  • packetparse⁠
• Swig⁠
• MacPorts⁠ Follow instructions under “macOS Package (.pkg) Installer”
• Git and homebrew⁠ to be able to run commands (eg: git)

Navigate to gr-equisat_decoder (???) by cd-ing. In xQuartz terminal, run:

pip install -r requirements.txt # if you haven't
git submodule init
git submodule update
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig

Finally, get GNU Radio itself, by typing

 sudo port install gnuradio 

Into xQuartz terminal

• Note: I can’t remember if it was this command or one previously, but I think this takes an ungodly amount of time to run on xQuartz (multiple hours)

To check what version of GNU Radio was downloaded, type into the xQuartz terminal.

 gnuradio-config-info --version 

Make sure your version is the same as the one for gr-equisat-decoder. To switch the gr-equisat-decoder version to 3.7, by cd-ing into gr-equisat_decoder and running git checkout maint-3.7 on your machine's terminal. (??? DCMAKE_INSTALL_PREFIX=/opt/local/)

To run GNU Radio, type the following into your xQuartz terminal, and it should open GNU Radio.

gnu-radio-companion

⁠Building & Running using Docker

Install Docker⁠ on your machine.

Run start_docker_grc.sh from this directory, and visit http://localhost:8080⁠ to view the Desktop of the Docker container. There you can run GNU Radio Companion and open flowgraphs from the apps directory here.

This web interface uses noVNC and you can find more info on using it at docker-ubuntu-vnc-desktop⁠, the site for the base Docker image. See also our GNU Radio-related instructions at gnuradio-companion-docker⁠.

Take a look at start_docker_grc.sh and the Dockerfile for more details.

⁠Running

There are GNU Radio flowgraphs in apps/ that you can "compile" and run as follows:

grcc <flowgraph>.grc
python <flowgraph>.py # run the generated python file

You can also open the flowgraph in GNU Radio Companion⁠ and click "generate" instead of using grcc

These flowgraphs are:

⁠apps/equisat.grc

This flowgraph listens for packets from a UDP audio stream from the GQRX SDR software or other frontends (see below). Usually all you need to do is click the "UDP" button in the bottom right of the GQRX interface, but if you have reconfigured GQRX you may need to specify a host and port to the Python script; see python equisat.py --help for how to.

If you don't have or don't want to use GQRX as a frontend, check out gr-frontends⁠ for alternative scripts that also stream over UDP. This repo provides frontends for SDRs, file sources, and other sources. For Windows, it is possible to use SDR# with this plugin⁠ to stream UDP audio and track the satellite.

If any complete packets are successfully received, they will be printed to the screen along with the data fields found in the packet. To automatically publish good packets to Brown Space Engineering's database, see below.

⁠apps/equisat_fm_input.grc

This flowgraph does essentially the same decoding as equisat.grc, but requires that you specify a FM-demodulated wav file to use as input using the --wavfile= parameter. It also does not publish to our API yet. You may also need to specify --sample-rate if your file was not recorded at 48kHz.

⁠Optimizing performance

The decoder is still in development, and performance can benefit from some tuning to a specific setup. Here are some variables in the flowgraphs worth tuning:

• gain_mu - this is a parameter for the MM Clock Recovery block for recovering the 4FSK symbols. GNU Radio documentation⁠ suggests that the optimal setting of this variable is dependent on the amplitude of the FM-demodulated audio coming into the flowgraph (i.e. the amplitude of the symbols). We've found that the correct tuning can make a significant difference in decoding quality. Generally decreasing the value is most helpful; overly large values can result in instability.

• Min premable length (EQUiSat 4FSK Preamble Detector) - this is a parameter that controls the minimum length of preamble is required for the decoder to try and search for the sync word and subsequently decode the following blocks. Decreasing it can allow the decoder to find more packets, but it is unlikely to improve the quality of the demodulated data, and setting it far too low can have an adverse impact on packet quality and detect preambles from noise.

⁠Publishing to telemetry databases

You can publish good EQUiSat packets to both Brown Space Engineering's database server and db.satnogs.org⁠ (extra dependency needed) by specifying the following as command line arguments to the flowgraphs above:

• A station name/callsign
• Your latitude/longitude (optional)
• If you're replaying a recording, the UTC time it started at
• An API key. To generate one, run the generate-api-key.sh script in the root of the repository.

You can run python equisat.py --help for specifics. We'd really appreciate it if you send your data!

To publish to db.satnogs.org, you'll need to install the gr-satellites⁠ module to get the required telemetry forwarder block.

⁠Understanding the telemetry

You can find a description of all the fields presented in EQUiSat's telemetry in this table⁠ of signal names. The document also has tabs with descriptions of the satellite's error code types, error "locations" (essentially error "categories"), and detailed information on the bitwise message layout.

You can also check out how those signals our presented on the EQUiSat web app⁠ or our mobile apps, to get a better understanding of which systems we pay the most attention to.

Finally, for an in-depth view, you can check out our systems block diagram⁠ for a more complete view of where the signals come from.