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 bi‐
64 nary 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. “AM‐
102 PCTL_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 AM‐
115 PCTL_HIST_DIR environment variable, e.g. “AMPCTL_HIST_DIR=~/tmp
116 ampctl -IRq. When AMPCTL_HIST_DIR is not set, the value of HOME
117 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 op‐
144 eration 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 up‐
156 per case letter will often be used for a set method whereas the corre‐
157 sponding 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 am‐
165 plifier itself may not support some commands. In that case, the
166 operation will fail with a Hamlib error message.
167 A simple example using commands saved to a file (typed text shown in
169 bold):
170 $ 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 $ ampctl -m1 - <cmds.txt
182 Amplifier command: # File of commands
184 Amplifier command: F 14250000
186 Amplifier command: f
188 Frequency(Hz): 14250000
189 Amplifier command: l PWRINPUT
191 Level Value: 0
192 Amplifier command: l PWRFORWARD
194 Level Value: 1499
195 Amplifier command: l SWR
197 Level Value: 1.000000
198 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 Overall backend warnings: 0
222 Amplifier command:
224 $
226 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 Q|q, exit ampctl
234 Exit ampctl in interactive mode.
235 When ampctl is controlling the amplifier directly, will close
237 the amplifier backend and port. When ampctl is connected to am‐
238 pctld (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 F, set_freq 'Frequency'
243 Set 'Frequency', in Hz.
244 Frequency may be a floating point or integer value.
246 f, get_freq
248 Get 'Frequency', in Hz.
249 Returns an integer value.
251 l, get_level 'Level'
253 Get 'Level Value'.
254 Returns Level Value as a float or integer for the Level token
256 given.
257 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 w, send_cmd 'Cmd'
264 Send a raw command string to the amplifier.
265 This is useful for testing and troubleshooting amplifier com‐
267 mands and responses when developing a backend.
268 For binary protocols enter values as \0xAA\0xBB. Expect a 'Re‐
270 ply' from the amplifier which will likely be a binary block or
271 an ASCII string depending on the amplifier's protocol (see your
272 amplifier's computer control documentation).
273 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 dump_state
279 Return certain state information about the amplifier backend.
280 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 TODO: Ensure this is in a consistent format so it can be read
287 into a hash, dictionary, etc. Bug reports requested.
288 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 _, get_info
295 Return information from the amplifier backend.
296 R, reset 'Reset'
298 Perform amplifier 'Reset'.
299 Reset is an integer value: ‘0’ = None, ‘1’ = Memory reset, ‘2’ =
301 Fault reset, ‘3’ = Amplifier reset.
302 set_powerstat 'Power Status'
304 Set 'Power Status'.
305 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 get_powerstat
311 Get 'Power Status' as in set_powerstat above.
312 Y, set_ant 'Antenna' 'Option'
314 Set 'Antenna' and 'Option'.
315 Number is 1-based antenna# (‘1’, ‘2’, ‘3’, ...).
317 1 = A/1
319 2 = B/2
320 3 = C/3
321
324 If Readline library development files are found at configure time, am‐
325 pctl will be conditonally built with Readline support for command and
326 argument entry. Readline command key bindings are at their defaults as
327 described in the Readline manual
328 ⟨https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩. ampctl
329 sets the name “ampctl” which can be used in Conditional Init Constructs
330 in the Readline Init File ($HOME/.inputrc by default) for custom key‐
331 bindings unique to ampctl.
332 Command history is available with Readline support as described in the
334 Readline History manual
335 ⟨https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩. Command
336 and argument strings are stored as single lines even when arguments are
337 prompted for input individually. Commands and arguments are not vali‐
338 dated and are stored as typed with values separated by a single space.
339 Normally session history is not saved, however, use of either of the
341 -i/--read-history or -I/--save-history options when starting ampctl
342 will cause any previously saved history to be read in and/or the cur‐
343 rent and any previous session history (assuming the -i and -I options
344 are given together) will be written out when ampctl is closed. Each
345 option is mutually exclusive, i.e. either may be given separately or in
346 combination. This is useful to save a set of commands and then read
347 them later but not write the modified history for a consistent set of
348 test commands in interactive mode, for example.
349 History is stored in $HOME/.ampctl_history by default although the des‐
351 tination directory may be changed by setting the AMPCTL_HIST_DIR envi‐
352 ronment variable. When AMPCTL_HIST_DIR is unset, the value of the HOME
353 environment variable is used instead. Only the destination directory
354 may be changed at this time.
355 If Readline support is not found at configure time the original inter‐
357 nal command handler is used. Readline is not used for ampctl commands
358 entered on the command line regardless if Readline support is built in
359 or not.
360 Note: Readline support is not included in the MS Windows 32 or 64 bit
362 binary builds supplied by the Hamlib Project. Running ampctl on the MS
363 Windows platform in the ‘cmd’ shell does give session command line his‐
364 tory, however, it is not saved to disk between sessions.
365
367 The -v, --verbose option allows different levels of diagnostics to be
368 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
369 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
370 A given verbose level is useful for providing needed debugging informa‐
372 tion to the email address below. For example, TRACE output shows all
373 of the values sent to and received from the amplifier which is very
374 useful for amplifier backend library development and may be requested
375 by the developers.
376
378 ampctl exits with:
379 0 if all operations completed normally;
381 1 if there was an invalid command line option or argument;
383 2 if an error was returned by Hamlib.
385
387 Start ampctl for am Elecraft KPA-1500 using a USB to serial adapter on
388 Linux in interactive mode:
389 $ ampctl -m 201 -r /dev/ttyUSB1
391 Start ampctl for an Elecraft KPA-1500 using COM1 on MS Windows while
393 generating TRACE output to stderr:
394 > ampctl -m 201 -r COM1 -vvvvv
396 Connect to a running ampctld with amplifier model 2 (“NET ampctl”) on
398 the local host and specifying the TCP port, setting frequency and mode:
399 $ ampctl -m 2 -r localhost:4531 F 7253500
401
403 This almost empty section...
404 Report bugs to:
406 Hamlib Developer mailing list
408 ⟨hamlib-developer@lists.sourceforge.net⟩
409
411 This file is part of Hamlib, a project to develop a library that sim‐
412 plifies radio, rotator, and amplifier control functions for developers
413 of software primarily of interest to radio amateurs and those inter‐
414 ested in radio communications.
415 Copyright © 2000-2011 Stephane Fillod
417 Copyright © 2000-2018 the Hamlib Group (various contributors)
418 Copyright © 2010-2020 Nate Bargmann
419 This is free software; see the file COPYING for copying conditions.
421 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
422 PARTICULAR PURPOSE.
423
425 less(1), more(1), ampctld(1), hamlib(7)
426
428 Links to the Hamlib Wiki, Git repository, release archives, and daily
429 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
430Hamlib 2020-09-08 AMPCTL(1)