cwlib

Langue: en

Autres versions - même langue

Version: CW Tutor Package (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

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).