----=== HFKERNEL / HFTERM ===----
LINUX AMATEUR HF PROTOCOL IMPLEMENTATION
Version 0.5 Feb. 2004
README
(most important file for introduction)
1) Introduction :
==============
(by Thomas Sailer 1996)
This is the first public release of my HF amateur protocol suite for Linux
using a soundcard as a modem. The state of the software is early alpha.
Although the protocols RTTY, Amtor (Sitor) and Pactor 1 are almost
fully implemented, it might not yet be completely stable, and there might
be interface changes in the future.
THE CONCEPT
The implementation of the protocol uses one binary called hfkernel, which
has no user interface. hfkernel provides an UNIX domain socket to
communicate with the user interface or mailbox or whatever. 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 USER INTERFACE
A terminal program is included. This is however only "an excuse for
a terminal program". I'll leave it to someone else to write something
decent.
THE INSTALLATION
Since the hfkernel software uses many advanced operating system features,
some of them only available under Linux, there isn't anything to configure.
Run make to compile the software.
It is very important you calibrate your clock source as described in
doc/hfkernel.1 (groff -Tascii -mandoc doc/hfkernel.1 |less)
(man hfkernel).
To run it, first run hfkernel as root, then start hfterm as ordinary
user. Don't forget to supply the correction factors on the hfkernel
command line. If you terminate hfterm, you might currently also have to
terminate and restart hfkernel.
73s
Tom
2) Installation :
==============
(by Günther Montag 2003)
(same text German in LIESMICH)
hfterm makes use of gtk+ toolkit (Version > 1.2.0).
To know whether this is installed, type
'gtk-config --cflags' and
'gtk-config --libs' .
The program has been made in 1996 for the OSS driver.
It has now been made to run also with the ALSA driver.
We are still collecting reports for different cards and drivers,
compilers and kernels! Please subscribe the mailing list and see 7) in this text.
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 executables (all of them start with 'hf...') are in /usr/bin,
dokumentation is in /usr/share/doc/packages/hf.
Error-Log is /var/log/hflog.
Your personal directory (configuration, fixtexts, Log...) is hf
in your home directory.
There are nice new examples for text macros in
/usr/share/doc/packages/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 ) Start Scripts:
==============
While installing, among others the two most important program files
(hfkernel_user and hfterm)
and 5 start scripts (hfkernel, hft, hfsuid, hfsu1, hfsudo) will be copied
to /usr/bin.
(Besides this 5 other scripts, named like the startscripts, but
with a prepended 'p', to edit the startscripts with editor pico).
The first (hfkernel) to start 'hfkernel_user' (the mod/demod program)
with option 'start' and to stop it with option 'stop'.
the second (hft) to start the graphic terminal program 'hfterm'.
The other two for simple start if all runs well,
(see 6, automagig start).
Don't frighten, if all runs, you only will need one of them.
4 ) start hfkernel :
================
Sound driver must be loaded (see 7).
At first open a console and try to start hfkernel_user as root by
calling 'hfkernel start'.
The important lines in hfkernel are
# aoss \
/usr/bin/hfkernel_user \
-R \ # maybe You can outcomment this line
-m $cpumhz \ # this we get automagically now, see above, does it work?
-t 1.0 \ # insert time correction here if needed e.g. -t 0.9998500 \
-p /dev/ttyS1 \ # correct for your ptt output
-c /var/run/hfapp
# > /dev/null 2>&1 \ # if you want free screen
Option '-c' must remain like this, it redirects kernel output to
the Unix Domain Socket, for
communication whith the graphic terminal program hfterm.
The other options have to be changed sometimes.
If hfkernel exits with
hfkernel[Pidnr...]: error: ioctl: TIOCMBI[CS]: Input/Output error
the serial port has not been called correctly.
Option '-p' sets serial line for PTT.
Default: 1 for /dev/ttyS1 (COM 2). (0 = Com 1, 2 = Com3, 3 = Com4).
Sometimes the program 'hangs' quite sinply, stop it with
<strg> c 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.5 i built in a brake to prevent this, so hope it helps.
If successful, after the first announcements (initializing the
soundcard, calculating txdelay in case of halfduplex, which should be
about 5... 32 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 BIG, however, (about 8000), or errors come,
maybe the option '-R' (disables RDTSC instruction, processor dependant) has to be added.
help for hfkernel:
(from hferm window) F1
or man hfkernel
or /usr/share/doc/packages/hf/hfkernel.txt
If pactor/amtor ARQ makes problems later, you maybe have to do a real time
calibration with the program reffreq (is in the package, see man reffreq)
and put the resulting correction factor with option -t into the start script.
5) start hfterm :
==============
When hfkernel is running, we go to the second script (hft):
#!/bin/bash
/usr/local/bin/hfterm -k /var/run/hfapp
This must be started from the graphical surface e.g. kde:
open a command line whith 'ALT + F2' and enter 'hft'.
The graphic hfterm window will appear and explain itself.
To test if hfkernel is really connected with it,
open the spectrum display with F2 or <Shft>F.
help for hfterm: F1
or man hfterm
or /usr/share/doc/packages/hf/hfterm.txt
6) start both at once :
====================
If this all is running, test a third script to simplify
starting the program in future.
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.
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 start
allow GODS prefix /usr/bin/hfkernel stop
Now, hfsu1 (started by you as normal user) calls 'hfkernel start'
(with superuser rights), then starts hfterm,
and also ends hfkernel ('hfkernel stop') when terminating hfterm.
An example file for /etc/su1.priv is
/usr/share/doc/packages/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 start, /usr/bin/hfkernel stop
Now, hfsudo (started by you as normal user) calls 'hfkernel start'
(with superuser rights), then starts hfterm,
and also ends hfkernel ('hfkernel stop') when terminating hfterm.
Another, 3rd, way is:
As root, give the suid bit to hfkernel_user by:
chmod u+s /usr/bin/hfkernel_user
Then a normal user can execute the program with the super user rights
it needs. For this case I prepared the script /usr/bin/hfsuid .
Problem: hfsuid does not kill hfkernel after exiting hfterm!!
Must kill by hand as root or with su1 hfkernel stop!
If it all runs, create a link onto the desktop with
ln -s /usr/bin/<Your start script> /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.
Be careful: All of theese workarounds can be security holes!
7) Sound cards / - drivers :
=========================
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: with OSS driver. But works with 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
This 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 hfkernel start
or by removing the comment in the line with aoss in start script hfkernel.
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 neueren ALSA-VERsionen wird das auch schon vorbereitet sein.
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.
An other way is to take old OSS drivers.
In old Linux distributios there was a 'free' packet (paid with the
distribution), e.g. in SuSE 6.3 in /tmp/opso.
(Secret advice: If You have an old computer, keep your old linux !!!)
The new OSS drivers are not free any more.
Yet another way:
In old and also in new (up to kernel 2.4...) linux versions there are
kernel modules similiar or same to the old OSS drivers.
(Unlike the ALSA modules, they do not begin with
'snd-') 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 -with ISA-PNP cards- by pnpdump and
isapnp, (see manpages) and -with PCI cards- by lspci, and docs in
/usr/src/linux/Documentation/sound for your sound card.
You can also send a question to the mailing list, i played with
sound cards a little, maybe i know something...
As ALSA is being improved quickly, and with my knowledge of probabilities of good luck,
I suggest the following:
Backup your data.
Try first with the soundcard and driver you have. Then:
Try another soundcard.
With both cards alternative:
Try your ALSA in native mode.
Try ALSA with aoss prefix (as is prepared in the hfkernel script).
Try latest ALSA version, they still fight with bugs, but 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 NOT writing an own sound driver, even if you can, but, if you can,
Try re-writing l1/user/oss.c into new ALSA API,
to get rid of the mmap mechanism which some soundcards don't like.
The ALSA peolpe say, in ALSA there are better things than mmap.
If you do this, take newest ALSA lib, because since ALSA 1.0 the API has changed a bit.
If hfkernel 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.
8) List of all programs in the package:
====================================
(they will all be installed in /usr/bin)
hfkernel_user and hfterm: the two main programs explained above.
hfkernel, hfsu1, hfsudo, hfsuid, hft: the start scripts explained above.
paccalc: calculates pactor data throughput, dependant on condx,
for theoretical study of pactor (informative!).
hfkernel_kernel: runs together with hfmodem, this is 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: HF channel simulator.
dcf77rx: Calculates clock correction constants from a DCF77 timecode
transmitter signal applied to the soundcard. 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 seems to be referenced as refclock, older name.)
9) help system :
=============
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, and had
(most of the time) much fun up to now !!!
Read the 'help library' ...
It is waiting in hf-<version>/doc,
will be installed to /usr/share/doc/packages/hf,
README, LIESMICH and all english and german .txt's can be
found in hfterm help menu by F1.
*** TRANSLATIONS WELCOME ***
ENGLISH:
README (this text)
hfkernel.txt (by Tom Sailer)
hfterm.txt (by Günther Montag)
TODO (the voices programmers hear in their heads...)
manpages:
man hfkernel (is hfkernel.txt)
man hfterm (is hfterm.txt)
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:
LIESMICH (this README in German)
hfkernel-de.txt (by Tom Sailer)
hfterm-de.txt (by Günther Montag)
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)
Ok, we hope Tom & you all will like ! So have a lot of fun ...
Günther
(at the moment the main (enter) tainer.)
============================================================================
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
Günther Montag DL4MGE http://www.hfterm.de.vu
Mail: dl4mge@darc.de
Packet: dl4mge@db0zka.bay.deu.eu
PLEASE _DO _ subscribe mailing list:
https://lists.sourceforge.net/lists/listinfo/hfterm-hackers
post to mailing list:
hfterm-hackers@lists.sourceforge.net
download latest version at:
https://sourceforge.net/projects/hfterm
Download Latest Version
hf-0.9.tar.gz (4.2 MB)
