unixcw(1)

COMMAND LINE OPTIONS

unixcw understands the following command line options. Only the short form options are available in non-LINUX versions.

-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 SELECTING SUITABLE SOUND DEVICE FILES below.

-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,

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

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

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

-e, --noecho

Stops unixcw echoing characters on standard output after they are sounded. The default is to have echoing on.

-m, --nomsgs

Stops unixcw printing error messages on standard error. The default is to print messages.

-c, --nocmds

Stops unixcw from interpreting commands embedded in the input stream. The default is to interpret embedded commands.

-o, --nocombo

Stops unixcw from treating character strings bracketed by [...] as a single combination character. The default is to honour combinations.

-o, --nocomments

Stops unixcw from treating character strings bracketed by {...} as output, but not sounded. When comments are being honoured, any embedded commands inside the braces will be ignored. The default is to honour comments.

SOUNDING CHARACTERS

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 unixcw

ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"$()+-./:;=?_ and space

If unixcw receives a character not in this set, it prints an error message '?c', where c is the error character. The only exceptions to this may be the unixcw command escape character '@', the combination start and stop characters '[' and ']', and the comment start and stop characters '{' and '}'. See EMBEDDED COMMANDS and MORSE CODE COMBINATIONS below.

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:

The duration of a dash is three dots.

The time between each element (dot or dash) is one dot length.

The space between characters is three dot lengths.

The space between words is seven dot lengths.

unixcw calculates the dot length it will use with the formula

dot length in milliseconds = ( 1200 / WPM )

with any timing adjustment, specified with -a or --adj applied afterward.

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.

MORSE CODE CHARACTER TABLES

The following table shows the ASCII characters that unixcw can generate, and the Morse code equivalents that it will send for each. This table is taken from the ARRL Handbook:

Ch	Code	Ch	Code	Ch	Code	Ch	Code
E		F		G	--.	H
I		J		K	-.-	L
M	--	N	-.	O	---	P
Q	--.-	R		S		T	-
U		V		W		X	-..-
Y	-.--	Z	--..
0	-----	1		2		3
4		5		6	-....	7	--...
8	---..	9	----.
"				$		(	-.--.
)	-.--.-	+		,	--..--	-	-....-
.		/	-..-.	:	---...	;	-.-.-.
=	-...-	?		_

The final set of entries in this table map into Morse code procedural signals as follows:

Ch	Prosig	Ch	Prosig	Ch	Prosig	Ch	Prosig
)	[KK]	+	[AR]	,	[MIM]	-	[DU]
.	[AAA]	/	[DN]	:	[OS]	;	[KR]
=	[BT]	?	[IMI]	_	[IQ]

EMBEDDED COMMANDS

unixcw recognises special sequences in the input stream as embedded commands. These commands alter the parameters of the unixcw 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.

The format of an embedded command to change a parameter value is

@Cvalue;

where C is a command letter indicating what action unixcw is to take, and value is the argument or value for the command.

Valid command letters are

T

Resets the tone pitch used to sound a character.

W

Resets the sending speed.

G

Resets the 'Farnsworth' gap between characters.

A

Resets the speed adjustment percentage.

E

Disables or re-enables echoing of sent characters on standard output.

M

Disables or re-enables error messages on standard error.

C

Disables processing of embedded commands. Note that once disabled, this command cannot re-enable them.

O

Disables or re-enables recognition of [...] character combinations.

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.

For example, the embedded command sequence

@W25;@T1200;

will set unixcw to a speed of 25 WPM, and a tone pitch of 1200Hz.

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.

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

@M0;@C0;

will turn off error messages, and then turn off the processing of embedded commands.

If a parameter is set successfully, unixcw reports the new setting on standard error (except if no error messages is set). If an error is detected in an embedded command, unixcw reports an error. For the formats of error messages see the MESSAGE FORMATS section below.

The current values of parameters within unixcw may be queried, as well as set. The command format

@?C

queries the value of the parameter normally set with command C. unixcw reports the current value on standard error, using the same format as when new values are set.

The current values of parameters within unixcw may also be requested as output in Morse code. The command format

@>C

will generate Morse output reporting the value of the parameter normally set with command C.

If embedded commands are disabled, '@' characters are treated as any other (in this case, invalid) input character.

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.

There is one additional command, and that is '@Q'. This command closes all open files and terminates unixcw. Any characters after this command in the input stream will be lost.

The file cw.h provides a full set of definitions for the commands, special characters, and status codes of unixcw.

MESSAGE FORMATS

Where a parameter value is set correctly with an embedded command, the message format

=Cvalue

is returned. C is the command used, and value is the new value.

If an invalid value is supplied for a parameter in an embedded command, a message

?Cvalue

is returned.

Where an invalid command is encountered, the message format

?@C

is used. For an invalid query, the message is

??C

and for an invalid request for a parameter in Morse code the message is

?>C

A character in the input stream that cannot be sounded produces a message

?C

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.

If error messages are disabled, no messages of any type are printed on standard error.

MORSE CODE COMBINATIONS

The standard set of characters offered by unixcw may not be sufficient for some purposes. For example, certain procedural signals, such as VA (also known as SK), have no ASCII equivalent, and unixcw cannot therefore sound them directly.

In these cases, such a combination character may be formed by placing its individual components between [...] brackets, for example

[VA]

This causes unixcw 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

[HH]

or the C-cedilla in international Morse code with

[CE]

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

[EHEI]

Embedded commands may be placed inside [...] combinations if required. Combinations do not nest.

This feature can be disabled by using the -O or --nocombo command line flags, or with the 'O' embedded command. If combinations are disabled, '[' and ']' characters are treated as any other (invalid) input character.

SELECTING SUITABLE SOUND DEVICE FILES

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 -d or --device option is used. If the device refuses to create tones, unixcw prints the error message

output device won't do sound

and exits.

Unless running on a character mode console multiscreen, unixcw 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 unixcw. They must however be console multiscreen devices; /dev/tty1 and up on LINUX, and /dev/tty01 and up on SCO systems.

On LINUX, it is normally possible to run unixcw as superuser, and specify /dev/tty1 as the sound device; this combination will usually work no matter which physical tty or pseudo-tty is being used. Unless running as superuser, unixcw won't have the necessary permission to access a 'foreign' tty (making unixcw an suid binary can avoid this problem).