xcatctl

xcatctl − Control an xcat board in a Syntor X via CI-V over a serial port

xcatctl [ options ]

Xcatctl controls an xcat board installed in a Syntor X radio by sending commands to it through a serial port. The command structure is based on Icom’s CI-V protocol, with a number of extensions. The xcat board provides 32 modes (channels) of radio configuration space, plus a number of features not provided by the original code plug hardware, while making the radio believe the standard hardware is installed.

For more information about the xcat board, see http://groups.yahoo.com/group/xcat/. In particular, you will probably need to read the xcat documentation at least once to understand how to use this program.

For copious information on working with Syntor X radios, see http://www.open.org/~blenderm/syntorx/.

For details of the contents of a Syntor X code plug, see http://home.xnet.com/~pakman/syntor/syntorx.htm.

--verbose

Produce output suitable for human, instead of machine, consumption.

--setvfofreq freq

Set freq (specified in megahertz) as the operating frequency of the VFO. Note that you should set duplex, transmit offset, radio band and VCO split (v-bit shift) frequencies before setting the operating frequency, as the xcat needs these values to correctly calculate the data required by the radio.

--setmode mode

Select mode as the "current" mode (memory channel). Note that selecting a mode does NOT copy its data into the VFO.

--storevfotomode

Store the configuration currently in the VFO to the currently selected mode (memory channel).

--storemodetovfo

Copy the configuration data from the currently selected mode (memory channel) into the VFO, thus making them the radio’s current operating parameters.

--setduplex { simplex | negative | positive }

Set the duplex (transmit offset direction) of the radio as specified. The size of any offset is selected using the --settxoffset option.

--settxpl plfreq

Set plfreq (specified in hertz) as the transmit (encode) PL (CTCSS) tone. Use 0 to turn off PL. Only standard PL tones can be set; nonstandard tones will be rejected by the xcat board. A list of standard tones appears below. Note that DPL cannot be set using standard commands; you must use the direct code plug loading functions to achieve DPL operation.

--setrxpl plfreq

Set plfreq (specified in hertz) as the receive (decode) PL (CTCSS) tone. Use 0 to turn off PL. Only standard PL tones can be set; nonstandard tones will be rejected by the xcat board. A list of standard tones appears below. Note that DPL cannot be set using standard commands; you must use the direct code plug loading functions to achieve DPL operation.

--getvfocodeplug

Retrieve the code plug data from the VFO and display it in hex.

--setvfocodeplug codeplugdata

Store one mode (channel) of codeplugdata (16 bytes) into the VFO. The format of the data should be the same as that displayed by the --getcodeplugdata option. Note that you will probably have to quote the hexadecimal string to get it past your command interpreter/shell. Loading mode data using this option allows more flexibility in configuring the radio, since all code plug variables can be manipulated. You may find the syntorxgen (1) and loadplug (1) programs useful in generating and loading such code plug data.

--getversion

Retrieve the firmware version number from the xcat and display it.

--getconfig

Retrieve the two bytes of configuration data from the xcat and display them in hexadecimal.

--setconfig

Using the default values, and/or those specified by the --radioband, --sendcos, --controlsys, and --io0..--io7 options, change the configuration of the xcat.

--setconfigbits hexbytes

Use the two byte values specified by hexbytes to change the configuration of the xcat. See the xcat documentation for the bit maps needed to calculate the values.

--gettxoffset

Retrieve the value added to or subtracted from the receive frequency by the xcat to determine the transmit frequency when operating in positive or negative duplex (offset) modes. The value is displayed in hertz.

--settxoffset offset

Set to offset the value added to or subtracted from the receive frequency by the xcat to determine the transmit frequency when operating in positive or negative duplex (offset) modes. The value should be specified in hertz. Note that changing this value does not cause any immediate change in the operation of the radio. The value is only used by the xcat in calculating new data when a frequency is set using the --setvfofreq option.

--getvcosplit

Retrieve the transmit and receive VCO splits (v-bit shift frequencies) currently being used by the xcat. The Syntor X VCO operates in several frequency ranges, typically two for transmit and two for receive. The VCO splits determine at which frequency the radio shifts from using the lower range to the upper range.

--setvcosplit

Set the VCO splits to the values specified by the --txvcosplit and --rxvcosplit options. There are no defaults for the splits, and specifying --setvcosplit without also specifying --txvcosplit and -B --rxvcosplit is an error. Note that these values do not cause any immediate change in the operation of the radio. The value is only used by the xcat in calculating new data when a frequency is set using the --setvfofreq option.

--txvcosplit splitfreq

Make splitfreq the transmit VCO split frequency to be loaded into the xcat by the --setvcosplit option. The frequency should be specified in megahertz.

--rxvcosplit splitfreq

Make splitfreq the receive VCO split frequency to be loaded into the xcat by the --setvcosplit option. The frequency should be specified in megahertz.

--radioband { 10 | 10+6 | 6 | 440 }

Set the values in the config word which will be sent to the xcat by --setconfig to indicate in which band of radio the board is installed. For VHF-HI radios, use "440".

--sendcos { yes | no }

Set the values in the config word which will be sent to the xcat by --setconfig to indicate whether the xcat should send or not send indications of channel activity to the attached computer. These notifications are asynchronous. Note that xcatctl does not have any mechanism for dealing with such notifications.

--controlsys { none | doughall | generic | palomar | cactus }

Set the values in the config word which will be sent to the xcat by --setconfig to indicate which type of control system will be connected to the xcat. The CI-V interface on the xcat is always active.

--io0 .. --io7 { user | alternate }

Set the values in the config word which will be sent to the xcat by --setconfig to indicate how the xcat should configure its I/O pins. See the xcat documentation for information on what the alternate functions of the pins are.

--toaddr civaddr

Set the CI-V address used by the xcat board. The default is 0x20, and the only way to change the board is by hacking on its firmware.

--fromaddr civaddr

Set the CI-V address to be used by xcatctl. The default is 0xe0.

--serialport serialdevice

Set to serialdevice the name of the serial device (COM port) on the computer running xcatctl to which the xcat is connected.

The program may emit any of the following diagnostic messages:

--setmode argument must be between 1 and 32"

Legal mode (channel) numbers are 1 to 32. You specified something outside that range.

--setduplex argument must be ’simplex’, ’negative’ or ’positive’

Legal duplex values are as shown. You specified something else.

nnn.n is not a valid pl; will try anyway

You specified a non-standard PL. The program will try to set it anyway. The Syntor X radio is capable of generating arbitrary non-standard PLs, though the use of such PLs would be a bad idea in most circumstances. In any event, the xcat board does enforce use of valid PLs, so the attempt will probably fail.

--radioband argument must be ’10’, ’10+6’, ’6’ or ’440’

Valid configuration values for radio band are as shown. You specified something else.

--sendcos argument must be ’yes’ or ’no’

The carrier operated squelch messages configuration setting must be set to yes or no. You specified something else.

--controlsys argument must be ’none’, ’doughall’, ’generic’, ’palomar’ or ’cactus’

The control system configuration setting must be set to one of the above. You specified something else. Note that CI-V is always active.

--io0..--io7 argument must be ’user’or ’alternate’

Valid values for the --io0 through --io7 options are as shown. You specified something else.

invalid baud rate 38400

You specified a baud rate which is not supported by the operating system. The xcat usually runs at 19200; try that.

logic error in command line parser, index nnn

The program has a bug. Please report what you did to expose it.

unrecognized option index nnn value xxx

The program has a bug. Please report what you did to expose it.

You must specify --txvcosplit and --rxvcosplit with --setvcosplit

The --setvcosplit option must be specified with the --txvcosplit and --rxvcosplit options, or it will have no split frequencies to store into the xcat board.

logic error in dispatcher, index nnn

The program has a bug. Please report what you did to expose it.

Invalid argument (EINVAL)

This error may be caused by several things: selecting an invalid CI-V address, a serial communications problem, a broken xcat board, insufficient data in a code plug you tried to load, or an out-of-range value you tried to set into the xcat and which the program didn’t specifically check for.

No space left on device (ENOSPC)

Indicates a programming error in xcatctl.

Connection timed out (ETIMEDOUT)

The xcat board didn’t respond to a command within 30 seconds. This may mean the board isn’t connected, serial parameters are wrong, etc.

Broken pipe (EPIPE)

Data from the xcat was reported to be available, but could not be read by the program. If you see this, something is seriously wrong with your system.

In addition, xcatctl may fail for any of the reasons listed in the man pages for the open(2), tcgetattr(2), cfsetispeed(2), cfsetospeed(2), tcsetattr(2), write(2), select(2), or read(2), man pages.

If successful, xcatctl exits with a return code of 0. Most errors cause it to return the standard system error code related to the problem. Specifically, invalid parameters in most cases result in an exit status of 22; timeouts result in 110.

The default values for the configuration bits set the xcat for 440 radios, no COS messages, no control system, and all I/O pins for user functions.

The default serial port is /dev/ttyS0.

The default CI-V address for the xcat is 0x20. The default address for xcatctl is 0xe0.

Doubtless there are many.

The xcat board recognizes the following PL frequencies as standard:

67.0, 69.3, 71.9, 74.4, 77.0, 79.7, 82.5, 85.4, 88.5, 91.5, 94.8, 97.4, 100.0, 103.5, 107.2, 110.9, 114.8, 118.8, 123.0, 127.3, 131.8, 136.5, 141.3, 146.2, 151.4, 156.7, 162.2, 167.9, 173.8, 179.9, 186.2, 192.8, 203.5, 206.5, 210.7, 218.1, 225.7, 229.1, 233.6, 241.8, 250.3, 254.1

Dennis Boone <jm-sxg at yagi.h-net.msu.edu>

loadplug(1), syntorxgen(1)