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 --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 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 There are no mandatory options.
20 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
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 Use 'Ctrl+D' key combination to exit cw.
35 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 -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 -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 -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 -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 -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 -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 -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 -e, --noecho
89 Stops cw echoing characters on standard output after they are
90 sounded. The default is to have echoing on.
91 -m, --nomessages
93 Stops cw printing error messages on standard error. The default
94 is to print messages.
95 -c, --nocommands
97 Stops cw from interpreting commands embedded in the input
98 stream. The default is to interpret embedded commands.
99 -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 -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 -f, --infile=FILE
113 Specifies a text file that cw can read to configure its practice
114 text.
115 -h, --help
117 Prints short help message.
118 -V, --version
120 Prints information about program's version, authors and license.
121 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 ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_@ and space
129 In addition, the program also understands the following ISO 8859-1 and
131 ISO 8859-2 accented characters:
132 ÜÄÇÖÉÈÀÑŞ (S with cedilla), Ž (Z with caron/hacek),
134 and accepts the following as single character forms of common procedur‐
136 al signals:
137 <>!&^~
139 See cw(7,LOCAL) for more information on the above characters and Morse
141 code.
142 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 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 The format of an embedded command to change a parameter value is
157 %Cvalue;
159 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 Valid command letters are
164 T Sets the tone pitch used to sound a character.
166 W Sets the sending speed.
168 G Sets the 'Farnsworth' gap between characters.
170 K Sets the weighting.
172 E Disables or re-enables echoing of sent characters on standard
174 output.
175 M Disables or re-enables error messages on standard error.
177 S Disables or re-enables speaker tone generation.
179 C Disables processing of embedded commands. Note that once dis‐
181 abled, this command cannot re-enable them.
182 O Disables or re-enables recognition of [...] character combina‐
184 tions.
185 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 For example, the embedded command sequence
192 %W25;%T1200;
194 will set cw to a speed of 25 WPM, and a tone pitch of 1200Hz.
196 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 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 %M0;%C0;
206 will turn off error messages, and then turn off the processing of
208 embedded commands.
209 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 The current values of parameters within cw may be queried, as well as
216 set. The command format
217 %?C
219 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 The current values of parameters within cw may also be requested as
225 output in Morse code. The command format
226 %>C
228 will generate Morse output reporting the value of the parameter nor‐
230 mally set with command C.
231 If embedded commands are disabled, '%' characters are treated as any
233 other (in this case, invalid) input character.
234 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 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 The file cw.h provides a full set of definitions for the commands, spe‐
244 cial characters, and status codes of cw.
245 MESSAGE FORMATS
247 Where a parameter value is set correctly with an embedded command, the
248 message format
249 =Cvalue
251 is returned. C is the command used, and value is the new value.
253 If an invalid value is supplied for a parameter in an embedded command,
255 a message
256 ?Cvalue
258 is returned.
260 Where an invalid command is encountered, the message format
262 ?%C
264 is used. For an invalid query, the message is
266 ??C
268 and for an invalid request for a parameter in Morse code the message is
270 ?>C
272 A character in the input stream that cannot be sounded produces a mes‐
274 sage
275 ?C
277 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 If error messages are disabled, no messages of any type are printed on
284 standard error.
285 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 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 For example
298 [VA]
300 is one way to form the VA procedural signal, though
302 [SK]
304 works just as well. The eight-dot error signal can be sounded with
306 [HSE]
308 or the C-cedilla in international Morse code with
310 [CE]
312 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 [EEEEEEEE]
318 Finally, three alternative ways of sending 73 might be
320 [TTEEE][EEETT]
322 [TDE][EUT]
323 [GEE][VT]
324 Embedded commands may be placed inside [...] combinations if required.
326 Combinations do not nest.
327 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 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 cannot set up soundcard sound
343 and exits.
345 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 open /dev/audio: Device or resource busy
354 and exits.
356 The sound card device is not used if cw is only sending tones on the
358 console speaker.
359 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 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 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 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 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 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
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 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 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 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 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 To test itimer timing, first try
426 X="PARIS PARIS PARIS PARIS "
428 echo "$X" | time cw -w 4
430 and note the elapsed time, which should be very close to one minute.
432 Next, try
433 echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time cw -w 48
435 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 Except for zero, which is silent, tone values lower than 10Hz may not
443 sound at the expected pitch.
444
446 Send a string of characters at 25 WPM, 700Hz, with no extra gaps:
447 echo "UNIX CW SOUNDER" | cw -w 25 -t 700
449 Send a string at varying speeds and tones on the console speaker, spec‐
451 ifying a system console device:
452 echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" | cw -m
454 -sc -d /dev/tty2
455 Send C-cedilla, VA, and a report of the WPM setting, with extra spacing
457 at half volume:
458 echo "[CE] [VA] %>W" | cw -g 10 -v 50
460
462 Cut numbers are not provided, though they can be emulated, up to a
463 point, by pre-filtering.
464 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
469 Man pages for cw(7,LOCAL), libcw(3,LOCAL), cwgen(1,LOCAL),
470 cwcp(1,LOCAL), and xcwcp(1,LOCAL).
471cw ver. 3.5.1 CW Tutor Package CW(1)