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