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 The special string “uh-rig” may be given to enable micro-ham de‐
77 vice support.
78 -p, --ptt-file=device
80 Use device as the file name of the Push-To-Talk device using a
81 device file as described above.
82 -d, --dcd-file=device
84 Use device as the file name of the Data Carrier Detect device
85 using a device file as described above.
86 -P, --ptt-type=type
88 Use type of Push-To-Talk device.
89 Supported types are ‘RIG’ (CAT command), ‘DTR’, ‘RTS’, ‘PARAL‐
91 LEL’, ‘NONE’, overriding PTT type defined in the rig's backend.
92 Some side effects of this command are that when type is set to
94 DTR, read PTT state comes from the Hamlib frontend, not read
95 from the radio. When set to NONE, PTT state cannot be read or
96 set even if rig backend supports reading/setting PTT status from
97 the rig.
98 -D, --dcd-type=type
100 Use type of Data Carrier Detect device.
101 Supported types are ‘RIG’ (CAT command), ‘DSR’, ‘CTS’, ‘CD’,
103 ‘PARALLEL’, ‘NONE’.
104 -s, --serial-speed=baud
106 Set serial speed to baud rate.
107 Uses maximum serial speed from radio backend capabilities (set
109 by -m above) as the default.
110 -c, --civaddr=id
112 Use id as the CI-V address to communicate with the rig.
113 Only useful for Icom and some Ten-Tec rigs.
115 Note: The id is in decimal notation, unless prefixed by 0x, in
117 which case it is hexadecimal.
118 -T, --listen-addr=IPADDR
120 Use IPADDR as the listening IP address.
121 The default is ANY (0.0.0.0).
123 rigctld can be run and connected to like this:
125 rigctld
127 rigctl -m 2
128 rigctl -m 2 -r 127.0.0.1
129 rigctl -m 2 -r localhost
130 rigctl -m 2 -r 192.168.1.1 (local IP address)
131 rigctl -m 2 -r ::1 (on Linux rigctld doesn't listen on IPV6 by default)
132 rigctld -T 127.0.0.1
134 rigctl -m 2
135 rigctl -m 2 -r 127.0.0.1
136 Exceptions:
137 rigctl -m 2 -r localhost (only works if localhost is IPV4 address)
138 rigctld -T localhost (will set up on IPV4 or IPV6 based on localhost)
140 rigctl -m 2
141 rigctl -m 2 -r localhost
142 rigctl -m 2 ip6-localhost
143 Exceptions:
144 rigctl -m 2 -r 127.0.0.1 (only works if localhost is IPV4 address)
145 rigctl -m 2 -r ::1 (only works localhost is IPV6 address)
146 On Linux only where ip6-localhost is fe00::0:
148 rigctld -T ip6-localhost
149 rigctl -m 2 -r ip6-localhost
150 -t, --port=number
152 Use number as the TCP listening port.
153 The default is 4532.
155 Note: As rotctld's default port is 4533, it is advisable to use
157 even numbered ports for rigctld, e.g. 4532, 4534, 4536, etc.
158 -L, --show-conf
160 List all config parameters for the radio defined with -m above.
161 -C, --set-conf=parm=val[,parm=val]
163 Set radio configuration parameter(s), e.g. stop_bits=2.
164 Use the -L option above for a list of configuration parameters
166 for a given model number.
167 -u, --dump-caps
169 Dump capabilities for the radio defined with -m above and exit.
170 -l, --list
172 List all model numbers defined in Hamlib and exit.
173 The list is sorted by model number.
175 Note: In Linux the list can be scrolled back using Shift-
177 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
178 minal in X or the cmd window in Windows. The output can be
179 piped to more(1) or less(1), e.g. “rigctl -l | more”.
180 -o, --vfo
182 Enable vfo mode.
183 An extra VFO argument will be required in front of each appro‐
185 priate command (except set_vfo). Otherwise, ‘currVFO’ is used
186 when this option is not set and an extra VFO argument is not
187 used.
188 See chk_vfo below.
190 -v, --verbose
192 Set verbose mode, cumulative (see DIAGNOSTICS below).
193 -W, --twiddle_timeout=seconds
195 Enables timeout when VFO twiddling is detected. Some functions
196 will be ignored.
197 Should only be needed when controlling software should be
199 "paused" so you can move the VFO. Continuous movement extends
200 the timeout.
201 -x, --uplink=option
203 1=Sub, 2=Main
204 For GPredict use to ignore get_freq for Sub or Main uplink VFO.
206 Should allow downlink VFO movement without confusing GPredict or
208 the uplink
209 -Z, --debug-time-stamps
211 Enable time stamps for the debug messages.
212 Use only in combination with the -v option as it generates no
214 output on its own.
215 -h, --help
217 Show a summary of these options and exit.
218 -V, --version
220 Show version of rigctl and exit.
221 Note: Some options may not be implemented by a given backend and will
223 return an error. This is most likely to occur with the --set-conf and
224 --show-conf options.
225 Please note that the backend for the radio to be controlled, or the ra‐
227 dio itself may not support some commands. In that case, the operation
228 will fail with a Hamlib error code.
229
231 Commands can be sent over the TCP socket either as a single char, or as
232 a long command name plus the value(s) space separated on one ‘\n’ ter‐
233 minated line. See PROTOCOL.
234 Since most of the Hamlib operations have a set and a get method, an up‐
236 per case letter will be used for set methods whereas the corresponding
237 lower case letter refers to the get method. Each operation also has a
238 long name; prepend a backslash, ‘\’, to send a long command name.
239 Example (Perl): “print $socket "\\dump_caps\n";” to see what the ra‐
241 dio's backend can do (Note: In Perl and many other languages a ‘\’ will
242 need to be escaped with a preceding ‘\’ so that even though two back‐
243 slash characters appear in the code, only one will be passed to
244 rigctld. This is a possible bug, beware!).
245 Note: The backend for the radio to be controlled, or the radio itself
247 may not support some commands. In that case, the operation will fail
248 with a Hamlib error message.
249 Here is a summary of the supported commands (In the case of set com‐
251 mands the quoted italicized string is replaced by the value in the de‐
252 scription. In the case of get commands the quoted italicized string is
253 the key name of the value returned.):
254 F, set_freq 'Frequency'
256 Set 'Frequency', in Hz.
257 Frequency may be a floating point or integer value.
259 f, get_freq
261 Get 'Frequency', in Hz.
262 Returns an integer value and the VFO hamlib thinks is active.
264 Note that some rigs (e.g. all Icoms) cannot track current VFO so
265 hamlib can get out of sync with the rig if the user presses rig
266 buttons like the VFO. rigctld clients should ensure they set
267 the intended VFO or use vfo mode.
268 M, set_mode 'Mode' 'Passband'
270 Set 'Mode' and 'Passband'.
271 Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
273 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’, ‘EC‐
274 SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
275 Passband is in Hz as an integer, or ‘0’ for the radio backend
277 default.
278 Note: Passing a ‘?’ (query) as the first argument instead of a
280 Mode token will return a space separated list of radio backend
281 supported Modes. Use this to determine the supported Modes of a
282 given radio backend.
283 m, get_mode
285 Get 'Mode' and 'Passband'.
286 Returns Mode as a token and Passband in Hz as in set_mode above.
288 V, set_vfo 'VFO'
290 Set 'VFO'.
291 VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
293 ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
294 In VFO mode (see --vfo option above) only a single VFO parameter
296 is required:
297 $ rigctl -m 229 -r /dev/rig -o
299 Rig command: V
301 VFO: VFOB
302 Rig command:
304 v, get_vfo
306 Get current 'VFO'.
307 Returns VFO as a token as in set_vfo above.
309 J, set_rit 'RIT'
311 Set 'RIT'.
312 RIT is in Hz and can be + or -. A value of ‘0’ resets RIT (Re‐
314 ceiver Incremental Tuning) to match the VFO frequency.
315 Note: RIT needs to be explicitly activated or deactivated with
317 the set_func command. This allows setting the RIT offset inde‐
318 pendently of its activation and allows RIT to remain active
319 while setting the offset to ‘0’.
320 j, get_rit
322 Get 'RIT' in Hz.
323 Returned value is an integer.
325 Z, set_xit 'XIT'
327 Set 'XIT'.
328 XIT is in Hz and can be + or -. A value of ‘0’ resets XIT
330 (Transmitter Incremental Tuning) to match the VFO frequency.
331 Note: XIT needs to be explicitly activated or deactivated with
333 the set_func command. This allows setting the XIT offset inde‐
334 pendently of its activation and allows XIT to remain active
335 while setting the offset to ‘0’.
336 z, get_xit
338 Get 'XIT' in Hz.
339 Returned value is an integer.
341 T, set_ptt 'PTT'
343 Set 'PTT'.
344 PTT is a value: ‘0’ (RX), ‘1’ (TX), ‘2’ (TX mic), or ‘3’ (TX
346 data).
347 t, get_ptt
349 Get 'PTT' status.
350 Returns PTT as a value in set_ptt above.
352 S, set_split_vfo 'Split' 'TX VFO'
354 Set 'Split' mode.
355 Split is either ‘0’ = Normal or ‘1’ = Split.
357 Set 'TX VFO'.
359 TX VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’,
361 ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
362 s, get_split_vfo
364 Get 'Split' mode.
365 Split is either ‘0’ = Normal or ‘1’ = Split.
367 Get 'TX VFO'.
369 TX VFO is a token as in set_split_vfo above.
371 I, set_split_freq 'Tx Frequency'
373 Set 'TX Frequency', in Hz.
374 Frequency may be a floating point or integer value.
376 i, get_split_freq
378 Get 'TX Frequency', in Hz.
379 Returns an integer value.
381 X, set_split_mode 'TX Mode' 'TX Passband'
383 Set 'TX Mode' and 'TX Passband'.
384 TX Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
386 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’, ‘EC‐
387 SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
388 TX Passband is in Hz as an integer, or ‘0’ for the radio backend
390 default.
391 Note: Passing a ‘?’ (query) as the first argument instead of a
393 TX Mode token will return a space separated list of radio back‐
394 end supported TX Modes. Use this to determine the supported TX
395 Modes of a given radio backend.
396 x, get_split_mode
398 Get 'TX Mode' and 'TX Passband'.
399 Returns TX Mode as a token and TX Passband in Hz as in
401 set_split_mode above.
402 Y, set_ant 'Antenna'
404 Set 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
405 Option depends on rig..for Icom it probably sets the Tx & Rx an‐
407 tennas as in the IC-7851. See your manual for rig specific op‐
408 tion values. Most rigs don't care about the option.
409 For the IC-7851 (and perhaps others) it means this:
411 1 = TX/RX = ANT1
413 2 = TX/RX = ANT2
414 3 = TX/RX = ANT3
415 4 = TX/RX = ANT1/ANT4
416 5 = TX/RX = ANT2/ANT4
417 6 = TX/RX = ANT3/ANT4
418 y, get_ant
420 Get 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
421 b, send_morse 'Morse'
423 Send 'Morse' symbols.
424 0x8b, get_dcd
426 Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
427 R, set_rptr_shift 'Rptr Shift'
429 Set 'Rptr Shift'.
430 Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
432 r, get_rptr_shift
434 Get 'Rptr Shift'.
435 Returns ‘+’, ‘-’, or ‘None’.
437 O, set_rptr_offs 'Rptr Offset'
439 Set 'Rptr Offset', in Hz.
440 o, get_rptr_offs
442 Get 'Rptr Offset', in Hz.
443 C, set_ctcss_tone 'CTCSS Tone'
445 Set 'CTCSS Tone', in tenths of Hz.
446 c, get_ctcss_tone
448 Get 'CTCSS Tone', in tenths of Hz.
449 D, set_dcs_code 'DCS Code'
451 Set 'DCS Code'.
452 d, get_dcs_code
454 Get 'DCS Code'.
455 0x90, set_ctcss_sql 'CTCSS Sql'
457 Set 'CTCSS Sql' tone, in tenths of Hz.
458 0x91, get_ctcss_sql
460 Get 'CTCSS Sql' tone, in tenths of Hz.
461 0x92, set_dcs_sql 'DCS Sql'
463 Set 'DCS Sql' code.
464 0x93, get_dcs_sql
466 Get 'DCS Sql'
467 code.
468 N, set_ts 'Tuning Step'
470 Set 'Tuning Step', in Hz.
471 n, get_ts
473 Get 'Tuning Step', in Hz.
474 U, set_func 'Func' 'Func Status'
476 Set 'Func' and 'Func Status'.
477 Func is a token: ‘FAGC’, ‘NB’, ‘COMP’, ‘VOX’, ‘TONE’, ‘TSQL’,
479 ‘SBKIN’, ‘FBKIN’, ‘ANF’, ‘NR’, ‘AIP’, ‘APF’, ‘MON’, ‘MN’, ‘RF’,
480 ‘ARO’, ‘LOCK’, ‘MUTE’, ‘VSC’, ‘REV’, ‘SQL’, ‘ABM’, ‘BC’, ‘MBC’,
481 ‘RIT’, ‘AFC’, ‘SATMODE’, ‘SCOPE’, ‘RESUME’, ‘TBURST’, ‘TUNER’,
482 ‘XIT’.
483 Func Status is a non null value for “activate” or “de-activate”
485 otherwise, much as TRUE/FALSE definitions in the C language
486 (true is non-zero and false is zero, ‘0’).
487 Note: Passing a ‘?’ (query) as the first argument instead of a
489 Func token will return a space separated list of radio backend
490 supported set function tokens. Use this to determine the sup‐
491 ported functions of a given radio backend.
492 u, get_func 'Func'
494 Get 'Func Status'.
495 Returns Func Status as a non null value for the Func token given
497 as in set_func above.
498 Note: Passing a ‘?’ (query) as the first argument instead of a
500 Func token will return a space separated list of radio backend
501 supported get function tokens. Use this to determine the sup‐
502 ported functions of a given radio backend.
503 L, set_level 'Level' 'Level Value'
505 Set 'Level' and 'Level Value'.
506 Level is a token: ‘PREAMP’, ‘ATT’, ‘VOX’, ‘AF’, ‘RF’, ‘SQL’,
508 ‘IF’, ‘APF’, ‘NR’, ‘PBT_IN’, ‘PBT_OUT’, ‘CWPITCH’, ‘RFPOWER’,
509 ‘RFPOWER_METER’, ‘RFPOWER_METER_WATTS’, ‘MICGAIN’, ‘KEYSPD’,
510 ‘NOTCHF’, ‘COMP’, ‘AGC’, ‘BKINDL’, ‘BAL’, ‘METER’, ‘VOXGAIN’,
511 ‘ANTIVOX’, ‘SLOPE_LOW’, ‘SLOPE_HIGH’, ‘RAWSTR’, ‘SWR’, ‘ALC’,
512 ‘STRENGTH’.
513 The Level Value can be a float or an integer value. For the AGC
515 token the value is one of ‘0’ = OFF, ‘1’ = SUPERFAST, ‘2’ =
516 FAST, ‘3’ = SLOW, ‘4’ = USER, ‘5’ = MEDIUM, ‘6’ = AUTO.
517 Note: Passing a ‘?’ (query) as the first argument instead of a
519 Level token will return a space separated list of radio backend
520 supported set level tokens. Use this to determine the supported
521 levels of a given radio backend.
522 l, get_level 'Level'
524 Get 'Level Value'.
525 Returns Level Value as a float or integer for the Level token
527 given as in set_level above.
528 Note: Passing a ‘?’ (query) as the first argument instead of a
530 Level token will return a space separated list of radio backend
531 supported get level tokens. Use this to determine the supported
532 levels of a given radio backend.
533 P, set_parm 'Parm' 'Parm Value'
535 Set 'Parm' and 'Parm Value'.
536 Parm is a token: ‘ANN’, ‘APO’, ‘BACKLIGHT’, ‘BEEP’, ‘TIME’,
538 ‘BAT’, ‘KEYLIGHT’.
539 Note: Passing a ‘?’ (query) as the first argument instead of a
541 Parm token will return a space separated list of radio backend
542 supported set parameter tokens. Use this to determine the sup‐
543 ported parameters of a given radio backend.
544 p, get_parm 'Parm'
546 Get 'Parm Value'.
547 Returns Parm Value as a float or integer for the Parm token
549 given as in set_parm above.
550 Note: Passing a ‘?’ (query) as the first argument instead of a
552 Parm token will return a space separated list of radio backend
553 supported get parameter tokens. Use this to determine the sup‐
554 ported parameters of a given radio backend.
555 B, set_bank 'Bank'
557 Set 'Bank'.
558 Sets the current memory bank number.
560 E, set_mem 'Memory#'
562 Set 'Memory#' channel number.
563 e, get_mem
565 Get 'Memory#' channel number.
566 G, vfo_op 'Mem/VFO Op'
568 Perform a 'Mem/VFO Op'.
569 Mem/VFO Operation is a token: ‘CPY’, ‘XCHG’, ‘FROM_VFO’,
571 ‘TO_VFO’, ‘MCL’, ‘UP’, ‘DOWN’, ‘BAND_UP’, ‘BAND_DOWN’, ‘LEFT’,
572 ‘RIGHT’, ‘TUNE’, ‘TOGGLE’.
573 Note: Passing a ‘?’ (query) as the first argument instead of a
575 Mem/VFO Op token will return a space separated list of radio
576 backend supported Set Mem/VFO Op tokens. Use this to determine
577 the supported Mem/VFO Ops of a given radio backend.
578 g, scan 'Scan Fct' 'Scan Channel'
580 Perform a 'Scan Fct' on a 'Scan Channel'.
581 Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
583 ‘DELTA’, ‘VFO’, ‘PLT’.
584 Scan Channel is an integer (maybe?).
586 Note: Passing a ‘?’ (query) as the first argument instead of a
588 Scan Fct token will return a space separated list of radio back‐
589 end supported Scan Function tokens. Use this to determine the
590 supported Scan Functions of a given radio backend.
591 H, set_channel 'Channel'
593 Set memory 'Channel' data.
594 Not implemented yet.
596 h, get_channel 'readonly'
598 Get channel memory.
599 If readonly!=0 then only channel data is returned and rig re‐
601 mains on the current channel. If readonly=0 then rig will be
602 set to the channel requested. data.
603 A, set_trn 'Transceive'
605 Set 'Transceive' mode.
606 Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
608 Transceive is a mechanism for radios to report events without a
610 specific call for information.
611 Note: Passing a ‘?’ (query) as the first argument instead of a
613 Transceive token will return a space separated list of radio
614 backend supported Transceive mode tokens. Use this to determine
615 the supported Transceive modes of a given radio backend.
616 a, get_trn
618 Get 'Transceive' mode.
619 Transceive mode (reporting event) as in set_trn above.
621 *, reset 'Reset'
623 Perform rig 'Reset'.
624 Reset is a value: ‘0’ = None, ‘1’ = Software reset, ‘2’ = VFO
626 reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
627 Since these values are defined as a bitmask in include/ham‐
629 lib/rig.h, it should be possible to AND these values together to
630 do multiple resets at once, if the backend supports it or sup‐
631 ports a reset action via rig control at all.
632 0x87, set_powerstat 'Power Status'
634 Set 'Power Status'.
635 Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’ =
637 Power Standby.
638 0x88, get_powerstat
640 Get 'Power Status' as in set_powerstat above.
641 0x89, send_dtmf 'Digits'
643 Set DTMF 'Digits'.
644 0x8a, recv_dtmf
646 Get DTMF 'Digits'.
647 _, get_info
649 Get misc information about the rig.
650 0xf5, get_rig_info
652 Get misc information about the rig vfos and other info.
653 0xf3, get_vfo_info 'VFO'
655 Get misc information about a specific vfo.
656 dump_state
658 Return certain state information about the radio backend.
659 1, dump_caps
661 Not a real rig remote command, it just dumps capabilities, i.e.
662 what the backend knows about this model, and what it can do.
663 TODO: Ensure this is in a consistent format so it can be read
665 into a hash, dictionary, etc. Bug reports requested.
666 Note: This command will produce many lines of output so be very
668 careful if using a fixed length array! For example, running
669 this command against the Dummy backend results in over 5kB of
670 text output.
671 VFO parameter not used in 'VFO mode'.
673 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
675 Returns 'Power mW'.
676 Converts a Power value in a range of 0.0...1.0 to the real
678 transmit power in milli-Watts (integer).
679 'Frequency' and 'Mode' also need to be provided as output power
681 may vary according to these values.
682 VFO parameter is not used in VFO mode.
684 4, mW2power 'Power mW' 'Frequency' 'Mode'
686 Returns 'Power [0.0..1.0]'.
687 Converts the real transmit power in milli-Watts (integer) to a
689 Power value in a range of 0.0 ... 1.0.
690 'Frequency' and 'Mode' also need to be provided as output power
692 may vary according to these values.
693 VFO parameter is not used in VFO mode.
695 set_clock 'DateTime'
697 Set 'DateTime'
698 Sets rig clock -- note that some rigs do not handle seconds or
700 milliseconds. If you try to set that you will get a debug warn‐
701 ing message. Format is ISO8601.
702 Formats accepted
703 YYYY-MM-DDTHH:MM:SS.sss+ZZ (where +ZZ is either -/+ UTC offset)
704 YYYY-MM-DDTHH:MM:SS+ZZ
705 YYYY-MM-DDTHH:MM+ZZ
706 YYYY-MM-DD (sets date only)
707 get_clock
709 Get 'RigTime'
710 Gets rig clock -- note that some rigs do not handle seconds or
712 milliseconds. Format is ISO8601 YYYY-MM-DDTHH:MM:SS.sss+ZZ
713 where +ZZ is either -/+ UTC offset
714 chk_vfo
716 Returns “1\n” (single line only) if rigctld was invoked with the
717 -o/--vfo option and “0\n” if not.
718 When in VFO mode the client will need to pass 'VFO' as the first
720 parameter to set or get commands. VFO is one of the strings de‐
721 fined in set_vfo above.
722 set_vfo_opt 'Status'
724 Set 'Status'
725 Set vfo option Status 1=on or 0=off This is the same as using
727 the -o switch for rigctl and ritctld. This can be dyamically
728 changed while running.
729
731 There are two protocols in use by rigctld, the Default Protocol and the
732 Extended Response Protocol.
733 The Default Protocol is intended primarily for the communication be‐
735 tween Hamlib library functions and rigctld (“NET rigctl”, available us‐
736 ing radio model ‘2’).
737 The Extended Response Protocol is intended to be used with scripts or
739 other programs interacting directly with rigctld as consistent feedback
740 is provided.
741 Default Protocol
743 The Default Protocol is intentionally simple. Commands are entered on
744 a single line with any needed values. In practice, reliable results
745 are obtained by terminating each command string with a newline charac‐
746 ter, ‘\n’.
747 Example set frequency and mode commands (Perl code (typed text shown in
749 bold)):
750 print $socket "F 14250000\n";
752 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
753 A one line response will be sent as a reply to set commands, “RPRT x\n”
755 where x is the Hamlib error code with ‘0’ indicating success of the
756 command.
757 Responses from rigctld get commands are text values and match the same
759 tokens used in the set commands. Each value is returned on its own
760 line. On error the string “RPRT x\n” is returned where x is the Hamlib
761 error code.
762 Example get frequency (Perl code):
764 print $socket "f\n";
766 "14250000\n"
767 Most get functions return one to three values. A notable exception is
769 the dump_caps command which returns many lines of key:value pairs.
770 This protocol is primarily used by the “NET rigctl” (rigctl model 2)
772 backend which allows applications already written for Hamlib's C API to
773 take advantage of rigctld without the need of rewriting application
774 code. An application's user can select rotator model 2 (“NET rigctl”)
775 and then set rig_pathname to “localhost:4532” or other network
776 host:port (set by the -T/-t options, respectively, above).
777 Extended Response Protocol
779 The Extended Response protocol adds several rules to the strings re‐
780 turned by rigctld and adds a rule for the command syntax.
781 1. The command received by rigctld is echoed with its long command name
783 followed by the value(s) (if any) received from the client terminated
784 by the specified response separator as the first record of the re‐
785 sponse.
786 2. The last record of each block is the string “RPRT x\n” where x is
788 the numeric return value of the Hamlib backend function that was called
789 by the command.
790 3. Any records consisting of data values returned by the radio backend
792 are prepended by a string immediately followed by a colon then a space
793 and then the value terminated by the response separator. e.g. “Fre‐
794 quency: 14250000\n” when the command was prepended by ‘+’.
795 4. All commands received will be acknowledged by rigctld
797 with records from rules 1 and 2. Records from rule 3 are only re‐
798 turned when data values must be returned to the client.
799 An example response to a set_mode command sent from the shell prompt
801 (note the prepended ‘+’):
802 $ echo "+M USB 2400" | nc -w 1 localhost 4532
804 set_mode: USB 2400
805 RPRT 0
806 In this case the long command name and values are returned on the first
808 line and the second line contains the end of block marker and the nu‐
809 meric radio backend return value indicating success.
810 An example response to a get_mode query:
812 $ echo "+\get_mode" | nc -w 1 localhost 4532
814 get_mode:
815 Mode: USB
816 Passband: 2400
817 RPRT 0
818 Note: The ‘\’ is still required for the long command name even
820 with the ERP character.
821 In this case, as no value is passed to rigctld, the first line consists
823 only of the long command name. The final line shows that the command
824 was processed successfully by the radio backend.
825 Invoking the Extended Response Protocol requires prepending a command
827 with a punctuation character. As shown in the examples above, prepend‐
828 ing a ‘+’ character to the command results in the responses being sepa‐
829 rated by a newline character (‘\n’). Any other punctuation character
830 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
831 cause that character to become the response separator and the entire
832 response will be on one line.
833 Separator character summary:
835 ‘+’ Each record of the response is appended with a newline (‘\n’).
837 ‘;’, ‘|’, or, ‘,’
839 Each record of the response is appended by the given character
840 resulting in entire response on one line.
841 These are common record separators for text representations of
843 spreadsheet data, etc.
844 ‘?’ Reserved for help in rigctl.
846 ‘_’ Reserved for get_info short command
848 ‘#’ Reserved for comments when reading a command file script.
850 Note: Other punctuation characters have not been tested! Use at
852 your own risk.
853 For example, invoking a get_mode query with a leading ‘;’ returns:
855 get_mode:;Mode: USB;Passband: 2400;RPRT 0
857 Or, using the pipe character ‘|’ returns:
859 get_mode:|Mode: USB|Passband: 2400|RPRT 0
861 And a set_mode command prepended with a ‘|’ returns:
863 set_mode: USB 2400|RPRT 0
865 Such a format will allow reading a response as a single event using a
867 preferred response separator. Other punctuation characters have not
868 been tested!
869 The following commands have been tested with the Extended Response pro‐
871 tocol and the included testctld.pl Perl script:
872 set_freq, get_freq, set_split_freq, get_split_freq, set_mode,
874 get_mode, set_split_mode, get_split_mode, set_vfo, get_vfo,
875 set_split_vfo, get_split_vfo, set_rit, get_rit, set_xit,
876 get_xit, set_ptt, get_ptt, power2mW, mW2power, dump_caps.
877
879 The -v, --verbose option allows different levels of diagnostics to be
880 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
881 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
882 A given verbose level is useful for providing needed debugging informa‐
884 tion to the email address below. For example, TRACE output shows all
885 of the values sent to and received from the radio which is very useful
886 for radio backend library development and may be requested by the de‐
887 velopers.
888
890 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
891 backgrounding:
892 $ rigctld -m 1014 -r /dev/ttyUSB1 &
894 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter while
896 setting baud rate and stop bits, and backgrounding:
897 $ rigctld -m 1014 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
899 Start rigctld for an Elecraft K3 using COM2 on MS Windows:
901 $ rigctld -m 2029 -r COM2
903 Connect to the already running rigctld and set the frequency to 14.266
905 MHz with a 1 second read timeout using the default protocol from the
906 shell prompt:
907 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532P
909 Connect to a running rigctld with rigctl on the local host:
911 $ rigctl -m2
913
915 No authentication whatsoever; DO NOT leave this TCP port open wide to
916 the Internet. Please ask if stronger security is needed or consider
917 using a Secure Shell (ssh(1)) tunnel.
918 As rigctld does not need any greater permissions than rigctl, it is ad‐
920 visable to not start rigctld as “root” or another system user account
921 in order to limit any vulnerability.
922
924 The daemon is not detaching and backgrounding itself.
925 No method to exit the daemon so the kill(1) command must be used to
927 terminate it.
928 Multiple clients using the daemon may experience contention with the
930 connected radio.
931 Report bugs to:
933 Hamlib Developer mailing list
935 ⟨hamlib-developer@lists.sourceforge.net⟩
936
938 This file is part of Hamlib, a project to develop a library that sim‐
939 plifies radio, rotator, and amplifier control functions for developers
940 of software primarily of interest to radio amateurs and those inter‐
941 ested in radio communications.
942 Copyright © 2000-2010 Stephane Fillod
944 Copyright © 2000-2018 the Hamlib Group (various contributors)
945 Copyright © 2011-2020 Nate Bargmann
946 This is free software; see the file COPYING for copying conditions.
948 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
949 PARTICULAR PURPOSE.
950
952 kill(1), rigctl(1), ssh(1), hamlib(7)
953
955 Links to the Hamlib Wiki, Git repository, release archives, and daily
956 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
957Hamlib 2020-09-09 RIGCTLD(1)