is a general purpose CW (Morse code) functions library. It contains
routines for converting characters into Morse code representations
and back again, for sending Morse code characters, and for receiving
characters. It also contains routines to emulate an Iambic Morse
keyer, and a straight key.
The library can be included in any program that wishes to make use of
these features. It forms the heart of three Morse code tutor
applications that accompany the package in which it is distributed.
See the cw(7) man page for information on Morse code timings,
and the dot and dash representations for the various Morse characters.
contains an inbuilt tone queue. The queue is emptied by background
processing, using SIGALRM calls and itimers, so a caller program can
continue with other tasks while the library sends tones and keys any
As well as being used by the library functions that sound Morse code
characters and provide a keyer sidetone, the primitive tone queue
functions are publicly available to caller programs.
CONTROLLING AN EXTERNAL DEVICE
may be passed the address of a function that controls external keying.
This function is called each time the library changes the keying state,
either as a result of sending a Morse character or representation, or
as a result of an iambic keyer or straight key state change. The argument
passed is a single integer, TRUE for key-down, and FALSE for key-up.
calls the external keying function only when the keying state changes.
A call is likely each time a tone is taken off the tone queue.
SENDING CW CHARACTERS AND STRINGS
offers several functions that send individual characters and character
strings as Morse code. It also offers functions that allow
specialized 'representations' to be sent. A 'representation' is an ASCII
string that consists of only the characters '.' and '-'.
Characters and strings are converted into representations, and then the
correct tones for the dots and dashes in these representations are queued
on the tone queue, for action by the background queue emptying process.
RECEIVING CW CHARACTERS AND REPRESENTATIONS
contains functions to allow it to receive Morse code. To receive, the
library must be told when a tone start is detected, and when a tone end
is detected. It then determines whether the tone was a dot or a dash
depending on the timing difference between the two. After the required
silence gap has passed, the library may be queried to see what the
received representation or character was.
Errors in receiving may be detected by means of the flags passed back on
receive character functions.
offers functions to simulate an Iambic Morse keyer. The caller program
needs to tell the library of paddle state changes. Iambic keyer functions
are mutually exclusive with character send and straight key functions.
offers simple functions to allow effective pass-through of straight key
information. The caller program needs to tell the library of key state
changes. Straight key functions are mutually exclusive with character
send and iambic keyer functions.
The following list describes the functions available to a cwlib caller:
Despite the fact that this manual page constantly and consistently
refers to Morse code elements as dots and dashes, DO NOT think in these
terms when trying to learn Morse code. Always think of them as 'dit's
uses system itimers for its internal timing. On most UNIX flavours,
itimers are not guaranteed to signal a program exactly at the specified
time, and they generally offer a resolution only as good as the normal
system 'clock tick' resolution. An itimer SIGALRM usually falls on a
system clock tick, making it accurate to no better than 10mS on a typical
The effect of this is that an itimer period is generally either
exactly as specified, or, more likely, slightly longer. At higher
WPM settings, the cumulative effect of this affects timing accuracy,
because at higher speeds, there are fewer 10mS clock ticks in a dot
period. For example, at 12 WPM, the dot length is 100mS, enough to
contain five kernel clock ticks; at 60 WPM, the dot length is 20mS,
or just two kernel clock ticks. So at higher speeds, the effect of itimer
resolutions becomes more pronounced.
Man pages for cw(7,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL),
cwcp(1,LOCAL), and xcwcp(1,LOCAL).