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

LINUX AMATEUR SHORTWAVE PROGRAM
FOR PACTOR 1, AMTOR, GTOR, RTTY
WITH INTERFACE ZU F6FBB TO USE AS ALS MAILBOX 

Version 0.6 AUGUST 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.

The terminal program hfterm is the user interface. 

The start script hf reads a configuration file and starts the two
programs in the right order.

hfterm can connect via a TCP port with the well-known mailbox program
F6FBB 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.

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. Development is running.

Please contact us by the mailing list!


2) Installation and Configuration :
   ================================

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

download 'hf-<version>.tar.gz',
unpack whith 
	tar -zxvf hf-<version>.tar.gz,
go into directory hf-<version>,
	./configure
(options are visible with configure --help, but 
normally you need no options)
	make
and, as You do not have write permission to /usr/bin, as root:
	make install

The main executables hfkernel_user, hfterm and the start script hf are
in /usr/bin, the global config file is /etc/hf.conf, normally you only
have to enter your serial line for PTT here. 

The documentation is in /usr/share/doc/hf, the main text is this.

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

There are nice new examples for text macros in
/usr/share/doc/hf/hf-examplefiles. If you update from former
version, and want to take the examples as your fixtexts,  remove your
~/hf directory before starting hfterm. The dir will then be made new,
and the new examples will be copied to it. (If you want to keep part of
your files in this directory,  e.g. the parameters or brag, rename them
and copy them back afterwards.) 


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) hfkernel :
   ==========
    
The sound driver must be loaded (see 7).

/usr/bin/hf starts the programs "in every situation of life" as good as it can:
On the console: (for test purposes) hfkernel_user only
As Root: (for test purposes, if "suid rood" has a problem) hfkernel_user only
Unter X und als non-root-user: hfkernel_user and then hfterm.

Try first to start hf from a console.

If hfkernel exits with the message
hfkernel[Pidnr...]: error: ioctl: TIOCMBI[CS]: Input/Output error
the serial port has not been given correctly in /etc/hf.conf.

Sometimes the program 'hangs' quite sinply while starting, stop it with 
<strg> c or with hfkernel_user -k and try again.

But, at this point the worst thing can happen:  Depending on some
combinations of soundcard / sounddrivers,  the hfkernel can hang here in
an endless loop with "... fragments passed since last wakeup" or "OSS
driver lost interrupt". Before this made system hang forever, never
reacting to anything except  switching off computer, and, (sorry,
Hubert), hard disk damage. In Version 0.6 I built in a brake to prevent
this, so hope it helps. Soundcard / Sound driver problems: see 7).

If successful, after the first announcements (confirming parameters from
/etc/hf.conf, initializing the soundcard, calculating txdelay in case
of halfduplex, which should be about 5... 35 ms) a double row of SMALL
numbers will run over the screen, like:

corrout		-1	intermediate		-1
corrout		-1	intermediate		 0
corrout		 0	intermediate		-1

If dates are received (rig on) the numbers may be a bit bigger.

*** If this runs: VERY GOOD, most work is done. ***

If the numbers are always BIG, however, (about 8000),  maybe the option
'-R' (disables RDTSC instruction, processor dependant) has to be added.

If an error containing "MMAP" occurs, it may be more complicated. Try
option -h (force halfduplex) and /or the experimental option -n (no
mmap). Then: See 7).

If pactor/amtor ARQ makes problems later, especially if you need option
-R or -h, you maybe have to do a calibration, see 8) further down.  

Btw, 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) start and test the whole program :
   ==================================

When hfkernel makes no problems, hf can be started from the graphical
surface e.g. kde: open a command window whith 'ALT + F2' and enter 'hf'.
Hfkernel will appear in an xterm, and then the graphic hfterm window
will appear in the foreground. To test if the 2 programs are really
connected, and of the soundcard gain is adjusted correctly, open the
spectrum display with F2 or <Shft>F.

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). The
Status Display Window on the bottom tells you what the program is just
doing. 

The special thing in the new version of hfterm: It thinks, as far as it
can. 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. 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
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/doc/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 will hang. Instead, do QRT ('Alt Q'),
wait a little (let the program finish its QRT routine!), then go to
standby again.

 "PARAMETERS"
By 'Ctrl P' you will open a notebook where you can enter parameters like
mark, shift, baudrate, txdelay etc. for the different modes. Here also
in a coming version I hope to install a page for a contest number and
size for logfiles. When you finish the program, these parameters will be
stored in ~/hf/hfterm.rc,  so on next start they will not be forgotten.

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

If it all 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. That's it.


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_user 
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_user
Now, hf (started by you as normal user) calls hfkernel (with superuser rights).
An example file for /etc/su1.priv is 
/usr/share/doc/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_user
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.

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) and -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, hf makes 
	lovely sounds already, but it is not finished! 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 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 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/doc/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 before
writing down the measurements. If the correction values seem credible
and constant, enter them as options to the prepared lines of 
/etc/hf.conf.

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 an (experimental) -n (no  mmap) option.

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!

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. 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 only few to configure: ( <----- )
(In my examples I configured F6FBB only for hf.)

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:

#
# 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
#for new connect to be able to read-write, plus 128!
# 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.

*****************************************************************************

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 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 starting the mailbox is simple: start als root xfbbd, then start hf
as normal user hf, then go to Pactor standby mit F4 (normal standby is
preset and also works), then activate the mailbox mit <Alt>M or with the
State menu, and it runs!

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 Pactor mailbox at your Club
station?


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

   (they will all be installed in /usr/bin)
   
   hfkernel_user 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!).
   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!).
   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)
   			

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/doc/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)
   TODO			(the voices programmers hear in their heads...)
   manpages:
   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	(is hfkernel-de.txt)
   man hfterm-de   	(is hfterm-de.txt)

   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
	
