xcwcp - X Window-based Morse tutor program
[-s --system= SYSTEM
] [-d --device=
] [-w --wpm= WPM
] [-t --tone= HZ
[-v --volume= PERCENT
] [-g --gap= GAP
] [-F, --outifile= FILE
] [-h --help]
installed on GNU/Linux systems understands both short form and long
form command line options. xcwcp
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 XCWCP_OPTIONS
defined, these options are used first; command line options take precedence.
is a X Window-based interactive Morse code tutor program. It lets
you choose from a number of options for practice, including sending random
characters, random words, and characters from the keyboard. It will also
receive Morse code that you send using the keyboard or mouse as a Morse keyer,
and display the characters it sees.
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 xcwcp generates tones. Valid values are:
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, soundcard for tones generated through the system sound
card, but without explicit selection of sound system. These values can be
shortened to 'c', 'a', 'o', or 's', respectively. The default value is
- -d, --device=DEVICE
- Specifies the device file to open for generating a sound. xcwcp
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. 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 xcwcp 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.
- -f, --infile=FILE
- Specifies a text file that xcwcp can read to configure its practice
text. See CREATING CONFIGURATION FILES below.
- -F, --outfile=FILE
- Specifies a text file to which xcwcp should write its current
offers GUI controls for changing the speed, tone frequency,
'Farnsworth' gap, and mode of the program. All of the major controls are
placed on the application toolbar.
The main GUI window is used to display the characters that xcwcp
To find out more about what a particular GUI control does, use the "What's
this..." icon (the '?' at the far right of the toolbar).
sends random characters in groups of five, with a space between
When sending random words, xcwcp
sends the complete word, followed by a
space. Because short words are easier to copy without writing, xcwcp
default dictionary contains only three, four, and five-letter words in its
random words list.
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
can receive Morse code, and display it in its main GUI window. To
key Morse code into the program, select the Receive Keyed CW mode, and press
the stop/start button. Now, place the mouse cursor over the central window of
the program. By pressing the middle mouse button, you should be able to key
Morse into the program as if the mouse button was a straight Morse key.
For better keying, you can use the left and right mouse buttons as if they were
paddles on an Iambic keyer. This will send Morse code at the exact rate set on
the Speed control.
You can also use the keyboard for keying. In this case, any of the Up or Down
cursor keys, Space, Enter, or Return may be used as the straight key, and the
Left and Right cursor keys act as the two paddles of an Iambic keyer.
By default, xcwcp
will try to follow the speed of the Morse code that you
send to it. It is possible to switch this tracking off, in which case the
program switches to receiving only at the exact speed set on the Speed
control. However, fixed speed receiving is very, very picky about receiving
only extremely accurately timed Morse code, so unless you are striving for
complete perfection, you may find that speed tracking is more comfortable.
The speed tracking in xcwcp
can sometime be confused by very wide and
abrupt changes in speed. If it is having difficulty finding the speed you are
sending at, you can use the File pulldown menu to synchronize the receive
speed to the speed set on the Speed control.
At any time, the mode selection combowidget can get focus by using Alt+M. You
can then use the space bar or the up/down keys to change the mode. The Tab key
moves to the next widget, so you can change speed, etc. Shift+Tab moves
By default, xcwcp
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
, combined with -s
can be used to specify the device and audio system for sound
card access. If the sound card device cannot be set up, xcwcp
the error message
- cannot set up soundcard sound
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 xcwcp
course conflict with any other programs that expect exclusive use of the
system sound card (for example, MP3 players). If xcwcp
finds that the
sound card is already busy, it prints the error message
- open /dev/audio: Device or resource busy
The sound card device is not used if xcwcp
is only sending tones on the
first tries to access sound card using PulseAudio sound system,
using default device name, unless user specifies other audio device with
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
If opening soundcard through OSS fails, xcwcp
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
If opening soundcard through ALSA also fails, xcwcp
tries to access
system console buzzer using default buzzer device '/dev/console', unless user
specifies other audio device with option -d
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 xcwcp
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
As stated, user can tell xcwcp
which device to use, using -d
option. Which device files are suitable will depend on which
operating system is running, which system user ID runs xcwcp
, and which
user groups user belongs to.
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 -i
option. The file should introduce each xcwcp
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
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, xcwcp
write its default configuration to a file if given the undocumented -#
option, for example "xcwcp -# /tmp/xcwcp.ini".
is an X Window rewrite of cwcp
. Both programs borrow heavily
from the the DOS Morse code tutor CP222C.EXE, by VU2ZAP.
The characters echoed in the main GUI window may be ASCII equivalents of Morse
procedural signals; see the cw
(7,LOCAL) man page for details.
Here are a few hints and tips that may help with the process of learning Morse
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
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 recognising 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
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 xcwcp
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 memorise 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. Recognise 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 recognise 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.
Neither the mouse buttons nor the keyboard are ideal for use a keys or keyer
paddles, for sending practice. Try to use a proper key for sending where
possible. It is hard even for experienced operators to get good keying using
the mouse or keyboard. Of the two, the mouse is probably the better option,
though, in a pinch.
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.
Man pages for cw
(1,LOCAL), and xcwcp