gMFSK v0.5 - The Gnome MFSK terminal program
============================================

gMFSK is a multi-mode soundcard terminal program for HF amateur
communications. Originally the program was written for compatibility
with the IZ8BLY Stream program in MFSK16 mode. Currently the program
supports the following amateur digital communications modes: MFSK16,
MFSK8, RTTY, THROB, PSK31, MT63 and FELDHELL.

MFSK
====

The MFSK modem supports two modes:

 MFSK16	- 16 tones, 15.625 symbols per second
 MFSK8	- 32 tones, 7.8125 symbols per second

Both modes use convolutional encoding (R=1/2, K=7, NASA standard
polynomials) and viterbi decoding.

RTTY
====

RTTY support in gMFSK should be considered experimental. I have tried a
few decoding algorithms and the one currently in use is not necessarily
the best one.

All the parameters (shift, baudrate, number of bits, parity, number of
stopbits) are almost freely configurable. There is also a separate
"reverse" setting for RTTY which you probably want to enable if you want
to use USB to work RTTY.

The "MSB first" option is needed for the ASCII modes. Or at least when I
tested the modem against MMTTY (http://www.qsl.net/mmhamsoft/mmtty/) it
was.

THROB
=====

Throb support is also to be considered experimental. When you enable THROB
you will see a red vertical line in the sync scope window. This vertical
line represents the symbol synch timing and you should adjust it to follow
the minimum between consecutive symbols (click with left mouse button to
adjust the sync position). This obviously works well only if the sound
card sample rates at both ends are fairly accurate. Unfortunately it seems
that sound card hardware and possibly certain driver software (from
redmond) is all but accurate. Implementing a working automatic sync method
is on my TODO list.

For more information about THROB please check Lionel's web page
(http://www.lsear.freeserve.co.uk/page3.html).

PSK31
=====

PSK31 support in gMFSK borrows heavily from the C++ modem classes written
by Hansi Reiser DL9RDZ (which in turn is partly derived from the work of
Andrew Senior G0TJZ and Peter Martinez G3PLX). While I have not used any
code directly, much of the architecture and algorithms are almost
directly copied from there. As a result I think the PSK31 support is
pretty mature.

MT63
====

The MT63 modem uses source code written by Pawel Jalocha SP9VRC. I have
only written a few lines of glue code to integrate Pawel's code to my
framework. The modem should be pretty mature. I haven't done much
testing but it does decode real life signals. There is no support for
the IZ8BLY style secondary channel (yet).

FELDHELL
========

Feldhell is a last minute addition to this release of the program. Only
RX is currently supported. I have a fully working transmitter but I
have yet to figure out how to render the fonts for transmission under
GTK+ 2.0. (I have it working under GTK+ 1.2.)

Operating
=========

Operating gMFSK should be easy to learn even without much help if you have
any experience in operating with other modern soundcard digital modes. The
MFSK web site (http://www.qsl.net/zl1bpu/MFSK/) is suggested reading for
background information. Also the help in IZ8BLY Stream program could prove
useful. Note however that tuning in gMFSK works a little different to that
in Stream.

Setting audio levels is very important. The scope display should prove a
nice tool for setting the incoming audio level. However be aware that the
amplifier stages before the sound card mixer can also be overdriven
without showing signs on the scope display.

On transmit you should be just as careful. Overdriving MFSK or RTTY
doesn't produce intermodulation products as there is only one tone
transmitted at a time but harmonic products (of the audio) are always
present when overdriving. THROB on the other hand does produce
intermodulation products as most of the possible symbols use two tones.

The GUI
=======

The graphical user interface should for the most part be self explanatory.
From top to bottom there are the Menubar, Toolbar, QSO data area, Received
text, Transmitted text, Preconfigured messages buttons and the Waterfall
indicator area. In addition to the obvious there are a few additional
tricks:

As with any Gnome application the Menubar and Toolbar areas are
dockable, ie. you can drag them around the desktop or the application
window.

The received text and the QSO data area are of course subject to the
normal X Window Selection system: dragging with the left button selects
text and the middle button pastes the selected text. However the received
text area also implements an additional trick with the right button.
Clicking the right button over a word selects the word and opens a context
menu where you can select where you want the selected data to be pasted.

The waterfall display configuration dialog opens when you right click
over it.

The "Log entry" button sends the QSO data to logging program using inter
process communication (IPC). Currently only xlog
(http://savannah.gnu.org/projects/Xlog) supports this feature.

The "New entry" button clears all the QSO data fields and resets the QSO
time (the first change after a reset on any of the QSO data fields sets
the time).

The most used functions now have keyboard accelerators. Fixtext buttons
show the associated function keys in their labels and the other buttons
tell you the accelerator in their tooltips ie. when you hover the mouse
pointer above the button (be sure to enable tooltips in gnome config).

All in all, I recommend experimenting with the GUI before having real
contacts.

Macros
======

The predefined text buttons can contain macros. Macros start with the
letter $. A standard macro is of the form $text. A list of available
standard macros is here:

  $$		- The letter '$'
  $tx		- Push the TX button.
  $rx		- Push the RX button.
  $pause	- Push the Pause button.
  $abort	- Push the Abort button (this is probably of no use to anyone).
  $mycall	- Callsign as defined in preferences.
  $myname	- Name as defined in preferences.
  $myqth	- QTH as defined in preferences.
  $myloc  	- Locator as defined in preferences.
  $myemail	- Email address as defined in preferences.
  $time		- Local time.
  $utctime	- Universal Coordinated Time.
  $date		- Local date.
  $utcdate	- UTC date.
  $call		- Other partys callsign taken from QSO data.
  $band		- Band taken from QSO data.
  $rxrst	- Received RST taken from QSO data.
  $txrst	- Transmitted RST taken from QSO data.
  $name		- Other partys name taken from QSO data.
  $qth		- Other partys QTH taken from QSO data.
  $notes	- Notes taken from QSO data.
  $soft		- Software version.
  $mode		- Currently active mode name.

In addition to standard macros you can use so called command substitution
with a macro of the form $(command). The command specified is executed in
a shell and its output is captured. All the normal shell redirections,
pipelines etc. can be used. At the most 4096 characters of the command
output is captured and if the last captured characted is a newline it is
deleted.

The macros are evaluated at the time the button is pressed (as opposed to
being evaluated during the transmission) which is a significant fact
especially with the "push ... button" and date/time macros.

An unrecognized $-macro is ignored.

Disclaimer
==========

This program is something I wrote for my own amusement. I'm not a
professional DSP engineer (though I may want to be one in the future) and
I'm certainly not a GUI programmer nor do I ever want to be one.
Suggestions especially for the GUI part are more than welcome!

Hopefully the program is of use to you!

Thanks
======

Thanks to Murray ZL1BPU and Nino IZ8BLY for creating a very cool ham
communication modes, MFSK16 and MFSK8. Special thanks to Murray for the
technical documentation of MFSK16/8 and Hellschreiber.

Thanks also to Jess EB1DIX for his RTTY decoder program for Linux. I used
that software as the base for my experiments and a lot of ideas was
borrowed from it.

Likewise thanks to Lionel G3PPT for making Throb source code publically
available. Again lot was learned just by browsing through it.

Thanks to Hansi DL9RDZ for his PSK31 C++ classes and the work of Andrew
G0TJZ and Peter G3PLX on which the classes are based on.

Special thanks to Pawel SP9VRC for his work on MT63 and the source code
for it. 

Also many thanks to Phil KA9Q and Charles G4GUO for giving ideas and/or
code for the project. Neither probably knew about this project but that's
simply what free software is, everyone benefits from it!

Last but not least many thanks to Joni OH2NJR/OH2MUI for providing me with
feedback and equipment to be able to develop and test the stuff.....

-- 
Tomi Manninen, OH2BNS <oh2bns@sral.fi>
