1CWCP(1)                     General Commands Manual                    CWCP(1)
2
3
4

NAME

6       cwcp - curses-based Morse tutor program
7

SYNOPSIS

9       cwcp     [-s --system=SYSTEM]    [-d --device=DEVICE]    [-w --wpm=WPM]
10       [-t --tone=HZ]   [-v --volume=PERCENT]   [-g --gap=GAP]   [-k --weight‐
11       ing=WEIGHT] [-T --time=TIME] [-f, --infile=FILE] [-F, --outifile=FILE]
12       [-h --help] [-V --version]
13
14       cwcp installed on GNU/Linux systems understands  both  short  form  and
15       long form command line options.  cwcp installed on other operating sys‐
16       tems may understand only the short form options.
17
18       There are no mandatory options.
19
20       Options may be predefined in the environment variable CWCP_OPTIONS.  If
21       defined, these options are used first; command line options take prece‐
22       dence.
23

DESCRIPTION

25       cwcp is a curses-based interactive Morse code tutor program.  It allows
26       menu selection from a number of sending modes, and also permits charac‐
27       ter sounding options, such as the tone pitch, and sending speed, to  be
28       varied from the keyboard using a full-screen user interface.
29
30   COMMAND LINE OPTIONS
31       cwcp  understands  the  following  command line options.  The long form
32       options may not be available in non-LINUX versions.
33
34       -s, --system=SYSTEM
35              Specifies the way that cwcp generates tones.  Valid values  are:
36              null  for  no tones, just timings, console for tones through the
37              console speaker, alsa for tones  generated  through  the  system
38              sound  card  using  ALSA  sound  system, oss for tones generated
39              through system sound card using OSS sound system, pulseaudio for
40              tones generated through system sound card using PulseAudio sound
41              system, soundcard for tones generated through the  system  sound
42              card, but without explicit selection of sound system. These val‐
43              ues can be shortened to 'n', 'c', 'a', 'o', 'p', or 's', respec‐
44              tively. The default value is 'pulseaudio'.
45
46       -d, --device=DEVICE
47              Specifies  the device file to open for generating a sound.  cwcp
48              will use default  device  if  none  is  specified.  The  default
49              devices  are:  /dev/console  for sound produced through console,
50              default for ALSA sound system, /dev/audio for OSS sound  system,
51              a default device for PulseAudio sound system.  See also NOTES ON
52              USING A SOUND CARD below.
53
54       -w, --wpm=WPM
55              Sets the initial sending speed in words per minute.   The  value
56              must be between 4 and 60.  The default value is 12 WPM.
57
58       -t, --tone=HZ
59              Sets  the  initial  sounder  pitch  in  Hz.   This value must be
60              between 0 and 4,000.  A value of 0 selects silent operation, and
61              can  be  used  for  timing checks or other testing.  The default
62              value is 800Hz,
63
64       -v, --volume=PERCENT
65              Sets the initial sending volume, as a percentage of  full  scale
66              volume.  The value must be between 0 and 100.  The default value
67              is 70 %.  Sound volumes work fully for  sound  card  tones,  but
68              cwcp  cannot  control  the  volume  of  tones  from  the console
69              speaker.  In this case, a volume of  zero  is  silent,  and  all
70              other volume values are simply sounded.
71
72       -g, --gap=GAP
73              Sets  the  initial extra gap, in dot lengths, between characters
74              (the 'Farnsworth' delay).  It must be between  0  and  60.   The
75              default is 0.
76
77       -k, --weighting=WEIGHT
78              Sets  the initial weighting, as a percentage of dot lengths.  It
79              must be between 20 and 80.  The default is 50.
80
81       -T, --time=TIME
82              Sets the initial practice time, in minutes.   cwcp  stops  after
83              generating random Morse code for this period.  The value must be
84              between 1 and 99.  The default is 15 minutes.
85
86       -f, --infile=FILE
87              Specifies a text file that cwcp can read to configure its  prac‐
88              tice text.  See CREATING CONFIGURATION FILES below.
89
90       -F, --outfile=FILE
91              Specifies  a  text  file  to which cwcp should write its current
92              practice text.
93
94       -h, --help
95              Prints short help message.
96
97       -V, --version
98              Prints information about program's version, authors and license.
99
100   USER INTERFACE
101       cwcp is a curses-based program that takes over the  complete  operation
102       of  the  terminal  on which it is run.  If colours are available on the
103       terminal, it will produce a colour interface.
104
105       The cwcp screen is divided into several distinct areas:
106
107       The Menu Selection window
108              The Menu Selection window shows the main modes that cwcp offers.
109              Use  the  F10  and F11 or KEY_DOWN and KEY_UP keys to select the
110              mode.  F9 or Return start sending, and  F9  again  or  Esc  stop
111              sending.  Changing mode also stops sending.
112
113       The Morse Code Display window
114              This window displays each Morse code character after it has been
115              sent.
116
117       The Speed Control window
118              The Speed window shows the current Morse code sending  speed  in
119              words  per  minute.  Pressing the F2 or KEY_RIGHT keys increases
120              the speed; pressing the F1 or KEY_LEFT keys decreases the speed.
121
122       The Tone Control window
123              This window shows the current Morse code tone pitch.  Use the F4
124              or KEY_HOME key to increase the pitch, and the F3 or KEY_END key
125              to decrease it.  Values change in steps of 20Hz.
126
127       The Volume Control window
128              This window shows the current Morse code volume.  Use the F6 key
129              to  increase  the volume, and the F5 key to decrease it.  Values
130              change in steps of 1%.  Note that cwcp cannot control the volume
131              of  the console speaker, so the volume control only works effec‐
132              tively for tones generated on the sound card.
133
134       The Gap Control window
135              This window shows the current additional 'Farnsworth' gaps to be
136              appended  after each Morse code character is sounded.  Use F8 to
137              increase the gap, and F7 to decrease it.
138
139       The Time Control window
140              This window shows the selected practice time.  After  generating
141              Morse  code  in  a particular mode for this amount of time, cwcp
142              stops automatically.  Use KEY_NPAGE to increase  the  time,  and
143              KEY_PPAGE  to  decrease  it.   During sending, the value in this
144              window counts down to one, and after final minute of sending has
145              elapsed,   cwcp  stops  sending.   The  timer  operates  like  a
146              microwave or kitchen timer; it counts down on its own,  but  the
147              time  remaining  can  also  be  altered manually while the timer
148              operates.
149
150       The following keys vary the screen colours:
151
152       { key  Changes the foreground colour of the window boxes.
153
154       } key  Changes the background colour of the window boxes.
155
156       [ key  Changes the foreground colour of the window contents.
157
158       ] key  Changes the background colour of the window contents.
159
160       Eight screen colours are available for each: black, red, green, yellow,
161       blue, magenta, cyan, and white.  Use a key to cycle round these colours
162       for the particular part of the display controlled by that  key.   On  a
163       change of colours, the complete screen is repainted.
164
165       Use  Ctrl-L  to  repaint the complete screen, in case of screen corrup‐
166       tion.  Use Ctrl-V to clear the Morse Code Display Window.  This command
167       is available only when cwcp is not sending.
168
169       To leave cwcp, press F12 or Ctrl-C, or select Exit on the mode menu.
170
171       All  of  the above command keys may be used while random characters are
172       being sent, and when keyboard input is being sent.
173
174       If function keys are not available on the terminal, Ctrl-<key> combina‐
175       tions  can be used.  On the top row of letter keys on the keyboard, the
176       keys Ctrl-Q to Ctrl-I may be used as alternatives for F1 to F8, and  on
177       the  second row of letter keys, Ctrl-A to Ctrl-F as alternatives for F9
178       to F12.  For KEY_PPAGE and KEY_NPAGE, use Ctrl-O and Ctrl-P.
179
180   RANDOM CHARACTERS AND WORDS
181       cwcp sends random characters in groups of five, with  a  space  between
182       each group.  After a period of sending, set in the Time Control window,
183       cwcp stops automatically.  It can also be stopped manually, before this
184       time period expires.
185
186       When  sending random words, cwcp sends the complete word, followed by a
187       space.  Because short words are easier to copy without writing,  cwcp's
188       default  dictionary contains only three, four, and five-letter words in
189       its random words list.
190
191       cwcp chooses at random from a list of around 3000 words in its  default
192       dictionary.   You can change this text using a configuration file, read
193       at startup.  See CREATING CONFIGURATION FILES below.
194
195   NOTES ON USING A SOUND CARD
196       By default, cw tries to open default PulseAudio. If  PulseAudio  server
197       is  not  accessible, cw tries to open OSS device "/dev/audio" to access
198       the system sound card.  This is generally the correct  device  to  use,
199       but for systems with special requirements, or those with multiple sound
200       cards, the option -d or --device, combined with -s or --system  can  be
201       used  to specify the device and sound system for sound card access.  If
202       the sound card device cannot be set up, cwcp prints the error message
203
204              cannot set up soundcard sound
205
206       and exits.
207
208       Sound card devices, when opened through OSS sound system,  are  usually
209       single-access  devices, so that when one process has opened the device,
210       other processes are prevented from using it. In such cases cwcp will of
211       course  conflict  with  any other programs that expect exclusive use of
212       the system sound card (for example, MP3 players).  If cwcp  finds  that
213       the sound card is already busy, it prints the error message
214
215              open /dev/audio: Device or resource busy
216
217       and exits.
218
219       The  sound card device is not used if cwcp is only sending tones on the
220       console speaker.
221
222   SOUND OUTPUT - DEFAULTS AND SELECTION
223       cwcp first tries to access sound card using  PulseAudio  sound  system,
224       using  default  device  name,  unless user specifies other sound device
225       with option -d or --device.
226
227       cwcp then tries to access sound card using OSS sound system and default
228       OSS sound device name ('/dev/audio'), unless user specifies other sound
229       device with option -d or --device.
230
231       If opening soundcard through OSS fails, cwcp tries to access the  sound
232       card  using  ALSA  sound  system,  and  default  ALSA sound device name
233       ('default'), unless user specifies other sound device with option -d or
234       --device.
235
236       If opening soundcard through ALSA also fails, cwcp tries to access sys‐
237       tem console buzzer using default buzzer device  '/dev/console',  unless
238       user specifies other sound device with option -d or --device.
239
240       It  is  very  common  that in order to access the console buzzer device
241       user has to have root privileges.  For that reason trying to open  con‐
242       sole  buzzer almost always fails.  This is not a program's bug, this is
243       a result of operating  system's  restrictions.   Making  cwcp  an  suid
244       binary  bypasses  this  restriction.   The  program  does not fork() or
245       exec(), so making it suid should be relatively safe.  Note however that
246       this practice is discouraged for security reasons.
247
248       As stated, user can tell cwcp which device to use, using -d or --device
249       option.  Which device files are suitable will depend on which operating
250       system  is  running,  which  system  user  ID runs cwcp, and which user
251       groups user belongs to.
252
253   CREATING CONFIGURATION FILES
254       cwcp contains a default set of modes and practice text that  should  be
255       enough  to  begin  with.  It can however read in a file at startup that
256       reconfigures these to provide different character groupings, word sets,
257       and other practice data.
258
259       To  read  a  configuration  file,  use  the -f or --infile command line
260       options.  The file should introduce  each  cwcp  mode  with  a  section
261       header  in  '['  ...  ']' characters, followed by the practice text for
262       that mode, with elements separated by whitespace.  Lines starting  with
263       a semicolon or hash are treated as comments.  For example
264
265              ; Simple example mode
266              [ A to Z ]
267              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
268
269       cwcp  will  generate five character groups for modes whose elements are
270       all single characters, and treat other modes as  having  elements  that
271       are  complete  words.   As  a starting point for customized modes, cwcp
272       will write its default configuration to a file  if  given  the  undocu‐
273       mented -# option, for example "cwcp -# /tmp/cwcp.ini".
274

NOTES

276       cwcp  owes  its  existence  to  the DOS Morse code tutor CP222C.EXE, by
277       VU2ZAP.  CP222C.EXE seemed to offer the right range of  facilities  for
278       learning  Morse  code  in  a  simple, easy-to-use, and compact package.
279       cwcp is very much modeled on that DOS program, and should prove  useful
280       both  for  learning the code, and for experienced CW users who want, or
281       need, to improve their receiving speed.
282
283       Curses may impose a delay when recognizing the Esc key alone,  as  this
284       character is often the first of a sequence generated by a function key.
285       cwcp responds instantly to F9.
286
287       The characters echoed in the Morse Code Display  window  may  be  ASCII
288       representations  of  Morse  procedural signals; see the cw(7,LOCAL) man
289       page for details.
290
291   HINTS ON LEARNING MORSE CODE
292       Here are a few hints and tips that may help with the process of  learn‐
293       ing Morse code.
294
295       Firstly,  do  NOT  think  of the elements as dots and dashes.  Instead,
296       think of them as dits and dahs (so 'A' is di-dah).   If  you  think  of
297       them in this way, the process of translating sound into characters will
298       be learned much more easily.
299
300       Do not learn the characters from a table.  Learn them by  watching  the
301       groups  appear  on  the screen, and listening to the sounds produced as
302       each is sent.  In the very initial stages, it may be beneficial if  you
303       can  find  a person to take you through the first stages of recognizing
304       characters.
305
306       Do not waste your time learning Morse code at 5 WPM.  Set the speed  to
307       12  or  15  WPM,  but  use extra spacing (the Gap window) to reduce the
308       effective speed to much lower -  around  four  or  five  WPM  effective
309       speed.   This  way, you will learn the rhythm of the characters as they
310       are sent, but still have plenty of time  between  characters.   As  you
311       practice, decrease the gap to zero.
312
313       Learn in stages.  Start by learning the EISH5 group, then progress down
314       through the menu as each group is mastered.  The groups contain charac‐
315       ters  which  are  in  some  way related, either by sound, or by type of
316       character.
317
318       Once you have completed all the groups EISH5 to "'$(+:_  (or  23789  if
319       you  do not want to learn procedural signals yet), use the full charac‐
320       ter set options, and the words and CW words options,  to  sharpen  your
321       skill.   If you have difficulties with particular characters, return to
322       that group and practice again with a smaller character set.
323
324       Resist the temptation to try to learn or improve your speed by  copying
325       off-air.   You  will  not  know what speed you are working at, and much
326       hand-sent Morse is not perfectly formed.  What  you  can  gain  off-air
327       though  is a general 'resilience', a tolerance for Morse code where the
328       timing of individual elements, or spacing between characters and words,
329       is not 100% accurate.
330
331       If  working  to  attain  a  particular speed for a test, always set the
332       speed slightly higher.  For example, if aiming  for  12  WPM,  set  the
333       tutor  speed  to  14 or 15 WPM.  This way, when you drop back to 12 WPM
334       you will feel much more relaxed about copying.  Be aware that  cwcp  is
335       not necessarily going to send at exactly the speed you set, due to lim‐
336       itations in what can be done with UNIX timers.  It  often  sends  at  a
337       slower  speed  than you set, so be very careful with this if you have a
338       target speed that you need to reach.
339
340       Use the program to make cassette tapes that you can take with you in  a
341       walkman  or  in  the  car, for long journeys.  You do not have to write
342       down everything you hear to practice Morse code.  Simply  listening  to
343       the  shapes  of  characters over a period will help to train your brain
344       into effortless recognition.  In  fact,  slavishly  writing  everything
345       down  becomes a barrier at speeds of 15-20 WPM and above, so if you can
346       begin to copy without  writing  each  character  down,  you  will  find
347       progress  much  easier  above  these speeds.  But do not over-use these
348       tapes, otherwise you will quickly memorize them.  Re-record  them  with
349       new contents at very regular intervals.
350
351       Try  to  spend  at  least 15-30 minutes each day practicing.  Much less
352       than this will make progress glacially slow.   But  significantly  more
353       than  an  hour  or  so  may  just result in you becoming tired, but not
354       improving.  Recognize when it is time to stop for the day.
355
356       Do not worry if you reach a speed 'plateau'.  This is common,  and  you
357       will soon pass it with a little perseverance.
358
359       At  higher  speeds, CW operators tend to recognize the 'shape' of whole
360       words, rather than the individual characters within the words.  The  CW
361       words  menu  option  can  be  used to help to practice and develop this
362       skill.
363

ERRORS AND OMISSIONS

365       The calibration option is a bit ropy.  It simply  sends  PARIS  repeat‐
366       edly,  and  relies  on you to time the sending and then work out if any
367       adjustment to the speed is really necessary.  Automatic calibration  by
368       making measurements over a given period would be a lot better.
369
370       Generating random CW QSOs would be fun to do.
371
372       A facility to allow a user to key Morse into the system, and to have it
373       send code, and measure the accuracy of keying, would be nice.
374

SEE ALSO

376       Man pages for cw(7,LOCAL), libcw(3,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL),
377       and xcwcp(1,LOCAL).
378
379
380
381cwcp ver. 3.6.0                CW Tutor Package                        CWCP(1)
Impressum