cwdaemon - Man Page

cwdaemon [options]

cwdaemon is a small daemon which uses an USB-to-UART converter or PC parallel or serial port (so called "cwdevice") to output Morse code to a transmitter from a text message sent to it via UDP port 6789.

1. Make sure that cwdaemon has not been already started by your OS.

   If cwdaemon is already running, you can start another instance. Just add "--port <value>" option in step 2 and use the port's value instead of "6789" in step 3.

2. Start your instance of cwdaemon. Without "-n" option the program will start running in the background.

   cwdaemon -x s -n

3. In another terminal, start "nc" program with which you will send text to cwdaemon.

   nc -u 127.0.0.1 6789

4. With "nc" running, type any text, press Enter. "nc" will send the text to cwdaemon listening on specified UDP port, cwdaemon will play the text on sound card ("-x s").

You can interact with a running instance of cwdaemon through UDP messages exchanged between cwdaemon and your program.

cwdaemon can receive at most 256 bytes in a single request. Any bytes in a request beyond that limit are dropped by cwdaemon. Received bytes are further processed inside of cwdaemon. Dropped bytes aren't processed further by cwdaemon. Client program that sent an oversized message is not informed about the dropping of bytes by cwdaemon.

There are three types of requests that can be sent to cwdaemon:

plain request

Plain requests consist only of characters that should be keyed by cwdaemon on cwdevice.

caret request

Caret requests are similar to plain requests, but the last character in the request is ´^´. See "Replies" section below for more info.

Escape request

Escape requests start with ASCII Escape character (decimal 27, hex 1B) followed by an Escape code: a character specifying exact request type. Escape requests are used to control and configure a running instance of cwdaemon.

The Escape code characters are case-sensitive.

The Escape character is represented in the "Options" section below by "<ESC>" string. Notice that there are no space characters between parts of Escape requests.

Some of the Escape requests require passing a value (e.g. Morse speed [wpm], tone (frequency) [Hz] etc.). The values should be string representations of parameters. E.g. "20" string should be used as a value of Escape request to request 20 wpm Morse speed.

When handling Escape requests, cwdaemon usually does not accept invalid, malformed or out-of-range vales. Upon receiving request with such value, it prints debug message, ignores the request containing such value, and waits for next request. One exception to the rule is PTT delay: requested delay values that are too large will be clipped to maximal allowed value and then will be used by cwdaemon. Requested negative or malformed values of PTT delay will be ignored.

Some types of requests are followed by replies sent back from cwdaemon to a program issuing the original request. These requests are:

• caret request
• ´reply´ Escape request (Escape request ´h´)

Each reply is terminated with '\r' + '\n' characters.

cwdaemon can be configured through command line options on start of the daemon.

Some of the options require passing a value (e.g. Morse speed [wpm], tone (frequency) [Hz] etc.). Call "cwdaemon -h" to see default values for these options/requests, and ranges of accepted values.

When handling command line options, cwdaemon does not accept invalid, malformed, or out-of-range values passed through command line. It won't attempt to guess caller's intentions, it won't try to start with some fallback value of the option. Instead it will just print a debug message and exit. Rejection of bad values and exiting will happen before attempting to fork.

Print help text to stdout and exit

Command line option: -h, --help

Escaped request: N/A

Print version information to stdout and exit

Command line option: -V, --version

Escaped request: N/A

Use hardware keying device (cwdevice) specified by device's name or path

Command line option: -d, --cwdevice <device name>

Example command line: cwdaemon --cwdevice ttyS0
Example command line: cwdaemon -d /dev/ttyUSB0

Escaped request: <ESC>8<device name>

You can specify the device either by device's name (then cwdaemon will look for the device in /dev directory) or by full path to the device.

See chapter "Keying Devices" below for more information.

Don't fork daemon, run in foreground

Command line option: -n, --nofork

Escaped request: N/A

Debug information will be printed to stdout (unless different debug output is selected, or debug output is silenced by setting debug output verbosity).

Provide device-specific options to keying device's driver

Command line option: -o, --options <option>

Example command line: cwdaemon -d /dev/ttyUSB0 -o key=RTS -o ptt=none
Example command line: cwdaemon -d /dev/ttyUSB0 -o key=RTS --option ptt=none

Escaped request: N/A

This passes <option> to the driver for the keying device selected by the -d / --cwdevice option. Multiple <option> values can be passed in multiple -o invocations. These options must always follow the -d / --cwdevice option on the command line.

The driver for serial devices understands the following options (without spaces):

key=DTR|RTS|none

Use DTR or RTS line for CW keying, or none to disable CW keying. Default is DTR.

ptt=RTS|DTR|none

Use RTS or DTS line for SSB PTT, or none to disable PTT. Default is RTS.

Set network UDP port

Command line option: -p, --port <port number>

Allowed values of port number are in range <1024 - 65535>, inclusive.
If this option is not used, cwdaemon will listen on UDP port 6789 by default.

Escaped request: <ESC>9<port number>

This Escape request is obsolete and has no effect.

Set process priority (niceness)

Command line option: -P, --priority <priority>

Escaped request: N/A

Set Morse speed [wpm]

Command line option: -s, --wpm <speed>

Escaped request: <ESC>2<speed>

Set PTT delay [ms] (TOD, Turn On Delay, TX delay)

Command line option: -t, --pttdelay <delay>

Escaped request: <ESC>d<delay>

Set state of PTT pin

Command line option: N/A

Escaped request: <ESC>a<{0|1}>

0 - PTT off, 1 - PTT on

Set sound system (sound backend)

Command line option: -x, --system <system>

Escaped request: <ESC>f<system>

See chapter "Sound System" below for more information.

Set sound volume for soundcard [%]

Command line option: -v, --volume <volume>

Escaped request: <ESC>g<volume>

Set Morse weighting

Command line option: -w, --weighting <weighting>

Escaped request: <ESC>7<weighting>

Set tone (frequency) of sound [Hz]

Command line option: -T, --tone <tone>

Escaped request: <ESC>3<tone>

Notice that sending Escape request with value '0' silences cwdaemon.

Increase verbosity of debug output

Command line option: -i

Escaped request: N/A

The option can be repeated up to four times (-iiii) to gradually increase the verbosity.  Alternatively you can use -y/--verbosity option.

Set verbosity threshold for debug messages

Command line option: -y, --verbosity <threshold>

Escaped request: N/A

Alternatively you can use -i option.

See chapter "Debugging" below for more information.

Set value of libcw debug flags

Specify value (as decimal number) of flags passed to libcw for purposes of debugging of the libcw library.

Command line option: -I, --libcwflags <flags>

Escaped request: N/A

Set debug output

Command line option: -f, --debugfile <output>

Escaped request: N/A

Print debug information to <output> instead of stdout. Value of <output> can be explicitly stated as "stdout" (when not forking). Value of <output> can be also "stderr" (when not forking). Special value of <output> being "syslog" is reserved for future use. For now it will be rejected as invalid. Passing path to disc file as value of <output> works in both situations: when forking and when not forking.

Reset some of cwdaemon parameters

Command line option: N/A

Escaped request: <ESC>0

The request resets program's parameters to cwdaemon default values, unless the defaults were overridden with command line options - then the values passed in command line are used.

Abort currently sent message

Command line option: N/A

Escaped request: <ESC>4

This request may be used to interrupt/end keying of current message or to interrupt/end a tuning procedure, provided that cwdaemon is working in interrupt-able (non-word) mode.

Exit (close) cwdaemon

Command line option: N/A

Escaped request: <ESC>5

Set word mode

Command line option: N/A

Escaped request: <ESC>6

Set SSB way

Command line option: N/A

Escaped request: <ESC>b<{0|1}

0 - microphone, 1 - soundcard

Tune for a number of seconds

Command line option: N/A

Escaped request: <ESC>c<seconds>

Tune for <seconds> seconds. This function does two things: plays continuous wave using current sound system, and holds down (closed / 1) the 'key' pin of keying device.

The tuning may be interrupted/terminated with ABORT Escape request (<ESC>4) if cwdaemon is working in interrupt-able (non-word) mode.

Set band switch output

Command line option: N/A

Escaped request: <ESC>e<value>

This option sets state of pins of lpt port: pin 9 (MSB), 8, 7, 2 (LSB).

Any serial device that supports getting and setting the modem control lines can be used.  On Linux, ttyS0, ttyS1, etc. will work.  On FreeBSD these devices are known as ttyd0, ttyd1, etc. On OpenBSD, these same devices are known as tty00, tty01, etc., but may vary with platform.

For parallel ports on Linux try parport0 (default) or parport1, and on FreeBSD, ppi0 (default), ppi1, etc.  OpenBSD does not support parallel port operation, and defaults to 'tty00'.

You can also specify a full path to the device in /dev/ dir, e.g. '/dev/ttyUSB0'.

cwdaemon can be used with USB-to-UART converters that support DTR and RTS pins.

You can assign keying and ptt functions to the pins of serial port or USB-to-UART converter through '-o'/--options' command line options.

For completeness, a dummy 'null' device is provided.  This device does exactly nothing (no rig keying, no ssb keying, etc.).

´sound system´ should be one of following:

´c´ - console buzzer (PC speaker) - default sound system,

´o´ - OSS,

´a´ - ALSA,

´p´ - PulseAudio,

´n´ - none - no audio,

´s´ - soundcard - autoselect from OSS/ALSA/PulseAudio.

Currently it's not possible to specify name of sound device.

For OSS, cwdaemon will try to use /dev/audio device.

cwdaemon can print debug messages. Each debug message in cwdaemon has specified priority (severity), and can be printed (or not) depending on current priority threshold specified for cwdaemon.  The priority level value for each message can be changed in future versions of cwdaemon. Don't depend on current setup.

The priority threshold can be specified through command line options: -i, -y, or --verbosity. -y and --verbosity accept "threshold" value (single character) as specified below:

´n´ - none

´e´ - error

´w´ - warning (default)

´i´ - information

´d´ - debug

By default the threshold is set to "warning" - cwdaemon will print errors and warnings. Changing the threshold to "information" will make the cwdaemon print errors, warnings, and information messages.

Debug messages can be printed to stdout, stderr, or disc file. Printing to stdout or stderr is available only if cwdaemon has not forked. Printing to disc file is available regardless of whether cwdaemon has forked or not.  You can specify intended debug output using -f or --debugfile command line option. Values "stdout" and "stderr" passed to cwdaemon with these options are recognized as special file names. "syslog" value is also treated as special value, but is not supported at the moment. Every other value will be treated as path to disc file.  "stdout" is a default debug output for non-forked cwdaemon. You don't have to specify this explicitly through command line options, but you can.

Regardless of values passed through -f or --debugfile options, cwdaemon opens a syslog output and (when forked) prints some messages to the syslog. There is no way to override this at the moment. Which messages are always printed to syslog, and which can be printed to other file, is settled for now, but may be changed in the future. Don't depend too much on current setup.

When an Escape request "f" (change sound system) is sent asking for switching to sound system that is generally supported by libcw, but not available on given machine, cwdaemon will not recognize that the sound system is not available. It will close current audio system, and will attempt to open unavailable audio system. That fails, and cwdaemon falls back to Null audio system. If the falling back fails, it will result in cwdaemon working without any sound system, and it may potentially crash the daemon on next attempt to play audio.

The provided README in /usr/share/cwdaemon for a description of the circuitry, usage and testing of cwdaemon.

cwdaemon was written by Joop Stakenborg <pg4i at amsat.org>, Rein Couperus <pa0r at amsat.org>, Wolf-Ruediger Juergens, DL2WRJ <WJuergens at t-online.de> and Ladislav Vaiz, OK1ZIA <ok1zia at nagano.cz>. Cwlib was taken and adapted from the unixcw package, version 2.2 by Simon Baldwin, G0FRD. FreeBSD support mostly done by Diane Bruce, VA3DB. OpenBSD support by Jason L. Wright, AI4JW.

Since 2012 the main developer is Kamil Ignacak <acerion@wp.pl>.