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] [-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 -Z, --debug-time-stamps
168 Enable time stamps for the debug messages.
169 Use only in combination with the -v option as it generates no
171 output on its own.
172 -h, --help
174 Show a summary of these options and exit.
175 -V, --version
177 Show version of rigctl and exit.
178 Note: Some options may not be implemented by a given backend and will
180 return an error. This is most likely to occur with the --set-conf and
181 --show-conf options.
182 Please note that the backend for the radio to be controlled, or the
184 radio itself may not support some commands. In that case, the opera‐
185 tion will fail with a Hamlib error code.
186
188 Commands can be sent over the TCP socket either as a single char, or as
189 a long command name plus the value(s) space separated on one ‘\n’ ter‐
190 minated line. See PROTOCOL.
191 Since most of the Hamlib operations have a set and a get method, an
193 upper case letter will be used for set methods whereas the correspond‐
194 ing lower case letter refers to the get method. Each operation also
195 has a long name; prepend a backslash, ‘\’, to send a long command name.
196 Example (Perl): “print $socket "\\dump_caps\n";” to see what the
198 radio's backend can do (Note: In Perl and many other languages a ‘\’
199 will need to be escaped with a preceding ‘\’ so that even though two
200 backslash characters appear in the code, only one will be passed to
201 rigctld. This is a possible bug, beware!).
202 Note: The backend for the radio to be controlled, or the radio itself
204 may not support some commands. In that case, the operation will fail
205 with a Hamlib error message.
206 Here is a summary of the supported commands (In the case of set com‐
208 mands the quoted italicized string is replaced by the value in the
209 description. In the case of get commands the quoted italicized string
210 is the key name of the value returned.):
211 F, set_freq 'Frequency'
213 Set 'Frequency', in Hz.
214 Frequency may be a floating point or integer value.
216 f, get_freq
218 Get 'Frequency', in Hz.
219 Returns an integer value.
221 M, set_mode 'Mode' 'Passband'
223 Set 'Mode' and 'Passband'.
224 Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
226 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’,
227 ‘ECSSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
228 Passband is in Hz as an integer, or ‘0’ for the radio backend
230 default.
231 Note: Passing a ‘?’ (query) as the first argument instead of a
233 Mode token will return a space separated list of radio backend
234 supported Modes. Use this to determine the supported Modes of a
235 given radio backend.
236 m, get_mode
238 Get 'Mode' and 'Passband'.
239 Returns Mode as a token and Passband in Hz as in set_mode above.
241 V, set_vfo 'VFO'
243 Set 'VFO'.
244 VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
246 ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
247 In VFO mode (see --vfo option above) only a single VFO parameter
249 is required:
250 $ rigctl -m 229 -r /dev/rig -o
252 Rig command: V
254 VFO: VFOB
255 Rig command:
257 v, get_vfo
259 Get current 'VFO'.
260 Returns VFO as a token as in set_vfo above.
262 J, set_rit 'RIT'
264 Set 'RIT'.
265 RIT is in Hz and can be + or -. A value of ‘0’ resets RIT
267 (Receiver Incremental Tuning) to match the VFO frequency.
268 Note: RIT needs to be explicitly activated or deactivated with
270 the set_func command. This allows setting the RIT offset inde‐
271 pendently of its activation and allows RIT to remain active
272 while setting the offset to ‘0’.
273 j, get_rit
275 Get 'RIT' in Hz.
276 Returned value is an integer.
278 Z, set_xit 'XIT'
280 Set 'XIT'.
281 XIT is in Hz and can be + or -. A value of ‘0’ resets XIT
283 (Transmitter Incremental Tuning) to match the VFO frequency.
284 Note: XIT needs to be explicitly activated or deactivated with
286 the set_func command. This allows setting the XIT offset inde‐
287 pendently of its activation and allows XIT to remain active
288 while setting the offset to ‘0’.
289 z, get_xit
291 Get 'XIT' in Hz.
292 Returned value is an integer.
294 T, set_ptt 'PTT'
296 Set 'PTT'.
297 PTT is a value: ‘0’ (RX), ‘1’ (TX), ‘2’ (TX mic), or ‘3’ (TX
299 data).
300 t, get_ptt
302 Get 'PTT' status.
303 Returns PTT as a value in set_ptt above.
305 S, set_split_vfo 'Split' 'TX VFO'
307 Set 'Split' mode.
308 Split is either ‘0’ = Normal or ‘1’ = Split.
310 Set 'TX VFO'.
312 TX VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’,
314 ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
315 s, get_split_vfo
317 Get 'Split' mode.
318 Split is either ‘0’ = Normal or ‘1’ = Split.
320 Get 'TX VFO'.
322 TX VFO is a token as in set_split_vfo above.
324 I, set_split_freq 'Tx Frequency'
326 Set 'TX Frequency', in Hz.
327 Frequency may be a floating point or integer value.
329 i, get_split_freq
331 Get 'TX Frequency', in Hz.
332 Returns an integer value.
334 X, set_split_mode 'TX Mode' 'TX Passband'
336 Set 'TX Mode' and 'TX Passband'.
337 TX Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
339 ‘AM’, ‘FM’, ‘WFM’, ‘AMS’, ‘PKTLSB’, ‘PKTUSB’, ‘PKTFM’,
340 ‘ECSSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
341 TX Passband is in Hz as an integer, or ‘0’ for the radio backend
343 default.
344 Note: Passing a ‘?’ (query) as the first argument instead of a
346 TX Mode token will return a space separated list of radio back‐
347 end supported TX Modes. Use this to determine the supported TX
348 Modes of a given radio backend.
349 x, get_split_mode
351 Get 'TX Mode' and 'TX Passband'.
352 Returns TX Mode as a token and TX Passband in Hz as in
354 set_split_mode above.
355 Y, set_ant 'Antenna'
357 Set 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
358 y, get_ant
360 Get 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
361 b, send_morse 'Morse'
363 Send 'Morse' symbols.
364 0x8b, get_dcd
366 Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
367 R, set_rptr_shift 'Rptr Shift'
369 Set 'Rptr Shift'.
370 Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
372 r, get_rptr_shift
374 Get 'Rptr Shift'.
375 Returns ‘+’, ‘-’, or ‘None’.
377 O, set_rptr_offs 'Rptr Offset'
379 Set 'Rptr Offset', in Hz.
380 o, get_rptr_offs
382 Get 'Rptr Offset', in Hz.
383 C, set_ctcss_tone 'CTCSS Tone'
385 Set 'CTCSS Tone', in tenths of Hz.
386 c, get_ctcss_tone
388 Get 'CTCSS Tone', in tenths of Hz.
389 D, set_dcs_code 'DCS Code'
391 Set 'DCS Code'.
392 d, get_dcs_code
394 Get 'DCS Code'.
395 0x90, set_ctcss_sql 'CTCSS Sql'
397 Set 'CTCSS Sql' tone, in tenths of Hz.
398 0x91, get_ctcss_sql
400 Get 'CTCSS Sql' tone, in tenths of Hz.
401 0x92, set_dcs_sql 'DCS Sql'
403 Set 'DCS Sql' code.
404 0x93, get_dcs_sql
406 Get 'DCS Sql'
407 code.
408 N, set_ts 'Tuning Step'
410 Set 'Tuning Step', in Hz.
411 n, get_ts
413 Get 'Tuning Step', in Hz.
414 U, set_func 'Func' 'Func Status'
416 Set 'Func' and 'Func Status'.
417 Func is a token: ‘FAGC’, ‘NB’, ‘COMP’, ‘VOX’, ‘TONE’, ‘TSQL’,
419 ‘SBKIN’, ‘FBKIN’, ‘ANF’, ‘NR’, ‘AIP’, ‘APF’, ‘MON’, ‘MN’, ‘RF’,
420 ‘ARO’, ‘LOCK’, ‘MUTE’, ‘VSC’, ‘REV’, ‘SQL’, ‘ABM’, ‘BC’, ‘MBC’,
421 ‘RIT’, ‘AFC’, ‘SATMODE’, ‘SCOPE’, ‘RESUME’, ‘TBURST’, ‘TUNER’,
422 ‘XIT’.
423 Func Status is a non null value for “activate” or “de-activate”
425 otherwise, much as TRUE/FALSE definitions in the C language
426 (true is non-zero and false is zero, ‘0’).
427 Note: Passing a ‘?’ (query) as the first argument instead of a
429 Func token will return a space separated list of radio backend
430 supported set function tokens. Use this to determine the sup‐
431 ported functions of a given radio backend.
432 u, get_func 'Func'
434 Get 'Func Status'.
435 Returns Func Status as a non null value for the Func token given
437 as in set_func above.
438 Note: Passing a ‘?’ (query) as the first argument instead of a
440 Func token will return a space separated list of radio backend
441 supported get function tokens. Use this to determine the sup‐
442 ported functions of a given radio backend.
443 L, set_level 'Level' 'Level Value'
445 Set 'Level' and 'Level Value'.
446 Level is a token: ‘PREAMP’, ‘ATT’, ‘VOX’, ‘AF’, ‘RF’, ‘SQL’,
448 ‘IF’, ‘APF’, ‘NR’, ‘PBT_IN’, ‘PBT_OUT’, ‘CWPITCH’, ‘RFPOWER’,
449 ‘MICGAIN’, ‘KEYSPD’, ‘NOTCHF’, ‘COMP’, ‘AGC’, ‘BKINDL’, ‘BAL’,
450 ‘METER’, ‘VOXGAIN’, ‘ANTIVOX’, ‘SLOPE_LOW’, ‘SLOPE_HIGH’, ‘RAW‐
451 STR’, ‘SWR’, ‘ALC’, ‘STRENGTH’.
452 The Level Value can be a float or an integer value. For the AGC
454 token the value is one of ‘0’ = OFF, ‘1’ = SUPERFAST, ‘2’ =
455 FAST, ‘3’ = SLOW, ‘4’ = USER, ‘5’ = MEDIUM, ‘6’ = AUTO.
456 Note: Passing a ‘?’ (query) as the first argument instead of a
458 Level token will return a space separated list of radio backend
459 supported set level tokens. Use this to determine the supported
460 levels of a given radio backend.
461 l, get_level 'Level'
463 Get 'Level Value'.
464 Returns Level Value as a float or integer for the Level token
466 given as in set_level above.
467 Note: Passing a ‘?’ (query) as the first argument instead of a
469 Level token will return a space separated list of radio backend
470 supported get level tokens. Use this to determine the supported
471 levels of a given radio backend.
472 P, set_parm 'Parm' 'Parm Value'
474 Set 'Parm' and 'Parm Value'.
475 Parm is a token: ‘ANN’, ‘APO’, ‘BACKLIGHT’, ‘BEEP’, ‘TIME’,
477 ‘BAT’, ‘KEYLIGHT’.
478 Note: Passing a ‘?’ (query) as the first argument instead of a
480 Parm token will return a space separated list of radio backend
481 supported set parameter tokens. Use this to determine the sup‐
482 ported parameters of a given radio backend.
483 p, get_parm 'Parm'
485 Get 'Parm Value'.
486 Returns Parm Value as a float or integer for the Parm token
488 given as in set_parm above.
489 Note: Passing a ‘?’ (query) as the first argument instead of a
491 Parm token will return a space separated list of radio backend
492 supported get parameter tokens. Use this to determine the sup‐
493 ported parameters of a given radio backend.
494 B, set_bank 'Bank'
496 Set 'Bank'.
497 Sets the current memory bank number.
499 E, set_mem 'Memory#'
501 Set 'Memory#' channel number.
502 e, get_mem
504 Get 'Memory#' channel number.
505 G, vfo_op 'Mem/VFO Op'
507 Perform a 'Mem/VFO Op'.
508 Mem/VFO Operation is a token: ‘CPY’, ‘XCHG’, ‘FROM_VFO’,
510 ‘TO_VFO’, ‘MCL’, ‘UP’, ‘DOWN’, ‘BAND_UP’, ‘BAND_DOWN’, ‘LEFT’,
511 ‘RIGHT’, ‘TUNE’, ‘TOGGLE’.
512 Note: Passing a ‘?’ (query) as the first argument instead of a
514 Mem/VFO Op token will return a space separated list of radio
515 backend supported Set Mem/VFO Op tokens. Use this to determine
516 the supported Mem/VFO Ops of a given radio backend.
517 g, scan 'Scan Fct' 'Scan Channel'
519 Perform a 'Scan Fct' on a 'Scan Channel'.
520 Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
522 ‘DELTA’, ‘VFO’, ‘PLT’.
523 Scan Channel is an integer (maybe?).
525 Note: Passing a ‘?’ (query) as the first argument instead of a
527 Scan Fct token will return a space separated list of radio back‐
528 end supported Scan Function tokens. Use this to determine the
529 supported Scan Functions of a given radio backend.
530 H, set_channel 'Channel'
532 Set memory 'Channel' data.
533 Not implemented yet.
535 h, get_channel
537 Get memory 'Channel' data.
538 Not implemented yet.
540 A, set_trn 'Transceive'
542 Set 'Transceive' mode.
543 Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
545 Transceive is a mechanism for radios to report events without a
547 specific call for information.
548 Note: Passing a ‘?’ (query) as the first argument instead of a
550 Transceive token will return a space separated list of radio
551 backend supported Transceive mode tokens. Use this to determine
552 the supported Transceive modes of a given radio backend.
553 a, get_trn
555 Get 'Transceive' mode.
556 Transceive mode (reporting event) as in set_trn above.
558 *, reset 'Reset'
560 Perform rig 'Reset'.
561 Reset is a value: ‘0’ = None, ‘1’ = Software reset, ‘2’ = VFO
563 reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
564 Since these values are defined as a bitmask in include/ham‐
566 lib/rig.h, it should be possible to AND these values together to
567 do multiple resets at once, if the backend supports it or sup‐
568 ports a reset action via rig control at all.
569 0x87, set_powerstat 'Power Status'
571 Set 'Power Status'.
572 Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’ =
574 Power Standby.
575 0x88, get_powerstat
577 Get 'Power Status' as in set_powerstat above.
578 0x89, send_dtmf 'Digits'
580 Set DTMF 'Digits'.
581 0x8a, recv_dtmf
583 Get DTMF 'Digits'.
584 _, get_info
586 Get misc information about the rig (no VFO in 'VFO mode' or
587 value is passed).
588 1, dump_caps
590 Not a real rig remote command, it just dumps capabilities, i.e.
591 what the backend knows about this model, and what it can do.
592 TODO: Ensure this is in a consistent format so it can be read
594 into a hash, dictionary, etc. Bug reports requested.
595 Note: This command will produce many lines of output so be very
597 careful if using a fixed length array! For example, running
598 this command against the Dummy backend results in over 5kB of
599 text output.
600 VFO parameter not used in 'VFO mode'.
602 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
604 Returns 'Power mW'.
605 Converts a Power value in a range of 0.0...1.0 to the real
607 transmit power in milli-Watts (integer).
608 'Frequency' and 'Mode' also need to be provided as output power
610 may vary according to these values.
611 VFO parameter is not used in VFO mode.
613 4, mW2power 'Power mW' 'Frequency' 'Mode'
615 Returns 'Power [0.0..1.0]'.
616 Converts the real transmit power in milli-Watts (integer) to a
618 Power value in a range of 0.0 ... 1.0.
619 'Frequency' and 'Mode' also need to be provided as output power
621 may vary according to these values.
622 VFO parameter is not used in VFO mode.
624 chk_vfo
626 Returns “CHKVFO 1\n” (single line only) if rigctld was invoked
627 with the -o/--vfo option and “CHKVFO 0\n” if not.
628 When in VFO mode the client will need to pass 'VFO' as the first
630 parameter to set or get commands. VFO is one of the strings
631 defined in set_vfo above.
632
634 There are two protocols in use by rigctld, the Default Protocol and the
635 Extended Response Protocol.
636 The Default Protocol is intended primarily for the communication
638 between Hamlib library functions and rigctld (“NET rigctl”, available
639 using radio model ‘2’).
640 The Extended Response Protocol is intended to be used with scripts or
642 other programs interacting directly with rigctld as consistent feedback
643 is provided.
644 Default Protocol
646 The Default Protocol is intentionally simple. Commands are entered on
647 a single line with any needed values. In practice, reliable results
648 are obtained by terminating each command string with a newline charac‐
649 ter, ‘\n’.
650 Example set frequency and mode commands (Perl code):
652 print $socket "F 14250000\n";
654 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
655 A one line response will be sent as a reply to set commands, “RPRT x\n”
657 where x is the Hamlib error code with ‘0’ indicating success of the
658 command.
659 Responses from rigctld get commands are text values and match the same
661 tokens used in the set commands. Each value is returned on its own
662 line. On error the string “RPRT x\n” is returned where x is the Hamlib
663 error code.
664 Example get frequency (Perl code):
666 print $socket "f\n";
668 "14250000\n"
669 Most get functions return one to three values. A notable exception is
671 the dump_caps command which returns many lines of key:value pairs.
672 This protocol is primarily used by the “NET rigctl” (rigctl model 2)
674 backend which allows applications already written for Hamlib's C API to
675 take advantage of rigctld without the need of rewriting application
676 code. An application's user can select rotator model 2 (“NET rigctl”)
677 and then set rig_pathname to “localhost:4532” or other network
678 host:port (set by the -T/-t options, respectively, above).
679 Extended Response Protocol
681 The Extended Response protocol adds several rules to the strings
682 returned by rigctld and adds a rule for the command syntax.
683 1. The command received by rigctld is echoed with its long command name
685 followed by the value(s) (if any) received from the client terminated
686 by the specified response separator as the first record of the
687 response.
688 2. The last record of each block is the string “RPRT x\n” where x is
690 the numeric return value of the Hamlib backend function that was called
691 by the command.
692 3. Any records consisting of data values returned by the radio backend
694 are prepended by a string immediately followed by a colon then a space
695 and then the value terminated by the response separator. e.g. “Fre‐
696 quency: 14250000\n” when the command was prepended by ‘+’.
697 4. All commands received will be acknowledged by rigctld
699 with records from rules 1 and 2. Records from rule 3 are only
700 returned when data values must be returned to the client.
701 An example response to a set_mode command sent from the shell prompt
703 (note the prepended ‘+’):
704 $ echo "+M USB 2400" | nc -w 1 localhost 4532
706 set_mode: USB 2400
707 RPRT 0
708 In this case the long command name and values are returned on the first
710 line and the second line contains the end of block marker and the
711 numeric radio backend return value indicating success.
712 An example response to a get_mode query:
714 $ echo "+\get_mode" | nc -w 1 localhost 4532
716 get_mode:
717 Mode: USB
718 Passband: 2400
719 RPRT 0
720 Note: The ‘\’ is still required for the long command name even
722 with the ERP character.
723 In this case, as no value is passed to rigctld, the first line consists
725 only of the long command name. The final line shows that the command
726 was processed successfully by the radio backend.
727 Invoking the Extended Response Protocol requires prepending a command
729 with a punctuation character. As shown in the examples above, prepend‐
730 ing a ‘+’ character to the command results in the responses being sepa‐
731 rated by a newline character (‘\n’). Any other punctuation character
732 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
733 cause that character to become the response separator and the entire
734 response will be on one line.
735 Separator character summary:
737 ‘+’ Each record of the response is appended with a newline (‘\n’).
739 ‘;’, ‘|’, or, ‘,’
741 Each record of the response is appended by the given character
742 resulting in entire response on one line.
743 These are common record separators for text representations of
745 spreadsheet data, etc.
746 ‘?’ Reserved for help in rigctl.
748 ‘_’ Reserved for get_info short command
750 ‘#’ Reserved for comments when reading a command file script.
752 Note: Other punctuation characters have not been tested! Use at
754 your own risk.
755 For example, invoking a get_mode query with a leading ‘;’ returns:
757 get_mode:;Mode: USB;Passband: 2400;RPRT 0
759 Or, using the pipe character ‘|’ returns:
761 get_mode:|Mode: USB|Passband: 2400|RPRT 0
763 And a set_mode command prepended with a ‘|’ returns:
765 set_mode: USB 2400|RPRT 0
767 Such a format will allow reading a response as a single event using a
769 preferred response separator. Other punctuation characters have not
770 been tested!
771 The following commands have been tested with the Extended Response pro‐
773 tocol and the included testctld.pl Perl script:
774 set_freq, get_freq, set_split_freq, get_split_freq, set_mode,
776 get_mode, set_split_mode, get_split_mode, set_vfo, get_vfo,
777 set_split_vfo, get_split_vfo, set_rit, get_rit, set_xit,
778 get_xit, set_ptt, get_ptt, power2mW, mW2power, dump_caps.
779
781 The -v, --verbose option allows different levels of diagnostics to be
782 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
783 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
784 A given verbose level is useful for providing needed debugging informa‐
786 tion to the email address below. For example, TRACE output shows all
787 of the values sent to and received from the radio which is very useful
788 for radio backend library development and may be requested by the
789 developers.
790
792 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
793 backgrounding:
794 $ rigctld -m 114 -r /dev/ttyUSB1 &
796 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter while
798 setting baud rate and stop bits, and backgrounding:
799 $ rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
801 Start rigctld for an Elecraft K3 using COM2 on MS Windows:
803 $ rigctld -m 229 -r COM2
805 Connect to the already running rigctld and set the frequency to 14.266
807 MHz with a 1 second read timeout using the default protocol from the
808 shell prompt:
809 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532
811 Connect to a running rigctld with rigctl on the local host:
813 $ rigctl -m2
815
817 No authentication whatsoever; DO NOT leave this TCP port open wide to
818 the Internet. Please ask if stronger security is needed or consider
819 using a Secure Shell (ssh(1)) tunnel.
820 As rigctld does not need any greater permissions than rigctl, it is
822 advisable to not start rigctld as “root” or another system user account
823 in order to limit any vulnerability.
824
826 The daemon is not detaching and backgrounding itself.
827 No method to exit the daemon so the kill(1) command must be used to
829 terminate it.
830 Multiple clients using the daemon may experience contention with the
832 connected rotator.
833 Report bugs to:
835 Hamlib Developer mailing list
837 ⟨hamlib-developer@lists.sourceforge.net⟩
838
840 This file is part of Hamlib, a project to develop a library that sim‐
841 plifies radio and rotator control functions for developers of software
842 primarily of interest to radio amateurs and those interested in radio
843 communications.
844 Copyright © 2000-2010 Stephane Fillod
846 Copyright © 2000-2018 the Hamlib Group (various contributors)
847 Copyright © 2011-2018 Nate Bargmann
848 This is free software; see the file COPYING for copying conditions.
850 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
851 PARTICULAR PURPOSE.
852
854 kill(1), rigctl(1), ssh(1), hamlib(7)
855
857 Links to the Hamlib Wiki, Git repository, release archives, and daily
858 snapshot archives:
859 hamlib.org ⟨http://www.hamlib.org⟩.
861Hamlib 2018-04-29 RIGCTLD(1)