1CW(1) General Commands Manual CW(1)
2
6 cw - sound characters as Morse code on the soundcard or console speaker
7
9 cw [-s sound] [--sound=sound] [-x sdevice] [--sdevice=sdevice] [-y mde‐
10 vice] [--mdevice=mdevice] [-d cdevice] [--cdevice=cdevice] [-f file]
11 [--file=file] [-w WPM] [--wpm=WPM] [-t tone] [--tone=tone] [--hz=tone]
12 [-v volume] [--volume=volume] [-g gap] [--gap=gap] [-k weighting]
13 [--weighting=weighting] [-e] [--noecho] [-m] [--nomessages] [-c]
14 [--nocommands] [-o] [--nocombinations] [-p] [--nocomments]
15 cw also accepts the -h, --help, -V and --version options.
17 The LINUX version understands both short form and long form command
19 line options. Other versions may understand only the short form
20 options.
21 Options may be predefined in the environment variable CW_OPTIONS. If
23 defined, these options are used first; command line options take prece‐
24 dence.
25
27 cw reads characters from an input file, or from standard input, and
28 sounds each valid character as Morse code on either the system sound
29 card, the system console speaker, or both. After it sounds a charac‐
30 ter, cw echoes it to standard output. The input stream can contain
31 embedded command strings. These change the parameters used when sound‐
32 ing the Morse code. cw reports any errors in embedded commands on
33 standard error.
34 COMMAND LINE OPTIONS
36 cw understands the following command line options. The long form
37 options may not be available in non-LINUX versions.
38 -s, --sound
40 Specifies the way that cw generates tones. Valid values are
41 'soundcard' for tones through the system sound card, 'console'
42 for tones through the console speaker, or 'both'. These may be
43 shortened to 's', 'c', or 'b'. The default value is 'sound‐
44 card'.
45 -x, --sdevice
47 Specifies the device file to open for access to the sound card.
48 The default device is /dev/audio, and this is generally the cor‐
49 rect device on most systems. See NOTES ON USING A SOUND CARD
50 below. This option is invalid if cw is generating tones only on
51 the console.
52 -y, --mdevice
54 Specifies the device file to open for access to the sound mixer.
55 The default device is /dev/mixer. See NOTES ON USING A SOUND
56 CARD below. This option is invalid if cw is generating tones
57 only on the console.
58 -d, --cdevice
60 Specifies the device file to open for sound using the console
61 speaker. The default device here is /dev/console, although in
62 general it is likely to be necessary to provide a suitable value
63 for this option if console sound is selected. The value should
64 be a console device file, capable of KIOCSOUND. See SELECTING
65 SUITABLE SOUND DEVICE FILES below. This option is invalid if cw
66 is generating tones only on the soundcard.
67 -f, --file
69 Specifies the input file to open. The default input file is
70 standard input.
71 -w, --wpm
73 Sets the initial sending speed in words per minute. The value
74 must be between 4 and 60. The default value is 12 WPM.
75 -t, --hz, --tone
77 Sets the initial sounder pitch in Hz. This value must be
78 between 0 and 4,000. A value of 0 selects silent operation, and
79 can be used for timing checks or other testing. The default
80 value is 800Hz,
81 -v, --volume
83 Sets the initial sending volume, as a percentage. The value
84 must be between 0 and 100. The default value is 70 %. Sound
85 volumes work fully for sound card tones, but cw cannot control
86 the volume of tones from the console speaker. In this case, a
87 volume of zero is silent, and all other volume values are simply
88 sounded.
89 -g, --gap
91 Sets the initial extra gap, in dot lengths, between characters
92 (the 'Farnsworth' delay). It must be between 0 and 60. The
93 default is 0.
94 -k, --weighting
96 Sets the initial weighting, as a percentage of dot lengths. It
97 must be between 20 and 80. The default is 50.
98 -e, --noecho
100 Stops cw echoing characters on standard output after they are
101 sounded. The default is to have echoing on.
102 -m, --nomessages
104 Stops cw printing error messages on standard error. The default
105 is to print messages.
106 -c, --nocommands
108 Stops cw from interpreting commands embedded in the input
109 stream. The default is to interpret embedded commands.
110 -o, --nocombinations
112 Stops cw from treating character strings bracketed by [...] as a
113 single combination character. The default is to honor combina‐
114 tions.
115 -p, --nocomments
117 Stops cw from treating character strings bracketed by {...} as
118 'comments'. Characters inside these braces will be echoed to
119 standard output, but not sounded. When comments are being hon‐
120 ored, any embedded commands inside the braces will be ignored.
121 The default is to honor comments.
122 SOUNDING CHARACTERS
124 cw reads characters, one at a time, from its standard input or from its
125 input file. Lowercase letters are converted internally to uppercase.
126 The following list shows the valid IS0 8859-1 (Latin-1) characters that
127 can be sounded by cw:
128 ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_@ and space
130 In addition, the program also understands the following ISO 8859-1 and
132 ISO 8859-2 accented characters:
133 ÜÄÇÖÉČŔŃŞŽ
135 and accepts the following as single character forms of common procedur‐
137 al signals:
138 <>!&^~
140 See cw(7,LOCAL) for more information on the above characters and Morse
142 code.
143 If cw receives a character not in this set, it prints an error message
145 '?c', where c is the error character. The only exceptions to this may
146 be the cw command escape character '%', the combination start and stop
147 characters '[' and ']', and the comment start and stop characters '{'
148 and '}'. See EMBEDDED COMMANDS and MORSE CODE COMBINATIONS below.
149 EMBEDDED COMMANDS
151 cw recognizes special sequences in the input stream as embedded com‐
152 mands. These commands alter the parameters of the cw while it is run‐
153 ning, or query current values. All commands are prefixed by the com‐
154 mand escape character '%', and those which set a value end with a semi‐
155 colon.
156 The format of an embedded command to change a parameter value is
158 %Cvalue;
160 where C is a command letter indicating what action cw is to take, and
162 value is the argument or value for the command.
163 Valid command letters are
165 T Sets the tone pitch used to sound a character.
167 W Sets the sending speed.
169 G Sets the 'Farnsworth' gap between characters.
171 K Sets the weighting.
173 E Disables or re-enables echoing of sent characters on standard
175 output.
176 M Disables or re-enables error messages on standard error.
178 S Disables or re-enables speaker tone generation.
180 C Disables processing of embedded commands. Note that once dis‐
182 abled, this command cannot re-enable them.
183 O Disables or re-enables recognition of [...] character combina‐
185 tions.
186 P Disables or re-enables recognition of {...} comments. When com‐
188 ments are being recognized, any character after an opening '{'
189 and before any closing '}' will be echoed to standard output,
190 but will not be sounded, or have any other effect.
191 For example, the embedded command sequence
193 %W25;%T1200;
195 will set cw to a speed of 25 WPM, and a tone pitch of 1200Hz.
197 The 'T', 'W', 'G', and 'A' commands take values along with the command.
199 The limits on values given for embedded commands are the same as the
200 limits available for command line options, detailed above.
201 The 'E', 'M', 'S', 'C' and 'O' commands are flags, and treat a value of
203 zero as clear, and any other value as set. So, for example, the
204 sequence
205 %M0;%C0;
207 will turn off error messages, and then turn off the processing of
209 embedded commands.
210 If a parameter is set successfully, cw reports the new setting on stan‐
212 dard error (except if no error messages is set). If an error is
213 detected in an embedded command, cw reports an error. For the formats
214 of error messages see the MESSAGE FORMATS section below.
215 The current values of parameters within cw may be queried, as well as
217 set. The command format
218 %?C
220 queries the value of the parameter normally set with command C. cw
222 reports the current value on standard error, using the same format as
223 when new values are set.
224 The current values of parameters within cw may also be requested as
226 output in Morse code. The command format
227 %>C
229 will generate Morse output reporting the value of the parameter nor‐
231 mally set with command C.
232 If embedded commands are disabled, '%' characters are treated as any
234 other (in this case, invalid) input character.
235 Once processing of embedded commands has been switched off, any command
237 to switch this feature back on will not be recognized. That is, after
238 '%C0;', an '%C1;' will not be recognized.
239 There is one additional command, and that is '%Q'. This command closes
241 all open files and terminates cw. Any characters after this command in
242 the input stream will be lost.
243 The file cw.h provides a full set of definitions for the commands, spe‐
245 cial characters, and status codes of cw.
246 MESSAGE FORMATS
248 Where a parameter value is set correctly with an embedded command, the
249 message format
250 =Cvalue
252 is returned. C is the command used, and value is the new value.
254 If an invalid value is supplied for a parameter in an embedded command,
256 a message
257 ?Cvalue
259 is returned.
261 Where an invalid command is encountered, the message format
263 ?%C
265 is used. For an invalid query, the message is
267 ??C
269 and for an invalid request for a parameter in Morse code the message is
271 ?>C
273 A character in the input stream that cannot be sounded produces a mes‐
275 sage
276 ?C
278 These messages are not intended to be user-friendly, but are designed
280 to be easily and quickly interpreted by another program. Similarly,
281 the format of embedded commands is more computer-friendly than user-
282 friendly.
283 If error messages are disabled, no messages of any type are printed on
285 standard error.
286 MORSE CODE COMBINATIONS
288 The standard set of characters offered by cw may not be sufficient for
289 some purposes. For example, some international characters do not have
290 equivalent ISO 8859-1 and ISO 8859-2 that cw can sound directly.
291 To help in sounding such characters, cw offers the ability to form com‐
293 bination characters by placing individual character components between
294 [...] brackets. Cw sounds characters inside a combination without the
295 usual gap between them. In this way, any missing character in the set
296 can be built.
297 For example
299 [VA]
301 is one way to form the VA procedural signal, though
303 [SK]
305 works just as well. The eight-dot error signal can be sounded with
307 [HSE]
309 or the C-cedilla in international Morse code with
311 [CE]
313 There can be as many valid letters, numbers, or figures inside the
315 [...] brackets as required. For example, an alternative way of send‐
316 ing the error signal could be
317 [EEEEEEEE]
319 Finally, three alternative ways of sending 73 might be
321 [TTEEE][EEETT]
323 [TDE][EUT]
324 [GEE][VT]
325 Embedded commands may be placed inside [...] combinations if required.
327 Combinations do not nest.
328 This feature can be disabled by using the -O or --nocombinations com‐
330 mand line flags, or with the 'O' embedded command. If combinations are
331 disabled, '[' and ']' characters are treated as any other (invalid)
332 input character.
333 NOTES ON USING A SOUND CARD
335 By default, cw uses the sound device "/dev/audio" to access the system
336 sound card. This is generally the correct device to use, but for sys‐
337 tems with special requirements, or those with multiple sound cards, the
338 option -x or --sdevice can be used to specify the device for sound card
339 access. If the sound card device cannot be set up, cw prints the error
340 message
341 cannot set up soundcard sound
343 and exits.
345 Sound card devices are usually single-access devices, so that when one
347 process has opened the device, other processes are prevented from using
348 it. If cw finds that the sound card is busy, it prints the error mes‐
349 sage
350 open /dev/audio: Device or resource busy
352 but continues to retry on each new tone until it can access the device.
354 Once it has control of the sound card, cw will only use it as long as
355 it has Morse code tones to sound. It will close the device during
356 pauses in output, to allow other programs to use it.
357 The main sound card device will often allow cw to control tone volumes
359 directly, but where this is not possible, cw uses the mixer device
360 instead. By default, this is "/dev/mixer", but the device can be spec‐
361 ified with the -y or --mdevice options. In general, as with the main
362 sound card device, the default mixer device is usually the correct one
363 to use.
364 The mixer device is only used if the sound card does not allow volume
366 control through the main sound card device.
367 cw will of course conflict with any other programs that expect exclu‐
369 sive use of the system sound card (for example, MP3 players).
370 The sound card device is not used if cw is only sending tones on the
372 console speaker.
373 SELECTING SUITABLE SOUND DEVICE FILES
375 When cw sounds Morse code on the UNIX console speaker, it uses the
376 KIOCSOUND ioctl. By default, it will try to use the device "/dev/con‐
377 sole", unless the -d or --cdevice option is used. If the device
378 refuses to create tones, cw prints the error message
379 cannot set up console sound
381 and exits.
383 If the default device is not available, or if cw has no permissions to
385 use it, cw will need to be told which device to use. Which device
386 files are suitable will depend on which operating system is running,
387 and which system user ID runs cw. They must however be console multi‐
388 screen devices, for example /dev/tty1 and up on LINUX.
389 For console sound on LINUX, it is normally possible to run cw as supe‐
391 ruser, with the default /dev/console as the sound device; this combina‐
392 tion will usually work. Unless running as superuser, cw won't have the
393 necessary permission to access a 'foreign' tty. Making cw an suid
394 binary avoids this problem. The program does not fork() or exec(), so
395 making it suid should be relatively safe.
396 There is no need to worry about console sound devices if cw is only
398 sending tones on the system sound card.
399
401 Despite the fact that this manual page constantly and consistently
402 refers to Morse code elements as dots and dashes, DO NOT think in these
403 terms when trying to learn Morse code. Always think of them as 'dit's
404 and 'dah's.
405 The Morse code table in the cw(7,LOCAL) man page is provided for refer‐
407 ence only. If learning for the first time, you will be much better off
408 learning by hearing the characters sent, rather than by looking at the
409 table.
410 Other programs running in the system may interfere with the timing of
412 the Morse code that cw is sending. If this is a problem, either try to
413 run on a quiescent system, or try running cw with nice(1L,C,1). UNIX
414 is not really designed for user-level programs to do the sort of fine
415 timing required to send Morse code. cw is therefore more sensitive
416 than most programs to other system activity.
417 cw uses system itimers for its internal timing. On most UNIX flavors,
419 itimers are not guaranteed to signal a program exactly at the specified
420 time, and they generally offer a resolution only as good as the normal
421 system 'clock tick' resolution. An itimer SIGALRM usually falls on a
422 system clock tick, making it accurate to no better than 10mS on a typi‐
423 cal 100Hz kernel.
424 The effect of this is that an itimer period is generally either exactly
426 as specified, or, more likely, slightly longer. At higher WPM set‐
427 tings, the cumulative effect of this affects timing accuracy, because
428 at higher speeds, there are fewer 10mS clock ticks in a dot period.
429 For example, at 12 WPM, the dot length is 100mS, enough to contain five
430 kernel clock ticks. But at 60 WPM, the dot length is 20mS, or just two
431 kernel clock ticks. So at higher speeds, the effect of itimer resolu‐
432 tions becomes more pronounced.
433 To test itimer timing, first try
435 X="PARIS PARIS PARIS PARIS "
437 echo "$X" | time cw -w 4
439 and note the elapsed time, which should be very close to one minute.
441 Next, try
442 echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time cw -w 48
444 The elapsed time should be the same. If it has increased, this is the
446 effect of system itimers delaying for slightly longer than the speci‐
447 fied period (higher WPM rates make more itimer calls). That's itimers
448 for you, not perfect for this job, but the best there is without writ‐
449 ing some, and perhaps a lot of, kernel code.
450 Except for zero, which is silent, tone values lower than 10Hz may not
452 sound at the expected pitch.
453
455 Send a string of characters at 25 WPM, 700Hz, with no extra gaps:
456 echo "UNIX CW SOUNDER" | cw -w 25 -t 700
458 Send a string at varying speeds and tones on both the sound card and
460 the console speaker, specifying a system console device:
461 echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" | cw -m
463 -sb -d /dev/tty2
464 Send C-cedilla, VA, and a report of the WPM setting, with extra spacing
466 at half volume:
467 echo "[CE] [VA] %>W" | cw -g 10 -v 50
469
471 Cut numbers are not provided, though they can be emulated, up to a
472 point, by pre-filtering.
473 An output to an optional external device, for example, keying a line on
475 the parallel port, or a serial line, might also be useful.
476
478 Man pages for cw(7,LOCAL), cwlib(3,LOCAL), cwgen(1,LOCAL),
479 cwcp(1,LOCAL), and xcwcp(1,LOCAL).
480G0FRD CW Tutor Package CW(1)