Join GitHub today
FreeDV HorusBinary Setup & Usage Instructions
FreeDV + Horus Binary Setup & Usage Instructions
Mark Jessop 2018-07-22 firstname.lastname@example.org
This page contains preliminary documentation for installing, configuring, and using FreeDV and the horusbinary.py script within this repository to decode MFSK Telemetry from the Project Horus binary telemetry payloads. The first flight of this payload was on Horus 49, where it performed well. Further Project Horus flights will be using this mode as the primary telemetry downlink.
This documentation is a counterpart to that contained within the main README.md, and is targeted at users that may be new to the FreeDV application.
1 - Installation of FreeDV & Dependencies
1.1 - Installation of FreeDV
The additions to FreeDV that allow decoding of the Horus Binary telemetry have only been in place since SVN revision 3709. At the time of writing this document, most released packages of FreeDV are older than this.
There are a few options to obtaining the latest version of FreeDV:
Under Windows, we have pre-built installers available here: http://rowetel.com/downloads/freedv/
Download the version with the highest SVN revision available, and with the architecture (win32/win64) appropriate to your system. It should work fine on Windows 7 through 10.
Under Linux, your best bet is to compile FreeDV from source. There are good instructions on how to do this available here: https://svn.code.sf.net/p/freetel/code/freedv-dev/README.txt Note that the FreeDV versions that are in most distributions package repositories will not have the latest updates required to decode Horus Binary!
There are currently some bugs when running FreeDV under OSX which have not yet been resolved. Sorry :-(
1.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.
Note: There is a compiled (using 'pyinstaller') version of this script for 64-bit Windows available as a zip file here: http://rfhead.net/horus/horusbinary_20181014.zip You can just un-zip this and run horusbinary.exe from within the directory (after modifying the config file - see below). THIS WILL NOT WORK ON 32-BIT WINDOWS INSTALLS.
Under Windows, the Anaconda Python distribution provides almost everything you need. Download and install the Python 2.7 version of Anaconda. When installing make sure the 'Add Anaconda Python to system PATH' tickbox 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
Under Linux (Ubuntu/Debian) install the required packages using:
$ sudo apt-get install git python-numpy python-pyqtgraph python-crcmod python-requests python-pip
Under OSX, Macports or Homebrew should be able to provide the above packages.
If the python-pyqtgraph, python-crcmod and python-requests packages are not available via your package manager, you can try installing them via pip using
sudo pip install pyqtgraph 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.
2 - Configuration
2.1 - Configuring FreeDV
FreeDV is normally used for two-way digital voice communication over HF. When using it for decoding the Horus MFSK telemetry, we only make use of the RX functions of the software.
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 USB 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).
UDP Messaging Output
FreeDV communicates with the
horusbinary.py script via UDP messaging, which needs to be enabled.
Open the 'Options' dialog from Tools -> Options, and:
- Tick the 'Enable UDP Messages' checkbox.
- Set the UDP Port Number to: 55690
Check this one carefully! If this setting is off, or the wrong port is set, you will not be able to upload packets to HabHub!
2.2 - Configuring the Horus Binary Uploader
Within the horusbinary directory (which you should have downloaded or git-cloned earlier), the file
user.cfg should 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. 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
3 - Operation
3.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.
You now have a working decoder - Congratulations! Now we need to upload the received telemetry to the internet...
3.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.
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 - Troubleshooting
This binary telemetry system is very new, and while we have performed a lot of testing, there may be bugs!
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.
4.1 - Debug Logs
The horusbinary uploader writes two log files, 'telemetry.log' and 'horusb_debug.log', which are useful to us for debugging purposes. It would be appreciated if listeners of Project Horus flights e-mail both these files through to David & Mark (see above) after the flight to help evaluate the performance of the new Horus Binary modem.