This page contains documentation on receiving Horus Binary telemetry using GQRX, and the command-line demodulator provided in this repository. It is targeted at Linux and OSX platforms. For reception under Windows, use the FreeDV Guide.

Using GQRX allows reception of the HorusBinary signal using a wide range of Software Defined Radios, including RTLSDR, Airspy, LimeSDR, Funcube Dongle, HackRF and more!

1 - Getting GQRX

Refer to the GQRX webpage for information on obtaining GQRX for your particular platform.

In many cases, GQRX may be available through your Linux distributions package manager, and hence could be installed using something like sudo apt-get install gqrx. Under OSX GQRX can be obtained using Macports or Homebrew.

There is a great guide to setting up GQRX available here. This uses the Funcube Dongle as an example, but is applicable to other SDRs also.

Once you have set up GQRX to work with your SDR and are familiar with its usage, continue on with the rest of this guide.

2 - Software Dependencies & Compilation

We may require a few dependencies to be able to compile and use the new modem and uploader scripts. Under Ubuntu/Debian/Raspbian, you can install the required packages using:

$ sudo apt-get install subversion cmake build-essential libfftw3-dev libspeexdsp-dev libsamplerate0-dev libusb-1.0-0-dev git python-crcmod python-requests python-pip sox bc

Under OSX, Macports or Homebrew should be able to provide the above packages, though they may be named slightly differently.

If the python-crcmod and python-requests packages are not available via your package manager, you can try installing them via pip using sudo pip install crcmod requests.

2.1 - Downloading this Repository

You can either clone this repository using git:

$ git clone https://github.com/projecthorus/horusbinary.git

or download a zip file of the repository from here.

2.2 - Compiling Horus-Demod

We need to compile the horus_demod binary (taken from the codec2 repository). This can be accomplished by performing (within this directory):

$ cd src
$ make
$ cd ../

3 - Configuration File Changes

Copy the example configuration file user.cfg.example to user.cfg, i.e.:

$ cp user.cfg.example user.cfg

The file user.cfg should then be modified to reflect the callsign you wish to use when uploading data to Habitat. Simply change the following section as appropriate:

[user]
# Your callsign -  used when uploading to the HabHub Tracker.
callsign = YOUR_CALL_HERE

# Your station latitude/longitude, which will show up on tracker.habhub.org.
# These values must be in Decimal Degree format.
# Leave the lat/lon at 0.0 if you do not wish your station plotted on the map,
# or if you are uploading your position via other means (i.e. using chasemapper)
station_lat = 0.0
station_lon = 0.0
# Radio/Antenna descriptions.
# An optional short description of your radio/antenna setup.
radio_comment = Your Radio Description Here
antenna_comment = Your Antenna Description Here

4 - Tuning in with GQRX

Startup GQRX, and configure the receiver options to receive in 'USB' mode, with either a Normal or Wide filter width. Tune the receive such that the Horus Binary signal is completely contained within the filter passband, as shown in the following figure:

We now need to configure GQRX to output audio samples via UDP. At the bottom-right of the GQRX window, click the '...' button, which will open up a small window. Go to the network tab in this window, and configure to use a hostname of 'localhost' and a port of 7355:

You can then close this window, and activate the UDP output by clicking the 'UDP' button.

5 - Starting up the Demodulator

To start up the demodulator and uploader, open a new terminal, and navigate to your horusbinary directory. Within the directory, run the command:

$ ./start_gqrx_rx.sh

You can also append --noupload, which will disable uploading of telemetry to the internet for local testing purposes.

Once started, you should see output similar to the following:

$ ./start_gqrx_rx.sh
Found horus_demod.
Setting estimator limits to 100 to 10000 Hz.
2020-02-09 16:22:44,673 INFO: Attempting to download latest payload ID list from GitHub...
2020-02-09 16:22:45,076 INFO: Payload ID list updated successfully.
2020-02-09 16:22:45,077 INFO: Known Payload IDs:
2020-02-09 16:22:45,077 INFO: 	0 - 4FSKTEST
2020-02-09 16:22:45,077 INFO: 	1 - HORUSBINARY
2020-02-09 16:22:45,077 INFO: 	2 - VK5BRL
2020-02-09 16:22:45,077 INFO: 	3 - STRATOS
2020-02-09 16:22:45,077 INFO: 	4 - HORUSBINARY2
2020-02-09 16:22:45,078 INFO: 	5 - HORUSBINARY3
2020-02-09 16:22:45,078 INFO: 	6 - PE2BZ-4FSK
2020-02-09 16:22:45,078 INFO: 	7 - SP8NCG-4FSK
2020-02-09 16:22:45,079 INFO: 	8 - PY2UEP-4FSK
2020-02-09 16:22:45,081 INFO: 	9 - PC4L-4FSK
2020-02-09 16:22:45,081 INFO: 	10 - HAPPYSAT-4FSK
2020-02-09 16:22:45,082 INFO: 	11 - PH1M-4FSK
2020-02-09 16:22:45,082 INFO: 	12 - DK0WT-4FSK
2020-02-09 16:22:45,082 INFO: 	13 - PE1ANS-4FSK
2020-02-09 16:22:45,083 INFO: 	23 - MAGNU
2020-02-09 16:22:45,085 INFO: Using User Callsign: VK5QI-9
2020-02-09 16:22:45,086 INFO: No user position supplied, not uploading position to Habitat.
2020-02-09 16:22:45,088 INFO: Started Habitat Uploader Thread.
2020-02-09 16:22:45,088 INFO: Waiting for data on stdin.
2020-02-09 16:22:45,089 INFO: Started Horus Binary Uploader. Hit CTRL-C to exit.

As packets are received, further output will be shown:

2020-02-09 16:37:21,591 INFO: Hexadecimal Sentence: 00010000000000000000000000000000000025A05E64
2020-02-09 16:37:21,596 INFO: Decoded Binary Telemetry as: $$4FSKTEST,1,00:00:00,0.00000,0.00000,0,0,0,37,3.14*2E72
2020-02-09 16:37:21,598 ERROR: Could not parse ASCII Sentence - Zero Lat/Long.
2020-02-09 16:37:21,598 ERROR: Horus UDP - Zero Latitude/Longitude, not sending.
2020-02-09 16:37:23,049 INFO: Habitat - Uploaded sentence to Habitat successfully

(In this example, the payload does not yet have GPS lock.)

Congratulations! You are now decoding and uploading Horus Binary telemetry! If the payload has GPS lock, you should be able to visit the Habhub Tracker and see the payload on the map.

To close, just hit Ctrl-C, or close the terminal.