======================
FREEDV GUI USER MANUAL
======================

Introduction
------------

This document describes additional features in the latest FreeDV
releases that haven't been documented in other sources.  See also
freedv.org

FreeDV V1.3, May 2018
---------------------

FreeDV GUI 1.3 includes the new 700D mode, which has a new modem and
powerful Forward Error Correction (FEC) and optional interleaving.  It
uses the same 700 bit/s speech codec at 700C. It operates error free
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.

Main GUI Page:

  1) Separate indication of Modem and (for 700D) Interleaver Sync. The
     number On the Interleaver Sync indicator is the interleaver size
     in 160ms frames.
     
  2) ReSync button breaks 700D sync and forces it to try
     again.  Useful if 700D gets a false sync in low SNR channels.

Tools - Options:

  1) 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).

  2) 700D Manual Unsync: Sync must be broken manually (ReSync button)
     when this option is selected.  Disables automatic falling out of
     sync. May be useful for ensuring 700D stays in sync during long
     fades, to avoid long resync delays with the interleaver.

  3) 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.
     
  4) 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:

     a) Adjusting framesPerBuffer; try 0, 128, 256, 512, 1024.

     b) Shut down other applications that might be using audio, such
        as Skype or your web browser.

     c) A different sound card rate such as 44.1kHz instead of 48kHz.
     
     If the outempty1 counter is incrementing on transmit try:

     d) 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.
     
  5) UDP Messages: 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.  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 your@gmail.com your_pass
     
Changing COM Port On Windows, May 2018
---------------------------------------

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.

PTT Configuration
-----------------

Tools-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.

Serial PTT support is complex.  We get many reports that FreeDV Hamlib
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.

If you are really stuck, download Hamlib and test your radio's PTT
using the command line rigctl program.

Voice Keyer 
-----------

Voice Keyer Button on Front Page
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.

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.

Test Frame Histogram
--------------------

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.

Suggested usage: 

i) 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.  

ii) 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).  

iii) 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
---------------------------------

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)

TODO
----

[ ] Merge this information into existing start up guides

