Man Linux: Main Page and Category List

NAME

       cw - sound characters as Morse code on the soundcard or console speaker

SYNOPSIS

       cw [-s sound]  [--sound=sound]  [-x  sdevice]  [--sdevice=sdevice]  [-y
       mdevice] [--mdevice=mdevice] [-d cdevice] [--cdevice=cdevice] [-f file]
       [--file=file] [-w WPM] [--wpm=WPM] [-t tone] [--tone=tone]  [--hz=tone]
       [-v  volume]  [--volume=volume]  [-g  gap]  [--gap=gap]  [-k weighting]
       [--weighting=weighting]    [-e]  [--noecho]  [-m]  [--nomessages]  [-c]
       [--nocommands] [-o] [--nocombinations] [-p] [--nocomments]

       cw also accepts the -h, --help, -V and --version options.

       The  LINUX  version  understands  both short form and long form command
       line options.  Other  versions  may  understand  only  the  short  form
       options.

       Options  may  be predefined in the environment variable CW_OPTIONS.  If
       defined, these options  are  used  first;  command  line  options  take
       precedence.

DESCRIPTION

       cw  reads  characters  from  an input file, or from standard input, and
       sounds each valid character as Morse code on either  the  system  sound
       card,  the  system  console  speaker,  or  both.   After  it  sounds  a
       character, cw echoes it to  standard  output.   The  input  stream  can
       contain  embedded  command  strings.   These change the parameters used
       when sounding the Morse  code.   cw  reports  any  errors  in  embedded
       commands on standard error.

   COMMAND LINE OPTIONS
       cw  understands  the  following  command  line  options.  The long form
       options may not be available in non-LINUX versions.

       -s, --sound
              Specifies the way that cw generates  tones.   Valid  values  are
              ’soundcard’  for  tones through the system sound card, ’console’
              for tones through the console speaker, or ’both’.  These may  be
              shortened   to   ’s’,   ’c’,  or  ’b’.   The  default  value  is
              ’soundcard’.

       -x, --sdevice
              Specifies the device file to open for access to the sound  card.
              The  default  device  is  /dev/audio,  and this is generally the
              correct device on most systems.  See NOTES ON USING A SOUND CARD
              below.  This option is invalid if cw is generating tones only on
              the console.

       -y, --mdevice
              Specifies the device file to open for access to the sound mixer.
              The  default  device  is /dev/mixer.  See NOTES ON USING A SOUND
              CARD below.  This option is invalid if cw  is  generating  tones
              only on the console.

       -d, --cdevice
              Specifies  the  device  file to open for sound using the console
              speaker.  The default device here is /dev/console,  although  in
              general it is likely to be necessary to provide a suitable value
              for this option if console sound is selected.  The value  should
              be  a  console device file, capable of KIOCSOUND.  See SELECTING
              SUITABLE SOUND DEVICE FILES below.  This option is invalid if cw
              is generating tones only on the soundcard.

       -f, --file
              Specifies  the  input  file  to open.  The default input file is
              standard input.

       -w, --wpm
              Sets the initial sending speed in words per minute.   The  value
              must be between 4 and 60.  The default value is 12 WPM.

       -t, --hz, --tone
              Sets  the  initial  sounder  pitch  in  Hz.   This value must be
              between 0 and 4,000.  A value of 0 selects silent operation, and
              can  be  used  for  timing checks or other testing.  The default
              value is 800Hz,

       -v, --volume
              Sets the initial sending volume, as  a  percentage.   The  value
              must  be  between  0 and 100.  The default value is 70 %.  Sound
              volumes work fully for sound card tones, but cw  cannot  control
              the  volume  of tones from the console speaker.  In this case, a
              volume of zero is silent, and all other volume values are simply
              sounded.

       -g, --gap
              Sets  the  initial extra gap, in dot lengths, between characters
              (the ’Farnsworth’ delay).  It must be between  0  and  60.   The
              default is 0.

       -k, --weighting
              Sets  the initial weighting, as a percentage of dot lengths.  It
              must be between 20 and 80.  The default is 50.

       -e, --noecho
              Stops cw echoing characters on standard output  after  they  are
              sounded.  The default is to have echoing on.

       -m, --nomessages
              Stops cw printing error messages on standard error.  The default
              is to print messages.

       -c, --nocommands
              Stops cw  from  interpreting  commands  embedded  in  the  input
              stream.  The default is to interpret embedded commands.

       -o, --nocombinations
              Stops cw from treating character strings bracketed by [...] as a
              single  combination  character.   The  default   is   to   honor
              combinations.

       -p, --nocomments
              Stops  cw  from treating character strings bracketed by {...} as
              ’comments’.  Characters inside these braces will  be  echoed  to
              standard  output,  but  not  sounded.   When  comments are being
              honored,  any  embedded  commands  inside  the  braces  will  be
              ignored.  The default is to honor comments.

   SOUNDING CHARACTERS
       cw reads characters, one at a time, from its standard input or from its
       input file.  Lowercase letters are converted internally  to  uppercase.
       The following list shows the valid IS0 8859-1 (Latin-1) characters that
       can be sounded by cw:

              ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_@ and space

       In addition, the program also understands the following ISO 8859-1  and
       ISO 8859-2 accented characters:

              ÜÄÇÖÉÈÀÑ, S with cedilla, Z with dot above

       and   accepts  the  following  as  single  character  forms  of  common
       procedural signals:

              <>!&^~

       See cw(7,LOCAL) for more information on the above characters and  Morse
       code.

       If  cw receives a character not in this set, it prints an error message
       ’?c’, where c is the error character.  The only exceptions to this  may
       be  the cw command escape character ’%’, the combination start and stop
       characters ’[’ and ’]’, and the comment start and stop  characters  ’{’
       and ’}’.  See EMBEDDED COMMANDS and MORSE CODE COMBINATIONS below.

   EMBEDDED COMMANDS
       cw  recognizes  special  sequences  in  the  input  stream  as embedded
       commands.  These commands alter the parameters of the cw  while  it  is
       running,  or  query  current  values.  All commands are prefixed by the
       command escape character ’%’, and those which set a value  end  with  a
       semicolon.

       The format of an embedded command to change a parameter value is

              %Cvalue;

       where  C  is a command letter indicating what action cw is to take, and
       value is the argument or value for the command.

       Valid command letters are

       T      Sets the tone pitch used to sound a character.

       W      Sets the sending speed.

       G      Sets the ’Farnsworth’ gap between characters.

       K      Sets the weighting.

       E      Disables or re-enables echoing of sent  characters  on  standard
              output.

       M      Disables or re-enables error messages on standard error.

       S      Disables or re-enables speaker tone generation.

       C      Disables  processing  of  embedded  commands.   Note  that  once
              disabled, this command cannot re-enable them.

       O      Disables  or   re-enables   recognition   of   [...]   character
              combinations.

       P      Disables  or  re-enables  recognition  of  {...} comments.  When
              comments are being recognized, any character  after  an  opening
              ’{’  and  before  any  closing  ’}’  will  be echoed to standard
              output, but will not be sounded, or have any other effect.

       For example, the embedded command sequence

              %W25;%T1200;

       will set cw to a speed of 25 WPM, and a tone pitch of 1200Hz.

       The ’T’, ’W’, ’G’, and ’A’ commands take values along with the command.
       The  limits  on  values given for embedded commands are the same as the
       limits available for command line options, detailed above.

       The ’E’, ’M’, ’S’, ’C’ and ’O’ commands are flags, and treat a value of
       zero  as  clear,  and  any  other  value  as set.  So, for example, the
       sequence

              %M0;%C0;

       will turn off error messages, and  then  turn  off  the  processing  of
       embedded commands.

       If  a  parameter  is  set  successfully,  cw reports the new setting on
       standard error (except if no error messages is set).  If  an  error  is
       detected  in an embedded command, cw reports an error.  For the formats
       of error messages see the MESSAGE FORMATS section below.

       The current values of parameters within cw may be queried, as  well  as
       set.  The command format

              %?C

       queries  the  value  of  the parameter normally set with command C.  cw
       reports the current value on standard error, using the same  format  as
       when new values are set.

       The  current  values  of  parameters within cw may also be requested as
       output in Morse code.  The command format

              %>C

       will generate  Morse  output  reporting  the  value  of  the  parameter
       normally set with command C.

       If  embedded  commands  are disabled, ’%’ characters are treated as any
       other (in this case, invalid) input character.

       Once processing of embedded commands has been switched off, any command
       to  switch this feature back on will not be recognized.  That is, after
       ’%C0;’, an ’%C1;’ will not be recognized.

       There is one additional command, and that is ’%Q’.  This command closes
       all open files and terminates cw.  Any characters after this command in
       the input stream will be lost.

       The file cw.h provides a full set  of  definitions  for  the  commands,
       special characters, and status codes of cw.

   MESSAGE FORMATS
       Where  a parameter value is set correctly with an embedded command, the
       message format

              =Cvalue

       is returned.  C is the command used, and value is the new value.

       If an invalid value is supplied for a parameter in an embedded command,
       a message

              ?Cvalue

       is returned.

       Where an invalid command is encountered, the message format

              ?%C

       is used.  For an invalid query, the message is

              ??C

       and for an invalid request for a parameter in Morse code the message is

              ?>C

       A character in the input stream  that  cannot  be  sounded  produces  a
       message

              ?C

       These  messages  are not intended to be user-friendly, but are designed
       to be easily and quickly interpreted by  another  program.   Similarly,
       the  format  of  embedded commands is more computer-friendly than user-
       friendly.

       If error messages are disabled, no messages of any type are printed  on
       standard error.

   MORSE CODE COMBINATIONS
       The  standard set of characters offered by cw may not be sufficient for
       some purposes.  For example, some international characters do not  have
       equivalent ISO 8859-1 and ISO 8859-2 that cw can sound directly.

       To  help  in  sounding  such  characters, cw offers the ability to form
       combination  characters  by  placing  individual  character  components
       between  [...]  brackets.   Cw  sounds  characters inside a combination
       without the usual gap between them.  In this way, any missing character
       in the set can be built.

       For example

              [VA]

       is one way to form the VA procedural signal, though

              [SK]

       works just as well.  The eight-dot error signal can be sounded with

              [HSE]

       or the C-cedilla in international Morse code with

              [CE]

       There  can  be  as  many  valid letters, numbers, or figures inside the
       [...]  brackets as  required.   For  example,  an  alternative  way  of
       sending the error signal could be

              [EEEEEEEE]

       Finally, three alternative ways of sending 73 might be

              [TTEEE][EEETT]
              [TDE][EUT]
              [GEE][VT]

       Embedded  commands may be placed inside [...] combinations if required.
       Combinations do not nest.

       This feature can be  disabled  by  using  the  -O  or  --nocombinations
       command  line flags, or with the ’O’ embedded command.  If combinations
       are disabled, ’[’ and ’]’ characters are treated as any other (invalid)
       input character.

   NOTES ON USING A SOUND CARD
       By  default, cw uses the sound device "/dev/audio" to access the system
       sound card.  This is generally the  correct  device  to  use,  but  for
       systems  with special requirements, or those with multiple sound cards,
       the option -x or --sdevice can be used to specify the device for  sound
       card  access.  If the sound card device cannot be set up, cw prints the
       error message

              cannot set up soundcard sound

       and exits.

       Sound card devices are usually single-access devices, so that when  one
       process has opened the device, other processes are prevented from using
       it.  If cw finds that the sound card  is  busy,  it  prints  the  error
       message

              open /dev/audio: Device or resource busy

       but continues to retry on each new tone until it can access the device.
       Once it has control of the sound card, cw will only use it as  long  as
       it  has  Morse  code  tones  to sound.  It will close the device during
       pauses in output, to allow other programs to use it.

       The main sound card device will often allow cw to control tone  volumes
       directly,  but  where  this  is  not possible, cw uses the mixer device
       instead.  By default, this is  "/dev/mixer",  but  the  device  can  be
       specified  with  the  -y or --mdevice options.  In general, as with the
       main sound card device, the default mixer device is usually the correct
       one to use.

       The  mixer  device is only used if the sound card does not allow volume
       control through the main sound card device.

       cw will  of  course  conflict  with  any  other  programs  that  expect
       exclusive use of the system sound card (for example, MP3 players).

       The  sound  card  device is not used if cw is only sending tones on the
       console speaker.

   SELECTING SUITABLE SOUND DEVICE FILES
       When cw sounds Morse code on the UNIX  console  speaker,  it  uses  the
       KIOCSOUND   ioctl.    By  default,  it  will  try  to  use  the  device
       "/dev/console", unless the -d or --cdevice  option  is  used.   If  the
       device refuses to create tones, cw prints the error message

              cannot set up console sound

       and exits.

       If  the default device is not available, or if cw has no permissions to
       use it, cw will need to be told which  device  to  use.   Which  device
       files  are  suitable  will depend on which operating system is running,
       and which system user  ID  runs  cw.   They  must  however  be  console
       multiscreen devices, for example /dev/tty1 and up on LINUX.

       For  console  sound  on  LINUX,  it  is  normally possible to run cw as
       superuser, with the default /dev/console  as  the  sound  device;  this
       combination  will  usually work.  Unless running as superuser, cw won’t
       have the necessary permission to access a ’foreign’ tty.  Making cw  an
       suid  binary  avoids  this  problem.   The  program  does not fork() or
       exec(), so making it suid should be relatively safe.

       There is no need to worry about console sound devices  if  cw  is  only
       sending tones on the system sound card.

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.

       The Morse code table in  the  cw(7,LOCAL)  man  page  is  provided  for
       reference  only.   If  learning  for  the  first time, you will be much
       better off learning by hearing the  characters  sent,  rather  than  by
       looking at the table.

       Other  programs  running in the system may interfere with the timing of
       the Morse code that cw is sending.  If this is a problem, either try to
       run  on  a quiescent system, or try running cw with nice(1L,C,1).  UNIX
       is not really designed for user-level programs to do the sort  of  fine
       timing  required  to  send  Morse code.  cw is therefore more sensitive
       than most programs to other system activity.

       cw uses system itimers for its internal timing.  On most UNIX  flavors,
       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.  But 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.

       To test itimer timing, first try

              X="PARIS PARIS PARIS PARIS "

              echo "$X" | time cw -w 4

       and note the elapsed time, which should be very close  to  one  minute.
       Next, try

              echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time cw -w 48

       The  elapsed time should be the same.  If it has increased, this is the
       effect  of  system  itimers  delaying  for  slightly  longer  than  the
       specified  period  (higher  WPM  rates make more itimer calls).  That’s
       itimers for you, not perfect for  this  job,  but  the  best  there  is
       without writing some, and perhaps a lot of, kernel code.

       Except  for  zero, which is silent, tone values lower than 10Hz may not
       sound at the expected pitch.

EXAMPLES

       Send a string of characters at 25 WPM, 700Hz, with no extra gaps:

              echo "UNIX CW SOUNDER" | cw -w 25 -t 700

       Send a string at varying speeds and tones on both the  sound  card  and
       the console speaker, specifying a system console device:

              echo  "%W12;%T400;400HZ  12WPM %W25;%T1500;1500HZ 25WPM" | cw -m
              -sb -d /dev/tty2

       Send C-cedilla, VA, and a report of the WPM setting, with extra spacing
       at half volume:

              echo "[CE] [VA] %>W" | cw -g 10 -v 50

ERRORS AND OMISSIONS

       Cut  numbers  are  not  provided,  though they can be emulated, up to a
       point, by pre-filtering.

       An output to an optional external device, for example, keying a line on
       the parallel port, or a serial line, might also be useful.

SEE ALSO

       Man    pages    for    cw(7,LOCAL),   cwlib(3,LOCAL),   cwgen(1,LOCAL),
       cwcp(1,LOCAL), and xcwcp(1,LOCAL).