.\"
.\" UnixCW CW Tutor Package - CW
.\" Copyright (C) 1998  Simon Baldwin (simonb@sco.com)
.\" 
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version 2
.\" of the License, or (at your option) any later version.
.\" 
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
.\"
.\"
.TH UNIXCW 1 "CW Tutor Package" "G0FRD" \" -*- nroff -*-
.SH NAME
.\"
unixcw \- sound characters as Morse code on the console speaker
.\"
.\"
.\"
.SH SYNOPSIS
.\"
.B unixcw
[\-d \fIdevice\fP] [\-\-device=\fIdevice\fP]
[\-t \fItone\fP] [\-\-tone=\fItone\fP] [\-\-hz=\fItone\fP]
[\-w \fIWPM\fP] [\-\-wpm=\fIWPM\fP]
[\-g \fIgap\fP] [\-\-gap=\fIgap\fP]
[\-a \fIadj\fP] [\-\-adj=\fIadj\fP]
.BR
[\-e] [\-\-noecho]
[\-m] [\-\-nomsgs]
[\-c] [\-\-nocmds]
[\-o] [\-\-nocombo]
[\-p] [\-\-nocomments]
.BR
.PP
.B unixcw
also accepts the \-h, \-\-help, \-v and \-\-version options.
.PP
The LINUX version understands both short form and long form command
line options.  Other versions understand only the short form options.
.PP
Options may be predefined in the environment variable \fBCW_OPTIONS\fP.
If defined, these options are used first; command line options take
precedence.
.PP
.\"
.\"
.\"
.SH DESCRIPTION
.\"
.PP
.B unixcw
reads characters from standard input, and sounds each valid character
as Morse code on the system console speaker.  After a character is
sounded,
.B unixcw
echoes it to standard output.  The input stream can contain embedded
command strings.  These change the parameters used when sounding the
Morse code.
.B unixcw
reports any errors in embedded commands on standard error.
.PP
.\"
.\"
.\"
.SS COMMAND LINE OPTIONS
.\"
.B unixcw
understands the following command line options.  Only the short form
options are available in non-LINUX versions.
.TP
.I "\-d, \-\-device"
Specifies the device file to open for sound ioctls.  The default
is to generate tones using standard output, on the assumption that
the program is being run on a character-mode system multiscreen.  If it
is not, a console device file, capable of KIOCSOUND, should be
given.  See \fISELECTING SUITABLE SOUND DEVICE FILES\fP below.
.TP
.I "\-t, \-\-hz, \-\-tone"
Sets the initial sounder pitch in Hz.  This value must be between 0
and 10000.  A value of 0 selects silent operation, and can be used for
timing checks or other testing.  The default value is 800Hz,
.TP
.I "\-w, \-\-wpm"
Sets the initial sending speed in words per minute.  The value must be
between 1 and 60.  The default value is 12 WPM.
.TP
.I "\-g, \-\-gap"
Sets the initial extra gap, in dot lengths, between characters
(the 'Farnsworth' delay).  It must be between 0 and 100.  The default
is 0.
.TP
.I "\-a, \-\-adj"
Allows an adjustment of +/\- several percent on the sending speed,
to allow for timing differences between systems.  The value may be
between \-50 and +50.  The default is 0%.
.TP
.I "\-e, \-\-noecho"
Stops \fBunixcw\fP echoing characters on standard output after they are
sounded.  The default is to have echoing on.
.TP
.I "\-m, \-\-nomsgs"
Stops \fBunixcw\fP printing error messages on standard error.
The default is to print messages.
.TP
.I "\-c, \-\-nocmds"
Stops \fBunixcw\fP from interpreting commands embedded in the input stream.
The default is to interpret embedded commands.
.TP
.I "\-o, \-\-nocombo"
Stops \fBunixcw\fP from treating character strings bracketed by [...] as
a single combination character.  The default is to honour combinations.
.TP
.I "\-o, \-\-nocomments"
Stops \fBunixcw\fP from treating character strings bracketed by {...} as
'comments'; characters inside these braces will be echoed to standard
output, but not sounded.  When comments are being honoured, any
embedded commands inside the braces will be ignored.  The default is
to honour comments.
.PP
.\"
.\"
.\"
.SS SOUNDING CHARACTERS
.\"
.B unixcw
reads characters, one at a time, from its standard input.  Lowercase
letters are converted internally to uppercase.  The following list
shows the valid Morse characters that can be sounded by \fBunixcw\fP
.IP
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+\-./:;=?_ and space
.PP
If \fBunixcw\fP receives a character not in this set, it prints an error
message '?\fIc\fP', where \fIc\fP is the error character.  The only
exceptions to this may be the \fBunixcw\fP command escape character '@',
the combination start and stop characters '[' and ']', and the
comment start and stop characters '{' and '}'.
See \fIEMBEDDED COMMANDS\fP and \fIMORSE CODE COMBINATIONS\fP below.
.PP
.\"
.\"
.\"
.SS MORSE CODE TIMINGS
.\"
In Morse code, a dot or dash is referred to as an element.  The basic
timing unit is the dot length; this is the time taken to send a dot,
not including any space before or after the dot.  The lengths of all
other elements are then derived from this basic unit, using the
following rules:
.IP
The duration of a dash is three dots.
.IP
The time between each element (dot or dash) is one dot length.
.IP
The space between characters is three dot lengths.
.IP
The space between words is seven dot lengths.
.PP
.B unixcw
calculates the dot length it will use with the formula
.IP
dot length in milliseconds = ( 1200 / WPM )
.PP
with any timing adjustment, specified with \fI\-a\fP or \fI\-\-adj\fP
applied afterward.
.PP
This formula arises from the use of the word PARIS as a 'standard'
word for calibrating Morse code speed.  PARIS is 50 units long when
sent in Morse code.  Analysis of English plain-text indicates that
the average word is 50 units, including spaces.
.PP
.\"
.\"
.\"
.SS MORSE CODE CHARACTER TABLES
.\"
The following table shows the ASCII characters that \fBunixcw\fP can
generate, and the Morse code equivalents that it will send for
each.  This table is taken from the \fIARRL Handbook\fP:
.\"
.SP
.IP
.TS
l l l l l l l l 
_ _ _ _ _ _ _ _
l l l l l l l l .
Ch	Code	Ch	Code	Ch	Code	Ch	Code
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	--..				
.BR
0	-----	1	.----	2	..---	3	...--
4	....-	5	.....	6	-....	7	--...
8	---..	9	----.
.BR
"	.-..-.	'	.----.	$	...-..-	(	-.--.
)	-.--.-	+	.-.-.	,	--..--	-	-....-
\.	.-.-.-	/	-..-.	:	---...	;	-.-.-.
\(eq	-...-	?	..--..	\(ul	..--.-		
.TE
.PP
The final set of entries in this table map into Morse code procedural
signals as follows:
.\"
.SP
.IP
.TS
l l l l l l l l
_ _ _ _ _ _ _ _
l l l l l l l l.
Ch	Prosig	Ch	Prosig	Ch	Prosig	Ch	Prosig
"	[AF]	'	[WG]	$	[SX]	(	[KN]
)	[KK]	+	[AR]	,	[MIM]	-	[DU]
\.	[AAA]	/	[DN]	:	[OS]	;	[KR]
\(eq	[BT]	?	[IMI]	\(ul	[IQ]		
.TE
.PP
.\"
.\"
.\"
.SS EMBEDDED COMMANDS
.\"
.B unixcw
recognises special sequences in the input stream as embedded commands.
These commands alter the parameters of the \fBunixcw\fP while it is
running, or query current values.  All commands are prefixed by the
command escape character '@', and those which set a value end with a
semicolon.
.PP
The format of an embedded command to change a parameter value is
.IP
\@\fICvalue\fP;
.PP
where \fIC\fP is a command letter indicating what action \fBunixcw\fP
is to take, and \fIvalue\fP is the argument or value for the command.
.PP
Valid command letters are
.TP
.I "T"
Resets the tone pitch used to sound a character.
.TP
.I "W"
Resets the sending speed.
.TP
.I "G"
Resets the 'Farnsworth' gap between characters.
.TP
.I "A"
Resets the speed adjustment percentage.
.TP
.I "E"
Disables or re-enables echoing of sent characters on standard output.
.TP
.I "M"
Disables or re-enables error messages on standard error.
.TP
.I "C"
Disables processing of embedded commands.  Note that once disabled,
this command cannot re-enable them.
.TP
.I "O"
Disables or re-enables recognition of [...] character combinations.
.TP
.I "P"
Disables or re-enables recognition of {...} comments.  When comments
are being recognised, any character after an opening '{' and before
any closing '}' will be echoed to standard output, but will not be
sounded, or have any other effect.
.PP
For example, the embedded command sequence
.IP
\@W25;@T1200;
.PP
will set \fBunixcw\fP to a speed of 25 WPM, and a tone pitch of 1200Hz.
.PP
The 'T', 'W', 'G', and 'A' commands take values along with the command.
The limits on values given for embedded commands are the same as the
limits available for command line options, detailed above.
.PP
The 'E', 'M', 'C' and 'O' commands are flags, and treat a value of zero
as clear, and any other value as set.  So, for example, the sequence
.IP
\@M0;@C0;
.PP
will turn off error messages, and then turn off the processing of
embedded commands.
.PP
If a parameter is set successfully, \fBunixcw\fP reports the new setting on
standard error (except if no error messages is set).  If an error is
detected in an embedded command, \fBunixcw\fP reports an error.  For the
formats of error messages see the \fIMESSAGE FORMATS\fP section below.
.PP
The current values of parameters within \fBunixcw\fP may be queried,
as well as set.  The command format
.IP
\@?\fIC\fP
.PP
queries the value of the parameter normally set with command \fIC\fP.
.B unixcw
reports the current value on standard error, using the same format
as when new values are set.
.PP
The current values of parameters within \fBunixcw\fP may also be requested
as output in Morse code.  The command format
.IP
\@>\fIC\fP
.PP
will generate Morse output reporting the value of the parameter
normally set with command \fIC\fP.
.PP
If embedded commands are disabled, '@' characters are treated as any
other (in this case, invalid) input character.
.PP
Once processing of embedded commands has been switched off, any
command to switch this feature back on will not be recognised; that
is, after '@C0;', an '@C1' will not be recognised.
.PP
There is one additional command, and that is '@Q'.  This command
closes all open files and terminates \fBunixcw\fP.  Any characters after
this command in the input stream will be lost.
.PP
The file \fIcw.h\fP provides a full set of definitions for the
commands, special characters, and status codes of \fBunixcw\fP.
.PP
.\"
.\"
.\"
.SS MESSAGE FORMATS
.\"
Where a parameter value is set correctly with an embedded command, the
message format
.IP
\=\fICvalue\fP
.PP
is returned.  \fIC\fP is the command used, and \fIvalue\fP is the
new value.
.PP
If an invalid value is supplied for a parameter in an embedded
command, a message
.IP
?\fICvalue\fP
.PP
is returned.
.PP
Where an invalid command is encountered, the message format
.IP
?@\fIC\fP
.PP
is used.  For an invalid query, the message is
.IP
??\fIC\fP
.PP
and for an invalid request for a parameter in Morse code the message
is
.IP
?>\fIC\fP
.PP
A character in the input stream that cannot be sounded produces a
message
.IP
?\fIC\fP
.PP
These messages are not intended to be user-friendly, but are designed
to be easily and quickly interpreted by another program.  Similarly,
the format of embedded commands is more computer-friendly than
user-friendly.
.PP
If error messages are disabled, no messages of any type are printed on
standard error.
.PP
.\"
.\"
.\"
.SS MORSE CODE COMBINATIONS
.\"
The standard set of characters offered by \fBunixcw\fP may not be sufficient
for some purposes.  For example, certain procedural signals, such as VA
(also known as SK), have no ASCII equivalent, and \fBunixcw\fP cannot
therefore sound them directly.
.PP
In these cases, such a combination character may be formed by placing
its individual components between [...] brackets, for example
.IP
[VA]
.PP
This causes \fBunixcw\fP to sound the characters without the usual gap
between them.  In this way, any missing character in the set can be
built.  The eight-dot error signal can be sounded with
.IP
[HH]
.PP
or the C-cedilla in international Morse code with
.IP
[CE]
.PP
There can be as many valid letters, numbers, or figures inside the [...]
brackets as required.  For example, an alternative way of sending the
error signal could be
.IP
[EHEI]
.PP
Embedded commands may be placed inside [...] combinations if required.
Combinations do not nest.
.PP
This feature can be disabled by using the \fI\-O\fP or \fI\-\-nocombo\fP
command line flags, or with the 'O' embedded command.  If combinations
are disabled, '[' and ']' characters are treated as any other (invalid)
input character.
.PP
.\"
.\"
.\"
.SS SELECTING SUITABLE SOUND DEVICE FILES
.\"
.B unixcw
can sound Morse code only to the UNIX console speaker; for this, it
uses the KIOCSOUND ioctl.  By default, it will use standard output
unless the \fI-d\fP or \fI\-\-device\fP option is used.  If the
device refuses to create tones, \fBunixcw\fP prints the error message
.IP
output device won't do sound
.PP
and exits.
.PP
Unless running on a character mode console multiscreen, \fBunixcw\fP will
need to be told which device to use.  Which device files are suitable
will depend on which operating system is running, and which system
user ID runs \fBunixcw\fP.  They must however be console multiscreen
devices; \fI/dev/tty1\fP and up on LINUX, and \fI/dev/tty01\fP and up
on SCO systems.
.PP
On LINUX, it is normally possible to run \fBunixcw\fP as superuser, and
specify \fI/dev/tty1\fP as the sound device; this combination will
usually work no matter which physical tty or pseudo-tty is being used.
Unless running as superuser, \fBunixcw\fP won't have the necessary permission
to access a 'foreign' tty (making \fBunixcw\fP an suid binary can avoid
this problem).
.PP
.\"
.\"
.\"
.SH NOTES
.\"
Despite the fact that this manual page constantly and consistently
refers to Morse code elements as dots and dashes, DO NOT think in these
terms when trying to learn Morse code.  Always think of them as 'dit's
and 'dah's.
.PP
The Morse code table is provided for reference only.  If learning for
the first time, you'll be much better off learning by hearing the
characters sent, rather than by looking at the table.
.PP
Other programs running in the system may interfere with the timing of
the Morse code that \fBunixcw\fP is sending.  If this is a problem,
either try to run on a quiescent system, or try running \fBunixcw\fP
with nice(1L,C,1).  UNIX isn't really designed for user-level programs
to do the sort of fine timing required to send Morse code.  \fBunixcw\fP
is therefore more sensitive than most programs to other system activity.
.PP
.B unixcw
uses system itimers for its internal timing.  On most UNIX flavours,
itimers are not guaranteed to signal a program exactly at the specified
time.  The effect of this is that an itimer period is generally either
exactly as specified, or, more likely, slightly longer.  At higher
WPM settings, the cumulative effect of this affects timing accuracy. 
To test it, first try
.IP
X="PARIS "
.IP
echo "$X" | time unixcw -w 1
.PP
and note the elapsed time, which should be very close to one minute.
Next, try
.IP
echo "$X$X$X$X$X$X$X$X$X$X$X$X" | time unixcw -w 12
.PP
The elapsed time should be the same; if it has increased, this is the
effect of system itimers delaying for slightly longer than the specified
period (higher WPM rates make more itimer calls).  If this is the case,
an appropriate adjustment can be used.  That's itimers for you; not
perfect for this job, but the best there is without writing kernel code.
.PP
Except for zero, which is silent, tone values lower than 10Hz may not
sound at the expected pitch.
.PP
.\"
.\"
.\"
.SH EXAMPLES
.\"
Send a string of characters at 25 WPM, 700Hz, with no extra gaps:
.IP
echo "UNIX CW SOUNDER" | unixcw \-w 25 \-t 700
.PP
Send a string at varying speeds and tones.  Specify a system console
device, since standard output is redirected:
.IP
echo "@W12;@T400;400HZ 12WPM@W25;@T1500;1500HZ 25WPM" |
unixcw \-d /dev/tty1 >/dev/null
.PP
Send C-cedilla, VA, and a report of the WPM setting, with extra spacing:
.IP
echo "[CE] [VA] @>W" | unixcw \-g 10
.PP
.\"
.\"
.\"
.SH ERRORS AND OMISSIONS
.\"
There is no way to vary the weighting of the code sent from the
standard set value.  This isn't because it's hard, but because I
happen to think it sounds awful (and isn't good to learn from; for
over-weighted Morse code, try the 3.5MHz band).
.PP
Cut numbers are not provided, though they can be emulated, up to a
point, by pre-filtering.
.PP
No accented characters, and few non-Latin characters, can be sounded
without resorting to [...] combinations.
.PP
There is no sound card output available (because I don't have one).
An output to an optional external device (for example, keying a
line on the parallel port, or a serial line) might also be useful.
.PP
.\"
.\"
.\"
.SH SEE ALSO
.\"
Man pages for \fBcwgen\fP(1,LOCAL), and \fBcwcp\fP(1,LOCAL).
.\"