1CW(1)                       General Commands Manual                      CW(1)
2
3
4

NAME

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

SYNOPSIS

9       cw     [-s --system=SYSTEM]     [-d --device=DEVICE]     [-w --wpm=WPM]
10       [-t --tone=HZ]   [-v --volume=PERCENT]   [-g --gap=GAP]   [-k --weight‐
11       ing=WEIGHT]       [-e --noecho]   [-m --nomessages]   [-c --nocommands]
12       [-o --nocombinations] [-p --nocomments] [-f --infile=FILE]  [-h --help]
13       [-V --version]
14
15       cw  installed on GNU/Linux systems understands both short form and long
16       form command line options.  cw installed on other operating systems may
17       understand only the short form options.
18
19       There are no mandatory options.
20
21       Options  may  be predefined in the environment variable CW_OPTIONS.  If
22       defined, these options are used first; command line options take prece‐
23       dence.
24

DESCRIPTION

26       cw  reads  characters  from  an input file, or from standard input, and
27       sounds each valid character as Morse code on either  the  system  sound
28       card,  or  the system console speaker.  After it sounds a character, cw
29       echoes it to standard output.  The input stream  can  contain  embedded
30       command  strings.   These  change the parameters used when sounding the
31       Morse code.  cw reports any errors in  embedded  commands  on  standard
32       error.
33
34       Use 'Ctrl+D' key combination to exit cw.
35
36   COMMAND LINE OPTIONS
37       cw  understands  the  following  command  line  options.  The long form
38       options may not be available in non-LINUX versions.
39
40       -s, --system=SYSTEM
41              Specifies the way that cw generates tones.   Valid  values  are:
42              null  for  no tones, just timings, console for tones through the
43              console speaker, alsa for tones  generated  through  the  system
44              sound  card  using  ALSA  sound  system, oss for tones generated
45              through system sound card using OSS sound system, pulseaudio for
46              tones generated through system sound card using PulseAudio sound
47              system, soundcard for tones generated through the  system  sound
48              card, but without explicit selection of sound system. These val‐
49              ues can be shortened to 'n', 'c', 'a', 'o', 'p', or 's', respec‐
50              tively.  The  default  value  is  'pulseaudio'  (on systems with
51              PulseAudio installed), followed by 'oss'.
52
53       -d, --device=DEVICE
54              Specifies the device file to open for generating  a  sound.   cw
55              will  use  default  device  if  none  is  specified. The default
56              devices are: /dev/console for sound  produced  through  console,
57              default  for ALSA sound system, /dev/audio for OSS sound system,
58              a default device for PulseAudio sound system.  See also NOTES ON
59              USING A SOUND CARD below.
60
61       -w, --wpm=WPM
62              Sets  the  initial sending speed in words per minute.  The value
63              must be between 4 and 60.  The default value is 12 WPM.
64
65       -t, --tone=HZ
66              Sets the initial sounder  pitch  in  Hz.   This  value  must  be
67              between 0 and 4,000.  A value of 0 selects silent operation, and
68              can be used for timing checks or  other  testing.   The  default
69              value is 800Hz,
70
71       -v, --volume=PERCENT
72              Sets  the  initial sending volume, as a percentage of full scale
73              volume.  The value must be between 0 and 100.  The default value
74              is  70 %.  Sound volumes work fully for sound card tones, but cw
75              cannot control the volume of tones from the console speaker.  In
76              this case, a volume of zero is silent, and all other volume val‐
77              ues are simply sounded.
78
79       -g, --gap=GAP
80              Sets the initial extra gap, in dot lengths,  between  characters
81              (the  'Farnsworth'  delay).   It  must be between 0 and 60.  The
82              default is 0.
83
84       -k, --weighting=WEIGHT
85              Sets the initial weighting, as a percentage of dot lengths.   It
86              must be between 20 and 80.  The default is 50.
87
88       -e, --noecho
89              Stops  cw  echoing  characters on standard output after they are
90              sounded.  The default is to have echoing on.
91
92       -m, --nomessages
93              Stops cw printing error messages on standard error.  The default
94              is to print messages.
95
96       -c, --nocommands
97              Stops  cw  from  interpreting  commands  embedded  in  the input
98              stream.  The default is to interpret embedded commands.
99
100       -o, --nocombinations
101              Stops cw from treating character strings bracketed by [...] as a
102              single  combination character.  The default is to honor combina‐
103              tions.
104
105       -p, --nocomments
106              Stops cw from treating character strings bracketed by  {...}  as
107              'comments'.   Characters  inside  these braces will be echoed to
108              standard output, but not sounded.  When comments are being  hon‐
109              ored,  any  embedded commands inside the braces will be ignored.
110              The default is to honor comments.
111
112       -f, --infile=FILE
113              Specifies a text file that cw can read to configure its practice
114              text.
115
116       -h, --help
117              Prints short help message.
118
119       -V, --version
120              Prints information about program's version, authors and license.
121
122   SOUNDING CHARACTERS
123       cw reads characters, one at a time, from its standard input or from its
124       input file.  Lowercase letters are converted internally  to  uppercase.
125       The following list shows the valid IS0 8859-1 (Latin-1) characters that
126       can be sounded by cw:
127
128              ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_@ and space
129
130       In addition, the program also understands the following ISO 8859-1  and
131       ISO 8859-2 accented characters:
132
133              ÜÄÇÖÉÈÀÑŞ (S with cedilla), Ž (Z with caron/hacek),
134
135       and accepts the following as single character forms of common procedur‐
136       al signals:
137
138              <>!&^~
139
140       See cw(7,LOCAL) for more information on the above characters and  Morse
141       code.
142
143       If  cw receives a character not in this set, it prints an error message
144       '?c', where c is the error character.  The only exceptions to this  may
145       be  the cw command escape character '%', the combination start and stop
146       characters '[' and ']', and the comment start and stop  characters  '{'
147       and '}'.  See EMBEDDED COMMANDS and MORSE CODE COMBINATIONS below.
148
149   EMBEDDED COMMANDS
150       cw  recognizes  special  sequences in the input stream as embedded com‐
151       mands.  These commands alter the parameters of the cw while it is  run‐
152       ning,  or  query current values.  All commands are prefixed by the com‐
153       mand escape character '%', and those which set a value end with a semi‐
154       colon.
155
156       The format of an embedded command to change a parameter value is
157
158              %Cvalue;
159
160       where  C  is a command letter indicating what action cw is to take, and
161       value is the argument or value for the command.
162
163       Valid command letters are
164
165       T      Sets the tone pitch used to sound a character.
166
167       W      Sets the sending speed.
168
169       G      Sets the 'Farnsworth' gap between characters.
170
171       K      Sets the weighting.
172
173       E      Disables or re-enables echoing of sent  characters  on  standard
174              output.
175
176       M      Disables or re-enables error messages on standard error.
177
178       S      Disables or re-enables speaker tone generation.
179
180       C      Disables  processing  of embedded commands.  Note that once dis‐
181              abled, this command cannot re-enable them.
182
183       O      Disables or re-enables recognition of [...]  character  combina‐
184              tions.
185
186       P      Disables or re-enables recognition of {...} comments.  When com‐
187              ments are being recognized, any character after an  opening  '{'
188              and  before  any  closing '}' will be echoed to standard output,
189              but will not be sounded, or have any other effect.
190
191       For example, the embedded command sequence
192
193              %W25;%T1200;
194
195       will set cw to a speed of 25 WPM, and a tone pitch of 1200Hz.
196
197       The 'T', 'W', 'G', and 'A' commands take values along with the command.
198       The  limits  on  values given for embedded commands are the same as the
199       limits available for command line options, detailed above.
200
201       The 'E', 'M', 'S', 'C' and 'O' commands are flags, and treat a value of
202       zero  as  clear,  and  any  other  value  as set.  So, for example, the
203       sequence
204
205              %M0;%C0;
206
207       will turn off error messages, and  then  turn  off  the  processing  of
208       embedded commands.
209
210       If a parameter is set successfully, cw reports the new setting on stan‐
211       dard error (except if no error  messages  is  set).   If  an  error  is
212       detected  in an embedded command, cw reports an error.  For the formats
213       of error messages see the MESSAGE FORMATS section below.
214
215       The current values of parameters within cw may be queried, as  well  as
216       set.  The command format
217
218              %?C
219
220       queries  the  value  of  the parameter normally set with command C.  cw
221       reports the current value on standard error, using the same  format  as
222       when new values are set.
223
224       The  current  values  of  parameters within cw may also be requested as
225       output in Morse code.  The command format
226
227              %>C
228
229       will generate Morse output reporting the value of  the  parameter  nor‐
230       mally set with command C.
231
232       If  embedded  commands  are disabled, '%' characters are treated as any
233       other (in this case, invalid) input character.
234
235       Once processing of embedded commands has been switched off, any command
236       to  switch this feature back on will not be recognized.  That is, after
237       '%C0;', an '%C1;' will not be recognized.
238
239       There is one additional command, and that is '%Q'.  This command closes
240       all open files and terminates cw.  Any characters after this command in
241       the input stream will be lost.
242
243       The file cw.h provides a full set of definitions for the commands, spe‐
244       cial characters, and status codes of cw.
245
246   MESSAGE FORMATS
247       Where  a parameter value is set correctly with an embedded command, the
248       message format
249
250              =Cvalue
251
252       is returned.  C is the command used, and value is the new value.
253
254       If an invalid value is supplied for a parameter in an embedded command,
255       a message
256
257              ?Cvalue
258
259       is returned.
260
261       Where an invalid command is encountered, the message format
262
263              ?%C
264
265       is used.  For an invalid query, the message is
266
267              ??C
268
269       and for an invalid request for a parameter in Morse code the message is
270
271              ?>C
272
273       A  character in the input stream that cannot be sounded produces a mes‐
274       sage
275
276              ?C
277
278       These messages are not intended to be user-friendly, but  are  designed
279       to  be  easily  and quickly interpreted by another program.  Similarly,
280       the format of embedded commands is more  computer-friendly  than  user-
281       friendly.
282
283       If  error messages are disabled, no messages of any type are printed on
284       standard error.
285
286   MORSE CODE COMBINATIONS
287       The standard set of characters offered by cw may not be sufficient  for
288       some  purposes.  For example, some international characters do not have
289       equivalent ISO 8859-1 and ISO 8859-2 that cw can sound directly.
290
291       To help in sounding such characters, cw offers the ability to form com‐
292       bination  characters by placing individual character components between
293       [...] brackets.  Cw sounds characters inside a combination without  the
294       usual  gap between them.  In this way, any missing character in the set
295       can be built.
296
297       For example
298
299              [VA]
300
301       is one way to form the VA procedural signal, though
302
303              [SK]
304
305       works just as well.  The eight-dot error signal can be sounded with
306
307              [HSE]
308
309       or the C-cedilla in international Morse code with
310
311              [CE]
312
313       There can be as many valid letters,  numbers,  or  figures  inside  the
314       [...]   brackets as required.  For example, an alternative way of send‐
315       ing the error signal could be
316
317              [EEEEEEEE]
318
319       Finally, three alternative ways of sending 73 might be
320
321              [TTEEE][EEETT]
322              [TDE][EUT]
323              [GEE][VT]
324
325       Embedded commands may be placed inside [...] combinations if  required.
326       Combinations do not nest.
327
328       This  feature  can be disabled by using the -O or --nocombinations com‐
329       mand line flags, or with the 'O' embedded command.  If combinations are
330       disabled,  '['  and  ']'  characters are treated as any other (invalid)
331       input character.
332
333   NOTES ON USING A SOUND CARD
334       By default, cw tries to open default PulseAudio. If  PulseAudio  server
335       is  not  accessible, cw tries to open OSS device "/dev/audio" to access
336       the system sound card.  This is generally the correct  device  to  use,
337       but for systems with special requirements, or those with multiple sound
338       cards, the option -d or --device, combined with -s or --system  can  be
339       used  to specify the device and audio system for sound card access.  If
340       the sound card device cannot be set up, cw prints the error message
341
342              cannot set up soundcard sound
343
344       and exits.
345
346       Sound card devices, when opened through OSS sound system,  are  usually
347       single-access  devices, so that when one process has opened the device,
348       other processes are prevented from using it. In such cases cw  will  of
349       course  conflict  with  any other programs that expect exclusive use of
350       the system sound card (for example, MP3 players).  If cw finds that the
351       sound card is already busy, it prints the error message
352
353              open /dev/audio: Device or resource busy
354
355       and exits.
356
357       The  sound  card  device is not used if cw is only sending tones on the
358       console speaker.
359
360   AUDIO OUTPUT - DEFAULTS AND SELECTION
361       cw first tries to access sound  card  using  PulseAudio  sound  system,
362       using  default  device  name,  unless user specifies other audio device
363       with option -d or --device.
364
365       cw then tries to access sound card using OSS audio system  and  default
366       OSS audio device name ('/dev/audio'), unless user specifies other audio
367       device with option -d or --device.
368
369       If opening soundcard through OSS fails, cw tries to  access  the  sound
370       card  using  ALSA  audio  system,  and  default  ALSA audio device name
371       ('default'), unless user specifies other audio device with option -d or
372       --device.
373
374       If opening soundcard through ALSA also fails, cw tries to access system
375       console buzzer using default buzzer device '/dev/console', unless  user
376       specifies other audio device with option -d or --device.
377
378       It  is  very  common  that in order to access the console buzzer device
379       user has to have root privileges.  For that reason trying to open  con‐
380       sole  buzzer almost always fails.  This is not a program's bug, this is
381       a result of operating system's restrictions.  Making cw an suid  binary
382       bypasses  this  restriction.  The program does not fork() or exec(), so
383       making it suid should be relatively safe.  Note however that this prac‐
384       tice is discouraged for security reasons.
385
386       As  stated,  user can tell cw which device to use, using -d or --device
387       option.  Which device files are suitable will depend on which operating
388       system  is running, which system user ID runs cw, and which user groups
389       user belongs to.
390

NOTES

392       Despite the fact that this  manual  page  constantly  and  consistently
393       refers to Morse code elements as dots and dashes, DO NOT think in these
394       terms when trying to learn Morse code.  Always think of them as  'dit's
395       and 'dah's.
396
397       The Morse code table in the cw(7,LOCAL) man page is provided for refer‐
398       ence only.  If learning for the first time, you will be much better off
399       learning  by hearing the characters sent, rather than by looking at the
400       table.
401
402       Other programs running in the system may interfere with the  timing  of
403       the Morse code that cw is sending.  If this is a problem, either try to
404       run on a quiescent system, or try running cw with  nice(1L,C,1).   UNIX
405       is  not  really designed for user-level programs to do the sort of fine
406       timing required to send Morse code.  cw  is  therefore  more  sensitive
407       than most programs to other system activity.
408
409       cw  uses system itimers for its internal timing.  On most UNIX flavors,
410       itimers are not guaranteed to signal a program exactly at the specified
411       time,  and they generally offer a resolution only as good as the normal
412       system 'clock tick' resolution.  An itimer SIGALRM usually falls  on  a
413       system clock tick, making it accurate to no better than 10mS on a typi‐
414       cal 100Hz kernel.
415
416       The effect of this is that an itimer period is generally either exactly
417       as  specified,  or,  more  likely, slightly longer.  At higher WPM set‐
418       tings, the cumulative effect of this affects timing  accuracy,  because
419       at  higher  speeds,  there  are fewer 10mS clock ticks in a dot period.
420       For example, at 12 WPM, the dot length is 100mS, enough to contain five
421       kernel clock ticks.  But at 60 WPM, the dot length is 20mS, or just two
422       kernel clock ticks.  So at higher speeds, the effect of itimer  resolu‐
423       tions becomes more pronounced.
424
425       To test itimer timing, first try
426
427              X="PARIS PARIS PARIS PARIS "
428
429              echo "$X" | time cw -w 4
430
431       and  note  the  elapsed time, which should be very close to one minute.
432       Next, try
433
434              echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time cw -w 48
435
436       The elapsed time should be the same.  If it has increased, this is  the
437       effect  of  system itimers delaying for slightly longer than the speci‐
438       fied period (higher WPM rates make more itimer calls).  That's  itimers
439       for  you, not perfect for this job, but the best there is without writ‐
440       ing some, and perhaps a lot of, kernel code.
441
442       Except for zero, which is silent, tone values lower than 10Hz  may  not
443       sound at the expected pitch.
444

EXAMPLES

446       Send a string of characters at 25 WPM, 700Hz, with no extra gaps:
447
448              echo "UNIX CW SOUNDER" | cw -w 25 -t 700
449
450       Send a string at varying speeds and tones on the console speaker, spec‐
451       ifying a system console device:
452
453              echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" |  cw  -m
454              -sc -d /dev/tty2
455
456       Send C-cedilla, VA, and a report of the WPM setting, with extra spacing
457       at half volume:
458
459              echo "[CE] [VA] %>W" | cw -g 10 -v 50
460

ERRORS AND OMISSIONS

462       Cut numbers are not provided, though they can  be  emulated,  up  to  a
463       point, by pre-filtering.
464
465       An output to an optional external device, for example, keying a line on
466       the parallel port, or a serial line, might also be useful.
467

SEE ALSO

469       Man   pages   for    cw(7,LOCAL),    libcw(3,LOCAL),    cwgen(1,LOCAL),
470       cwcp(1,LOCAL), and xcwcp(1,LOCAL).
471
472
473
474cw ver. 3.5.1                  CW Tutor Package                          CW(1)
Impressum