hfkernel - HF (shortwave radio) protocol implementation using a soundcard

hfkernel [-2] [-3] [-a <audio device>] [-c <comm socket>] [-f] [-h] [-i] [-k] [-l] [-M <mixer device>] [-m <cpu clock MHz>] [-n] [-p <ptt comm port>] [-R] [-r <socket perms] [-s <soundcard clock correction>] [-t <gettimeofday correction>]

hfkernel is an implementation of the Pactor 1, AMTOR (SITOR) and RTTY radio protocols. It uses a standard soundcard as the mod em. PTT (push to talk) can be output on a serial port's RTS line. Pactor speedup (transition from 100 to 200 baud) is initiated by the software automatically after measuring channel conditions. hfkernel does not have its own user interface. Instead, it provides an UNIX domain socket. This was chosen to make it possible to change it to an Internet domain socket in the future. The terminal program and mailbox interface hfterm connects with this socket. hfkernel needs to be run as root, because it wants realtime scheduling policies. However, it is installed with the suid bit, and the startscript hf simplifies combined start with hfterm.

-2

standby: disable monitoring of 200baud signals

-3

standby: disable monitoring of 300baud signals

-a

audio device path (default for OSS: /dev/dsp) (for ALSA driver use -a plughw:0,0)

-c

path of the communication socket (default: /var/run/hfapp)

-f

standby: disable frequency estimation

-h

force half duplex mode (OSS only)

-i

invert PTT (default: PTT = positive signal)

-k

stop hfkernel (e.g. for use by scripts)

-l

logging (default: off)

-M

mixer device path (default: none)

-m

CPU clock in MHz (exact at the kHz level)

-n

no mmap() (which some cards/drivers can't) (OSS only!)

-p

path of the serial port to output PTT (default: none)

-R

disable the use of the rdtsc instruction (Intel systems only), the use of the RDTSC instruction may cause problems on Laptops and/or APM enabled.

-r

access permissions of the communication socket (default: 0777 = rwxrwxrwx)

-s

soundcard sampling rate correction

-t

gettimeofday correction factor

HF protocols are usually synchronous. They require an exact clock source to remain bit synchronous even during longer disruption of the propagation. SITOR (similiar AMTOR) for example specifies that the reference clock must be no more than 20ppm off the ideal value. It's difficult to find such an exact clock source, therefore all the options chosen by the current implementation require manual tuning.

If the soundcard is full duplex capable, the reference clock is derived from the sample clock. To correct for inaccurate sample rate information given by the OSS driver, the -s option can be used. Your soundcard should use real crystals instead of cheap ceramic resonators.

If the soundcard is not full duplex capable, the above method cannot be used. On Intel systems, the program tries the RDTSC (read time stamp counters) to see if it is available and working (on Pentium class computers and better, this should be the case). These counters increment at the CPU clock rate, therefore the CPU clock frequency must be known to the program, accurate to the kHz level (option -m). Don't be fooled by marketing gags, eg. an AMD K5 PR133 runs at 100MHz.

On non-Intel systems or if the RDTSC instruction is either unavailable or not working, gettimeofday is used, in the hope that the tv_usec field is accurate enough. Systematic frequency errors may be corrected by the -t option.

If you can receive the german timecode and reference frequency transmitter DCF77, you can use the dcf77 executable to measure the calibration factors. Tune your HF receiver to 78.5kHz LSB (or 76.5kHz USB) and start the dcf77 program (preferably as root). After 1-2 minutes (under error free conditions), the program should have aquired the DCF77 time. From then on wait about 15 minutes before writing down the measurements.

The swiss timecode transmitter HBG at 75kHz might probably be used, but I do not know its exact transmission format (it seems to be very similar to DCF77).

If you cannot receive either DCF77 or HBG, you can use the reffreq binary and a known exact clock source in the 200Hz-20kHz region. A readily available in most households and usually very accurate source is the line sync of an ordinary TV receiver. As far as I know, the line sync of the second public german TV channel (ZDF) is used as a reference frequency even by official bodies. Tune your TV equipment (with baseband video output) to a TV channel and feed the video output to the soundcard. Run reffreq -f 15625 as root. After a few seconds, the program should have calculated the correction parameters. (The command line above implies PAL format with its 15625Hz line sync frequency. For other video formats, use the appropriate frequency.)

The soundcard must be supported by the OSS driver. It must support 16bit sampling in the endianness of the CPU, 8kHz sampling rate, memory mapping of the DMA buffers and triggering. It must be able to work in "mono", which some new cards cannot do any more! An improvement is planned. A full duplex soundcard is preferred.

On half duplex soundcards, the soundcard must be switched if the protocol changes from receive to transmit and vice versa. This lasts quite long; anywhere in the region of 5 to 35 ms. The program measures an average at startup. It tries to hide this latency under the PTT keyup delay (TXDelay), so set the txdelay to a larger value! And hope that the propagation time to your peers plus their txdelay is also longer.

The audio levels and parameters may be set with the usual mixer tools. Builtin AGC should be disabled.

Currently, RTTY, Amtor, GTOR and Pactor 1 are supported. RTTY and Amtor has very limited support for national charsets, due to lack of documentation.

All implemented protocols are not very robust by nature, and are not state of the art. The current version does not do frequency tracking (like almost all other amateur implementations). This is somewhat more problematic as the filters are probably narrower (their bandwidth gets adjusted to the reception speed automatically) than in other implementations. Pactor's diversity combining scheme commonly dubbed memory ARQ by advertising is implemented but inherently broken by design. The inventors assumed that noise statistics are the same during retransmissions which is usually wrong. Real diversity combining schemes should use equalizer bits (i.e. bits already known to the receiver) which enable the receiver to estimate the channel state and combine retransmissions accordingly. The time tracking might be responding too fast.

This implementation is currently very picky about the other hardware installed on the computer. The reason is that the hfkernel processes, even though with realtime scheduling policy, only run after every interrupt handler and every bottom half of the operating system has terminated. Depending on the computer speed and the nature of the drivers, this can last very long, more than 100ms. More than 10ms has a very detrimental effect on this HF protocol implementation. The conclusion of this is that the L1 (FSK modem) should probably go into kernel space. But currently I do not like the idea of me having to implement yet another soundcard driver...

The documentation on the pactor 1 protocol, the CCIR document defining SITOR (AMTOR), OSS and ALSA programming docs. More and recent version's documentation in /usr/share/doc/packages/hf ! man hf, man hfterm, man dcf77rx, man dcf77gen and this manpage are short introductions and can not be not actualized regularly!

or misfeatures will surely be found...

Thomas M. Sailer, HB9JNX/AE4WA, sailer@ife.ee.ethz.ch graphical interface hfterm improved by Ralf-Axel Krystof, DF3JRK, df3jrk@gmx.de and Guenther Montag, DL4MGE, dl4mge@darc.de ... have a lot of fun !!!