1RIGCTLD(1)                     Hamlib Utilities                     RIGCTLD(1)
2
3
4

NAME

6       rigctld - TCP radio control daemon
7

SYNOPSIS

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

DESCRIPTION

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
25       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
36       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
43       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
47       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

OPTIONS

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
57       Here is a summary of the supported options:
58
59       -m, --model=id
60              Select radio model number.
61
62              See model list (use “rigctl -l”).
63
64              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
68       -r, --rig-file=device
69              Use device as the file name of the port connected to the radio.
70
71              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
76              The special string “uh-rig” may be  given  to  enable  micro-ham
77              device support.
78
79       -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
83       -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
87       -P, --ptt-type=type
88              Use type of Push-To-Talk device.
89
90              Supported  types  are ‘RIG’ (CAT command), ‘DTR’, ‘RTS’, ‘PARAL‐
91              LEL’, ‘NONE’, overriding PTT type defined in the rig's backend.
92
93              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
99       -D, --dcd-type=type
100              Use type of Data Carrier Detect device.
101
102              Supported types are ‘RIG’ (CAT  command),  ‘DSR’,  ‘CTS’,  ‘CD’,
103              ‘PARALLEL’, ‘NONE’.
104
105       -s, --serial-speed=baud
106              Set serial speed to baud rate.
107
108              Uses  maximum  serial speed from radio backend capabilities (set
109              by -m above) as the default.
110
111       -c, --civaddr=id
112              Use id as the CI-V address to communicate with the rig.
113
114              Only useful for Icom and some Ten-Tec rigs.
115
116              Note: The id is in decimal notation, unless prefixed by  0x,  in
117              which case it is hexadecimal.
118
119       -T, --listen-addr=IPADDR
120              Use IPADDR as the listening IP address.
121
122              The default is ANY.
123
124       -t, --port=number
125              Use number as the TCP listening port.
126
127              The default is 4532.
128
129              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
132       -L, --show-conf
133              List all config parameters for the radio defined with -m above.
134
135       -C, --set-conf=parm=val[,parm=val]
136              Set radio configuration parameter(s), e.g.  stop_bits=2.
137
138              Use the -L option above for a list of  configuration  parameters
139              for a given model number.
140
141       -u, --dump-caps
142              Dump capabilities for the radio defined with -m above and exit.
143
144       -l, --list
145              List all model numbers defined in Hamlib and exit.
146
147              The list is sorted by model number.
148
149              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
154       -o, --vfo
155              Enable vfo mode.
156
157              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
162              See chk_vfo below.
163
164       -v, --verbose
165              Set verbose mode, cumulative (see DIAGNOSTICS below).
166
167       -Z, --debug-time-stamps
168              Enable time stamps for the debug messages.
169
170              Use  only  in  combination with the -v option as it generates no
171              output on its own.
172
173       -h, --help
174              Show a summary of these options and exit.
175
176       -V, --version
177              Show version of rigctl and exit.
178
179       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
183       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

COMMANDS

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
192       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
197       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
203       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
207       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
212       F, set_freq 'Frequency'
213              Set 'Frequency', in Hz.
214
215              Frequency may be a floating point or integer value.
216
217       f, get_freq
218              Get 'Frequency', in Hz.
219
220              Returns an integer value.
221
222       M, set_mode 'Mode' 'Passband'
223              Set 'Mode' and 'Passband'.
224
225              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
229              Passband is in Hz as an integer, or ‘0’ for  the  radio  backend
230              default.
231
232              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
237       m, get_mode
238              Get 'Mode' and 'Passband'.
239
240              Returns Mode as a token and Passband in Hz as in set_mode above.
241
242       V, set_vfo 'VFO'
243              Set 'VFO'.
244
245              VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
246              ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
247
248              In VFO mode (see --vfo option above) only a single VFO parameter
249              is required:
250
251                 $ rigctl -m 229 -r /dev/rig -o
252
253                 Rig command: V
254                 VFO: VFOB
255
256                 Rig command:
257
258       v, get_vfo
259              Get current 'VFO'.
260
261              Returns VFO as a token as in set_vfo above.
262
263       J, set_rit 'RIT'
264              Set 'RIT'.
265
266              RIT is in Hz and can be + or -.   A  value  of  ‘0’  resets  RIT
267              (Receiver Incremental Tuning) to match the VFO frequency.
268
269              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
274       j, get_rit
275              Get 'RIT' in Hz.
276
277              Returned value is an integer.
278
279       Z, set_xit 'XIT'
280              Set 'XIT'.
281
282              XIT is in Hz and can be + or -.   A  value  of  ‘0’  resets  XIT
283              (Transmitter Incremental Tuning) to match the VFO frequency.
284
285              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
290       z, get_xit
291              Get 'XIT' in Hz.
292
293              Returned value is an integer.
294
295       T, set_ptt 'PTT'
296              Set 'PTT'.
297
298              PTT is a value: ‘0’ (RX), ‘1’ (TX), ‘2’ (TX  mic),  or  ‘3’  (TX
299              data).
300
301       t, get_ptt
302              Get 'PTT' status.
303
304              Returns PTT as a value in set_ptt above.
305
306       S, set_split_vfo 'Split' 'TX VFO'
307              Set 'Split' mode.
308
309              Split is either ‘0’ = Normal or ‘1’ = Split.
310
311              Set 'TX VFO'.
312
313              TX  VFO  is  a  token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’,
314              ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
315
316       s, get_split_vfo
317              Get 'Split' mode.
318
319              Split is either ‘0’ = Normal or ‘1’ = Split.
320
321              Get 'TX VFO'.
322
323              TX VFO is a token as in set_split_vfo above.
324
325       I, set_split_freq 'Tx Frequency'
326              Set 'TX Frequency', in Hz.
327
328              Frequency may be a floating point or integer value.
329
330       i, get_split_freq
331              Get 'TX Frequency', in Hz.
332
333              Returns an integer value.
334
335       X, set_split_mode 'TX Mode' 'TX Passband'
336              Set 'TX Mode' and 'TX Passband'.
337
338              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
342              TX Passband is in Hz as an integer, or ‘0’ for the radio backend
343              default.
344
345              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
350       x, get_split_mode
351              Get 'TX Mode' and 'TX Passband'.
352
353              Returns TX Mode  as  a  token  and  TX  Passband  in  Hz  as  in
354              set_split_mode above.
355
356       Y, set_ant 'Antenna'
357              Set 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
358
359       y, get_ant
360              Get 'Antenna' number (‘0’, ‘1’, ‘2’, ...).
361
362       b, send_morse 'Morse'
363              Send 'Morse' symbols.
364
365       0x8b, get_dcd
366              Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
367
368       R, set_rptr_shift 'Rptr Shift'
369              Set 'Rptr Shift'.
370
371              Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
372
373       r, get_rptr_shift
374              Get 'Rptr Shift'.
375
376              Returns ‘+’, ‘-’, or ‘None’.
377
378       O, set_rptr_offs 'Rptr Offset'
379              Set 'Rptr Offset', in Hz.
380
381       o, get_rptr_offs
382              Get 'Rptr Offset', in Hz.
383
384       C, set_ctcss_tone 'CTCSS Tone'
385              Set 'CTCSS Tone', in tenths of Hz.
386
387       c, get_ctcss_tone
388              Get 'CTCSS Tone', in tenths of Hz.
389
390       D, set_dcs_code 'DCS Code'
391              Set 'DCS Code'.
392
393       d, get_dcs_code
394              Get 'DCS Code'.
395
396       0x90, set_ctcss_sql 'CTCSS Sql'
397              Set 'CTCSS Sql' tone, in tenths of Hz.
398
399       0x91, get_ctcss_sql
400              Get 'CTCSS Sql' tone, in tenths of Hz.
401
402       0x92, set_dcs_sql 'DCS Sql'
403              Set 'DCS Sql' code.
404
405       0x93, get_dcs_sql
406              Get 'DCS Sql'
407               code.
408
409       N, set_ts 'Tuning Step'
410              Set 'Tuning Step', in Hz.
411
412       n, get_ts
413              Get 'Tuning Step', in Hz.
414
415       U, set_func 'Func' 'Func Status'
416              Set 'Func' and 'Func Status'.
417
418              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
424              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
428              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
433       u, get_func 'Func'
434              Get 'Func Status'.
435
436              Returns Func Status as a non null value for the Func token given
437              as in set_func above.
438
439              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
444       L, set_level 'Level' 'Level Value'
445              Set 'Level' and 'Level Value'.
446
447              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
453              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
457              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
462       l, get_level 'Level'
463              Get 'Level Value'.
464
465              Returns  Level  Value  as a float or integer for the Level token
466              given as in set_level above.
467
468              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
473       P, set_parm 'Parm' 'Parm Value'
474              Set 'Parm' and 'Parm Value'.
475
476              Parm  is  a  token:  ‘ANN’,  ‘APO’, ‘BACKLIGHT’, ‘BEEP’, ‘TIME’,
477              ‘BAT’, ‘KEYLIGHT’.
478
479              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
484       p, get_parm 'Parm'
485              Get 'Parm Value'.
486
487              Returns  Parm  Value  as  a  float or integer for the Parm token
488              given as in set_parm above.
489
490              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
495       B, set_bank 'Bank'
496              Set 'Bank'.
497
498              Sets the current memory bank number.
499
500       E, set_mem 'Memory#'
501              Set 'Memory#' channel number.
502
503       e, get_mem
504              Get 'Memory#' channel number.
505
506       G, vfo_op 'Mem/VFO Op'
507              Perform a 'Mem/VFO Op'.
508
509              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
513              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
518       g, scan 'Scan Fct' 'Scan Channel'
519              Perform a 'Scan Fct' on a 'Scan Channel'.
520
521              Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
522              ‘DELTA’, ‘VFO’, ‘PLT’.
523
524              Scan Channel is an integer (maybe?).
525
526              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
531       H, set_channel 'Channel'
532              Set memory 'Channel' data.
533
534              Not implemented yet.
535
536       h, get_channel
537              Get memory 'Channel' data.
538
539              Not implemented yet.
540
541       A, set_trn 'Transceive'
542              Set 'Transceive' mode.
543
544              Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
545
546              Transceive is a mechanism for radios to report events without  a
547              specific call for information.
548
549              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
554       a, get_trn
555              Get 'Transceive' mode.
556
557              Transceive mode (reporting event) as in set_trn above.
558
559       *, reset 'Reset'
560              Perform rig 'Reset'.
561
562              Reset is a value: ‘0’ = None, ‘1’ = Software reset,  ‘2’  =  VFO
563              reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
564
565              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
570       0x87, set_powerstat 'Power Status'
571              Set 'Power Status'.
572
573              Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’  =
574              Power Standby.
575
576       0x88, get_powerstat
577              Get 'Power Status' as in set_powerstat above.
578
579       0x89, send_dtmf 'Digits'
580              Set DTMF 'Digits'.
581
582       0x8a, recv_dtmf
583              Get DTMF 'Digits'.
584
585       _, get_info
586              Get  misc  information  about  the  rig (no VFO in 'VFO mode' or
587              value is passed).
588
589       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
593              TODO:  Ensure  this  is in a consistent format so it can be read
594              into a hash, dictionary, etc.  Bug reports requested.
595
596              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
601              VFO parameter not used in 'VFO mode'.
602
603       2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
604              Returns 'Power mW'.
605
606              Converts  a  Power  value  in  a  range of 0.0...1.0 to the real
607              transmit power in milli-Watts (integer).
608
609              'Frequency' and 'Mode' also need to be provided as output  power
610              may vary according to these values.
611
612              VFO parameter is not used in VFO mode.
613
614       4, mW2power 'Power mW' 'Frequency' 'Mode'
615              Returns 'Power [0.0..1.0]'.
616
617              Converts  the  real transmit power in milli-Watts (integer) to a
618              Power value in a range of 0.0 ... 1.0.
619
620              'Frequency' and 'Mode' also need to be provided as output  power
621              may vary according to these values.
622
623              VFO parameter is not used in VFO mode.
624
625       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
629              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

PROTOCOL

634       There are two protocols in use by rigctld, the Default Protocol and the
635       Extended Response Protocol.
636
637       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
641       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
645   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
651       Example set frequency and mode commands (Perl code):
652
653            print $socket "F 14250000\n";
654            print $socket "\\set_mode LSB 2400\n";   # escape leading '\'
655
656       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
660       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
665       Example get frequency (Perl code):
666
667            print $socket "f\n";
668            "14250000\n"
669
670       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
673       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
680   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
684       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
689       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
693       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
698       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
702       An  example  response  to a set_mode command sent from the shell prompt
703       (note the prepended ‘+’):
704
705            $ echo "+M USB 2400" | nc -w 1 localhost 4532
706            set_mode: USB 2400
707            RPRT 0
708
709       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
713       An example response to a get_mode query:
714
715            $ echo "+\get_mode" | nc -w 1 localhost 4532
716            get_mode:
717            Mode: USB
718            Passband: 2400
719            RPRT 0
720
721              Note: The ‘\’ is still required for the long command  name  even
722              with the ERP character.
723
724       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
728       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
736       Separator character summary:
737
738+’    Each record of the response is appended with a newline (‘\n’).
739
740;’, ‘|’, or, ‘,
741              Each  record  of the response is appended by the given character
742              resulting in entire response on one line.
743
744              These are common record separators for text  representations  of
745              spreadsheet data, etc.
746
747?’    Reserved for help in rigctl.
748
749_’    Reserved for get_info short command
750
751#’    Reserved for comments when reading a command file script.
752
753              Note: Other punctuation characters have not been tested!  Use at
754              your own risk.
755
756       For example, invoking a get_mode query with a leading ‘;’ returns:
757
758            get_mode:;Mode: USB;Passband: 2400;RPRT 0
759
760       Or, using the pipe character ‘|’ returns:
761
762            get_mode:|Mode: USB|Passband: 2400|RPRT 0
763
764       And a set_mode command prepended with a ‘|’ returns:
765
766            set_mode: USB 2400|RPRT 0
767
768       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
772       The following commands have been tested with the Extended Response pro‐
773       tocol and the included testctld.pl Perl script:
774
775              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

DIAGNOSTICS

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
785       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

EXAMPLE

792       Start rigctld for a Yaesu FT-920  using  a  USB-to-serial  adapter  and
793       backgrounding:
794
795            $ rigctld -m 114 -r /dev/ttyUSB1 &
796
797       Start  rigctld  for  a Yaesu FT-920 using a USB-to-serial adapter while
798       setting baud rate and stop bits, and backgrounding:
799
800            $ rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
801
802       Start rigctld for an Elecraft K3 using COM2 on MS Windows:
803
804            $ rigctld -m 229 -r COM2
805
806       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
810            $ echo "\set_freq 14266000" | nc -w 1 localhost 4532
811
812       Connect to a running rigctld with rigctl on the local host:
813
814            $ rigctl -m2
815

SECURITY

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
821       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

BUGS

826       The daemon is not detaching and backgrounding itself.
827
828       No method to exit the daemon so the kill(1) command  must  be  used  to
829       terminate it.
830
831       Multiple  clients  using  the daemon may experience contention with the
832       connected rotator.
833
834       Report bugs to:
835
836              Hamlib Developer mailing list
837              ⟨hamlib-developer@lists.sourceforge.net⟩
838

COPYING

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
845       Copyright © 2000-2010 Stephane Fillod
846       Copyright © 2000-2018 the Hamlib Group (various contributors)
847       Copyright © 2011-2018 Nate Bargmann
848
849       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

SEE ALSO

854       kill(1), rigctl(1), ssh(1), hamlib(7)
855

COLOPHON

857       Links  to  the Hamlib Wiki, Git repository, release archives, and daily
858       snapshot archives:
859
860              hamlib.org ⟨http://www.hamlib.org⟩.
861
862
863
864Hamlib                            2018-04-29                        RIGCTLD(1)
Impressum