1AMPCTLD(1) Hamlib Utilities AMPCTLD(1)
2
6 ampctld - TCP amplifier control daemon
7
9 ampctld [-hlLuV] [-m id] [-r device] [-s baud] [-T IPADDR] [-t number]
10 [-C parm=val] [-v[-Z]]
11
13 The ampctld program is an amplifier control daemon that handles client
14 requests via TCP sockets. This allows multiple user programs to share
15 one amplifier (this needs more development). Multiple amplifiers can
16 be controlled on different TCP ports by use of multiple ampctld pro‐
17 cesses. Note that multiple processes/ports are also necessary if some
18 clients use extended responses and/or vfo mode. So up to 4 pro‐
19 cesses/ports may be needed for each combination of extended
20 response/vfo mode. The syntax of the commands are the same as
21 ampctl(1). It is hoped that ampctld will be especially useful for
22 client authors using languages such as Perl, Python, PHP, and others.
23 ampctld communicates to a client through a TCP socket using text com‐
25 mands shared with ampctl. The protocol is simple, commands are sent to
26 ampctld on one line and ampctld responds to get commands with the
27 requested values, one per line, when successful, otherwise, it responds
28 with one line “RPRT x”, where ‘x’ is a negative number indicating the
29 error code. Commands that do not return values respond with the line
30 “RPRT x”, where ‘x’ is ‘0’ when successful, otherwise is a regative
31 number indicating the error code. Each line is terminated with a new‐
32 line ‘\n’ character. This protocol is primarily for use by the NET
33 ampctl (amplifier model 2) backend.
34 A separate Extended Response Protocol extends the above behavior by
36 echoing the received command string as a header, any returned values as
37 a key: value pair, and the “RPRT x” string as the end of response
38 marker which includes the Hamlib success or failure value. See the
39 PROTOCOL section for details. Consider using this protocol for clients
40 that will interact with ampctld directly through a TCP socket.
41 Keep in mind that Hamlib is BETA level software. While a lot of back‐
43 end libraries lack complete amplifier support, the basic functions are
44 usually well supported.
45 Please report bugs and provide feedback at the e-mail address given in
47 the BUGS section below. Patches and code enhancements sent to the same
48 address are welcome.
49
51 This program follows the usual GNU command line syntax. Short options
52 that take an argument may have the value follow immediately or be sepa‐
53 rated by a space. Long options starting with two dashes (‘-’) require
54 an ‘=’ between the option and any argument.
55 Here is a summary of the supported options:
57 -m, --model=id
59 Select amplifier model number.
60 See model list (use “ampctl -l”).
62 Note: ampctl (or third party software using the C API) will use
64 amplifier model 2 for NET ampctl (communicating with ampctld).
65 -r, --amp-file=device
67 Use device as the file name of the port connected to the ampli‐
68 fier.
69 Often a serial port, but could be a USB to serial adapter. Typ‐
71 ically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux,
72 COM1, COM2, etc. on MS Windows. The BSD flavors and Mac OS/X
73 have their own designations. See your system's documentation.
74 -s, --serial-speed=baud
76 Set serial speed to baud rate.
77 Uses maximum serial speed from amplifier backend capabilities
79 (set by -m above) as the default.
80 -t, --port=number
82 Use number as the TCP listening port.
83 The default is 4531.
85 Note: As rigctld's default port is 4532 and rotctld's default
87 port is 4533, it is recommended to use DESCENDING odd numbered
88 ports for multiple ampctld instances, e.g. 4529, 4527, 4525,
89 etc.
90 -T, --listen-addr=IPADDR
92 Use IPADDR as the listening IP address.
93 The default is ANY.
95 -L, --show-conf
97 List all config parameters for the amplifier defined with -m
98 above.
99 -C, --set-conf=parm=val[,parm=val]
101 Set amplifier configuration parameter(s), e.g. stop_bits=2.
102 Use the -L option above for a list of configuration parameters
104 for a given model number.
105 -u, --dump-caps
107 Dump capabilities for the amplifier defined with -m above and
108 exit.
109 -l, --list
111 List all amplifier model numbers defined in Hamlib and exit.
112 The list is sorted by model number.
114 Note: In Linux the list can be scrolled back using Shift-
116 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
117 minal in X or the cmd window in Windows. The output can be
118 piped to more(1) or less(1), e.g. “ampctl -l | more”.
119 -v, --verbose
121 Set verbose mode, cumulative (see DIAGNOSTICS below).
122 -Z, --debug-time-stamps
124 Enable time stamps for the debug messages.
125 Use only in combination with the -v option as it generates no
127 output on its own.
128 -h, --help
130 Show a summary of these options and exit.
131 -V, --version
133 Show version of ampctl and exit.
134 Note: Some options may not be implemented by a given backend and will
136 return an error. This is most likely to occur with the --set-conf and
137 --show-conf options.
138 Please note that the backend for the amplifier to be controlled, or the
140 amplifier itself may not support some commands. In that case, the
141 operation will fail with a Hamlib error code.
142
144 Commands can be sent over the TCP socket either as a single char, or as
145 a long command name plus the value(s) space separated on one ‘\n’ ter‐
146 minated line. See PROTOCOL.
147 Since most of the Hamlib operations have a set and a get method, an
149 upper case letter will be used for set methods whereas the correspond‐
150 ing lower case letter refers to the get method. Each operation also
151 has a long name; prepend a backslash, ‘\’, to send a long command name.
152 Example (Perl): “print $socket "\\dump_caps\n";” to see what the ampli‐
154 fier's backend can do (Note: In Perl and many other languages a ‘\’
155 will need to be escaped with a preceding ‘\’ so that even though two
156 backslash characters appear in the code, only one will be passed to
157 ampctld. This is a possible bug, beware!).
158 Note: The backend for the amplifier to be controlled, or the amplifier
160 itself may not support some commands. In that case, the operation will
161 fail with a Hamlib error message.
162 Here is a summary of the supported commands (In the case of set com‐
164 mands the quoted italicized string is replaced by the value in the
165 description. In the case of get commands the quoted italicized string
166 is the key name of the value returned.):
167 F, set_freq 'Frequency'
169 Set 'Frequency', in Hz.
170 Frequency may be a floating point or integer value.
172 f, get_freq
174 Get 'Frequency', in Hz.
175 Returns an integer value.
177 l, get_level 'Level'
179 Get 'Level Value'.
180 Returns Level Value as a float or integer for the Level token
182 given.
183 Note: Passing a ‘?’ (query) as the first argument instead of a
185 Level token will return a space separated list of amplifier
186 backend supported get level tokens. Use this to determine the
187 supported levels of a given amplifier backend.
188 dump_state
190 Return certain state information about the amplifier backend.
191 1, dump_caps
193 Not a real amplifier remote command, it just dumps capabilities,
194 i.e. what the backend knows about this model, and what it can
195 do.
196 TODO: Ensure this is in a consistent format so it can be read
198 into a hash, dictionary, etc. Bug reports requested.
199 Note: This command will produce many lines of output so be very
201 careful if using a fixed length array! For example, running
202 this command against the Dummy backend results in a number of
203 lines of text output.
204 _, get_info
206 Return information from the amplifier backend.
207 R, reset 'Reset'
209 Perform amplifier 'Reset'.
210 Reset is an integer value: ‘0’ = None, ‘1’ = Memory reset, ‘2’ =
212 Fault reset, ‘3’ = Amplifier reset.
213 set_powerstat 'Power Status'
215 Set 'Power Status'.
216 Power Status is an integer value: ‘0’ = Power Off, ‘1’ = Power
218 On, ‘2’ = Power Standby (enter standby), ‘4’ = Power Operate
219 (leave standby).
220 get_powerstat
222 Get 'Power Status' as in set_powerstat above.
223
225 There are two protocols in use by ampctld, the Default Protocol and the
226 Extended Response Protocol.
227 The Default Protocol is intended primarily for the communication
229 between Hamlib library functions and ampctld (“NET ampctl”, available
230 using amplifier model ‘2’).
231 The Extended Response Protocol is intended to be used with scripts or
233 other programs interacting directly with ampctld as consistent feedback
234 is provided.
235 Default Protocol
237 The Default Protocol is intentionally simple. Commands are entered on
238 a single line with any needed values. In practice, reliable results
239 are obtained by terminating each command string with a newline charac‐
240 ter, ‘\n’.
241 Example set frequency and mode commands (Perl code (typed text shown in
243 bold)):
244 print $socket "F 14250000\n";
246 print $socket "\\set_powerstat 1\n"; # escape leading '\'
247 A one line response will be sent as a reply to set commands, “RPRT x\n”
249 where x is the Hamlib error code with ‘0’ indicating success of the
250 command.
251 Responses from ampctld get commands are text values and match the same
253 tokens used in the set commands. Each value is returned on its own
254 line. On error the string “RPRT x\n” is returned where x is the Hamlib
255 error code.
256 Example get frequency (Perl code):
258 print $socket "f\n";
260 "14250000\n"
261 Most get functions return one to three values. A notable exception is
263 the dump_caps command which returns many lines of key:value pairs.
264 This protocol is primarily used by the “NET ampctl” (ampctl model 2)
266 backend which allows applications already written for Hamlib's C API to
267 take advantage of ampctld without the need of rewriting application
268 code. An application's user can select amplifier model 2 (“NET
269 ampctl”) and then set amp_pathname to “localhost:4531” or other network
270 host:port (set by the -T/-t options, respectively, above).
271 Extended Response Protocol
273 The Extended Response protocol adds several rules to the strings
274 returned by ampctld and adds a rule for the command syntax.
275 1. The command received by ampctld is echoed with its long command name
277 followed by the value(s) (if any) received from the client terminated
278 by the specified response separator as the first record of the
279 response.
280 2. The last record of each block is the string “RPRT x\n” where x is
282 the numeric return value of the Hamlib backend function that was called
283 by the command.
284 3. Any records consisting of data values returned by the amplifier
286 backend are prepended by a string immediately followed by a colon then
287 a space and then the value terminated by the response separator. e.g.
288 “Frequency: 14250000\n” when the command was prepended by ‘+’.
289 4. All commands received will be acknowledged by ampctld
291 with records from rules 1 and 2. Records from rule 3 are only
292 returned when data values must be returned to the client.
293 4. All commands received will be acknowledged by ampctld with records
295 from rules 1 and 2. Records from rule 3 are only returned when data
296 values must be returned to the client.
297 An example response to a set_frequency command sent from the shell
299 prompt (note the prepended ‘+’):
300 $ echo "+F 14250000" | nc -w 1 localhost 4531
302 set_freq: 14250000
303 RPRT 0
304 In this case the long command name and values are returned on the first
306 line and the second line contains the end of block marker and the
307 numeric amplifier backend return value indicating success.
308 An example response to a get_freq query:
310 $ echo "+\get_freq" | nc -w 1 localhost 4531
312 get_freq:
313 Frequency(Hz): 14250000
314 RPRT 0
315 Note: The ‘\’ is still required for the long command name even
317 with the ERP character.
318 In this case, as no value is passed to ampctld, the first line consists
320 only of the long command name. The final line shows that the command
321 was processed successfully by the amplifier backend.
322 Invoking the Extended Response Protocol requires prepending a command
324 with a punctuation character. As shown in the examples above, prepend‐
325 ing a ‘+’ character to the command results in the responses being sepa‐
326 rated by a newline character (‘\n’). Any other punctuation character
327 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
328 cause that character to become the response separator and the entire
329 response will be on one line.
330 Separator character summary:
332 ‘+’ Each record of the response is appended with a newline (‘\n’).
334 ‘;’, ‘|’, or, ‘,’
336 Each record of the response is appended by the given character
337 resulting in entire response on one line.
338 These are common record separators for text representations of
340 spreadsheet data, etc.
341 ‘?’ Reserved for help in ampctl.
343 ‘_’ Reserved for get_info short command
345 ‘#’ Reserved for comments when reading a command file script.
347 Note: Other punctuation characters have not been tested! Use at
349 your own risk.
350 For example, invoking a get_freq query with a leading ‘;’ returns:
352 get_freq:;Frequency(Hz): 14250000;RPRT 0
354 Or, using the pipe character ‘|’ returns:
356 get_freq:|Frequency(Hz): 14250000|RPRT 0
358 And a set_freq command prepended with a ‘|’ returns:
360 set_freq: 14250000|RPRT 0
362 Such a format will allow reading a response as a single event using a
364 preferred response separator. Other punctuation characters have not
365 been tested!
366
368 The -v, --verbose option allows different levels of diagnostics to be
369 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
370 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
371 A given verbose level is useful for providing needed debugging informa‐
373 tion to the email address below. For example, TRACE output shows all
374 of the values sent to and received from the amplifier which is very
375 useful for amplifier backend library development and may be requested
376 by the developers.
377
379 Start ampctld for an Elecraft KPA-1500 using a USB-to-serial adapter
380 and backgrounding:
381 $ ampctld -m 201 -r /dev/ttyUSB1 &
383 Start ampctld for an Elecraft KPA-1500 using COM2 on MS Windows:
385 $ ampctld -m 201 -r COM2
387 Connect to the already running ampctld and set the frequency to 14.266
389 MHz with a 1 second read timeout using the default protocol from the
390 shell prompt:
391 $ echo "\set_freq 14266000" | nc -w 1 localhost 4531
393 Connect to a running ampctld with ampctl on the local host:
395 $ ampctl -m2
397
399 No authentication whatsoever; DO NOT leave this TCP port open wide to
400 the Internet. Please ask if stronger security is needed or consider
401 using a Secure Shell (ssh(1)) tunnel.
402 As ampctld does not need any greater permissions than ampctl, it is
404 advisable to not start ampctld as “root” or another system user account
405 in order to limit any vulnerability.
406
408 The daemon is not detaching and backgrounding itself.
409 No method to exit the daemon so the kill(1) command must be used to
411 terminate it.
412 Multiple clients using the daemon may experience contention with the
414 connected amplifier.
415 Report bugs to:
417 Hamlib Developer mailing list
419 ⟨hamlib-developer@lists.sourceforge.net⟩
420
422 This file is part of Hamlib, a project to develop a library that sim‐
423 plifies radio, rotator, and amplifier control functions for developers
424 of software primarily of interest to radio amateurs and those inter‐
425 ested in radio communications.
426 Copyright © 2000-2010 Stephane Fillod
428 Copyright © 2000-2018 the Hamlib Group (various contributors)
429 Copyright © 2011-2020 Nate Bargmann
430 This is free software; see the file COPYING for copying conditions.
432 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
433 PARTICULAR PURPOSE.
434
436 kill(1), ampctl(1), ssh(1), hamlib(7)
437
439 Links to the Hamlib Wiki, Git repository, release archives, and daily
440 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
441Hamlib 2020-09-09 AMPCTLD(1)