FreeDV + Horus Binary Setup & Usage Instructions

Mark Jessop 2020-06-21 [email protected]

This page contains documentation for installing, configuring, and using FreeDV and the horusbinary.py script within this repository to decode Horus Binary Telemetry from the Project Horus binary telemetry payloads. The first flight of this payload was on Horus 49, where it performed well. All flights since then have flown this telemetry.

IMPORTANT NOTE: FreeDV 1.4.1 will be the last FreeDV version with Horus Binary decode support. We will be moving to a standalone decoder application. Copies of the FreeDV 1.4.1 installers will be available here until this occurs.

For more detail on the modulation, refer to the main horusbinary page, and David Rowe's blog post.

1 - Hardware Requirements

The Horus Binary mode uses a narrow bandwidth (~1kHz), and can be received using a regular single-sideband (SSB) radio receiver. This could be a 'traditional' receiver (like a Icom IC-7000, Yaesu FT-817 to name but a few), or a software-defined radio receiver. The point is we need to receive the on-air signal (we usually transmit on 70cm) with an Upper-Sideband (USB) demodulator, and then get that audio into your computer.

If you are using a traditional receiver, you'll likely either have some kind of audio interface for it, or will be able to connect an audio cable between it and your computer's sound card. Easy!

With a RTLSDR, you will need to use software like GQRX (Linux/OSX), SDR#, or SDR Console to perform the USB demodulation. You'll then need some kind of loop-back audio interface to present that audio as a virtual sound card. This can be done using:

• Linux - via the snd-aloop module. Some information on this is here.
• OSX - Using the SoundFlower application.
• Windows - Use VBCable

You're also going to need some sort of antenna to receive the signal from the balloon payload, but I figure that's a bit out of scope for this guide! Just know that the Horus Binary demodulator is very robust, and you can often receive the signal using a very modest antenna setup.

2 - Installation of FreeDV & Dependencies

2.1 - Installation of FreeDV

The additions to FreeDV that allow decoding of the Horus Binary telemetry have been in place since version 1.4.

There are a few options to obtaining the latest version of FreeDV:

Windows

Under Windows, you can get installers here: https://rfhead.net/horus/freedv/

Currently (2019-12-23) the FreeDV v1.4.1 includes the HorusBinary decoder. Older versions (1.3.1) do not.

Linux

As FreeDV no longer supports the Horus data modes, and compiling an older version of FreeDV is extremely difficult, I would recommend using the new in-development Horus-GUI application for decoding signals under Linux.

Information on how to set this up is available here: https://github.com/projecthorus/horus-gui#usage

OSX

A disk image (DMG) for OSX is available at https://rfhead.net/horus/freedv/

Alternatively, use the Horus-GUI application: https://github.com/projecthorus/horus-gui#usage

2.2 - Horus Binary Uploader

While FreeDV will perform the demodulation of the MFSK telemetry, we still need to upload it to the HabHub Balloon Tracker for it to be useful. This function is currently performed by the horusbinary.py Python script, contained within this repository.

If your system already has Python, then you're most of the way to running this script! Otherwise, you will need to download a few things.

Windows

The easiest way to get going under windows is using the compiled version of the uploader script. This is available for 64-bit Windows 7/10 as a zip file here: http://rfhead.net/horus/horusbinary_20200208.zip

NOTE - THIS WILL NOT WORK ON 32-BIT WINDOWS INSTALLS.

Another note - Some users have reported the compiled horusbinary.exe causes false-positive trips on some virus scanners heuristic detection. This is a known issue with pyinstaller (the program I'm using to compile with), and has been reported to the various virus scanner vendors.

You can just un-zip this and run horusbinary.exe from within the directory (after modifying the config file - see below). Once you've done this, you can skip ahead to the configuration section.

If for some reason you can't use the compiled version of the uploader, then the Anaconda Python distribution provides almost all the dependencies required to run the script directly. Download and install the latest version of Anaconda. When installing make sure the 'Add Anaconda Python to system PATH' tick-box is checked, else the below commands will not work.

Once Anaconda is installed, grab the rest of the required dependencies by opening an administrator command prompt, and running:

> pip install crcmod python-dateutil

Linux

Under Linux (Ubuntu/Debian) install the required packages using:

$ sudo apt-get install git python-crcmod python-requests python-pip sox bc

Under OSX, Macports or Homebrew should be able to provide the above packages, though they might use slightly different names.

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.

Once these dependencies are downloaded, 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.

3 - Configuration

3.1 - Configuring FreeDV

FreeDV is normally used for two-way digital voice communication over HF. When using it for decoding the Horus Binary telemetry, we only make use of the RX functions of the software.

Audio Configuration

First up, we need to tell FreeDV what audio interfaces we are going to use. We need one interface to receive the USB-demodulated audio with, and another for a 'monitor' output, so we can listen to the telemetry.

First up, open FreeDV, and go to Tools -> Audio Config

Within this dialog, we need to configure a 'From Radio' and 'To Speaker/Headphones' sound card:

In the screenshot above, I'm using a 'VB-Cable' output so I can get audio from a SDR-receiver application, but you could also use a regular Line-In and use audio from a standard single-sideband receiver. I've set the output to my computer's speakers.

The sample rates for both devices both need to be set the same (either 44100 or 48000 is fine), otherwise FreeDV will complain. Finally, in the 'Transmit' tab, set both the 'From Microphone' and 'To Radio' devices to 'none' (if they aren't set to this already).

3.2 - Configuring the Horus Binary Uploader

Within the horusbinary directory (which you should have downloaded or git-cloned earlier), copy the example configuration file user.cfg.example to user.cfg, i.e. (under linux):

$ cp user.cfg.example user.cfg

This file then needs to 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 decription of your radio/antenna setup.
radio_comment = Your Radio Description Here
antenna_comment = Your Antenna Description Here

4 - Operation

4.1 - Starting FreeDV

To start receiving telemetry with FreeDV, open up FreeDV, select 'HorusB' from the mode list at the right, and click 'Start'. A few points to note:

• The bar-graph on the left of the screen shows received SNR, which will only start updating once packets are being received. Packets can be reliably decoded with SNRs greater than -5 dB.
• The raw binary telemetry packet is shown in the text-box at the bottom of the screen. This will update as telemetry is received.
• The 'bits' field on the left of the window will increment by 22 units as packets are received.
• Unlike fl-digi, you do not need to select the signal in the waterfall. The MFSK demodulator will detect and lock-on to the signal automatically. Note that the signal needs to be as close as possible to the centre of the display for decoding to work correctly.

You now have a working decoder - Congratulations! Now we need to upload the received telemetry to the internet...

4.2 - Starting the Horus Binary uploader.

The Horus Binary uploader can be started by simply running the python script:

$ python horusbinary.py

If you are using the Windows build, just run horusbinary.exe by double-clicking on it.

Output will be similar to the following:

You should now be able to view uploaded telemetry on the HabHub Balloon Tracker. If you set your latitude/longitude in the configuration file, your station should show up on the map as a small antenna tower icon (this may take a few minutes to appear).

4.3 - Testing with a sample recording

You can play-back a sample recording which can be downloaded here.

To do this, within FreeDV go to the Tools menu, and click 'Start/Stop Play File - From Radio', then select the downloaded file.

5 - Troubleshooting

This binary telemetry system is very new, and while we have performed a lot of testing, there may be bugs!

If you have issues installing or running the software, please contact me.

If you encounter a situation where you can hear/see a clear signal, but it does not appear to be decoding, then please get an audio recording so we can figure out what went wrong. You can capture an audio recording within FreeDV by clicking Tools -> Start/Stop Record File - From Radio.

Good luck!