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

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

Version 0.6.4 NOVEMBER 2004


1) Introduction :
   ==============
   
The hf program suite implements the amateur radio FSK protocols
Pactor-1, AMTOR (SITOR), GTOR and RTTY. 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 RTS pin of a serial
interface.
   
The implementation of the protocol uses one binary called hfkernel,
which runs as daemon in the background. hfkernel provides an UNIX domain
socket to communicate with the user interface andd mailbox interface -
like the terminal program hfterm. 
UNIX domain sockets were chosen since they could be easily changed to
internet domain sockets in the future, to let the hfkernel process run
on a different machine than the user interface.

hfkernel internally uses three threads, one for the L1 FSK modem code,
one for the protocol, and one that handles socket I/O.
Hfkernel has been made for the OSS sound drivers, but it also runs with
the new ALSA drivers, because they have an OSS emulation that is being
improved steadily. But it does not run with every soundcard, because 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) is working good very often and 
is now also available for the 2 calibration programs in the package.

The terminal program hfterm is the graphic user interface to hfkernel.

The start script hf reads and tests the configuration file and starts 
hfkernel and hfterm.

hfterm can connect via a TCP port with the well-known mailbox program
F6FBB (and, as we hope, with other mailbox programs) 
to be used as an automatic Pactor and Amtor mailbox.

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:
   ========================================

Requirements:
Hardware:
Pentium from 133 MHz on. The soundcard must support mmap().
Software:
hf makes use of gtk+ toolkit (Version > 1.2.0), which is in many
linux distributions. To know whether this is installed, type 
'gtk-config --version'.

hf-<version>.tar.gz:
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:
# make
install it, as you do not have write permission to /usr/bin, as root:
# make install

'hf-<version>.rpm':
install: 
# 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. 

First test:
On a console:
Start once as root, once as user
# /usr/bin/hf
without options.
The start script hf tests the configuration and gives hints.
If successfull, after the first messages a row of numbers 
rolls over the screen:
corrout .... intermediate ...

If this runs, then under X:
Open a command window whith 'ALT + F2' and enter 
# /usr/bin/hf
Hfkernel will appear in an xterm, and then the graphic hfterm window
will appear in the foreground. 
To test signal input and the soundcard gain, open the spectrum display 
with F2 or <Shft>F or the Spectrum button.
Decoded characters should appear in the rx window.

If hf runs, 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 and end the program
whith one mouse click. 

Your personal directory (configuration, fixtexts, Log...) is hf in your
home directory. It is made at first start of hf and filled with
example text macros. Your personal configuration (call, name ...) 
is done menu-guided from hfterm.

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.


3) PTT Wiring :
   ============

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

Naturally there are many more sophisticated possibilities 
with opto couplers and relais...


4) Problems with start of hfkernel :
   =================================
    
Sometimes the program 'hangs' while starting, stop it with 
<strg> c or with hfkernel -k and try again.

Failure of start script hf, or do you want to start manually:
Try to start first hfkernel as root from console:
# hfkernel
and if successfull
(corrout	...	intermediate   ...)
add the other necessary options one by one.
Most important is the socket to hfterm (-c /var/run/hfapp)
and the serial line.
Then start as normal user under X:
# hfterm -k /var/run/hfapp 

Most common error messages:

Error containing 'MMAP': (MOST COMMON ERROR !)
Soundcard and / or driver does not support 'mmap()'
(means DMA, program handles sound card buffer directly).
Try first the experimental option -n (no mmap)
or try option -h (force halfduplex).
More help: See 7).
The best way is: Set the options in /etc/hf.conf with your favourite editor 
and then start again
# /usr/bin/hf

Error containing 'open':
Is the sound driver loaded? (see 7).

Error containing 'ioctl: TIOCMBI[CS]:'
Is the serial line correct in /etc/hf.conf ? 

Error containing 'permission denied':
Error containing 'pthread_create':
If starting hfkernel as non-root:
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 the Suid Bit by hand:
# chmod 4755 /usr/bin/hfkernel .
There are 2 other alternative workarounds for the non-root users, 
see 6) Root Rights.

Depending on some combinations of soundcard / sounddrivers,  
the hfkernel can hang 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. 
More about soundcard / sound driver problems: see 7).

In half-duplex mode, if the numbers
corrout ... intermediate ...
always big, (about 8000),  maybe the option
'-R' (disables RDTSC instruction, processor dependant, often with
non-intel architectures) has to be added.

If pactor/amtor ARQ works not or bad later, (especially if hfkernel only runs 
with the option -h, or -still worse - -R,) you have calibrate, see 8).  

Btw, try to get hfkernel running with the script hf, which includes 
/etc/hf.conf. All additional options can be put in /etc/hf.conf into the line 
"otheroptions", separated by spaces, e.g. "-n -i ".

Here is the 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)
  -c: path of the communication socket (default: hfapp)
  -f: standby: disable frequency estimation
  -h: force half duplex mode
  -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!)
  -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 :
   ========

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... 
The Status Display Window on the bottom 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 is useful for the beacon and
mailbox  functions.

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

 "PACTOR - AMTOR - GTOR"
Pactor is a science...  If you do not know what Pactor is, read 
'pactor.txt' in /usr/share/hf (sorry, German only.) 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, 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. Sometimes you fish a callsign out of the fog, which is sent
in levl I. Call CQ by FEC. If you have a partner answering by FEC, 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.

 "PARAMETERS"
By 'Ctrl P' you will open a notebook where you can enter parameters like
mark, shift, baudrate, txdelay etc. for the different modes. When you 
finish the program, the parameters will be 
stored in ~/hf/hfterm.rc (digital, please do not edit!).

 "BRAG"
also called 'Personal Data': By 'Ctrl B' you can open an entry field
where you can enter your call and personal 'brag' e.g. power, rig, 
antenna, locator, qth, name, mail address. This data will be used by the 
text macro processing functions to create texts while transmitting. When
you finish the program, the brag will be stored in  ~/hf/hfterm.brag, so
the everlasting fame of your amateur radio station is granted on your
hard disk. 

 "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. In a later
version, we will also implement an automagic increasing contest number. 
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>, 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.

 "LOGBOOK"
We even have 2 logbooks. One for big screens, always open. Write your
entry, and click 'save' in the log menu to save, or 'clear' to 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, you will be able to  change this number from next version on.
The old log files are numbered and can be opened with every text editor.
The ascii format is adapted to cabrillo standard.

 "RX-TEXT"
If you receive something, it will be stored, 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 choose a file for storing.



6 ) Superuser Rights :
====================== 

The problem is, hfkernel needs superuser rights because of its real-time
high-priority modus. But you should run programs if possible only as a
normal user.  To let non-root-users start hfkernel together with hfterm
easily, at installation hfkernel gets superuser rights by the suid bit: 
chmod u+s /usr/bin/hfkernel 
Then normal users can execute the program with superuser rights.
If this is o.k. and running, you do not have to read on this chapter.

If not, in  /etc/hf.conf 2 other ways are prepared and described. You
need 1 of the (2 or more?) programs that make normal users able to run
programs with root rights: 'su1' or 'sudo'.

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


7) Problems with sound cards / - drivers :
   =======================================

Soundcards:
===========

hf does not run with every soundcard and / or driver.  The reason is not
bad code, but good code: Because of the time-critical ARQ protocols it
is necessyryx 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.

I am experimenting with an alternative code with the OSS API using
normal read()'s and write()'s instead of mmap(). For this the option
"-n" (no mmap) is prepared.

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

Problems (crashes & hangs, as described in 4) ) have been reported with:
ESS 1968: "chipbug", does not work with ALSA and not with OSS drivers.
VIA82C686: works not with OSS driver. But works with ALSA. 
Intel 101k: many xruns ("OSS driver lost interrupt"), bad decoding.

Drivers :
=========

hfkernel has been written for the (old) OSS drivers, but it often runs
(often better) with the new ALSA drivers, as they have an OSS emulation
which is improved steadily. Depending on the card, hfkernel runs with
none, one or both of these classes of drivers.

OSS:  

In old Linux distributios there was a 'free' packet (paid with the 
distribution), e.g. in my old SuSE 6.3 in /tmp/opso, it works good with
hf, I am still using it. As far as I know, OSS is still being
maintained. The new OSS drivers are not free any more
(www.opensound.com).

In old and also in new (up to kernel 2.4...) linux versions there are 
kernel modules included, similiar or same to the old OSS drivers. 
(Unlike the ALSA modules, they do not begin with 'snd-'). They can be
found in /lib/modules/<kernelversion>/misc. (Source in
/usr/src/linux/<kernelversion>/drivers/sound). You can install them with
modprobe (after unloading ALSA by rcalsasound stop). See man modprobe,
modprobe -p <module> (for parameter info),  modprobe -d <module> shows
which other depended modules are 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.

ALSA:

At this time the new ALSA (Advanced Linux Sound Architecture)
is being developed quickly and will be used by many linux systems.
It will be standard part of the new kernels from 2.6 on.
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

The ALSA system has 2 ways of OSS emulation: 

The default one (which is in the kernel modules)  is activated when a
programm 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 will linked
to the program by the script  /usr/bin/aoss (contains: env
LD_PRELOAD=/usr/lib/libaoss.so $*) e.g.: aoss <program>. This is
prepared in /etc/hf.conf.In order to use this lib, you have to prepare a
config file /etc/asoundrc or ~/asoundrc containing (if you have one
sound card)

	pcm.dsp0 {
		type hw
		card 0
	}
In newer ALSA versions this is done already.

Both ways of ALSA OSS emulation are still in development, and because
hfkernel's special desires (mmap and realtime mode) it sometimes does
not run with ALSA, 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.

EXTENDED PROBLEM SOLVING STRATEGY :
==================================

If hf does not run, I suggest the following:

for (;;) {
	Backup your data.
	Try first with the soundcard and driver you have. Then:
	Try option -n (no mmap) or -h (halfduplex).
	Try your ALSA in native mode.
	Try ALSA with aoss prefix (as is prepared in /etc/hf.conf).
	Try latest ALSA version, its becoming better.
	Try latest ALSA with aoss prefix.
	Try commercial OSS, if you have (maybe free in an old distribution).
	Try OSS kernel modules which are in your distribution.
	Try another soundcard.
	if (nervous system == corrupted) {
	break;
	}
}
if (you can program in c) {
	Improve l1/user/oss.c: oss_nommap_fdx_driver() and 
	oss_nommap_hdx_driver(), there I try simple read()'s und write()'s 
	with the OSS API. (I, Gnther, am working at this, hfkernel can 
	do bad-quality pactor ARQ with option -n  already! 
	Please contact me via mailinglist!)
	Or: re-write ist into ALSA API, which has more possibilities for 
	mmap-like operations. (They told me, it is more difficult than
	OSS API) (If you do this, use newest ALSA lib, the API changed a bit 
	at Version 1.0)
}
else {
	try the many good psk31, MT63, MFSK programs 
	that run well and make fun,
	try hf 1 year later...
}

If hf runs, fix it with glue and never touch your system again. Never
work more than 24 hours an evening. Look if your family is still there.
And do not 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.


9) Real Time Problems and Calibration :
   ====================================
   
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.

RTTY, Pactor-FEC and Amtor-FEC work without calibration, there have also
been reports about successful Pactor- / Amtor-ARQ connects without
calibration. If these should last longer, however, a calibration 
improves the performance of the program. 

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 2 Programs for calibration:

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.) 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 weitten 
automagically to /etc/hf.conf. See there if the correction values seem 
credible and constant, edit them, the last in the file will be read 
by the start script hf and used as options for hfkernel.

I made the output of dcf77rx a bit clearer and added an option to set
system time (see man dcf77rx).

These experiments made a lot of fun! 

dcf77rx and also dcf77gen already have the n (no  mmap) option.
It gives acceptable values for the most important correction -s here.
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).

What timecode beacons do You have in U.S.? Please mail!

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

reffreq
=======

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. 

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.
Do you know frequency beacons in America? Tell me!
I heard of WWV, Boulder, Colorado, 
at 60 KHz, 5 MHz, 10 MHz, 15 MHZ, is that correct?
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.


9) Mailbox :
   =========

From version 0.6 on hfterm can be linked by TCP/IP (a telnet-Port)  with
F6FBB, which is well-known and proven as Packet Radio BBS. It can be
installed on the same or an other computer linked by ethernet or PLIP. 

There is something to configure: ( <----- )
(In my examples I configured F6FBB only for hf.)

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 for F6FBB itself!

If your computer ip adress and Port differ from the defaults  
(Localhost = 127.0.0.1 = the same computer, Port 6300 = default for F6FBB) 
change entries in /etc/hf.conf.

/etc/ax25/fbb/port.sys:
# 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.
#

At "Ports TNCs" for hf 1 Port / 1 TNC has to be added.
The other marked lines have to be inserted additionally.

/etc/ax25/fbb.conf:
(in older versions 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				<-----

# 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.
# orig was: mask = 3616
# orig + 2 + 128 means: local and modem     	<-----
mask = 3746					<-----
.....
#
# End of fbb.conf file
#

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", or TNC, and hfterm is seen as TNC by F6FBB.
Atention: New remote users can send mails only from
the second login on! I could not improve this, adding 4 to the 'mask'
did not help, `feature` of F6FBB ?

Directory /etc/ax25/fbb/lang:
Replace english.ent by an empty file.

If you want to use hf e.g. for your club station as mailbox and connect
it  with Packet Radio, you can optimize the greeting messages, e.g. in
/etc/ax25/fbb/lang/english.txt. It might be good to inform the users
here 
 - that they can send mails from the second login on, 
 - that they should send a newline in case of hangs which occur sometimes,
 - that a mail is finished with "/EX".

Maybe you also want to shorten some output of F6FBB, adapting it for
short wave.

To configure F6FBB it sometimes kryptic, but it is a good and stable program.

Now you can test F6FBB with  telnet localhost 6300. It must be possible
te login with a call, and, from the second login on, to send and read
mails.

Now start of the mailbox is simple: start als root xfbbd, then start hf
as normal user hf, 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 (best take Standby Pactor only mode, then you transceive in 
Pactor-FEC). 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 success. With RTTY it
would run if the noise would not be so much, must implement a 
squelch funktion - or did you already? 

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

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


10) List of all programs in the package:
    ====================================

   installed in /usr/bin:
   
   hfkernel and hfterm: the two main programs.
   hf: the start script for both.
   
   paccalc:		calculates pactor data throughput, dependant on condx, 
   			for theoretical study of pactor (informative!).
   channel:		Short wave channel simulator.
   dcf77rx:		Calculates clock correction constants from a DCF77 timecode
   			transmitter signal applied to the soundcard. 
			Can also set system time. See man dcf77rx.
   dcf77gen:		generates DCF77 signal with soundcard. 
                        See man dcf77gen.
   reffreq:		Calculates clock correction constants from an exact 
   			reference signal (e.g. the video baseband signal of 
   			certain TV transmitters). 
			See man reffreq.
   			(Sometimes in Tom Sailer's original documentations
   			reffreq was referenced as refclock)
   			
   optional, at the moment not maintained:
   (to compile, remove comments in os/makefile.am)

   hfkernel_kernel:	runs together with hfmodem, a kernel module, 
   			which executes the time-critical functions in the kernel
   			(experimental!)
   hfkernel_link:	this version of hfkernel can be run twice on one single
   			computer, connected with channel (see below).
   			For development and performance evaluation (experimental!).


11) List of Help Texts :
    ====================

For now, there is help in English and German. Translations are very welcome!

The texts are in the doc directory of the program packet and will be
installed into /usr/share/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
   TODO			(the voices programmers hear in their heads...)
   manpages:
   man hf
   man hfkernel 	
   man hfterm   	
   man dcf77gen 	(emulation of dcf77 reference frequency beacon sigs)
   man dcf77rx  	(handles dcf77 sigs for calibration)
   man reffreq		(utility using e.g. TV line freq for calibration)

   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)
   manpages:
   man hfkernel-de	
   man hfterm-de   	

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

12) 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
						

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
