		UNIX Morse Code Tutor, Version 2.2
		----------------------------------


Introduction
------------
The original Unixcw package, version 1, grew out of a desire to have a
program available under Linux that was very similar to the one I was
used to under DOS.  While several Linux Morse Tutors were, in fact,
still are, available, I never quite found one that did the stuff I
wanted.

From the original Unixcw package came version 2.  This was almost a
total rewrite, although it included the same basic binaries as were in
version 1.  The two major changes for this version were the addition
of an extensive, general purpose CW library, and also an Xwindows-
based CW tutor program.

With version 2.1, finally, came full sound card support, built into
the CW library itself.  All three main user level programs that use
the library were enhanced to allow control over the sound card tone
volume.  Console speaker sound is still there, if needed, but sound
card tones became the default mode.

Version 2.2 is a bug-fixed version of 2.1.  It seems that some sound
card drivers (some later OSS drivers) couldn't handle the volume
control ioctls that the CW library uses, and this meant sound card
tones would not work for these systems.  To solve this, version 2.2
will use the /dev/mixer device to control volumes if it finds that it
cannot do this with the main sound card device.


The CW library
--------------
The heart of the package is 'libcw'.  This is a library which, when
built, offers the following basic CW services to a caller program:

  o Morse code character translation tables, and lookup functions
  o Morse code low-level timing calculations
  o A 'sidetone' generation and queueing system, using either the
    system sound card, the console speaker, or both
  o Optional keying control for an external device, say a transmitter,
    or an oscillator
  o CW character and string send routines, tied in with the character
    lookup
  o CW receive routines, also tied in to the character lookup
  o Adaptive speed tracking of received CW
  o An iambic keyer, with both Curtis 8044 types A and B timing
  o Straight key emulation

The library uses signals extensively to create a background task in
which to do the majority of its work, leaving the main program free to
handle other tasks.  For example, the simplest CW sending program that
uses the library looks like:

	#include <cwlib.h>
	int main (int argc, char **argv)
	    {
		/* Start the string sending in the background. */
		cw_send_string ("Hello, world");

		/* Wait for the string send to complete. */
		cw_tone_queue_wait ();
	    }

Instead of the cw_tone_queue_wait() call, this program could go off and
handle any other work it has to do, asynchronously from the CW library's
sending the string.

As well as the handful of applications included in Unixcw 2.2, the
the following sorts of programs might also use 'libcw' as their core:

  o A fully graphical CW send and receive station
  o 'CWbiff', announces incoming email sender in CW
  o Offline CW reader program, capable of decoding CW from MP3 or other
    audio file formats
  o A simple Iambic keyer for an external transmitter, using the mouse
    buttons as the keyer paddles
  o A more comprehensive CW tutor program
  o An automated Morse Code testing application

'cwlib' is coded in 'C' for easy portability and use.


Included applications
---------------------
The package comes with four basic applications:

  o cw    This is a CW sending 'engine',  that reads  characters
          from stdin, sounds them on either the sound card,  the
          console speaker, or both, and echoes them  to  stdout.

  o cwgen This is a simple random character generator,  that can
          be used as a 'feed' for cw.  For example:

              cwgen | cw

  o cwcp  This is a curses-based menu program that will generate
          random morse, groups of characters from selected sets,
          words, and CW abbreviations randomly, sound them using
          'cw', and can handle changes of WPM and pitch from the
          keyboard.  It owes much to CP222.EXE, by VU2ZAP.

  o xcwcp This is X-based CW tutor program.  This version offers
          the same random and keyboard sending as 'cwcp', but in
          addition,  will also read CW that you send to it using
          the keyboard or mouse as a keyer, so you  can  use  it
          for sending practice as well as receiving.

'cw' and 'cwgen' require only a basic 'C' compiler.  'cwcp' requires a
'C' compiler and a Curses library.  'xcwcp' requires a 'C++' compiler
and a copy of the Trolltech Qt library.  This library is fairly
standard on Linux systems, since it is the basis of KDE, so relying on
this should not be too much of a problem.


Building the library and programs
---------------------------------
Please see the file INSTALLING for details on how to build Unixcw
version 2.2 from the distributed sources.


License
-------
Unixcw is distributed under the GNU GPL.  Please see the COPYING file
for details.


Acknowlegements
---------------
Thanks to Kamal Mostafa, KA6MAL, for reviewing the cwlib API, showing
me the errors of my ways with 64-bit integers, and hounding me to add
the adaptive receive speed tracking, and to Joop Stakenborg, PA4TU,
for being a willing "guinea pig" with various snapshots of unfinished
versions of the package, for help in isolating various sound card
problems, and for his continued enthusiasm and interest in maintaining
Unixcw as a Debian Linux package.

Huge thanks to Paolo Cravero, IK1ZYW, for very kindly making the first
sound card patch available for Unixcw 2.  His tone generation code is
now fully embedded inside the CW library, and it's no exaggeration to
say that without his help, there would still be no sound card support
in Unixcw.

Also, thanks to Michael D. Ivey for identifying a problem with CW
sending rhythm when sending in 'Farnsworth' mode, and for taking the
time and trouble to test the patches I sent him.

Finally, thanks to everyone who has sent feedback about Unixcw.  If
not for your interest, and fairly frequent requests for a version that
works with a sound card, the package would not have progressed at all.


Have fun
--------
Simon Baldwin, G0FRD
simonb@caldera.com
