1.
Introduction
xfhell is an X/GTK+ Linux application for Amateur Radio
communications in the Hellschreiber "fuzzy" digital mode and it
currently supports two modes, standard Pulse-modulated FeldHell and
MFSK-modulated FMHell as per IZ8BLY's design. xfhell detects the
pulsed/FM tone output of the receiver which represents the "dots"
of Hellschreiber characters, by reading audio samples from the DSP
in the computer's sound card, connected to the output of the
receiver. The audio signal is processed by a Goertzel tone detector
and is "painted" directly to the Receive window of xfhell. Thus
there is no software decoding of the incoming signal, leaving the
recognition of characters to the human eye/brain combination, hence
the term "fuzzy digital" often used to describe the Hellschreiber
system. An FFT based "Waterfall" display is available to help tune
in signals.
Transmission of Hellschreiber characters is realized by writing pre-computed audio samples to the sound card's DSP and feeding the resultant audio signal to the transmitter's input. The transmitter must be in the SSB mode during transmission but for reception a narrow-bandwidth mode like CW-Narrow is preferable since Hellschreiber only occupies about 250 Hz of bandwidth. xfhell has built-in CAT control capability for the Yaesu FT-847 or FT857 Transceiver which, when enabled, can change the operating mode automatically. xfhell now also has serial port RTS control to allow transceiver PTT-On/PTT-Off control.
Usage: xfhell [-hv]
-h: Print usage information and exit.
-v: Print version number and exit.
Sound-card
set-up
xfhell automatically prepares the sound card and sets the line
input level at the mixer to about 50%. For proper operation the
level of the input signal must be adjusted from the receiver, if
volume control is available, or by changing the value of the
Recording/Capture level in the ~/xfhell/xfhellrc run time
configuration file, if audio is taken from a fixed-volume source
such as the "data" i/o port. The output audio level is also set to
50% although again this will need to be set-up properly for
low-distortion transmission. Please see the Operation section for details on how to set-up the
sound card.
Software Tone
detector
xfhell was designed from the beginning to be simple and efficient,
decoding Hellschreiber signals using mostly integer arithmetic and
simple processing methods. It uses the computer's sound card to
detect the pulsed/fsk'd tone signal that makes up the Hellschreiber
characters, by implementing a Goertzel tone detector algorithm. The
output from the detector is painted directly to the Receive window
in continuous grey scale so that there is no thresholding of signal
intensity.
"Waterfall" display with
CAT
xfhell has a "Waterfall" (audio spectrum) display derived from an
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. The Waterfall
display also indicates the spectrum of the transmitted signal.
xfhell 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 xfhell to using the "hamlib" library was unsuccessful for various reasons. However xfhell now also has serial port RTS control to allow transceiver PTT-On/PTT-Off control. The Waterfall display can be used to tune in a signal by clicking with the left mouse button near its trace. xfhell 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 it may be necessary to fine-tune the receiver manually for best results.
Signal Waveform
Display
xfhell has a simple "Oscilloscope" display of the input signal.
This appears when the right mouse button is clicked on the
"Waterfall" window and can be used to monitor both the received and
transmitted waveforms.
Macros in Transmit
mode
xfhell allows 9 prepared Macros to be sent by clicking on one of
the nine buttons in the 'Prepared Macros' frame for easy
transmission of repeated messages like call-sign exchanges, station
info, BTU, sign-off etc. Theses Macros are stored in the 'xfhellrc'
run time configuration file (in ~/xfhell/) and are invoked by
clicking on the relevant Macro button. The keyboard keys F1-F9 can
also be used to start Macro transmission.
Short labels for these Macros are also stored in xfhellrc and are
displayed in the button labels. For even more operating convenience
xfhell allows the use of 'tags' embedded in the Macros for
automatic insertion of certain basic strings in the transmitted
message: call-sign, RST, name, QTH and QTH locator for both the
operator and the remote station, the current UTC date and time and
the operating frequency. The program's version string is also
available as a tag so that it can be included in a macro, e.g.
there are 13 tags altogether in this version. Icons and smileys
included in the built-in fonts can be transmitted if their glyph
number is enclosed in angled brackets, please read the comments in
xfhell/xfhellrc config file for more details.
QSO Recording and
Logging
xfhell can save details of activity during its operation in three
separate files on the disk:
1. In ~/xfhell/record.txt all characters printed in the Transmit
window including Macros are recorded 'raw' e.g. in real time and
unedited. This makes it possible to check everything transmitted
during operation if something goes wrong.
2. In ~/xfhell/log.txt all details of a QSO entered in the QSO
Record form (under the Receive window) are saved in text form with
the addition of date and time to form a standard station log.
3. In ~/xfhell/log.adif an ADIF-formatted version of the QSO Record
is saved for direct uploading to eQSL.cc or other sites that can
accept ADIF formatted logs.
4. Additionally, when the Receive window is filled, it is saved as
a jpeg image in the ~/xfhell/pixbufs/ directory as a direct record
of received signals.
Built-in Fonts including
Icons
xfhell has a set of built-in fonts in Adobe BDF format files in the
xfhell/fonts/ directory. These were derived from font files kindly
sent to me by Nino Porcino IZ8BLY from his own Hellschreiber
program. In addition there are two non-standard font files with the
font height reduced to 12 points instead of the 14 of normal
Hellschreiber fonts. These fonts are not normally compatible with
other Hellschreiber receiving systems but only with xfhell and are
intended to speed up character transmission rate by removing
redundant blank rows from the standard fonts. Update: With the
addition of a 105 Baud rate, 12-point fonts can be used with
programs running in standard 122.5 Baud/14-point FeldHell mode.
Please see the README file in xfhell/fonts/ for details.
Single-row Display of Received
characters
xfhell is probably unique in its ability to compensate for slight
timing differences between transmitter and receiver, thereby making
it possible to print characters on the screen in a single row only.
It does this by using the blank rows of the Hellschreiber font as a
synchronizing signal from which to derive and compensate for the
timing errors. This feature is enabled by activating the "Deskew"
button at the top left of the receiving window.
Different Operating Speeds
available
xfhell can operate at (sub)multiples of the standard 122.5 baud
rate of the Hellschreiber system. These speeds are not compatible
with other Hellschreiber programs but are experimental, mainly to
test the Hell mode in very weak signal conditions. One such
application could be in VHF/UHF EME operation were in conjunction
with the more efficient 12-point fonts Hellschreiber could prove to
be an effective mode.
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 "xfhell" 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. The "xfhellrc" directory contains the "xfhellrc" configuration file, the "pixbuff" directory where xfhell stores screen captures of the Receive window and the "fonts" directory with various Hellschreiber fonts in Adobe BDF format. This "xfhell" directory must be copied into our home directory.
xfhell requires a directory named xfhell in the user's Home
directory, where the default "xfhellrc" run time configuration file
is placed after suitable editing. Additionally, xfhell places three
files in this directory, created during operation:
1. record.txt is a complete character-by-character record of
everything that has been sent during a session.
2. log.adif is an 'ADIF' formatted record of the main QSO data e.g.
call-sign, signal report, mode, frequency and date-time.
3. log.txt is a more detailed record of conducted QSO's in text
format.
As well, xfhell requires the ~/xfhell/pixbufs/ sub-directory in
which it saves the Receive window as a jpeg image and the
~/xfhell/fonts sub-directory in which the Font files are stored.
All these files should be available in xfhell/, in the package's
top directory.
4. Command line
options
xfhell can be invoked with the following options:
-h: Print this usage information and exit.
-v: Print version number and exit.
xfhell User
Interface
xfhell is an X/GTK+ application for Linux. The main application
window has the following widgets:
1. The Transmit window: Any text typed during transmission appears in this window, although please note that only when the "space" key is pressed are the buffered characters transmitted. This is to avoid idle characters in broken words. When the Transmit window is filled, it scrolls automatically so that the last line is always visible. It can be cleared by right-clicking in the window and activating the 'Clear Window' item in the pop-up menu. Clicking the middle button in the window toggles xfhell between the Transmit and Receive modes. Same also by clicking the "Transmit" button at the top left of the Transmit window. Next to the "Transmit" button there is a text field showing the name of the current Font in use for transmission.
2. The Receive window: Displays characters "painted" directly to the screen from the output of the tone detector. When the screen is filled, it is saved in the ~/xfhell/pixbufs/ directory as a jpeg image. It can be cleared by right-clicking in the window and activating the 'Clear Window' item in the pop-up menu. Clicking the middle button toggles xfhell between the Receive mode and Standby. If xfhell is in Transmit mode it is changed over to Receive, but if a Macro is being transmitted, then it is interrupted and xfhell remains in Transmit mode until another middle-click on either window. Same also by clicking the "Receive" button at the top left of the Receive window.
3. Character size and Contrast: In the main pop-up menu,
the "Pixels per Dot" sub-menu selects the size of the characters
("glyphs") painted on the Receive screen, by changing the pixel
size of each "dot" of the Hellschreiber font bitmap. Default size
is set in the ~/xfhell/xfhellrc config file and is 2x4
pixels/dot.
Under the Receive Window, the Contrast slider adjust the contrast
of characters as they are painted on the screen. Already painted
characters are not effected. The default value is 5, e.g.
mid-scale.
Mode Display and Level Control: Under the Receive Window there is a text field that shows the current Mode of operation (FeldHell or FMHell) and the Baud Rate. Next to this there is a spin button for adjusting the Level controls of the sound card Mixer. This adjusts the Volume of the output tone (and hence the Transmitter power output) when in Transmit Mode. In Receive Mode, this spin button adjust the Capture Level control and hence the audio input to the DSP.
4. Waterfall/Waveform: The Waterfall/Waveform widget is
an aid to tuning the receiver accurately to an incoming Feld Hell
signal. The "Waterfall" displays the spectrum of the receiver's
audio output or the spectrum of transmitted signals via the
"loopback" arrangement. There is a CAT function associated with the
Waterfall but only for the Yaesu FT847 or
FT857 transceivers, as there were problems adapting xfhell to work
with the Hamlib library.
The Waveform display is a simple "oscilloscope" in which the
receiver's output is plotted. The transmitted waveform is also
displayed via a "loopback" arrangement from the transmit dsp
buffer. The Signal Waveform display appears in place of the
Waterfall when the right button is clicked in the window.
5. The QSO Record frame: In this frame there are seven entry fields in which basic QSO data are entered for saving in the text-format station log file and the ADIF-format log file in the ~/xfhell/ directory. The minimum requirement for a valid record is the DX station's call-sign, signal report and operating frequency. The mode and date are entered automatically by xfhell each time a new record is opened. If the transceiver in use is an FT847 or FT857 and CAT is enabled, xfhell will read the Transceiver status and enter the signal report and operating frequency automatically each time a new record is opened.
The buttons below the QSO Record fields have the following
functions:
Open New Record: This button clears all but the 'Band' field
and enters the mode (fhell) and the date and time to the QSO record
buffer in memory. If there is a previous valid record then this is
saved to the log files in ~/xfhell/ before a new record is
opened.
Save Record: Opens a pop-up save dialog box. If the QSO
Record is valid (call-sign, RST-out and Band have been entered)
then a confirmation request for saving is shown, otherwise if not,
a warning is given to that effect.
Clear All Fields: This button clears all entry fields. NOTE:
This will clear the QSO Record buffer in memory, resulting in lost
data if the record has not been saved first!.
Clear Windows: Clears the Transmit and Receive windows of
all text/characters.
6. The Macro buttons frame: In this frame there are nine buttons that initiate the transmission of prepared macros, e.g. standard messages saved in the run time config file xfhell (in the ~/xfhell/ directory). Clicking on a button puts xfhell in Transmit mode and starts transmission of the macro, clicking again on any of these buttons interrupts the macro but leaves xfhell in transmit mode.
7. The pop-up menu: This opens on a right-click on the
Receive or Transmit window. It has the following items:
Mode: Select Hellschreiber mode: FeldHell or FMHell.
Baud Rate:Select the operating Baud rate. This also results
in xfhell automatically loading a Font file suitable for the
current Mode/Baud rate combination
Font Selector: Select the Hellschreiber font to be used on
Transmit. Font files are stored in the separate 12pt/ and 14pt/
sub-directories.
Show Font:Paints the current Hellschreiber font file onto
the Receive window.
Pixels per Dot: Select the number of Screen pixels for each
dot of Hellschreiber "glyph" (character) painted to the Screen. The
default is 2x4 (each dot has a size of 2 pixels wide and 4 pixels
high). Enable CAT: Enable/disable CAT control of the FT847
or FT857 transceivers.
Record QSO's: Enable/disable recording of everything printed
in the Transmit window to the ~/xfhell/record.txt file.
Capitalize letters: Enable/disable capitalization of letters
in Transmit mode.
Loopback Tx to Rx:When in Transmit mode, enables a loopback
from the TX dsp buffer to the Rx buffer so that the transmitted
waveform is decoded by the Receive functions of xfhell.
Identify in CW: Sends the station call-sign in CW/Morse
code.
Quit: Quits xfhell.
Configuration and
set-up
After compilation and installation, the ~/xfhell/xfhellrc run time
configuration file MUST be edited for proper operation! To do this,
load ~/xfhell/xfhellrc into your favorite editor and make sure that
you check ALL the configuration fields in the file and that you
properly edit all the ones that must be edited. There are four
sections, Sound card, xfhell Run time, Operator/QTH info and Macros
fields. Please check ALL and EDIT as needed!! There are more
detailed instructions in the file itself so please follow them for
a proper set-up. In particular, station details like Call-sign,
operator's name and QTH etc must be edited for Macros to be
usable.
Next, the sound card must be set up. For this to be done, the receiver's audio output should be connected to the computer's sound card (usually to the 'line' input) and the receiver tuned to some stable carrier signal with no am modulation. Modern HF transceivers have general coverage receivers with DSP audio filters down to 25 or 50 Hz bandwidth and this makes it possible to use a local MW broadcast station as a signal source.
With the narrowest bandwidth selected start xfhell, click the "Receive" button and disable the Receive de-skewing function by deactivating the "Deskew" toggle button. Fine-tune the receiver for a 500 Hz beat frequency output using the Waterfall display as a guide, e.g. tune so that the signal's trace is under the red line. Then right-click on the Waterfall display to switch to the "Oscilloscope" display: For the correct level of audio input, the signal trace must be a little below the top of the 'scope display. If the audio level is to high, reduce the receiver's volume level or if the audio output is taken from a fixed-level output (like the 'data' port), set the correct input level by using "Level" spin button. Then use the spin button's value as the Recording/Capture Level option in ~/xfhell/xfhellrc file. Quit and restart xfhell so that it reads the new configuration and check that it sets up capture level correctly.
For Hellschreiber transmission, the DSP output level needs to be set up for linear modulation of the transmitter to preserve the "soft" keying waveform. The Volume/PCM level setting in ~/xfhell/xfhellrc can be edited to give the correct audio output level by first using the Level spin button to adjust the Volume/PCM setting, then using the spin button's value in xfhellrc.
If the setting is below approximately 20% then a simple resistive attenuator will be needed ahead of the transmitter's audio input. In each case the best way to set the sound card output level would be to have the transmitter's settings (Mic gain, ALC or other appropriate control) at an average or 'normal' level and adjust the sound-card audio level so that the RF output power is about 80% or less of the rated maximum power. This will ensure that distortion is kept to a minimum and the dissipation of the final stage within its ratings.
Receiving Hellschreiber
signals
To receive Hellschreiber signals, start xfhell and tune-in the
station as follows: Set up the receiver for a narrow-band mode
(normally this would be CW-Narrow, or if available a DSP audio
filter with a bandwidth of 250 Hz or so should be used). Then tune
the receiver until the trace of the signal in the Waterfall window
is centered under the red line. If you are using an FT847 or FT857
transceiver and the appropriate CAT control is enabled, clicking
near a signal trace in the Waterfall should cause xfhell to change
the main dial frequency so that the trace is centered under the red
line. Some manual touch-up may be needed to fine-tune the signal,
especially in FMHell mode since xfhell will tend to tune the Rx to
one of the two traces that FM Hell leaves in the Waterfall.
Conducting a QSO
As usual to make a QSO with another station using Feld Hell you may
call CQ or reply to a CQ. Calling CQ would normally be done using a
prepared Macro by clicking on the relevant Macro button then during
the course of a QSO, other Macros can be started as needed to send
some of the standard messages that are usually exchanged. When the
Macro is finished, xfhell will revert to Receive mode unless a
tilde '~' is the last character in the Macro, in which case it
remains in Transmit so that a manually typed message can follow the
Macro. Reversion to Receive would then be done by middle-clicking
on the Receive or Transmit window, clicking the "Receive" or
"Transmit" buttons or using the F11 or F12 keys. Please note that
Macro transmission can be interrupted by middle-clicking on the
Receive or Transmit window or left-clicking on any of the Macro
buttons.
When a station replies to a CQ it would normally be netted closely and characters transmitted will appear in the Receive window. If there is a significant frequency offset, it will weaken received characters but correcting this from the main dial may cause the remote station to miss reception. Using the RIT control may be advisable as this will help to avoid 'crawling' along the band as stations tune in to each other during the QSO.
Once two-way contact is established, at least the station's call-sign, RST, and the QSO frequency must be entered in the QSO Record's fields before it can be saved to ~/xfhell/log.adif and ~/xfhell/log.txt. BUT PLEASE NOTE: Always remember to click 'Open New Record' before entering any data otherwise the mode and date/time will not be entered to the record buffer by xfhell.
Any information entered in the fields is available to any relevant 'tag' in the Macros but please note that if any fields are not filled, xfhell enters blanks in place of tags! Please note that during transmission no entries should be made to the QSO Record fields since these will reflect in whatever tags are embedded in Macros.
To reply to a CQ, tune in the station accurately and type its call-sign, signal report and frequency in the QSO Record fields. Then prepared Macros can be used to reply to the call and conduct a QSO. Have a look in ~/xfhell/xfhellrc for some typical prepared Macros.
NOTE: You will need to edit at least some of these!!
6. Bugs and deficiencies
I have fixed whatever bugs I came across testing xfhell, but there
may be some hiding, waiting for the right conditions to appear.
The tone detector algorithm may need further improvements to make it more tolerant to fading and noise. The biggest problem seems to be adjacent strong signals raising the AGC and reducing the level of the signal being received.
Version 0.1 First beta release of the basic xfhell application.
Version 0.2 Added Radio buttons to select the size of characters in Receive mode.
Version 0.3 Modified the QSO record so that the RST-out is before the RST-in field. Also changed the format of the 'log.txt' file that is used for logging QSO's to make it more printable.
Version 0.4 Added a Contrast control for the Receive window.
Version 0.5 Added an "Oscilloscope" display for Receive and Transmit waveforms.
Version 0.6 Added a simple FFT-based "Waterfall" (audio spectrum) display with CAT functions for the Yaesu FT847/FT857 transceivers. This allows tuning in a signal by clicking on its trace in the Waterfall.
Version 0.7 Added functionality to enable use of 12-point fonts and lower operating Baud rates.
Version 0.8 Replaced the quadrature tone detector with a Goertzel tone detector since it seems to produce a somewhat cleaner output. Also added a Volume control spin button to adjust audio output from the sound card and hence transmitter power.
Version 0.9 Modified my integer arithmetic version of the Goertzel algorithm back to the original floating point implementation, since on low baud rates there was a small mismatch between the transmit and receiver audio tones, due to the insufficient accuracy of integer arithmetic
Version 1.0 Added the IZ8BLY FMHell mode as it now seems to be popular due to its better performance in poor conditions.
Version 1.1 Changed the FMHell detector from a differential phase detector to a dual Goertzel tone detector scheme. The level of black/white tones is measured by a Goertzel detector set up for that tone and the black/white decision is made by comparing levels. Also arranged for a suitable default Font file to be loaded for the current Mode/Baud rate, see the README file in xfhell/fonts/ directory.
Version 1.2 Changed the Receive printing mode from 'wrap-around" to Scroll-up, e.g. when Receive is enabled, characters are printed in the bottom line of the receive window and scrolled up when the line is full. Also, when Deskew is disabled, printing is done in the traditional double row lines mode.
Version 1.3 Fixed a bug that skewed printed characters by one column between the upper and lower rows in the double-row printing mode. Also fixed a memory leak caught by Valgrind when changing baud rates.
Version 1.4 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 xfhell source code and changed all "sprintf" commands to "snprintf" just in case. While going through the xfhell source code, I also fixed some minor bugs like typos and tidied error messages and other aspects of the GUI.
Version 1.5 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.6 After a bug report from Pino Zollo ZP4KFX, I modified the GUI to allow the changing of the Receive window's height, through a check button, to half the normal size. This was needed to allow xfhell's window to fit in low height desktops. I also modified the program to hopefully correct GUI problems caused by glitches (race conditions) on start up, which caused incorrect initialization of the GDK pixbuf used to draw Hell characters in the receive window. I also fixed a similar problem with the Waterfall pixbuf.
Version 1.7 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 also added a menu item to select "Reverse Video", e.g. to transmit white characters on black background. This might give better results in noisy conditions.
Version 1.8 After a feature request by Pino Zollo ZP4KFX, I added serial port RTS line control to enable PTT-On/PTT-Off of transceivers other than FT847/FT857. But please note that no CAT functions will be available, e.g. clicking on the waterfall trace will not tune in the receiver and frequency/S-meter readings will not be available in the QSO records.
Version 1.9 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.
Last modified: Sat Mar 8 07:38:59 EET 2003