xcwcp - X Window-based Morse tutor program

Description

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

COMMANDLINEOPTIONSxcwcp 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 'oss'.

-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 NOTESONUSINGASOUNDCARD
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 CREATINGCONFIGURATIONFILES below.

-F,--outfile=FILE
Specifies a text file to which xcwcp should write its current practice text.

USERINTERFACExcwcp 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 sends or receives.

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

RANDOMCHARACTERSANDWORDSxcwcp sends random characters in groups of five, with a space between each group.

When sending random words, xcwcp sends the complete word, followed by a space. Because short words are
easier to copy without writing, xcwcp's default dictionary contains only three, four, and five-letter
words in its random words list.

xcwcp 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 CREATINGCONFIGURATIONFILES below.

RECEIVINGMORSExcwcp 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 backwards.

NOTESONUSINGASOUNDCARD
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 option -d or --device, combined with -s or --system can be used to specify the device
and sound system for sound card access. If the sound card device cannot be set up, xcwcp 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 xcwcp will
of 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

and exits.

The sound card device is not used if xcwcp is only sending tones on the console speaker.

SOUNDOUTPUT-DEFAULTSANDSELECTIONxcwcp first tries to access sound card using PulseAudio sound system, using default device name, unless
user specifies other sound device with option -d or --device.

xcwcp then tries to access sound card using OSS sound system and default OSS sound device name
('/dev/audio'), unless user specifies other sound device with option -d or --device.

If opening soundcard through OSS fails, xcwcp tries to access the sound card using ALSA sound system, and
default ALSA sound device name ('default'), unless user specifies other sound device with option -d or
--device.

If opening soundcard through ALSA also fails, xcwcp tries to access system console buzzer using default
buzzer device '/dev/console', unless user specifies other sound 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 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 security reasons.

As stated, user can tell xcwcp 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 xcwcp, and which
user groups user belongs to.

CREATINGCONFIGURATIONFILESxcwcp 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 or --infile command line 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

xcwcp 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
will write its default configuration to a file if given the undocumented -# option, for example "xcwcp -#
/tmp/xcwcp.ini".

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.

Name

       xcwcp - X Window-based Morse tutor program

Notes

xcwcp is an X Window rewrite of cwcp. Both programs borrow heavily from 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.

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

Synopsis

xcwcp   [-s --system=SYSTEM]  [-d --device=DEVICE]  [-w --wpm=WPM]  [-t --tone=HZ]  [-v --volume=PERCENT]
       [-g --gap=GAP] [-f, --infile=FILE] [-F, --outifile=FILE] [-h --help] [-V --version]

       xcwcp 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.  If defined, these options are used
       first; command line options take precedence.