NAME¶
cw - sound characters as Morse code on the soundcard or console speaker
SYNOPSIS¶
cw [-s --system=
SYSTEM] [-d --device=
DEVICE] [-w --wpm=
WPM] [-t --tone=
HZ]
[-v --volume=
PERCENT] [-g --gap=
GAP]
[-k --weighting=
WEIGHT] [-e --noecho]
[-m --nomessages] [-c --nocommands] [-o --nocombinations]
[-p --nocomments] [-f --infile=
FILE] [-h --help]
[-V --version]
cw installed on GNU/Linux systems understands both short form and long
form command line options.
cw installed on other operating systems may
understand only the short form options.
There are no mandatory 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, or
the system console speaker. 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.
Use 'Ctrl+D' key combination to exit
cw.
COMMAND LINE OPTIONS¶
cw understands the following command line options. The long form options
may not be available in non-LINUX versions.
- -s, --system=SYSTEM
- Specifies the way that cw generates tones. Valid values are:
null for no tones, just timings, console for tones through
the console speaker, alsa for tones generated through the system
sound card using ALSA sound system, oss for tones generated through
system sound card using OSS sound system, pulseaudio for tones
generated through system sound card using PulseAudio sound system,
soundcard for tones generated through the system sound card, but
without explicit selection of sound system. These values can be shortened
to 'n', 'c', 'a', 'o', 'p', or 's', respectively. The default value is
'pulseaudio' (on systems with PulseAudio installed), followed by
'oss'.
- -d, --device=DEVICE
- Specifies the device file to open for generating a sound. cw will
use default device if none is specified. The default devices are:
/dev/console for sound produced through console, default for
ALSA sound system, /dev/audio for OSS sound system, a default
device for PulseAudio sound system. See also NOTES ON USING A SOUND
CARD below.
- -w, --wpm=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, --tone=HZ
- 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=PERCENT
- Sets the initial sending volume, as a percentage of full scale volume. 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=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=WEIGHT
- 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.
- -f, --infile=FILE
- Specifies a text file that cw can read to configure its practice
text.
- -h, --help
- Prints short help message.
- -V, --version
- Prints information about program's version, authors and license.
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 caron/hacek),
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.
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 tries to open default PulseAudio. If PulseAudio server is
not accessible, cw tries to open OSS 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
-d or
--device, combined with
-s or
--system can be used to specify the device and audio system 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, when opened through OSS sound system, are usually
single-access devices, so that when one process has opened the device, other
processes are prevented from using it. In such cases
cw will of course
conflict with any other programs that expect exclusive use of the system sound
card (for example, MP3 players). If
cw finds that the sound card is
already busy, it prints the error message
- open /dev/audio: Device or resource busy
and exits.
The sound card device is not used if
cw is only sending tones on the
console speaker.
AUDIO OUTPUT - DEFAULTS AND SELECTION¶
cw first tries to access sound card using PulseAudio sound system, using
default device name, unless user specifies other audio device with option
-d or
--device.
cw then tries to access sound card using OSS audio system and default OSS
audio device name ('/dev/audio'), unless user specifies other audio device
with option
-d or
--device.
If opening soundcard through OSS fails,
cw tries to access the sound card
using ALSA audio system, and default ALSA audio device name ('default'),
unless user specifies other audio device with option
-d or
--device.
If opening soundcard through ALSA also fails,
cw tries to access system
console buzzer using default buzzer device '/dev/console', unless user
specifies other audio device with option
-d or
--device.
It is very common that in order to access the console buzzer device user has to
have root privileges. For that reason trying to open console buzzer almost
always fails. This is not a program's bug, this is a result of operating
system's restrictions. Making
cw an suid binary bypasses this
restriction. The program does not fork() or exec(), so making it suid should
be relatively safe. Note however that this practice is discouraged for
security reasons.
As stated, user can tell
cw which device to use, using
-d or
--device option. Which device files are suitable will depend on which
operating system is running, which system user ID runs
cw, and which
user groups user belongs to.
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 the console speaker, specifying a
system console device:
- echo "%W12;%T400;400HZ 12WPM %W25;%T1500;1500HZ 25WPM" | cw -m
-sc -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),
libcw(3,LOCAL),
cwgen(1,LOCAL),
cwcp(1,LOCAL), and
xcwcp(1,LOCAL).