NAME¶
cwcp - curses-based Morse tutor program
SYNOPSIS¶
cwcp [-s --system=
SYSTEM] [-d --device=
DEVICE] [-w --wpm=
WPM] [-t --tone=
HZ]
[-v --volume=
PERCENT] [-g --gap=
GAP]
[-k --weighting=
WEIGHT] [-T --time=
TIME] [-f,
--infile=
FILE] [-F, --outifile=
FILE] [-h --help]
[-V --version]
cwcp installed on GNU/Linux systems understands both short form and long
form command line options.
cwcp 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
CWCP_OPTIONS. If
defined, these options are used first; command line options take precedence.
DESCRIPTION¶
cwcp is a curses-based interactive Morse code tutor program. It allows
menu selection from a number of sending modes, and also permits character
sounding options, such as the tone pitch, and sending speed, to be varied from
the keyboard using a full-screen user interface.
COMMAND LINE OPTIONS¶
cwcp 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 cwcp 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'.
- -d, --device=DEVICE
- Specifies the device file to open for generating a sound. cwcp 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 cwcp 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.
- -T, --time=TIME
- Sets the initial practice time, in minutes. cwcp stops after
generating random Morse code for this period. The value must be between 1
and 99. The default is 15 minutes.
- -f, --infile=FILE
- Specifies a text file that cwcp can read to configure its practice
text. See CREATING CONFIGURATION FILES below.
- -F, --outfile=FILE
- Specifies a text file to which cwcp should write its current
practice text.
- -h, --help
- Prints short help message.
- -V, --version
- Prints information about program's version, authors and license.
USER INTERFACE¶
cwcp is a curses-based program that takes over the complete operation of
the terminal on which it is run. If colours are available on the terminal, it
will produce a colour interface.
The
cwcp screen is divided into several distinct areas:
- The Menu Selection window
- The Menu Selection window shows the main modes that cwcp offers.
Use the F10 and F11 or KEY_DOWN and KEY_UP
keys to select the mode. F9 or Return start sending, and
F9 again or Esc stop sending. Changing mode also stops
sending.
- The Morse Code Display window
- This window displays each Morse code character after it has been
sent.
- The Speed Control window
- The Speed window shows the current Morse code sending speed in words per
minute. Pressing the F2 or KEY_RIGHT keys increases the
speed; pressing the F1 or KEY_LEFT keys decreases the
speed.
- The Tone Control window
- This window shows the current Morse code tone pitch. Use the F4 or
KEY_HOME key to increase the pitch, and the F3 or
KEY_END key to decrease it. Values change in steps of 20Hz.
- The Volume Control window
- This window shows the current Morse code volume. Use the F6 key to
increase the volume, and the F5 key to decrease it. Values change
in steps of 1%. Note that cwcp cannot control the volume of the
console speaker, so the volume control only works effectively for tones
generated on the sound card.
- The Gap Control window
- This window shows the current additional 'Farnsworth' gaps to be appended
after each Morse code character is sounded. Use F8 to increase the
gap, and F7 to decrease it.
- The Time Control window
- This window shows the selected practice time. After generating Morse code
in a particular mode for this amount of time, cwcp stops
automatically. Use KEY_NPAGE to increase the time, and
KEY_PPAGE to decrease it. During sending, the value in this window
counts down to one, and after final minute of sending has elapsed,
cwcp stops sending. The timer operates like a microwave or kitchen
timer; it counts down on its own, but the time remaining can also be
altered manually while the timer operates.
The following keys vary the screen colours:
- { key
- Changes the foreground colour of the window boxes.
- } key
- Changes the background colour of the window boxes.
- [ key
- Changes the foreground colour of the window contents.
- ] key
- Changes the background colour of the window contents.
Eight screen colours are available for each: black, red, green, yellow, blue,
magenta, cyan, and white. Use a key to cycle round these colours for the
particular part of the display controlled by that key. On a change of colours,
the complete screen is repainted.
Use
Ctrl-L to repaint the complete screen, in case of screen corruption.
Use
Ctrl-V to clear the Morse Code Display Window. This command is
available only when
cwcp is not sending.
To leave
cwcp, press
F12 or
Ctrl-C, or select
Exit
on the mode menu.
All of the above command keys may be used while random characters are being
sent, and when keyboard input is being sent.
If function keys are not available on the terminal,
Ctrl-<key>
combinations can be used. On the top row of letter keys on the keyboard, the
keys
Ctrl-Q to
Ctrl-I may be used as alternatives for
F1
to
F8, and on the second row of letter keys,
Ctrl-A to
Ctrl-F as alternatives for
F9 to
F12. For
KEY_PPAGE and
KEY_NPAGE, use
Ctrl-O and
Ctrl-P.
RANDOM CHARACTERS AND WORDS¶
cwcp sends random characters in groups of five, with a space between each
group. After a period of sending, set in the
Time Control window,
cwcp stops automatically. It can also be stopped manually, before this
time period expires.
When sending random words,
cwcp sends the complete word, followed by a
space. Because short words are easier to copy without writing,
cwcp's
default dictionary contains only three, four, and five-letter words in its
random words list.
cwcp chooses at random from a list of around 3000 words in its default
dictionary. You can change this text using a configuration file, read at
startup. See
CREATING CONFIGURATION FILES below.
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,
cwcp 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
cwcp will of
course conflict with any other programs that expect exclusive use of the
system sound card (for example, MP3 players). If
cwcp 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
cwcp is only sending tones on the
console speaker.
AUDIO OUTPUT - DEFAULTS AND SELECTION¶
cwcp 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.
cwcp 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,
cwcp 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,
cwcp 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
cwcp 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
cwcp 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
cwcp, and which
user groups user belongs to.
CREATING CONFIGURATION FILES¶
cwcp contains a default set of modes and practice text that should be
enough to begin with. It can however read in a file at startup that
reconfigures these to provide different character groupings, word sets, and
other practice data.
To read a configuration file, use the
-f or
--infile command line
options. The file should introduce each
cwcp mode with a section header
in '[' ... ']' characters, followed by the practice text for that mode, with
elements separated by whitespace. Lines starting with a semicolon or hash are
treated as comments. For example
- ; Simple example mode
[ A to Z ]
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
cwcp will generate five character groups for modes whose elements are all
single characters, and treat other modes as having elements that are complete
words. As a starting point for customized modes,
cwcp will write its
default configuration to a file if given the undocumented
-# option,
for example "cwcp -# /tmp/cwcp.ini".
NOTES¶
cwcp owes its existence to the DOS Morse code tutor CP222C.EXE, by
VU2ZAP. CP222C.EXE seemed to offer the right range of facilities for learning
Morse code in a simple, easy-to-use, and compact package.
cwcp is very
much modeled on that DOS program, and should prove useful both for learning
the code, and for experienced CW users who want, or need, to improve their
receiving speed.
Curses may impose a delay when recognizing the
Esc key alone, as this
character is often the first of a sequence generated by a function key.
cwcp responds instantly to
F9.
The characters echoed in the Morse Code Display window may be ASCII
representations of Morse procedural signals; see the
cw(7,LOCAL) man
page for details.
HINTS ON LEARNING MORSE CODE¶
Here are a few hints and tips that may help with the process of learning Morse
code.
Firstly, do
NOT think of the elements as dots and dashes. Instead, think
of them as dits and dahs (so 'A' is di-dah). If you think of them in this way,
the process of translating sound into characters will be learned much more
easily.
Do not learn the characters from a table. Learn them by watching the groups
appear on the screen, and listening to the sounds produced as each is sent. In
the very initial stages, it may be beneficial if you can find a person to take
you through the first stages of recognizing characters.
Do not waste your time learning Morse code at 5 WPM. Set the speed to 12 or 15
WPM, but use extra spacing (the Gap window) to reduce the effective speed to
much lower - around four or five WPM
effective speed. This way, you
will learn the rhythm of the characters as they are sent, but still have
plenty of time between characters. As you practice, decrease the gap to zero.
Learn in stages. Start by learning the
EISH5 group, then progress down
through the menu as each group is mastered. The groups contain characters
which are in some way related, either by sound, or by type of character.
Once you have completed all the groups
EISH5 to
"'$(+:_ (or
23789 if you do not want to learn procedural signals yet), use the full
character set options, and the words and CW words options, to sharpen your
skill. If you have difficulties with particular characters, return to that
group and practice again with a smaller character set.
Resist the temptation to try to learn or improve your speed by copying off-air.
You will not know what speed you are working at, and much hand-sent Morse is
not perfectly formed. What you can gain off-air though is a general
'resilience', a tolerance for Morse code where the timing of individual
elements, or spacing between characters and words, is not 100% accurate.
If working to attain a particular speed for a test, always set the speed
slightly higher. For example, if aiming for 12 WPM, set the tutor speed to 14
or 15 WPM. This way, when you drop back to 12 WPM you will feel much more
relaxed about copying. Be aware that
cwcp is not necessarily going to
send at exactly the speed you set, due to limitations in what can be done with
UNIX timers. It often sends at a slower speed than you set, so be very careful
with this if you have a target speed that you need to reach.
Use the program to make cassette tapes that you can take with you in a walkman
or in the car, for long journeys. You do not have to write down everything you
hear to practice Morse code. Simply listening to the shapes of characters over
a period will help to train your brain into effortless recognition. In fact,
slavishly writing everything down becomes a barrier at speeds of 15-20 WPM and
above, so if you can begin to copy without writing each character down, you
will find progress much easier above these speeds. But do not over-use these
tapes, otherwise you will quickly memorize them. Re-record them with new
contents at very regular intervals.
Try to spend at least 15-30 minutes each day practicing. Much less than this
will make progress glacially slow. But significantly more than an hour or so
may just result in you becoming tired, but not improving. Recognize when it is
time to stop for the day.
Do not worry if you reach a speed 'plateau'. This is common, and you will soon
pass it with a little perseverance.
At higher speeds, CW operators tend to recognize the 'shape' of whole words,
rather than the individual characters within the words. The CW words menu
option can be used to help to practice and develop this skill.
ERRORS AND OMISSIONS¶
The calibration option is a bit ropy. It simply sends PARIS repeatedly, and
relies on you to time the sending and then work out if any adjustment to the
speed is really necessary. Automatic calibration by making measurements over a
given period would be a lot better.
Generating random CW QSOs would be fun to do.
A facility to allow a user to key Morse into the system, and to have it send
code, and measure the accuracy of keying, would be nice.
SEE ALSO¶
Man pages for
cw(7,LOCAL),
libcw(3,LOCAL),
cw(1,LOCAL),
cwgen(1,LOCAL), and
xcwcp(1,LOCAL).