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

This program is an implementation of M-ary Frequency Shift Keying
modulation for amateur radio communications. Originally the program aimed
only at being compatible with the IZ8BLY Stream program in MFSK16 mode.
However currently the program also implements other FSK based modes,
namely RTTY and THROB.

MFSK16
======

The MFSK support currently only covers the default mode with 16 tones at
15.625 symbols per second and R=1/2, K=7 (NASA standard polynomials)
convolutional encoding. This mode is known as MFSK16. I will implement
MFSK8 in the future.

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. Actually I'm not at all happy with the current algorithm but
it seems to work fairly well at least with strong signals.

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

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 can be stopped (and restarted) by right clicking
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.

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 mode, MFSK16. Special thanks to Murray for the technical
documentation.

Thanks also to Jesús 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.

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>
