Man Linux: Main Page and Category List

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