gMFSK - The Gnome MFSK terminal program
=======================================

This program is an implementation of M-ary Frequency Shift Keying
modulation for amateur radio communications. It is a digital communication
mode intended for keyboard to keyboard QSO's over challenging HF
propagation conditions. The main goal for the program is interoperability
with the IZ8BLY Stream program in MFSK16 mode. However the rather strange
licencing conditions (see http://www.qsl.net/zl1bpu/MFSK/tech.html chapter
F) don't allow me to call this an implementation of MFSK16.

This version only implements the mode with 16 tones at 15.625 symbols per
second and R=1/2, K=7 (NASA standard polynomials) convolutional encoding.
Other modes will be implemented later.

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.

What I want to distress is the setting of audio levels. 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 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.
MFSK is very insensitive to overdriving but other band users might not
be...

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 by right clicking over it.

The "Log entry" button currently doesn't do much anything. 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).

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 $. The macros are evaluated at the time the button is pressed which
is a significant fact especially with the "push ... button" macros. A
predefined text like "$tx foobar $rx" probably does what you would expect
it to do but a text like "$tx foobar $abort" probably wouldn't...

Here is a list of all the recognized macros:

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

An unrecognized $-macro is transmitted as is.

Disclaimer
==========

This program is mostly a display of the Finnish Sisu: I can do it so why
wouldn't I do it? I'm not a GUI programmer nor do I ever want to be one.
Suggestions for the GUI part are more than welcome! Also the whole MFSK
engine is better described as a hack. Suggestions on how to do things
better are again welcome. Hopefully the program is usefull to you!

Thanks
======

Thanks to Murray ZL1BPU and Nino IZ8BLY for creating a very cool ham
communication mode. Especially to Murray for the technical documentation.
Also many thanks to Phil KA9Q and Charles G4GUO for giving ideas and/or
code for the project (even if neither knew about the project... the power
of free software!!!

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>
