1RIGCTLD(8) Rig Control Daemon RIGCTLD(8)
2
6 rigctld - Hamlib TCP rig control daemon
7
9 rigctld [OPTION]...
10
12 The rigctld program is a NEW Hamlib rig control daemon ready for test‐
13 ing that handles client requests via TCP sockets. This allows multiple
14 user programs to share one radio (this needs testing). Multiple radios
15 can be controlled on different TCP ports by use of multiple rigctld
16 processes. The syntax of the commands are the same as rigctl. It is
17 hoped that rigctld will be especially useful for client authors using
18 languages such as Perl, Python, PHP, and others.
19 rigctld communicates to a client through a TCP socket using text com‐
21 mands shared with rigctl. The protocol is simple; commands are sent to
22 rigctld on one line and rigctld responds to "get" commands with the
23 requested values, one per line, when successful, otherwise, it responds
24 with one line "RPTR x", where x is a negative number indicating the
25 error code. Commands that do not return values respond with the line
26 "RPTR x", where x is zero when successful, otherwise is a regative num‐
27 ber indicating the error code. Each line is terminated with a newline
28 '\n' character. This protocol is primarily for use by the NET rigctl
29 (rig model 2)backend.
30 A separate Extended Response protocol extends the above behavior by
32 echoing the received command string as a header, any returned values as
33 a key: value pair, and the "RPTR x" string as the end of response
34 marker which includes the Hamlib success or failure value. See the
35 PROTOCOL section for details. Consider using this protocol for clients
36 that will interact with rigctld directly through a TCP socket.
37 Keep in mind that Hamlib is BETA level software. While a lot of back‐
39 end libraries lack complete rig support, the basic functions are usu‐
40 ally well supported. The API may change without publicized notice,
41 while an advancement of the minor version (e.g. 1.1.x to 1.2.x) indi‐
42 cates such a change.
43 Please report bugs and provide feedback at the e-mail address given in
45 the REPORTING BUGS section. Patches and code enhancements are also
46 welcome.
47
49 This program follows the usual GNU command line syntax, with long
50 options starting with two dashes ('-').
51 Here is a summary of the supported options:
53 -m, --model=id
55 Select radio model number. See the -l, --list option below.
56 -r, --rig-file=device
58 Use device as the file name of the port the radio is connected.
59 Often a serial port, but could be a USB to serial adapter or USB
60 port device. Typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0,
61 etc.
62 -p, --ptt-file=device
64 Use device as the file name of the Push-To-Talk device using a
65 device file as described above.
66 -d, --dcd-file=device
68 Use device as the file name of the Data Carrier Detect device
69 using a device file as described above.
70 -P, --ptt-type=type
72 Use type of Push-To-Talk device. Supported types are RIG (CAT
73 command), DTR, RTS, PARALLEL, NONE.
74 -D, --dcd-type=type
76 Use type of Data Carrier Detect device. Supported types are RIG
77 (CAT command), DSR, CTS, CD, PARALLEL, NONE.
78 -s, --serial-speed=baud
80 Set serial speed to baud rate. Uses maximum serial speed from
81 rig backend capabilities (set by -m above) as the default.
82 -c, --civaddr=id
84 Use id as the CI-V address to communicate with the rig. Only
85 useful for Icom rigs.
86 N.B.: The id is in decimal notation, unless prefixed by 0x for a
88 hexadecimal value.
89 -T, --listen-addr=IPADDR
91 Use IPADDR as the listening IP address. The default is ANY.
92 -t, --port=number
94 Use number as the TCP listening port. The default is 4532.
95 N.B.: As rotctld's default port is 4533, it is advisable to use
97 even numbered ports for rigctld, e.g. 4532, 4534, 4536, etc.
98 -L, --show-conf
100 List all config parameters for the radio defined with -m above.
101 -C, --set-conf=parm=val[,parm=val]*
103 Set config parameter. e.g. --set-conf=stop_bits=2
104 Use -L option for a list.
106 -l, --list
108 List all model numbers defined in Hamlib and exit.
109 -u, --dump-caps
111 Dump capabilities for the radio defined with -m above and exit.
112 -o, --vfo
114 Set vfo mode, requiring an extra VFO argument in front of each
115 appropriate command (except \set_vfo!). Otherwise, 'currVFO' is
116 assumed when this option is not set and an extra VFO argument is
117 not used. See \chk_vfo below.
118 -e, --end-marker
120 Use END marker in rigctld protocol.
121 N.B.: This option should be considered obsolete. Please con‐
123 sider using the Extended Response protocol instead (see PROTOCOL
124 below). This option will be removed in a future Hamlib release.
125 -v, --verbose
127 Set verbose mode, cumulative (see DIAGNOSTICS below).
128 -h, --help
130 Show a summary of these options and exit.
131 -V, --version
133 Show the version of rigctld and exit.
134 N.B. Some options may not be implemented by a given backend and will
136 return an error. This is most likely to occur with the --set-conf and
137 --show-conf options.
138 Please note that the backend for the radio to be controlled, or the
140 radio itself may not support some commands. In that case, the operation
141 will fail with a Hamlib error code.
142
144 Commands can be sent over the TCP socket either as a single char, or as
145 a long command name plus the value(s) space separated on one '\n' ter‐
146 minated line. See PROTOCOL.
147 Since most of the Hamlib operations have a set and a get method, an
149 upper case letter will be used for set methods whereas the correspond‐
150 ing lower case letter refers to the get method. Each operation also
151 has a long name; prepend a backslash to send a long command name.
152 Example (Perl): `print $socket "\\dump_caps\n";' to see what the
154 radio's backend can do
155 (N.B.: In Perl and many other languages a '\' will need to be escaped
156 with a preceding '\' so that even though two backslash characters
157 appear in the code, only one will be passed to rigctld. This is a pos‐
158 sible bug, beware!).
159 Please note that the backend for the radio to be controlled, or the
161 radio itself may not support some commands. In that case, the operation
162 will fail with a Hamlib error message.
163 Here is a summary of the supported commands (In the case of "set" com‐
165 mands the quoted string is replaced by the value in the description.
166 In the case of "get" commands the quoted string is the key name of the
167 value returned.):
168 F, set_freq 'Frequency'
170 Set 'Frequency', in Hz.
171 f, get_freq
173 Get 'Frequency', in Hz.
174 M, set_mode 'Mode' 'Passband'
176 Set 'Mode': USB, LSB, CW, CWR, RTTY, RTTYR, AM, FM, WFM, AMS,
177 PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH,
178 DSB.
179 Set 'Passband' in Hz, or '0' for the Hamlib backend default.
181 m, get_mode
183 Get 'Mode' 'Passband'.
184 Returns Mode as a string from set_mode above and Passband in Hz.
186 V, set_vfo 'VFO'
188 Set 'VFO': VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub, TX,
189 RX.
190 In VFO mode only a single VFO parameter is required.
192 v, get_vfo
194 Get current 'VFO'.
195 Returns VFO as a string from set_vfo above.
197 J, set_rit 'RIT'
199 Set 'RIT', in Hz, can be + or -.
200 A value of '0' resets RIT and *should* turn RIT off. If not,
202 file a bug report against the Hamlib backend.
203 j, get_rit
205 Get 'RIT', in Hz.
206 Z, set_xit 'XIT'
208 Set 'XIT', in Hz can be + or -.
209 A value of '0' resets RIT and *should* turn RIT off. If not,
211 file a bug report against the Hamlib backend.
212 z, get_xit
214 Get 'XIT', in Hz.
215 T, set_ptt 'PTT'
217 Set 'PTT', 0 (RX) or 1 (TX).
218 t, get_ptt
220 Get 'PTT' status.
221 0x8b, get_dcd
223 Get 'DCD' (squelch) status, 0 (Closed) or 1 (Open)
224 R, set_rptr_shift 'Rptr Shift'
226 Set 'Rptr Shift': "+", "-" or something else for none.
227 r, get_rptr_shift
229 Get 'Rptr Shift'. Returns "+", "-" or "None".
230 O, set_rptr_offs 'Rptr Offset'
232 Set 'Rptr Offset', in Hz.
233 o, get_rptr_offs
235 Get 'Rptr Offset', in Hz.
236 C, set_ctcss_tone 'CTCSS Tone'
238 Set 'CTCSS Tone', in tenths of Hz.
239 c, get_ctcss_tone
241 Get 'CTCSS Tone', in tenths of Hz.
242 D, set_dcs_code 'DCS Code'
244 Set 'DCS Code'.
245 d, get_dcs_code
247 Get 'DCS Code'.
248 0x90, set_ctcss_sql 'CTCSS Sql'
250 Set 'CTCSS Sql' tone, in tenths of Hz.
251 0x91, get_ctcss_sql
253 Get 'CTCSS Sql' tone, in tenths of Hz.
254 0x92, set_dcs_sql 'DCS Sql'
256 Set 'DCS Sql' code.
257 0x93, get_dcs_sql
259 Get 'DCS Sql' code.
260 I, set_split_freq 'Tx Frequency'
262 Set 'TX Frequency', in Hz.
263 i, get_split_freq
265 Get 'TX Frequency', in Hz.
266 X, set_split_mode 'TX Mode' 'TX Passband'
268 Set 'TX Mode': AM, FM, CW, CWR, USB, LSB, RTTY, RTTYR, WFM, AMS,
269 PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH,
270 DSB.
271 The 'TX Passband' is the exact passband in Hz, or '0' for the
273 Hamlib backend default.
274 x, get_split_mode
276 Get 'TX Mode' and 'TX Passband'.
277 Returns TX mode as a string from set_split_mode above and TX
279 passband in Hz.
280 S, set_split_vfo 'Split' 'TX VFO'
282 Set 'Split' mode, '0' or '1', and 'TX VFO' from set_vfo above.
283 s, get_split_vfo
285 Get 'Split' mode, '0' or '1', and 'TX VFO'.
286 N, set_ts 'Tuning Step'
288 Set 'Tuning Step', in Hz.
289 n, get_ts
291 Get 'Tuning Step', in Hz.
292 U, set_func 'Func' 'Func Status'
294 Set 'Func' 'Func Status'.
295 Func is one of: FAGC, NB, COMP, VOX, TONE, TSQL, SBKIN, FBKIN,
297 ANF, NR, AIP, APF, MON, MN, RF, ARO, LOCK, MUTE, VSC, REV, SQL,
298 ABM, BC, MBC, AFC, SATMODE, SCOPE, RESUME, TBURST, TUNER.
299 Func Status argument is a non null value for "activate", "de-
301 activate" otherwise, much as TRUE/FALSE definitions in C lan‐
302 guage.
303 u, get_func
305 Get 'Func' 'Func Status'.
306 Returns Func as a string from set_func above and Func status as
308 a non null value.
309 L, set_level 'Level' 'Level Value'
311 Set 'Level' and 'Level Value'.
312 Level is one of: PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR,
314 PBT_IN, PBT_OUT, CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF,
315 COMP, AGC, BKINDL, BAL, METER, VOXGAIN, ANTIVOX. SLOPE_LOW,
316 SLOPE_HIGH, RAWSTR, SQLSTAT, SWR, ALC, STRENGTH.
317 The Level Value can be a float or an integer.
319 l, get_level
321 Get 'Level' 'Level Value'.
322 Returns Level as a string from set_level above and Level value
324 as a float or integer.
325 P, set_parm 'Parm' 'Parm Value'
327 Set 'Parm' 'Parm Value'
328 Parm is one of: ANN, APO, BACKLIGHT, BEEP, TIME, BAT, KEYLIGHT.
330 p, get_parm
332 Get 'Parm' 'Parm Value'.
333 Returns Parm as a string from set_parm above and Parm Value as a
335 float or integer.
336 B, set_bank 'Bank'
338 Set 'Bank'. Sets the current memory bank number.
339 E, set_mem 'Memory#'
341 Set 'Memory#' channel number.
342 e, get_mem
344 Get 'Memory#' channel number.
345 G, vfo_op 'Mem/VFO Op'
347 Perform 'Mem/VFO Op'.
348 Mem VFO operation is one of: CPY, XCHG, FROM_VFO, TO_VFO, MCL,
350 UP, DOWN, BAND_UP, BAND_DOWN, LEFT, RIGHT, TUNE, TOGGLE.
351 g, scan 'Scan Fct' 'Scan Channel'
353 Perform 'Scan Fct' 'Scan Channel'.
354 Scan function/channel is one of: STOP, MEM, SLCT, PRIO, PROG,
356 DELTA, VFO, PLT.
357 H, set_channel 'Channel'
359 Set memory 'Channel' data. Not implemented yet.
360 h, get_channel
362 Get memory 'Channel' data. Not implemented yet.
363 A, set_trn 'Transceive'
365 Set 'Transceive' mode (reporting event): OFF, RIG, POLL.
366 a, get_trn
368 Get 'Transceive' mode (reporting event) as in set_trn above.
369 Y, set_ant 'Antenna'
371 Set 'Antenna' number (0, 1, 2, ..).
372 y, get_ant
374 Get 'Antenna' number (0, 1, 2, ..).
375 *, reset 'Reset'
377 Perform rig 'Reset'.
378 0 = None, 1 = Software reset, 2 = VFO reset, 4 = Memory Clear
380 reset, 8 = Master reset. Since these values are defined as a
381 bitmask in rig.h, it should be possible to AND these values
382 together to do multiple resets at once, if the backend supports
383 it or supports a reset action via rig control at all.
384 b, send_morse 'Morse'
386 Send 'Morse' symbols.
387 0x87, set_powerstat 'Power Status'
389 Set power On/Off/Standby 'Power Status'.
390 0 = Power Off, 1 = Power On, 2 = Power Standby. Defined as a
392 bitmask in rig.h.
393 0x88, get_powerstat
395 Get power On/Off/Standby 'Power Status' as in set_powerstat
396 above.
397 0x89, send_dtmf 'Digits'
399 Set DTMF 'Digits'.
400 0x8a, recv_dtmf
402 Get DTMF 'Digits'.
403 _, get_info
405 Get misc information about the rig (no VFO in 'VFO mode' or
406 value is passed).
407 1, dump_caps
409 Not a real rig remote command, it just dumps capabilities, i.e.
410 what the backend knows about this model, and what it can do.
411 TODO: Ensure this is in a consistent format so it can be read
412 into a hash, dictionary, etc. Bug reports requested.
413 N.B.: This command will produce many lines of output so be very
415 careful if using a fixed length array! For example, running
416 this command against the Dummy backend results in over 5kB of
417 text output.
418 VFO parameter not used in 'VFO mode'.
420 2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
422 Returns 'Power mW'
423 Converts a Power value in a range of 0.0 ... 1.0 to the real
425 transmit power in milli-Watts (integer). The frequency and mode
426 also need to be provided as output power may vary according to
427 these values.
428 VFO parameter not used in 'VFO mode'.
430 4, mW2power 'Power mW' 'Frequency' 'Mode'
432 Returns 'Power [0.0..1.0]'
433 Converts the real transmit power in milli-Watts (integer) to a
435 Power value in a range of 0.0 ... 1.0. The frequency and mode
436 also need to be provided as output power may vary according to
437 these values.
438 VFO parameter not used in 'VFO mode'.
440 w, send_cmd 'Cmd'
442 Send raw command string to rig.
443 For binary protocols enter values as \0xAA\0xBB. Expect a
445 'Reply' from the rig which will likely be a binary block or an
446 ASCII string.
447 chk_vfo
449 Returns "CHKVFO 1\n" (single line only) if rigctld was invoked
450 with the -o or --vfo option, "CHKVFO 0\n" if not.
451 When in VFO mode the client will need to pass 'VFO' as the first
453 parameter to \set or \get commands. 'VFO' is one of the strings
454 defined for \set_vfo above.
455
457 Default Protocol
458 The rigctld protocol is intentionally simple. Commands are entered on a
460 single line with any needed values. In Perl, reliable results are
461 obtained by terminating each command string with a newline character,
462 '\n'.
463 Example set (Perl code):
465 print $socket "F 14250000\n";
467 print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
468 A one line response will be sent as a reply to set commands, "RPTR
470 x\n" where x is the Hamlib error code with '0' indicating success of
471 the command.
472 Responses from rigctld get commands are text values and match the same
474 tokens used in the set commands. Each value is returned on its own
475 line. On error the string "RPTR x\n" is returned where x is the Hamlib
476 error code.
477 Example get (Perl code):
479 print $socket "f\n";
481 "14250000\n"
482 Most get functions return one to three values. A notable exception is
484 the \dump_caps function which returns many lines of key:value pairs.
485 This protocol is primarily used by the NET rigctl (rigctl model 2)
487 backend which allows applications already written for Hamlib's C API to
488 take advantage of rigctld without the need of rewriting application
489 code. An application's user can select rig model 2 ("NET rigctl") and
490 then set rig_pathname to "localhost:4532" or other network host:port.
491 Extended Response Protocol
493 An EXPERIMENTAL Extended Response protocol has been introduced into
495 rigctld as of February 16, 2010. This protocol adds several rules to
496 the strings returned by rigctld and adds a rule for the command syntax.
497 1. The command received by rigctld is echoed with its long command name
499 followed by the value(s) (if any) received from the client terminated
500 by the specified response separator as the record line of the response.
501 2. The last line of each block is the string "RPTR x\n" where x is the
503 numeric return value of the Hamlib backend function that was called by
504 the command.
505 3. Any records consisting of data values returned by the rig backend
507 are prepended by a string immediately followed by a colon then a space
508 and then the value terminated by the response separator. e.g. "Fre‐
509 quency: 14250000\n" when the command was prepended by '+'.
510 4. All commands received will be acknowledged by rigctld with lines
512 from rules 1 and 2. Lines from rule 3 are only returned when data val‐
513 ues must be returned to the client.
514 An example response to a +\set_mode command (note the prepended '+'):
516 $ echo "+M USB 2400" | nc -w 1 localhost 4532
518 set_mode: USB 2400
519 RPRT 0
520 In this case the long command name and values are returned on the first
522 line and the second line contains the end of block marker and the
523 numeric rig backend return value indicating success.
524 An example response to a \get_mode query:
526 $ echo "+\get_mode" | nc -w 1 localhost 4532
528 get_mode:
529 Mode: USB
530 Passband: 2400
531 RPRT 0
532 In this case, as no value is passed to rigctld, the first line consists
534 only of the long command name. The final line shows that the command
535 was processed successfully by the rig backend.
536 Invoking the Extended Response protocol requires prepending a command
538 with a punctuation character. As shown in the examples above, prepend‐
539 ing a '+' character to the command results in the responses being sepa‐
540 rated by a newline character ('\n'). Any other punctuation character
541 recognized by the C ispunct() function except '\', '?', or '_' will
542 cause that character to become the response separator and the entire
543 response will be on one line.
544 Separator character summary:
546 '+'
548 Each record of the response is appended with a newline ('\n').
549 ';', '|', or ','
551 Each record of the response is appended by the given character
552 resulting in entire response on one line.
553 Common record separators for text representations of spreadsheet
555 data, etc.
556 '?'
558 Reserved for 'help' in rigctl short command
559 '_'
561 Reserved for \get_info short command
562 '#'
564 Reserved for comments when reading a command file script
565 Other punctuation characters have not been tested! Use at your
567 own risk.
568 For example, invoking a ;\get_mode query with a leading ';' returns:
570 get_mode:;Mode: USB;Passband: 2400;RPRT 0
572 Or, using the pipe character '|' returns:
574 get_mode:|Mode: USB|Passband: 2400|RPRT 0
576 And a \set_pos command prepended with a '|' returns:
578 set_mode: USB 2400|RPRT 0
580 Such a format will allow reading a response as a single event using a
582 prefered response separator. Other punctuation characters have not
583 been tested!
584 The following commands have been tested with the Extended Response pro‐
586 tocol and the included testctld.pl script:
587 \set_freq \get_freq \set_split_freq \get_split_freq
588 \set_mode \get_mode \set_split_mode \get_split_mode
589 \set_vfo \get_vfo \set_split_vfo \get_split_vfo
590 \set_rit \get_rit
591 \set_xit \get_xit
592 \set_ptt \get_ptt
593 \power2mW \mW2power
594 \dump_caps
595
597 Start rigctld for a Yaesu FT-920 using a USB-to-serial adapter and
598 backgrounding:
599 $ rigctld -m 114 -r /dev/ttyUSB1 &
601 Start rigctld for a Yaesu FT-920 using a USB to serial adapter while
603 setting baud rate and stop bits, and backgrounding:
604 $ rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
606 Connect to the already running rigctld, and set current frequency to
608 14.266 MHz with a 1 second read timeout using the default protocol:
609 $ echo "\set_freq 14266000" | nc -w 1 localhost 4532
611
613 The -v, --verbose, option allows different levels of diagnostics to be
614 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
615 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
616 A given verbose level is useful for providing needed debugging informa‐
618 tion to the email address below. For example, TRACE output shows all
619 of the values sent to and received from the radio which is very useful
620 for radio backend library development and may be requested by the
621 developers. See the README.betatester and README.developer files for
622 more information.
623
625 No authentication whatsoever; DO NOT leave this TCP port open wide to
626 the Internet. Please ask if stronger security is needed or consider
627 using an SSH tunnel.
628 As rigctld does not need any greater permissions than rigctl, it is
630 advisable to not start rigctld as root or another system user account
631 in order to limit any vulnerability.
632
634 The daemon is not detaching and backgrounding itself.
635 Much testing needs to be done.
637
639 Report bugs to <hamlib-developer@lists.sourceforge.net>.
640 We are already aware of the bugs in the previous section :-)
642
644 Written by Stephane Fillod, Nate Bargmann, and the Hamlib Group
645 <http://www.hamlib.org>.
647
649 Copyright © 2000-2010 Stephane Fillod
650 Copyright © 2010 Nate Bargmann
651 Copyright © 2000-2010 the Hamlib Group.
652 This is free software; see the source for copying conditions. There is
654 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
655 PURPOSE.
656
658 rigctl(1), hamlib(3)
659Hamlib March 1, 2010 RIGCTLD(8)