kopia lustrzana https://github.com/Hamlib/Hamlib
722 wiersze
25 KiB
Groff
722 wiersze
25 KiB
Groff
.\" Hey, EMACS: -*- nroff -*-
|
|
.\" First parameter, NAME, should be all caps
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
.TH RIGCTLD "8" "March 12, 2013" "Hamlib" "Rig Control Daemon"
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
.\"
|
|
.\" Some roff macros, for reference:
|
|
.\" .nh disable hyphenation
|
|
.\" .hy enable hyphenation
|
|
.\" .ad l left justify
|
|
.\" .ad b justify to both left and right margins
|
|
.\" .nf disable filling
|
|
.\" .fi enable filling
|
|
.\" .br insert line break
|
|
.\" .sp <n> insert n+1 empty lines
|
|
.\" for manpage-specific macros, see man(7)
|
|
.SH NAME
|
|
rigctld \- Hamlib TCP rig control daemon
|
|
.SH SYNOPSIS
|
|
.B rigctld
|
|
[\fIOPTION\fR]...
|
|
.SH DESCRIPTION
|
|
The \fBrigctld\fP program is a NEW \fBHamlib\fP rig control daemon ready for
|
|
testing that handles client requests via TCP sockets. This allows multiple
|
|
user programs to share one radio (this needs testing). Multiple radios can be
|
|
controlled on different TCP ports by use of multiple \fBrigctld\fP processes.
|
|
The syntax of the commands are the same as \fBrigctl\fP. It is hoped that
|
|
\fBrigctld\fP will be especially useful for client authors using languages
|
|
such as Perl, Python, PHP, and others.
|
|
.PP
|
|
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
|
|
.\" \fI<whatever>\fP escape sequences to invoke bold face and italics,
|
|
.\" respectively.
|
|
\fBrigctld\fP communicates to a client through a TCP socket using text
|
|
commands shared with \fBrigctl\fP. The protocol is simple; commands are sent
|
|
to \fBrigctld\fP on one line and \fBrigctld\fP 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 \fINET rigctl\fP (rig model 2)backend.
|
|
.PP
|
|
A separate \fBExtended Response\fP 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 \fBHamlib\fP success or failure value. See the \fIPROTOCOL\fP
|
|
section for details. Consider using this protocol for clients that will
|
|
interact with \fBrigctld\fP directly through a TCP socket.
|
|
.PP
|
|
Keep in mind that \fBHamlib\fP is BETA level software. While a lot of backend
|
|
libraries lack complete rig support, the basic functions are usually well
|
|
supported. The API may change without publicized notice, while an advancement
|
|
of the minor version (e.g. 1.1.x to 1.2.x) indicates such a change.
|
|
.PP
|
|
Please report bugs and provide feedback at the e-mail address given in the
|
|
\fIREPORTING BUGS\fP section. Patches and code enhancements are also welcome.
|
|
.SH OPTIONS
|
|
This program follows the usual GNU command line syntax, with long
|
|
options starting with two dashes ('-').
|
|
.PP
|
|
Here is a summary of the supported options:
|
|
.TP
|
|
.B \-m, --model=id
|
|
Select radio model number. See the -l, --list option below.
|
|
.TP
|
|
.B \-r, --rig-file=device
|
|
Use \fIdevice\fP as the file name of the port the radio is connected.
|
|
Often a serial port, but could be a USB to serial adapter or USB port device.
|
|
Typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux or COM1, COM2,
|
|
etc. on Win32.
|
|
.TP
|
|
.B \-p, --ptt-file=device
|
|
Use \fIdevice\fP as the file name of the Push-To-Talk device using a
|
|
device file as described above.
|
|
.TP
|
|
.B \-d, --dcd-file=device
|
|
Use \fIdevice\fP as the file name of the Data Carrier Detect device using a
|
|
device file as described above.
|
|
.TP
|
|
.B \-P, --ptt-type=type
|
|
Use \fItype\fP of Push-To-Talk device.
|
|
Supported types are RIG (CAT command), DTR, RTS, PARALLEL, NONE.
|
|
.TP
|
|
.B \-D, --dcd-type=type
|
|
Use \fItype\fP of Data Carrier Detect device.
|
|
Supported types are RIG (CAT command), DSR, CTS, CD, PARALLEL, NONE.
|
|
.TP
|
|
.B \-s, --serial-speed=baud
|
|
Set serial speed to \fIbaud\fP rate. Uses maximum serial speed from rig
|
|
backend capabilities (set by -m above) as the default.
|
|
.TP
|
|
.B \-c, --civaddr=id
|
|
Use \fIid\fP as the CI-V address to communicate with the rig. Only useful for
|
|
Icom rigs.
|
|
.sp
|
|
\fBN.B.\fP: The \fIid\fP is in decimal notation, unless prefixed by
|
|
\fI0x\fP for a hexadecimal value.
|
|
.TP
|
|
.B \-T, --listen-addr=IPADDR
|
|
Use \fIIPADDR\fP as the listening IP address. The default is ANY.
|
|
.TP
|
|
.B \-t, --port=number
|
|
Use \fInumber\fP as the TCP listening port. The default is 4532.
|
|
.sp
|
|
\fBN.B.\fP: As \fBrotctld\fP's default port is 4533, it is advisable to use even
|
|
numbered ports for \fBrigctld\fP, e.g. 4532, 4534, 4536, etc.
|
|
.TP
|
|
.B \-L, --show-conf
|
|
List all config parameters for the radio defined with -m above.
|
|
.TP
|
|
.B \-C, --set-conf=parm=val[,parm=val]*
|
|
Set config parameter. e.g. --set-conf=stop_bits=2
|
|
.sp
|
|
Use -L option for a list.
|
|
.TP
|
|
.B \-l, --list
|
|
List all model numbers defined in \fBHamlib\fP and exit. As of 1.2.15.1
|
|
the list is sorted by model number.
|
|
.sp
|
|
\fBN.B.\fP 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 Windows. The output can be piped to 'more' or 'less',
|
|
e.g. 'rigctld -l | more'.
|
|
.TP
|
|
.B \-u, --dump-caps
|
|
Dump capabilities for the radio defined with -m above and exit.
|
|
.TP
|
|
.B \-o, --vfo
|
|
Set vfo mode, requiring an extra VFO argument in front of each appropriate
|
|
command (except \fI\\set_vfo\fP!). Otherwise, 'currVFO' is assumed when this
|
|
option is not set and an extra VFO argument is not used. See \fI\\chk_vfo\fP
|
|
below.
|
|
.TP
|
|
.B \-v, --verbose
|
|
Set verbose mode, cumulative (see \fIDIAGNOSTICS\fP below).
|
|
.TP
|
|
.B \-h, --help
|
|
Show a summary of these options and exit.
|
|
.TP
|
|
.B \-V, --version
|
|
Show the version of \fBrigctld\fP and exit.
|
|
.PP
|
|
\fBN.B.\fP Some options may not be implemented by a given backend and will
|
|
return an error. This is most likely to occur with the \fI\-\-set-conf\fP
|
|
and \fI\-\-show-conf\fP options.
|
|
.PP
|
|
Please note 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 \fBHamlib\fP error code.
|
|
.SH 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 \fIPROTOCOL\fP.
|
|
.PP
|
|
Since most of the \fBHamlib\fP operations have a \fIset\fP and a \fIget\fP
|
|
method, an upper case letter will be used for \fIset\fP methods whereas the
|
|
corresponding lower case letter refers to the \fIget\fP method. Each operation
|
|
also has a long name; prepend a backslash to send a long command name.
|
|
.PP
|
|
Example (Perl): `print $socket "\\\\dump_caps\\n";' to see what the radio's
|
|
backend can do
|
|
.br
|
|
(\fBN.B.\fP: 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 \fBrigctld\fP. This is a
|
|
possible bug, beware!).
|
|
.PP
|
|
Please note 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
|
|
\fBHamlib\fP error message.
|
|
.PP
|
|
Here is a summary of the supported commands (In the case of "set" commands the
|
|
quoted string is replaced by the value in the description. In the case of "get"
|
|
commands the quoted string is the key name of the value returned.):
|
|
.TP
|
|
.B F, set_freq 'Frequency'
|
|
Set 'Frequency', in Hz.
|
|
.TP
|
|
.B f, get_freq
|
|
Get 'Frequency', in Hz.
|
|
.TP
|
|
.B M, set_mode 'Mode' 'Passband'
|
|
Set 'Mode': USB, LSB, CW, CWR, RTTY, RTTYR, AM, FM, WFM, AMS,
|
|
PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.
|
|
.sp
|
|
Set 'Passband' in Hz, or '0' for the Hamlib backend default.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B m, get_mode
|
|
Get 'Mode' 'Passband'.
|
|
.sp
|
|
Returns Mode as a string from \fIset_mode\fP above
|
|
and Passband in Hz.
|
|
.TP
|
|
.B V, set_vfo 'VFO'
|
|
Set 'VFO': VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub, TX, RX.
|
|
.sp
|
|
In VFO mode only a single VFO parameter is required.
|
|
.TP
|
|
.B v, get_vfo
|
|
Get current 'VFO'.
|
|
.sp
|
|
Returns VFO as a string from \fIset_vfo\fP above.
|
|
.TP
|
|
.B J, set_rit 'RIT'
|
|
Set 'RIT', in Hz, can be + or -.
|
|
.sp
|
|
A value of '0' resets RIT and *should* turn RIT off. If not, file a
|
|
bug report against the Hamlib backend.
|
|
.sp
|
|
\fBN.B\fP This functionality is under transition and in the future will
|
|
need to be activated with the \fIset_func\fP command.
|
|
.TP
|
|
.B j, get_rit
|
|
Get 'RIT', in Hz.
|
|
.TP
|
|
.B Z, set_xit 'XIT'
|
|
Set 'XIT', in Hz can be + or -.
|
|
.sp
|
|
A value of '0' resets XIT and *should* turn XIT off. If not, file a
|
|
bug report against the Hamlib backend.
|
|
.sp
|
|
\fBN.B\fP This functionality is under transition and in the future will
|
|
need to be activated with the \fIset_func\fP command.
|
|
.TP
|
|
.B z, get_xit
|
|
Get 'XIT', in Hz.
|
|
.TP
|
|
.B T, set_ptt 'PTT'
|
|
Set 'PTT', 0 (RX) or 1 (TX).
|
|
.TP
|
|
.B t, get_ptt
|
|
Get 'PTT' status.
|
|
.TP
|
|
.B 0x8b, get_dcd
|
|
Get 'DCD' (squelch) status, 0 (Closed) or 1 (Open)
|
|
.TP
|
|
.B R, set_rptr_shift 'Rptr Shift'
|
|
Set 'Rptr Shift': "+", "-" or something else for none.
|
|
.TP
|
|
.B r, get_rptr_shift
|
|
Get 'Rptr Shift'. Returns "+", "-" or "None".
|
|
.TP
|
|
.B O, set_rptr_offs 'Rptr Offset'
|
|
Set 'Rptr Offset', in Hz.
|
|
.TP
|
|
.B o, get_rptr_offs
|
|
Get 'Rptr Offset', in Hz.
|
|
.TP
|
|
.B C, set_ctcss_tone 'CTCSS Tone'
|
|
Set 'CTCSS Tone', in tenths of Hz.
|
|
.TP
|
|
.B c, get_ctcss_tone
|
|
Get 'CTCSS Tone', in tenths of Hz.
|
|
.TP
|
|
.B D, set_dcs_code 'DCS Code'
|
|
Set 'DCS Code'.
|
|
.TP
|
|
.B d, get_dcs_code
|
|
Get 'DCS Code'.
|
|
.TP
|
|
.B 0x90, set_ctcss_sql 'CTCSS Sql'
|
|
Set 'CTCSS Sql' tone, in tenths of Hz.
|
|
.TP
|
|
.B 0x91, get_ctcss_sql
|
|
Get 'CTCSS Sql' tone, in tenths of Hz.
|
|
.TP
|
|
.B 0x92, set_dcs_sql 'DCS Sql'
|
|
Set 'DCS Sql' code.
|
|
.TP
|
|
.B 0x93, get_dcs_sql
|
|
Get 'DCS Sql' code.
|
|
.TP
|
|
.B I, set_split_freq 'Tx Frequency'
|
|
Set 'TX Frequency', in Hz.
|
|
.TP
|
|
.B i, get_split_freq
|
|
Get 'TX Frequency', in Hz.
|
|
.TP
|
|
.B X, set_split_mode 'TX Mode' 'TX Passband'
|
|
Set 'TX Mode': AM, FM, CW, CWR, USB, LSB, RTTY, RTTYR, WFM, AMS,
|
|
PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.
|
|
.sp
|
|
The 'TX Passband' is the exact passband in Hz, or '0' for the Hamlib
|
|
backend default.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B x, get_split_mode
|
|
Get 'TX Mode' and 'TX Passband'.
|
|
.sp
|
|
Returns TX mode as a string from \fIset_split_mode\fP above and TX passband in
|
|
Hz.
|
|
.TP
|
|
.B S, set_split_vfo 'Split' 'TX VFO'
|
|
Set 'Split' mode, '0' or '1', and 'TX VFO' from \fIset_vfo\fP above.
|
|
.TP
|
|
.B s, get_split_vfo
|
|
Get 'Split' mode, '0' or '1', and 'TX VFO'.
|
|
.TP
|
|
.B N, set_ts 'Tuning Step'
|
|
Set 'Tuning Step', in Hz.
|
|
.TP
|
|
.B n, get_ts
|
|
Get 'Tuning Step', in Hz.
|
|
.TP
|
|
.B U, set_func 'Func' 'Func Status'
|
|
Set 'Func' 'Func Status'.
|
|
.sp
|
|
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.
|
|
.sp
|
|
Func Status argument is a non null value for "activate", "de-activate"
|
|
otherwise, much as TRUE/FALSE definitions in C language (true is non-zero and
|
|
false is zero).
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B u, get_func 'Func'
|
|
Get 'Func Status'.
|
|
.sp
|
|
Returns 'Func Status' as a non null value for the 'Func' passed.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B L, set_level 'Level' 'Level Value'
|
|
Set 'Level' 'Level Value'.
|
|
.sp
|
|
Level is one of: PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR, PBT_IN, PBT_OUT,
|
|
CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF, COMP, AGC, BKINDL, BAL, METER,
|
|
VOXGAIN, ANTIVOX, SLOPE_LOW, SLOPE_HIGH, RAWSTR, SQLSTAT, SWR, ALC, STRENGTH.
|
|
.sp
|
|
The Level Value can be a float or an integer.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B l, get_level
|
|
Get 'Level' 'Level Value'.
|
|
.sp
|
|
Returns Level as a string from \fIset_level\fP above and Level value as a float
|
|
or integer.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B P, set_parm 'Parm' 'Parm Value'
|
|
Set 'Parm' 'Parm Value'
|
|
.sp
|
|
Parm is one of: ANN, APO, BACKLIGHT, BEEP, TIME, BAT, KEYLIGHT.
|
|
.TP
|
|
.B p, get_parm 'Parm'
|
|
Get 'Parm Value'.
|
|
.sp
|
|
Returns 'Parm Value' as a float or integer for the 'Parm' passed.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B B, set_bank 'Bank'
|
|
Set 'Bank'. Sets the current memory bank number.
|
|
.TP
|
|
.B E, set_mem 'Memory#'
|
|
Set 'Memory#' channel number.
|
|
.TP
|
|
.B e, get_mem
|
|
Get 'Memory#' channel number.
|
|
.TP
|
|
.B G, vfo_op 'Mem/VFO Op'
|
|
Perform 'Mem/VFO Op'.
|
|
.sp
|
|
Mem VFO operation is one of: CPY, XCHG, FROM_VFO, TO_VFO, MCL, UP, DOWN,
|
|
BAND_UP, BAND_DOWN, LEFT, RIGHT, TUNE, TOGGLE.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B g, scan 'Scan Fct' 'Scan Channel'
|
|
Perform 'Scan Fct' 'Scan Channel'.
|
|
.sp
|
|
Scan function/channel is one of: STOP, MEM, SLCT, PRIO, PROG, DELTA, VFO, PLT.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B H, set_channel 'Channel'
|
|
Set memory 'Channel' data. Not implemented yet.
|
|
.TP
|
|
.B h, get_channel
|
|
Get memory 'Channel' data. Not implemented yet.
|
|
.TP
|
|
.B A, set_trn 'Transceive'
|
|
Set 'Transceive' mode (reporting event): OFF, RIG, POLL.
|
|
.sp
|
|
\fBN.B.\fP 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.
|
|
.TP
|
|
.B a, get_trn
|
|
Get 'Transceive' mode (reporting event) as in \fIset_trn\fP above.
|
|
.TP
|
|
.B Y, set_ant 'Antenna'
|
|
Set 'Antenna' number (0, 1, 2, ..).
|
|
.TP
|
|
.B y, get_ant
|
|
Get 'Antenna' number (0, 1, 2, ..).
|
|
.TP
|
|
.B *, reset 'Reset'
|
|
Perform rig 'Reset'.
|
|
.sp
|
|
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.
|
|
.TP
|
|
.B b, send_morse 'Morse'
|
|
Send 'Morse' symbols.
|
|
.TP
|
|
.B 0x87, set_powerstat 'Power Status'
|
|
Set power On/Off/Standby 'Power Status'.
|
|
.sp
|
|
0 = Power Off, 1 = Power On, 2 = Power Standby. Defined as a bitmask in rig.h.
|
|
.TP
|
|
.B 0x88, get_powerstat
|
|
Get power On/Off/Standby 'Power Status' as in \fIset_powerstat\fP above.
|
|
.TP
|
|
.B 0x89, send_dtmf 'Digits'
|
|
Set DTMF 'Digits'.
|
|
.TP
|
|
.B 0x8a, recv_dtmf
|
|
Get DTMF 'Digits'.
|
|
.TP
|
|
.B _, get_info
|
|
Get misc information about the rig (no VFO in 'VFO mode' or value is passed).
|
|
.TP
|
|
.B 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.
|
|
.sp
|
|
\fBN.B.\fP: 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.
|
|
.sp
|
|
VFO parameter not used in 'VFO mode'.
|
|
.TP
|
|
.B 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
|
|
Returns 'Power mW'
|
|
.sp
|
|
Converts a Power value in a range of \fI0.0 ... 1.0\fP to the real transmit
|
|
power in milli-Watts (integer). The \fIfrequency\fP and \fImode\fP also need to
|
|
be provided as output power may vary according to these values.
|
|
.sp
|
|
VFO parameter not used in 'VFO mode'.
|
|
.TP
|
|
.B 4, mW2power 'Power mW' 'Frequency' 'Mode'
|
|
Returns 'Power [0.0..1.0]'
|
|
.sp
|
|
Converts the real transmit power in milli-Watts (integer) to a Power value in
|
|
a range of \fI0.0 ... 1.0\fP. The \fIfrequency\fP and \fImode\fP also need to
|
|
be provided as output power may vary according to these values.
|
|
.sp
|
|
VFO parameter not used in 'VFO mode'.
|
|
.TP
|
|
.B w, send_cmd 'Cmd'
|
|
Send raw command string to rig.
|
|
.sp
|
|
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.
|
|
.TP
|
|
.B chk_vfo
|
|
Returns "CHKVFO 1\\n" (single line only) if \fBrigctld\fP was invoked with the
|
|
\fI-o\fP or \fI--vfo\fP option, "CHKVFO 0\\n" if not.
|
|
.sp
|
|
When in VFO mode the client will need to pass 'VFO' as the first parameter to
|
|
\fI\\set\fP or \fI\\get\fP commands. 'VFO' is one of the strings defined
|
|
for \fI\\set_vfo\fP above.
|
|
.SH PROTOCOL
|
|
\fBDefault Protocol\fP
|
|
.PP
|
|
The \fBrigctld\fP protocol is intentionally simple. Commands are entered on
|
|
a single line with any needed values. In Perl, reliable results are obtained
|
|
by terminating each command string with a newline character, '\\n'.
|
|
.sp
|
|
Example \fIset\fP (Perl code):
|
|
.sp
|
|
print $socket "F 14250000\\n";
|
|
.br
|
|
print $socket "\\\\set_mode LSB 2400\\n"; # escape leading '\\'
|
|
.PP
|
|
A one line response will be sent as a reply to \fIset\fP commands,
|
|
"RPRT \fIx\fP\\n" where \fIx\fP is the Hamlib error code with '0'
|
|
indicating success of the command.
|
|
.PP
|
|
Responses from \fBrigctld\fP \fIget\fP commands are text values and match the
|
|
same tokens used in the \fIset\fP commands. Each value is returned on its own
|
|
line. On error the string "RPRT \fIx\fP\\n" is returned where \fIx\fP is the
|
|
Hamlib error code.
|
|
.sp
|
|
Example \fIget\fP (Perl code):
|
|
.sp
|
|
print $socket "f\\n";
|
|
.br
|
|
"14250000\\n"
|
|
.PP
|
|
Most \fIget\fP functions return one to three values. A notable exception is
|
|
the \fI\\dump_caps\fP function which returns many lines of key:value pairs.
|
|
.PP
|
|
This protocol is primarily used by the \fINET rigctl\fP (rigctl model 2)
|
|
backend which allows applications already written for Hamlib's C API to take
|
|
advantage of \fBrigctld\fP 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 \fI-t\fP
|
|
option above).
|
|
.PP
|
|
\fBExtended Response Protocol\fP
|
|
.PP
|
|
An \fIEXPERIMENTAL\fP Extended Response protocol has been introduced into
|
|
\fBrigctld\fP as of February 16, 2010. This protocol adds several rules
|
|
to the strings returned by \fBrigctld\fP and adds a rule for the command
|
|
syntax.
|
|
.PP
|
|
1. The command received by \fBrigctld\fP 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.
|
|
.PP
|
|
2. The last line of each block is the string "RPRT \fIx\fP\\n" where \fIx\fP is
|
|
the numeric return value of the Hamlib backend function that was called by the
|
|
command.
|
|
.PP
|
|
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 '+'.
|
|
.PP
|
|
4. All commands received will be acknowledged by \fBrigctld\fP with lines from
|
|
rules 1 and 2. Lines from rule 3 are only returned when data values must be
|
|
returned to the client.
|
|
.PP
|
|
An example response to a \fI+\\set_mode\fP command sent from the shell prompt
|
|
(note the prepended '+'):
|
|
.sp
|
|
$ echo "+M USB 2400" | nc -w 1 localhost 4532
|
|
.br
|
|
set_mode: USB 2400
|
|
.br
|
|
RPRT 0
|
|
.PP
|
|
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.
|
|
.PP
|
|
An example response to a \fI\\get_mode\fP query:
|
|
.sp
|
|
$ echo "+\\get_mode" | nc -w 1 localhost 4532
|
|
.br
|
|
get_mode:
|
|
.br
|
|
Mode: USB
|
|
.br
|
|
Passband: 2400
|
|
.br
|
|
RPRT 0
|
|
.PP
|
|
In this case, as no value is passed to \fBrigctld\fP, the first line consists
|
|
only of the long command name. The final line shows that the command was
|
|
processed successfully by the rig backend.
|
|
.PP
|
|
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
|
|
\fIispunct()\fP function except '\\', '?', or '_' will cause that character to
|
|
become the response separator and the entire response will be on one line.
|
|
.PP
|
|
Separator character summary:
|
|
.TP
|
|
.B '+'
|
|
.br
|
|
Each record of the response is appended with a newline ('\\n').
|
|
.TP
|
|
.B ';', '|', or ','
|
|
.br
|
|
Each record of the response is appended by the given character resulting in
|
|
entire response on one line.
|
|
.sp
|
|
Common record separators for text representations of spreadsheet data, etc.
|
|
.TP
|
|
.B '?'
|
|
.br
|
|
Reserved for 'help' in rigctl short command
|
|
.TP
|
|
.B '_'
|
|
.br
|
|
Reserved for \\get_info short command
|
|
.TP
|
|
.B '#'
|
|
.br
|
|
Reserved for comments when reading a command file script
|
|
.sp
|
|
Other punctuation characters have not been tested! Use at your own risk.
|
|
.PP
|
|
For example, invoking a \fI;\\get_mode\fP query with a leading ';' returns:
|
|
.sp
|
|
get_mode:;Mode: USB;Passband: 2400;RPRT 0
|
|
.sp
|
|
Or, using the pipe character '|' returns:
|
|
.sp
|
|
get_mode:|Mode: USB|Passband: 2400|RPRT 0
|
|
.sp
|
|
And a \\set_mode command prepended with a '|' returns:
|
|
.sp
|
|
set_mode: USB 2400|RPRT 0
|
|
.PP
|
|
Such a format will allow reading a response as a single event using a preferred
|
|
response separator. Other punctuation characters have not been tested!
|
|
.PP
|
|
The following commands have been tested with the Extended Response protocol and
|
|
the included \fBtestctld.pl\fP script:
|
|
.br
|
|
\fI\\set_freq\fP \fI\\get_freq\fP \fI\\set_split_freq\fP \fI\\get_split_freq\fP
|
|
.br
|
|
\fI\\set_mode\fP \fI\\get_mode\fP \fI\\set_split_mode\fP \fI\\get_split_mode\fP
|
|
.br
|
|
\fI\\set_vfo\fP \fI\\get_vfo\fP \fI\\set_split_vfo\fP \fI\\get_split_vfo\fP
|
|
.br
|
|
\fI\\set_rit\fP \fI\\get_rit\fP
|
|
.br
|
|
\fI\\set_xit\fP \fI\\get_xit\fP
|
|
.br
|
|
\fI\\set_ptt\fP \fI\\get_ptt\fP
|
|
.br
|
|
\fI\\power2mW\fP \fI\\mW2power\fP
|
|
.br
|
|
\fI\\dump_caps\fP
|
|
.SH EXAMPLES
|
|
Start \fBrigctld\fP for a Yaesu FT-920 using a USB-to-serial adapter and
|
|
backgrounding:
|
|
.PP
|
|
$ rigctld -m 114 -r /dev/ttyUSB1 &
|
|
.PP
|
|
Start \fBrigctld\fP for a Yaesu FT-920 using a USB to serial adapter while
|
|
setting baud rate and stop bits, and backgrounding:
|
|
.PP
|
|
$ rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
|
|
.PP
|
|
Start \fBrigctld\fP for an Elecraft K3 using COM2 on Win32:
|
|
.sp
|
|
$ rigctld -m 229 -r COM2
|
|
.PP
|
|
Connect to the already running \fBrigctld\fP, and set current frequency to
|
|
14.266 MHz with a 1 second read timeout using the default protocol from the
|
|
shell prompt:
|
|
.sp
|
|
$ echo "\\set_freq 14266000" | nc -w 1 localhost 4532
|
|
.PP
|
|
Connect to a running \fBrigctld\fP with \fBrigctl\fP on the local host:
|
|
.sp
|
|
$ rigctl -m2
|
|
.SH DIAGNOSTICS
|
|
The \fB-v\fP, \fB--verbose\fP, option allows different levels of diagnostics
|
|
to be output to \fBstderr\fP and correspond to -v for BUG, -vv for ERR,
|
|
-vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
|
|
.PP
|
|
A given verbose level is useful for providing needed debugging information to
|
|
the email address below. For example, TRACE output shows all of the values
|
|
sent to and received from the radio which is very useful for radio backend
|
|
library development and may be requested by the developers. See the
|
|
\fBREADME.betatester\fP and \fBREADME.developer\fP files for more information.
|
|
.SH SECURITY
|
|
No authentication whatsoever; DO NOT leave this TCP port open wide to the
|
|
Internet. Please ask if stronger security is needed or consider using an
|
|
SSH tunnel.
|
|
.PP
|
|
As \fBrigctld\fP does not need any greater permissions than \fBrigctl\fP, it
|
|
is advisable to not start \fBrigctld\fP as \fIroot\fP or another system user
|
|
account in order to limit any vulnerability.
|
|
.SH BUGS
|
|
The daemon is not detaching and backgrounding itself.
|
|
.PP
|
|
Much testing needs to be done.
|
|
.SH REPORTING BUGS
|
|
Report bugs to <hamlib-developer@lists.sourceforge.net>.
|
|
.PP
|
|
We are already aware of the bugs in the previous section :-)
|
|
.SH AUTHORS
|
|
Written by Stephane Fillod, Nate Bargmann, and the Hamlib Group
|
|
.PP
|
|
<http://www.hamlib.org>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2000-2010 Stephane Fillod
|
|
.br
|
|
Copyright \(co 2011-2013 Nate Bargmann
|
|
.br
|
|
Copyright \(co 2000-2010 the Hamlib Group.
|
|
.PP
|
|
This is free software; see the source for copying conditions.
|
|
There is NO warranty; not even for MERCHANTABILITY
|
|
or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH SEE ALSO
|
|
.BR rigctl (1),
|
|
.BR hamlib (3)
|