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
15 requests 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
28 requested 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.
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
77 device 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
227 radio itself may not support some commands. In that case, the opera‐
228 tion 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
236 upper case letter will be used for set methods whereas the correspond‐
237 ing lower case letter refers to the get method. Each operation also
238 has a long name; prepend a backslash, ‘\’, to send a long command name.
239 Example (Perl): “print $socket "\\dump_caps\n";” to see what the
241 radio's backend can do (Note: In Perl and many other languages a ‘\’
242 will need to be escaped with a preceding ‘\’ so that even though two
243 backslash 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
252 description. In the case of get commands the quoted italicized string
253 is 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’,
274 ‘ECSSUSB’, ‘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
314 (Receiver 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’,
387 ‘ECSSUSB’, ‘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
407 antennas as in the IC-7851. See your manual for rig specific
408 option 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
601 remains 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 (no VFO in 'VFO mode' or
650 value is passed).
651 dump_state
653 Return certain state information about the radio backend.
654 1, dump_caps
656 Not a real rig remote command, it just dumps capabilities, i.e.
657 what the backend knows about this model, and what it can do.
658 TODO: Ensure this is in a consistent format so it can be read
660 into a hash, dictionary, etc. Bug reports requested.
661 Note: This command will produce many lines of output so be very
663 careful if using a fixed length array! For example, running
664 this command against the Dummy backend results in over 5kB of
665 text output.
666 VFO parameter not used in 'VFO mode'.
668 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
670 Returns 'Power mW'.
671 Converts a Power value in a range of 0.0...1.0 to the real
673 transmit power in milli-Watts (integer).
674 'Frequency' and 'Mode' also need to be provided as output power
676 may vary according to these values.
677 VFO parameter is not used in VFO mode.
679 4, mW2power 'Power mW' 'Frequency' 'Mode'
681 Returns 'Power [0.0..1.0]'.
682 Converts the real transmit power in milli-Watts (integer) to a
684 Power value in a range of 0.0 ... 1.0.
685 'Frequency' and 'Mode' also need to be provided as output power
687 may vary according to these values.
688 VFO parameter is not used in VFO mode.
690 chk_vfo
692 Returns “CHKVFO 1\n” (single line only) if rigctld was invoked
693 with the -o/--vfo option and “CHKVFO 0\n” if not.
694 When in VFO mode the client will need to pass 'VFO' as the first
696 parameter to set or get commands. VFO is one of the strings
697 defined in set_vfo above.
698 set_vfo_opt 'Status'
700 Set 'Status'
701 Set vfo option Status 1=on or 0=off This is the same as using
703 the -o switch for rigctl and ritctld. This can be dyamically
704 changed while running.
705
707 There are two protocols in use by rigctld, the Default Protocol and the
708 Extended Response Protocol.
709 The Default Protocol is intended primarily for the communication
711 between Hamlib library functions and rigctld (“NET rigctl”, available
712 using radio model ‘2’).
713 The Extended Response Protocol is intended to be used with scripts or
715 other programs interacting directly with rigctld as consistent feedback
716 is provided.
717 Default Protocol
719 The Default Protocol is intentionally simple. Commands are entered on
720 a single line with any needed values. In practice, reliable results
721 are obtained by terminating each command string with a newline charac‐
722 ter, ‘\n’.
723 Example set frequency and mode commands (Perl code (typed text shown in
725 bold)):
726 print $socket "F 14250000\n";
728 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
729 A one line response will be sent as a reply to set commands, “RPRT x\n”
731 where x is the Hamlib error code with ‘0’ indicating success of the
732 command.
733 Responses from rigctld get commands are text values and match the same
735 tokens used in the set commands. Each value is returned on its own
736 line. On error the string “RPRT x\n” is returned where x is the Hamlib
737 error code.
738 Example get frequency (Perl code):
740 print $socket "f\n";
742 "14250000\n"
743 Most get functions return one to three values. A notable exception is
745 the dump_caps command which returns many lines of key:value pairs.
746 This protocol is primarily used by the “NET rigctl” (rigctl model 2)
748 backend which allows applications already written for Hamlib's C API to
749 take advantage of rigctld without the need of rewriting application
750 code. An application's user can select rotator model 2 (“NET rigctl”)
751 and then set rig_pathname to “localhost:4532” or other network
752 host:port (set by the -T/-t options, respectively, above).
753 Extended Response Protocol
755 The Extended Response protocol adds several rules to the strings
756 returned by rigctld and adds a rule for the command syntax.
757 1. The command received by rigctld is echoed with its long command name
759 followed by the value(s) (if any) received from the client terminated
760 by the specified response separator as the first record of the
761 response.
762 2. The last record of each block is the string “RPRT x\n” where x is
764 the numeric return value of the Hamlib backend function that was called
765 by the command.
766 3. Any records consisting of data values returned by the radio backend
768 are prepended by a string immediately followed by a colon then a space
769 and then the value terminated by the response separator. e.g. “Fre‐
770 quency: 14250000\n” when the command was prepended by ‘+’.
771 4. All commands received will be acknowledged by rigctld
773 with records from rules 1 and 2. Records from rule 3 are only
774 returned when data values must be returned to the client.
775 An example response to a set_mode command sent from the shell prompt
777 (note the prepended ‘+’):
778 $ echo "+M USB 2400" | nc -w 1 localhost 4532
780 set_mode: USB 2400
781 RPRT 0
782 In this case the long command name and values are returned on the first
784 line and the second line contains the end of block marker and the
785 numeric radio backend return value indicating success.
786 An example response to a get_mode query:
788 $ echo "+\get_mode" | nc -w 1 localhost 4532
790 get_mode:
791 Mode: USB
792 Passband: 2400
793 RPRT 0
794 Note: The ‘\’ is still required for the long command name even
796 with the ERP character.
797 In this case, as no value is passed to rigctld, the first line consists
799 only of the long command name. The final line shows that the command
800 was processed successfully by the radio backend.
801 Invoking the Extended Response Protocol requires prepending a command
803 with a punctuation character. As shown in the examples above, prepend‐
804 ing a ‘+’ character to the command results in the responses being sepa‐
805 rated by a newline character (‘\n’). Any other punctuation character
806 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
807 cause that character to become the response separator and the entire
808 response will be on one line.
809 Separator character summary:
811 ‘+’ Each record of the response is appended with a newline (‘\n’).
813 ‘;’, ‘|’, or, ‘,’
815 Each record of the response is appended by the given character
816 resulting in entire response on one line.
817 These are common record separators for text representations of
819 spreadsheet data, etc.
820 ‘?’ Reserved for help in rigctl.
822 ‘_’ Reserved for get_info short command
824 ‘#’ Reserved for comments when reading a command file script.
826 Note: Other punctuation characters have not been tested! Use at
828 your own risk.
829 For example, invoking a get_mode query with a leading ‘;’ returns:
831 get_mode:;Mode: USB;Passband: 2400;RPRT 0
833 Or, using the pipe character ‘|’ returns:
835 get_mode:|Mode: USB|Passband: 2400|RPRT 0
837 And a set_mode command prepended with a ‘|’ returns:
839 set_mode: USB 2400|RPRT 0
841 Such a format will allow reading a response as a single event using a
843 preferred response separator. Other punctuation characters have not
844 been tested!
845 The following commands have been tested with the Extended Response pro‐
847 tocol and the included testctld.pl Perl script:
848 set_freq, get_freq, set_split_freq, get_split_freq, set_mode,
850 get_mode, set_split_mode, get_split_mode, set_vfo, get_vfo,
851 set_split_vfo, get_split_vfo, set_rit, get_rit, set_xit,
852 get_xit, set_ptt, get_ptt, power2mW, mW2power, dump_caps.
853
855 The -v, --verbose option allows different levels of diagnostics to be
856 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
857 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
858 A given verbose level is useful for providing needed debugging informa‐
860 tion to the email address below. For example, TRACE output shows all
861 of the values sent to and received from the radio which is very useful
862 for radio backend library development and may be requested by the
863 developers.
864
866 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
867 backgrounding:
868 $ rigctld -m 1014 -r /dev/ttyUSB1 &
870 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter while
872 setting baud rate and stop bits, and backgrounding:
873 $ rigctld -m 1014 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
875 Start rigctld for an Elecraft K3 using COM2 on MS Windows:
877 $ rigctld -m 2029 -r COM2
879 Connect to the already running rigctld and set the frequency to 14.266
881 MHz with a 1 second read timeout using the default protocol from the
882 shell prompt:
883 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532P
885 Connect to a running rigctld with rigctl on the local host:
887 $ rigctl -m2
889
891 No authentication whatsoever; DO NOT leave this TCP port open wide to
892 the Internet. Please ask if stronger security is needed or consider
893 using a Secure Shell (ssh(1)) tunnel.
894 As rigctld does not need any greater permissions than rigctl, it is
896 advisable to not start rigctld as “root” or another system user account
897 in order to limit any vulnerability.
898
900 The daemon is not detaching and backgrounding itself.
901 No method to exit the daemon so the kill(1) command must be used to
903 terminate it.
904 Multiple clients using the daemon may experience contention with the
906 connected radio.
907 Report bugs to:
909 Hamlib Developer mailing list
911 ⟨hamlib-developer@lists.sourceforge.net⟩
912
914 This file is part of Hamlib, a project to develop a library that sim‐
915 plifies radio, rotator, and amplifier control functions for developers
916 of software primarily of interest to radio amateurs and those inter‐
917 ested in radio communications.
918 Copyright © 2000-2010 Stephane Fillod
920 Copyright © 2000-2018 the Hamlib Group (various contributors)
921 Copyright © 2011-2020 Nate Bargmann
922 This is free software; see the file COPYING for copying conditions.
924 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
925 PARTICULAR PURPOSE.
926
928 kill(1), rigctl(1), ssh(1), hamlib(7)
929
931 Links to the Hamlib Wiki, Git repository, release archives, and daily
932 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
933Hamlib 2020-09-09 RIGCTLD(1)