Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CWCP(1)			    General Commands Manual		       CWCP(1)

       cwcp - curses-based Morse tutor program

       cwcp	[-s --system=SYSTEM]	[-d --device=DEVICE]	[-w --wpm=WPM]
       [-t --tone=HZ]	[-v --volume=PERCENT]	[-g --gap=GAP]	 [-k --weight-
       ing=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 sys-
       tems 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	prece-

       cwcp is a curses-based interactive Morse	code tutor program.  It	allows
       menu selection from a number of sending modes, and also permits charac-
       ter sounding options, such as the tone pitch, and sending speed,	to  be
       varied from the keyboard	using a	full-screen user interface.

       cwcp understands	the following command line options.  The long form op-
       tions 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 val-
	      ues can be shortened to 'n', 'c',	'a', 'o', 'p', or 's', respec-
	      tively. 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  de-
	      vices  are: /dev/console for sound produced through console, de-
	      fault 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 be-
	      tween 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 de-
	      fault 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	 prac-
	      tice 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.

       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

       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	effec-
	      tively 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 mi-
	      crowave or kitchen timer;	it counts down on  its	own,  but  the
	      time  remaining can also be altered manually while the timer op-

       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 corrup-
       tion.  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_ combina-
       tions  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.

       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.

       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.

       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 ('de-
       fault'),	unless user specifies other audio device  with	option	-d  or

       If opening soundcard through ALSA also fails, cwcp tries	to access sys-
       tem 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  con-
       sole  buzzer almost always fails.  This is not a	program's bug, this is
       a result	of operating system's restrictions.  Making cwcp an  suid  bi-
       nary 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.

       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 op-
       tions.  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  undocu-
       mented -# option, for example "cwcp -# /tmp/cwcp.ini".

       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.

       Here are	a few hints and	tips that may help with	the process of	learn-
       ing 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

       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 ef-
       fective 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, de-
       crease 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 charac-
       ters  which  are	 in  some  way related,	either by sound, or by type of

       Once you	have completed all the groups EISH5 to "'$(+:_	(or  23789  if
       you  do not want	to learn procedural signals yet), use the full charac-
       ter 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  tu-
       tor  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 limita-
       tions 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 im-
       proving.	 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

       The calibration option is a bit ropy.  It simply	 sends	PARIS  repeat-
       edly,  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.

       Man pages for cw(7,LOCAL), libcw(3,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL),
       and xcwcp(1,LOCAL).

cwcp ver. 3.5.1		       CW Tutor	Package			       CWCP(1)


Want to link to this manual page? Use this URL:

home | help