1RIGCTLD(1) Hamlib Utilities RIGCTLD(1)
2
6 rigctld - TCP radio control daemon
7
9 rigctld [-hlLouV] [-m id] [-r device] [-p device] [-d device] [-P type]
10 [-D type] [-s baud] [-c id] [-T IPADDR] [-t number]
11 [-C parm=val] [-X seconds] [-v[-Z]]
12
14 The rigctld program is a radio control daemon that handles client re‐
15 quests via TCP sockets. This allows multiple user programs to share
16 one radio (this needs more development). Multiple radios can be con‐
17 trolled on different TCP ports by use of multiple rigctld processes.
18 Note that multiple processes/ports are also necessary if some clients
19 use extended responses and/or vfo mode. So up to 4 processes/ports may
20 be needed for each combination of extended response/vfo mode. The syn‐
21 tax of the commands are the same as rigctl(1). It is hoped that
22 rigctld will be especially useful for client authors using languages
23 such as Perl, Python, PHP, and others.
24 rigctld communicates to a client through a TCP socket using text com‐
26 mands shared with rigctl. The protocol is simple, commands are sent to
27 rigctld on one line and rigctld responds to get commands with the re‐
28 quested values, one per line, when successful, otherwise, it responds
29 with one line “RPRT x”, where ‘x’ is a negative number indicating the
30 error code. Commands that do not return values respond with the line
31 “RPRT x”, where ‘x’ is ‘0’ when successful, otherwise is a regative
32 number indicating the error code. Each line is terminated with a new‐
33 line ‘\n’ character. This protocol is primarily for use by the NET
34 rigctl (radio model 2) backend.
35 A separate Extended Response Protocol extends the above behavior by
37 echoing the received command string as a header, any returned values as
38 a key: value pair, and the “RPRT x” string as the end of response
39 marker which includes the Hamlib success or failure value. See the
40 PROTOCOL section for details. Consider using this protocol for clients
41 that will interact with rigctld directly through a TCP socket.
42 Keep in mind that Hamlib is BETA level software. While a lot of back‐
44 end libraries lack complete rotator support, the basic functions are
45 usually well supported.
46 Please report bugs and provide feedback at the e-mail address given in
48 the BUGS section below. Patches and code enhancements sent to the same
49 address are welcome.
50
52 This program follows the usual GNU command line syntax. Short options
53 that take an argument may have the value follow immediately or be sepa‐
54 rated by a space. Long options starting with two dashes (‘-’) require
55 an ‘=’ between the option and any argument.
56 Here is a summary of the supported options:
58 -m, --model=id
60 Select radio model number. Defaults to dummy device.
61 See model list (use “rigctl -l”).
63 Note: rigctl (or third party software using the C API) will use
65 radio model 2 for NET rigctl (this model number is not used for
66 rigctld even though it shows in the model list).
67 -r, --rig-file=device
69 Use device as the file name of the port connected to the radio.
70 Often a serial port, but could be a USB to serial adapter. Typ‐
72 ically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux,
73 COM1, COM2, etc. on MS Windows. The BSD flavors and Mac OS/X
74 have their own designations. See your system's documentation.
75 Can be a network address:port, e.g. 127.0.0.1:12345
77 The special string “uh-rig” may be given to enable micro-ham de‐
79 vice support.
80 -p, --ptt-file=device
82 Use device as the file name of the Push-To-Talk device using a
83 device file as described above.
84 -d, --dcd-file=device
86 Use device as the file name of the Data Carrier Detect device
87 using a device file as described above.
88 -P, --ptt-type=type
90 Use type of Push-To-Talk device.
91 Supported types are ‘RIG’ (CAT command), ‘DTR’, ‘RTS’, ‘PARAL‐
93 LEL’, ‘NONE’, overriding PTT type defined in the rig's backend.
94 Some side effects of this command are that when type is set to
96 DTR, read PTT state comes from the Hamlib frontend, not read
97 from the radio. When set to NONE, PTT state cannot be read or
98 set even if rig backend supports reading/setting PTT status from
99 the rig.
100 -D, --dcd-type=type
102 Use type of Data Carrier Detect device.
103 Supported types are ‘RIG’ (CAT command), ‘DSR’, ‘CTS’, ‘CD’,
105 ‘PARALLEL’, ‘NONE’.
106 -s, --serial-speed=baud
108 Set serial speed to baud rate.
109 Uses maximum serial speed from radio backend capabilities (set
111 by -m above) as the default.
112 -c, --civaddr=id
114 Use id as the CI-V address to communicate with the rig.
115 Only useful for Icom and some Ten-Tec rigs.
117 Note: The id is in decimal notation, unless prefixed by 0x, in
119 which case it is hexadecimal.
120 -S, --separator=char
122 Use char as separator instead of line feed
123 The default is 0 Recommend using $ or @ as they work on both
125 Unix and Windows
126 -T, --listen-addr=IPADDR
128 Use IPADDR as the listening IP address.
129 The default is ANY (0.0.0.0).
131 rigctld can be run and connected to like this:
133 rigctld
135 rigctl -m 2
136 rigctl -m 2 -r 127.0.0.1
137 rigctl -m 2 -r localhost
138 rigctl -m 2 -r 192.168.1.1 (local IP address)
139 rigctl -m 2 -r ::1 (on Linux rigctld doesn't listen on IPV6 by default)
140 rigctld -T 127.0.0.1
142 rigctl -m 2
143 rigctl -m 2 -r 127.0.0.1
144 Exceptions:
145 rigctl -m 2 -r localhost (only works if localhost is IPV4 address)
146 rigctld -T localhost (will set up on IPV4 or IPV6 based on localhost)
148 rigctl -m 2
149 rigctl -m 2 -r localhost
150 rigctl -m 2 ip6-localhost
151 Exceptions:
152 rigctl -m 2 -r 127.0.0.1 (only works if localhost is IPV4 address)
153 rigctl -m 2 -r ::1 (only works localhost is IPV6 address)
154 On Linux only where ip6-localhost is fe00::0:
156 rigctld -T ip6-localhost
157 rigctl -m 2 -r ip6-localhost
158 -t, --port=number
160 Use number as the TCP listening port.
161 The default is 4532.
163 Note: As rotctld's default port is 4533, it is advisable to use
165 even numbered ports for rigctld, e.g. 4532, 4534, 4536, etc.
166 -L, --show-conf
168 List all config parameters for the radio defined with -m above.
169 -C, --set-conf=parm=val[,parm=val]
171 Set radio configuration parameter(s), e.g. stop_bits=2.
172 Use the -L option above for a list of configuration parameters
174 for a given model number.
175 -u, --dump-caps
177 Dump capabilities for the radio defined with -m above and exit.
178 -l, --list
180 List all model numbers defined in Hamlib and exit.
181 The list is sorted by model number.
183 Note: In Linux the list can be scrolled back using Shift-
185 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
186 minal in X or the cmd window in Windows. The output can be
187 piped to more(1) or less(1), e.g. “rigctl -l | more”.
188 -o, --vfo
190 Enable vfo mode.
191 An extra VFO argument will be required in front of each appro‐
193 priate command (except set_vfo). Otherwise, ‘currVFO’ is used
194 when this option is not set and an extra VFO argument is not
195 used.
196 See chk_vfo below.
198 -v, --verbose
200 Set verbose mode, cumulative (see DIAGNOSTICS below).
201 -W, --twiddle_timeout=seconds
203 Enables timeout when VFO twiddling is detected. Some functions
204 will be ignored.
205 Should only be needed when controlling software should be
207 "paused" so you can move the VFO. Continuous movement extends
208 the timeout.
209 -x, --uplink=option
211 1=Sub, 2=Main
212 For GPredict use to ignore get_freq for Sub or Main uplink VFO.
214 Should allow downlink VFO movement without confusing GPredict or
216 the uplink
217 -Z, --debug-time-stamps
219 Enable time stamps for the debug messages.
220 Use only in combination with the -v option as it generates no
222 output on its own.
223 -A, --password
225 Sets password on rigctld which requires hamlib to use
226 rig_set_password and rigctl to use \password to access rigctld.
227 A 32-char shared secret will be displayed to be used on the
228 client side.
229 -R, --rigctld_idle
231 Will make rigctld close the rig when no clients are connected.
232 Normally remains connected to speed up connects.
233 -h, --help
235 Show a summary of these options and exit.
236 -V, --version
238 Show version of rigctl and exit.
239 Note: Some options may not be implemented by a given backend and will
241 return an error. This is most likely to occur with the --set-conf and
242 --show-conf options.
243 Please note that the backend for the radio to be controlled, or the ra‐
245 dio itself may not support some commands. In that case, the operation
246 will fail with a Hamlib error code.
247
249 Commands can be sent over the TCP socket either as a single char, or as
250 a long command name plus the value(s) space separated on one ‘\n’ ter‐
251 minated line. See PROTOCOL.
252 Since most of the Hamlib operations have a set and a get method, a sin‐
254 gle pper case letter will be used for set methods whereas the corre‐
255 sponding single lower case letter refers to the get method. Each oper‐
256 ation also has a long name; prepend a backslash, ‘\’, to send a long
257 command name all in lower case.
258 Example (Perl): “print $socket "\\dump_caps\n";” to see what the ra‐
260 dio's backend can do (Note: In Perl and many other languages a ‘\’ will
261 need to be escaped with a preceding ‘\’ so that even though two back‐
262 slash characters appear in the code, only one will be passed to
263 rigctld. This is a possible bug, beware!).
264 Note: The backend for the radio to be controlled, or the radio itself
266 may not support some commands. In that case, the operation will fail
267 with a Hamlib error message.
268 Here is a summary of the supported commands (In the case of set com‐
270 mands the quoted italicized string is replaced by the value in the de‐
271 scription. In the case of get commands the quoted italicized string is
272 the key name of the value returned.):
273 F, set_freq 'Frequency'
275 Set 'Frequency', in Hz.
276 Frequency may be a floating point or integer value.
278 f, get_freq
280 Get 'Frequency', in Hz.
281 Returns an integer value and the VFO hamlib thinks is active.
283 Note that some rigs (e.g. all Icoms) cannot track current VFO so
284 hamlib can get out of sync with the rig if the user presses rig
285 buttons like the VFO. rigctld clients should ensure they set
286 the intended VFO or use vfo mode.
287 M, set_mode 'Mode' 'Passband'
289 Set 'Mode' and 'Passband'.
290 Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
292 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’, ‘EC‐
293 SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
294 Passband is in Hz as an integer, -1 for no change, or ‘0’ for
296 the radio backend default.
297 Note: Passing a ‘?’ (query) as the first argument instead of a
299 Mode token will return a space separated list of radio backend
300 supported Modes. Use this to determine the supported Modes of a
301 given radio backend.
302 m, get_mode
304 Get 'Mode' and 'Passband'.
305 Returns Mode as a token and Passband in Hz as in set_mode above.
307 V, set_vfo 'VFO'
309 Set 'VFO'.
310 VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
312 ‘Main’, ‘Sub’, ‘TX’, ‘RX’, ‘MainA’, ‘MainB’, ‘MainC’, ‘SubA’,
313 ‘SubB’ ‘SubC’.
314 In VFO mode (see --vfo option above) only a single VFO parameter
316 is required:
317 $ rigctl -m 229 -r /dev/rig -o
319 Rig command: V
321 VFO: VFOB
322 Rig command:
324 v, get_vfo
326 Get current 'VFO'.
327 Returns VFO as a token as in set_vfo above.
329 J, set_rit 'RIT'
331 Set 'RIT'.
332 RIT is in Hz and can be + or -. A value of ‘0’ resets RIT (Re‐
334 ceiver Incremental Tuning) to match the VFO frequency.
335 Note: RIT needs to be explicitly activated or deactivated with
337 the set_func command. This allows setting the RIT offset inde‐
338 pendently of its activation and allows RIT to remain active
339 while setting the offset to ‘0’.
340 j, get_rit
342 Get 'RIT' in Hz.
343 Returned value is an integer.
345 Z, set_xit 'XIT'
347 Set 'XIT'.
348 XIT is in Hz and can be + or -. A value of ‘0’ resets XIT
350 (Transmitter Incremental Tuning) to match the VFO frequency.
351 Note: XIT needs to be explicitly activated or deactivated with
353 the set_func command. This allows setting the XIT offset inde‐
354 pendently of its activation and allows XIT to remain active
355 while setting the offset to ‘0’.
356 z, get_xit
358 Get 'XIT' in Hz.
359 Returned value is an integer.
361 T, set_ptt 'PTT'
363 Set 'PTT'.
364 PTT is a value: ‘0’ (RX), ‘1’ (TX), ‘2’ (TX mic), or ‘3’ (TX
366 data).
367 t, get_ptt
369 Get 'PTT' status.
370 Returns PTT as a value in set_ptt above.
372 S, set_split_vfo 'Split' 'TX VFO'
374 Set 'Split' mode.
375 Split is either ‘0’ = Normal or ‘1’ = Split.
377 Set 'TX VFO'.
379 TX VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’,
381 ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
382 s, get_split_vfo
384 Get 'Split' mode.
385 Split is either ‘0’ = Normal or ‘1’ = Split.
387 Get 'TX VFO'.
389 TX VFO is a token as in set_split_vfo above.
391 I, set_split_freq 'Tx Frequency'
393 Set 'TX Frequency', in Hz.
394 Frequency may be a floating point or integer value.
396 i, get_split_freq
398 Get 'TX Frequency', in Hz.
399 Returns an integer value.
401 X, set_split_mode 'TX Mode' 'TX Passband'
403 Set 'TX Mode' and 'TX Passband'.
404 TX Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
406 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’, ‘EC‐
407 SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
408 TX Passband is in Hz as an integer, or ‘0’ for the radio backend
410 default.
411 Note: Passing a ‘?’ (query) as the first argument instead of a
413 TX Mode token will return a space separated list of radio back‐
414 end supported TX Modes. Use this to determine the supported TX
415 Modes of a given radio backend.
416 x, get_split_mode
418 Get 'TX Mode' and 'TX Passband'.
419 Returns TX Mode as a token and TX Passband in Hz as in
421 set_split_mode above.
422 Y, set_ant 'Antenna'
424 Set 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
425 Option depends on rig..for Icom it probably sets the Tx & Rx an‐
427 tennas as in the IC-7851. See your manual for rig specific op‐
428 tion values. Most rigs don't care about the option.
429 For the IC-7851 (and perhaps others) it means this:
431 1 = TX/RX = ANT1
433 2 = TX/RX = ANT2
434 3 = TX/RX = ANT3
435 4 = TX/RX = ANT1/ANT4
436 5 = TX/RX = ANT2/ANT4
437 6 = TX/RX = ANT3/ANT4
438 y, get_ant
440 Get 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
441 b, send_morse 'Morse'
443 Send 'Morse' symbols.
444 0x8b, get_dcd
446 Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
447 R, set_rptr_shift 'Rptr Shift'
449 Set 'Rptr Shift'.
450 Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
452 r, get_rptr_shift
454 Get 'Rptr Shift'.
455 Returns ‘+’, ‘-’, or ‘None’.
457 O, set_rptr_offs 'Rptr Offset'
459 Set 'Rptr Offset', in Hz.
460 o, get_rptr_offs
462 Get 'Rptr Offset', in Hz.
463 C, set_ctcss_tone 'CTCSS Tone'
465 Set 'CTCSS Tone', in tenths of Hz.
466 c, get_ctcss_tone
468 Get 'CTCSS Tone', in tenths of Hz.
469 D, set_dcs_code 'DCS Code'
471 Set 'DCS Code'.
472 d, get_dcs_code
474 Get 'DCS Code'.
475 0x90, set_ctcss_sql 'CTCSS Sql'
477 Set 'CTCSS Sql' tone, in tenths of Hz.
478 0x91, get_ctcss_sql
480 Get 'CTCSS Sql' tone, in tenths of Hz.
481 0x92, set_dcs_sql 'DCS Sql'
483 Set 'DCS Sql' code.
484 0x93, get_dcs_sql
486 Get 'DCS Sql'
487 code.
488 N, set_ts 'Tuning Step'
490 Set 'Tuning Step', in Hz.
491 n, get_ts
493 Get 'Tuning Step', in Hz.
494 U, set_func 'Func' 'Func Status'
496 Set 'Func' and 'Func Status'.
497 Func is a token: ‘FAGC’, ‘NB’, ‘COMP’, ‘VOX’, ‘TONE’, ‘TSQL’,
499 ‘SBKIN’, ‘FBKIN’, ‘ANF’, ‘NR’, ‘AIP’, ‘APF’, ‘MON’, ‘MN’, ‘RF’,
500 ‘ARO’, ‘LOCK’, ‘MUTE’, ‘VSC’, ‘REV’, ‘SQL’, ‘ABM’, ‘BC’, ‘MBC’,
501 ‘RIT’, ‘AFC’, ‘SATMODE’, ‘SCOPE’, ‘RESUME’, ‘TBURST’, ‘TUNER’,
502 ‘XIT’.
503 Func Status is a non null value for “activate” or “de-activate”
505 otherwise, much as TRUE/FALSE definitions in the C language
506 (true is non-zero and false is zero, ‘0’).
507 Note: Passing a ‘?’ (query) as the first argument instead of a
509 Func token will return a space separated list of radio backend
510 supported set function tokens. Use this to determine the sup‐
511 ported functions of a given radio backend.
512 u, get_func 'Func'
514 Get 'Func Status'.
515 Returns Func Status as a non null value for the Func token given
517 as in set_func above.
518 Note: Passing a ‘?’ (query) as the first argument instead of a
520 Func token will return a space separated list of radio backend
521 supported get function tokens. Use this to determine the sup‐
522 ported functions of a given radio backend.
523 L, set_level 'Level' 'Level Value'
525 Set 'Level' and 'Level Value'.
526 evel is a token: ‘PREAMP’, ‘ATT’, ‘VOXDELAY’, ‘AF’, ‘RF’, ‘SQL’,
528 ‘IF’, ‘APF’, ‘NR’, ‘PBT_IN’, ‘PBT_OUT’, ‘CWPITCH’, ‘RFPOWER’,
529 ‘MICGAIN’, ‘KEYSPD’, ‘NOTCHF’, ‘COMP’, ‘AGC’, ‘BKINDL’, ‘BAL’,
530 ‘METER’, ‘VOXGAIN’, ‘ANTIVOX’, ‘SLOPE_LOW’, ‘SLOPE_HIGH’,
531 ‘BKIN_DLYMS’, ‘RAWSTR’, ‘SWR’, ‘ALC’, ‘STRENGTH’, ‘RFPOWER_ME‐
532 TER’, ‘COMPMETER’, ‘VD_METER’, ‘ID_METER’, ‘NOTCHF_RAW’, ‘MONI‐
533 TOR_GAIN’, ‘NQ’, ‘RFPOWER_METER_WATTS‘SPECTRUM_SPAN’, ‘SPEC‐
534 TRUM_EDGE_LOW’, ‘SPECTRUM_EDGE_HIGH’, ‘SPECTRUM_SPEED‘SPEC‐
535 TRUM_REF’, (oqSPECTRUM_AVG’, ‘SPECTRUM_ATT‘USB_AF’.
536 The Level Value can be a float or an integer value. For the AGC
538 token the value is one of ‘0’ = OFF, ‘1’ = SUPERFAST, ‘2’ =
539 FAST, ‘3’ = SLOW, ‘4’ = USER, ‘5’ = MEDIUM, ‘6’ = AUTO. Note
540 that not all values work on all rigs. To list usable values do
541 'rigctl -m [modelnum] -u | grep "AGC levels"' or for Windows
542 'rigctl -m [modelnum] -u | find "AGC levels"'.
543 Note: Passing a ‘?’ (query) as the first argument instead of a
545 Level token will return a space separated list of radio backend
546 supported set level tokens. Use this to determine the supported
547 levels of a given radio backend.
548 l, get_level 'Level'
550 Get 'Level Value'.
551 Returns Level Value as a float or integer for the Level token
553 given as in set_level above.
554 Note: Passing a ‘?’ (query) as the first argument instead of a
556 Level token will return a space separated list of radio backend
557 supported get level tokens. Use this to determine the supported
558 levels of a given radio backend.
559 P, set_parm 'Parm' 'Parm Value'
561 Set 'Parm' and 'Parm Value'.
562 Parm is a token: ‘ANN’, ‘APO’, ‘BACKLIGHT’, ‘BEEP’, ‘TIME’,
564 ‘BAT’, ‘KEYLIGHT’.
565 Note: Passing a ‘?’ (query) as the first argument instead of a
567 Parm token will return a space separated list of radio backend
568 supported set parameter tokens. Use this to determine the sup‐
569 ported parameters of a given radio backend.
570 p, get_parm 'Parm'
572 Get 'Parm Value'.
573 Returns Parm Value as a float or integer for the Parm token
575 given as in set_parm above.
576 Note: Passing a ‘?’ (query) as the first argument instead of a
578 Parm token will return a space separated list of radio backend
579 supported get parameter tokens. Use this to determine the sup‐
580 ported parameters of a given radio backend.
581 B, set_bank 'Bank'
583 Set 'Bank'.
584 Sets the current memory bank number.
586 E, set_mem 'Memory#'
588 Set 'Memory#' channel number.
589 e, get_mem
591 Get 'Memory#' channel number.
592 G, vfo_op 'Mem/VFO Op'
594 Perform a 'Mem/VFO Op'.
595 Mem/VFO Operation is a token: ‘CPY’, ‘XCHG’, ‘FROM_VFO’,
597 ‘TO_VFO’, ‘MCL’, ‘UP’, ‘DOWN’, ‘BAND_UP’, ‘BAND_DOWN’, ‘LEFT’,
598 ‘RIGHT’, ‘TUNE’, ‘TOGGLE’.
599 Note: Passing a ‘?’ (query) as the first argument instead of a
601 Mem/VFO Op token will return a space separated list of radio
602 backend supported Set Mem/VFO Op tokens. Use this to determine
603 the supported Mem/VFO Ops of a given radio backend.
604 g, scan 'Scan Fct' 'Scan Channel'
606 Perform a 'Scan Fct' on a 'Scan Channel'.
607 Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
609 ‘DELTA’, ‘VFO’, ‘PLT’.
610 Scan Channel is an integer (maybe?).
612 Note: Passing a ‘?’ (query) as the first argument instead of a
614 Scan Fct token will return a space separated list of radio back‐
615 end supported Scan Function tokens. Use this to determine the
616 supported Scan Functions of a given radio backend.
617 H, set_channel 'Channel'
619 Set memory 'Channel' data.
620 Not implemented yet.
622 h, get_channel 'readonly'
624 Get channel memory.
625 If readonly!=0 then only channel data is returned and rig re‐
627 mains on the current channel. If readonly=0 then rig will be
628 set to the channel requested. data.
629 A, set_trn 'Transceive'
631 Set 'Transceive' mode.
632 Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
634 Transceive is a mechanism for radios to report events without a
636 specific call for information.
637 Note: Passing a ‘?’ (query) as the first argument instead of a
639 Transceive token will return a space separated list of radio
640 backend supported Transceive mode tokens. Use this to determine
641 the supported Transceive modes of a given radio backend.
642 a, get_trn
644 Get 'Transceive' mode.
645 Transceive mode (reporting event) as in set_trn above.
647 *, reset 'Reset'
649 Perform rig 'Reset'.
650 Reset is a value: ‘0’ = None, ‘1’ = Software reset, ‘2’ = VFO
652 reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
653 Since these values are defined as a bitmask in include/ham‐
655 lib/rig.h, it should be possible to AND these values together to
656 do multiple resets at once, if the backend supports it or sup‐
657 ports a reset action via rig control at all.
658 0x87, set_powerstat 'Power Status'
660 Set 'Power Status'.
661 Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’ =
663 Power Standby.
664 0x88, get_powerstat
666 Get 'Power Status' as in set_powerstat above.
667 0x89, send_dtmf 'Digits'
669 Set DTMF 'Digits'.
670 0x8a, recv_dtmf
672 Get DTMF 'Digits'.
673 _, get_info
675 Get misc information about the rig.
676 0xf5, get_rig_info
678 Get misc information about the rig vfos and other info.
679 0xf3, get_vfo_info 'VFO'
681 Get misc information about a specific vfo.
682 dump_state
684 Return certain state information about the radio backend.
685 1, dump_caps
687 Not a real rig remote command, it just dumps capabilities, i.e.
688 what the backend knows about this model, and what it can do.
689 TODO: Ensure this is in a consistent format so it can be read
691 into a hash, dictionary, etc. Bug reports requested.
692 Note: This command will produce many lines of output so be very
694 careful if using a fixed length array! For example, running
695 this command against the Dummy backend results in over 5kB of
696 text output.
697 VFO parameter not used in 'VFO mode'.
699 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
701 Returns 'Power mW'.
702 Converts a Power value in a range of 0.0...1.0 to the real
704 transmit power in milli-Watts (integer).
705 'Frequency' and 'Mode' also need to be provided as output power
707 may vary according to these values.
708 VFO parameter is not used in VFO mode.
710 4, mW2power 'Power mW' 'Frequency' 'Mode'
712 Returns 'Power [0.0..1.0]'.
713 Converts the real transmit power in milli-Watts (integer) to a
715 Power value in a range of 0.0 ... 1.0.
716 'Frequency' and 'Mode' also need to be provided as output power
718 may vary according to these values.
719 VFO parameter is not used in VFO mode.
721 set_clock 'DateTime'
723 Set 'DateTime'
724 Sets rig clock -- note that some rigs do not handle seconds or
726 milliseconds. If you try to set that you will get a debug warn‐
727 ing message. Format is ISO8601.
728 Formats accepted
729 YYYY-MM-DDTHH:MM:SS.sss+ZZ (where +ZZ is either -/+ UTC offset)
730 YYYY-MM-DDTHH:MM:SS+ZZ
731 YYYY-MM-DDTHH:MM+ZZ
732 YYYY-MM-DD (sets date only)
733 get_clock
735 Get 'RigTime'
736 Gets rig clock -- note that some rigs do not handle seconds or
738 milliseconds. Format is ISO8601 YYYY-MM-DDTHH:MM:SS.sss+ZZ
739 where +ZZ is either -/+ UTC offset
740 chk_vfo
742 Returns “1\n” (single line only) if rigctld was invoked with the
743 -o/--vfo option and “0\n” if not.
744 When in VFO mode the client will need to pass 'VFO' as the first
746 parameter to set or get commands. VFO is one of the strings de‐
747 fined in set_vfo above.
748 set_vfo_opt 'Status'
750 Set 'Status'
751 Set vfo option Status 1=on or 0=off This is the same as using
753 the -o switch for rigctl and ritctld. This can be dyamically
754 changed while running.
755 set_lock_mode 'Locked'
757 Turns mode lock on(1) or off(0) (only when using rigctld).
758 Turning on will prevent all clients from changing the rig mode.
759 For example this is useful when running CW Skimmer in FM mode on
760 an IC-7300. Clicking spots in a spotting program will not
761 change the VFOA mode when lock is on. So "set_lock_mode 1" when
762 CW Skimmer is started and "set_lock_mode 0" when CW Skimmer is
763 stopped.
764 get_lock_mode
766 Returns current lock mode status 1=On, 2=Off (only useful with
767 rigctld)
768
770 There are two protocols in use by rigctld, the Default Protocol and the
771 Extended Response Protocol.
772 The Default Protocol is intended primarily for the communication be‐
774 tween Hamlib library functions and rigctld (“NET rigctl”, available us‐
775 ing radio model ‘2’).
776 The Extended Response Protocol is intended to be used with scripts or
778 other programs interacting directly with rigctld as consistent feedback
779 is provided.
780 Default Protocol
782 The Default Protocol is intentionally simple. Commands are entered on
783 a single line with any needed values. In practice, reliable results
784 are obtained by terminating each command string with a newline charac‐
785 ter, ‘\n’.
786 Example set frequency and mode commands (Perl code (typed text shown in
788 bold)):
789 print $socket "F 14250000\n";
791 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
792 A one line response will be sent as a reply to set commands, “RPRT x\n”
794 where x is the Hamlib error code with ‘0’ indicating success of the
795 command.
796 Responses from rigctld get commands are text values and match the same
798 tokens used in the set commands. Each value is returned on its own
799 line. On error the string “RPRT x\n” is returned where x is the Hamlib
800 error code.
801 Example get frequency (Perl code):
803 print $socket "f\n";
805 "14250000\n"
806 Most get functions return one to three values. A notable exception is
808 the dump_caps command which returns many lines of key:value pairs.
809 This protocol is primarily used by the “NET rigctl” (rigctl model 2)
811 backend which allows applications already written for Hamlib's C API to
812 take advantage of rigctld without the need of rewriting application
813 code. An application's user can select rotator model 2 (“NET rigctl”)
814 and then set rig_pathname to “localhost:4532” or other network
815 host:port (set by the -T/-t options, respectively, above).
816 Extended Response Protocol
818 The Extended Response protocol adds several rules to the strings re‐
819 turned by rigctld and adds a rule for the command syntax.
820 1. The command received by rigctld is echoed with its long command name
822 followed by the value(s) (if any) received from the client terminated
823 by the specified response separator as the first record of the re‐
824 sponse.
825 2. The last record of each block is the string “RPRT x\n” where x is
827 the numeric return value of the Hamlib backend function that was called
828 by the command.
829 3. Any records consisting of data values returned by the radio backend
831 are prepended by a string immediately followed by a colon then a space
832 and then the value terminated by the response separator. e.g. “Fre‐
833 quency: 14250000\n” when the command was prepended by ‘+’.
834 4. All commands received will be acknowledged by rigctld
836 with records from rules 1 and 2. Records from rule 3 are only re‐
837 turned when data values must be returned to the client.
838 An example response to a set_mode command sent from the shell prompt
840 (note the prepended ‘+’):
841 $ echo "+M USB 2400" | nc -w 1 localhost 4532
843 set_mode: USB 2400
844 RPRT 0
845 In this case the long command name and values are returned on the first
847 line and the second line contains the end of block marker and the nu‐
848 meric radio backend return value indicating success.
849 An example response to a get_mode query:
851 $ echo "+\get_mode" | nc -w 1 localhost 4532
853 get_mode:
854 Mode: USB
855 Passband: 2400
856 RPRT 0
857 Note: The ‘\’ is still required for the long command name even
859 with the ERP character.
860 In this case, as no value is passed to rigctld, the first line consists
862 only of the long command name. The final line shows that the command
863 was processed successfully by the radio backend.
864 Invoking the Extended Response Protocol requires prepending a command
866 with a punctuation character. As shown in the examples above, prepend‐
867 ing a ‘+’ character to the command results in the responses being sepa‐
868 rated by a newline character (‘\n’). Any other punctuation character
869 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
870 cause that character to become the response separator and the entire
871 response will be on one line.
872 Separator character summary:
874 ‘+’ Each record of the response is appended with a newline (‘\n’).
876 ‘;’, ‘|’, or, ‘,’
878 Each record of the response is appended by the given character
879 resulting in entire response on one line.
880 These are common record separators for text representations of
882 spreadsheet data, etc.
883 ‘?’ Reserved for help in rigctl.
885 ‘_’ Reserved for get_info short command
887 ‘#’ Reserved for comments when reading a command file script.
889 Note: Other punctuation characters have not been tested! Use at
891 your own risk.
892 For example, invoking a get_mode query with a leading ‘;’ returns:
894 get_mode:;Mode: USB;Passband: 2400;RPRT 0
896 Or, using the pipe character ‘|’ returns:
898 get_mode:|Mode: USB|Passband: 2400|RPRT 0
900 And a set_mode command prepended with a ‘|’ returns:
902 set_mode: USB 2400|RPRT 0
904 Such a format will allow reading a response as a single event using a
906 preferred response separator. Other punctuation characters have not
907 been tested!
908 The following commands have been tested with the Extended Response pro‐
910 tocol and the included testctld.pl Perl script:
911 set_freq, get_freq, set_split_freq, get_split_freq, set_mode,
913 get_mode, set_split_mode, get_split_mode, set_vfo, get_vfo,
914 set_split_vfo, get_split_vfo, set_rit, get_rit, set_xit,
915 get_xit, set_ptt, get_ptt, power2mW, mW2power, dump_caps.
916
918 The -v, --verbose option allows different levels of diagnostics to be
919 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
920 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
921 A given verbose level is useful for providing needed debugging informa‐
923 tion to the email address below. For example, TRACE output shows all
924 of the values sent to and received from the radio which is very useful
925 for radio backend library development and may be requested by the de‐
926 velopers.
927
929 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
930 backgrounding:
931 $ rigctld -m 1014 -r /dev/ttyUSB1 &
933 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter while
935 setting baud rate and stop bits, and backgrounding:
936 $ rigctld -m 1014 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
938 Start rigctld for an Elecraft K3 using COM2 on MS Windows:
940 $ rigctld -m 2029 -r COM2
942 Connect to the already running rigctld and set the frequency to 14.266
944 MHz with a 1 second read timeout using the default protocol from the
945 shell prompt:
946 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532P
948 Connect to a running rigctld with rigctl on the local host:
950 $ rigctl -m2
952
954 No authentication whatsoever; DO NOT leave this TCP port open wide to
955 the Internet. Please ask if stronger security is needed or consider
956 using a Secure Shell (ssh(1)) tunnel.
957 As rigctld does not need any greater permissions than rigctl, it is ad‐
959 visable to not start rigctld as “root” or another system user account
960 in order to limit any vulnerability.
961
963 The daemon is not detaching and backgrounding itself.
964 No method to exit the daemon so the kill(1) command must be used to
966 terminate it.
967 Multiple clients using the daemon may experience contention with the
969 connected radio.
970 Report bugs to:
972 Hamlib Developer mailing list
974 ⟨hamlib-developer@lists.sourceforge.net⟩
975
977 This file is part of Hamlib, a project to develop a library that sim‐
978 plifies radio, rotator, and amplifier control functions for developers
979 of software primarily of interest to radio amateurs and those inter‐
980 ested in radio communications.
981 Copyright © 2000-2010 Stephane Fillod
983 Copyright © 2000-2018 the Hamlib Group (various contributors)
984 Copyright © 2011-2020 Nate Bargmann
985 This is free software; see the file COPYING for copying conditions.
987 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
988 PARTICULAR PURPOSE.
989
991 kill(1), rigctl(1), ssh(1), hamlib(7)
992
994 Links to the Hamlib Wiki, Git repository, release archives, and daily
995 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
996Hamlib 2020-09-09 RIGCTLD(1)