# &app; Manual V&manrevision;

## Introduction

&app; is a terminal program for digital conversation modes on HF amateur radio. &app; uses the soundcard to interface to the radio. No external modem or TNC is needed.

&app; currently implements the following modes:

- MFSK (MFSK16 and MFSK8)

- RTTY

- THROB (1, 2 and 4 throbs/sec)

- PSK31 (BPSK and QPSK)

- PSK63

- MT63

- Hellschreiber (Feld Hell)

### Available Modes

MFSK (MFSK16/MFSK8)

- M-ary Frequency Shift Keying is a way of transmitting digital data using multiple tones usually sending one tone at a time. It is designed for real-time keyboard to keyboard communications and could probably be regarded as a logical replacement for RTTY.

  MFSK16 uses 16 individual tones using around 300 Hz of bandwidth and sends data at around 40 wpm. MFSK8 uses 32 individual tones also using around 300 Hz of bandwidth but sends data at around half the speed. MFSK8 is better in low signal and very noisy conditions than MFSK16, but MFSK16 is usually the default as it still performs very will in most conditions and provides a faster data transfer.

  The original MFSK website by Murray Greenman ZL1BPU is at http://www.qsl.net/zl1bpu/MFSK/

  Look for MFSK signals around 7037, 10147, 14080, 18105 and 21080 USB.

RTTY

- RTTY is the granddaddy of Amateur HF digital communications. While there are several variations, you are most likely to find 170Hz Shift, 45.45 baud BAUDOT code radioteletype on the Amateur bands.

  Look for RTTY signals around 7080, 10140, 14070-14095, 18100, 21070-21100 USB.

THROB (1/2/4 throbs/sec)

- Throb is an experimental mode written by Lionel Sear, G3PPT. It uses a possible 9 tones spaced 8 or 16 Hz apart, which gives a bandwidth of 72 or 144Hz respectively. It has three transmission speeds, 1,2 and 4 Throbs/sec which give data rates of 10, 20 and 40 wpm respectively. The 1 and 2 Throb/sec speed use a tone spacing of 8Hz, bandwidth 72 Hz and the 4 Throb/sec speed uses a spacing of 16 Hz, bandwidth 144 Hz.

  Lionel's web page is at http://www.lsear.freeserve.co.uk/page3.html

  Look for THROB signals near where you would also find MFSK signals.

PSK31 (BPSK/QPSK)

- Phase Shift Keying 31.25 baud is one of the most popular HF Digital modes. It uses BPSK (Binary Phase Shift Keying) or QPSK (Quadrature Phase Shift Keying) and a varicode character set to achieve up to 50 WPM. It's a good performer most of the time although not quite as good as MFSK in noisy or high fading conditions.

  QPSK provides twice the raw data rate, which is then halved by adding redundancy to the data in the form of FEC. In therory this gives exactly the same data rate as BPSK but with slightly increased reliability. However in real world conditions there is little or no difference. The vast majority of contacts are done using BPSK.

  The "PSK31 Official Homepage" is at http://aintel.bi.ehu.es/psk31.html

  Look for PSK31 signals around 7070, 7035, 14070 and 21080 USB.

PSK63

- PSK63 is a faster variant of PSK31 designed especially for contest operation. It is otherwise identical to PSK31 but the symbol rate is 62.5 baud.

  PSK63 info can be found at http://www.qsl.net/kh6ty/psk63/

MT63

- MT63 encodes the data into 64 different tones spread across either 500, 1000 (default) or 2000 Hz. The data is also encoded using Forward Error Correction (FEC) which spreads each character over 3.2 seconds in time as well. This makes it an extremely robust mode which is incredibly resistant to interference and exceptionally good at decoding weak signals. Due to the high number of tones and FEC encoding MT63 delivers approximately 100 wpm.

  The main MT63 website seems to be http://www.qsl.net/zl1bpu/MT63/MT63.html

  Look for MT63 signals around 14109.5 USB

FELDHELL

- Feld-Hell or "Field Hellschreiber" is quite an old communications mode. It was first patented in 1929 and that patented form is still in use today. It was often used for field communications during WWII and so given the name of "Field" or "Feld" Hellschreiber to distinguish it from the land-line versions.

  Each character of a Feld-Hell transmission is portrayed as a series of dots, in a matrix, just like the printing of a dot-matrix printer. The dots are sent one at a time, rather like Morse code. Feld-Hell transmits in the following order - up each column from bottom to top, then up each successive column from left to right.

  An excellent website with Feld-Held info is at http://www.qsl.net/zl1bpu/FUZZY/Feld.html

  Look for Feld-Hell signals around 3575 (Region 1) 3559 (Region3), 7030-7040, 10135-10145, 14063-14070 (many operators monitor 14063), 18100-18105 and 21063-21070.

## Getting Started

### To Start &app;

To start &app; type the following command, then press Return:

`gmfsk`

&app; accepts the following command line arguments:

--cwirc

- Start &app; in a special CWIrc slave mode. See http://webperso.easyconnect.fr/om.the/web/helloip/ for details.

--run-druid

- Start the configuration druid. The druid is normally started the first time you use the program.

--testmode=MODE

- Start &app; in test mode. In test mode &app; reads the audio samples from standard input and writes them to standard output. MODE can be rx, tx or both.

### When You Start &app;

When you start &app;, the following window is displayed.

#### &app; Start Up Window

Shows &app; main window. Contains titlebar, menubar, toolbar, received text area, transmitted text area, macro buttons and the waterfall Menubar contains File, Mode, Settings, and Help menus.

The &app; window contains the following elements:

Menubar.

- The menus on the menubar contain commands that let you log received text, select operating mode, modify parameters, and get help.

Toolbar.

- The toolbar lets you switch between receiving, transmitting, generating a test tone or keeping the program idle.

Loggingbar.

- The loggingbar provides an easy way to enter logging information into XLog. XLog is a seperate Unix Ham Logging program. It is not included with this program.

Received Window.

- This is where all received text appears.

Transmit Window.

- This is where the text you type appears as you type it when in transmit mode.

Macro Buttons.

- There are 12 macros available to automate various tasks. These buttons will trigger the listed macro.

Waterfall Display.

- Waterfall tuning display

Function Box.

- The function box displays received signal and tuning information and allows you to manually set some operating parameters.

Status Bar.

- The Status bar displays the operating status of the program including transmit state and mode.

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

## Usage

Let's take a look at &app;'s menubar:

### File Menu

The File Menu allows you to some basic file management functions

File Send File

- The Send File command loads a text file and sends enters it into the transmit window exactly as if you were typing it yourself, only much faster!

  When you invoke the Send File command a file selection box is displayed. Select the file that you want to transmit, then click OK. Click Cancel to abort.

File Log to File

- Log to File saves everything both received and transmitted into a log file. This log file is specified in the Settings menu. The default filename is `~/gMFSK/log.txt`. The state of Log to File is saved at program exit and restored next time the program is started.

File Clear TX Window

- The Clear TX Window command clears the Transmit Text Window.

File Clear RX Window

- The Clear RX Window command clears the Received Text Window.

File Quit

- The Quit command does pretty much what you would expect...

### Mode Menu

The Mode pulldown menu allows you to select which mode to use.

Select one of the following modes;

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 FEC encoding (R=1/2, K=7, NASA standard polynomials) and viterbi decoding.

  MFSK16 also supports sending small pictures in analog FM mode. This is compatible with MixW (http://www.mixw.net/). Receiving pictures is automatic. Sending is triggered with the macros $pic and $picc (see gmfsk-settings-menu).

RTTY

- RTTY support in &app; should be considered experimental.

  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 may be needed for the ASCII modes.

  Note that no sanity checking of the parameters is made by the program, it is quite possible to enter values that don't make sense.

THROB

- Throb support is also to be considered experimental.

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

PSK31

- PSK31 support in &app; 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.

PSK63

- PSK63 is a faster variant of PSK31.

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. There is no support for the IZ8BLY style secondary channel. 8 bit characters are supported using escape 127 encoding.

FELDHELL

- FeldHell has full international charater set support. However, FeldHell TX uses antialiased fonts which is probably not the optimal solution. The AGC parameter adjustments don't work yet.

### Settings

The Settings pulldown menu allows you to modify program settings and FixText macros.

Preferences

- Preferences are covered in the gmfsk-prefs section.

Configure Macros

- Configure Macros allows you to edit any one of the 12 fixtext macros. Selecting a fixtext macro to edit brings up a dialog box with two entry fields. The top one is for the name of the fixtext macro. Fixtext macro names are displayed on the fixtext buttons on the main screen. The larger text entry field is where you type the macro itself. Pretty much anything can be entered in here to be automatically sent when you either press the function key or the on screen button.

FixTexts can contain macros. Macros start with the letter $. A standard macro is of the form $text. The available standard macros are;

$$

- The letter '$'

$tx

- Push the TX button.

$rx

- Switch to receive.

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

$startqso

- Set QSO start time to current time.

$logqso

- Send QSO data to Xlog

$clearqso

- Clear loggingbar

$mode

- Currently active mode name.

$pic

- Send grayscale picture.

$picc

- Send color picture

The macro name can also be enclosed in curly braces. This can be useful if you need to avoid any spaces between the macro and some text. The macro can also have an optional argument separated by a colon. This only works in conjunction with curly braces. Currently this argument is only useful with the picture macro where you can supply a filename that way. A typical picture function might be:

`${picc:/home/joe/joe.jpg}`

If the picture name is omitted or it is '?', the user is presented with a file selection dialog.

In addition to standard macros you can use so called command substitution with a function of the form $(command). The command is executed using fork()/exec() and the standard output of the command is captured (standard error is discarded). If the last character of the captured output is a newline, it is removed.

The fixtext 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.

## Settings

To configure &app;, choose Settings Preferences . The Preferences dialog contains the following sections:

### General

General configuration options for &app;:

Station info

- Specify your personal information. &app; will use these values in variables in macros.

  - Callsign

    Station Callsign

  - Name

    Your preferred name

  - QTH

    Your location (eg Canberra, Australia)

  - Locator

    Your Maidenhead locator square. The ARRL has a good page at http://www.arrl.org/locate/gridinfo.html

  - E-mail

    Your email address (if you have one).

Date & Time

- These are used in the $time and $date macros.

Bands

- A comma separated list of bands that you want to appear in the Bands popdown list.

Files & Dirs

- Configure the log file name and default directories for sent and received picture files.

### Appearance

Lets you configure the colours and fonts used in &app;:

Colors

- Click on the color button and then select your favourite colors from the Gnome color picker.

Fonts

- Click on the font buttons and then select your favourite fonts from the Gnome font dialog.

### Modems

Configure modem parameters. All modems preference panels have a Restart modem button at the bottom of the panel. If you make a change to a parameter you must press this button to restart the modem to make your changes take effect.

All

- Settings that affect all modems.

  With TX frequency offset you can correct any systematic frequency error your transceiver might have between RX and TX modes.

MFSK/THROB/PSK31

- The only modem setting for these modes is an individual squelch setting. (THROB squelch has no effect.)

RTTY

- This allows you to modify RTTY shift, baudrate, bits (5=BAUDOT, 7/8=ASCII) parity, stopbits, inverted or normal byte ordering. The defaults are: Shift 170, Baudrate 45.45, Bits 5 (BAUDOT), Parity none, Stopbits 1.5, Reverse Polarity yes and Send MSB First no. These are the Amateur default. You can change them if you want to work in ASCII rather then BAUDOT or decode non-Amateur signals. Not however that the software makes no sanity checking of the parameters. It's possible to enter values that make no sense. (RTTY squelch has no effect.)

MT63

- This allows you to change the bandwidth and interleave of the MT63 modem. The default parameters are: Bandwidth 1000 Hz, Interleave 64 (long), CW Identification no, Allow 8 Bit Characters yes. These are the recommended ones. It would be best to change them only when you fully understand the protocol.

  CW ID is sent alongside the transmission if selected. The callsign is taken from the station info preferences.

HELL

- Here you can change the font and operating parameters of the Feld-Hell modem. (The AGC settings don't currently work.)

### Waterfall

Configure the waterfall display.

Settings

- This panel allows you to tweak the parameters of the waterfall display.

  Ref level

- Sets the reference level of the waterfall and spectrum displays. This sets the level in dB that corresponds to the brightest color in waterfall and to the top of the window in spectrum display. 0 dB corresponds (approximately) to the strongest signal that the sound card can handle.

Amp span

- Sets the amplitude span of the waterfall and spectrum displays. This sets the difference in dB between black and white in waterfall and the top and bottom of the window in spectrum display.

Mode

- Switches between Waterfall, Spectrum and Scope displays.

Zoom

- Sets the zoom in Waterfall and Spectrum display modes.

Speed

- Sets the display update speed.

Window

- Sets the FFT windowing function used when calculating the Waterfall and Spectrum displays.

Waterfall scrolls upwards

- Changes the direction of scrolling in the waterfall display (up or down).

### Devices

Configure sound and PTT devices.

Sound

- Please enter the full path to your OSS compatible sound device. This is probably something like `/dev/dsp` on Linux and `/dev/dspW` on FreeBSD.

  The Requested sample rate, TX rate offset and RX rate offset allow you to rectify any sample rate problems with your soundcard. Normally you don't need to touch these but in case your soundcard doesn't support the default rate of 8000 samples per second or if you know that it has some sample rate offset, you can correct it separately for transmit and receive.

  As an example of a bad case consider this: Your soundcard only supports 11025 sps, but you know that it actually samples at 11020 sps on transmit and 11035 on receive. In this case you should put 11025 to the Requested sample rate box, (11020 - 11025) / 11025 * 1000000 = -453.5 to the TX rate offset box and (11035 - 11025) / 11025 * 1000000 = 907 to the RX rate offset box.

  There are also options to enable 8 bit sound, stereo sound and full duplex. Try 8 bit or stereo audio if you get errors when &app; tries to open the sound device. Full duplex should not be used unless it's the only option that works; it is unsupported and generally a bad idea.

PTT

- &app; has the ability to key your transmitter using either the serial or the parallel port. For serial port you can select DTR or RTS (or both), for parallel port DATA0 is used.

  Select one from the list or type whatever you want to the entry. Serial ports are of the form `/dev/ttyS0` and parallel ports of the form `/dev/parport0`. On FreeBSD serial ports are something like `/dev/cuaa0`.

  There's a good page on interfacing your soundcard to your rig at; http://www.qsl.net/wm2u/interface.html

### Hamlib

Configure Hamlib (http://hamlib.org) support. This may not be available if the support is not compiled in the binary.

Settings

- Select the radio model and the port the radio is connected to. For the RPC rig, the port is the hostname where the rig daemon runs (typically localhost). For serial ports you need to then select the speed to be used.

  Config is a comma separated list of Hamlib config parameters: param1 = value1, param2 = value2, ... You can get a list of the parameters your rig support using the `rigctl` command:

  `rigctl -m <model> -L`

Features

- Here you can select what &app; uses hamlib for.

## Operating &app;

Operating &app; 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 &app; 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 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 can be paused from the popup menu that opens if you right click over it. The waterfall config dialog can also be activated from the popup menu.

The status bar shows modem state, transmission mode and UTC time. Clicking the mode label is a shortcut to the mode config dialog.

The Log entry button sends the QSO data to a logging program using interprocess 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).

## About &app;

&app; was written by Tomi Manninen. To find more information about &app;, please visit the gMFSK Web page.

To report a bug or make a suggestion regarding this application or this manual, please email the author at oh2bns@sral.fi.

This program is distributed under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found at this link, or in the file COPYING included with the source code of this program.

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

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. Due to a stupid oversight from my part I released &app; v0.5 with Pawel's MT63 code under GPL even though Pawel's original license was not GPL-compatible. Fortunately Pawel has since agreed to release his code under the GPL. Thanks Pawel!

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

&GFDL;