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

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

Version 0.7 JANUAR 2005

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

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

Die Implementation der 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

Hfkernel verwendet intern drei Unterprozesse (threads): 
einen Modemcode, der im Echtzeitmodus die Soundkarte beschreibt und liest,
einen fr das jeweils laufende 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 2 der 3 beigefgten Kalibrierprogramme vorhanden,
die mmap() verwenden.

Fr die ARQ-Modes und MT63 kann eine Kalibrierung in vielen Fllen ntig sein. 
Dazu sind drei Kalibrierprogramme im Paket enthalten.

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- Amtor- 
oder MT63-Mailbox arbeiten.

Das Programm wurde 1997 von Tom Sailer geschrieben (Danke!!!) und wird
laufend von Axel Krause, Gnther Montag und vielen Freunden
weiterentwickelt. Ab Version 0.6.6 ist Pawel Jalocha's MT63 integriert.

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.
Als user gestartet, legt es ein Verzeichnis "hf" in Deinem Home-Verzeichnis 
an und fllt es mit Beispieldateien.
(Wenn Du das hf-Skript nicht verwendest, tue dies von Hand.
Die Beispiele sind in /usr/share/hf/hf-examplefiles.)
Bei Erfolg rollt nach den ersten Meldungen eine Zahlenreihe wie diese
ber den Schirm:
corrout	...	intermediate   ...
Das bedeutet, da das "Herz" hfkernel regelmig schlgt.

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?

Wie bereits gesagt: 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/ds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               