1.
Introduction
xdemorse is a X/GTK+ application for decoding Morse code signals
into text. xdemorse detects the "dihs" and "dahs" that make a Morse
code character via the computer's sound card, which can be
connected to a radio receiver tuned to a CW Morse code transmission
or to a tone generator. The input signal is processed by a Goertzel
tone detector algorithm which produces "mark" or "space" (signal/no
signal) outputs and the resulting stream of Morse code "elements"
is decoded into an ASCII character for printing to the Text
viewer.
Goertzel tone
detector
xdemorse was designed from the beginning to be simple and
efficient, decoding Morse code using (almost) only integer
arithmetic and simple processing methods. It uses the computer's
sound card to read the "dit" and "dah" elements that make the Morse
coded characters by implementing an integer Goertzel tone detector
algorithm, which measures the level of sound signals from a radio
receiver or tone generator. This Goertzel tone detector is centered
on a nominal frequency of 500 Hz, which is lower than the more
common 700-800 Hz BFO setting, because my PSK31 applications have
to work with a 500 Hz audio tone due to various limitations. I have
chosen to run my Morse decoding applications on the same BFO
setting, to avoid regular changes to my receiver.
The Mark/Space (key-down - key-up) condition is detected using an edge detector which give a positive spike for a mark->space transition and a negative spike for a space->mark transition.
Error and noise
tolerance
xdemorse has a certain level of tolerance towards operator errors
(bad "fist") regarding deviation from the standard duration of the
various elements that make up the Morse code. It can also reject to
some extend the effects of interference and noise by ignoring marks
or spaces shorter than a certain fraction of the unit Morse code
element. Below is a table of the basic Morse code elements and the
range of durations that xdemorse can deal with:
Morse Element Duration xdemorse
-------------------------------------------------
dit 1 units 1/2-2 units
dah 3 units 2-4 units
Inter-elem space 1 units 1/2-2 units
Inter-char space 3 units 2-4 units
Inter-word space > 5 units > 4 units
The Morse code characters, punctuation marks and special signals
that xdemorse can currently recognize are in the file
doc/Morse-code.txt. Extra characters etc can be added to the
collection by inserting the hex equivalent of the decoded Morse
code character in the xdemorse.h header file before compilation.
Please see detailed explanation in that file.
"Waterfall" display with
CAT
xdemorse has a "Waterfall" (audio spectrum) display derived from a
FFT of the receiver's audio output. A vertical red line indicates
the center frequency of the tone detector. When tuning a signal
manually, its trace should be centered on this line for best
results. Clicking with the center button on the display reverses
the background/foreground colors of the display.
xdemorse has built-in CAT capability but only for the Yaesu FT847 or FT857, the only rigs I have. This is an unfortunate limitation but an attempt to convert xdemorse to using the "hamlib" library was unsuccessful for various reasons. The waterfall display can be used to tune in a signal by clicking with the left mouse button near its trace. xdemorse will scan a small section of the display either side of the mouse pointer, looking for the strongest trace and then tune the receiver so that the signal is centered on the red line. Since the FT847/FT857 has only a 10 Hz resolution when tuned by the CAT, there can be an error of +-5 Hz in the tuning of a signal. Other errors resulting from the finite resolution of the FFT can increase the tuning discrepancy and since xdemorse has a sharp tone detector, it may be necessary to fine-tune the receiver manually for best results.
Sound-card
set-up
xdemorse automatically sets up the sound card and tries to set the
input and recording/capture level to the RECORD_LEV entry in
xdemorse.h. If it fails it will give an appropriate warning and the
mixer levels for line input and recording level must be set up
manually using a mixer app like 'aumix'.
For proper operation the level of the input audio signal must be adjusted from the receiver or the tone generator, using the 'scope' display at the bottom left of the main window. If the audio signal is taken from an outlet that provides a fixed audio level, then the #define RECORD_LEV entry in xdemorse.h will need to be edited by trial and error and xdemorse re-compiled, until the signal plotted in the scope display is about 80% of the height of the scope frame.
3.
Compilation
Please note that I use Arch
Linux AMD64 which is a "bleeding edge" type distribution, so
there may be compilation and/or run time difficulties if you are
using a relatively old distro. This is mostly true of the basic
dependencies like GTK+ 2 and Glade-2, and there can also be sound
card incompatibility problems at run time.
To compile the package the first time, run the "autogen.sh" script in the package's top directory. The "configure" script as produced by Glade-2 specifies the gcc flags as "-g -O2", but if you want to specify different flags, you will have to run "configure" with the CFLAGS option, e.g. ./configure CFLAGS="-Wall -O2 -march=i686" or whatever flags of your choice.
Run "make" to produce the executable binary "xdemorse" in src/. This can then be copied to a suitable location, usually /usr/local/bin or /usr/bin. You can of course run "make install" which will install the binary into /usr/local/bin by default. You can change this to a different location, e.g. /usr/bin, by including the --prefix=/usr option when running "configure". To recompile the package, you must run "make distclean" in the top directory to clean up the package and then run the "configure" script and "make install".
There is this hypertext documentation file which you can copy to a location of your choice. There is also a default configuration file .xdemorserc in the 'default" subdirectory. This must be copied to your home directory and edited to match your setup. If you have problems identifying your sound card mixer devices (recording source, recording level etc) run "xdemorse -l" in a terminal to get a list of mixer device names.
xdemorse [-hlv] -h: Print this usage information and exit. -l: List mixer device names and exit. -v: Print version number and exit.
5. Operation
Before xdemorse is used to decode Morse signals, the input level to
the sound card must be set up correctly. For this, the radio
receiver or tone generator must be connected to the "line" input of
the sound card with a suitable cable and connectors, with either
the left or right channel connected to the receiver's o/p if in
stereo mode, or if in mono mode normally the left channel input.
The receiver's output level is adjusted so that the maximum signal
input level, as shown in the 'scope' display at the bottom left of
the main window, is about 80% of the scope's window height. The
receiver should be tuned to a strong, clean CW transmission, with
the AGC setting in the fast position and IF/AF bandwidth in the
narrowest setting. Please note that the receiver should be tuned
accurately to the incoming signal so that the BFO note is 500Hz.
This can be done by slowly tuning the receiver, with a tuning step
of 1Hz if available, so that the INPUT SIGNAL display in the scope
is at a maximum. The waterfall display is also very useful for
tuning, since a signal trace tuned to be exactly under the red
middle line of the waterfall will result in a 500 Hz BFO
frequency.
By default xdemorse starts with Morse code speed set to 20 wpm and the detector threshold set at 50. These are shown in the two spin-wheel widgets at the right of the scope window. As xdemorse begins to decode Morse coded signals, it estimates the sending speed and adapts to it, indicating the actual speed in the 'Speed' spin-wheel. If the Morse transmission is a lot faster or slower than the indicated speed, it may not be decoded correctly and manual changing of the speed setting will be needed to fix the problem. Auto adaptation to incoming Morse speed can be disabled with the "Auto wpm" check button.
To decode Morse code from a communications receiver, set the BFO so that the tone of the CW signal is near to 500 Hz and then start xdemorse. Assuming that keying is not too bad (operator's 'fist' is reasonably good) then decoded characters should appear in the 'Receive Window' of xdemorse. Some changes to the speed and/or squelch setting may be helpful and experience will show the best setting for the latter. A maximum tuning step of 1 Hz should be selected on digital receivers and tuning should be slow. A narrow CW filter is an advantage although very narrow (less than 300-400 Hz) IF or dsp/AF filters tend to ring and cause spurious characters, mainly E's to be printed on the screen.
Please note that the 'scope' display of xdemorse-fft has two functions, it can display the input signal waveform or the output from the Mark/Space (signal/no-signal) detector. The first function is the default and it can be selected, stopped or started by clicking in the scope window with the left button of the mouse. The second function can be selected, stopped or started by clicking in the scope window with the right button of the mouse. The middle button stops whatever function is selected. Clicking on the FFT display with the middle button reverses background/foreground colors.
Generally xdemorse has a fairly wide tolerance of sending errors (bad fists or noise) but in practice it has proved to be difficult to correctly decode CW signals on the amateur bands, with the main problem appearing to be bad keying habits. Sometimes inter-character spacing is too small so two or more characters are taken as one and therefore cannot be decoded correctly. Characters not recognized by xdemorse are indicated by an asterisk * on the screen. Word spacing also seems to be inconsistent with many hams resulting in fragmented or fused words.
Finally a list of all characters, punctuation marks and special signals recognized by xdemorse are listed in the doc/Morse-code.txt file. Additional characters can be entered in two tables in the xdemorse.h header file before compilation, following the instructions in there.
6. Bugs and annoyances
I have fixed whatever bugs I came across testing xdemorse but there
may be some hiding, waiting for the right conditions to appear.
The Morse code decoding algorithm may need further improvements to make it more tolerant to errors and noise and the mark/space detection process may need to be improved to reduce spurious output due to noise interference.
Version 0.1: First beta release of this basic Morse decoding X/GTK+ application, which is based on the console Morse decoding tool 'demorse'.
Version 0.2: Added a simple "Oscilloscope" display of the incoming waveform or the Detector output.
Version 0.3: Added a simple FFT-based "Waterfall" display of the receiver's audio spectrum. The Waterfall display incorporates CAT functions for the FT847 or FT857 transceiver allowing netting of the receiver by clicking on the trace of a signal.
Version 0.4: Replaced the original software synchronous tone detector with a Goertzel tone detector, since it has slightly better performance.
Version 0.5: Changed Mark/Space tone detection from thresholding the signal level to detecting the mark->space and space->mark transition edge. Seems to give more reliable decoding.
Version 0.6: Added a display function for the output of the Goertzel signal detector. This is displayed int the "scope" window at the left lower corner of the xdemorse window.
Version 0.7: Changed the detector scheme to a Mark/Space transition (edge) detector which works by counting the number of consecutive signal samples (steps) that change by more than 5% in the same direction (up or down). If the number of steps is more than a given threshold (default 60% of the Morse element duration) then this is taken to indicate a rising or falling edge. This seems to work better than the previous slope detection scheme. Also added a few extra command line options to specify parameters for demorse's operation.
Version 0.8 Added a parser to read a runtime configuration file from the user's home directory. This file (~/.xdemorse) must be edited to match the user's setup. The command line options for specifying the various parameters xdemorse needs have been removed. Also its no longer necessary to make any changes to the xdemorse.h header.
Version 0.9 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in xdemorse source code and changed all "sprintf" commands to "snprintf" just in case. While going through the xdemorse source code, I also fixed some minor bugs like typos and tidied error messages and other aspects of the GUI.
Version 1.0 After a bug report from Pino Zollo ZP4KFX, I modified the waterfall display function to avoid a divide by zero condition that caused a SIGFPE crash.
Version 1.1 After a bug report from Pino Zollo ZP4KFX regarding GUI problems with my Hellschreiber program xfhell, I made some changes to the GUI code in most of my GTK2 applications.
Version 1.2 After a bug report from Pino Zollo ZP4KFX,
regarding failure of "xdemorse" to start the Morse decoding loop
after reading its configuration file, I have modified the functions
that read this file so that more detailed error messages are
printed if entries are malformed.
I added 3 new entries to the ~/.xdemorserc config file to allow a
wider range of max and min Morse speeds and to define the initial
Morse speed (WPM) at start-up. I also added a "Receive" button in
the GUI to start and stop xdemorse as needed.
Version 1.3 Made the page size of spin buttons 0 to make setting of spin button values compatible with GTK 2.4.
8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details:
August 16 2002.Last modified: Mon Mar 31 16:13:49 EEST 2003