NAME
cwlib - general purpose Morse code functions library
SYNOPSIS
#include <cwlib.h>
include(signatures)
DESCRIPTION
cwlib 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.
TONE QUEUE
cwlib 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 external device.
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
cwlib 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.
cwlib 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
cwlib 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
cwlib 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.
IAMBIC KEYER
cwlib 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.
STRAIGHT KEY
cwlib 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.
FUNCTIONS
The following list describes the functions available to a cwlib caller:
include(functions)
NOTES
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
and ’dah’s.
cwlib 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 100Hz kernel.
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.
SEE ALSO
Man pages for cw(7,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL), cwcp(1,LOCAL),
and xcwcp(1,LOCAL).