CWLIB(3)
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 con- tains routines for converting characters into Morse code representa- tions 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 applica- tions 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 back- ground 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 func- tions 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 key- ing state, either as a result of sending a Morse character or represen- tation, 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