1AMPCTL(1) Hamlib Utilities AMPCTL(1)
2
6 ampctl - control radio amplifiers
7
9 ampctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
10 [-v[-Z]] [command|-]
11
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 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 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
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 Here is a summary of the supported options:
32 -m, --model=id
34 Select amplifier model number.
35 See model list (use “ampctl -l”).
37 Note: ampctl (or third party software using the C API) will use
39 amplifier model 2 for NET ampctl (communicating with ampctld).
40 -r, --amp-file=device
42 Use device as the file name of the port connected to the ampli‐
43 fier.
44 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 -s, --serial-speed=baud
51 Set serial speed to baud rate.
52 Uses maximum serial speed from amplifier backend capabilities
54 (set by -m above) as the default.
55 -t, --send-cmd-term=char
57 Change the termination char for text protocol when using the
58 send_cmd command.
59 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 For example, to specify a command terminator for Kenwood style
67 text commands pass “-t ';'” to ampctl. See EXAMPLE below.
68 -L, --show-conf
70 List all config parameters for the amplifier defined with -m
71 above.
72 -C, --set-conf=parm=val[,parm=val]
74 Set amplifier configuration parameter(s), e.g. stop_bits=2.
75 Use the -L option above for a list of configuration parameters
77 for a given model number.
78 -u, --dump-caps
80 Dump capabilities for the amplifier defined with -m above and
81 exit.
82 -l, --list
84 List all amplifier model numbers defined in Hamlib and exit.
85 The list is sorted by model number.
87 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 -i, --read-history
94 Read previously saved command and argument history from a file
95 (default $HOME/.ampctl_history) for the current session.
96 Available when ampctl is built with Readline support (see READ‐
98 LINE below).
99 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 -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 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 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 -v, --verbose
120 Set verbose mode, cumulative (see DIAGNOSTICS below).
121 -Z, --debug-time-stamps
123 Enable time stamps for the debug messages.
124 Use only in combination with the -v option as it generates no
126 output on its own.
127 -h, --help
129 Show a summary of these options and exit.
130 -V, --version
132 Show version of ampctl and exit.
133 - Stop option processing and read commands from standard input.
135 See Standard Input below.
137 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 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
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 F 14250000
154 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 Example: Use “\dump_caps” to see what capabilities this amplifier and
162 backend support.
163 Note: The backend for the amplifier to be controlled, or the amplifier
165 itself may not support some commands. In that case, the operation will
166 fail with a Hamlib error message.
167 A simple example:
169 $ cat <<.EOF. >cmds.txt
171 > # File of commands
172 > F 14250000
173 > f
174 > l PWRINPUT
175 > l PWRFORWARD
176 > l SWR
177 > \dump_caps
178 > .EOF.
179 $ ampctl -m1 - <cmds.txt
181 Amplifier command: # File of commands
183 Amplifier command: F 14250000
185 Amplifier command: f
187 Frequency(Hz): 14250000
188 Amplifier command: l PWRINPUT
190 Level Value: 0
191 Amplifier command: l PWRFORWARD
193 Level Value: 1499
194 Amplifier command: l SWR
196 Level Value: 1.000000
197 Amplifier command: \dump_caps
199 Caps dump for model: 1
200 Model name: Dummy
201 Mfg name: Hamlib
202 Backend version: 0.1
203 Backend copyright: LGPL
204 Backend status: Alpha
205 Amp type: Other
206 Port type: None
207 Write delay: 0mS, timeout 0mS, 0 retries
208 Post Write delay: 0mS
209 Has priv data: N
210 Get level: SWR NH PF PWRINPUT PWRFORWARD PWRREFLECTED PWRPEAK FAULT
211 Has Init: Y
212 Has Cleanup: Y
213 Has Open: Y
214 Has Close: Y
215 Can set Conf: N
216 Can get Conf: N
217 Can Reset: Y
218 Can get Info: Y
219 Overall backend warnings: 0
221 Amplifier command:
223 $
225 ampctl Commands
227 A summary of commands is included below (In the case of set commands
228 the quoted italicized string is replaced by the value in the descrip‐
229 tion. In the case of get commands the quoted italicized string is the
230 key name of the value returned.):
231 Q|q, exit ampctl
233 Exit ampctl in interactive mode.
234 When ampctl is controlling the amplifier directly, will close
236 the amplifier backend and port. When ampctl is connected to
237 ampctld (amplifier model 2), the TCP/IP connection to ampctld is
238 closed and ampctld remains running, available for another TCP/IP
239 network connection.
240 F, set_freq 'Frequency'
242 Set 'Frequency', in Hz.
243 Frequency may be a floating point or integer value.
245 f, get_freq
247 Get 'Frequency', in Hz.
248 Returns an integer value.
250 l, get_level 'Level'
252 Get 'Level Value'.
253 Returns Level Value as a float or integer for the Level token
255 given.
256 Note: Passing a ‘?’ (query) as the first argument instead of a
258 Level token will return a space separated list of amplifier
259 backend supported get level tokens. Use this to determine the
260 supported levels of a given amplifier backend.
261 w, send_cmd 'Cmd'
263 Send a raw command string to the amplifier.
264 This is useful for testing and troubleshooting amplifier com‐
266 mands and responses when developing a backend.
267 For binary protocols enter values as \0xAA\0xBB. Expect a
269 'Reply' from the amplifier which will likely be a binary block
270 or an ASCII string depending on the amplifier's protocol (see
271 your amplifier's computer control documentation).
272 The command terminator, set by the send-cmd-term option above,
274 will terminate each command string sent to the amplifier. This
275 character should not be a part of the input string.
276 dump_state
278 Return certain state information about the amplifier backend.
279 1, dump_caps
281 Not a real amplifier remote command, it just dumps capabilities,
282 i.e. what the backend knows about this model, and what it can
283 do.
284 TODO: Ensure this is in a consistent format so it can be read
286 into a hash, dictionary, etc. Bug reports requested.
287 Note: This command will produce many lines of output so be very
289 careful if using a fixed length array! For example, running
290 this command against the Dummy backend results in a number of
291 lines of text output.
292 _, get_info
294 Return information from the amplifier backend.
295 R, reset 'Reset'
297 Perform amplifier 'Reset'.
298 Reset is an integer value: ‘0’ = None, ‘1’ = Memory reset, ‘2’ =
300 Fault reset, ‘3’ = Amplifier reset.
301 set_powerstat 'Power Status'
303 Set 'Power Status'.
304 Power Status is an integer value: ‘0’ = Power Off, ‘1’ = Power
306 On, ‘2’ = Power Standby (enter standby), ‘4’ = Power Operate
307 (leave standby).
308 get_powerstat
310 Get 'Power Status' as in set_powerstat above.
311
313 If Readline library development files are found at configure time,
314 ampctl will be conditonally built with Readline support for command and
315 argument entry. Readline command key bindings are at their defaults as
316 described in the Readline manual
317 ⟨https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩. ampctl
318 sets the name “ampctl” which can be used in Conditional Init Constructs
319 in the Readline Init File ($HOME/.inputrc by default) for custom key‐
320 bindings unique to ampctl.
321 Command history is available with Readline support as described in the
323 Readline History manual
324 ⟨https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩. Command
325 and argument strings are stored as single lines even when arguments are
326 prompted for input individually. Commands and arguments are not vali‐
327 dated and are stored as typed with values separated by a single space.
328 Normally session history is not saved, however, use of either of the
330 -i/--read-history or -I/--save-history options when starting ampctl
331 will cause any previously saved history to be read in and/or the cur‐
332 rent and any previous session history (assuming the -i and -I options
333 are given together) will be written out when ampctl is closed. Each
334 option is mutually exclusive, i.e. either may be given separately or in
335 combination. This is useful to save a set of commands and then read
336 them later but not write the modified history for a consistent set of
337 test commands in interactive mode, for example.
338 History is stored in $HOME/.ampctl_history by default although the des‐
340 tination directory may be changed by setting the AMPCTL_HIST_DIR envi‐
341 ronment variable. When AMPCTL_HIST_DIR is unset, the value of the HOME
342 environment variable is used instead. Only the destination directory
343 may be changed at this time.
344 If Readline support is not found at configure time the original inter‐
346 nal command handler is used. Readline is not used for ampctl commands
347 entered on the command line regardless if Readline support is built in
348 or not.
349 Note: Readline support is not included in the MS Windows 32 or 64 bit
351 binary builds supplied by the Hamlib Project. Running ampctl on the MS
352 Windows platform in the ‘cmd’ shell does give session command line his‐
353 tory, however, it is not saved to disk between sessions.
354
356 The -v, --verbose option allows different levels of diagnostics to be
357 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
358 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
359 A given verbose level is useful for providing needed debugging informa‐
361 tion to the email address below. For example, TRACE output shows all
362 of the values sent to and received from the amplifier which is very
363 useful for amplifier backend library development and may be requested
364 by the developers.
365
367 ampctl exits with:
368 0 if all operations completed normally;
370 1 if there was an invalid command line option or argument;
372 2 if an error was returned by Hamlib.
374
376 Start ampctl for am Elecraft KPA-1500 using a USB to serial adapter on
377 Linux in interactive mode:
378 $ ampctl -m 201 -r /dev/ttyUSB1
380 Start ampctl for an Elecraft KPA-1500 using COM1 on MS Windows while
382 generating TRACE output to stderr:
383 > ampctl -m 201 -r COM1 -vvvvv
385 Connect to a running ampctld with amplifier model 2 (“NET ampctl”) on
387 the local host and specifying the TCP port, setting frequency and mode:
388 $ ampctl -m 2 -r localhost:4531 F 7253500
390
392 This almost empty section...
393 Report bugs to:
395 Hamlib Developer mailing list
397 ⟨hamlib-developer@lists.sourceforge.net⟩
398
400 This file is part of Hamlib, a project to develop a library that sim‐
401 plifies radio, rotator, and amplifier control functions for developers
402 of software primarily of interest to radio amateurs and those inter‐
403 ested in radio communications.
404 Copyright © 2000-2011 Stephane Fillod
406 Copyright © 2000-2018 the Hamlib Group (various contributors)
407 Copyright © 2010-2019 Nate Bargmann
408 This is free software; see the file COPYING for copying conditions.
410 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
411 PARTICULAR PURPOSE.
412
414 less(1), more(1), ampctld(1), hamlib(7)
415
417 Links to the Hamlib Wiki, Git repository, release archives, and daily
418 snapshot archives:
419 hamlib.org ⟨http://www.hamlib.org⟩.
421Hamlib 2019-12-10 AMPCTL(1)