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
165 amplifier itself may not support some commands. In that case,
166 the 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
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 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
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 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
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
318 ⟨https://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 Command history is available with Readline support as described in the
324 Readline History manual
325 ⟨https://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 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 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 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 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
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 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
368 ampctl exits with:
369 0 if all operations completed normally;
371 1 if there was an invalid command line option or argument;
373 2 if an error was returned by Hamlib.
375
377 Start ampctl for am Elecraft KPA-1500 using a USB to serial adapter on
378 Linux in interactive mode:
379 $ ampctl -m 201 -r /dev/ttyUSB1
381 Start ampctl for an Elecraft KPA-1500 using COM1 on MS Windows while
383 generating TRACE output to stderr:
384 > ampctl -m 201 -r COM1 -vvvvv
386 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 $ ampctl -m 2 -r localhost:4531 F 7253500
391
393 This almost empty section...
394 Report bugs to:
396 Hamlib Developer mailing list
398 ⟨hamlib-developer@lists.sourceforge.net⟩
399
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 Copyright © 2000-2011 Stephane Fillod
407 Copyright © 2000-2018 the Hamlib Group (various contributors)
408 Copyright © 2010-2020 Nate Bargmann
409 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
415 less(1), more(1), ampctld(1), hamlib(7)
416
418 Links to the Hamlib Wiki, Git repository, release archives, and daily
419 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
420Hamlib 2020-09-08 AMPCTL(1)