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

LINUX-AMATEURFUNK-KURZWELLEN-PROGRAMM 
FR PACTOR 1, AMTOR, GTOR, RTTY, 
MIT INTERFACE ZU F6FBB - MAILBOX 

Version 0.6.4 NOVEMBER 2004

  
1) Einfhrung :
   ============

Das hf-Paket implementiert die Amateurfunk-FSK-Protokolle Pactor-1,
AMTOR (SITOR), GTOR und RTTY. Es bentzt eine normale Soundkarte als
Modem. Der Geschwindigkeitswechsel bei Pactor (von 100 auf 200 baud)
geschieht automatisch. Ein PTT (push to talk) -Signal kann ber die
RTS-Leitung einer seriellen Schnittstelle ausgegeben werden.  

Die Implementation der FSK-Protokolle ist im Programm hfkernel, das im
Hintergrund als "Dmon" luft. Es stellt ein UNIX-domain-socket zur
Verfgung, das mit einer Benutzeroberflche und Mailbox-Schnittstelle 
kommunizieren kann - wie etwa dem Terminalprogramm hfterm. 
UNIX-domain-sockets wurden gewhlt, weil sie in der Zukunft leicht in 
Internet-domain-sockets umgewandelt werden knnen, so da der
hfkernel-Prozess auch auf einem anderen Computer als die
Benutzeroberflche laufen kann. 

Hfkernel verwendet intern drei Unterprozesse (threads), einen fr den 
L1-FSK-Modem-Code, einen fr das Protokoll, und einen der die Socket- 
Ein- und Ausgabe steuert.
Hfkernel wurde fr den OSS-Soundtreiber geschrieben, luft aber auch mit
den neuen ALSA-Treibern, den diese haben eine OSS-Emulation, die
stndig verbessert wird. Wegen des fr das Amtor- und Pactor-Protokoll
notwendigen Echtzeitmodus und den dafr ntigen kurzen Signallaufzeiten
wird die Soundkarte ber den  "mmap()"-Mechanismus (memory mapping)
angesprochen, was nicht jede Hardware untersttzt. Es luft deswegen
nicht mit allen Soundkarten und Treibern!  Systemabstrze knnen nicht
ausgeschlossen werden! 
Die experimentelle Option '-n' (no-mmap) funktioniert oft gut,
sie ist auch fr die beigefgten Kalibrierprogramme vorhanden.

Das Terminalprogramm hfterm ist die Benutzeroberflche zu hfkernel.

Das Startskript hf liest die Konfigurationsdatei ein,
prft sie und startet hfkernel und hfterm.

ber einen TCP-Port kann hfterm mit dem bekannten Mailbox-Programm F6FBB
(und, wie wir hoffen, auch mit anderen Mailbox-Programmen)
verbunden  werden und so als automatische Pactor- und Amtor- Mailbox
arbeiten.

Das Programm wurde 1997 von Tom Sailer geschrieben (Danke!!!) und wird
laufend von Axel Krause, Gnther Montag und vielen Freunden
weiterentwickelt.

Bitte um Kontakt ber die Mailingliste!


2) Installation, Konfiguration, erster Test:
   =========================================

Voraussetzungen:
Hardware: 
Pentium ab 133 MHz. Die Soundkarte mu mmap() untersttzen.
Software:
hf bentzt das gtk+ -Toolkit (Version ab 1.2.0),
das in vielen Linux-Distributionen enthalten ist.
Mit 'gtk-config --version' wird die installierte Version angezeigt.

'hf-<version>.tar.gz':
entpacke:
# tar -zxvf hf-<version>.tar.gz 
gehe in das Verzeichnis:
# cd hf-<version> ,
starte das configure-Skript:
# ./configure ,
(die Optionen sind sichtbar mit	configure --help,
aber normalerweise mssen keine Optionen mehr eingeben werden)
kompiliere es:
# mit make,
installiere es (wegen sonst fehlender Schreibrechte als root !):
# make install 

'hf-<version>.rpm':
installiere: 
# rpm -i hf-<version>.rpm
oder (bei falscher Fehlermeldung wegen fehlendem gtk)
# rpm -i --nodeps hf-<version>.rpm

Die systemweite Konfigurationsdatei ist /etc/hf.conf.
Dort mu normalerweise nur die serielle Schnittstelle fr 
die PTT-Schaltung eingestellt werden. 

Erster Test:
Von der Konsole:
Starte einmal als root und als normaler Benutzer
# /usr/bin/hf
ohne Optionen.
Das Startskript hf prft die Konfiguration und gibt Hinweise.
Bei Erfolg rollt nach den ersten Meldungen eine Zahlenreihe wie diese
ber den Schirm:
corrout	...	intermediate   ...

Wenn das luft, dann unter X:
mit 'ALT + F2' ein Befehlsfenster ffnen,
# /usr/bin/hf
Hfkernel erscheint in einem "xterm", danach
erscheint das graphische Terminal hfterm im Vordergrund. 
Das Spektrumdisplay (Spectrum-Button oder F2 oder <Strg>F) zeigt ob Signale
ankommen, und ob die Verstrkung der Soundkarte richtig eingestellt ist.
Im RX-Fenster erscheinen decodierte Zeichen.

Wenn hf luft: mit ln -s /usr/bin/hf /home/(Benutzername)/Desktop/hf 
ein dynamisches Link auf das Desktop legen. Dies geht auch, wenn man mit
der rechten Maustaste  auf das Desktop klickt, 'neu', 'Anwendung' ... 
aber das wei ein alter Linux-Hase schon, oder?

Das Verzeichnis fr Deine persnlichen Dateien (Konfiguration, Fixtexte,
Log...) heit hf in Deinem home-Verzeichnis  und wird beim ersten Start
von hf automatisch angelegt und mit Beispieldateien gefllt.
Die persnliche Konfiguration (Rufzeichen, Name...) erfolgt mengefhrt
von hfterm aus.

Die Dokumentation ist in /usr/share/hf, und - je nach Distribution - 
in /usr/share/doc/hf oder in /usr/share/doc/packages/hf,
der wichtigste Text ist dieser.


3) Anschlu der PTT-Buchse :
   =========================

Wie bei jedem Funkprogramm, werden mit 1 npn-Transistor und 2 Widerstnden 
Computer und Funkgert verbunden:
                              _____
                      /------|_10k_|---O  
 RTS pin             /                PTT pin 
 Computer           /                 Transceiver
       _____    B |/   C
 O----|_10k_|-----|\
                  | \_| E
                     \
            npn       \
            Transistor |
                       |
                       |
               Masse =====
                                               

Natrlich gibt es jede Menge verfeinerte Mglichkeiten
mit Optokopplern und Relais...


4) Probleme mit hfkernel:
   ======================

Manchmal "klemmt" das Programm nur einfach: 
-> mit <strg> c oder hfkernel -k beenden und nochmal probieren.

Versagt das Startskript hf oder mchtest Du "von Hand" starten?
Versuche von einer Konsole aus hfkernel starten:
# hfkernel
Fge bei Erfolg
(corrout	...	intermediate   ...)
nach und nach die weiteren bentigten Optionen hinzu.
Am wichtigsten das socket zur Verbindung mit hfterm (-c /var/run/hfapp),
und die serielle Schnittstelle.
Dann starte als normaler Benutzer unter X:
# hfterm -k /var/run/hfapp 

Hufigste Fehhlermeldungen:

Fehler mit 'MMAP': (HUFIGSTER FEHLER !)
Soundkarte und / oder -treiber untersttzt 'mmap()' nicht.
(DMA, Programm greift direkt auf den Soundkartenpuffer zu)
Versuche zuerst die experimentelle Option -n (no mmap)
oder die Option -h (Halbduplex erzwingen), ausfhrlichere Hilfe: siehe 7).
Am besten, setze die Optionen mit einem beliebigen Editor
in /etc/hf.conf, dort sind auch hilfreiche Kommentare, und starte dann 
# /usr/bin/hf

Fehler mit 'open':
Ist der Soundkarten-Treiber geladen ? (siehe 7).

Fehler mit 'ioctl: TIOCMBI[CS]:'
Ist die serielle Schnittstelle in /etc/hf.conf richtig? 

Fehler mit 'permission denied':
Fehler mit 'pthread_create':
Bei Start von hfkernel als Nicht-root: Ist das suid-bit gesetzt?
# ls -l /usr/bin/hfkernel 
sollte etwa ergeben:
-rwsr-xr-x   1 root     root       372757 Sep 13 10:34 /usr/bin/hfkernel
Das 's' hier ist das suid-Bit, also Superuser-Recht bei Ausfhrung.
Wenn es nicht da ist, setze das Suid-Bit von Hand mit
# chmod 4755 /usr/bin/hfkernel. 
Es gibt noch 2 andere Wege, hfkernel fr Nicht-root-Bentzer ausfhrbar
zu machen: siehe dazu 6) Root-Rechte.

Bei manchen Kombinationen von Soundkarte und -treiber kann sich der
hfkernel aufhngen mit einer Endlosschleife von 
"... fragments passed since last wakeup" 
oder 
"OSS driver lost interrupt". 
Leider gab es manchmal auch Abstrze, sorry!
In V.0.6 habe ich eine Sicherungsfunktion eingebaut, die dies
verhindern sollte.
Mehr ber Probleme mit der Soundkarte oder Sound-Treiber: 7).

Wenn bei Halbduplexbetrieb die Zahlen 
corrout	...	intermediate   ...
immer sehr gro sind (z.B. 8000)  mu evtl. die Option
'-R' (Ausschalten der RDTSC-Instruktion, prozessorabhngig, 
vor allem bei Nicht-Intel-Prozessoren) zugefgt werden.

Wenn Pactor-ARQ nicht oder nur schlecht geht, 
(vor allem dann, wenn hfkernel nur mit der Option -h oder 
- noch schlechter - -R luft) 
mut Du noch eine Kalibrierung durchfhren - siehe 8).

Versuche auf jeden Fall, hfkernel ber das Skript hf, das /etc/hf.conf 
einliest, zum Laufen zu bringen. Das kombinierten Starten mit hfterm 
ist dann leichter. Alle zustzlichen Optionen knnen 
in /etc/hf.conf in die Zeile "otheroptions" eingefgt werden, 
von Leerzeichen getrennt, z.B. "-n -i "

Hier ist die vollstndige Liste der Optionen von hfkernel:
 -2 Im Standby-Modus 200 Baud nicht decodieren
 -3 Im Standby-Modus 300 Baud nicht decodieren
 -a Pfad zum Audio-Gert (Default: /dev/dsp)
 -c Pfad zur Software-Schnittstelle (Default: /var/run/hfapp)
 -f Im Standby-Modus keine Frequenznachstellung (frequency tracking)
 -h Halbduplex erzwingen (luft mit manchen Soundkarten besser)
 -i invertiert PTT-Impuls
 -k Hfkernel beenden (wird im Startskript hf verwendet)
 -l Eintrge in Logdatei (Default: keine)
 -M Pfad zum Mixergert 
 -m CPU-Uhr in MHz (auf khz genau)
 -n Verzicht auf 'mmap()' (kein direkter Zugriff auf Soundkartenpuffer).
    Experimentell! Fr manche Soundkarten, die (oder deren Treiber) mmap
    nicht richtig untersttzen.
 -p Pfad zur seriellen Schnittstelle fr die PTT-Ausgabe (Default: keiner)
 -R deaktiviert den Gebrauch der RDTSC-Instruction (nur bei Intel-Systemen).
    Die Verwendung der RDTSC-Instruktion kann bei Laptops und/oder 
    bei aktiviertem APM (Advanced Power Management) Probleme verursachen.
 -r Zugangsrechte zur Software-Schnittstelle (Default: 0777 = rwxrwxrwx)
 -s Korrektur der soundcard sampling rate
 -t gettimeofday - Korrekturfaktor (Zeitbestimmung ber Prozessortaktrate)

   
5) hfterm:
   =======

Die Bedienung von hfterm ist intuitiv. Hilfe, wenn gebraucht: F1.
Status- und Mode-Men und die Buttons erklren sich selbst. Wenn Du, wie
ich, keine Muse magst, werden Dich die vielen Tastenkrzel siehe Mens) 
beglcken. Modus mit F..., Textmakros mit <Shft>F...
Beachte die Meldungen im Status-Display-Fenster unten. 

Wenn Du wissen mchtest, wie die Digimodes klingen:
Beispielklnge in www.wunclub.com/sounds !

hfterm denkt mit (autorx / autotx -Funktionen).
Eingaben ins Sendefenster schalten auf Senden im
passenden oder letzten Modus. Nach einigen Sekunden schaltet hfterm auf
Empfang, auer es ist explizit ein Sendemodus, z.B. Rtty-Tx, gewhlt.
Das ist hilfreich fr die Baken- und Mailbox-Funktion.

 "RTTY" 
Zum Anfreunden mit dem Programm versuche zuerst RTTY zu
empfangen und zu senden. blich sind Shift 170 Hz und Baudrate 45. 
Suche im 20m-Band nach dem typischen schnen
RTTY-Maschinengerusch. ffne ber das Men Utilities oder einfach mit
'<Strg> F' (<Strg>-Taste gedrckt halten und F eingeben) das
Frequenzspektrumdisplay. Nach meiner Erfahrung geht das Abstimmen am
schnellsten mit dem Transceiver.  Drehe die 2 Peaks unter die blaue und
rote Linie im Spektrum. Mit '<Strg> F' verlasse das Spektrum, gehe auf
'RTTY-Rx' und staune, das  Empfangsfenster decodiert Text. Warum nicht
einen CQ-Ruf beantworten? Natrlich nur mit Funklizenz, ohne
bersteuerte Soundkarte, mit miger Leistung (20 W gengt!), und mit
Rcksicht auf die Anderen, wie in allen Digimodes. 
Bei Dauersendung kommt ein "Diddle" mit "LTRS...".

 "PACTOR - AMTOR - GTOR"
Pactor ist eine Wissenschaft fr sich. Wenn Du noch nichts darber
weit, lies 'pactor.txt'  in /usr/share/hf/hfterm. be erst
das Empfangen, es ist etwas schwieriger als bei RTTY. Im Spektrumdisplay
sieht es wie RTTY aus, aber der Ton ist im 1.25 Sekunden- Rhythmus
gehackt. Manchmal kannst Du zwischen den Datenblcken die kurzen
Kontrollblcke hren. Auch bei exakter Abstimmung kannst Du manchmal
nichts dekodieren, wenn die Sendung in  Pactor-Level II oder III ist.
Manchmal erkennst du nur ein Rufzeichen, das immer in  Level I gesendet
wird. Rufe CQ in Pactor-FEC (Geduld!). Wenn jemand in FEC ruft, antworte
in ARQ.  Rufe eine Mailbox in ARQ.  Gehe nach dem Senden nicht sofort in
'standby', das Programm knnte hngen. (Wenn es hngt, einfach warten.)
Sondern: QRT ('Alt Q'), etwas warten (QRT -Routine),  dann geht das 
Program von selbst in standby (Bereitschaft). 

 "PARAMETER"
'<Strg> P' ffnet eine Eingabemglickheit fr Dein Rufzeichen und
Programm-Parameter wie mark, Shift, Baudrate, Txdelay fr die
verschiedenen Betriebsarten. Beim Beenden von hfterm werden die
Parameter in  ~/hf/hfterm.rc  gespeichert (digital, bitte nicht editieren!).

 "'BRAG' (PERSNLICHE DATEN)"
'<Strg> B' ffnet ein Eingabefeld fr Dein Rufzeichen und 'brag'
(Angeben), also  Power, Rig, Antenne, Locator, QTH, Name, Mail. Diese
Daten werden von einer Such- und  Ersetz- Funktion zusammen mit den
Fixtexten bentzt, um Textbausteine zu senden. Der Ruhm Deiner Station
wird in ~hf/hfterm.brag gespeichert. 

 "FIXTEXTE"  
Wenn Du Textbausteine magst, editiere die Fixtexte (bis to 12) mit
'<Strg> T'. Bestimmte Begriffe in eckigen Klammern werden ersetzt -
Gedchtnissttze fr die mglichen Schlsselwrter ist das Fenster
unten. Zum Beispiel: [B] = Bakenaussendung (z.B. CQ), [TIME] =
Zeitstempel. Zum Senden eines Bausteins auf einen der 12 Buttons klicken
oder  'Shift F<1 ..12>', zurcklehnen und Kaffee trinken. Die Fixtexte
werden in ~/hf/fix.<nr> gespeichert. Dort knnen sie auch auerhalb des
Programms editiert werden. Durch Einfgen oder Umbenennen kannst Du 
beliebige Ascii-Texte bis zu einer Lnge von 1024 Zeichen importieren.
Mit dem File-Men  kannst Du auch eine beliebige Datei einmal oder als
Bake senden.

 "LOGBUCH"
Es gibt sogar 2. Eins fr groe Schirme, es ist immer offen.  Einfach
ausfllen und auf 'save' (oder 'clear') im Log-Men klicken. Das andere
Log ist fr meinen alten kleinen Bildschirm (ein grerer pat nicht in
mein Funkzimmer).  Entferne das groe Log-Eingabefeld mit '<Strg> Q'. 
Mit '<Strg> N' ffnet sich das kleine Log, wenn Du es brauchst, und das
Status display unten bleibt zu sehen. '<Strg> L' zeigt das ganze
Logbuch, '<Strg> A' archiviert die Logdatei und ffnet eine neue.
'<Strg> O' sucht alte Eintrge zum Editieren oder Lschen. Das Log wird
in Portionen zu je 50 Eintrgen gespeichert.

 "RX-TEXT" 
Empfangene Texte werden gespeichert, bis zu 5 alte empfangene Texte in 
in ~/hf aufgehoben. Im File-Men kann auch zustzlich eine Datei zum
Speichern ausgewhlt werden.


6) Root-Rechte:
   ============

hfkernel mu wegen des besonderen Hardwarezugriffs (im  Echtzeitmodus,
mit hoher Prioritt) nur von root, dem Superuser, aufgerufen werden. Im
normalen Betrieb sollte man aber nur als normaler Benutzer arbeiten.
Damit normale Benutzer hfkernel mit hfterm zusammen bequem starten
knnen,  wird nun bei der Installation von hfkernel automatisch das
Suid-Bit an hfkernel  vergeben mit: 
chmod u+s /usr/bin/hfkernel.
Dann kann das Programm vom normalen user mit Superuser-Rechten 
ausgefhrt werden. 
Wenn das luft und Du so zufrieden bist, brauchst Du
nichts weiter ndern und diesen Abschnitt nicht weiterlesen.

Wenn dies nicht gewnscht wird, sind in /etc/hf.conf 2 andere Wege
vorbereitet und beschrieben. Du brauchst dazu eins der (2 oder mehr?)
Programme, die es normalen Benutzern ermglichen, Programme mit
root-Rechten auszufhren: 'su1' oder 'sudo'. Diese sind in den meisten
Linux-Versionen enthalten.

su1: (man su1). 
Installiere su1, ffne mit einem Editor 
/etc/su1.priv (als root natrlich) und ndere wie folgt:
	# Define some privileged users
	define	GODS	root <dein_user_name>
und
	# These never require a password since they are reasonably safe
	ask	never
	allow   GODS    prefix  /usr/bin/hfkernel
Und: hf (vom user gestartet) ruft hfkernel mit Root-Rechten auf.
Eine Beispieldatei fr /etc/su1.priv ist 
/usr/share/hf/hfsu1.priv.txt

sudo: (man sudo)
Als root ergnze die Datei '/etc/sudoers' mit der Zeile 
<dein_benutzername> ALL=(ALL) NOPASSWD: /usr/bin/hfkernel
Und: hf (vom user gestartet) ruft hfkernel (mit Root-Rechten) auf.

Vorsicht: Alle diese Umgehungen der Root-Schranke knnen
Sicherheitslcken sein!


7) Probleme mit Soundkarten und Treibern:
   ======================================

Soundkarte :
============

hf geht nicht mit jeder Soundkarte und nicht mit jedem Treiber. Grund
ist nicht, weil das Programm schlecht wre, sondern weil es gut ist!
Wegen der zeitkritischen ARQ-Protokolle ist es notwendig, im
Echtzeit-Modus zu arbeiten, und deswegen wurde von Tom Sailer als bester
Weg das Programm mit dem "mmap()" - Systemaufruf geschrieben. Diese
Technik wird auch "DMA" (direct memory access, direkter Zpeicherzugriff)
genannt, also direktes Spiegeln des Soundkarten-Ringpuffers im
Arbeitsspeicher des Computers. Und nicht jede Soundkarte kann das, und
nicht jeder Soundtreiber untersttzt das richtig.

Ich experimentiere mit einem alternativen Code mit der OSS-API, der
nicht mmap(), sondern normale read() und write()-Zugriffe verwendet.
Dazu ist eine Option "-n" (no mmap) vorbereitet. 

Die Soundkarte mu 16-Bit-Sampling in der Byteordnung der CPU, 8kHz
Sampling-Rate, memory mapping der DMA-Puffer and triggering
untersttzen. Sie mu im "Mono"-Betrieb laufen knnen, was manche neuere
Soundkarten nicht mehr knnen! (Eine Verbesserung dafr ist angedacht.)
Eine Voll-Duplex-Soundkarte ist vorzuziehen.

Halb-Duplex-Soundkarten mssen umgeschaltet werden, wenn das Protokoll
vom Empfangen zum Senden und umgekehrt bergeht. Das dauert recht lang,
zwischen 5 und 35 ms. Das Program mit die durchschnittliche Zeit beim
Start.  Es versucht, diese Latenz in der PTT-Auftastverzgerung
(TXDelay) zu verstecken, also stelle das txdelay im Parameters-Men von
hfterm auf einen greren Wert ein! Und hoffe, da die Summe aus
Ausbreitungszeit zu Deinem Funkpartner  und dessen txdelay auch lnger
ist.

Die Audio-Level und -Parameter knnen mit den blichen Mixer-
Programmen eingestellt werden. Das eingebaute AGC sollte ausgeschaltet
sein.

Probleme (Abstrze und Hngenbleiben) gab es bei: 
ESS 1968 "Chipbug",hfkernel geht nicht mit OSS und nicht mit ALSA. 
VIA82C686: nicht mit OSS-Treiber, geht aber mit ALSA. 
Intel 101k: viele xruns ("OSS driver lost interrupt"), decodiert schlecht.

Treiber :
=========
hfkernel wurde fr die (alten) OSS-Treiber geschrieben, luft aber auch
(und oft besser) mit den neuen ALSA-Treibern, den diese haben
eine OSS-Emulation, die stndig verbessert wird. Je nach Soundkarte
luft hf mit beidem, einem oder keinem dieser zwei Treiberklassen. 

OSS:  

In alten Linux-Distributionen gab es ein 'freies' (mit der Distribution
bezahltes) OSS-Paket, das, z.B. bei meinem SuSE 6.3 in /tmp/opso
gefunden werden konnte und mit hf gut funktioniert, ich verwende es
immer noch. So weit ich wei, wird OSS immer noch weiterentwickelt, die
neueren OSS-Treiber kosten etwas (www.opensound.com). 

Mit alten und auch mit neuen (bis Kernel 2.4....) Linux-Versionen 
werden Kernelmodule mitgeliefert, die den alten OSS-Treibern hnlich
oder gleich sind. (Unterschied zu den ALSA-Modulen: Sie fangen nicht mit
'snd-' an.) Sie sind in /lib/modules/<kernelversion>/misc. (Quelltexte
in /usr/src/linux/<kernelversion>/drivers/sound). Sie lassen sich, nach
Deaktivieren von ALSA (rcalsasound stop), mit modprobe installieren.
(man modprobe, modprobe -p liefert Parameterinformation, modprobe -d
zeigt die Reihenfolge des Ladens der voneinander abhngigen Module.)
Vielleicht hilft Dir -bei ISA-PNP-Karten- pnpdump und isapnp, (siehe
manpages), bei PCI-Karten lspci, und die Dokumentation in	
/usr/src/linux/Documentation/sound fr Deine Soundkarte.  

ALSA: 

Zur Zeit wird die neue ALSA (Advanced Linux Sound Architecture)
rasant weiterentwickelt und von vielen Linux-Systemen verwendet. ALSA
wird mit den neuen Kerneln ab 2.6 als Standard geliefert. 
Die neueste Version von ALSA und viel gute Dokumentation bei:
http://www.alsa-project.org
http:///www.alsa-opensource.org
Mailinglisten knnen abonniert werden, fast 1000 Mails pro Monat:
https://lists.sourceforge.net/lists/listinfo/alsa-devel 
https://lists.sourceforge.net/lists/listinfo/alsa-user

Das ALSA-System hat 2 Arten der OSS-Emulation:

Die standardmige, (in den ALSA-Kernelmodulen enthaltene)  wird
automatisch aktiviert, wenn ein Programm wie hfkernel die  erste
(zweite...) Soundkarte als /dev/dsp0 (1...) anspricht, so wie es alle
OSS-Programme tun. 

Die andere (alternative) ist in einer zustzlichen library, die durch
das Skript  /usr/bin/aoss (enthlt: env LD_PRELOAD=/usr/lib/libaoss.so
$*) an das Programm gelinkt wird, z.B.: aoss <Programm).
Diese Mglichkeit ist in /etc/hf.conf vorbereitet. Um diese lib zu verwenden,
mu die Konfigurationsdatei /etc/asoundrc oder ~/asoundrc vorbereitet
werden mit dem Inhalt (bei nur einer Soundkarte)

	pcm.dsp0 {
		type hw
		card 0
	}

In neueren ALSA-Versionen ist diese Datei bereits vorhanden.

Beide Arten der ALSA-OSS-Emulation sind noch in der Entwicklung, und da
hfkernel besondere Ansprche stellt (mmap und Realtime-Modus) luft es,
je nach Soundkarte, manchmal mit OSS, manchmal mit ALSA, manchmal gar
nicht! Es wird intensiv an Verbesserungen gearbeitet, hole Dir die
neueste Version von ALSA und sei geduldig!!!

erweiterte PROBLEMLSUNG :
==========================

Wenn hfkernel nicht luft,
schlage ich die folgende Strategie vor:
for(;;) { 
	Sichere Deine Daten.
	Versuche zuerst die Soundkarte und den Treiber, die du hast.
	Versuche Optionen -n (no-mmap), oder -h (halfduplex).
	Versuche ALSA im normalen Modus.
	Versuche ALSA mit dem aoss-Prefix 
	(in /etc/hf.conf nur ein Kommentarzeichen entfernen)
	Versuche die neueste ALSA-Version, es wird besser.
	Versuche die neueste ALSA-Version mit dem aoss-Prefix.
	Versuche das kommerzielle OSS, wenn Du es hast.
	Versuche die OSS-Kernelmodule in Deiner Distribution.
	Versuche eine andere Soundkarte.
	if (Nerven am Ende) {
		break;
	}
}
if (wenn du c-programmieren kannst) {
	Verbessere l1/user/oss.c: oss_nommap_fdx_driver() und 
	oss_nommap_hdx_driver(), darin werden einfache read()'s und write()'s 
	mit der OSS-API versucht. (Ich, Gnther, arbeite auch daran gerade, 
	hf gibt	schon vertraute Gerusche von sich, Pactor-ARQ in schlechtert
	Qualitt mglich! Bitte Kontakt ber die Mailingliste!)
	Oder schreibe es in die ALSA-API um, die fr mmap-hnliche Mechanismen
	mehr Mglichkeiten hat. (Das sei aber schwerer als die OSS-Api, hat 
	man mir gesagt.) (Wenn Du das tust, verwende die neueste ALSA-lib, 
	weil sich mit Version 1.0 die API etwas gendert hat.)
}
else {
	versuche die vielen Linux-PSK-31-, MT63, MFSK - Programme,
	die gut laufen und auch Spa machen
	Versuchs mit hf wieder in 1 Jahr.
}

Wenn hfkernel luft, fixiere ihn mit Leim und berhre das System nie
mehr. Arbeite nie mehr als 24 Stunden pro Abend. Schau ob Deine Familie
noch da ist. Vergi nie: Mach das Ganze nur mit Spa. Wenn Du depressiv
wirst, maile mir. Ich bin ein Psychotherapeut. Wirklich. Ich heile mich
selbst durch Klavierspielen, andere Sachen machen und computerfreie
Tage feiern.


8) Echtzeit-Probleme und Kalibrierung: 
   =================================== 

Kurzwellenprotokolle sind normalerweise synchron. Sie bentigen eine
exakte Zeitquelle, um auch bei lngeren Unterbrechungen der bertragung
bitsynchron zu bleiben. Z.B. fordert das SITOR- (hnlich Amtor-)
Protokoll, da die Referenzzeitquelle nicht mehr als 20ppm vom Idealwert
abweichen darf. Pactor stellt hnliche Anforderungen, damit lngere
Verbindungen stabil bleiben. Es ist schwierig, eine so exakte Zeitquelle
zu finden. Deshalb erfordern alle Optionen, die in dieser Implementation
gewhlt werden knnen, eine manuelle Einstellung.

Wenn die Soundkarte voll-duplex-fhig ist, wird die Referenzzeit von der
Sampling-Rate (Zahl der pro Sekunde aufgenommenen, z.B.
16-Bit-Dateneinheiten) der Soundkarte abgeleitet. Um unzutreffende
Informationen des OSS-Treibers ber die Sample-Rate zu korrigieren, kann
die Option -s bentzt werden. Die Soundkarte sollte echte Quarze statt
billiger keramischer Resonatoren enthalten.

Wenn die Soundkarte nicht voll-duplex-fhig ist, kann die o.g. Methode
nicht angewandt werden. 

Auf Intel-Architekturen testet das Programm die Prozessorinstruktion
RDTSC (read time stamp counters, lese Zeitmarkenzhler), um zu sehen ob
sie verfgbar ist und arbeitet (auf Pentium-Computern und neueren sollte
dies der  Fall sein). Dieser Zhler zhlt im Takt der CPU-Uhr, deshalb
mu dem Programm die auf khz exakte Frequenz der CPU-Uhr bekannt sein
(Option -m). La Dich nicht von Werbegags irrefhren, z.B. luft ein AMD
K5 PR133  auf 100MHz.

Auf Nicht-Intel-Systemen, oder wenn die RDTSC-Instruktion nicht 
verfgbar ist oder nicht arbeitet, verwenden wir gettimeofday - in der 
Hoffnung da das tv_usec-Feld genau genug ist. Systematische
Frequenzabweichungen knnten mit der Option -t korrigiert werden.

RTTY, Pactor-FEC und Amtor-FEC sind immer ohne Kalibrierung mglich, es
wurde auch ber erfolgreiche Pactor- / Amtor-ARQ - Verbindungen ohne
Kalibrierung berichtet. Wenn ARQ-Verbindungen in Pactor, Amtor oder GTOR
lnger bestehen sollen, kann eine Kalibrierung die Leistung des
Programms verbessern. 

Wie bereits beschrieben, kann man mittels Optionen kann man an hfkernel
Korrekturfaktoren fr die Samplingrate der Soundkarte (-s), die
Prozessortaktrate (-m) und die gettimeofday-Funktion (-t) bergeben.
-s wirkt nur bei Vollduplex-Betrieb (Taktgeber ist hier die Soundkarte),
-m nur bei Halbduplexbetrieb mit funktionierender RDTSC-Instruktion 
-t nur bei Halbduplexbetrieb ohne funktionierende RDTSC-Instruktion,
das ist schlechter, da hier der Prozessor ber die Funktion
gettimeofday() die Zeit angibt, dies ist wegen schwankender
Systemauslastung ungenauer. 

Im hf-Paket sind 2 Programme zur Kalibrierung enthalten:

dcf77rx   
=======  

benutzt das Zeitzeichensignal des bekannten Langwellen-
Frequenznormalsenders DCF77 auf 77,5 KHz in der Nhe von Frankfurt, der
mit einer Leistung von 25 kW in etwa 2000 km Entfernung in fast ganz Europa
zu empfangen ist und brigens auch das Signal fr die Funkuhren liefert.
(Siehe auch dcf77.txt) Wenn Du dieses Signal noch nie gehrt hast, teste
doch einfach einmal das Demo-Programm dcf77gen !

Das Signal mu dazu auf eine Frequenz von 1000 Hz umgesetzt und an den
Mic- oder Line in - Eingang der Soundkarte gelegt werden. Stelle dazu
Deinen Empfnger auf 78.5kHz LSB (oder 76.5kHz USB). Weil ich keinen
Langwellenempfnger fr diesen Bereich hatte, habe ich, von Vorschlgen
aus dem Internet inspiriert, einen kleinen Konverters gebastelt, der die
77,5 KHz auf 4077,5 KHz umsetzt, die ich dann mit meinem Funkgert
empfangen konnte. Fr den Konverter brauchte ich einen 4MHz-Quarz aus
der Bastelkiste, 5 npn-Transistoren und noch ein paar Teile, auf deren
Werte es nicht exakt ankommt. Zum Empfangen gengt eine Ferritantenne
aus einem alten Radio oder ein einfacher Draht. Der Schaltplan ist in
/usr/share/lfconv.jpg. 

Starte dann dcf77rx (vorzugsweise als root). Man mu im SSB- oder CW-
Modus den DCF77-Sender ziemlich fein auf 1000 Hz einstellen, bis die
Sekundenticks mglichst regelmig erkannt werden. Das gelingt am besten
mit der Option -v 2 oder (nach etwas Training) mit dem Blick auf die
rotierende Linie, 

Nach 1-2 Minuten (unter strungs- freien Bedingungen) sollte das
Programm die DCF77-Zeit ermittelt haben. Von da an warte etwa 15 Minuten
und prfe die Messungen auf. Du kannst sie zur Sicherheit aufschreiben.
Aber sie werden automatisch nach /etc/hf.conf geschrieben. 
Sieh dort, ob die Korrekturwerte glaubhaft und etwa konstant sind, 
editiere sie wenn ntig, die letzten in der Datei werden vom Startskript
hf als Optionen fr hfkernel gelesen.

Ich habe den Output des Programms dcf77rx etwas verstndlicher gemacht
und eine Option zum Setzen der Systemzeit zugefgt (siehe man dcf77rx).

Diese Experimente haben mir viel Spa gemacht! 

dcf77rx und auch dcf77gen haben brigens jetzt auch schon eine 
-n (no  mmap) -Option. Sie gibt fr den wichtigsten Wert -s 
bei mir akzeptable Werte. Die anderen schwanken mehr.

Der Schweizer Zeitnormalsender HBG bei 75 kHz knnte vermutlich auch
verwendet werden, aber wir kennen das genaue Format seiner bertragung
nicht (es scheint dem des DCF77 sehr hnlich zu sein).

Wenn Du 2 Soundkarten aufeinander abstimmen mchtest, auch ber Funk,
knnte ein Partner dcf77gen und der andere dcf77rx laufen lassen.

reffreq  
=======  

Wenn Du weder DCF77 noch HBG empfangen kannst, bentze reffreq und eine
bekannte exakte Zeitquelle im Bereich von 200Hz-20kHz. 

Falls dcf77rx schlecht funktioniert, wenn Du aber das DCF77-Signal in AM
empfangen kannst, (2500 Hz), feht damit reffreq -f 2500. 
es pulsiert, aber es funktioniert!

Wenn Du Referenzfrequenzen in Funk oder Radio suchst, 
kann Dir hfterm's Spectrum bei der groben Messung helfen.
Rate dann einen runden Wert und lasse reffreq damit laufen.
Kennst Du Normfrequenzbaken in Deiner Gegend? Teile sie mir mit!
Ich hrte von WWV, Boulder, Colorado, 
auf 60 KHz, 5 MHz, 10 MHz, 15 MHZ, stimmt das? JJY in Japan?

Eine in den meisten Haushalten bereitstehende und normalerweise 
sehr genaue Quelle ist die Zeilenfrequenz-Synchronisation eines gewhnlichen
Fernsehempfngers. Die Zeilenfrequenz des ZDF wird auch von Behrden als
Zeitnormal benutzt. 

Stelle Deinen  Fernseher (mit Video-Grundfrequenzausgang) auf einen
Kanal ein und leite den Videoausgang an die Soundkarte. Starte 'reffreq
-f 15625' als root. Nach einigen Sekunden sollte das Programm die 
Korrekturparameter ermittelt haben. (Die oben angegebene Kommandozeile
setzt das PAL-format mit seiner Zeilenfrequenz von 15625 Hz voraus. Fr
andere Formate verwende die entsprechende Frequenz.)

In der CQDL 3/2003, S. 168, ist ein interessanter Artikel von Stefan 
Steger, der beschreibt, wie man aus einem Fernsehempfnger das
Zeilenfrequenzsignal ableiten kann, dazu gibt es eine Schaltung die es
in gerade Normalfrequenzen umwandelt.
(http://home.t-online.de/home/stefan.steger/homepage.html)

Ich konnte auch schon aus dem Koax-Kabel, das einen Satellitenreceiver
mit dem Fernseher verbindet, mit dem Oszillographen die 15625 Hz 
erkennen.


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

Ab Version 0.6 kann hfterm ber das TCP/IP-Protokoll (ber einen 
telnet-Port) Verbindung zu dem  hauptschlich im Packet Radio bekannten
und bewhrten Programm F6FBB aufnehmen. Dies kann auf dem gleichen,
oder auf einem ber Ethernet oder PLIP verbundenen anderen Computer
installiert sein. 

Einiges ist als Vorbereitung zu konfigurieren: ( <----- )
(In meinem Beispiel habe ich F6FBB nur fr hf konfiguriert.)

Ich ein bichen knobeln um das alles herauszufinden! Danke an alle 
Freunde von der F6FBB-Mailingliste xfbb@f6fbb.org und fr die gute
Dokumentation: http://www.f6fbb.org/fbbdoc/doc.htm und natrlich fr
F6FBB selbst!


Falls Computer und Port anders als die Vorgabe 
(Localhost = 127.0.0.1 = derselbe Computer, Port 6300, wie fr F6FBB blich) 
sein sollen, in /etc/hf.conf ndern.

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

Bei "Ports TNCs" mu fr hf je 1 Port / TNC addiert werden.
Die anderen mit Pfeil markierten Zeilen mssen zustzlich eingefgt werden.

/etc/ax25/fbb.conf:
(in lteren Versionen war das 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
#

Das wichtigste ist "mask" - addiere zur vorgegebenen "mask" 130.
Das ist: 2 fr Local und 128 fr Modem.
Dann kann sich ein User "local" (wozu auch das IP und telnet zhlt)
einloggen und hat Zugang zum "Modem", das ist auch ein TNC, und hfterm 
wird von F6FBB als TNC betrachtet.
Achtung: Erst ab dem zweiten login eines neuen Benutzers kann 
eine Mail verschickt werden! Konnte das noch nicht verbessern,
4 zur 'mask' addieren half nicht! `Feature` von F6FBB ?

Verzeichnis /etc/ax25/fbb/lang:
Ersetze english.ent durch eine leere Datei.

Wenn Du hf (vielleicht fr Deine Clubstation?) als Mailbox einsetzen und
mit Packet Radio verbinden mchtest, kannst Du natrlich noch die
Begrungsbotschaften in /etc/ax25/fbb/lang/english.txt optimieren. Es
knnte gut sein, darin die Benutzer zu informieren,
 - da sie erst ab dem zweiten Login Mails schicken knnen, 
 - da sie bei eventuellem Hngenbleiben ein Return senden sollen, und 
 - da man eine Mail mit "/EX" beendet.

Vielleicht kann auch manche Meldung, zur Kurz-Welle passend, gekrzt
werden.

F6FBB ist manchmal etwas sehr kryptisch zu konfiguren, ist aber gut und
stabil. 

Die Konfiguration von F6FBB kann nun mit telnet localhost 6300 getestet
werden. Es mu mglich sein, sich mit Rufzeichen neu anzumelden, und
beim zweiten login Mails zu versenden und zu lesen.

Nun ist der Start der Mailbox ganz einfach: Starte als root xfbbd, dann
als normaler user hf, aktiviere die Mailbox mit <Alt>M 
oder mit dem State-Men, und es luft.

Die Verbindung hfterm <--> F6FBB kann nun durch Schreiben ins Empfangs-
Fenster getestet werden (am besten im Modus Standby Pactor only, 
dann wird in Pactor-FEC gesendet). So kannst Du den Login eines
entfernten Bentzers simulieren, ohne 2 Computer verkabeln oder
eine Verbindung ber Funk machen zu mssen.

Ein Pactor-Connect mit dem Call im Men Utilities/Parameters/Pactor/Mycall
oder ein Amtor-Connect mit dem Call in ../Amtor/Mycall ffnet die Mailbox.
In FEC-Modes mu der Partner das Call, das in 'Personal Edit` (brag) 
konfiguriert ist, rufen.

Ich habe die Mailbox mit 2 Computern mit verkabelten Soundkarten 
mit Pactor FEC, Pactor ARQ, Amtor FEC und Amtor ARQ erfolgreich getestet.
Mit RTTY wrde sie auch gut gehen wenn nicht so viel Datenmll 
empfangen wrde, ich sollte noch eine Squelch-Funktion implementieren....

Beachte beim Einsatz ber Funk die Bestimmungen Deines Landes!

Wie wre das mit einer ptc-freien, microsoft-freien, vllig mit freier
Software laufenden Pactor-Mailbox in
Eurer Clubstation?


10) Liste aller im Paket enthaltenen Programme :
    ============================================

   In /usr/bin installiert:
   
   hfkernel and hfterm: Die 2 Hauptprogramme.
   hf: das Startskript fr beide. 
      
   paccalc:		berechnet den Datendurchsatz fr Pactor, 
                        in Abhngigkeit von den Empfangsbedingungen. 
			Fr das theoretische Studium von Pactor, informativ!
   channel:		Simulator fr die bertragung auf Kurzwelle.
   dcf77rx:		Berechnet Uhr-Korrekturwerte aus dem Signal des 
   			DCF77-Zeitnormalsenders, das an den Eingang der 
			Soundkarte gelegt werden mu. Setzt auch die Systemzeit.
			Siehe man dcf77rx.
   dcf77gen:		erzeugt das DCF77-Signal mit der Soundkarte. 
                        Siehe man dcf77gen.
   reffreq:		Berechnet Uhr-Korrekturwerte aus einem genauen 
                        Referenz-Signal (z.B. Zeilenfrequenz des Fernsehsenders
			ZDF). 
			Siehe  man reffreq.
   			(Manchmal wurde reffreq in Tom Sailer's ursprnglichen  
   			Dokumentationen als refclock bezeichnet.)

    Zustzlich optional: 
    (zum Kompilieren Komentarzeichen in os/makefile.am entfernen)
    (derzeit nicht verwendet):
    
    hfkernel_kernel:	arbeitet mit hfmodem, einem Kernelmodul, 
                        das die zeitkritischen Funktionen im Kernel-Space 
			ausfhrt (experimental!)
    hfkernel_link:	Diese Version von hfkernel kann auf einem Computer 
                        zweimal	laufen, verbunden mit channel (siehe unten). 
			Zu Entwicklung und Test (experimental!).
   


11) Verzeichnis der Hilfetexte :
    ============================
    
Bis jetzt gibt es Hilfe auf deutsch und englisch. bersetzungen sind
willkommen!

Die Texte warten im Programm-Verzeichnisbaum unter /doc auf den
geneigten Leser, und werden bei der Installation ins Verzeichnis 
/usr/share/hf kopiert. Die wichtigsten Texte sind ber das
Hilfe-Men von hfterm (F1) erreichbar.
   
  
    DEUTSCH:
    ========
   
   DE-HF-HOWTO.txt	(dieser Text, 
                        enthlt nun auch den Inhalt von 
			man hfkernel-de und man hfterm-de)
   pactor.txt		(gute Erklrung von Pactor, H.-P. Helfert et al.)
   pactor.ps		(wie oben in ps, drucke es mit lpr pactor.ps)
   dcf77.txt		(Langwellen-Zeitnormal fr Kalibrierung)
   TODO			(Die Stimmen, die Programmierer in schlaflosen 
                         Nchten im Kopf hren, zweisprachig)
   deutsche manpages:
   man hfkernel-de	
   man hfterm-de   	
   
   ENGLISCH:
   =========
   
   HF-HOWTO.txt		(wie dieser Text)
   P-MB-list.txt	Liste der Pactor-Mailboxen von Jost, ZS5S
   TODO			(die Stimmen..., zweisprachig)
   englische manpages:
   man hf
   man hfkernel 	
   man hfterm   	
   man dcf77gen 	(Tool zur Emulation des dcf77-Signals)
   man dcf77rx  	(Kalibrierprogramm, verarbeitet das dcf77-Signal)
   man reffreq		(Kalibrierprogramm, verarbeitet TV-Zeilenfrequenz)


   BILDER :
   ========
   lfconv.jpg		Schaltplan von  DL4MGE's Langwellen-4 MHz-Konverter


12 ) Schluwort :
=================
 
Das Programm hat noch einige BUGS,  manche sind auch FEATURES,  nicht
brllen, besser warten, noch besser reporten,  am besten
mitprogrammieren (Siehe 'TODO')! Mich selbst hat dieses Programm
inspiriert, c zu lernen, ich habe sehr viel gelernt (alles, was ich hier
geschrieben habe, wute ich vorher auch nicht!) und es hat mir bisher
(meistens) viel Spa gemacht !

Ich hoffe Tom und Ihr alle werdet es mgen.
Viel Spa!


Gnther Montag DL4MGE

00000000000000000000000000000000000000000000000000000000000000000000000


AUTOREN

Thomas M. Sailer	HB9JNX/AE4WA	Mail: sailer@scs.ch
			
Ralf-Axel Krause	DF3JRK		http://www.df3jrk.de.vu
					Mail: df3jrk@gmx.de	
					Packet: df3jrk @ df0hmb.#hh.deu.eu

Gnther Montag		DL4MGE  	Mail: dl4mge@darc.de
 					Packet: dl4mge @ db0zka.#bay.deu.eu

	
Homepage des Projekts, neueste Meldungen und neueste Version:
	http://hfterm.sourceforge.net	
	(Link: www.hfterm.de.vu)

Bitte trage Dich UNBEDINGT als Mitglied der mailing list ein bei:	
	https://lists.sourceforge.net/lists/listinfo/hfterm-hackers

Bitte alle Fragen und Bugmeldungen NUR an die mailing list:
	hfterm-hackers@lists.sourceforge.net
	
