| Introduction:
| -------------

Yes, this is written in english. Sorry, but you'll have to deal with
that.

| This README file covers the basics of "zhfcom", a program aimed at
| decoding HF data transmissions. It was initially aimed at the Sharp
| Zaurus family of Linux PDAs, but should also compile and run on other
| Linux systems.

I never intended to release this. I wrote this for personal use only
and the state of the project and the code quality is accordingly, as
well as the documentation (i.e. there is none).

I'm not capable (timewise) of giving you any support for it, with the
possible exception of people paying me exorbitant amounts of money in
consulting fees :)

Yes, the code is copyrighted. In other words: It's mine, all mine. If
you want to use it commercially, get in touch with me and I'm sure we
can work something out. If I find out you ripped me off, I will make
sure my lawyers hit you where it hurts the most -- your wallet.

As for personal use? Do what you must, let me know what you think,
but, as mentioned do _not_ _expect_ me to fix your problems or, even
worse, give you a basic introduction to working with computers for
free. Yes, I'm an arrogant asshole. So there.

Still wanna use it? Gee, you must be _really_ desperate. :)

So, what can I tell you?

The archive this came in should consist of several directories, namely
src, bin and etc. The 'src' directory contains the source code, whereas
there is a ready-to-run binary in the 'bin' directory. In addition,
there is an example configuration file in the 'etc' directory.

To make things work, copy/link the executable file from the bin
directory to someplace in your $PATH. Make a copy of the sample
configuration file (granted, it's mostly obsolete by now, but still)
and copy/link it to /etc/zhfcom.cfg -- have a look at the file and
change the appropriate entries to something that suits you.


| Configuration:
| --------------

What you need to know about the config file:

The configuration file consists of sections that are delimited by
lines only containing keywords in square brackets, [Like this]. A
specific section can be selected upon startup using command line
switches. If none is specified by the user, the program will try to
load its initial parameters from a section called [Default].

A section consists of variable assignments in the form

Variable = Value

The following variables are defined:

Mode -- the mode of operation. This is numeric, according to the list:

	0	RTTY (Baudot)
	1	RTTY (SITOR-B)
	2	FACSIMILE (bilevel, i.e. B/W)
	3	RTTY (SITOR-A)
	4	CW (lousy, not really working)
	5	GMDSS/DSC (experimental, not really working)
	6	ARQ/NRZI (experimental, not working)
	7	RTTY (ASCII -- untested)
	8	ARQ (experimental, not working)

It defaults to 0.

Rate -- the audio sampling rate used. Numeric. It defaults to 8000.

Baud -- the baudrate used for decoding, if applicable. Numeric. It
defaults to 50.

Mark -- the mark frequency assumed for signal decoding. Numeric. It
defaults to 1245 (Hz).

Shift -- the frequency shift between mark and space. Numeric. It
defaults to 450 (Hz).

LPM -- Lines Per Minute for decoding facsimile transmissions. Numeric.
Defaults to 120.

| Correction -- a correction value for decoding facsimile transmissions.
| It is possible to fine tune the LPM value using this. Numeric float.
| Defaults to 0. The Correction value is added to the LPM value in order
| to determine the exact LPM to use.

Squelch -- as the name implies. This defines the threshold the signal
needs to cross in order for the decoder to accept it. Numeric. A
useful range is 0-100, with 0 disabling the squelch function
altogether. Defaults to 50.

Log -- path to the file where received text transmissions are logged.
String. Defaults to "zhfcom.log".

Device -- the path to the audio device used for signal acquisition.
String. Defaults to "/dev/dsp1".

FAXPath -- the path to the file where received facsimile transmissions
are saved. An included "%lld" in this path will be replaced with date
and time. Facsimile data is saved in PBM format. String. Defaults to
"/home/root/%lld.pbm"

| Capture -- the path to the file where audio captures are saved. An
| included "%lld" in this path will be replaced with date and time.
| Audio data is saved in WAV format. String. Defaults to
| "/home/root/%lld.wav"


| Invocation:
| -----------

What you need to know about command line options:

Command line options will usually override settings from the config
file.

-z <int> -- set the "dotlen" parameter for CW decoding. Default 50.

-d <dev> -- audio device to use (see "Device" variable)

-b <baud> -- baud rate to use (see "Baud" variable)

-m <freq> -- 'mark' frequency (see "Mark" variable)

-s <shift> -- frequency shift between mark and space (see "Shift"
variable)

-r <rate> -- audio sampling rate to use (see "Rate" variable)

-M <mode> -- decoding mode to use (see "Mode" variable)

-L <LPM> -- LPM value for facsimile (see "LPM" variable)

-C <corr> -- LPM correction value (see "Correction" variable)

-c <path> -- use an alternate config file at <path>

-S <section> -- use parameter set from [section] for startup

-l <path> -- path of the file to log text transmissions to

-I -- start in idle mode when doing facsimile decoding

| -V -- print version information


| Operation:
| ----------

What you need to know about interactivity:

The program uses (hardcoded -- yes, I know that's nasty, but it
started out as a crude hack) escape sequences to diplay a kind of
status line on top of the terminal session. This line gives some
indication as to the current operating parameters. It looks like
this:

Mode Baud Shift Mark Squelch/10 Marklevel Spacelevel

This will tell you what the program is trying to do as well as give
you some basic aid for tuning the signal.

Received text will scroll in the remaining terminal area, possibly
with different colors to indicate the status of the received data.
This may or may not be of any significance, though. For facsimile,
reception status and progress is indicated there as well.


Keys to interactively change behaviour:

Cancel (ESC) -- terminates the program.

| Ok (Return) -- toggles capturing audio to a .wav file using the path
| defined in the "Capture" variable. Active recording is indicated by an
| asterisk in the status line.

| Center (Space) -- forces facsimile reception to start immediately
| (e.g. if you missed the beginning of a transmission or the APT signal
| wasn't recognized by the program) when in facsimile mode.

q -- squelch = squelch + 10, max. 150	'f'

w -- squelch = squelch - 10, min. 0	'0'

t -- switch to next mode of operation, according to the list of modes
as mentioned earlier in this document.

i -- invert shift (i.e. shift = -shift)

r -- reverse signal (switch mark and space)

m -- increase mark by 5 Hz

n -- decrease mark by 5 Hz

b -- skip to next baud rate (increase dotlen for CW). Baud rates are
toggled between 46, 50, 75, 100, 150, 200 and 300.

v -- decrease dotlen for CW

| s -- skip to next shift. Shifts are toggled between 85, 170, 200, 250,
| 450, 800, 850 and 1000 Hz.


| Warning:
| --------
|
| When doing facsimile reception, DO NOT use a flash memory device for
| holding the incoming facsimile, since the program will update the line
| count of the file for every line received, which might wear out the
| flash memory very quickly. I will NOT be held responsible for people
| killing their flash memory this way!


| Epilogue:
| ---------

That's all the information there is. Hope this helps.

Regards,
Chris.

