FREEDV GUI USER MANUAL
FreeDV GUI (or just FreeDV) is a GUI program for Linux, Windows, and OSX for running FreeDV on a desktop PC or laptop.
This document is a work in progress. Notes on new FreeDV features are being added as they are developed.
FreeDV GUI can be challenging to set up. The easiest way is to find a friend who has set up FreeDV and get them to help. Alternatively, this section contains several tips to help you get started.
Sound Card Configuration
For Receive only operation you just need one sound card, this is a great way to get started.
For Tx/Rx Operation, you need two sound cards. One connects to your radio, and one for the operator. The sound card connecting to the radio can be a rig interface device like a Signalink, Rigblaster, your radio's internal USB sound card, or a home brew rig interface.
The second sound card is often a set of USB headphones, or your computers internal sound card.
Receive Only (One Sound Card)
Start with just a receive only station. You just need the basic sound hardware in your computer, for example a microphone/speaker on your computer.
- Open the Tools - Audio Config Dialog
- At the bottom select Receive Tab
- In From Radio To Computer select your default sound input device (usually at the top)
- In the From Computer To Speaker/Headphone window select your default sound output device (usually at the top)
- At the bottom select Transmit Tab
- In From Microphone window select none
- In To Radio window select none
- Press OK to close the dialog
When you press Start FreeDV will start decoding any incoming signals on the microphone input, playing the decoded audio out of your speaker. If no valid FreeDV signals are received, no audio will be played.
If you connect the microphone input on your computer to your radio receiver, you can decode off air signals. If you have a rig interface, try configuring that as the From Radio To Computer device, with your computers sound card as the From Computer To Speaker/Headphone device.
If you don't have anyone to transmit FreeDV signals to you, try the test wave files in the next section.
Test Wave Files
In the wav directory are audio files containing off-air FreeDV modem signals. There is one for each FreeDV mode. Select a FreeDV mode and press Start. Choose a file using "Tools - Start/Stop Play File From Radio". You should hear decoded FreeDV speech.
These files will give you a feel for what FreeDV signals sound like, and basic operation of the FreeDV software.
Transmit/Receive (Two Sound Cards)
For Tx/Rx operation you need to configure two sound cards, by setting up Tools - Audio Config Transmit and Receive Tabs.
When receiving, FreeDV off-air signals from your radio are decoded by your computer and sent to your speaker/headphones, where you can listen to them.
When transmitting, FreeDV takes your voice from the microphone, and encodes it to a FreeDV signal in you computer which is sent to your radio for transmission over the air.
|Receive Tab||From Radio To Computer||The off air FreeDV signal from your radio rig interface to your computer|
|Receive Tab||From Computer To Speaker/Headphone||The decoded audio from your computer to your Speaker/headphones|
|Transmit Tab||From Microphone to Computer||Your voice from the microphone to your computer|
|Transmit Tab||From Computer To Radio||The FreeDV signal from your computer sent to your radio rig interface for transmission|
Sound Card Levels
Sound card levels are generally adjusted in the computers Control Panel or Settings, or in some cases via controls on your rig interface hardware or menus on your radio.
When FreeDV is running, you can observe the sound card signals in the main window tabs (From Radio, From Mic, To Speaker).
On receive, FreeDV is not very sensitive to the From Radio level, adjust so it is mid range and not clipping. FreeDV uses phase shift keying (PSK) so is not sensitive to amplitude.
The transmit level from your computer to your radio is important. On transmit, adjust your level so that the ALC is just being nudged. More is not better with the FreeDV transmit signal. Over driving your transmitter will lead to a distorted transit signal, and a poor SNR at the receiver. This is a very common problem.
Adjust the microphone audio so the peaks are not clipping, and the average is about half the maximum.
FreeDV likes a clean path through you radio. Turn all audio processing OFF on transmit and receive:
On receive, DSP noise reduction should be off.
On transmit, speech compression should be off.
Keep the receive audio path as "flat" as possible, no special filters
FreeDV will not work any better if you band pass filter the off air received signals. It has it's own, very tight filters in the demodulator.
The Tools - PTT dialog supports three different ways to control PTT on your radio:
- VOX: sends a tone to the left channel of the Transmit/To Radio sound card
- HamLib: support for many different radios via the HamLib library and a serial port
- Serial Port: Direct access to the Serial port pins
Once you have configured PTT, try the Test button.
Serial PTT support is complex. We get many reports that FreeDV PTT doesn't work on a particular radio, but may work fine with other programs such as Fldigi. This is often a mis-match between the serial parameters Hamlib is using with FreeDV and your radio. For example you may have changed the default serial rate on your radio. Carefully check the serial parameters on your radio match those used by FreeDV in the PTT Dialog.
Hamlib comes with a default serial rate for each radio. If your radio has a different serial rate change the Serial Rate drop down box to match your radio.
When Test is pressed, the "Serial Params" field is populated and displayed. This will help track down any mis-matches between Hamlib and your radio.
If you are really stuck, download Hamlib and test your radio's PTT
using the command line
Changing COM Port On Windows
If you change the COM port of a USB-Serial device in Device Manager, please unplug and plug back in the USB device. Windows/FreeDV won't recognise the device on the new COM Port until it has been unplugged/plugged.
Overdriving Transmit Level
This is a very common problem for first time FreeDV users. Adjust your transmit levels so the ALC is just being nudged. For a 100W PEP radio, you average power should be 20W.
More power is not better with FreeDV. An overdriven signal will have poor SNR at the receiver.
I can't set up FreeDV, especially the Sound Cards
This can be challenging the first time around:
Try a receive only (one audio card) set up first.
Ask someone who already runs FreeDV for help.
If you don't know anyone local, ask for help on the digital voice mailing list. Be specific about the hardware you have and the exact nature of your problem.
I need help with my radio or rig interface
There are many radios, many computers, and many sound cards. It is impossible to test them all. Many radios have intricate menus with custom settings. It is unreasonable to expect the authors of FreeDV to have special knowledge of your exact hardware.
However someone may have worked through the same problem as you. Ask on the digital voice mailing list.
Can't hear anything on receive
Many FreeDV modes will not play any audio if there is no valid signal. You may also have squelch set too high. In some modes the Analog button will let you hear the received signal from the SSB radio.
Try the Test Wave Files above to get a feel for what a FreeDV signal looks and sounds like.
Trouble getting Sync with 700D
You need to be within +/- 20 Hz on the transmit signal. It helps if both the tx and rx stations tune to known, exact frequencies such as exactly 7.177MHz. On channels with fast fading sync may take a few seconds.
PTT doesn't work. It works with Fldigi and other Hamlib applications.
Many people struggle with initial PTT setup:
Read the PTT Configuration section above.
Try the Tools - PTT Test function.
Check you rig serial settings. Did you change them from defaults for another program?
Ask someone who already uses FreeDV to help.
Contact the digital voice mailing list. Be specific about your hardware, what you have tried, and the exact nature of the problem.
The FreeDV 2020 mode button isn grayed out
You don't have AVX support on your CPU. FreeDV 2020 requires AVX to run.
Voice Keyer Button on Front Page, and Options-PTT dialog.
Puts FreeDV and your radio into transmit, reads a wave file of your voice to call CQ, then switches to receive to see if anyone is replying. If you press space bar the voice keyer stops. If a signal with a valid sync is received for a few seconds the voice keyer stops.
The Options-PTT dialog can be used to select the wave file, set the Rx delay, and number of times the tx/rx cycle repeats.
The wave file for the voice keyer should be in 8kHz mono 16 bit sample form. Use a free application such as Audacity to convert a file you have recorded to this format.
The following table is a guide to the different modes, using analog SSB and Skype as anchors for a rough guide to audio quality:
|Mode||Min SNR||Fading||Latency||Speech Bandwidth||Speech Quality|
The Min SNR is the roughly the SNR where you cannot converse without repeating yourself. The numbers above are on channels without fading (AWGN channels like VHF radio). For fading channels the minimum SNR is a few dB higher. The Fading column shows how robust the mode is to HF Fading channels, higher is more robust.
The more advanced 700D and 2020 modes have a high latency due to the use of large Forward Error Correction (FEC) codes. They buffer many frames of speech, which combined with PC sound card buffering results in end-end latencies of 1-2 seconds. They may take a few seconds to sync at the start of an over, especially in fading channels.
In mid 2018 FreeDV 700D was released, with a new OFDM modem, powerful Forward Error Correction (FEC) and optional interleaving. It uses the same 700 bit/s speech codec at 700C. It operates at SNRs as low as -2dB, and has good HF channel performance. It is around 10dB better than FreeDV 1600 on fading channels, and is competitive with SSB at low SNRs. The FEC provides some protection from urban HF noise.
FreeDV 700D is sensitive to tuning. To obtain sync you must be within +/- 20Hz of the transmit frequency. This is straight forward with modern radios which are generally accurate to +/-1 Hz, but requires skill and practice when used with older, VFO based radios.
The rest of this section describes features and options specific to FreeDV 700D.
Main GUI Page:
Separate indication of Modem and (for 700D) Interleaver Sync. The number on the Interleaver Sync indicator is the interleaver size in 160ms frames. This is usually set to 1.
ReSync button breaks 700D sync and forces it to try again. Useful if 700D gets a false sync in low SNR channels.
Tools - Options dialog:
Clipping: For 700C and 700D reduces the Peak/Average Power Ratio (PAPR) (also known as Crest Factor) from 12dB to 8dB by clipping the Tx signal. This will add a little noise to the Tx spectrum and Rx Scatter diagram, but MAY enable you to drive your Power Amplifier harder. Use with caution to avoid overloading your Power Amplifier.
Tx Band Pass Filter: limits the transmit bandwidth to about 1000 Hz. Usually left on.
700D Interleaver: The interleaver averages out errors over several frames, which improves performance for fast fading channels, and channels with burst errors. A 16 frame interleaver will improve performance by 4dB. However interleaving adds delay, and delays sync. Both the tx and rx must have the same interleaver setting. For example a setting of 2 means we average errors over 2 160ms frames, and introduces 2x160=320ms delay in both the Tx and Rx (640ms total). The interleaver is usually set to 1.
700D Manual Unsync: Sync must be broken manually (ReSync button) when this option is selected. Disables automatic falling out of sync. Experimental features that may be useful for ensuring 700D stays in sync during long fades, to avoid long resync delays with the interleaver.
FreeDV 2020 was released in mid 2019. It uses an experimental codec based on the LPCNet neural net (deep learning) synthesis engine developed by Jean-Marc Valin. It offers 8 kHz audio bandwidth in an RF bandwidth of just 1600 Hz. FreeDV 2020 employs the same OFDM modem and FEC as 700D.
The purpose of FreeDV 2020 is to test neural net speech coding over HF radio. It is highly experimental, and possibly the first use of neural net vocoders in a real world, over the air system.
FreeDV 2020 is designed for slow fading HF channels with a SNR of 10dB or better. It is not designed for fast fading or very low SNRs like 700D. It is designed to be a high quality alternative to SSB in channels where SSB is already an "aim-chair" copy. On an AWGN (non fading channel), it will deliver reasonable speech quality down to 2dB SNR.
You may encounter the following limitations with FreeDV 2020:
- Some voices may sound very rough. In early testing about 90% of speakers tested work well.
- Like 700D, you must tune within -/+ 20Hz for FreeDV 2020 to sync.
- With significant fading, sync may take a few seconds.
- There is a 2 second end-end latency. You are welcome to try tuning this (Tools - Options - FIFO size, also see Sound Card Debug section below).
- It requires a modern (post 2010) Intel CPU with AVX support. If you don't have AVX the FreeDV 2020 mode button will be grayed out.
- The audio in Analog mode is choppy.
Horus Binary Mode
Horus Binary mode (HorusB) High Altitude Balloon (HAB) telemetry using the same FSK modem as 2400A/B and 800XA.
Connect your UHF SSB radio to FreeDV, and it will output telemetry messages to the UDP port specified on Tools-Options "UDP Messages". For Project Horus work, the port 55690 is used. Check the "Enable UDP messages" checkbox.
You can test Horus telemetry decodes by "Playing" this test file.
using Tools - Start/Stop Play File - from Radio. On Linux, you can monitoring the messages using netcat:
$ nc -ul 55690
At the bottom of Tools-Options, the "APiVerbose" check box enables printing of verbose API debug messages to the console, which will also work in Windows if Tools-Options "Windows Debug Console" is checked.
A Python script is required to upload the telemetry messages to the HabHub server, please see https://github.com/projecthorus/horusbinary#usage---via-freedv
When FreeDV syncs on a received signal for 5 seconds, it will send a "rx sync" UDP message to a Port on your machine (localhost). An external program or script listening on this port can then take some action, for example send "spotting" information to a web server or send an email your phone.
Enable UDP messages on Tools-Options, and test using the "Test" button.
On Linux you can test reception of messages using netcat:
$ nc -ul 3000
An sample script to email you on FreeDV sync: https://svn.code.sf.net/p/freetel/code/freedv-dev/src/send_email_on_sync.py
Usage for Gmail:
$ python send_email_on_sync.py --listen_port 3000 --smtp_server smtp.gmail.com --smtp_port 587 firstname.lastname@example.org your_pass
Sound Card Debug
These features were added for FreeDV 700D, to help diagnose sound card issues during development.
Tools - Options dialog:
Debug FIFO and PortAudio counters: used for debugging audio problems on 700D. During beta testing there were problems with break up in the 700D Tx and Rx audio on Windows.
The PortAudio counters (PortAudio1 and PortAudio2) should not be incremented when running in Tx or Rx, as this indicates samples are being lost by the sound driver which will lead to sync problems.
The Fifo counter outempty1 counter should not be incremented during Tx, as this indicates FreeDV is not supplying samples fast enough to the PortAudio drivers. The results will be resyncs at the receiver.
Check these counters by pressing Start, then Reset them and observe the counters for 30 seconds.
If the PortAudio counters are incrementing on receive try:
Adjusting framesPerBuffer; try 0, 128, 256, 512, 1024.
Shut down other applications that might be using audio, such as Skype or your web browser.
A different sound card rate such as 44.1kHz instead of 48kHz.
If the outempty1 counter is incrementing on transmit try increasing the FifoSize.
The txThreadPriority checkbox reduces the priority of the main txRx thread in FreeDV which may help the sound driver thread process samples.
The txRxDumpTiming check box dumps timing information to a console that is used for debugging the rx break up problem on 700D. Each number is how many ms the txRxThread took to run.
The txRxDumpTiming check box dumps the number of samples free in the tx FIFO sending samples to the Tx. If this hits zero, your tx audio will break up and the rx will lose sync. Tx audio break up will also occur if you see "outfifo1" being incremented on the "Fifo" line during tx. Try increasing the FifoSize.
Test Frame Histogram
This feature was developed for testing FreeDV 700C. Select the Test Frame Histogram tab on Front Page
Displays BER of each carrier when in "test frame" mode. As each QPSK carrier has 2 bits there are 2*Nc histogram points.
Ideally all carriers will have about the same BER (+/- 20% after 5000 total bit errors). However problems can occur with filtering in the tx path. If one carrier has less power, then it will have a higher BER. The errors in this carrier will tend to dominate overall BER. For example if one carrier is attenuated due to SSB filter ripple in the tx path then the BER on that carrier will be higher. This is bad news for DV.
Transmit FreeDV in test frame mode. Use a 2nd rx (or get a friend) to monitor your rx signal with FreeDV in test frame mode.
Adjust your rx SNR to get a BER of a few % (e.g. reduce tx power, use a short antenna for the rx, point your beam away, adjust rx RF gain).
Monitor the error histogram for a few minutes, until you have say 5000 total bit errors. You have a problem if the BER of any carrier is more than 20% different from the rest.
A typical issue will be one carrier at 1.0, the others at 0.5, indicating the poorer carrier BER is twice the larger.
Full Duplex Testing with loopback
Tools - Options - Half Duplex check box
FreeDV GUI can operate in full duplex mode which is useful for development of listening to your own FreeDV signal as only one PC is required. Normal operation is half duplex.
Tx and Rx signals can be looped back via an analog connection between the sound cards.
On Linux, using the Alsa loopback module:
$ sudo modprobe snd-aloop $ ./freedv In Tools - Audio Config - Receive Tab - From Radio select -> Loopback: Loopback PCM (hw:1,0) - Transmit Tab - To Radio select -> Loopback: Loopback PCM (hw:1,1)
|AWGN||Additive White Gaussian Noise - a channel with just noise and no fading (like VHF)|
|FEC||Foward Error Correction. Extra bits to we send to protect the speech codec bits|
|LDPC||Low Density Parity Check Codes, a powerful family of FEC codes|
|V1.4||June 2019||Project Horus Binary Mode, FreeDV 2020|
|V1.3||May 2018||FreeDV 700D|