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

NAME

6       ampctl - control radio amplifiers
7

SYNOPSIS

9       ampctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
10              [-v[-Z]] [command|-]
11

DESCRIPTION

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

OPTIONS

26       This program follows the usual GNU command line syntax.  Short  options
27       that take an argument may have the value follow immediately or be sepa‐
28       rated by a space.  Long options starting with two dashes (‘-’)  require
29       an ‘=’ between the option and any argument.
30
31       Here is a summary of the supported options:
32
33       -m, --model=id
34              Select amplifier model number.
35
36              See model list (use “ampctl -l”).
37
38              Note:  ampctl (or third party software using the C API) will use
39              amplifier model 2 for NET ampctl (communicating with ampctld).
40
41       -r, --amp-file=device
42              Use device as the file name of the port connected to the  ampli‐
43              fier.
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       -s, --serial-speed=baud
51              Set serial speed to baud rate.
52
53              Uses maximum serial speed from  amplifier  backend  capabilities
54              (set by -m above) as the default.
55
56       -t, --send-cmd-term=char
57              Change  the  termination  char  for text protocol when using the
58              send_cmd command.
59
60              The default value is  ASCII  CR  (‘0x0D’).   ASCII  non-printing
61              characters  can be given as the ASCII number in hexadecimal for‐
62              mat prepended with “0x”.  You may pass an empty  string  for  no
63              termination  char.   The  string  “-1” tells ampctl to switch to
64              binary protocol.
65
66              For example, to specify a command terminator for  Kenwood  style
67              text commands pass “-t ';'” to ampctl.  See EXAMPLE below.
68
69       -L, --show-conf
70              List  all  config  parameters  for the amplifier defined with -m
71              above.
72
73       -C, --set-conf=parm=val[,parm=val]
74              Set amplifier configuration parameter(s), e.g.  stop_bits=2.
75
76              Use the -L option above for a list of  configuration  parameters
77              for a given model number.
78
79       -u, --dump-caps
80              Dump  capabilities  for  the amplifier defined with -m above and
81              exit.
82
83       -l, --list
84              List all amplifier model numbers defined in Hamlib and exit.
85
86              The list is sorted by model number.
87
88              Note: In Linux the  list  can  be  scrolled  back  using  Shift-
89              PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
90              minal in X or the cmd window in  Windows.   The  output  can  be
91              piped to more(1) or less(1), e.g. “ampctl -l | more”.
92
93       -i, --read-history
94              Read  previously  saved command and argument history from a file
95              (default $HOME/.ampctl_history) for the current session.
96
97              Available when ampctl is built with Readline support (see  READ‐
98              LINE below).
99
100              Note:  To  read  a history file stored in another directory, set
101              the     AMPCTL_HIST_DIR     environment      variable,      e.g.
102              “AMPCTL_HIST_DIR=~/tmp  ampctl -i”.  When AMPCTL_HIST_DIR is not
103              set, the value of HOME is used.
104
105       -I, --save-history
106              Write current session (and previous session(s), if -i option  is
107              given)   command   and  argument  history  to  a  file  (default
108              $HOME/.ampctl_history) at the end of the current session.
109
110              Complete commands with arguments are saved as a single  line  to
111              be  recalled and used or edited.  Available when ampctl is built
112              with Readline support (see READLINE below).
113
114              Note: To write a history file  in  another  directory,  set  the
115              AMPCTL_HIST_DIR         environment        variable,        e.g.
116              “AMPCTL_HIST_DIR=~/tmp ampctl -IRq.  When AMPCTL_HIST_DIR is not
117              set, the value of HOME is used.
118
119       -v, --verbose
120              Set verbose mode, cumulative (see DIAGNOSTICS below).
121
122       -Z, --debug-time-stamps
123              Enable time stamps for the debug messages.
124
125              Use  only  in  combination with the -v option as it generates no
126              output on its own.
127
128       -h, --help
129              Show a summary of these options and exit.
130
131       -V, --version
132              Show version of ampctl and exit.
133
134       -      Stop option processing and read commands from standard input.
135
136              See Standard Input below.
137
138       Note: Some options may not be implemented by a given backend  and  will
139       return  an error.  This is most likely to occur with the --set-conf and
140       --show-conf options.
141
142       Please note that the backend for the amplifier to be controlled, or the
143       amplifier  itself  may  not  support  some commands.  In that case, the
144       operation will fail with a Hamlib error code.
145

COMMANDS

147       Commands can be entered either as a single char, or as a  long  command
148       name.   The  commands  are not prefixed with a dash as the options are.
149       They may be typed in when in interactive  mode  or  provided  as  argu‐
150       ment(s)  in  command line interface mode.  In interactive mode commands
151       and their arguments may be entered on a single line:
152
153           F 14250000
154
155       Since most of the Hamlib operations have a set and  a  get  method,  an
156       upper  case letter will often be used for a set method whereas the cor‐
157       responding lower case letter refers to the get method.  Each  operation
158       also has a long name; in interactive mode, prepend a backslash, ‘\’, to
159       enter a long command name.
160
161       Example: Use “\dump_caps” to see what capabilities this  amplifier  and
162       backend support.
163
164              Note:  The  backend  for  the amplifier to be controlled, or the
165              amplifier itself may not support some commands.  In  that  case,
166              the operation will fail with a Hamlib error message.
167
168       A  simple  example  using commands saved to a file (typed text shown in
169       bold):
170
171           $ cat <<.EOF. >cmds.txt
172           > # File of commands
173           > F 14250000
174           > f
175           > l PWRINPUT
176           > l PWRFORWARD
177           > l SWR
178           > \dump_caps
179           > .EOF.
180
181           $ ampctl -m1 - <cmds.txt
182
183           Amplifier command: # File of commands
184
185           Amplifier command: F 14250000
186
187           Amplifier command: f
188           Frequency(Hz): 14250000
189
190           Amplifier command: l PWRINPUT
191           Level Value: 0
192
193           Amplifier command: l PWRFORWARD
194           Level Value: 1499
195
196           Amplifier command: l SWR
197           Level Value: 1.000000
198
199           Amplifier command: \dump_caps
200           Caps dump for model:    1
201           Model name:             Dummy
202           Mfg name:               Hamlib
203           Backend version:        0.1
204           Backend copyright:      LGPL
205           Backend status:         Alpha
206           Amp type:               Other
207           Port type:              None
208           Write delay:            0mS, timeout 0mS, 0 retries
209           Post Write delay:       0mS
210           Has priv data:          N
211           Get level: SWR NH PF PWRINPUT PWRFORWARD PWRREFLECTED PWRPEAK FAULT
212           Has Init:               Y
213           Has Cleanup:            Y
214           Has Open:               Y
215           Has Close:              Y
216           Can set Conf:           N
217           Can get Conf:           N
218           Can Reset:              Y
219           Can get Info:           Y
220
221           Overall backend warnings: 0
222
223           Amplifier command:
224
225           $
226
227   ampctl Commands
228       A summary of commands is included below (In the case  of  set  commands
229       the  quoted  italicized string is replaced by the value in the descrip‐
230       tion.  In the case of get commands the quoted italicized string is  the
231       key name of the value returned.):
232
233       Q|q, exit ampctl
234              Exit ampctl in interactive mode.
235
236              When  ampctl  is  controlling the amplifier directly, will close
237              the amplifier backend and port.  When  ampctl  is  connected  to
238              ampctld (amplifier model 2), the TCP/IP connection to ampctld is
239              closed and ampctld remains running, available for another TCP/IP
240              network connection.
241
242       F, set_freq 'Frequency'
243              Set 'Frequency', in Hz.
244
245              Frequency may be a floating point or integer value.
246
247       f, get_freq
248              Get 'Frequency', in Hz.
249
250              Returns an integer value.
251
252       l, get_level 'Level'
253              Get 'Level Value'.
254
255              Returns  Level  Value  as a float or integer for the Level token
256              given.
257
258              Note: Passing a ‘?’ (query) as the first argument instead  of  a
259              Level  token  will  return  a  space separated list of amplifier
260              backend supported get level tokens.  Use this to  determine  the
261              supported levels of a given amplifier backend.
262
263       w, send_cmd 'Cmd'
264              Send a raw command string to the amplifier.
265
266              This  is  useful  for testing and troubleshooting amplifier com‐
267              mands and responses when developing a backend.
268
269              For binary protocols  enter  values  as  \0xAA\0xBB.   Expect  a
270              'Reply'  from  the amplifier which will likely be a binary block
271              or an ASCII string depending on the  amplifier's  protocol  (see
272              your amplifier's computer control documentation).
273
274              The  command  terminator, set by the send-cmd-term option above,
275              will terminate each command string sent to the amplifier.   This
276              character should not be a part of the input string.
277
278       dump_state
279              Return certain state information about the amplifier backend.
280
281       1, dump_caps
282              Not a real amplifier remote command, it just dumps capabilities,
283              i.e. what the backend knows about this model, and  what  it  can
284              do.
285
286              TODO:  Ensure  this  is in a consistent format so it can be read
287              into a hash, dictionary, etc.  Bug reports requested.
288
289              Note: This command will produce many lines of output so be  very
290              careful  if  using  a  fixed length array!  For example, running
291              this command against the Dummy backend results in  a  number  of
292              lines of text output.
293
294       _, get_info
295              Return information from the amplifier backend.
296
297       R, reset 'Reset'
298              Perform amplifier 'Reset'.
299
300              Reset is an integer value: ‘0’ = None, ‘1’ = Memory reset, ‘2’ =
301              Fault reset, ‘3’ = Amplifier reset.
302
303       set_powerstat 'Power Status'
304              Set 'Power Status'.
305
306              Power Status is an integer value: ‘0’ = Power Off, ‘1’  =  Power
307              On,  ‘2’  =  Power  Standby (enter standby), ‘4’ = Power Operate
308              (leave standby).
309
310       get_powerstat
311              Get 'Power Status' as in set_powerstat above.
312

READLINE

314       If Readline library development files  are  found  at  configure  time,
315       ampctl will be conditonally built with Readline support for command and
316       argument entry.  Readline command key bindings are at their defaults as
317       described           in           the           Readline          manual
318https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩.      ampctl
319       sets the name “ampctl” which can be used in Conditional Init Constructs
320       in the Readline Init File ($HOME/.inputrc by default) for  custom  key‐
321       bindings unique to ampctl.
322
323       Command  history is available with Readline support as described in the
324       Readline                         History                         manual
325https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩.  Command
326       and argument strings are stored as single lines even when arguments are
327       prompted  for input individually.  Commands and arguments are not vali‐
328       dated and are stored as typed with values separated by a single space.
329
330       Normally session history is not saved, however, use of  either  of  the
331       -i/--read-history  or  -I/--save-history  options  when starting ampctl
332       will cause any previously saved history to be read in and/or  the  cur‐
333       rent  and  any previous session history (assuming the -i and -I options
334       are given together) will be written out when ampctl  is  closed.   Each
335       option is mutually exclusive, i.e. either may be given separately or in
336       combination.  This is useful to save a set of commands  and  then  read
337       them  later  but not write the modified history for a consistent set of
338       test commands in interactive mode, for example.
339
340       History is stored in $HOME/.ampctl_history by default although the des‐
341       tination  directory may be changed by setting the AMPCTL_HIST_DIR envi‐
342       ronment variable.  When AMPCTL_HIST_DIR is unset, the value of the HOME
343       environment  variable  is used instead.  Only the destination directory
344       may be changed at this time.
345
346       If Readline support is not found at configure time the original  inter‐
347       nal  command handler is used.  Readline is not used for ampctl commands
348       entered on the command line regardless if Readline support is built  in
349       or not.
350
351       Note:  Readline  support is not included in the MS Windows 32 or 64 bit
352       binary builds supplied by the Hamlib Project.  Running ampctl on the MS
353       Windows platform in the ‘cmd’ shell does give session command line his‐
354       tory, however, it is not saved to disk between sessions.
355

DIAGNOSTICS

357       The -v, --verbose option allows different levels of diagnostics  to  be
358       output  to  stderr  and correspond to -v for BUG, -vv for ERR, -vvv for
359       WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
360
361       A given verbose level is useful for providing needed debugging informa‐
362       tion  to  the email address below.  For example, TRACE output shows all
363       of the values sent to and received from the  amplifier  which  is  very
364       useful  for  amplifier backend library development and may be requested
365       by the developers.
366

EXIT STATUS

368       ampctl exits with:
369
370       0      if all operations completed normally;
371
372       1      if there was an invalid command line option or argument;
373
374       2      if an error was returned by Hamlib.
375

EXAMPLES

377       Start ampctl for am Elecraft KPA-1500 using a USB to serial adapter  on
378       Linux in interactive mode:
379
380           $ ampctl -m 201 -r /dev/ttyUSB1
381
382       Start  ampctl  for  an Elecraft KPA-1500 using COM1 on MS Windows while
383       generating TRACE output to stderr:
384
385           > ampctl -m 201 -r COM1 -vvvvv
386
387       Connect to a running ampctld with amplifier model 2 (“NET  ampctl”)  on
388       the local host and specifying the TCP port, setting frequency and mode:
389
390           $ ampctl -m 2 -r localhost:4531 F 7253500
391

BUGS

393       This almost empty section...
394
395       Report bugs to:
396
397              Hamlib Developer mailing list
398              ⟨hamlib-developer@lists.sourceforge.net⟩
399

COPYING

401       This  file  is part of Hamlib, a project to develop a library that sim‐
402       plifies radio, rotator, and amplifier control functions for  developers
403       of  software  primarily  of interest to radio amateurs and those inter‐
404       ested in radio communications.
405
406       Copyright © 2000-2011 Stephane Fillod
407       Copyright © 2000-2018 the Hamlib Group (various contributors)
408       Copyright © 2010-2020 Nate Bargmann
409
410       This is free software; see the file  COPYING  for  copying  conditions.
411       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
412       PARTICULAR PURPOSE.
413

SEE ALSO

415       less(1), more(1), ampctld(1), hamlib(7)
416

COLOPHON

418       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
419       snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
420
421
422
423Hamlib                            2020-09-08                         AMPCTL(1)
Impressum