Included with the Hamlib distribution are several utility programs. Besides providing a way for developers to test new code and bug fixes, the programs also offer a reference implementation for interfacing to the Hamlib library functions both through the C API and offering a network accessible API.

This chapter focuses on the two test programs, rigctl for testing radio back ends and rotctl for testing rotor back ends and the two network daemons, rigctld and rotcltd for radio and rotor access via network sockets.

rigctl
======

rigctl is the most frequently used Hamlib utility.  As the other utilities share many of the same characteristics, much of the introductory information presented in this section is applicable to the other utility programs.

Introduction to rigctl
----------------------

Most likely the first of the Hamlib utility programs that is used is rigctl.  rigctl is a character based interactive program and a command line program able to set or query a radio's value with a single command.  rigctl is invoked from a shell command prompt with various options and additional commands.

In its most simple use as a command line program, rigctl is used to set frequency and mode by typing commands after any rigctl options:

     rigctl F 14205000
     rigctl M USB 2400

and then query those values:

     rigctl f
     rigctl m

Entering interactive mode is a simple matter of not placing any commands after any rigctl options:

     rigctl

Entering interactive mode allows successive commands to be entered without exiting rigctl.  Recent additions to rigctl allow command editing and history recall through use of the Readline (http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html) library.

Interactive mode is indicated by the spartan prompt:

     Rig command:

Commands are given at the prompt and follow the general rule that upper case letters set a value and lower case letters query a value:

     Rig command: M
     Mode: USB
     Passband: 2500

     Rig command: m
     Mode: USB
     Passband: 2500

     Rig command:

An additional prompt is printed when more information is required by the command.  For M above, rigctl prompted for the ``Mode'' and ``Passband'' values.  For m above, rigctl returned the ``Mode'' and ``Passband'' values without further prompts. The command prompt is returned after each command invocation.

The above examples invoked rigctl without specifying a radio model.  This is a feature where the Hamlib internal radio dummy is used instead.  The dummy radio provides a way to test Hamlib functions with out the need for actual radio hardware.  However, to develop back end capability for a given radio, having the actual radio connected to the computer is necessary for debugging.

For example, to quickly set frequency on an Elecraft K3:

     rigctl -m 229 -r /dev/rig F 3900000

and to query the frequency and then mode:

     rigctl -m 229 -r /dev/rig f
     3900000

     rigctl -m 229 -r /dev/rig m
     LSB
     2000

The returned values do not have the prompt strings associated with interactive mode as shown above.

The -m option takes a numeric value that corresponds to a given radio back end model.  The -r option takes the path to the port device on POSIX and the device name on MS Windows.

     A complete list of supported radio models may be seen by use of the -l option:

          rigctl -l
           Rig #  Mfg              Model         Version    Status
               1  Hamlib           Dummy         0.5        Beta
               2  Hamlib           NET rigctl    0.3        Beta
             101  Yaesu            FT-847        0.5        Beta
             103  Yaesu            FT-1000D      0.0.6      Alpha
          .
          .
          .
            2702  Rohde&Schwarz    EB200         0.1        Untested
            2801  Philips/Simoco   PRM8060       0.1        Alpha
            2901  ADAT www.adat.ch ADT-200A      1.36       Beta

     The list is long so use SHIFT-PageUp/ SHIFT-PageDown on Linux, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual terminal window (cmd window on MS Windows) or the output can be piped to 'more' or 'less', e.g. 'rigctl -l | more' to scroll back up the list.  The list is sorted numerically by model number since Hamlib 1.2.15.1.  Model numbers of a manufacturer/ protocol family are grouped together.

rigctl invocation
-----------------

Here are some additional examples for invoking rigctl for various situations.

Start rigctl for a Yaesu FT-920 using a USB to serial adapter on Linux in interactive mode:

     rigctl -m 114 -r /dev/ttyUSB1

Start rigctl for a Yaesu FT-920 using COM1 on MS Windows while generating TRACE output to stderr:

     rigctl -m 114 -r COM1 -vvvvv

Start rigctl for a Yaesu FT-920 using a USB to serial adapter on Linux while setting baud rate and stop bits:

     rigctl -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2

Start rigctl for an Elecraft K3 using a USB to serial adapter on Linux while specifying a command terminator for the w command:

     rigctl -m 229 -r /dev/ttyUSB0 -t';'

Connect to a running rigctld with radio model 2 (NET rigctl) on the local host and specifying the TCP port, setting frequency and mode:

     rigctl -m 2 -r localhost:4532 F 7253500 M LSB 0

N.B. On MS Windows localhost may need to be replaced with the actual loopback IP address--127.0.0.1--or the address passed to rigctld with the -T option.

rigctl command line options
---------------------------

The rigctl command line options (not to be confused with rigctl commands) control the action of various features. Options consist of both ``short options''--a single hyphen '-' followed by a single letter and ``long options''--two hyphens '--' followed by several letters often comprising one or more words separated by a hyphen.

rigctl accepts the following options:

-m
--model=ID
     Select radio model number. See model list (use rigctl -l).

     N.B. rigctl (or third party software) will use rig model 2 for NET rigctl (rigctld).

-r
--rig-file=DEVICE
     Use DEVICE as the file name of the port the radio is connected. Often a serial port, but could be a USB to serial adapter.  Typically /dev/ttyS0 , /dev/ttyS1 , /dev/ttyUSB0 , etc. on Linux or COM1 , COM2 , etc. on MS Windows.

-p
--ptt-file=DEVICE
     Use DEVICE as the file name of the Push-To-Talk device using a device file as described above.

-d
--dcd-file=DEVICE
     Use DEVICE as the file name of the Data Carrier Detect device using a device file as described above.

-P
--ptt-type=TYPE
     Use TYPE of Push-To-Talk device.  Supported types are RIG, DTR, RTS, PARALLEL, NONE, overriding PTT type defined in the rig's backend.

     Some side effects of this command are that when type is set to DTR, read PTT state comes from Hamlib frontend, not read from the radio.  When set to NONE, PTT state cannot be read or set even if rig backend supports reading/setting PTT status from the rig.

-D
--dcd-type=TYPE
     Use TYPE of Data Carrier Detect device.  Supported types are RIG (CAT command), DSR, CTS, CD, PARALLEL, NONE.

-s
--serial-speed=BAUD
     Set serial speed to BAUD rate. Uses maximum serial speed from rig backend capabilities (set by -m above) as the default.

-c
--civaddr=ID
     Use ID as the CI-V address to communicate with the rig. Only useful for Icom radios and those using the Icom protocol.

     N.B. The ID is in decimal notation, unless prefixed by 0x, in which case it is a hexadecimal value.

-t
--send-cmd-term=CHAR
     Change the termination CHAR for text protocol when using the send_cmd command.  The default value is <CR> (0x0d). Non ASCII printable characters can be specified as an ASCII number, in hexadecimal format, prepended with 0x. You may pass an empty string for no termination char. The string '-1' tells rigctl to switch to binary protocol. See the send_cmd command for further explanation.

-L
--show-conf
     List all config parameters for the radio defined with -m above.

-C
--set-conf=PARM=VAL[,PARM=VAL,...]
     Set config parameter. e.g. stop_bits=2

     Use -L option for a list.

-l
--list
     List all model numbers defined in Hamlib and exit.  As of 1.2.15.1 the list is sorted by model number.

     N.B. In Linux the list can be scrolled back using SHIFT-PageUp/ SHIFT-PageDown, or using the scrollbars of a virtual terminal in X or the cmd window in MS Windows.  The output can be piped to 'more' or 'less', e.g. 'rigctl -l | more'.

-u
--dump-caps
     Dump capabilities for the radio defined with -m above and exit.

-o
--vfo
     Set vfo mode, requiring an extra VFO argument in front of each appropriate command (except set_vfo!). Otherwise, currVFO is assumed when this option is not set and an extra VFO argument is not used.  See chk_vfo below.

-i
--read-history
     Read previously saved command and argument history from a file (default '~/.rigctl_history') for the current session. Available when rigctl is built with Readline support.

     N.B. To read a history file stored in another directory, set the RIGCTL_HIST_DIR environment variable, e.g. 'RIGCTL_HIST_DIR=~/tmp rigctl -i'.  When RIGCTL_HIST_DIR is not set, the value of HOME is used.

-I
--save-history
     Write current session (and previously saved session(s) if -i option is also given) command and argument history to a file (default '~/.rigctl_history') at the end of the current session. Complete commands with arguments are saved as a single line to be recalled and used or edited.  Available when rigctl is built with Readline support.

     To write a history file in another directory, set the RIGCTL_HIST_DIR environment variable, e.g. 'RIGCTL_HIST_DIR=~/tmp rigctl -I'.  When RIGCTL_HIST_DIR is not set, the value of HOME is used.

-v
--verbose
     Set verbose mode level, cumulative i.e. -vvvvv sets maximum debugging output to stderr.

     Five different levels of diagnostics can be output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.  Back end authors will use the verbose facility to print critical values useful for testing and will often ask for this output in response to a request for help.

-h
--help
     Show summary of these options and exit.

-V
--version
     Show version of rigctl and exit.

     Some options may not be implemented by a given backend and will return an error.  This is most likely to occur with the --set-conf and --show-conf options.

rigctl commands
---------------

Commands can be entered either as a single char, or as a long command name.  Basically, the commands do not take a dash in front of them on the command line, as the options do. They may be typed in when in interactive mode or provided as argument(s) in command line interface mode.  In interactive mode commands and their arguments may be entered on a single line:

     Rig command: M LSB 2400

or singly and rigctl will prompt for any needed values.

Since most of the Hamlib operations have a ``set'' and a ``get'' method, in general an upper case letter will be used for set methods whereas the corresponding lower case letter refers to the get method. Each operation also has a long name; prepend a backslash \ to enter a long command name.

     Example: Use \dump_caps to see what this radio can do.

Be aware that the backend for the radio to be controlled, or the radio itself may not support some commands. In that case, the operation will fail with a Hamlib error message.

Here is a summary of the supported commands:

  * Command short name is followed by the long name which is followed by any variable names.

  * Some short commands are noted as hexadecimal digits due to the limitation of upper and lower case letters available.  Use the associated long command name instead.

  * While a comma is used to separate variable names in this document, they are not part of the command syntax used by rigctl.  Use a space to separate values.

  * In the case of ``set'' commands the variable NAME is replaced by the value in the description.

  * In the case of ``get'' commands the variable NAME is the key name of the value returned.

q
     Exit rigctl in interactive mode (q is not case sensitive).

     When rigctl is controlling the rig directly, will close the rig back end and port.  When rigctl is connected to rigctld (rig model 2), the TCP/IP connection to rigctld is closed and rigctld remains running, available for another TCP/IP network connection.

F, set_freq FREQUENCY
     Set FREQUENCY, in Hertz.

f, get_freq
     Get FREQUENCY, in Hertz.

M, set_mode MODE, PASSBAND
     Set MODE to one of: USB, LSB, CW, CWR, RTTY, RTTYR, AM, FM, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.

     Set PASSBAND frequency in Hertz, or 0 for the Hamlib backend default.

     N.B. Passing a ? (query) as the first argument instead of MODE will return a space separated list of radio backend supported Modes.  Use this to determine the supported Modes of a given radio backend.

m, get_mode
     Get MODE, PASSBAND.

     Returns Mode as a string from set_mode above and Passband frequency in Hertz.

V, set_vfo VFO
     Set VFO to one of: VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub, TX, RX.

     In VFO mode only a single VFO parameter is required.

v, get_vfo
     Get current VFO.

     Returns VFO as a string from set_vfo above.

J, set_rit RIT
     Set RIT, in Hertz, can be a positive or negative value.

     A value of 0 resets RIT and should turn RIT off.  If not, file a bug report against the Hamlib backend.

     N.B. This functionality is under transition and in the future will need to be activated with the set_func command.

j, get_rit
     Get RIT, in Hertz.

Z, set_xit XIT
     Set XIT, in Hertz, can be a positive or negative value.

     A value of 0 resets XIT and should turn XIT off.  If not, file a bug report against the Hamlib backend.

     N.B. This functionality is under transition and in the future will need to be activated with the set_func command.

z, get_xit
     Get XIT, in Hertz.

T, set_ptt PTT
     Set PTT to one of: 0 (RX), 1 (TX), 2 (TX mic), 3 (TX data).

t, get_ptt
     Get PTT status.

0x8b, get_dcd
     Get DCD (squelch) status, 0 (Closed) or 1 (Open)

R, set_rptr_shift RPTR SHIFT
     Set RPTR SHIFT: +, - or something else for none.

r, get_rptr_shift
     Get RPTR SHIFT.  Returns +, - or None.

O, set_rptr_offs RPTR OFFSET
     Set RPTR OFFSET, in Hertz.

o, get_rptr_offs
     Get RPTR OFFSET, in Hertz.

C, set_ctcss_tone CTCSS TONE
     Set CTCSS TONE, in tenths of Hertz.

     CTCSS, Continuous Tone Coded Squelch System (http://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System), is a method used to reduce the annoyance of listening to other users on a shared two-way communications radio channel by imposing a tone on the transmitted signal.  Also known as subaudible tone and PL, Private Line.

c, get_ctcss_tone
     Get CTCSS TONE, in tenths of Hertz.

D, set_dcs_code DCS CODE
     Set DCS CODE.

     DCS, Digital-Coded Squelch (http://en.wikipedia.org/wiki/Digital-Coded_Squelch#DCS) is a digital version of CTCSS which imposes a digital code on the transmitted signal.

d, get_dcs_code
     Get DCS CODE.

0x90, set_ctcss_sql CTCSS SQL
     Set CTCSS SQL tone, in tenths of Hertz.

0x91, get_ctcss_sql
     Get CTCSS SQL tone, in tenths of Hertz.

0x92, set_dcs_sql DCS SQL
     Set DCS SQL code.

0x93, get_dcs_sql
     Get DCS SQL code.

I, set_split_freq TX FREQUENCY
     Set TX FREQUENCY, in Hertz for ``split'' frequency operation.

i, get_split_freq
     Get TX FREQUENCY, in Hertz for ``split'' frequency operation.

X, set_split_mode TX MODE, TX PASSBAND
     Set TX MODE to one of: AM, FM, CW, CWR, USB, LSB, RTTY, RTTYR, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.

     The TX PASSBAND is the exact passband frequency in Hertz, or 0 for the Hamlib backend default.

     N.B. Passing a ? (query) as the first argument instead of TX MODE will return a space separated list of radio backend supported TX Modes.  Use this to determine the supported TX Modes of a given radio backend.

x, get_split_mode
     Get TX MODE, TX PASSBAND.

     Returns TX mode as a string from set_split_mode above and TX passband in Hz.

S, set_split_vfo SPLIT, TX VFO
     Set SPLIT mode, 0 (off) or 1 (on), and TX VFO from set_vfo above.

s, get_split_vfo
     Get SPLIT mode, 0 (off) or 1 (on), and TX VFO.

N, set_ts TUNING STEP
     Set TUNING STEP, in Hertz.

n, get_ts
     Get TUNING STEP, in Hertz.

U, set_func FUNC, FUNC STATUS
     Set FUNC, FUNC STATUS.

     FUNC is one of: FAGC, NB, COMP, VOX, TONE, TSQL, SBKIN, FBKIN, ANF, NR, AIP, APF, MON, MN, RF, ARO, LOCK, MUTE, VSC, REV, SQL, ABM, BC, MBC, RIT, AFC, SATMODE, SCOPE, RESUME, TBURST, TUNER, XIT.

     Func Status argument is 1 for ``activate'', 0 for ``de-activate'', much as TRUE/FALSE definitions in the C/C++ languages (true is non-zero and false is zero).

     N.B.  Passing a ? (query) as the first argument instead of FUNC will return a space separated list of radio backend supported ``set'' functions.  Use this to determine the supported functions of a given radio backend.

u, get_func FUNC
     Get FUNC STATUS.

     Returns FUNC STATUS as a non null value for the FUNC passed. FUNC is a token from the list in set_func above.

     N.B. Passing a ? (query) as the first argument instead of FUNC will return a space separated list of radio backend supported ``get'' functions.  Use this to determine the supported functions of a given radio backend.

L, set_level LEVEL, LEVEL VALUE
     Set LEVEL, LEVEL VALUE.

     LEVEL is one of: PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR, PBT_IN, PBT_OUT, CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF, COMP, AGC(0:OFF, 1:SUPERFAST, 2:FAST, 3:SLOW, 4:USER, 5:MEDIUM, 6:AUTO), BKINDL, BAL, METER, VOXGAIN, ANTIVOX, SLOPE_LOW, SLOPE_HIGH, RAWSTR, SWR, ALC, STRENGTH.

     The LEVEL VALUE can be a float or an integer.

     N.B. Passing a ? (query) as the first argument instead of LEVEL will return a space separated list of radio backend supported ``set'' levels.  Use this to determine the supported levels of a given radio backend.

l, get_level LEVEL
     Get LEVEL VALUE.

     Returns LEVEL VALUE as a float or integer for the LEVEL passed.  LEVEL is a token from the list in set_level above.

     N.B. Passing a ? (query) as the first argument instead of LEVEL will return a space separated list of radio backend supported ``get'' levels.  Use this to determine the supported levels of a given radio backend.

P, set_parm PARM, PARM VALUE
     Set PARM, PARM VALUE

     PARM is one of: ANN, APO, BACKLIGHT, BEEP, TIME, BAT, KEYLIGHT.

     N.B.  Passing a ? (query) as the first argument instead of PARM will return a space separated list of radio backend supported ``set'' parameters.  Use this to determine the supported parameters of a given radio backend.

p, get_parm PARM
     Get PARM VALUE.

     Returns PARM VALUE as a float or integer for the PARM passed.  PARM is a token from the list in set_parm above.

     N.B.  Passing a ? (query) as the first argument instead of PARM will return a space separated list of radio backend supported ``get'' parameters.  Use this to determine the supported parameters of a given radio backend.

B, set_bank BANK
     Set BANK.  Sets the current memory bank number.

E, set_mem MEMORY#
     Set MEMORY# channel number.

e, get_mem
     Get MEMORY# channel number.

G, vfo_op MEM/VFO OP
     Perform MEM/VFO OP.

     MEM/VFO OPeration is one of: CPY, XCHG, FROM_VFO, TO_VFO, MCL, UP, DOWN, BAND_UP, BAND_DOWN, LEFT, RIGHT, TUNE, TOGGLE.

     N.B. Passing a ? (query) as the first argument instead of MEM/VFO OP will return a space separated list of radio backend supported ``set'' Mem/VFO Ops.  Use this to determine the supported Mem/VFO Ops of a given radio backend.

g, scan SCAN FCT, SCAN CHANNEL
     Perform SCAN FCT SCAN CHANNEL.

     Scan function/channel is one of: STOP, MEM, SLCT, PRIO, PROG, DELTA, VFO, PLT.

     N.B. Passing a ? (query) as the first argument instead of SCAN FCT will return a space separated list of radio backend supported Scan Functions.  Use this to determine the supported Scan Functions of a given radio backend.

H, set_channel CHANNEL
     Set memory CHANNEL data. Not implemented yet.

h, get_channel
     Get memory CHANNEL data. Not implemented yet.

A, set_trn TRANSCEIVE
     Set TRANSCEIVE mode (reporting event): OFF, RIG, POLL.

     N.B. Passing a ? (query) as the first argument instead of TRANSCEIVE will return a space separated list of radio backend supported Scan Transceive modes.  Use this to determine the supported Transceive modes of a given radio backend.

a, get_trn
     Get TRANSCEIVE mode (reporting event) as in set_trn above.

Y, set_ant ANTENNA
     Set ANTENNA number (0, 1, 2, ...).

y, get_ant
     Get ANTENNA number (0, 1, 2, ...).

*, reset RESET
     Perform rig RESET.

     0 = None, 1 = Software reset, 2 = VFO reset, 4 = Memory Clear reset, 8 = Master reset.  Since these values are defined as a bitmask in rig.h, it should be possible to AND these values together to do multiple resets at once, if the backend supports it or supports a reset action via rig control at all.

b, send_morse MORSE
     Send MORSE symbols.

0x87, set_powerstat POWER STATUS
     Set power On/Off/Standby POWER STATUS.

     0 = Power Off, 1 = Power On, 2 = Power Standby. Defined as a bitmask in rig.h.

0x88, get_powerstat
     Get power On/Off/Standby POWER STATUS as in set_powerstat above.

0x89, send_dtmf DIGITS
     Set DTMF DIGITS.

0x8a, recv_dtmf
     Get DTMF DIGITS.

_, get_info
     Get misc information about the rig

     VFO parameter not used in 'VFO mode'.

1, dump_caps
     Not a real rig remote command, it just dumps capabilities, i.e. what the backend knows about this model, and what it can do.

     TODO: Ensure this is in a consistent format so it can be read into a hash, dictionary, etc.  Bug reports requested.

     N.B. This command will produce many lines of output so be very careful if using a fixed length array!  For example, running this command against the Dummy backend results in over 5kB of text output.

     VFO parameter not used in 'VFO mode'.

2, power2mW POWER 0.0..1.0, FREQUENCY, MODE
     Returns POWER MW

     Converts a POWER value in a range of 0.0..1.0 to the real transmit power in milli-Watts (integer).  The FREQUENCY and MODE also need to be provided as output power may vary according to these values.

     VFO parameter not used in 'VFO mode'.

4, mW2power POWER MW, FREQUENCY, MODE
     Returns POWER 0.0..1.0

     Converts the real transmit power in milli-Watts (integer) to a POWER value in a range of [0.0..1.0].  The FREQUENCY and MODE also need to be provided as output power may vary according to these values.

     VFO parameter not used in 'VFO mode'.

w, send_cmd CMD
     Send raw command string to rig.  This is useful for testing and troubleshooting rig commands and responses when developing a backend.

     For binary protocols enter values as \0xAA\0xBB.  Expect a REPLY from the rig which will likely be a binary block or an ASCII string depending on the rig's protocol (see your radio's computer control documentation).

     The command terminator, set by the --send-cmd-term option above, will terminate each command string sent to the radio.  This character should not be a part of the input string.

rigctl Readline support
-----------------------

If Readline library development files are found at configure time, rigctl will be conditonally built with Readline support for command and argument entry.  Readline command key bindings are at their defaults as described in the Readline manual (http://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html) although rigctl sets the name rigctl which can be used in Conditional Init Constructs in the Readline Init File (~/.inputrc by default) for custom keybindings unique to rigctl.

Command history is available with Readline support as described in the Readline History manual (http://cnswww.cns.cwru.edu/php/chet/readline/history.html#SEC1).  Command and argument strings are stored as single lines even when arguments are prompted for input individually. Commands and arguments are not validated and are stored as typed with values separated by a single space.

Normally session history is not saved, however, use of either of the -i/--read-history or -I/--save-history options when starting rigctl will cause any previously saved history to be read in and/or the current and any previous session history (assuming the -i and -I options are given together) will be written out when rigctl is closed.  Each option is mutually exclusive, i.e. either may be given separately or in combination. This is useful to save a set of commands and then read them later but not write the modified history for a consistent set of test commands in interactive mode, for example.

History is stored in ~/.rigctl_history by default although the destination directory may be changed by setting the RIGCTL_HIST_DIR environment variable.  When RIGCTL_HIST_DIR is unset, the value of the HOME environment variable is used instead.  Only the destination directory may be changed at this time.

If Readline support is not found at configure time the original internal command handler is used.  Readline is not used for rigctl commands entered on the command line regardless if Readline support is built in or not.

     Readline support is not included in the MS Windows 32 binary builds supplied by the Hamlib Project.  Running rigctl on the MS Windows 32 platform in the cmd shell does give session command line history, however, it is not saved to disk between sessions.

rotctl
======

Identical in function to rigctl, rotctl provides a means for testing Hamlib functions useful for rotor control and QRA locator computations.  As rotors have a much narrower scope than radios, there are fewer command line options and commands for rotctl.

Introduction to rotctl
----------------------

rotctl is a character based interactive program and a command line program able to set or query a rotor's value with a single command.  rotctl is invoked from a shell command prompt with various options and additional commands.

In its most simple use as a command line program, rotctl is used to set frequency and mode by typing commands after any rotctl options:

     rotctl P 145.0 23.0
     rotctl M 8 25

and then query those values:

     rotctl p

Entering interactive mode is a simple matter of not placing any commands after any rotctl options:

     rotctl

Entering interactive mode allows successive commands to be entered without exiting rotctl.  Recent additions to rotctl allow command editing and history recall through use of the Readline (http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html) library.

Interactive mode is indicated by the spartan prompt:

     Rotator command:

Commands are given at the prompt:

     Rotator command: M
     Direction: 16
     Speed: 60

     Rotator command: p
     Azimuth: 11.352000
     Elevation: 0.000000

     Rotator command: p
     Azimuth: 27.594000
     Elevation: 0.000000

     Rotator command:

An additional prompt is printed when more information is required by the command.  For M above, rotctl prompted for the ``Direction'' and ``Speed'' values.  For p above, rotctl returned the ``Azimuth'' and ``Elevation'' values without further prompts. The command prompt is returned after each command invocation.

The above examples invoked rotctl without specifying a rotor model.  This is a feature where the Hamlib internal rotor dummy is used instead.  The dummy rotor provides a way to test Hamlib functions with out the need for actual rotor hardware.  However, to develop back end capability for a given rotor, having the actual radio connected to the computer is necessary for debugging.

For example, to quickly set position for RotorEZ:

     rotctl -m 401 -r /dev/rotor P 100.0 0.0

and to query the position:

     rotctl -m 401 -r /dev/rotor p
     100.000000
     0.000000

The returned values do not have the prompt strings associated with interactive mode as shown above.

The -m option takes a numeric value that corresponds to a given rotor back end model.  The -r option takes the path to the port device on POSIX and the device name on MS Windows.

     A complete list of supported radio models may be seen by use of the -l option:

          rotctl -l
           Rig #  Mfg              Model         Version    Status
               1  Hamlib           Dummy         0.5        Beta
               2  Hamlib           NET rotctl    0.3        Beta
             201  Hamlib           EasycommI     0.3        Beta
             202  Hamlib           EasycommII    0.3        Beta
          .
          .
          .
            1201  AMSAT            IF-100        0.1        Untested
            1301  LA7LKA           ts7400        0.1        Beta
            1401  Celestron        NexStar       0.1        Untested

     The list is long so use SHIFT-PageUp/ SHIFT-PageDown on Linux, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual terminal window (cmd window on MS Windows) or the output can be piped to 'more' or 'less', e.g. 'rotctl -l | more' to scroll back up the list.  The list is sorted numerically by model number since Hamlib 1.2.15.1.  Model numbers of a manufacturer/ protocol family are grouped together.

rotctl invocation
-----------------

Here are some additional examples for invoking rotctl for various situations.

Start rotctl for RotorEZ using the first serial port on Linux:

     rotctl -m 401 -r /dev/ttyS0

Start rotctl for RotorEZ using COM2 on MS Windows:

     rotctl -m 401 -r COM2

Connect to a running rotctld with rotor model 2 (NET rotctl) on the local host and specifying the TCP port, and querying the position:

     rotctl -m 2 -r localhost:4533 \get_pos

rotctl command line options
---------------------------

rotctl accepts the following options:

-m
--model=ID
     Select rotator model number. See model list (use rotctl -l).

     N.B. rotctl (or third party software) will use rotor model 2 for NET rotctl (rotctld).

-r
--rig-file=DEVICE
     Use DEVICE as the file name of the port the rotor is connected. Often a serial port, but could be a USB to serial adapter.  Typically /dev/ttyS0 , /dev/ttyS1 , /dev/ttyUSB0 , etc. on Linux or COM1 , COM2 , etc. on MS Windows.

-s
--serial-speed=BAUD
     Set serial speed to BAUD rate. Uses maximum serial speed from rotor backend capabilities as the default.

-t
--send-cmd-term=CHAR
     Change the termination CHAR for text protocol when using the send_cmd command.  The default value is <CR> (0x0d). Non ASCII printable characters can be specified as an ASCII number, in hexadecimal format, prepended with 0x. You may pass an empty string for no termination char. The string '-1' tells rotctl to switch to binary protocol. See the send_cmd command for further explanation.

-L
--show-conf
     List all config parameters for the rotor defined with -m above.

-C
--set-conf=PARM=VAL[,PARM=VAL,...]
     Set config parameter. e.g. stop_bits=2

     Use -L option for a list.

-l
--list
     List all model numbers defined in Hamlib and exit.  As of 1.2.15.1 the list is sorted by model number.

     N.B. In Linux the list can be scrolled back using SHIFT-PageUp/ SHIFT-PageDown, or using the scrollbars of a virtual terminal in X or the cmd window in MS Windows.  The output can be piped to 'more' or 'less', e.g. 'rotctl -l | more'.

-u
--dump-caps
     Dump capabilities for the rotor defined with -m above and exit.

-i
--read-history
     Read previously saved command and argument history from a file (default '~/.rotctl_history') for the current session. Available when rotctl is built with Readline support.

     N.B. To read a history file stored in another directory, set the ROTCTL_HIST_DIR environment variable, e.g. 'ROTCTL_HIST_DIR=~/tmp rotctl -i'.  When ROTCTL_HIST_DIR is not set, the value of HOME is used.

-I
--save-history
     Write current session (and previously saved session(s) if -i option is also given) command and argument history to a file (default '~/.rotctl_history') at the end of the current session. Complete commands with arguments are saved as a single line to be recalled and used or edited.  Available when rotctl is built with Readline support.

     To write a history file in another directory, set the ROTCTL_HIST_DIR environment variable, e.g. 'ROTCTL_HIST_DIR=~/tmp rotctl -I'.  When ROTCTL_HIST_DIR is not set, the value of HOME is used.

-v
--verbose
     Set verbose mode level, cumulative i.e. -vvvvv sets maximum debugging output to stderr.

     Five different levels of diagnostics can be output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.  Back end authors will use the verbose facility to print critical values useful for testing and will often ask for this output in response to a request for help.

-h
--help
     Show summary of these options and exit.

-V
--version
     Show version of rotctl and exit.

     Some options may not be implemented by a given backend and will return an error.  This is most likely to occur with the --set-conf and --show-conf options.

rotctl commands
---------------

See rigctl commands, for command syntax.

Rotor commands

Here is a summary of the supported commands:

q
     Exit rotctl in interactive mode (q is not case sensitive).

     When rotctl is controlling the rotor directly, will close the rotor back end and port.  When rotctl is connected to rotctld (rotor model 2), the TCP/IP connection to rotctld is closed and rotctld remains running, available for another TCP/IP network connection.

P, set_pos AZIMUTH, ELEVATION
     Set position: AZIMUTH and ELEVATION as double precision floating point values.

p, get_pos
     Get position: AZIMUTH and ELEVATION as double precision floating point values.

M, move DIRECTION, SPEED
     Move the rotator in a specific direction at the given rate.

     Values are integers where DIRECTION is defined as 2 = Up, 4 = Down, 8 = Left, and 16 = Right.  SPEED is an integer between 1 and 100.

     N.B. Not all backends that implement the move command use the Speed value.  At this time only the gs232a utilizes the Speed parameter.

S, stop
     Stop the rotator.

K, park
     Park the antenna.

C, set_conf TOKEN, VALUE
     Set a configuration parameter.  It is safe to give TOKEN a value of 0 (zero).  VALUE may be a string up to 20 characters.

     See -L output.

R, reset RESET
     Reset the rotator.

     Integer value of 1 for Reset All.

_, get_info
     Get misc information on the rotator.

     At the moment returns MODEL NAME.

w, send_cmd CMD
     Send raw command string to the rotator.

     <CR> (or send-cmd-term, see -t option) is appended automatically at the end of the command for text protocols. For binary protocols, enter values as \0xAA\0xBB.

Locator Commands

These commands offer conversions of Degrees Minutes Seconds to other formats, Maidenhead square locator conversions and distance and azimuth conversions.

L, lonlat2loc LONGITUDE, LATITUDE, LOC LEN 2..12
     Returns the Maidenhead locator for the given LONGITUDE and LATITUDE.

     Both are floating point values.  The precision of the returned square is controlled by LOC LEN which should be an even numbered integer value between 2 and 12.

     For example, L -170.000000 -85.000000 12 returns Locator: AA55AA00AA00.

l, loc2lonlat LOCATOR
     Returns LONGITUDE and LATITUDE in decimal degrees at the approximate center of the requested grid square (despite the use of double precision variables internally, some rounding error occurs). West longitude is expressed as a negative value.  South latitude is expressed as a negative value.  Locator can be from 2 to 12 characters in length.

     For example, l AA55AA00AA00 returns Longitude: -169.999983 Latitude: -84.999991.

D, dms2dec DEGREES, MINUTES, SECONDS, S/W
     Returns DEC DEGREES, a signed floating point value.

     DEGREES and MINUTES are integer values and SECONDS is a floating point value.  S/W is a flag with 1 indicating South latitude or West longitude and 0 North or East (the flag is needed as computers don't recognize a signed zero even though only the DEGREES value only is typically signed in DMS notation).

d, dec2dms DEC DEGREES
     Returns DEGREES, MINUTES, SECONDS, S/W.

     Values are as in dms2dec above.

E, dmmm2dec DEGREES, DEC MINUTES, S/W
     Returns DEC DEGREES, a signed floating point value.

     DEGREES is an integer value and MINUTES is a floating point value.  S/W is a flag with 1 indicating South latitude or West longitude and 0 North or East (the flag is needed as computers don't recognize a signed zero even though only the DEGREES value only is typically signed in DMS notation).

e, dec2dmmm DEC DEG
     Returns DEGREES, MINUTES, S/W.

     Values are as in dmmm2dec above.

B, qrb LON 1, LAT 1, LON 2, LAT 2
     Returns DISTANCE and AZIMUTH where DISTANCE is in km and AZIMUTH is in degrees.

     All LON/LAT values are signed floating point numbers.

A, a_sp2a_lp SHORT PATH DEG
     Returns LONG PATH DEG or -RIG_EINVAL upon input error.

     Both are floating point values within the range 0.00 to 360.00.

a, d_sp2d_lp SHORT PATH KM
     Returns LONG PATH KM.

     Both are floating point values.

rotctl Readline support
-----------------------

If Readline library development files are found at configure time, rotctl will be conditonally built with Readline support for command and argument entry.  Readline command key bindings are at their defaults as described in the Readline manual (http://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html) although rotctl sets the name rotctl which can be used in Conditional Init Constructs in the Readline Init File (~/.inputrc by default) for custom keybindings unique to rotctl.

Command history is available with Readline support as described in the Readline History manual (http://cnswww.cns.cwru.edu/php/chet/readline/history.html#SEC1).  Command and argument strings are stored as single lines even when arguments are prompted for input individually. Commands and arguments are not validated and are stored as typed with values separated by a single space.

Normally session history is not saved, however, use of either of the -i/--read-history or -I/--save-history options when starting rotctl will cause any previously saved history to be read in and/or the current and any previous session history (assuming the -i and -I options are given together) will be written out when rotctl is closed.  Each option is mutually exclusive, i.e. either may be given separately or in combination. This is useful to save a set of commands and then read them later but not write the modified history for a consistent set of test commands in interactive mode, for example.

History is stored in ~/.rotctl_history by default although the destination directory may be changed by setting the ROTCTL_HIST_DIR environment variable.  When ROTCTL_HIST_DIR is unset, the value of the HOME environment variable is used instead.  Only the destination directory may be changed at this time.

If Readline support is not found at configure time the original internal command handler is used.  Readline is not used for rotctl commands entered on the command line regardless if Readline support is built in or not.

     Readline support is not included in the MS Windows 32 binary builds supplied by the Hamlib Project.  Running rotctl on the MS Windows 32 platform in the cmd shell does give session command line history, however, it is not saved to disk between sessions.

rigctld
=======

The rigctld program is a network server that accepts the familiar commands of rigctl and provides the response data over a TCP/IP network socket to an application.  In this manner an application can access a rigctl instance from nearly anywhere (caveat, no security is currently provided by rigctl).  Applications using rigctl do not link to Hamlib nor use its C API.

Introduction to rigctld
-----------------------

Multiple radios can be controlled on different TCP ports by use of multiple rigctld processes.  The syntax of the commands are the same as rigctl. It is hoped that rigctld will be especially useful for client authors using languages such as Perl (http://www.perl.org/), Python (http://www.python.org/), PHP (http://php.net/), Ruby (http://www.ruby-lang.org/en/), TCL (http://www.tcl.tk/), and others.

rigctld communicates to a client through a TCP network socket using text commands shared with rigctl. The protocol is simple; commands are sent to rigctld on one line and rigctld responds to ``get'' commands with the requested values, one per line, when successful, otherwise, it responds with one line RPRT x, where x is a negative number indicating the Hamlib error code.  Commands that do not return values respond with the line RPRT x, where x is zero when successful, otherwise a regative number indicating the Hamlib error code.  Each line is terminated with a newline \n character.  This protocol is primarily for use by the NET rigctl (rig model 2) backend. See rigctld Default protocol.

A separate Extended Response protocol extends the above behavior by echoing the received command string as a header, any returned values as a key: value pair, and the RPRT x string as the end of response marker which includes the Hamlib success or failure value. Consider using this protocol for clients that will interact with rigctld directly through a TCP network socket. See rigctld Extended Response protocol.

rigctld invocation
------------------

The command line invocation for rigctld is similar to rigctl except that in POSIX environments a trailing & is appended to the command string to ``background'' the rigctld process so the shell can be used to run other commands while rigctld continues to run.

Here are some examples for invoking rigctld.

Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and backgrounding:

     rigctld -m 114 -r /dev/ttyUSB1 &

Start rigctld for a Yaesu FT-920 using a USB to serial adapter while setting baud rate and stop bits, and backgrounding:

     rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &

Start rigctld for an Elecraft K3 using COM2 on MS Windows:

     rigctld -m 229 -r COM2 -T 127.0.0.1 -t 4532

     On MS Windows the use of the -T and -t options appear to be necessary to set the IP address and TCP port or else the network socket cannot be found.  On POSIX systems the rigctld default values will be used.

Connect to the already running rigctld, and set current frequency to 14.266 MHz with a 1 second read timeout using the default protocol from the shell prompt:

     echo "\set_freq 14266000" | nc -w 1 localhost 4532

Connect to a running rigctld with rigctl on the local host:

     rigctl -m2

rigctld command line options
----------------------------

Many of the rigctld command line options are shared with rigctl with a few additions.

rigctld accepts the following options:

-m
--model=ID
     Select radio model number. See model list (use rigctld -l).

-r
--rig-file=DEVICE
     Use DEVICE as the file name of the port the radio is connected. Often a serial port, but could be a USB to serial adapter.  Typically /dev/ttyS0 , /dev/ttyS1 , /dev/ttyUSB0 , etc. on Linux or COM1 , COM2 , etc. on MS Windows.

-p
--ptt-file=DEVICE
     Use DEVICE as the file name of the Push-To-Talk device using a device file as described above.

-d
--dcd-file=DEVICE
     Use DEVICE as the file name of the Data Carrier Detect device using a device file as described above.

-P
--ptt-type=TYPE
     Use TYPE of Push-To-Talk device.  Supported types are RIG, DTR, RTS, PARALLEL, NONE, overriding PTT type defined in the rig's backend.

     Some side effects of this command are that when type is set to DTR, read PTT state comes from Hamlib frontend, not read from the radio.  When set to NONE, PTT state cannot be read or set even if rig backend supports reading/setting PTT status from the rig.

-D
--dcd-type=TYPE
     Use TYPE of Data Carrier Detect device.  Supported types are RIG (CAT command), DSR, CTS, CD, PARALLEL, NONE.

-s
--serial-speed=BAUD
     Set serial speed to BAUD rate. Uses maximum serial speed from rig backend capabilities (set by -m above) as the default.

-c
--civaddr=ID
     Use ID as the CI-V address to communicate with the rig. Only useful for Icom radios and those using the Icom protocol.

     N.B. The ID is in decimal notation, unless prefixed by 0x, in which case it is a hexadecimal value.

-T
--listen-addr=IPADDR
     Use IPADDR as the listening IP address. The default is ANY.

     N.B. On MS Windows setting a specific IP address is likely necessary.

-t
--port=NUMBER
     Use NUMBER as the TCP listening port. The default is 4532.

     N.B. As rotctld's default port is 4533, it is advisable to use even numbered ports for rigctld, e.g. 4532, 4534, 4536, etc.

-L
--show-conf
     List all config parameters for the radio defined with -m above.

-C
--set-conf=PARM=VAL[,PARM=VAL,...]
     Set config parameter. e.g. stop_bits=2

     Use -L option for a list.

-l
--list
     List all model numbers defined in Hamlib and exit.  As of 1.2.15.1 the list is sorted by model number.

     N.B. In Linux the list can be scrolled back using SHIFT-PageUp/ SHIFT-PageDown, or using the scrollbars of a virtual terminal in X or the cmd window in MS Windows.  The output can be piped to 'more' or 'less', e.g. 'rigctl -l | more'.

-u
--dump-caps
     Dump capabilities for the radio defined with -m above and exit.

-o
--vfo
     Set vfo mode, requiring an extra VFO argument in front of each appropriate command (except set_vfo!). Otherwise, currVFO is assumed when this option is not set and an extra VFO argument is not used.  See chk_vfo below.

-v
--verbose
     Set verbose mode level, cumulative i.e. -vvvvv sets maximum debugging output to stderr.

     Five different levels of diagnostics can be output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.  Back end authors will use the verbose facility to print critical values useful for testing and will often ask for this output in response to a request for help.

-h
--help
     Show summary of these options and exit.

-V
--version
     Show version of rigctl and exit.

     Some options may not be implemented by a given backend and will return an error.  This is most likely to occur with the --set-conf and --show-conf options.

rigctld commands
----------------

Commands can be sent over the TCP socket either as a single char, or as a long command name plus the value(s) space separated on one \n terminated line.  See rigctld protocol.

Since most of the Hamlib operations have a ``set'' and a ``get'' method, in general an upper case letter will be used for set methods whereas the corresponding lower case letter refers to the get method. Each operation also has a long name; in interactive mode, prepend a backslash \ to enter a long command name.

Example (Perl):

     print $socket "\\dump_caps\n";

to see what the radio's backend can do.

     In Perl and many other languages a \ will need to be escaped with a preceding \ so that even though two backslash characters appear in the code, only one will be passed to rigctld.  This is a possible bug, so beware!

Be aware that the backend for the radio to be controlled, or the radio itself may not support some commands. In that case, the operation will fail with a Hamlib error message.

Here is a summary of the supported commands:

  * Command short name is followed by the long name which is followed by any variable names.

  * Some short commands are noted as hexadecimal digits due to the limitation of upper and lower case letters available.  Use the associated long command name instead.

  * While a comma is used to separate variable names in this document, they are not part of the command syntax used by rigctl.  Use a space to separate values.

  * In the case of ``set'' commands the variable NAME is replaced by the value in the description.

  * In the case of ``get'' commands the variable NAME is the key name of the value returned.

F, set_freq FREQUENCY
     Set FREQUENCY, in Hertz.

f, get_freq
     Get FREQUENCY, in Hertz.

M, set_mode MODE, PASSBAND
     Set MODE to one of: USB, LSB, CW, CWR, RTTY, RTTYR, AM, FM, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.

     Set PASSBAND frequency in Hertz, or 0 for the Hamlib backend default.

     N.B. Passing a ? (query) as the first argument instead of MODE will return a space separated list of radio backend supported Modes.  Use this to determine the supported Modes of a given radio backend.

m, get_mode
     Get MODE, PASSBAND.

     Returns Mode as a string from set_mode above and Passband frequency in Hertz.

V, set_vfo VFO
     Set VFO to one of: VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub, TX, RX.

     In VFO mode only a single VFO parameter is required.

v, get_vfo
     Get current VFO.

     Returns VFO as a string from set_vfo above.

J, set_rit RIT
     Set RIT, in Hertz, can be a positive or negative value.

     A value of 0 resets RIT and should turn RIT off.  If not, file a bug report against the Hamlib backend.

     N.B. This functionality is under transition and in the future will need to be activated with the set_func command.

j, get_rit
     Get RIT, in Hertz.

Z, set_xit XIT
     Set XIT, in Hertz, can be a positive or negative value.

     A value of 0 resets XIT and should turn XIT off.  If not, file a bug report against the Hamlib backend.

     N.B. This functionality is under transition and in the future will need to be activated with the set_func command.

z, get_xit
     Get XIT, in Hertz.

T, set_ptt PTT
     Set PTT to one of: 0 (RX), 1 (TX), 2 (TX mic), 3 (TX data).

t, get_ptt
     Get PTT status.

0x8b, get_dcd
     Get DCD (squelch) status, 0 (Closed) or 1 (Open)

R, set_rptr_shift RPTR SHIFT
     Set RPTR SHIFT: +, - or something else for none.

r, get_rptr_shift
     Get RPTR SHIFT.  Returns +, - or None.

O, set_rptr_offs RPTR OFFSET
     Set RPTR OFFSET, in Hertz.

o, get_rptr_offs
     Get RPTR OFFSET, in Hertz.

C, set_ctcss_tone CTCSS TONE
     Set CTCSS TONE, in tenths of Hertz.

     CTCSS, Continuous Tone Coded Squelch System (http://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System), is a method used to reduce the annoyance of listening to other users on a shared two-way communications radio channel by imposing a tone on the transmitted signal.  Also known as subaudible tone and PL, Private Line.

c, get_ctcss_tone
     Get CTCSS TONE, in tenths of Hertz.

D, set_dcs_code DCS CODE
     Set DCS CODE.

     DCS, Digital-Coded Squelch (http://en.wikipedia.org/wiki/Digital-Coded_Squelch#DCS) is a digital version of CTCSS which imposes a digital code on the transmitted signal.

d, get_dcs_code
     Get DCS CODE.

0x90, set_ctcss_sql CTCSS SQL
     Set CTCSS SQL tone, in tenths of Hertz.

0x91, get_ctcss_sql
     Get CTCSS SQL tone, in tenths of Hertz.

0x92, set_dcs_sql DCS SQL
     Set DCS SQL code.

0x93, get_dcs_sql
     Get DCS SQL code.

I, set_split_freq TX FREQUENCY
     Set TX FREQUENCY, in Hertz for ``split'' frequency operation.

i, get_split_freq
     Get TX FREQUENCY, in Hertz for ``split'' frequency operation.

X, set_split_mode TX MODE, TX PASSBAND
     Set TX MODE to one of: AM, FM, CW, CWR, USB, LSB, RTTY, RTTYR, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.

     The TX PASSBAND is the exact passband frequency in Hertz, or 0 for the Hamlib backend default.

     N.B. Passing a ? (query) as the first argument instead of TX MODE will return a space separated list of radio backend supported TX Modes.  Use this to determine the supported TX Modes of a given radio backend.

x, get_split_mode
     Get TX MODE, TX PASSBAND.

     Returns TX mode as a string from set_split_mode above and TX passband in Hz.

S, set_split_vfo SPLIT, TX VFO
     Set SPLIT mode, 0 (off) or 1 (on), and TX VFO from set_vfo above.

s, get_split_vfo
     Get SPLIT mode, 0 (off) or 1 (on), and TX VFO.

N, set_ts TUNING STEP
     Set TUNING STEP, in Hertz.

n, get_ts
     Get TUNING STEP, in Hertz.

U, set_func FUNC, FUNC STATUS
     Set FUNC, FUNC STATUS.

     FUNC is one of: FAGC, NB, COMP, VOX, TONE, TSQL, SBKIN, FBKIN, ANF, NR, AIP, APF, MON, MN, RF, ARO, LOCK, MUTE, VSC, REV, SQL, ABM, BC, MBC, RIT, AFC, SATMODE, SCOPE, RESUME, TBURST, TUNER, XIT.

     Func Status argument is 1 for ``activate'', 0 for ``de-activate'', much as TRUE/FALSE definitions in the C/C++ languages (true is non-zero and false is zero).

     N.B.  Passing a ? (query) as the first argument instead of FUNC will return a space separated list of radio backend supported ``set'' functions.  Use this to determine the supported functions of a given radio backend.

u, get_func FUNC
     Get FUNC STATUS.

     Returns FUNC STATUS as a non null value for the FUNC passed. FUNC is a token from the list in set_func above.

     N.B. Passing a ? (query) as the first argument instead of FUNC will return a space separated list of radio backend supported ``get'' functions.  Use this to determine the supported functions of a given radio backend.

L, set_level LEVEL, LEVEL VALUE
     Set LEVEL, LEVEL VALUE.

     LEVEL is one of: PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR, PBT_IN, PBT_OUT, CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF, COMP, AGC(0:OFF, 1:SUPERFAST, 2:FAST, 3:SLOW, 4:USER, 5:MEDIUM, 6:AUTO), BKINDL, BAL, METER, VOXGAIN, ANTIVOX, SLOPE_LOW, SLOPE_HIGH, RAWSTR, SWR, ALC, STRENGTH.

     The LEVEL VALUE can be a float or an integer.

     N.B. Passing a ? (query) as the first argument instead of LEVEL will return a space separated list of radio backend supported ``set'' levels.  Use this to determine the supported levels of a given radio backend.

l, get_level LEVEL
     Get LEVEL VALUE.

     Returns LEVEL VALUE as a float or integer for the LEVEL passed.  LEVEL is a token from the list in set_level above.

     N.B. Passing a ? (query) as the first argument instead of LEVEL will return a space separated list of radio backend supported ``get'' levels.  Use this to determine the supported levels of a given radio backend.

P, set_parm PARM, PARM VALUE
     Set PARM, PARM VALUE

     PARM is one of: ANN, APO, BACKLIGHT, BEEP, TIME, BAT, KEYLIGHT.

     N.B.  Passing a ? (query) as the first argument instead of PARM will return a space separated list of radio backend supported ``set'' parameters.  Use this to determine the supported parameters of a given radio backend.

p, get_parm PARM
     Get PARM VALUE.

     Returns PARM VALUE as a float or integer for the PARM passed.  PARM is a token from the list in set_parm above.

     N.B.  Passing a ? (query) as the first argument instead of PARM will return a space separated list of radio backend supported ``get'' parameters.  Use this to determine the supported parameters of a given radio backend.

B, set_bank BANK
     Set BANK.  Sets the current memory bank number.

E, set_mem MEMORY#
     Set MEMORY# channel number.

e, get_mem
     Get MEMORY# channel number.

G, vfo_op MEM/VFO OP
     Perform MEM/VFO OP.

     MEM/VFO OPeration is one of: CPY, XCHG, FROM_VFO, TO_VFO, MCL, UP, DOWN, BAND_UP, BAND_DOWN, LEFT, RIGHT, TUNE, TOGGLE.

     N.B. Passing a ? (query) as the first argument instead of MEM/VFO OP will return a space separated list of radio backend supported ``set'' Mem/VFO Ops.  Use this to determine the supported Mem/VFO Ops of a given radio backend.

g, scan SCAN FCT, SCAN CHANNEL
     Perform SCAN FCT SCAN CHANNEL.

     Scan function/channel is one of: STOP, MEM, SLCT, PRIO, PROG, DELTA, VFO, PLT.

     N.B. Passing a ? (query) as the first argument instead of SCAN FCT will return a space separated list of radio backend supported Scan Functions.  Use this to determine the supported Scan Functions of a given radio backend.

H, set_channel CHANNEL
     Set memory CHANNEL data. Not implemented yet.

h, get_channel
     Get memory CHANNEL data. Not implemented yet.

A, set_trn TRANSCEIVE
     Set TRANSCEIVE mode (reporting event): OFF, RIG, POLL.

     N.B. Passing a ? (query) as the first argument instead of TRANSCEIVE will return a space separated list of radio backend supported Scan Transceive modes.  Use this to determine the supported Transceive modes of a given radio backend.

a, get_trn
     Get TRANSCEIVE mode (reporting event) as in set_trn above.

Y, set_ant ANTENNA
     Set ANTENNA number (0, 1, 2, ...).

y, get_ant
     Get ANTENNA number (0, 1, 2, ...).

*, reset RESET
     Perform rig RESET.

     0 = None, 1 = Software reset, 2 = VFO reset, 4 = Memory Clear reset, 8 = Master reset.  Since these values are defined as a bitmask in rig.h, it should be possible to AND these values together to do multiple resets at once, if the backend supports it or supports a reset action via rig control at all.

b, send_morse MORSE
     Send MORSE symbols.

0x87, set_powerstat POWER STATUS
     Set power On/Off/Standby POWER STATUS.

     0 = Power Off, 1 = Power On, 2 = Power Standby. Defined as a bitmask in rig.h.

0x88, get_powerstat
     Get power On/Off/Standby POWER STATUS as in set_powerstat above.

0x89, send_dtmf DIGITS
     Set DTMF DIGITS.

0x8a, recv_dtmf
     Get DTMF DIGITS.

_, get_info
     Get misc information about the rig

     VFO parameter not used in 'VFO mode'.

1, dump_caps
     Not a real rig remote command, it just dumps capabilities, i.e. what the backend knows about this model, and what it can do.

     TODO: Ensure this is in a consistent format so it can be read into a hash, dictionary, etc.  Bug reports requested.

     N.B. This command will produce many lines of output so be very careful if using a fixed length array!  For example, running this command against the Dummy backend results in over 5kB of text output.

     VFO parameter not used in 'VFO mode'.

2, power2mW POWER 0.0..1.0, FREQUENCY, MODE
     Returns POWER MW

     Converts a POWER value in a range of 0.0..1.0 to the real transmit power in milli-Watts (integer).  The FREQUENCY and MODE also need to be provided as output power may vary according to these values.

     VFO parameter not used in 'VFO mode'.

4, mW2power POWER MW, FREQUENCY, MODE
     Returns POWER 0.0..1.0

     Converts the real transmit power in milli-Watts (integer) to a POWER value in a range of [0.0..1.0].  The FREQUENCY and MODE also need to be provided as output power may vary according to these values.

     VFO parameter not used in 'VFO mode'.

w, send_cmd CMD
     Send raw command string to rig.  This is useful for testing and troubleshooting rig commands and responses when developing a backend.

     For binary protocols enter values as \0xAA\0xBB.  Expect a REPLY from the rig which will likely be a binary block or an ASCII string depending on the rig's protocol (see your radio's computer control documentation).

     The command terminator, set by the --send-cmd-term option above, will terminate each command string sent to the radio.  This character should not be a part of the input string.

chk_vfo
     Returns CHKVFO 1 (single line only) if rigctld was invoked with the -o or --vfo option, CHKVFO 0 if not.

rigctld protocol
----------------

Two protocols exist for communicating with rigctld.  The ``Default'' protocol is primarily used internally by Hamlib so an application that is not written to use rigctld directly via TCP network sockets can still access rigctld.  The other ``Extended Response Protocol'' is intended for the more general use case where a variety of response formats may be needed.

rigctld Default protocol
........................

The rigctld protocol is intentionally simple. Commands are entered on a single line with any needed values.  In Perl, for exampl, reliable results are obtained by terminating each command string with a newline character, \n.

Example set (Perl code):

     print $socket "F 14250000\n";
     print $socket "\\set_mode LSB 2400\n";   # escape leading '\'

A one line response will be sent as a reply to set commands, RPRT x\n where x is the Hamlib error code with 0 indicating success of the command.

Responses from rigctld get commands are text values and match the same tokens used in the set commands. Each value is returned on its own line.  On error the string RPRT x\n is returned where x is the Hamlib error code.

Example get (Perl code):

     print $socket "f\n";
     "14250000\n"

Most get functions return one to three values. A notable exception is the dump_caps command which returns many lines of key:value pairs.

This protocol is primarily used by the NET rigctl (rigctl model 2) backend which allows applications already written for Hamlib's C API to take advantage of rigctld without the need of rewriting application code.  An application's user can select rig model 2 (NET rigctl) and then set rig_pathname to localhost:4532 or other network host:port (set by the -t option above).

rigctld Extended Response Protocol
..................................

An EXPERIMENTAL Extended Response protocol has been introduced into rigctld as of February 16, 2010.  This protocol adds several rules to the strings returned by rigctld and adds a rule for the command syntax.

 1. The command received by rigctld is echoed with its long command name followed by the value(s) (if any) received from the client terminated by the specified response separator as the record line of the response.

 2. The last line of each block is the string RPRT x\n where x is the numeric return value of the Hamlib backend function that was called by the command.

 3. Any records consisting of data values returned by the rig backend are prepended by a string immediately followed by a colon then a space and then the value terminated by the response separator. e.g. Frequency: 14250000\n when the command was prepended by +.

 4. All commands received will be acknowledged by rigctld with lines from rules 1 and 2.  Lines from rule 3 are only returned when data values must be returned to the client.

An example response to a +\set_mode command sent from the shell prompt (note the prepended +):

     echo "+M USB 2400" | nc -w 1 localhost 4532
     set_mode: USB 2400
     RPRT 0

In this case the long command name and values are returned on the first line and the second line contains the end of block marker and the numeric rig backend return value indicating success.

An example response to a \get_mode query:

     echo "+\get_mode" | nc -w 1 localhost 4532
     get_mode:
     Mode: USB
     Passband: 2400
     RPRT 0

In this case, as no value is passed to rigctld, the first line consists only of the long command name.  The final line shows that the command was processed successfully by the rig backend.

Invoking the Extended Response protocol requires prepending a command with a punctuation character.  As shown in the examples above, prepending a '+ character to the command results in the responses being separated by a newline character (\n).  Any other punctuation character recognized by the C ispunct() function except \, ?, or _ will cause that character to become the response separator and the entire response will be on one line.

Separator character summary:

+
     Each record of the response is appended with a newline (\n).

;, |, or ,
     Each record of the response is appended by the given character resulting in entire response on one line.

     Common record separators for text representations of spreadsheet data, etc.

?
     Reserved for 'help' in rigctl short command.

_
     Reserved for \get_info in rigctl short command.

#
     Reserved for comments when reading a command file script.

Other punctuation characters have not been tested!  Use at your own risk.

For example, invoking a ;\get_mode query with a leading ; returns:

     get_mode:;Mode: USB;Passband: 2400;RPRT 0

Or, using the vertical bar (pipe) character | returns:

     get_mode:|Mode: USB|Passband: 2400|RPRT 0

And a \set_mode command prepended with a | returns:

     set_mode: USB 2400|RPRT 0

Such a format will allow reading a response as a single event using a preferred response separator.  Other punctuation characters have not been tested!

rotctld
=======

The rotctld program is a network server that accepts the familiar commands of rotctl and provides the response data over a TCP/IP network socket to an application.  In this manner an application can access a rotctl instance from nearly anywhere (caveat, no security is currently provided by rotctl).  Applications using rotctl do not link to Hamlib nor use its C API.

Introduction to rotctld
-----------------------

rotctld communicates to a client through a TCP socket using text commands shared with rotctl. The protocol is simple, commands are sent to rotctld on one line and rotctld responds to ``get'' commands with the requested values, one per line, when successful, otherwise, it responds with one line RPRT x, where x is a negative number indicating the error code.  Commands that do not return values respond with the line RPRT x, where x is zero when successful, otherwise is a regative number indicating the error code.  Each line is terminated with a newline \n character.  This protocol is primarily for use by the NET rotctl (rot model 2) backend.  See rotctld Default protocol.

A separate Extended Response protocol extends the above behavior by echoing the received command string as a header, any returned values as a key: value pair, and the RPRT x string as the end of response marker which includes the Hamlib success or failure value. Consider using this protocol for clients that will interact with rotctld directly through a TCP network socket. See rotctld Extended Response protocol.

rotctld invocation
------------------

The command line invocation for rotctld is similar to rotctl except that in POSIX environments a trailing & is appended to the command string to ``background'' the rotctld process so the shell can be used to run other commands while rotctld continues to run.

Here are some examples for invoking rotctld.

Start rotctld for a Ham IV rotor with the RotorEZ installed using a USB-to-serial adapter and backgrounding:

     rotctld -m 401 -r /dev/ttyUSB1 &

Start rotctld for RotorEZ using COM2 on MS Windows:

     rotctl -m 401 -r COM2 -T 127.0.0.1 -t 4533

     On MS Windows the use of the -T and -t options appear to be necessary to set the IP address and TCP port or else the network socket cannot be found.  On POSIX systems the rotctld default values will be used.

Connect to the already running rotctld, and set position to 135.0 degrees azimuth and 30.0 degrees elevation with a 1 second read timeout from the shell prompt:

     echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533

Connect to a running rotctld with rotctl on the local host:

     rotctl -m2

rotctld command line options
----------------------------

Many of the rotctld command line options are shared with rotctl with a few additions.

rotctld accepts the following options:

-m
--model=ID
     Select rotator model number. See model list (use rotctl -l).

     N.B. rotctl (or third party software) will use rotor model 2 for NET rotctl (rotctld).

-r
--rig-file=DEVICE
     Use DEVICE as the file name of the port the rotor is connected. Often a serial port, but could be a USB to serial adapter.  Typically /dev/ttyS0 , /dev/ttyS1 , /dev/ttyUSB0 , etc. on Linux or COM1 , COM2 , etc. on MS Windows.

-s
--serial-speed=BAUD
     Set serial speed to BAUD rate. Uses maximum serial speed from rotor backend capabilities as the default.

-T
--listen-addr=IPADDR
     Use IPADDR as the listening IP address. The default is ANY.

     N.B. On MS Windows setting a specific IP address is likely necessary.

-t
--port=NUMBER
     Use NUMBER as the TCP listening port. The default is 4533.

     N.B. As rigctld's default port is 4532, it is advisable to use odd numbered ports for rotctld, e.g. 4533, 4535, 4537, etc.

-L
--show-conf
     List all config parameters for the rotor defined with -m above.

-C
--set-conf=PARM=VAL[,PARM=VAL,...]
     Set config parameter. e.g. stop_bits=2

     Use -L option for a list.

-l
--list
     List all model numbers defined in Hamlib and exit.  As of 1.2.15.1 the list is sorted by model number.

     N.B. In Linux the list can be scrolled back using SHIFT-PageUp/ SHIFT-PageDown, or using the scrollbars of a virtual terminal in X or the cmd window in MS Windows.  The output can be piped to 'more' or 'less', e.g. 'rotctl -l | more'.

-u
--dump-caps
     Dump capabilities for the rotor defined with -m above and exit.

-v
--verbose
     Set verbose mode level, cumulative i.e. -vvvvv sets maximum debugging output to stderr.

     Five different levels of diagnostics can be output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.  Back end authors will use the verbose facility to print critical values useful for testing and will often ask for this output in response to a request for help.

-h
--help
     Show summary of these options and exit.

-V
--version
     Show version of rotctl and exit.

     Some options may not be implemented by a given backend and will return an error.  This is most likely to occur with the --set-conf and --show-conf options.

rotctld commands
----------------

Commands can be sent over the TCP socket either as a single char, or as a long command name plus the value(s) space separated on one \n terminated line.  See rotctld protocol.

Since most of the Hamlib operations have a ``set'' and a ``get'' method, in general an upper case letter will be used for set methods whereas the corresponding lower case letter refers to the get method. Each operation also has a long name; in interactive mode, prepend a backslash \ to enter a long command name.

Example (Perl):

     print $socket "\\dump_caps\n";

to see what the rotor's backend can do.

     In Perl and many other languages a \ will need to be escaped with a preceding \ so that even though two backslash characters appear in the code, only one will be passed to rotctld.  This is a possible bug, so beware!

Be aware that the backend for the rotor to be controlled, or the rotor itself may not support some commands. In that case, the operation will fail with a Hamlib error message.

Rotor commands

Here is a summary of the supported commands:

       * Command short name is followed by the long name which is followed by any variable names.

       * While a comma is used to separate variable names in this document, they are not part of the command syntax used by rotctl.  Use a space to separate values.

       * In the case of ``set'' commands the variable NAME is replaced by the value in the description.

       * In the case of ``get'' commands the variable NAME is the key name of the value returned.

P, set_pos AZIMUTH, ELEVATION
     Set position: AZIMUTH and ELEVATION as double precision floating point values.

p, get_pos
     Get position: AZIMUTH and ELEVATION as double precision floating point values.

M, move DIRECTION, SPEED
     Move the rotator in a specific direction at the given rate.

     Values are integers where DIRECTION is defined as 2 = Up, 4 = Down, 8 = Left, and 16 = Right.  SPEED is an integer between 1 and 100.

     N.B. Not all backends that implement the move command use the Speed value.  At this time only the gs232a utilizes the Speed parameter.

S, stop
     Stop the rotator.

K, park
     Park the antenna.

C, set_conf TOKEN, VALUE
     Set a configuration parameter.  It is safe to give TOKEN a value of 0 (zero).  VALUE may be a string up to 20 characters.

     See -L output.

R, reset RESET
     Reset the rotator.

     Integer value of 1 for Reset All.

_, get_info
     Get misc information on the rotator.

     At the moment returns MODEL NAME.

w, send_cmd CMD
     Send raw command string to the rotator.

     <CR> (or send-cmd-term, see -t option) is appended automatically at the end of the command for text protocols. For binary protocols, enter values as \0xAA\0xBB.

Locator Commands

These commands offer conversions of Degrees Minutes Seconds to other formats, Maidenhead square locator conversions and distance and azimuth conversions.

L, lonlat2loc LONGITUDE, LATITUDE, LOC LEN 2..12
     Returns the Maidenhead locator for the given LONGITUDE and LATITUDE.

     Both are floating point values.  The precision of the returned square is controlled by LOC LEN which should be an even numbered integer value between 2 and 12.

     For example, +L -170.000000 -85.000000 12\n returns Locator: AA55AA00AA00\n.

l, loc2lonlat LOCATOR
     Returns LONGITUDE and LATITUDE in decimal degrees at the approximate center of the requested grid square (despite the use of double precision variables internally, some rounding error occurs). West longitude is expressed as a negative value.  South latitude is expressed as a negative value.  Locator can be from 2 to 12 characters in length.

     For example, +l AA55AA00AA00 returns Longitude: -169.999983\nLatitude: -84.999991\n.

D, dms2dec DEGREES, MINUTES, SECONDS, S/W
     Returns DEC DEGREES, a signed floating point value.

     DEGREES and MINUTES are integer values and SECONDS is a floating point value.  S/W is a flag with 1 indicating South latitude or West longitude and 0 North or East (the flag is needed as computers don't recognize a signed zero even though only the DEGREES value only is typically signed in DMS notation).

d, dec2dms DEC DEGREES
     Returns DEGREES, MINUTES, SECONDS, S/W.

     Values are as in dms2dec above.

E, dmmm2dec DEGREES, DEC MINUTES, S/W
     Returns DEC DEGREES, a signed floating point value.

     DEGREES is an integer value and MINUTES is a floating point value.  S/W is a flag with 1 indicating South latitude or West longitude and 0 North or East (the flag is needed as computers don't recognize a signed zero even though only the DEGREES value only is typically signed in DMS notation).

e, dec2dmmm DEC DEG
     Returns DEGREES, MINUTES, S/W.

     Values are as in dmmm2dec above.

B, qrb LON 1, LAT 1, LON 2, LAT 2
     Returns DISTANCE and AZIMUTH where DISTANCE is in km and AZIMUTH is in degrees.

     All LON/LAT values are signed floating point numbers.

A, a_sp2a_lp SHORT PATH DEG
     Returns LONG PATH DEG or -RIG_EINVAL upon input error.

     Both are floating point values within the range 0.00 to 360.00.

a, d_sp2d_lp SHORT PATH KM
     Returns LONG PATH KM.

     Both are floating point values.

rotctld protocol
----------------

Two protocols exist for communicating with rotctld.  The ``Default'' protocol is primarily used internally by Hamlib so an application that is not written to use rotctld directly via TCP network sockets can still access rotctld.  The other ``Extended Response Protocol'' is intended for the more general use case where a variety of response formats may be needed.

rotctld Default protocol
........................

The rotctld protocol is intentionally simple. Commands are entered on a single line with any needed values.  In Perl, for exampl, reliable results are obtained by terminating each command string with a newline character, \n.

Example set (Perl code):

     print $socket "P 135 10\n";
     print $socket "\\set_pos 135 10\n";   # escape leading '\'

A one line response will be sent as a reply to set commands, RPRT x\n where x is the Hamlib error code with 0 indicating success of the command.

Responses from rotctld get commands are text values and match the same tokens used in the set commands. Each value is returned on its own line.  On error the string RPRT x\n is returned where x is the Hamlib error code.

Example get (Perl code):

     print $socket "p\n";
     "135"
     "10"

Most get functions return one to four values. A notable exception is the dump_caps command which returns many lines of key:value pairs.

This protocol is primarily used by the NET rotctl (rotctl model 2) backend which allows applications already written for Hamlib's C API to take advantage of rotctld without the need of rewriting application code.  An application's user can select rotor model 2 (NET rotctl) and then set rig_pathname to localhost:4533 or other network host:port (set by the -t option above).

rotctld Extended Response Protocol
..................................

An EXPERIMENTAL Extended Response protocol has been introduced into rotctld as of February 10, 2010.  This protocol adds several rules to the strings returned by rotctld and adds a rule for the command syntax.

 1. The command received by rotctld is echoed with its long command name followed by the value(s) (if any) received from the client terminated by the specified response separator as the record line of the response.

 2. The last line of each block is the string RPRT x\n where x is the numeric return value of the Hamlib backend function that was called by the command.

 3. Any records consisting of data values returned by the rotor backend are prepended by a string immediately followed by a colon then a space and then the value terminated by the response separator. e.g. Azimuth: 90.000000\n when the command was prepended by +.

 4. All commands received will be acknowledged by rotctld with lines from rules 1 and 2.  Lines from rule 3 are only returned when data values must be returned to the client.

An example response to a +P command sent from the shell prompt (note the prepended +):

     echo "+P 90 45" | nc -w 1 localhost 4533
     set_pos: 90 45
     RPRT 0

In this case the long command name and values are returned on the first line and the second line contains the end of block marker and the numeric rotor backend return value indicating success.

An example response to a +\get_pos query:

     echo "+\get_pos" | nc -w 1 localhost 4533
     get_pos:
     Azimuth: 90.000000
     Elevation: 45.000000
     RPRT 0

In this case, as no value is passed to rotctld, the first line consists only of the long command name.  The final line shows that the command was processed successfully by the rig backend.

Invoking the Extended Response protocol requires prepending a command with a punctuation character.  As shown in the examples above, prepending a '+ character to the command results in the responses being separated by a newline character (\n).  Any other punctuation character recognized by the C ispunct() function except \, ?, or _ will cause that character to become the response separator and the entire response will be on one line.

Separator character summary:

+
     Each record of the response is appended with a newline (\n).

;, |, or ,
     Each record of the response is appended by the given character resulting in entire response on one line.

     Common record separators for text representations of spreadsheet data, etc.

?
     Reserved for 'help' in rotctl short command.

_
     Reserved for \get_info in rotctl short command.

#
     Reserved for comments when reading a command file script.

Other punctuation characters have not been tested!  Use at your own risk.

For example, invoking a ;\get_pos query with a leading ; returns:

     get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0

Or, using the vertical bar (pipe) character | returns:

     get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0

And a \set_pos command prepended with a | returns:

     set_pos: 135 22.5|RPRT 0

Such a format will allow reading a response as a single event using a preferred response separator.  Other punctuation characters have not been tested!

All commands with the exception of \set_conf have been tested with the Extended Response protocol and the included testrotctld.pl script.