  	-----=== HF ===-----
	
H F  -  H O W T O 


LINUX HAM RADIO SHORTWAVE PROGRAM
FOR RTTY, AMTOR, GTOR, PACTOR 1, MT63
WITH TCP/IP INTERFACE TO F6FBB MAILBOX 

Version 0.7.3 (4/2005)
By Gnther Montag DL4MGE



1) Introduction :
   ==============
   
The hf program suite implements the amateur radio FSK protocols RTTY,
AMTOR (SITOR), GTOR, Pactor-1, and Pawel Jalocha's multitone protocol
MT63 and a CW elbug for mouse and paddle.

It uses a normal soundcard as modem.  The speed change in Pactor (100 to
200 baud) is done automatic. A PTT (push to talk) signal can be output
via the RTS pin of a serial interface.
   
The implementation of the protocols uses a binary called hfkernel,
which runs as daemon in the background. By UNIX domain
socket it communicates with its graphic user interface hfterm. 

Hfkernel internally uses three threads:  one is the modem code which
reads/writes to the sound card in real-time mode, one is the actual
digimode protocol, and one that handles socket I/O.

Hfkernel can be configured to run with the (traditional) OSS sound
drivers and the new ALSA driver's OSS emulation, but also for direct use
of the new ALSA API. 

Tom Sailer's original code might still not run with every soundcard / 
driver, as it uses the mmap() system call (for low latencies, needed for
real time mode in Pactor and Amtor ARQ), which is not supported by some
cards. Crashes are possible. 

The experimental option '-n' (no mmap) for the OSS driver is working
good very often and is now also available for the 2 of the 3 calibration
programs in the package, that use mmap(). For hfkernel, this option is
now (V.0.7.3) set by default in the main configuration file, to make the
first start easier.

For the ARQ modes and MT63 hfkernel should be testet without the option
-n, and a calibration will be necessary in most cases. For this three
calibration tools are included.

The start script hf reads and tests the global configuration file 
/etc/hf.conf, and starts hfkernel and hfterm.

hfterm can connect via a TCP port to the well-known mailbox program
F6FBB and to any other mailbox program, any program that can be 
accessed via a TCP/IP port, or that can be configured as an internet
service by /etc/inetd.conf.

So hf can be used as an automatic Pactor, Amtor or  (in future) MT63 ARQ
mailbox or for remote control.

The program was made in 1997 by Tom Sailer (Thank you!) and is being 
developed by Axel Krause, Gnther Montag and many friends.

Please contact us by the mailing list!



2. Installation, Configuration, first test:
===========================================

2.1. Requirements:

Hardware: Not critical. Processor from 100 MHz on. RAM from 16 MB on.

Software: hf makes use of gtk+ toolkit (Version > 1.2.0), which is in
all linux distributions. Package 'gtk-devel' must also be installed. To
know if this is installed, type  'gtk-config --version'. If the compiler
complains 'Cannot find GTK: Is gtk-config in path?', but you have gtk,
look for it (locate gtk-config) and (as root) a link like this may help: 

# ln -s /opt/gnome/bin/gtk-config /usr/bin/gtk-config 
or insert the path to gtk-config into /etc/ld.so.conf.


2.2. Installation of Source Package:

unpack:
# tar -zxvf hf-<version>.tar.gz,
go into directory:
# cd hf-<version>
start configure script:
# ./configure
(options are visible with configure --help, but 
normally you need no options)
compile it (c and c++ compilers must be installed):
# make
install it (as you do not have write permission to /usr/bin, as root):
# make install


2.3. Installation of rpm Package:

The i386-rpm is meant for older systems (also without ALSA sound driver),
the i686-rpm for newer ones.

# rpm -i hf-<version>.rpm
or, if false error "gtk missing":
# rpm -i --nodeps hf-<version>.rpm

The global configuration file is /etc/hf.conf, normally you only
have to enter your serial line for PTT here. 


2.4. First test:

2.4.1 Test hfkernel on a console:

Start once as root, once as user
# /usr/bin/hf
without options.

The start script hf reads and tests the global configuration file 
/etc/hf.conf and gives hints. If new installed, it makes a directory
"hf" in your home directory and fills it with the example files from
/usr/share/hf/hf-examplefiles. 

If hfkernel is started successfull, after the first messages a row of
numbers like this will roll over the screen. 

hfkernel running: corrout .... intermediate ... 

It is the ECG. This means, the "heart" of the program, hfkernel beats
regularly. Won!  Finish it for now with <Strg>+c. 

If no heart-beat, hfkernel needs some special options, see chapter 4.

For quick test, try at a console these options in this order:
# hfkernel 
# hfkernel -a plughw:0,0
# hfkernel -n
# hfkernel -R
# hfkernel -h -R
# aoss hfkernel 
# aoss hfkernel -n
# aoss hfkernel -h
# aoss hfkernel -R
# aoss hfkernel -h -R
If succesfull, write down the good options and set them in /etc/hf.conf
and be happy.


2.4.2 Combined start of hfkernel and hfterm by the script hf:

If hfkernel could be tested successfully, open a command window under X 
by <Alt>+F2 and write in it 

# /usr/bin/hf

The start script hf will now start at first hfkernel in the background, 
and and then the graphic terminal hfterm in the foreground.  To test
signal input and the soundcard gain, open the spectrum display  with F2
or <Shift>F or the Spectrum button. Squelch can be set with the  right
mouse key. Decoded characters should appear in the rx window.

If hf runs, as root create a link onto the desktop with 

# ln -s /usr/bin/hf /home/your_user_name/Desktop/hf. 

You also can right-click on the desktop, 'new', 'application' ... but as
an old linux rabbit you will know that. So you can start the program
whith one mouse click. 


2.5. Configuration


2.5.1. Global:

The globale configuratio file, read before start, is /etc/hf.conf. It
can be edited (as root) with any editor. Here the serial port for PTT
and elbug should be set. There are also options to select sound card and
driver.


2.5.2. Personal:

Your personal configuration (call, name, baud rates) is done by the menu
'config' within hfterm.

The text macros can be changed by menu 'fixtexts'.

Your personal directory (configuration, fixtexts, log...) is "hf" in
your home directory. It is made at first start of hf and filled with
examples. 

The documentation is in /usr/share/hf, and - depends on distribution - 
also in /usr/share/doc/hf or in /usr/share/doc/packages/hf,
the main text is this, which can also be seen via help menu.



3. PTT and Elbug Wiring :
=========================

3.1. PTT / Key:

As in evey ham radio digimode program, you have to connect computer and
transceiver with 1 npn transistor und 2 resistors:

                              _____
                      /------|_10k_|---O  
 RTS pin             /                PTT pin 
 Computer           /                 Transceiver
       _____    B |/      C
 O----|_10k_|-----|\
                  |  \_|  E
                      \
            npn        \
            Transistor  |
                        |
                        |
               gnd    =====
                                               

You need once more the same circuit, if you want to use the elbug with
DTR serial pin to key input of radio. You also can leave the elbug at
RTS and change key and PTT with a switch.

There are many more sophisticated possibilities for ptt and key with
opto couplers and relais. 

For some transceivers the ohms of the circuit above are too
much, then leave out the collector resistor and solder 330 Ohms at the
base. Tnx to Waldis Jirgens for your good example for this case at:
http://members.optusnet.com.au/~waldis/ifacen.gif, which contains also a
transformator coupling for the soundcard io.

3.2. elbug:

Middle pad: +9 V via Resistor 2 k                                                 
Left  contact: -> DCD (9-pin plug: 1) (25-pin plug: 8)     
Right contact: -> CTS (9-pin plug: 8) (25-pin plug: 5)     
Ground:               (9-pin plug: 5) (25-pin plug: 7) 


4. Options and Problem Solutions with for hfkernel :
====================================================
    
Does the start script hf fail, or do you want to start manually to learn 
about and test the options?

Try to start first hfkernel as root from console quite simple:
# hfkernel

It is a special program and has sometimes special needs...
So you must know some things to understand the most common errors.


4.1. Superuser Rights

Because of its special harware approach (real time mode, high priority, 
mmap) hfkernel needs superuser rights. In normal use you should work as 
normal user, however. To simplify the start, during installation the
suid  bit is set to hfkernel. Then it can be executed by normal users
with superuser rights. If this runs and o.k. for you, you need not read
on this section.

Errors containing 'permission denied' or 'pthread_create' at start of
hfkernel as non-root show a problem here: Is the suid bit set?

# ls -l /usr/bin/hfkernel 
should result something like:
-rwsr-xr-x   1 root     root       372757 Sep 13 10:34 /usr/bin/hfkernel
The 's' is the suid bit, gives normal user super-user-rights when
executing it. If not there, set it by hand:
# chmod u+s /usr/bin/hfkernel. (same is chmod 4755 /usr/bin/hfkernel)

If you don't wish this, you need one of the programs that make normal
users able to run programs with root rights: 'su1' or 'sudo'. These are 
included in most linux distributions.

su1: (see 'man su1')
Install it, open /etc/su1.priv whith an editor 
(of course, as root) and change like below:
	# Define some privileged users
	define	GODS	root <your_user_name>
and
	# These never require a password since they are reasonably safe
	ask	never
	allow   GODS    prefix  /usr/bin/hfkernel
Now, hf (started by you as normal user) calls hfkernel (with superuser rights).
An example file for /etc/su1.priv is /usr/share/hf/hfsu1.priv.txt
However, su1 is not contained any more in newer linuxes.
  
sudo: (see man sudo)
First '/etc/sudoers' has to be edited as root.
Insert the line:
<your_user_name> ALL=(ALL) NOPASSWD: /usr/bin/hfkernel
Now, hf (started by you as normal user) calls hfkernel (with superuser rights).

Be careful: All of theese workarounds can be security holes!

The most primitive way is:
start hf as root, then start hfterm as user.


4.2. Serial Line

Errors containing 'ioctl: TIOCMBI[CS]:'
Conflict with the mouse? Is the serial line correct in /etc/hf.conf ? 
(As default none is set, so no error at first...)


4.3. Problems with soundcards:

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

hfkernel with Tom's original code does not run with every soundcard and
/ or driver.  The reason is not bad code, but good code: Because of the
time-critical FSK ARQ protocols (Amtor, Gtor, Pactor) it is necessary to
work in real-time mode. For this, the author Tom Sailer choose the best
way and wrote the program with the "mmap()" system call. This is also
called "DMA" (direct memory access) and means mirroring the soundcard's
ring buffer directly into the working memory of the computer. And not
every soundcard can do this, and not every driver supports this
correctly. 

* So, the '-n' option works around this and is now set as default in
* /etc/hf.conf, to make start easy. But test hf also without it, for
* better performance in the FSK ARQ modes.

For MT63, it is no problem if the mmap mode is not working.

On half duplex soundcards, the soundcard is 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.


4.4. Problems with Sound Driver

4.4.1. What is a driver, what is an API?

A driver is a program that translates 'general' commands from a user 
application (e.g. hfkernel, or an audio file player) into 'special' 
commands for a special device, like the soundcard Via 82C686.

This means, the driver provides the 'general' command sets to the 
programmer, and translates them into the 'special' ones in the 
background when the application is running. 

The 'general' command sets are also called API (Application Programmer`s 
Interface) and you can imagine them like a little `programming
language', or something like a special jargon for a special area within 
c.


4.4.2 OSS and ALSA

For Linux there are 2 different API's for sound card programmng:

OSS: 

The older, traditional API is OSS (Open Sound Systems), in
distributions up to about kernel 2.4 the OSS drivers are included as 
loadable kernel modules 

There are also commercial, partially better developed OSS drivers.

In older Linux distributions there was something between, an OSS-Paket 
paid and free only for the purchaser of that distribution, e.g. in my good 
old SuSE 6.3 to be found in /tmp/opso and working good with hf, I am still 
using it. 

The standard OSS modules can be found in /lib/modules/<kernelversion>/misc.
(Source in /usr/src/linux/<kernelversion>/drivers/sound). You can install
them with modprobe (if ALSA is there, after unloading ALSA by rcalsasound
stop). See man modprobe, modprobe -p <module> (for parameter info).
modprobe -d <module> shows which other depending modules are to be loaded
before. You will get help for  ISA-PNP cards by pnpdump and isapnp, (see
manpages) and for PCI cards by lspci, and you find docs in 
/usr/src/linux/Documentation/sound for your sound card.

As far as I know, OSS is still being maintained. The
new OSS drivers are not free any more (www.opensound.com).

ALSA:

ALSA (Advanced Linux Sound Architecture) is new , is more flexible,
complexe and maybe sometimes still more error-prone and slower. The ALSA
modules are optional from kernel 2.4, standard from kernel 2.6 and will
play the main part in future. It supports many of the newest  soundcards,
it is being developed rapidly at SuSE and is taken by more and  more other
linux distributions. Latest version of ALSA and lots of good documentation
at:
http://www.alsa-project.org
http:///www.alsa-opensource.org
Mailing lists can be subscribed, almost 1000 mails a month:
https://lists.sourceforge.net/lists/listinfo/alsa-devel
https://lists.sourceforge.net/lists/listinfo/alsa-user

As root by 
# lsmod
you can test what sound driver modules are running in your Linux:
The ALSA modules start with 'snd-'.

The ALSA API has a very different logic compared to OSS-API. If ALSA would
not contain an additional OSS emulation, things it would be bad for  us,
the many good old (ham, music, game) programs would not run with new 
linux.. :-( 

(You can compare the different codes in hfkernel/l1/oss.c und
hfkernel/l1/alsa.c !)

Now it becomes a bit complicated: ALSA has 2 alternative kinds of
OSS-Emulation:

The default one (which is in the kernel modules) is activated if a
program like hfkernel approaches the first (2nd ...) sound card as
/dev/dsp0 (1 ...), as all OSS programs do.

The other, alternative one is an additional library, which is linked to the
program by the script  /usr/bin/aoss (in which is written: env
LD_PRELOAD=/usr/lib/libaoss.so $*) e.g.: 
# aoss <program>. 


4.4.3 hfkernel, OSS und ALSA:

hfkernel's soundcard code, like most ham programs' code, was written for
OSS-API, but runs also with ALSA's 2 OSS emulations, which are also being 
steadily improved. I could not yet find out if the aoss prefix has an 
advantage. (It can be set in /etc/hf.conf.)

Both ways of ALSA OSS emulation are still in development, and because of
hfkernel's special desires (mmap and realtime mode) it sometimes runs with 
OSS, sometimes with ALSA's OSS emulation, sometimes not at all, depending
on the sound card! The guys are working very hard on improvements, so
please try to get the latest version of ALSA and be patient with your
patient because your patient is a patient patient. 

I added an experimental code, written in OSS API, that does not use mmap(),
but normale read() and write() access instead. To use this code, option
'-n' (no mmap) is prepared. 

For version hf-7.1.1 I added a full duplex code written in ALSA API!
To test it, invoke hfkernel using the ALSA convention with the option
-a plughw:0,0 for the first, or 
-a plughw:1,0 fr the second soundcard and so on.
Also for this option a fixed setting is prepared in /etc/hf.conf.

Still the code for OSS API is default in hfkernel, but please test the 
ALSA code! Tnx !! ;-) 


4.4.4. Plan for sound driver problems with hfkernel

Errors with  'open':
Is the sound driver loaded at all ? 
(lsmod, and can another programm, e.g.  dcf77gen oder dcf77gen -n, 
make a tone?)

If 
# hfkernel 
does not run, you may test the options in this order:

if ALSA driver is installed (teste as root by 'lsmod', the modules start 
with '-snd' ):
# hfkernel -a plughw:0,0

if not: 

Error with 'MMAP':
Test the no-mmap version (using only read()/write() access) by:
# hfkernel -n

Sometimes hfkernel says, the soundcard is full-duplex capable, 
but in fact it is not: Force halfduplex mode by  
# hfkernel -h 

If in half duplex the numbers in 'corrout... intermediate...' 
are always 8000, the rdtsc time query does not work. 
This happens often with non-Intel-processors. 
Then add option '-R' (disables RDTSC instruction):
# hfkernel -R 
or 
# hfkernel -h -R

Still nothing?

Then try to add the aoss-Prefix to all of these options 
(excluding -a plughw:0,0, there it is no sense, it is no OSS any more):
# aoss hfkernel 
# aoss hfkernel -n
# aoss hfkernel -h
# aoss hfkernel -R
# aoss hfkernel -h -R

Still nothing?

Try another soundcard.
Try latest ALSA version, its becoming better.
Try commercial OSS, if you have (maybe free in an old distribution, like 
me, see above!).

if (nervous system == corrupted) {
    subscribe_mailing_list
	("https://lists.sourceforge.net/lists/listinfo/hfterm-hackers");
    mailto(hfterm.hackers@sf.net);
    sleep (24 hrs);
    break;
}

Beware: Before V.0.6, depending on some combinations of soundcard /
sounddrivers, hfkernel hang up in an endless loop with  "... fragments
passed since last wakeup" or "OSS driver lost interrupt".  Sorry, there
were some crashes ! In Version 0.6 I built in a brake to prevent this,
so hope it helps.  


4.4.5. Saving the configuration and your soul

If hfkernel runs, fix it with glue and never touch the running system
again. This means, fix your working options in /etc/hf.conf and backup 
this file, so that it can not be lost at next update (it will also contain 
your precios golden 3 correction factors later, after successfull
calibration!!). So you can start hfkernel and hfterm easy by the script hf 
later, which reads /etc/hf.conf.

Never work more than 24 hours an evening. Look if your family is still
there. Never forget: Do it only with fun. If depressive, mail me. I am a
psychotherapist. Real. It made me depressive sometimes, the whole thing, I
healed myself by playing piano and doing other things, and by celebrating
computer-free days.


4.4.6. Complete list of hfkernel's options:

  -2: standby: disable monitoring of 200baud signals
  -3: standby: disable monitoring of 300baud signals
  -a: audio device path (default: /dev/dsp (OSS))
      (For ALSA: -a plughw:0,0)
  -c: path of the communication socket (default: 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) (experimental!)
      (for soundcards that do not support mmap(), OSS only)
  -p: path of the serial port to output PTT (default: none)
  -R: disable the use of the rdtsc instruction (Intel systems only)
  -r: access permissions of the communication socket (default: 0777 = rwxrwxrwx)
  -s: soundcard sampling rate correction
  -t: gettimeofday correction factor


   
5. hfterm and the digimodes:
============================

5.1. Introduction

Most of the program is very intuitive. Help with F1. The state menu,
mode menu, and the buttons will explain  themselves. If you don't like
mice, like me, the shortcuts will make you happy (see menues): modes by
F..., text macros by <Shft>F... 

There are at all 3 levels of debugging output:
1. the xterm or console running in the background: hfkernel's output,
   sound driver and protocol low level.
2. the monitor window: level 2 of the protocol level
3. the most useful for the user: the Status Display Window on the 
   bottom of the screen tells you what the program is just doing. 

If you want to know how the digimodes sound:
Examples in www.wunclub.com/sounds !

Hfterm thinks. (autorx / autotx feature). If you write into the tx
window, it switches to the fitting or last tx mode. After some seconds
it switches to rx, exept you had chosen a tx mode explicitely, e.g. RTTY
TX.  This autorx/tx is useful for the beacon and mailbox functions, but
can be disturbed by too few waiting and too much clicking. Especially
MT63 has long delays between rx and tx and back because of its data
interleave! Be patient! But I like it, it makes me relax. 

If you change a mode, do not go from a transmit mode directly to another 
transmit! But, as you know as a good ham, go first on rx (or wait for
autorx), then on rx of the new mode, then on tx.

If the program hangs, first wait, then maybe you have to restart (hf, not
the computer. We do not have anything to do with Bill.) The worst case is 
a hang in an endless loop ('top' says 96% CPU usage), if hfkernel crashes. 
Then only this helps (from a console)
# killall hfterm
In last minute I made a counter and an emergency exit at count of 1000 in 
hfterm's socket poll routine, does it help?

I did not yet get the reason for this loop. It comes more often in newer
linux, and if hfkernel runs in an xterm in the background of hfterm.
(Race-Condition in message system via hfapp by slowdown?) Switch off the
xterm in /etc/hf.conf, or, for debugging, take xterm -hold -e hfterm.


5.2. General

5.2.1. SPECTRUM DISPLAY

If you are a new user, get into feeling with the program by looking at the
spectrum. If no signal appears, look if the tx and the soundcard  (line
out) are cabled correctly, and if the signal is adjusted well by a
potentiometer in the line or by a mixer like aumix (for OSS) or alsamixer
(for ALSA). The spectrum has a blue and a red line for mark and space, and
in the bottom there is a green line, the squelch.

Mark and Space:
You can change mark and space frequency with the mouse: If one of the
given shifts is chosen, the left button will select the mark (and space
will be mark plus shift), or the middle button will select the middle
frequency. If the "other" shift is chosen, you just have to click 2 times
and select first mark, then space, and the shift will be calculated. 

Squelch:
The right button selects the squelch.


5.2.2. PARAMETERS

By 'Ctrl P' you will open a notebook where you can enter parameters.
There are personal ones like power, rig,  antenna, locator, qth, name,
mail address, which will also be used by the text macro processing
functions to create texts while transmitting. There are program
parameters like mark, shift, baudrate, txdelay etc. for the different
modes. If you finish the program, the parameters will be stored in
~/hf/hfterm.rc (digital, please do not edit!).


5.2.3. FIXTEXTS

If you like text macros - edit your Fixtexts (up to 12) by 'Ctrl T'. There
are macros allowed for your call, name, QTH,  locator, rig, pwr, ant,
mail/internet address, timestamp and all the dates  of your QSO partner,
and: [B] for beacon - e.g. CQ. . You can not keep this all in mind?  No
matter, the window on the bottom reminds you. If you want to transmit one
of the macros, click on one of the 12 buttons, or 'Ctrl F<1..12>', lean
back and drink coffee.  The fixtexts are stored in ~/hf/fix.<nr>, they can
be edited there. By renaming or inserting you can import here any text,
maximum 1024 bytes. You can also choose a file to transmit from file menu.


5.2.4. BEACON

As said before, if a fixtext contains [B], the beacon is started when  you
select it. You can stop it by <Alt>+B or the file menu. If you want to send
an external file as beacon, start the beacon mode by <Alt>+B or the file
menu. A file selection dialog appears. After stop and new start of the
beacon the selected file is sent again. If you then select a fixtext
containing [B], this is the new beacon etc. If hf runs as mailbox, during a
connect from remote the beacon is suspended, after logout it is continued
with the same text.

The interval of beacon transmissions is set at the config menu, it is
rounded on a multiple of 5 seconds.


5.2.5. LOGBOOK

We even have 2 logbooks. One for big screens, always open. Write your
entry, and click 'save' or 'clear'. The other for my little old screen
(a bigger one does not fit in my shack).  Shrink the big log frame by
'Ctrl Q'.  By 'Ctrl N' you can open the little log frame if you need it
and you will still see the status display on the bottom. 'Ctrl L' shows
the log list. 'Ctrl A' archivates the log file and starts a new one. 
With 'Ctrl O' you can search old entries to  edit or clear them. The log
will be stored in portions of 50 entries. The old log files are numbered
and can not be opened by hfterm any more, but with every text editor.
The ascii format is adapted to cabrillo standard. If you want  to change
output for your special contest, if you understand the printf format
specifiers (see man  printf), you can change the source easily in
hfterm/src/log.c !


5.2.6. RX-TEXT

If you receive something, it will be stored. If hfterm runs long, from 
time to time half of the rx window contents is appended to this file. The
old stored rx files will be renamed, and kept, up to 5 of them, in ~/hf. In
the file menu, there is also an option to select a filename for storing.


5.3. The Modes

5.3.0 CW Elbug

My newest hack, maybe it is unique in Linux (is it?). I was inspired to
do it by Larry Winslow's "CW" DOS program. The circuit is also from
Larry's docs. It is an elbug only, maybe next time I will include
keyboard encoder and decoder which are already realized in gMFSK. 

The elbug is silent, my experiments with soundcard tone gave too big
delay. The thing with the PC speaker is coming, have to read into Joop's
and Rein's code of cedaemon ...
(http://www.qsl.net/pg4i/linux/cwdaemon.html).

You can test the elbug with the right and left mouse keys by clicking
into the tx window. Be sure the key input of your rig is cabled o.k.,
see wiring instruction above. Speed can be adjusted in the config menu.

There is also a console program elbug!


5.3.1. RTTY

For founding first friendship with the program try to receive and later
transmit RTTY. Usual values for shift: 170 Hz and for baudrate: 45.  Tune
on your tx e.g. in the 20m band and look for the typical  beautiful
machine-sound of rtty. Open the frequency spectrum display through the menu
'utilities' or - quickest - by keying F2 or 'Ctrl  F' (keep Ctrl pressed
and hack on F). In my experience it is quickest not to change mark and
space in the program, but turn the tx until the double peak of an rtty QSO 
come under the blue and red lines in the spectrum. By 'Ctrl F' again leave
the spectrum. You will see the Receive window decoding text. If someone is
calling CQ - if you have an amateur radio license - why not answer? Maybe
you have to adjust the output level of your soundcard,  do not tx with too
much power (20 W is enough!), listen before tx... like in all the
digimodes. If you hold on transmitting, there comes a "diddle" with
"LTRS...".


5.3.2. The FEC / ARQ Modes PACTOR - AMTOR - GTOR

If you want to test these modes with hf, please try in any case to run
hfkernel without option -n, and try also the ALSA Full Duplex driver by
option -a plughw:0,0 !


5.3.2.1 Error Correction Algorithms:

Pactor (hf implements Pactor Level 1 which has up to 200 Baud) and
Amtor can run with FEC = Forward Error Correction: Signals are sent 
repeatedly and averaged.

Pactor, Amtor and Gtor can build Connects of 2 stations with ARQ =
Automatic Repeat Request: After each data packet the receiver sends a 
control packet, confirming correct reception (if the CRC,a checksum, 
calculated by the receiver is o.k.) or asking for repeat, slowdown, 
speedup or change of direction.


5.3.2.2 Amtor 
5.3.2.3 Gtor 

The Howto is not yet complete here, please send
me docs on Amtor und Gtor!

5.3.2.4. PACTOR

Pactor is a science... If you do not know what Pactor is, read 
'pactor.txt' in /usr/share/hf (sorry, German only. Please translate it in 
your language. And mail it to me. Tnx !!!) First train to receive. It is
more difficult than RTTY. In the spectrum Pactor looks almost like RTTY,
but the sound is  hacked in typical 1.25 sec rhythm, (Amtor: 0,45 sec),
sometimes you can hear the short control signals  of the other station in
between.  Even if you adjust frequency exactly, sometimes you will not
decode anything  because people are using Pactor level II and maybe III
with a PTC.  Sometimes you fish a callsign out of the fog, which is sent in
level I.  Call CQ by FEC. Be patient! If you have a partner answering by
FEC, try to call him by ARQ. Call a mailbox by ARQ.  After transmitting, do
not go to standby directly, the  program might hang. Instead, do QRT ('Alt
Q'), wait a little (let the program finish its QRT routine!), then it will 
go to standby by itself.


5.3.3. MT63

Very much thanks to Pawel Jalocha, SP9VRC, who made this great new mode, 
which is said to be very robust, especially at bad conditions better than
Pactor 3, and might be precious for future "emcomm" systems. (Emergency
Communication, see the linlink mailing list at www.wetnet.net,  there is an
interesting discussion about this topic at the moment.)

Because of the many interesting experimental possibilities I inserted
Pawel`s complete MT63 package with the console programs  mt63tx, mt63rx und
mt63trx, the tools morsecod, peakrms, addnoise  and the calibration program
ratecal1 into the hf package. Thanks! 

I insert here a part of Pawel's documentation on MT63.
(The complete text is mt63.txt in the doc dir.)

This is the release 0.5 of the MT63 modem for LINUX.
Date: 08-JUL-2004, Author: Pawel Jalocha, SP9VRC, Pawel.Jalocha@cern.ch
Important notes:
1. To take full advantage of the MT63 modem, the sampling rate of your
   sound card needs to be either calibrated or dead precise on 8000.0 Hz.
   For now, the MT63 receiver doesn't tell you the rate mismatch, I may provide
   such facility in the next software versions.
2. When connecting the audio to your PC/laptop be carefull not to damage
   the computer audio inputs. I suggest you first connect the grounds
   of the radio and the computer and only then connect or disconnect
   the audio cables.

The MT63 modem is intended for amateur radio as a conversation (RTTY like)
mode where one station transmits and one or more other stations can listen.
In short, the modem transmits 64 tones in its 1 kHz bandwidth: the audio
range for the tones is 500-1500 Hz. The differential bipolar phase
modulation is used to encode 10 bits of information per second on each
tone. The user data in the form of 7-bit ASCII characters is encoded as a
set of 64-point Walsh functions. The bits are interleaved over 32 symbols
(3.2 seconds) to provide resistance against both pulse and frequency
selective noise or fading. The character rate equals to the symbols rate
thus the modem can transmit 10 7-bit characters per second. This modem can
as well run in two other modes obtained by simple time scaling, the
possible modes are summarized here:

Bandwidth  Audio range  Symb. rate  Char. rate  Interleave/char
  500 Hz   500-1000 Hz     5 baud     5 char/s   6.4 or 12.8 sec
 1000 Hz   500-1500 Hz    10 baud    10 char/s   3.2 or  6.4 sec
 2000 Hz   500-2500 Hz	  20 baud    20 char/s   1.6 or  3.2 sec

For each mode the interleave factor can be doubled thus each character
becomes spread over twice as long period of time. The first experiments
with this mode were done on the EVM56K DSP evaluation board from Motorola
and the package was named MT63ASC.ZIP. This LINUX implementation is written
to be compatible with that package. The MT63 modem is made for single side
band operation. The audio generated by the modem (sound card output) is
applied to the SSB modulator. On the receiver side, the output of the SSB
demodulator is put into the sound card input. The envelope of the MT63
signal is not constant as in other multi-tone systems - it is rather
noise-like. One must be carefull not to overdrive the transmitter. The
receiver of the MT63 is self-tuning and self-synchronizing thus the radio
operator is only required to tune into the signal with +/- 100 Hz accuracy
for the basic 1000 Hz mode. The modem will tell the actuall frequency
offset after it is synchronized. The operator should not try to correct
this offset unless he is able to tune  his radio receiver very slowly,
because the MT63 as a low rate  phase modulated system does not like sudden
frequency changes. 

Pawel, SP9VRC. 
(Thanks Pawel!)

I made in hf the "flushing data interleaver" at the end of each transmit
cycle still longer than Pawel in his original program,  to prevent my
squelch function from cutting away the last data at receive.



6. Real Time Problems and Calibration :
=======================================
   
6.1. Basics

HF protocols are usually synchronous. They require an exact clock source to
remain bit synchronous even during longer disruption of the propagation.
SITOR (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. Also MT63 in hf uses
the sample rate correction factor (-s).

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.

RTTY, Pactor-FEC and Amtor-FEC might work without calibration, there have
also been reports about successful Pactor- / Amtor-ARQ  connects without
calibration. It depends on the accuracy of your card`s samplerate!  If it
is bad, or the connects should last longer, however, a calibration 
improves the performance of the program.  Also for MT63 a calibration is
necessary in many cases.

As described above, with options hfkernel can be given correction
factors for the soundcard's sampling rate (-s),
the cpu clock rate (-m) and the gettimeofday funktion (-t).
-s only works for full duplex mode (time derived from soundcard),
-m only works for half duplex mode with working RDTSC instruktion,
-t only works for half duplex mode without RDTSC instruktion,
which is worse, as the prozessor gets time via gettimeofday(), which is
not so exact because of changing system load.

In the hf package there are 3 Programs for calibration. Two of them,
dcf77rx and reffreq, even write their results to the config file
/etc/hf.conf by themselves. But please test it before use, and maybe you
have to correct something by hand. In the end of this chapter I will
describe a very primitive estimation I succeeded with, and a script which
guesses the sample rate for MT63. This helps for old hardware where the cpu
and / or memory might not be sufficient for the calibration algorithms.


6.2. dcf77rx   

uses the timecode signal of the well-known German long wave reference
frequency transmitter DCF77 at 77,5 KHz near Frankfurt, that has a power of
25 kW an can be received up to about 2000 km distance almost all over 
Europe. It gives, btw, the signal for the radio clocks. (See also
dcf77.txt, sorry only German, translate it at least into French and Polish 
!!!.) If you never heard this signal, just try the demo program dcf77gen !

The signal must be converted to a frequency of 1000 Hz and put to the  Mic-
or Line in - input of the soundcard. Tune your receiver to 78.5 kHz LSB
(oder 76.5 kHz USB). I had no LF receiver, so i got inspired by ideas from
the internet and home-brewed a little converter that makes  4077,5 KHz from
the 77,5 KHz, which I can receive with my rig.  I needed only a 4MHz
crystal from the box, 5 npn transistors and some more parts which need no
exact values. To receive an old ferrite from a radio or a wire is o.k. The
circuit is in /usr/share/lfconv.jpg. 

Start the dcf77rx program (preferably as root). In SSB or cw mode you have
to tune exactly on 1000 Hz, until you see the second ticks being recognized
as regular as possible. The option -v 2 or (after some training) the
rotating rod will help. 

After 1-2 minutes (under error free conditions), the program should have
aquired the DCF77 time. From then on wait about 15 minutes so you can check 
the results. You can write them down for sure. But they will be written 
automagically to /etc/hf.conf. 

But please see there if the correction values seem  credible and constant,
and edit them if necessary! The last value of each kind hf.conf will be
read by the  start script hf and used as options for hfkernel.

dcf77rx also has an option to set the system time (see man dcf77rx).

dcf77rx and also dcf77gen already have the -n (no  mmap) option. It gave
acceptable values for the most important correction  parameter -s for me.
The others vary. 

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

If you want to tune 2 sound cards together, also over radio,  one partner
could run dcf77gen and the other dcf77rx.


6.3. reffreq

If you cannot receive  DCF77 or HBG, you can use the reffreq binary and a
known exact clock source in the 20Hz-20kHz region. 

If dcf77rx works bad, but if you can receive the DCF77 signal in AM (2500
Hz), run reffreq -f 2500, it pulsates, but it works!

If you are looking for a reference frequency on the radio, hfterm's
spectrum can help you in raw measuring the frequency. Guess it is a
straight value, you can then use reffreq with it.

Thanks to Dave <dalechid@cox.net> who gave the good info on the US time
standard stations WWV and WWVH, Boulder, Colorado,  which transmits 500 and
600 Hz in an alternating way at  2.5, 5 and 10 MHz AM! So run reffreq -f
500 or reffreq -f 600. In spite of the 10 and 25 ms periods without a tone
and the 5 ms 1000 Hz marker, reffreq seems to come up with good, accurate
calibration data. Interesting details of the WWV signal can be found at:
http://www.boulder.nist.gov/timefreq/stations/iform.html (I know there is
somebody out there who will get inspired by WWV`s spec at  this URL and
programs a tool like dcf77rx for  WWV!)

Who knows more about JJY in Japan?

A readily available in most households and usually very accurate source
is the line sync of an ordinary TV receiver. 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 15625 Hz
line sync frequency. For other video formats, use the appropriate
frequency.)

In CQDL 3/2003, page 168, there is an interesting article by Stefan 
Steger (sorry, German only), describing how to get the line frequency
signal from a TV, with a circuit that derives reference frequencies.
(http://home.t-online.de/home/stefan.steger/homepage.html)

With a scope I could get the 15625 Hz from the cable that connects a
satellite receiver with the TV.

Reffreq could serve for calibration over the air:  One sets in hfterm
mark and space to 1000 und sends RTTY (RTTY TX im Mode menu), Funkgert
auf AM.  with the transceiver at AM. A sinus tone of 1000 Hz will be
transmitted. The other hears the tone with AM und calibrates with
reffreq -f 1000.


6.4. ratecal1:

This tool is also by Pawel and part of his MT63, thanks! I insert here
Pawel's instructions:

The MT63 is a synchronous system and it relies on the sampling rate to be
the same at the receiver and the transmitter. At least the sampling rates
should not be different by more that 10^-4. MT63 samples at 8000 Hz thus if
your card runs at 8000.5 it's probably OK but if it runs at 8005 Hz it's
not good ! 

An extreme example can be my Soundman-16 (PAS-16 clone) which when asked to
run 8000 Hz tell me, that it can only do 8008 Hz and it reality it runs at
7910.3 Hz which makes an error of more than 1% - far too much for the MT63
even at infinitely good S/N. My other two cards (DSP-16 and Ensoniq 1371)
are more reasonable: they show an error of 0.3 to 0.5 Hz at 8000 Hz
sampling.

To measure the sampling rate I have prepared "ratecal1" utility. The
program has been tuned to work with the HF timing standards which transmit
short pulses each second. I used the signals on 4996.0, 9996.0 and 14996.0
kHz. I set the HF receiver in the USB mode and 1.0 kHz below the frequency
to get pulses at 1000 Hz audio. In principle any signal having a periodic
envelope with a known period can be used, so an AMTOR/SITOR station is OK,
if you change the reference period to 0.450 sec with -T0.450 option. What
counts is the envelope of the signal around the frequency given by -F and
within the bandwidth given by -B.

To measure the sampling rate I tune my HF receiver to say 4995.0 USB
so the pulses come up as a 1 kHz beeps. I connect the audio to the given
soundcard (say /dev/dsp) and I type:
# ratecal1 -d
After 10-20 seconds I can see the measured sampling rate of my card. 
The calibrator will try to match the delay which gives the smallest
differential error. This procedure ussually gives you the rate
within 0.5 Hz (at 8000 Hz sampling).

For more accuracy multiply the repetition time: for example give -T4.0 thus
4 second reference period; a signal with period of T is as well periodic
over time = N*T where N is an integer.

If your sampling rate error is large (like with my card) tell the program
the (about) true rate with the -R option. for example for my card I run the
more precise test:
# ratecal1 -r8000 -R7910 -T4.0 -I40 -B200
The most precise test I have ever done was by typing:
# ratecal1 -r8000 -R7910.3 -T300 -I60.0 -B500 -D4
and leaving it for 10 minutes on the 14995.0 USB.
After the calibration is done put down the two values:
the rate you request (-r) and the true rate you get.
You may try different requested rates (-r) so you get
the real rate close to what you like.
For example with my card, I need to request 8100 Hz to get
real rate of 8018.2 Hz which is closest to the 8000 Hz
which I want for my applications.

Timing signals on 4996, 9996 and 14996 kHz are not ideally periodic because
some pulses are longer, some are doubled, etc. This has certainly negative
effect on the calibration result. The pulses there are not transmitted all
the time but according to certain schedule thus we can not apply too long
integration times too. Still rate measurement with an error about 10^-5 is
possible.

When you know the true sampling rate you can correct for this
when working with the MT63 mode with the -R option. Say, you measured
that you card at /dev/dsp2 samples at 8010.5 Hz, so you type:
# mt63trx -d2 -R8010.5
I do so with my PAS-16 clone and it works just fine for the MT63
despite the 1% error.
You may happen to have a card which refuses to run at 8000 Hz - but you
are not all lost. Say the card at /dev/dsp1 only likes the 9600 Hz
sampling and when asked for 9600, it samples at 9605.4 Hz (you measure
this with the ratecal1). To run the MT63 receiver you type:
# mt63rx -d2 -r9600 -R9605.4
the mt63rx will ask the sound driver to sample at 9600 and knowing that it
really means 9605.4 it will apply the proper rate converter.
Ideally every operator should measure the sampling rate of his soundcard
and then correct for this when transmitting and receiving. This way every
signal on the air has same absolute timing and thus can be read by anyone.
(Thanks, Pawel!)

I (Gnther) compared ratecal1 with the 2 other tools and found the same
good results. Pawel told me that the mentioned pulsed signals at on 4996.0,
9996.0 and 14996.0 kHz come from Russia. I could not receive them at time
of my test, but used the signal of the dcf77 beacon, which is also pulsed.
If I divide the `official` sample rate of my soundcard by the real sample
rate which is obtained by ratecal1, I get the same  "soundcorr" as by the 2
other tools, exact to a degree of 10^-4 which is o.k.

Also ratecal1 could serve for an on-the-air-calibration: 
One sends Amtor or Pactor ARQ 
or even dcf77gen (but: this still can not take a correction as option!),
the other runs 
# ratecal -d -T0.45 (for Amtor) or -d -T1.25 (for Pactor)
or -d for dcf77gen.


6.5. Estimation of Samplerate by hearing and ratetry

I had an adventure with my laptop (150 MHz Pentium 1, 14 MB RAM only!), I
must tell you. It may help you if you also have old hardware... Hf and also
MT63 works with the laptop, but the calibration tools work bad,  they need
much men and cpu! It had worked in my tests with 2 cabled  computers with
Pactor and Amtor, but no single sign decoded with MT63. I had no idea about
its real sound rate! I wrote the script ratetry (look at it's text, you may
modify it to your needs, it just tries transmitting with rates from
...to...,  given by option.) I first checked it with around 8000, no
success. In my despair I found another, very primitive first-look test,
working with my ears only: I set both computers to
# mt63tx -d -C_____T____
which means, send MT63 with a single dah (T) within 9 spaces as cw id. Now
I heard the difference: The laptop was much quicker, it overtook the other
computer. It really sounded like the little fox jumping  over the lazy dog,
I could hear it! Now I guessed the real rate of the laptop to be 8100,
8200, 8300... and ran MT63 on it with 
# mt63tx -d -C_____T____ -R8100 and so on.
With R8300 the two 'dahs' sounded in about equal rythm. So I could use
ratetry 8200 8350 and could receive the data with the other computer
between laptop's "real rate " 8241 and 8335! So, now lab working,
developement can go on.


7. Mailbox :
============

7.1. Principle

hfterm hs a TCP-IP port. Every internet-capable program, which means, which
can be reached via 'telnet <host> <port>', can be reached by a remote user
via hf, if you configure it. 

See man inetd or look into /etc/services to see what is running on your
box... 


7.2. First test of the TCP/IP Ports with portecho:

Hf is made for F6FBB. But i you do not know F6FBB yet, you can make a
quick first test with the test program "portecho". It repeats its input 
in capitals, and it is polite, it greets and says good-bye. 

Start portecho with a port number as option: 
# portecho 3333. 
Test if it runs it from another console by 
# telnet localhost 3333. 

Then set the port to 3333 in hfterm, start the mailbox function by
<Alt>+M. By writing into the rx window you can do the first tests, best
in RTTY or Pactor FEC or Amtor FEC or MT63...

If you can run hf on 2 computers with cabled soundcards, try a Pactor or
oder Amtor connect, and run hf in mailbox mode with Portecho on one of 
them!


7.3. Configure F6FBB

hfterm can be linked by it's TCP/IP port with F6FBB, which is well-known
and proven as Packet Radio BBS. F6FBB can be installed on the same or an
other computer linked by ethernet or PLIP. If your computer ip adress and
Port for F6FBB differ from the defaults (Localhost = 127.0.0.1 = the same
computer, Port 6300 = default for F6FBB) change the corresponding entries
in /etc/hf.conf. But if possible, keep port 6300, for this activates a
special code in hfterm adapted for F6FBB, working around bugs of it, and
automatically surrendering the remote partner's call to F6FBB in case  of
Pactor connect.

At first there is something to change in only 5 configuration files and one
binary. Don't fear, I help you. Log in at a console as root.  If xfbbd is
running already, (test with ps -ax), quit it with killall xfbbd. For test
after the changes start it again by xfbbd.

The start is quite easy. 

7.3.1. /etc/ax25/fbb/passwd.sys:

Replace the password after the line 
#PASSWORD OF ALL NON DEFINED CALLSIGNS.
by an empty line!


7.3.2. /etc/ax25/fbb/port.sys:

Changes marked by arrows.
# FBB7.00
#
#Ports TNCs
 1     1				<-----	
#
#Com Interface Adress (Hex) Baud
 8   9         189C          0		<----- (189C hex. = 6300 dec.) 
#
#TNC NbCh Com MultCh Pacln Maxfr NbFwd MxBloc M/P-Fwd Mode  Freq
 0   0    0   0      0     0     0     0      00/01   ----  File-fwd.
# 1   8    9   ax0    250   3     1     10     30/60   XUWYL Linux
 2   8    8   0       250   2     1     10     0/60   TUR  # hf_telnet   <-----
#
# End of file.
#

(This port.sys is configured only for hf. If already other ports / TNC's
are there, for hf just 1 Port / 1 TNC has to be added. The other marked
lines have to be inserted additionally for hf.)


7.3.3. /etc/ax25/fbb.conf:

(in older versions of F6FBB this was init.srv)

#
# FBB Set-up file
#
version = FBB7.01
callsign = DL4MGE.BAY.DEU.EU  			<-----   
# Qra Locator of BBS
locator = JN58NG				<-----
qral = JN58NG					<-----
# Qth of BBS
city = Baindlkirch				<-----
# First name of SYSOP
name = Guenther					<-----
# Callsign of SYSOP
sysop = DL4MGE					<-----
# Callsign (and route if needed) that will have copy of SYSOP messages
sysmail = DL4MGE				<-----
# Wait for informations (Name, HomeBBS, Qth, ZIP)
askinfo = NO 		(chose one of them)	<-----
#askinfo = OK		( "    "   "  "   )	<-----				
# First connection mask :
# 0  : Disable
# 1  : Excluded
# 2  : Local					
# 4  : Expert	
# 8  : Sysop
# 16 : BBS
# 32 : Pagination
# 64 : Guest
# 128: Modem					
# 256: See-all-messages
# 512: Unproto list asking is allowed
# 1024: Liste des messages nouveaux. List of new messages.
# original was: mask = 3616
# orig + 2 + 128 means: local and modem     	
mask = 3746					<-----

The most important is "mask" - add 130 to the existing "mask". This means:
2 =  Local and 128 = Modem. So a new user can log in "local" (this is also
IP and telnet) and has access to the "Modem", which is  also a TNC, and
hfterm is seen as TNC by F6FBB. So a new remote users can send mails from
the second login on, without the sysop having to  become active.

Btw, 3746 is  2 + 32 + 128 + 512 + 1024 + 2048.
It works also with mask = 130 which is 2 + 128!


7.3.4. /etc/ax25/fbb/lang/english.ent:

Replace english.ent by an empty file.


7.3.5. /etc/ax25/fbb/lang/english.txt:

You may optimize the messages for shortwave: shorten them! Now I found out
how to change this file without making F6FBB crazy: It is just important
that the number of lines remains 287! Lines beginning with a comment sign
(which is the '#' like in shell scripts) are not counted for this. So you
can just outcomment a line (don't delete it, this helps you in debugging
later...), then copy it and edit it. The '$W' means that F6FBB prints a
newline. Some lines (where F6FBB asks for name, home BBS, town etc.) depend
on  your "askinfo" in /etc/ax25/fbb.conf: newlines, if you have
'askinfo=NO' (complete empty lines result in errors) or e.g. "Name ? ", if
'askinfo=OK'. I will deliver my english.txt in /usr/share/<doc>/hf, just
look at it, edit it to your desires, copy it (as root) to it's place in
/etc/ax25/fbb/lang.


7.3.6. Hack of binry file /usr/sbin/xfbbd:

And now the most dangerous operation. You have to study medicine for this.
( ;-) ) Did you already hack a binary? It is simple! It is about F6FBB's first
login message, which is hard-coded, but does  not fit for our hf. If a new
user logs in at F6FBB, it says:

Login in read-only mode.  
You may leave a message to SYSOP. 

But this is better, clearer:  

First login to register. 
You can send mail at next login! 

How to do it? At first, in every case make a backup of /sbin/xfbbd. (The
binary can be destroyed by one sign too much!) Then open xfbbd with an
editor, e.g. mcedit, best in overwrite mode. Look (F7 in mc) for 'SYSOP'.
Overwrite the 2 greeting lines, not more. The first line has 24 chars, the
second 33. For me it worked!

To configure F6FBB it sometimes kryptic, but it is a good and stable
program. I had to think and test much to get all this out. Thanks to the
friends from the F6FBB mailing list xfbb@f6fbb.org  and the good docs: 
http://www.f6fbb.org/fbbdoc/doc.htm  and, of course, for F6FBB itself to
its author Jean-Paul Robeller!

Now you can test F6FBB by `telnet localhost 6300`. It must be possible to
login with a call and register, logout, login again and to send and read
mails.

Now start of the hf-mailbox is simple: start als root xfbbd, then start hf
as normal user hf, then (if you want) activate the mailbox-beacon fixtext,
then activate the mailbox mit <Alt>+M or with the State menu, and it runs!

The connection hfterm <--> F6FBB can now be tested by writing into the rx
window (take Standby Pactor only mode, then you transceive in  Pactor-FEC,
or take MT63). So you can simulate the a remote user logging in without
having to cable 2 Computers or make a radio contact.

A Pactor connect to the call in menu Utilities/Parameters/Pactor/Mycall or
an amtor connect to the call in ../Amtor/Mycall opens the mailbox. In
FEC-modes the partner must call the call configured in 'Personal Edit` 
(brag). 

I tested the mailbox with 2 computers with cabled soundcards with Pactor
FEC, Pactor ARQ, Amtor FEC and Amtor ARQ with very good success. With RTTY
and MT63, it runs now sometimes with a lot of good luck and  patience, but
it is still prone to errors, and F6FBB confuses. (The squelch function
must have some delay, little for FSK and big for MT63, so it lets through
some rubbish at start and end of each transmit  cycle.) So let's wait for
the MT63 ARQ mode, which is being developed!

In use on the air as automatic mailbox station, concern the regulations of
your country! 

What about a ptc-free, microsoft-free, free-software based mailbox at your
Club station?


7.4. Using hf as a self-configured automatic station 

You also can set up any program that has a console prompt to become an
internet service and approach it over the air with hf.

I made a little example script 'hftcp', it can read your mails and send
mails (using the program 'mail'), and it can be configured for anything
you want, see the example commands like peace message. It can even open
a shell (dangerous!). So you can remote-control your computer with
hf... Don't launch the missiles!

Just run the script on a console to see what it does. You can edit and
modify it to your taste. You could, for example, extend the "read mail"
mode by starting an internet connection and running fetchmail, which
showels your mails to /var/mail/<your-user-name>, and then you could
read your new mails over the air... (not legal in any country)

Now see if port 3333 is free on your computer by
# netcat -z localhost 3333 && echo not free
or
# telnet -e# localhost 3333
If not free, take an other one.

To use hftcp with hf, you (as root) just have to enter one line into 
/etc/inetd.conf:
hftcp	stream	tcp	nowait	root	/usr/bin/hftcp	hftcp
and one into /etc/services:  
hftcp           3333/hftcp   

Then start it one one console, test it from another one by  netcat
localhost 3333. Then, if o.k., set the port, e.g. 3333, as option in
hfterm, switch to mailbox mode with <alt>+m, and it runs.



8. List of all programs in the package:
======================================

    All installed in /usr/bin:
   
    hfkernel,
    hfterm: 		the two main programs.
    hf: 		the start script for both.
    elbug:		console program for electronic key.
    paccalc:		calculates pactor data throughput
    channel:		Short wave channel simulator.
    dcf77rx:		Calculates clock correction constants from DCF77 timecode,
			can also set system time, see man dcf77rx.
    dcf77gen:		generates DCF77 signal, see man dcf77gen.
    reffreq:		Calculates clock correction from reference frequency.
    portecho:		Simple TCP test program for mailbox mode.
    hftcp:		Simple TCP test script for remote-control.

    and: (new!) Pawel Jalocha's MT63 suite as 
    console programs, with many experimental features:

    mt63rx:		receives  MT63
    mt63tx:		transmits MT63
    mt63trx:		does both
    ratecal1:		calculates real sound rate from pulsed beacon
    addnoise:		adds noise to an audio file, for experiments
    morsecod:		converts digital to readable morse alfabets
    peakrms:		tools for examining mt63 audio files
    ratetry:		a script for testing mt63tx with different rates

     
    More test programs in subdirs test and util of hf source tree.
    Help for all of them: Just call them without options.
    (Note for Pawel's programs: no whitespace between options and arguments.)



9.  List of Help Texts :
========================

For now, there is help in English and German. 

Translations in other languages are very welcome!

The texts are in the doc directory of the program packet and will be
installed into 
/usr/share/hf. 
and, according to distribution, in 
/usr/share/doc/hf or
/usr/share//doc/packages/hf. 

The most important texts can be found in hfterm help menu (F1).

   
   ENGLISH:
   ========
   
   HF-HOWTO.txt		(this text, 
                	also with contents of man hfkernel and man hfterm)
   P-MB-list.txt	List of Pactor Mailboxes by Jost, ZS5S
   english.txt		example for /etc/ax25/fbb/lang/english.txt.
   mt63.txt		Pawel Jalocha's original MT63 doc

   manpages:
   man hf, man hfkernel, man hfterm, man dcf77gen, man dcf77rx  	

   GERMAN:
   =======
   
   DE-HF-HOWTO.txt	(this HOWTO in German)
   dcf77.txt		(longwave time & frequency reference beacon)
   pactor.txt		(good explanation of pactor, H.-P. Helfert et al.)
   pactor.ps		(same in ps)

   German manpages:
   man hfkernel-de, man hfterm-de   	

   PICTURES :
   ==========
   lfconv.jpg		circuit of DL4MGE's longwave 4 MHz converter
   

10. TODO :
==========

MT63 ARQ. There is a spec for this in English language by  Paul L. Schmidt
<k9ps@arrl.net>. (Also in the archives of the hfterm list, it can be
downloaded as pdf.) Rein (PA0OR) hacked already an ARQ mode for gMFSK. 
There is a discussion in hfterm and linlink mailing lists.

CW: Would like to built in encoder and decoder from gMGFSK.

MAILBOX:
it is there since 0.6, test it, improve it!
Please report your configurations, especially if you link to packet!

MORE MODES:
Pactor 2 and 3?
This would be new and make the program more precious, as a PTC-2 etc. 
is expensive. But: The protocols are commercial, not public. 
300 baud packet? (does this exist for Linux?) 
PSK 31 - there are at least 5 good psk progs for linux, but 
it is very much used and nice.
MFSK? 
I had much fun in implementing MT63, although it was hard work.
And I learned much. I have to change about 20 files plus headers
for a new mode.
Button, menuitem, parameter page, parameter struct,
struct msg, struct parameter in hfkernel/msg.h, autorx, autotx, 
thread for the mode, define messages, mailbox.c, doc...

LOG:
Contest counter increasing by 1 each QSO. 
Format in log file OK? (I made 2: binary file for re-reading by program 
and ascii file for printing / further processing)  (By sprintf... in
hfterm/src/log.c in Funktion log_store you can change  ascii log output
easily). 
Who knows more about log formats? Every contest wants its own cabrillo 
format! Other formats to store / as interface, e.g. ADIF? Better to link
hfterm whith an existing log prog! (e.g. 'hamlog', is  in SuSELinux 8.1)

WORLDMAP:
Axel is preparing a fine toy - to show the QTHs of qso partners  from
log dates. He prepared the map. I outcommented calculation  of the
pixmap hfterm/src/main (if MAP...endif), because the programm  otherwise
would need 10 mins to start on my old machine.  The pixmap is not there
any more in V.0.5, 3 MB when unpacked. Axel is working at this feature
within developing "Baken".

HELP:
Translations...
Doc in html...
More info about the modes & experience reports!


11. Conclusion :
================

There are still 'some' BUGS, also called FEATURES,  don't scream, better
wait, still better report, best help! (see TODO). I myself have been
inspired to learn c by this program, learned a lot (all I wrote above I
also did not know before!) and had (most of the time) much fun up to now!
  	
Ok, we hope Tom & you all will like ! So have a lot of fun ...

Gnther Montag DL4MGE

============================================================================

		
		AUTHORS

Thomas M. Sailer	HB9JNX/AE4WA	Mail: sailer@ife.ee.ethz.ch
			
Ralf-Axel Krause	DF3JRK		http://www.df3jrk.de.vu
					Mail: df3jrk@gmx.de	
					Packet: df3jrk@df0hmb.hh.dl.eu.ww

Gnther Montag		DL4MGE  	http://www.hfterm.de.vu
 					Mail: dl4mge@darc.de
 					Packet: dl4mge@db0zka.bay.deu.eu
						
Pawel Jalocha		SP9VRC		Pawel.Jalocha@cern.ch

Project homepage, latest news and download of latest version:
	https://sourceforge.net/projects/hfterm

PLEASE _DO _ subscribe the mailing list:
	https://lists.sourceforge.net/lists/listinfo/hfterm-hackers

please post all questions and bugs and tips to the mailing list:
	hfterm-hackers@lists.sourceforge.net
