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.
123 -t, --port=number
125 Use number as the TCP listening port.
126 The default is 4532.
128 Note: As rotctld's default port is 4533, it is advisable to use
130 even numbered ports for rigctld, e.g. 4532, 4534, 4536, etc.
131 -L, --show-conf
133 List all config parameters for the radio defined with -m above.
134 -C, --set-conf=parm=val[,parm=val]
136 Set radio configuration parameter(s), e.g. stop_bits=2.
137 Use the -L option above for a list of configuration parameters
139 for a given model number.
140 -u, --dump-caps
142 Dump capabilities for the radio defined with -m above and exit.
143 -l, --list
145 List all model numbers defined in Hamlib and exit.
146 The list is sorted by model number.
148 Note: In Linux the list can be scrolled back using Shift-
150 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
151 minal in X or the cmd window in Windows. The output can be
152 piped to more(1) or less(1), e.g. “rigctl -l | more”.
153 -o, --vfo
155 Enable vfo mode.
156 An extra VFO argument will be required in front of each appro‐
158 priate command (except set_vfo). Otherwise, ‘currVFO’ is used
159 when this option is not set and an extra VFO argument is not
160 used.
161 See chk_vfo below.
163 -v, --verbose
165 Set verbose mode, cumulative (see DIAGNOSTICS below).
166 -X, --twiddle=seconds
168 Enables timeout when VFO twiddling is detected. Some functons
169 will be ignored.
170 Should only be needed when controlling software should be
172 "paused" -v so you can move the VFO. Continuous movement
173 extends the timeout.
174 -Z, --debug-time-stamps
176 Enable time stamps for the debug messages.
177 Use only in combination with the -v option as it generates no
179 output on its own.
180 -h, --help
182 Show a summary of these options and exit.
183 -V, --version
185 Show version of rigctl and exit.
186 Note: Some options may not be implemented by a given backend and will
188 return an error. This is most likely to occur with the --set-conf and
189 --show-conf options.
190 Please note that the backend for the radio to be controlled, or the
192 radio itself may not support some commands. In that case, the opera‐
193 tion will fail with a Hamlib error code.
194
196 Commands can be sent over the TCP socket either as a single char, or as
197 a long command name plus the value(s) space separated on one ‘\n’ ter‐
198 minated line. See PROTOCOL.
199 Since most of the Hamlib operations have a set and a get method, an
201 upper case letter will be used for set methods whereas the correspond‐
202 ing lower case letter refers to the get method. Each operation also
203 has a long name; prepend a backslash, ‘\’, to send a long command name.
204 Example (Perl): “print $socket "\\dump_caps\n";” to see what the
206 radio's backend can do (Note: In Perl and many other languages a ‘\’
207 will need to be escaped with a preceding ‘\’ so that even though two
208 backslash characters appear in the code, only one will be passed to
209 rigctld. This is a possible bug, beware!).
210 Note: The backend for the radio to be controlled, or the radio itself
212 may not support some commands. In that case, the operation will fail
213 with a Hamlib error message.
214 Here is a summary of the supported commands (In the case of set com‐
216 mands the quoted italicized string is replaced by the value in the
217 description. In the case of get commands the quoted italicized string
218 is the key name of the value returned.):
219 F, set_freq 'Frequency'
221 Set 'Frequency', in Hz.
222 Frequency may be a floating point or integer value.
224 f, get_freq
226 Get 'Frequency', in Hz.
227 Returns an integer value and the VFO hamlib thinks is active.
229 Note that some rigs (e.g. all Icoms) cannot track current VFO so
230 hamlib can get out of sync with the rig if the user presses rig
231 buttons like the VFO. rigctld clients should ensure they set
232 the intended VFO or use vfo mode.
233 M, set_mode 'Mode' 'Passband'
235 Set 'Mode' and 'Passband'.
236 Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
238 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’,
239 ‘ECSSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
240 Passband is in Hz as an integer, or ‘0’ for the radio backend
242 default.
243 Note: Passing a ‘?’ (query) as the first argument instead of a
245 Mode token will return a space separated list of radio backend
246 supported Modes. Use this to determine the supported Modes of a
247 given radio backend.
248 m, get_mode
250 Get 'Mode' and 'Passband'.
251 Returns Mode as a token and Passband in Hz as in set_mode above.
253 V, set_vfo 'VFO'
255 Set 'VFO'.
256 VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
258 ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
259 In VFO mode (see --vfo option above) only a single VFO parameter
261 is required:
262 $ rigctl -m 229 -r /dev/rig -o
264 Rig command: V
266 VFO: VFOB
267 Rig command:
269 v, get_vfo
271 Get current 'VFO'.
272 Returns VFO as a token as in set_vfo above.
274 J, set_rit 'RIT'
276 Set 'RIT'.
277 RIT is in Hz and can be + or -. A value of ‘0’ resets RIT
279 (Receiver Incremental Tuning) to match the VFO frequency.
280 Note: RIT needs to be explicitly activated or deactivated with
282 the set_func command. This allows setting the RIT offset inde‐
283 pendently of its activation and allows RIT to remain active
284 while setting the offset to ‘0’.
285 j, get_rit
287 Get 'RIT' in Hz.
288 Returned value is an integer.
290 Z, set_xit 'XIT'
292 Set 'XIT'.
293 XIT is in Hz and can be + or -. A value of ‘0’ resets XIT
295 (Transmitter Incremental Tuning) to match the VFO frequency.
296 Note: XIT needs to be explicitly activated or deactivated with
298 the set_func command. This allows setting the XIT offset inde‐
299 pendently of its activation and allows XIT to remain active
300 while setting the offset to ‘0’.
301 z, get_xit
303 Get 'XIT' in Hz.
304 Returned value is an integer.
306 T, set_ptt 'PTT'
308 Set 'PTT'.
309 PTT is a value: ‘0’ (RX), ‘1’ (TX), ‘2’ (TX mic), or ‘3’ (TX
311 data).
312 t, get_ptt
314 Get 'PTT' status.
315 Returns PTT as a value in set_ptt above.
317 S, set_split_vfo 'Split' 'TX VFO'
319 Set 'Split' mode.
320 Split is either ‘0’ = Normal or ‘1’ = Split.
322 Set 'TX VFO'.
324 TX VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’,
326 ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
327 s, get_split_vfo
329 Get 'Split' mode.
330 Split is either ‘0’ = Normal or ‘1’ = Split.
332 Get 'TX VFO'.
334 TX VFO is a token as in set_split_vfo above.
336 I, set_split_freq 'Tx Frequency'
338 Set 'TX Frequency', in Hz.
339 Frequency may be a floating point or integer value.
341 i, get_split_freq
343 Get 'TX Frequency', in Hz.
344 Returns an integer value.
346 X, set_split_mode 'TX Mode' 'TX Passband'
348 Set 'TX Mode' and 'TX Passband'.
349 TX Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
351 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’,
352 ‘ECSSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
353 TX Passband is in Hz as an integer, or ‘0’ for the radio backend
355 default.
356 Note: Passing a ‘?’ (query) as the first argument instead of a
358 TX Mode token will return a space separated list of radio back‐
359 end supported TX Modes. Use this to determine the supported TX
360 Modes of a given radio backend.
361 x, get_split_mode
363 Get 'TX Mode' and 'TX Passband'.
364 Returns TX Mode as a token and TX Passband in Hz as in
366 set_split_mode above.
367 Y, set_ant 'Antenna'
369 Set 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
370 y, get_ant
372 Get 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
373 b, send_morse 'Morse'
375 Send 'Morse' symbols.
376 0x8b, get_dcd
378 Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
379 R, set_rptr_shift 'Rptr Shift'
381 Set 'Rptr Shift'.
382 Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
384 r, get_rptr_shift
386 Get 'Rptr Shift'.
387 Returns ‘+’, ‘-’, or ‘None’.
389 O, set_rptr_offs 'Rptr Offset'
391 Set 'Rptr Offset', in Hz.
392 o, get_rptr_offs
394 Get 'Rptr Offset', in Hz.
395 C, set_ctcss_tone 'CTCSS Tone'
397 Set 'CTCSS Tone', in tenths of Hz.
398 c, get_ctcss_tone
400 Get 'CTCSS Tone', in tenths of Hz.
401 D, set_dcs_code 'DCS Code'
403 Set 'DCS Code'.
404 d, get_dcs_code
406 Get 'DCS Code'.
407 0x90, set_ctcss_sql 'CTCSS Sql'
409 Set 'CTCSS Sql' tone, in tenths of Hz.
410 0x91, get_ctcss_sql
412 Get 'CTCSS Sql' tone, in tenths of Hz.
413 0x92, set_dcs_sql 'DCS Sql'
415 Set 'DCS Sql' code.
416 0x93, get_dcs_sql
418 Get 'DCS Sql'
419 code.
420 N, set_ts 'Tuning Step'
422 Set 'Tuning Step', in Hz.
423 n, get_ts
425 Get 'Tuning Step', in Hz.
426 U, set_func 'Func' 'Func Status'
428 Set 'Func' and 'Func Status'.
429 Func is a token: ‘FAGC’, ‘NB’, ‘COMP’, ‘VOX’, ‘TONE’, ‘TSQL’,
431 ‘SBKIN’, ‘FBKIN’, ‘ANF’, ‘NR’, ‘AIP’, ‘APF’, ‘MON’, ‘MN’, ‘RF’,
432 ‘ARO’, ‘LOCK’, ‘MUTE’, ‘VSC’, ‘REV’, ‘SQL’, ‘ABM’, ‘BC’, ‘MBC’,
433 ‘RIT’, ‘AFC’, ‘SATMODE’, ‘SCOPE’, ‘RESUME’, ‘TBURST’, ‘TUNER’,
434 ‘XIT’.
435 Func Status is a non null value for “activate” or “de-activate”
437 otherwise, much as TRUE/FALSE definitions in the C language
438 (true is non-zero and false is zero, ‘0’).
439 Note: Passing a ‘?’ (query) as the first argument instead of a
441 Func token will return a space separated list of radio backend
442 supported set function tokens. Use this to determine the sup‐
443 ported functions of a given radio backend.
444 u, get_func 'Func'
446 Get 'Func Status'.
447 Returns Func Status as a non null value for the Func token given
449 as in set_func above.
450 Note: Passing a ‘?’ (query) as the first argument instead of a
452 Func token will return a space separated list of radio backend
453 supported get function tokens. Use this to determine the sup‐
454 ported functions of a given radio backend.
455 L, set_level 'Level' 'Level Value'
457 Set 'Level' and 'Level Value'.
458 Level is a token: ‘PREAMP’, ‘ATT’, ‘VOX’, ‘AF’, ‘RF’, ‘SQL’,
460 ‘IF’, ‘APF’, ‘NR’, ‘PBT_IN’, ‘PBT_OUT’, ‘CWPITCH’, ‘RFPOWER’,
461 ‘MICGAIN’, ‘KEYSPD’, ‘NOTCHF’, ‘COMP’, ‘AGC’, ‘BKINDL’, ‘BAL’,
462 ‘METER’, ‘VOXGAIN’, ‘ANTIVOX’, ‘SLOPE_LOW’, ‘SLOPE_HIGH’, ‘RAW‐
463 STR’, ‘SWR’, ‘ALC’, ‘STRENGTH’.
464 The Level Value can be a float or an integer value. For the AGC
466 token the value is one of ‘0’ = OFF, ‘1’ = SUPERFAST, ‘2’ =
467 FAST, ‘3’ = SLOW, ‘4’ = USER, ‘5’ = MEDIUM, ‘6’ = AUTO.
468 Note: Passing a ‘?’ (query) as the first argument instead of a
470 Level token will return a space separated list of radio backend
471 supported set level tokens. Use this to determine the supported
472 levels of a given radio backend.
473 l, get_level 'Level'
475 Get 'Level Value'.
476 Returns Level Value as a float or integer for the Level token
478 given as in set_level above.
479 Note: Passing a ‘?’ (query) as the first argument instead of a
481 Level token will return a space separated list of radio backend
482 supported get level tokens. Use this to determine the supported
483 levels of a given radio backend.
484 P, set_parm 'Parm' 'Parm Value'
486 Set 'Parm' and 'Parm Value'.
487 Parm is a token: ‘ANN’, ‘APO’, ‘BACKLIGHT’, ‘BEEP’, ‘TIME’,
489 ‘BAT’, ‘KEYLIGHT’.
490 Note: Passing a ‘?’ (query) as the first argument instead of a
492 Parm token will return a space separated list of radio backend
493 supported set parameter tokens. Use this to determine the sup‐
494 ported parameters of a given radio backend.
495 p, get_parm 'Parm'
497 Get 'Parm Value'.
498 Returns Parm Value as a float or integer for the Parm token
500 given as in set_parm above.
501 Note: Passing a ‘?’ (query) as the first argument instead of a
503 Parm token will return a space separated list of radio backend
504 supported get parameter tokens. Use this to determine the sup‐
505 ported parameters of a given radio backend.
506 B, set_bank 'Bank'
508 Set 'Bank'.
509 Sets the current memory bank number.
511 E, set_mem 'Memory#'
513 Set 'Memory#' channel number.
514 e, get_mem
516 Get 'Memory#' channel number.
517 G, vfo_op 'Mem/VFO Op'
519 Perform a 'Mem/VFO Op'.
520 Mem/VFO Operation is a token: ‘CPY’, ‘XCHG’, ‘FROM_VFO’,
522 ‘TO_VFO’, ‘MCL’, ‘UP’, ‘DOWN’, ‘BAND_UP’, ‘BAND_DOWN’, ‘LEFT’,
523 ‘RIGHT’, ‘TUNE’, ‘TOGGLE’.
524 Note: Passing a ‘?’ (query) as the first argument instead of a
526 Mem/VFO Op token will return a space separated list of radio
527 backend supported Set Mem/VFO Op tokens. Use this to determine
528 the supported Mem/VFO Ops of a given radio backend.
529 g, scan 'Scan Fct' 'Scan Channel'
531 Perform a 'Scan Fct' on a 'Scan Channel'.
532 Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
534 ‘DELTA’, ‘VFO’, ‘PLT’.
535 Scan Channel is an integer (maybe?).
537 Note: Passing a ‘?’ (query) as the first argument instead of a
539 Scan Fct token will return a space separated list of radio back‐
540 end supported Scan Function tokens. Use this to determine the
541 supported Scan Functions of a given radio backend.
542 H, set_channel 'Channel'
544 Set memory 'Channel' data.
545 Not implemented yet.
547 h, get_channel
549 Get memory 'Channel' data.
550 Not implemented yet.
552 A, set_trn 'Transceive'
554 Set 'Transceive' mode.
555 Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
557 Transceive is a mechanism for radios to report events without a
559 specific call for information.
560 Note: Passing a ‘?’ (query) as the first argument instead of a
562 Transceive token will return a space separated list of radio
563 backend supported Transceive mode tokens. Use this to determine
564 the supported Transceive modes of a given radio backend.
565 a, get_trn
567 Get 'Transceive' mode.
568 Transceive mode (reporting event) as in set_trn above.
570 *, reset 'Reset'
572 Perform rig 'Reset'.
573 Reset is a value: ‘0’ = None, ‘1’ = Software reset, ‘2’ = VFO
575 reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
576 Since these values are defined as a bitmask in include/ham‐
578 lib/rig.h, it should be possible to AND these values together to
579 do multiple resets at once, if the backend supports it or sup‐
580 ports a reset action via rig control at all.
581 0x87, set_powerstat 'Power Status'
583 Set 'Power Status'.
584 Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’ =
586 Power Standby.
587 0x88, get_powerstat
589 Get 'Power Status' as in set_powerstat above.
590 0x89, send_dtmf 'Digits'
592 Set DTMF 'Digits'.
593 0x8a, recv_dtmf
595 Get DTMF 'Digits'.
596 _, get_info
598 Get misc information about the rig (no VFO in 'VFO mode' or
599 value is passed).
600 dump_state
602 Return certain state information about the radio backend.
603 1, dump_caps
605 Not a real rig remote command, it just dumps capabilities, i.e.
606 what the backend knows about this model, and what it can do.
607 TODO: Ensure this is in a consistent format so it can be read
609 into a hash, dictionary, etc. Bug reports requested.
610 Note: This command will produce many lines of output so be very
612 careful if using a fixed length array! For example, running
613 this command against the Dummy backend results in over 5kB of
614 text output.
615 VFO parameter not used in 'VFO mode'.
617 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
619 Returns 'Power mW'.
620 Converts a Power value in a range of 0.0...1.0 to the real
622 transmit power in milli-Watts (integer).
623 'Frequency' and 'Mode' also need to be provided as output power
625 may vary according to these values.
626 VFO parameter is not used in VFO mode.
628 4, mW2power 'Power mW' 'Frequency' 'Mode'
630 Returns 'Power [0.0..1.0]'.
631 Converts the real transmit power in milli-Watts (integer) to a
633 Power value in a range of 0.0 ... 1.0.
634 'Frequency' and 'Mode' also need to be provided as output power
636 may vary according to these values.
637 VFO parameter is not used in VFO mode.
639 chk_vfo
641 Returns “CHKVFO 1\n” (single line only) if rigctld was invoked
642 with the -o/--vfo option and “CHKVFO 0\n” if not.
643 When in VFO mode the client will need to pass 'VFO' as the first
645 parameter to set or get commands. VFO is one of the strings
646 defined in set_vfo above.
647
649 There are two protocols in use by rigctld, the Default Protocol and the
650 Extended Response Protocol.
651 The Default Protocol is intended primarily for the communication
653 between Hamlib library functions and rigctld (“NET rigctl”, available
654 using radio model ‘2’).
655 The Extended Response Protocol is intended to be used with scripts or
657 other programs interacting directly with rigctld as consistent feedback
658 is provided.
659 Default Protocol
661 The Default Protocol is intentionally simple. Commands are entered on
662 a single line with any needed values. In practice, reliable results
663 are obtained by terminating each command string with a newline charac‐
664 ter, ‘\n’.
665 Example set frequency and mode commands (Perl code):
667 print $socket "F 14250000\n";
669 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
670 A one line response will be sent as a reply to set commands, “RPRT x\n”
672 where x is the Hamlib error code with ‘0’ indicating success of the
673 command.
674 Responses from rigctld get commands are text values and match the same
676 tokens used in the set commands. Each value is returned on its own
677 line. On error the string “RPRT x\n” is returned where x is the Hamlib
678 error code.
679 Example get frequency (Perl code):
681 print $socket "f\n";
683 "14250000\n"
684 Most get functions return one to three values. A notable exception is
686 the dump_caps command which returns many lines of key:value pairs.
687 This protocol is primarily used by the “NET rigctl” (rigctl model 2)
689 backend which allows applications already written for Hamlib's C API to
690 take advantage of rigctld without the need of rewriting application
691 code. An application's user can select rotator model 2 (“NET rigctl”)
692 and then set rig_pathname to “localhost:4532” or other network
693 host:port (set by the -T/-t options, respectively, above).
694 Extended Response Protocol
696 The Extended Response protocol adds several rules to the strings
697 returned by rigctld and adds a rule for the command syntax.
698 1. The command received by rigctld is echoed with its long command name
700 followed by the value(s) (if any) received from the client terminated
701 by the specified response separator as the first record of the
702 response.
703 2. The last record of each block is the string “RPRT x\n” where x is
705 the numeric return value of the Hamlib backend function that was called
706 by the command.
707 3. Any records consisting of data values returned by the radio backend
709 are prepended by a string immediately followed by a colon then a space
710 and then the value terminated by the response separator. e.g. “Fre‐
711 quency: 14250000\n” when the command was prepended by ‘+’.
712 4. All commands received will be acknowledged by rigctld
714 with records from rules 1 and 2. Records from rule 3 are only
715 returned when data values must be returned to the client.
716 An example response to a set_mode command sent from the shell prompt
718 (note the prepended ‘+’):
719 $ echo "+M USB 2400" | nc -w 1 localhost 4532
721 set_mode: USB 2400
722 RPRT 0
723 In this case the long command name and values are returned on the first
725 line and the second line contains the end of block marker and the
726 numeric radio backend return value indicating success.
727 An example response to a get_mode query:
729 $ echo "+\get_mode" | nc -w 1 localhost 4532
731 get_mode:
732 Mode: USB
733 Passband: 2400
734 RPRT 0
735 Note: The ‘\’ is still required for the long command name even
737 with the ERP character.
738 In this case, as no value is passed to rigctld, the first line consists
740 only of the long command name. The final line shows that the command
741 was processed successfully by the radio backend.
742 Invoking the Extended Response Protocol requires prepending a command
744 with a punctuation character. As shown in the examples above, prepend‐
745 ing a ‘+’ character to the command results in the responses being sepa‐
746 rated by a newline character (‘\n’). Any other punctuation character
747 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
748 cause that character to become the response separator and the entire
749 response will be on one line.
750 Separator character summary:
752 ‘+’ Each record of the response is appended with a newline (‘\n’).
754 ‘;’, ‘|’, or, ‘,’
756 Each record of the response is appended by the given character
757 resulting in entire response on one line.
758 These are common record separators for text representations of
760 spreadsheet data, etc.
761 ‘?’ Reserved for help in rigctl.
763 ‘_’ Reserved for get_info short command
765 ‘#’ Reserved for comments when reading a command file script.
767 Note: Other punctuation characters have not been tested! Use at
769 your own risk.
770 For example, invoking a get_mode query with a leading ‘;’ returns:
772 get_mode:;Mode: USB;Passband: 2400;RPRT 0
774 Or, using the pipe character ‘|’ returns:
776 get_mode:|Mode: USB|Passband: 2400|RPRT 0
778 And a set_mode command prepended with a ‘|’ returns:
780 set_mode: USB 2400|RPRT 0
782 Such a format will allow reading a response as a single event using a
784 preferred response separator. Other punctuation characters have not
785 been tested!
786 The following commands have been tested with the Extended Response pro‐
788 tocol and the included testctld.pl Perl script:
789 set_freq, get_freq, set_split_freq, get_split_freq, set_mode,
791 get_mode, set_split_mode, get_split_mode, set_vfo, get_vfo,
792 set_split_vfo, get_split_vfo, set_rit, get_rit, set_xit,
793 get_xit, set_ptt, get_ptt, power2mW, mW2power, dump_caps.
794
796 The -v, --verbose option allows different levels of diagnostics to be
797 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
798 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
799 A given verbose level is useful for providing needed debugging informa‐
801 tion to the email address below. For example, TRACE output shows all
802 of the values sent to and received from the radio which is very useful
803 for radio backend library development and may be requested by the
804 developers.
805
807 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
808 backgrounding:
809 $ rigctld -m 114 -r /dev/ttyUSB1 &
811 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter while
813 setting baud rate and stop bits, and backgrounding:
814 $ rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
816 Start rigctld for an Elecraft K3 using COM2 on MS Windows:
818 $ rigctld -m 229 -r COM2
820 Connect to the already running rigctld and set the frequency to 14.266
822 MHz with a 1 second read timeout using the default protocol from the
823 shell prompt:
824 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532
826 Connect to a running rigctld with rigctl on the local host:
828 $ rigctl -m2
830
832 No authentication whatsoever; DO NOT leave this TCP port open wide to
833 the Internet. Please ask if stronger security is needed or consider
834 using a Secure Shell (ssh(1)) tunnel.
835 As rigctld does not need any greater permissions than rigctl, it is
837 advisable to not start rigctld as “root” or another system user account
838 in order to limit any vulnerability.
839
841 The daemon is not detaching and backgrounding itself.
842 No method to exit the daemon so the kill(1) command must be used to
844 terminate it.
845 Multiple clients using the daemon may experience contention with the
847 connected radio.
848 Report bugs to:
850 Hamlib Developer mailing list
852 ⟨hamlib-developer@lists.sourceforge.net⟩
853
855 This file is part of Hamlib, a project to develop a library that sim‐
856 plifies radio, rotator, and amplifier control functions for developers
857 of software primarily of interest to radio amateurs and those inter‐
858 ested in radio communications.
859 Copyright © 2000-2010 Stephane Fillod
861 Copyright © 2000-2018 the Hamlib Group (various contributors)
862 Copyright © 2011-2019 Nate Bargmann
863 This is free software; see the file COPYING for copying conditions.
865 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
866 PARTICULAR PURPOSE.
867
869 kill(1), rigctl(1), ssh(1), hamlib(7)
870
872 Links to the Hamlib Wiki, Git repository, release archives, and daily
873 snapshot archives:
874 hamlib.org ⟨http://www.hamlib.org⟩.
876Hamlib 2019-12-10 RIGCTLD(1)