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

NAME

6       rigctl - control radio transceivers and receivers
7

SYNOPSIS

9       rigctl [-hiIlLnouV] [-m id] [-r device] [-p device] [-d device]
10              [-P type] [-D type] [-s baud] [-c id] [-t char] [-C parm=val] -Y
11              [-v[-Z]] [command|-]
12

DESCRIPTION

14       Control radio transceivers and receivers.  rigctl accepts commands from
15       the command line as well as in interactive mode if none are provided on
16       the command line.
17
18       Keep  in mind that Hamlib is BETA level software.  While a lot of back‐
19       end libraries lack complete rig support, the basic functions  are  usu‐
20       ally well supported.
21
22       Please  report bugs and provide feedback at the e-mail address given in
23       the BUGS section below.  Patches and code enhancements sent to the same
24       address are welcome.
25

OPTIONS

27       This  program follows the usual GNU command line syntax.  Short options
28       that take an argument may have the value follow immediately or be sepa‐
29       rated  by a space.  Long options starting with two dashes (‘-’) require
30       an ‘=’ between the option and any argument.
31
32       Here is a summary of the supported options:
33
34       -m, --model=id
35              Select radio model number. Defaults to dummy rig.
36
37              See model list (use “rigctl -l”).
38
39              Note: rigctl (or third party software using the C API) will  use
40              radio model 2 for NET rigctl (communicating with rigctld).
41
42       -r, --rig-file=device
43              Use device as the file name of the port connected to the radio.
44
45              Often a serial port, but could be a USB to serial adapter.  Typ‐
46              ically /dev/ttyS0,  /dev/ttyS1,  /dev/ttyUSB0,  etc.  on  Linux,
47              COM1,  COM2,  etc.  on MS Windows.  The BSD flavors and Mac OS/X
48              have their own designations.  See your system's documentation.
49
50              Can be a network address:port, e.g. 127.0.0.1:12345
51
52              The special string “uh-rig” may be given to enable micro-ham de‐
53              vice support.
54
55       -p, --ptt-file=device
56              Use  device  as the file name of the Push-To-Talk device using a
57              device file as described above.
58
59       -d, --dcd-file=device
60              Use device as the file name of the Data  Carrier  Detect  device
61              using a device file as described above.
62
63       -P, --ptt-type=type
64              Use type of Push-To-Talk device.
65
66              Supported  types  are ‘RIG’ (CAT command), ‘DTR’, ‘RTS’, ‘PARAL‐
67              LEL’, ‘CM108’, ‘GPIO’, ‘GPION’, ‘NONE’, overriding PTT type  de‐
68              fined in the rig's backend.
69
70              Some  side  effects of this command are that when type is set to
71              DTR, read PTT state comes from the  Hamlib  frontend,  not  read
72              from  the  radio.  When set to NONE, PTT state cannot be read or
73              set even if rig backend supports reading/setting PTT status from
74              the rig.
75
76       -D, --dcd-type=type
77              Use type of Data Carrier Detect device.
78
79              Supported  types  are  ‘RIG’  (CAT command), ‘DSR’, ‘CTS’, ‘CD’,
80              ‘PARALLEL’, ‘CM108’, ‘GPIO’, ‘GPION’, ‘NONE’.
81
82       -s, --serial-speed=baud
83              Set serial speed to baud rate.
84
85              Uses maximum serial speed from radio backend  capabilities  (set
86              by -m above) as the default.
87
88       -c, --civaddr=id
89              Use id as the CI-V address to communicate with the rig.
90
91              Only useful for Icom and some Ten-Tec rigs.
92
93              Note:  The  id is in decimal notation, unless prefixed by 0x, in
94              which case it is hexadecimal.
95
96       -t, --send-cmd-term=char
97              Change the termination char for text  protocol  when  using  the
98              send_cmd command.
99
100              The  default  value  is  ASCII  CR (‘0x0D’).  ASCII non-printing
101              characters can be given as the ASCII number in hexadecimal  for‐
102              mat  prepended  with  “0x”.  You may pass an empty string for no
103              termination char.  The string “-1” tells rigctl to switch to bi‐
104              nary  protocol.   See  the send_cmd command for further explana‐
105              tion.
106
107              For example, to specify a command terminator for  Kenwood  style
108              text commands pass “-t ';'” to rigctl.  See EXAMPLE below.
109
110       -L, --show-conf
111              List  all config parameters for the radio defined with -m above.
112              Note the dummy device has no serial parameters.
113
114       -C, --set-conf=parm=val[,parm=val]
115              Set radio configuration parameter(s), e.g.  stop_bits=2.
116
117              Use the -L option above for a list of  configuration  parameters
118              for a given model number.
119
120       -u, --dump-caps
121              Dump capabilities for the radio defined with -m above and exit.
122
123       -l, --list
124              List all model numbers defined in Hamlib and exit.
125
126              The list is sorted by model number.
127
128              Note:  In  Linux  the  list  can  be  scrolled back using Shift-
129              PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
130              minal  in  X  or  the  cmd window in Windows.  The output can be
131              piped to more(1) or less(1), e.g. “rigctl -l | more”.
132
133       -o, --vfo
134              Enable vfo mode.
135
136              An extra VFO argument will be required in front of  each  appro‐
137              priate  command  (except set_vfo).  Otherwise, ‘currVFO’ is used
138              when this option is not set and an extra  VFO  argument  is  not
139              used.
140
141       -n, --no-restore-ai
142              On  exit  rigctl  restores the state of auto information (AI) on
143              the controlled rig.
144
145              If this is not desired, for example if you are using  rigctl  to
146              turn AI mode on or off, pass this option.
147
148       -i, --read-history
149              Read  previously  saved command and argument history from a file
150              (default $HOME/.rigctl_history) for the current session.
151
152              Available when rigctl is built with Readline support (see  READ‐
153              LINE below).
154
155              Note:  To  read  a history file stored in another directory, set
156              the     RIGCTL_HIST_DIR     environment      variable,      e.g.
157              “RIGCTL_HIST_DIR=~/tmp  rigctl -i”.  When RIGCTL_HIST_DIR is not
158              set, the value of HOME is used.
159
160       -I, --save-history
161              Write current session (and previous session(s), if -i option  is
162              given)   command   and  argument  history  to  a  file  (default
163              $HOME/.rigctl_history) at the end of the current session.
164
165              Complete commands with arguments are saved as a single  line  to
166              be  recalled and used or edited.  Available when rigctl is built
167              with Readline support (see READLINE below).
168
169              Note: To write a history file  in  another  directory,  set  the
170              RIGCTL_HIST_DIR         environment        variable,        e.g.
171              “RIGCTL_HIST_DIR=~/tmp rigctl -IRq.  When RIGCTL_HIST_DIR is not
172              set, the value of HOME is used.
173
174       -v, --verbose
175              Set verbose mode, cumulative (see DIAGNOSTICS below).
176
177       -Y,--ignore-err
178              Ignores rig open errors
179
180       -Z, --debug-time-stamps
181              Enable time stamps for the debug messages.
182
183              Use  only  in  combination with the -v option as it generates no
184              output on its own.
185
186       -h, --help
187              Show a summary of these options and exit.
188
189       -V, --version
190              Show version of rigctl and exit.
191
192       -      Stop option processing and read commands from standard input.
193
194              See Standard Input below.
195
196       Note: Some options may not be implemented by a given backend  and  will
197       return  an error.  This is most likely to occur with the --set-conf and
198       --show-conf options.
199
200       Please note that the backend for the radio to be controlled, or the ra‐
201       dio  itself may not support some commands.  In that case, the operation
202       will fail with a Hamlib error code.
203

COMMANDS

205       Commands can be entered either as a single char, or as a  long  command
206       name.   The  commands  are not prefixed with a dash as the options are.
207       They may be typed in when in interactive  mode  or  provided  as  argu‐
208       ment(s)  in  command line interface mode.  In interactive mode commands
209       and their arguments may be entered on a single line:
210
211           M LSB 2400
212
213       Since most of the Hamlib operations have a set and a get method, a sin‐
214       gle  upper  case letter will often be used for a set method whereas the
215       corresponding single lower case letter refers to the get method.   Each
216       operation  also  has  a long name; in interactive mode, prepend a back‐
217       slash, ‘\’, to enter a long command name all lower case.
218
219       Example: Use “\dump_caps” to see what capabilities this radio and back‐
220       end support.
221
222              Note:  The  backend for the radio to be controlled, or the radio
223              itself may not support some commands. In that case,  the  opera‐
224              tion will fail with a Hamlib error message.
225
226   Standard Input
227       As an alternative to the READLINE interactive command entry or a single
228       command for each run, rigctl features a special option where  a  single
229       dash  (‘-’)  may  be used to read commands from standard input (stdin).
230       Commands must be separated by whitespace similar to the commands  given
231       on  the  command  line.  Comments may be added using the ‘#’ character,
232       all text up until the end of the current line including the ‘#’ charac‐
233       ter is ignored.
234
235       A simple example (typed text is in bold):
236
237           $ cat <<.EOF. >cmds.txt
238           > # File of commands
239           > v f m   # query rig
240           > V VFOB F 14200000 M CW 500  # set rig
241           > v f m   # query rig
242           > .EOF.
243
244           $ rigctl -m1 - <cmds.txt
245
246           v VFOA
247
248           f 145000000
249
250           m FM
251           15000
252
253           V VFOB
254           F 14200000
255           M CW 500
256           v VFOB
257
258           f 14200000
259
260           m CW
261           500
262
263           $
264
265   rigctl Commands
266       A  summary  of  commands is included below (In the case of set commands
267       the quoted italicized string is replaced by the value in  the  descrip‐
268       tion.   In the case of get commands the quoted italicized string is the
269       key name of the value returned.):
270
271       Q|q, exit rigctl
272              Exit rigctl in interactive mode.
273
274              When rigctl is controlling the rig directly, will close the  rig
275              backend  and  port.   When rigctl is connected to rigctld (radio
276              model 2), the TCP/IP connection to rigctld is closed and rigctld
277              remains  running,  available  for another TCP/IP network connec‐
278              tion.
279
280       F, set_freq 'Frequency'
281              Set 'Frequency', in Hz.
282
283              Frequency may be a floating point or integer value.
284
285       f, get_freq
286              Get 'Frequency', in Hz.
287
288              Returns an integer value and the VFO hamlib  thinks  is  active.
289              Note that some rigs (e.g. all Icoms) cannot track current VFO so
290              hamlib can get out of sync with the rig if the user presses  rig
291              buttons like the VFO.
292
293       M, set_mode 'Mode' 'Passband'
294              Set 'Mode' and 'Passband'.
295
296              Mode  is  a  token:  ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
297              ‘AM’, ‘FM’, ‘WFM’,  ‘AMS’,  ‘PKTLSB’,  ‘PKTUSB’,  ‘PKTFM’,  ‘EC‐
298              SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
299
300              Passband  is  in  Hz as an integer, -1 for no change, or ‘0’ for
301              the radio backend default.
302
303              Note: Passing a ‘?’ (query) as the first argument instead  of  a
304              Mode  token  will return a space separated list of radio backend
305              supported Modes.  Use this to determine the supported Modes of a
306              given radio backend.
307
308       m, get_mode
309              Get 'Mode' and 'Passband'.
310
311              Returns Mode as a token and Passband in Hz as in set_mode above.
312
313       V, set_vfo 'VFO'
314              Set 'VFO'.
315
316              VFO is a token: ‘VFOA’, ‘VFOB’, ‘VFOC’, ‘currVFO’, ‘VFO’, ‘MEM’,
317              ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
318
319              In VFO mode (see --vfo option above) only a single VFO parameter
320              is required:
321
322                  $ rigctl -m 229 -r /dev/rig -o
323
324                  Rig command: V
325                  VFO: VFOB
326
327                  Rig command:
328
329       v, get_vfo
330              Get current 'VFO'.
331
332              Returns VFO as a token as in set_vfo above.
333
334       J, set_rit 'RIT'
335              Set 'RIT'.
336
337              RIT  is in Hz and can be + or -.  A value of ‘0’ resets RIT (Re‐
338              ceiver Incremental Tuning) to match the VFO frequency.
339
340              Note: RIT needs to be explicitly activated or  deactivated  with
341              the  set_func command.  This allows setting the RIT offset inde‐
342              pendently of its activation and  allows  RIT  to  remain  active
343              while setting the offset to ‘0’.
344
345       j, get_rit
346              Get 'RIT' in Hz.
347
348              Returned value is an integer.
349
350       Z, set_xit 'XIT'
351              Set 'XIT'.
352
353              XIT  is  in  Hz  and  can  be + or -.  A value of ‘0’ resets XIT
354              (Transmitter Incremental Tuning) to match the VFO frequency.
355
356              Note: XIT needs to be explicitly activated or  deactivated  with
357              the  set_func command.  This allows setting the XIT offset inde‐
358              pendently of its activation and  allows  XIT  to  remain  active
359              while setting the offset to ‘0’.
360
361       z, get_xit
362              Get 'XIT' in Hz.
363
364              Returned value is an integer.
365
366       T, set_ptt 'PTT'
367              Set 'PTT'.
368
369              PTT  is  a  value:  ‘0’ (RX), ‘1’ (TX), ‘2’ (TX mic), or ‘3’ (TX
370              data).
371
372       t, get_ptt
373              Get 'PTT' status.
374
375              Returns PTT as a value in set_ptt above.
376
377       S, set_split_vfo 'Split' 'TX VFO'
378              Set 'Split' mode.
379
380              Split is either ‘0’ = Normal or ‘1’ = Split.
381
382              Set 'TX VFO'.
383
384              TX VFO is a token: ‘VFOA’,  ‘VFOB’,  ‘VFOC’,  ‘currVFO’,  ‘VFO’,
385              ‘MEM’, ‘Main’, ‘Sub’, ‘TX’, ‘RX’.
386
387       s, get_split_vfo
388              Get 'Split' mode.
389
390              Split is either ‘0’ = Normal or ‘1’ = Split.
391
392              Get 'TX VFO'.
393
394              TX VFO is a token as in set_split_vfo above.
395
396       I, set_split_freq 'Tx Frequency'
397              Set 'TX Frequency', in Hz.
398
399              Frequency may be a floating point or integer value.
400
401       i, get_split_freq
402              Get 'TX Frequency', in Hz.
403
404              Returns an integer value.
405
406       X, set_split_mode 'TX Mode' 'TX Passband'
407              Set 'TX Mode' and 'TX Passband'.
408
409              TX  Mode is a token: ‘USB’, ‘LSB’, ‘CW’, ‘CWR’, ‘RTTY’, ‘RTTYR’,
410              ‘AM’, ‘FM’, ‘WFM’,  ‘AMS’,  ‘PKTLSB’,  ‘PKTUSB’,  ‘PKTFM’,  ‘EC‐
411              SSUSB’, ‘ECSSLSB’, ‘FA’, ‘SAM’, ‘SAL’, ‘SAH’, ‘DSB’.
412
413              TX Passband is in Hz as an integer, or ‘0’ for the radio backend
414              default.
415
416              Note: Passing a ‘?’ (query) as the first argument instead  of  a
417              TX  Mode token will return a space separated list of radio back‐
418              end supported TX Modes.  Use this to determine the supported  TX
419              Modes of a given radio backend.
420
421       x, get_split_mode
422              Get 'TX Mode' and 'TX Passband'.
423
424              Returns  TX  Mode  as  a  token  and  TX  Passband  in  Hz as in
425              set_split_mode above.
426
427       Y, set_ant 'Antenna' 'Option'
428              Set 'Antenna' and 'Option'.
429
430              Number is 1-based antenna# (‘1’, ‘2’, ‘3’, ...).
431
432              Option depends on rig..for Icom it probably sets the Tx & Rx an‐
433              tennas  as  in the IC-7851. See your manual for rig specific op‐
434              tion values. Most rigs don't care about the option.
435
436              For the IC-7851, FTDX3000 (and perhaps others) it means this:
437
438                  1 = TX/RX = ANT1  FTDX3000=ANT1/ANT3
439                  2 = TX/RX = ANT2  FTDX3000=ANT2/ANT3
440                  3 = TX/RX = ANT3  FTDX3000=ANT3
441                  4 = TX/RX = ANT1/ANT4
442                  5 = TX/RX = ANT2/ANT4
443                  6 = TX/RX = ANT3/ANT4
444
445       y, get_ant 'Antenna'
446              Get 'Antenna'
447
448              A value of 0 for Antenna will return the current TX antenna
449
450              > 0 is 1-based antenna# (‘1’, ‘2’, ‘3’, ...).
451
452
453
454              Option returned depends on rig..for Icom is likely the  RX  only
455              flag.
456
457       b, send_morse 'Morse'
458              Send 'Morse' symbols.  For Yaesu rigs use memory#.
459
460       0xbb, stop_morse
461              Stop sending the current morse code.
462
463       0xbc, wait_morse
464              Wait for morse to finish -- only works on full break-in
465
466       0x8b, get_dcd
467              Get 'DCD' (squelch) status: ‘0’ (Closed) or ‘1’ (Open).
468
469       R, set_rptr_shift 'Rptr Shift'
470              Set 'Rptr Shift'.
471
472              Rptr Shift is one of: ‘+’, ‘-’, or something else for ‘None’.
473
474       r, get_rptr_shift
475              Get 'Rptr Shift'.
476
477              Returns ‘+’, ‘-’, or ‘None’.
478
479       O, set_rptr_offs 'Rptr Offset'
480              Set 'Rptr Offset', in Hz.
481
482       o, get_rptr_offs
483              Get 'Rptr Offset', in Hz.
484
485       C, set_ctcss_tone 'CTCSS Tone'
486              Set 'CTCSS Tone', in tenths of Hz.
487
488       c, get_ctcss_tone
489              Get 'CTCSS Tone', in tenths of Hz.
490
491       D, set_dcs_code 'DCS Code'
492              Set 'DCS Code'.
493
494       d, get_dcs_code
495              Get 'DCS Code'.
496
497       0x90, set_ctcss_sql 'CTCSS Sql'
498              Set 'CTCSS Sql' tone, in tenths of Hz.
499
500       0x91, get_ctcss_sql
501              Get 'CTCSS Sql' tone, in tenths of Hz.
502
503       0x92, set_dcs_sql 'DCS Sql'
504              Set 'DCS Sql' code.
505
506       0x93, get_dcs_sql
507              Get 'DCS Sql'
508               code.
509
510       N, set_ts 'Tuning Step'
511              Set 'Tuning Step', in Hz.
512
513       n, get_ts
514              Get 'Tuning Step', in Hz.
515
516       U, set_func 'Func' 'Func Status'
517              Set 'Func' and 'Func Status'.
518
519              Func  is  a  token: ‘FAGC’, ‘NB’, ‘COMP’, ‘VOX’, ‘TONE’, ‘TSQL’,
520              ‘SBKIN’, ‘FBKIN’, ‘ANF’, ‘NR’, ‘AIP’, ‘APF’, ‘MON’, ‘MN’,  ‘RF’,
521              ‘ARO’,  ‘LOCK’, ‘MUTE’, ‘VSC’, ‘REV’, ‘SQL’, ‘ABM’, ‘BC’, ‘MBC’,
522              ‘RIT’, ‘AFC’, ‘SATMODE’, ‘SCOPE’, ‘RESUME’,  ‘TBURST’,  ‘TUNER’,
523              ‘XIT’.
524
525              Func  Status is a non null value for “activate” or “de-activate”
526              otherwise, much as TRUE/FALSE  definitions  in  the  C  language
527              (true is non-zero and false is zero, ‘0’).
528
529              Note:  Passing  a ‘?’ (query) as the first argument instead of a
530              Func token will return a space separated list of  radio  backend
531              supported  set  function tokens.  Use this to determine the sup‐
532              ported functions of a given radio backend.
533
534       u, get_func 'Func'
535              Get 'Func Status'.
536
537              Returns Func Status as a non null value for the Func token given
538              as in set_func above.
539
540              Note:  Passing  a ‘?’ (query) as the first argument instead of a
541              Func token will return a space separated list of  radio  backend
542              supported  get  function tokens.  Use this to determine the sup‐
543              ported functions of a given radio backend.
544
545       L, set_level 'Level' 'Level Value'
546              Set 'Level' and 'Level Value'.
547
548              Level is a  token:  ‘PREAMP’,  ‘ATT’,  ‘VOXDELAY’,  ‘AF’,  ‘RF’,
549              ‘SQL’,  ‘IF’,  ‘APF’, ‘NR’, ‘PBT_IN’, ‘PBT_OUT’, ‘CWPITCH’, ‘RF‐
550              POWER’, ‘MICGAIN’, ‘KEYSPD’, ‘NOTCHF’, ‘COMP’, ‘AGC’,  ‘BKINDL’,
551              ‘BAL’, ‘METER’, ‘VOXGAIN’, ‘ANTIVOX’, ‘SLOPE_LOW’, ‘SLOPE_HIGH’,
552              ‘BKIN_DLYMS’, ‘RAWSTR’, ‘SWR’, ‘ALC’,  ‘STRENGTH’,  ‘RFPOWER_ME‐
553              TER’,  ‘COMPMETER’, ‘VD_METER’, ‘ID_METER’, ‘NOTCHF_RAW’, ‘MONI‐
554              TOR_GAIN’,  ‘NQ’,  ‘RFPOWER_METER_WATTS‘SPECTRUM_SPAN’,   ‘SPEC‐
555              TRUM_EDGE_LOW’,    ‘SPECTRUM_EDGE_HIGH’,   ‘SPECTRUM_SPEED‘SPEC‐
556              TRUM_REF’, (oqSPECTRUM_AVG’, ‘SPECTRUM_ATT‘USB_AF’.
557
558              The Level Value can be a float or an integer value.  For the AGC
559              token  the  value  is  one  of ‘0’ = OFF, ‘1’ = SUPERFAST, ‘2’ =
560              FAST, ‘3’ = SLOW, ‘4’ = USER, ‘5’ = MEDIUM, ‘6’  =  AUTO.   Note
561              that  not all values work on all rigs.  To list usable values do
562              "rigctl -m [modelnum] -u |  grep  AGC  levels"  or  for  Windows
563              "rigctl -m [modelnum] -u | find "AGC levels"".
564
565              Level units
566                  0.0-1.0 where 0=0% and 1.0=100% (except for BAL where 50% is center)
567                      AF, ALC, ANTIVOX, BAL, COMP, MICGAIN, MONITOR_GAIN, NOTCHF_RAW, NR, RF, RFPOWER, RFPOWER_METER, USB_AF, VOXGAIN
568
569                  Amps
570                      ID_METER(A)
571
572                  dB
573                      NL, COMP_METER, PREAMP, ATT, SLOPE_LOW, SLOPE_HIGH, SPECTRUM_REF, SPECTRUM_ATT, STRENGTH
574
575                  Degrees(temperature)
576                      TEMP_METER(C)
577
578                  Hz
579                      CWPITCH, IF, NOTCHF, PBT_IN, PBT_OUT, SPECTRUM_EDGE_LOW, SPECTRUM_EDGE_HIGH, SPECTRUM_SPAN
580
581                  Seconds
582                      VOXDELAY(ds), BKINDL(ms), BKIN_DLYMS(ms)
583
584                  Raw info from rig
585                      RAWSTR, BAND_SELECT (subject to change -- index right now but may convert to band name)
586
587                  SWR
588                      SWR
589
590                  Volts
591                      VD_METER
592
593                  Lookup - if level shows 0/0/0 then it's probably a lookup value
594                      METER RIG_METER_XXXX 1=SWR, 2=COMP, 4=ALC, 8=IC, 16=DB, 32=PO, 64=VDD, 128=Temp
595                      AGC 0=None, 1=SuperFast, 2=Fast, 3=Slow, 4=User, 5=Medium, 6=Auto
596                          Note: Not all AGC values may be available -- see AGC Level in dumpcaps (e.g. rigctl -m 1035 -u | grep AGC)
597                      SPECTRUM_MODE 0=None, 1=Center, 2=Fixed, 3=Center Scroll, 4=Fixed Scroll
598                      SPECTRUM_AVG rig specific
599
600                  Watts
601                      RFPOWER_METER_WATTS
602
603                  WPM
604                      KEYSPD
605
606              Note:  Passing  a ‘?’ (query) as the first argument instead of a
607              Level token will return a space separated list of radio  backend
608              supported set level tokens.  Use this to determine the supported
609              levels of a given radio backend.
610
611       l, get_level 'Level'
612              Get 'Level Value'.
613
614              Returns Level Value as a float or integer for  the  Level  token
615              given as in set_level above.
616
617              Note:  Passing  a ‘?’ (query) as the first argument instead of a
618              Level token will return a space separated list of radio  backend
619              supported get level tokens.  Use this to determine the supported
620              levels of a given radio backend.
621
622       P, set_parm 'Parm' 'Parm Value'
623              Set 'Parm' and 'Parm Value'.
624
625              Parm is a token:  ‘ANN’,  ‘APO’,  ‘BACKLIGHT’,  ‘BEEP’,  ‘TIME’,
626              ‘BAT’, ‘KEYLIGHT’.
627
628              Note:  Passing  a ‘?’ (query) as the first argument instead of a
629              Parm token will return a space separated list of  radio  backend
630              supported  set parameter tokens.  Use this to determine the sup‐
631              ported parameters of a given radio backend.
632
633       p, get_parm 'Parm'
634              Get 'Parm Value'.
635
636              Returns Parm Value as a float or  integer  for  the  Parm  token
637              given as in set_parm above.
638
639              Note:  Passing  a ‘?’ (query) as the first argument instead of a
640              Parm token will return a space separated list of  radio  backend
641              supported  get parameter tokens.  Use this to determine the sup‐
642              ported parameters of a given radio backend.
643
644       B, set_bank 'Bank'
645              Set 'Bank'.
646
647              Sets the current memory bank number.
648
649       E, set_mem 'Memory#'
650              Set 'Memory#' channel number.
651
652       e, get_mem
653              Get 'Memory#' channel number.
654
655       G, vfo_op 'Mem/VFO Op'
656              Perform a 'Mem/VFO Op'.
657
658              Mem/VFO  Operation  is  a  token:  ‘CPY’,  ‘XCHG’,   ‘FROM_VFO’,
659              ‘TO_VFO’,  ‘MCL’,  ‘UP’, ‘DOWN’, ‘BAND_UP’, ‘BAND_DOWN’, ‘LEFT’,
660              ‘RIGHT’, ‘TUNE’, ‘TOGGLE’.
661
662              Note: Passing a ‘?’ (query) as the first argument instead  of  a
663              Mem/VFO  Op  token  will  return a space separated list of radio
664              backend supported Set Mem/VFO Op tokens.  Use this to  determine
665              the supported Mem/VFO Ops of a given radio backend.
666
667       g, scan 'Scan Fct' 'Scan Channel'
668              Perform a 'Scan Fct' on a 'Scan Option'.
669
670              Scan Function is a token: ‘STOP’, ‘MEM’, ‘SLCT’, ‘PRIO’, ‘PROG’,
671              ‘DELTA’, ‘VFO’, ‘PLT’.
672
673              Scan Option is an integer.
674
675              Scan Option for Yaesu rigs 0=STOP, 1=UP, 2=DOWN.
676
677              Scan Option for Icom rigs is a channel number to program with  G
678              otherwise not used.
679
680              Scan Option for Kenwood rigs is not used.
681
682              Note:  Passing  a ‘?’ (query) as the first argument instead of a
683              Scan Fct token will return a space separated list of radio back‐
684              end  supported  Scan Function tokens.  Use this to determine the
685              supported Scan Functions of a given radio backend.
686
687       H, set_channel 'Channel'
688              Set memory 'Channel' data.
689
690              Sets memory channel information
691
692       h, get_channel 'readonly'
693              Get channel memory.
694
695              If readonly!=0 then only channel data is returned  and  rig  re‐
696              mains  on  the  current channel.  If readonly=0 then rig will be
697              set to the channel requested.  data.
698
699       A, set_trn 'Transceive'
700              Set 'Transceive' mode.
701
702              Transcieve is a token: ‘OFF’, ‘RIG’, ‘POLL’.
703
704              Transceive is a mechanism for radios to report events without  a
705              specific call for information.
706
707              Note:  Passing  a ‘?’ (query) as the first argument instead of a
708              Transceive token will return a space  separated  list  of  radio
709              backend supported Transceive mode tokens.  Use this to determine
710              the supported Transceive modes of a given radio backend.
711
712       a, get_trn
713              Get 'Transceive' mode.
714
715              Transceive mode (reporting event) as in set_trn above.
716
717       *, reset 'Reset'
718              Perform rig 'Reset'.
719
720              Reset is a value: ‘0’ = None, ‘1’ = Software reset,  ‘2’  =  VFO
721              reset, ‘4’ = Memory Clear reset, ‘8’ = Master reset.
722
723              Since  these  values  are  defined  as a bitmask in include/ham‐
724              lib/rig.h, it should be possible to AND these values together to
725              do  multiple  resets at once, if the backend supports it or sup‐
726              ports a reset action via rig control at all.
727
728       0x87, set_powerstat 'Power Status'
729              Set 'Power Status'.
730
731              Power Status is a value: ‘0’ = Power Off, ‘1’ = Power On, ‘2’  =
732              Power  Standby  (enter  standby),  ‘4’  =  Power  Operate (leave
733              standby).
734
735       0x88, get_powerstat
736              Get 'Power Status' as in set_powerstat above.
737
738       0x89, send_dtmf 'Digits'
739              Set DTMF 'Digits'.
740
741       0x8a, recv_dtmf
742              Get DTMF 'Digits'.
743
744       _, get_info
745              Get misc information about the rig.
746
747       0xf5, get_rig_info
748              Get misc information about the rig vfo status and other info.
749
750       0xf3, get_vfo_info 'VFO'
751              Get misc information about a specific vfo.
752
753       dump_state
754              Return certain state information about the radio backend.
755
756       1, dump_caps
757              Not a real rig remote command, it just dumps capabilities,  i.e.
758              what the backend knows about this model, and what it can do.
759
760              TODO:  Ensure  this  is in a consistent format so it can be read
761              into a hash, dictionary, etc.  Bug reports requested.
762
763              Note: This command will produce many lines of output so be  very
764              careful  if  using  a  fixed length array!  For example, running
765              this command against the Dummy backend results in  over  5kB  of
766              text output.
767
768              VFO parameter not used in 'VFO mode'.
769
770       2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
771              Returns 'Power mW'.
772
773              Converts  a  Power  value  in  a  range of 0.0...1.0 to the real
774              transmit power in milli-Watts (integer).
775
776              'Frequency' and 'Mode' also need to be provided as output  power
777              may vary according to these values.
778
779              VFO parameter is not used in VFO mode.
780
781       4, mW2power 'Power mW' 'Frequency' 'Mode'
782              Returns 'Power [0.0..1.0]'.
783
784              Converts  the  real transmit power in milli-Watts (integer) to a
785              Power value in a range of 0.0 ... 1.0.
786
787              'Frequency' and 'Mode' also need to be provided as output  power
788              may vary according to these values.
789
790              VFO parameter is not used in VFO mode.
791
792       w, send_cmd 'Cmd'
793              Send a raw command string to the radio.
794
795              This  is  useful  for testing and troubleshooting radio commands
796              and responses when developing a backend.
797
798              For binary protocols enter values as \0xAA\0xBB.  Expect a  'Re‐
799              ply'  from  the  radio which will likely be a binary block or an
800              ASCII string depending on the radio's protocol (see your radio's
801              computer control documentation).
802
803              The  command  terminator, set by the send-cmd-term option above,
804              will terminate each command string  sent  to  the  radio.   This
805              character should not be a part of the input string.
806
807       W, send_cmd_rx 'Cmd' [nbytesorterminatorchar
808              Send  a  raw  command  string to the radio and expect nbytes re‐
809              turned or the terminator char (e.g. ;).
810
811              This is useful for testing and  troubleshooting  radio  commands
812              and  responses when developing a backend.  If the # of bytes re‐
813              quested is <= the number actually returned no timeout  will  oc‐
814              cur.
815
816              The  command argument can have no spaces in it.  For binary pro‐
817              tocols enter values as \0xAA\0xBB.  Expect a  'Reply'  from  the
818              radio which will likely be a binary block or an ASCII string de‐
819              pending on the radio's protocol (see your radio's computer  con‐
820              trol documentation).
821
822              The  command  terminator, set by the send-cmd-term option above,
823              will terminate each command string  sent  to  the  radio.   This
824              character should not be a part of the input string.
825
826       set_clock 'DateTime'
827              Set 'DateTime'
828
829              Sets  rig  clock -- note that some rigs do not handle seconds or
830              milliseconds.  If you try to set sec/msec and rig does not  sup‐
831              port  it  you  will  get  a  debug  warning  message.  Format is
832              ISO8601,
833              Formats accepted allow for 2-digit or 4-digit time zone
834              YYYY-MM-DDTHH:MM:SS.SSS+ZZ (where +ZZ is either -/+ UTC offset HH)
835              YYYY-MM-DDTHH:MM:SS.SSS+ZZZZ (where +ZZZZ is either -/+ UTC offset HHMM)
836              YYYY-MM-DDTHH:MM:SS+ZZ
837              YYYY-MM-DDTHH:MM:SS+ZZZZ
838              YYYY-MM-DDTHH:MM+ZZ
839              YYYY-MM-DDTHH:MM+ZZZZ
840              YYYY-MM-DD (sets date only)
841              Note: Icom rigs expect you to set local time and the hours off to UTC.
842              So...4PM EST example would be 2021-12-01T16:00:00+0500
843              But...if you want to display GMT you must set the clock for GMT with zero UTC offset.
844              Hopefully Icom will allow displaying either clock in the future
845
846
847       get_clock
848              Get 'RigTime'
849
850              Gets rig clock -- note that some rigs do not handle  seconds  or
851              milliseconds.    Format  is  ISO8601  YYYY-MM-DDTHH:MM:SS.sss+ZZ
852              where +ZZ is either -/+ UTC offset
853
854       chk_vfo
855              Get 'Status'
856
857              Returns Status as 1 if vfo option is on and 0 if vfo  option  is
858              off.  This command reflects the -o switch for rigctl and ritctld
859              and can be dynamically changed by set_vfo_opt.
860
861       set_vfo_opt 'Status'
862              Set 'Status'
863
864              Set vfo option Status 1=on or 0=off This is the  same  as  using
865              the  -o  switch  for rigctl and ritctld.  This can be dyamically
866              changed while running.
867
868       get_separator
869              Get 'SeparatorChar'
870
871              Shows the current SeparatorChar
872
873       set_separator 'SeparatorChar'
874              Set 'SeparatorChar'
875
876              Change rigctld response to use a special char instead of newline
877              (recommend  #).   This  can be dyamically changed while running.
878              Handy for node-red's tcprequest node.  This  can  be  dyamically
879              changed while running.
880
881       pause 'Seconds'
882              Pause  for  the given whole (integer) number of 'Seconds' before
883              sending the next command to the radio.
884
885       password 'Password'
886              Sends password to rigctld when rigctld has been secured with -A.
887              Must use the 32-char shared secret from rigctld.
888
889       set_lock_mode 'Locked'
890              Turns  mode  lock  on(1)  or  off(0)  (only when using rigctld).
891              Turning on will prevent all clients from changing the rig  mode.
892              For example this is useful when running CW Skimmer in FM mode on
893              an IC-7300.  Clicking spots  in  a  spotting  program  will  not
894              change the VFOA mode when lock is on.  So "set_lock_mode 1" when
895              CW Skimmer is started and "set_lock_mode 0" when CW  Skimmer  is
896              stopped.
897
898       get_lock_mode
899              Returns  current  lock mode status 1=On, 2=Off (only useful when
900              using rigctld)
901
902       send_raw 'Terminator' 'String'
903              Can send ASCII string or 0xnn values -- there can be no spaces in the command string.
904              Possible terminator values are CR, LF, ;, ICOM, 0-100 (bytes to read), or -1 meaning unknown (will timeout on read)
905              Examples:
906                send_raw ; FA;MD;
907                send_raw icom 0xFE;0xFE;0x94;0x03;0xFD
908                send_raw -1 0xFE;0xFE;0x94;0x03;0xFD
909                send_raw 14 0xFE;0xFE;0x94;0x03;0xFD
910

READLINE

912       If Readline library development files  are  found  at  configure  time,
913       rigctl will be conditonally built with Readline support for command and
914       argument entry.  Readline command key bindings are at their defaults as
915       described           in           the           Readline          manual
916https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩.      rigctl
917       sets the name “rigctl” which can be used in Conditional Init Constructs
918       in the Readline Init File ($HOME/.inputrc by default) for  custom  key‐
919       bindings unique to rigctl.
920
921       Command  history is available with Readline support as described in the
922       Readline                         History                         manual
923https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩.  Command
924       and argument strings are stored as single lines even when arguments are
925       prompted  for input individually.  Commands and arguments are not vali‐
926       dated and are stored as typed with values separated by a single space.
927
928       Normally session history is not saved, however, use of  either  of  the
929       -i/--read-history  or  -I/--save-history  options  when starting rigctl
930       will cause any previously saved history to be read in and/or  the  cur‐
931       rent  and  any previous session history (assuming the -i and -I options
932       are given together) will be written out when rigctl  is  closed.   Each
933       option is mutually exclusive, i.e. either may be given separately or in
934       combination.  This is useful to save a set of commands  and  then  read
935       them  later  but not write the modified history for a consistent set of
936       test commands in interactive mode, for example.
937
938       History is stored in $HOME/.rigctl_history by default although the des‐
939       tination  directory may be changed by setting the RIGCTL_HIST_DIR envi‐
940       ronment variable.  When RIGCTL_HIST_DIR is unset, the value of the HOME
941       environment  variable  is used instead.  Only the destination directory
942       may be changed at this time.
943
944       If Readline support is not found at configure time the original  inter‐
945       nal  command handler is used.  Readline is not used for rigctl commands
946       entered on the command line regardless if Readline support is built  in
947       or not.
948
949       Note:  Readline  support is not included in the MS Windows 32 or 64 bit
950       binary builds supplied by the Hamlib Project.  Running rigctl on the MS
951       Windows platform in the ‘cmd’ shell does give session command line his‐
952       tory, however, it is not saved to disk between sessions.
953

DIAGNOSTICS

955       The -v, --verbose option allows different levels of diagnostics  to  be
956       output  to  stderr  and correspond to -v for BUG, -vv for ERR, -vvv for
957       WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
958
959       A given verbose level is useful for providing needed debugging informa‐
960       tion  to  the email address below.  For example, TRACE output shows all
961       of the values sent to and received from the radio which is very  useful
962       for  radio  backend library development and may be requested by the de‐
963       velopers.
964

EXIT STATUS

966       rigctl exits with:
967
968       0      if all operations completed normally;
969
970       1      if there was an invalid command line option or argument;
971
972       2      if an error was returned by Hamlib.
973

EXAMPLES

975       Start rigctl for a Yaesu FT-920 using a USB to serial adapter on  Linux
976       in interactive mode:
977
978           $ rigctl -m 1014 -r /dev/ttyUSB1
979
980       Start rigctl for a Yaesu FT-920 using COM1 on MS Windows while generat‐
981       ing TRACE output to stderr:
982
983           > rigctl -m 1014 -r COM1 -vvvvv
984
985       Start rigctl for a Yaesu FT-920 using a USB  to  serial  adapter  while
986       setting baud rate and stop bits:
987
988           $ rigctl -m 1014 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2
989
990       Start  rigctl  for  an  Elecraft K3 using a USB to serial adapter while
991       specifying a command terminator for the w command:
992
993           $ rigctl -m 2029 -r /dev/ttyUSB0 -t';'
994
995       Connect to a running rigctld with radio model 2 (“NET rigctl”)  on  the
996       local host and specifying the TCP port, setting frequency and mode:
997
998           $ rigctl -m 2 -r localhost:4532 F 7253500 M LSB 0
999

BUGS

1001       set_chan has no entry method as of yet, hence left unimplemented.
1002
1003       This almost empty section...
1004
1005       Report bugs to:
1006
1007              Hamlib Developer mailing list
1008              ⟨hamlib-developer@lists.sourceforge.net⟩
1009

COPYING

1011       This  file  is part of Hamlib, a project to develop a library that sim‐
1012       plifies radio, rotator, and amplifier control functions for  developers
1013       of  software  primarily  of interest to radio amateurs and those inter‐
1014       ested in radio communications.
1015
1016       Copyright © 2000-2011 Stephane Fillod
1017       Copyright © 2000-2018 the Hamlib Group (various contributors)
1018       Copyright © 2010-2020 Nate Bargmann
1019
1020       This is free software; see the file  COPYING  for  copying  conditions.
1021       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
1022       PARTICULAR PURPOSE.
1023

SEE ALSO

1025       less(1), more(1), rigctld(1), hamlib(7)
1026

COLOPHON

1028       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
1029       snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
1030
1031
1032
1033Hamlib                            2020-09-09                         RIGCTL(1)
Impressum