1AMPCTLD(1) Hamlib Utilities AMPCTLD(1)
2
3
4
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
24 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
35 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
42 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
46 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
56 Here is a summary of the supported options:
57
58 -m, --model=id
59 Select amplifier model number.
60
61 See model list (use “ampctl -l”).
62
63 Note: ampctl (or third party software using the C API) will use
64 amplifier model 2 for NET ampctl (communicating with ampctld).
65
66 -r, --amp-file=device
67 Use device as the file name of the port connected to the ampli‐
68 fier.
69
70 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
75 -s, --serial-speed=baud
76 Set serial speed to baud rate.
77
78 Uses maximum serial speed from amplifier backend capabilities
79 (set by -m above) as the default.
80
81 -t, --port=number
82 Use number as the TCP listening port.
83
84 The default is 4531.
85
86 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
91 -T, --listen-addr=IPADDR
92 Use IPADDR as the listening IP address.
93
94 The default is ANY.
95
96 -L, --show-conf
97 List all config parameters for the amplifier defined with -m
98 above.
99
100 -C, --set-conf=parm=val[,parm=val]
101 Set amplifier configuration parameter(s), e.g. stop_bits=2.
102
103 Use the -L option above for a list of configuration parameters
104 for a given model number.
105
106 -u, --dump-caps
107 Dump capabilities for the amplifier defined with -m above and
108 exit.
109
110 -l, --list
111 List all amplifier model numbers defined in Hamlib and exit.
112
113 The list is sorted by model number.
114
115 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
120 -v, --verbose
121 Set verbose mode, cumulative (see DIAGNOSTICS below).
122
123 -Z, --debug-time-stamps
124 Enable time stamps for the debug messages.
125
126 Use only in combination with the -v option as it generates no
127 output on its own.
128
129 -h, --help
130 Show a summary of these options and exit.
131
132 -V, --version
133 Show version of ampctl and exit.
134
135 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
139 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
148 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
153 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
159 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
163 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
168 F, set_freq 'Frequency'
169 Set 'Frequency', in Hz.
170
171 Frequency may be a floating point or integer value.
172
173 f, get_freq
174 Get 'Frequency', in Hz.
175
176 Returns an integer value.
177
178 l, get_level 'Level'
179 Get 'Level Value'.
180
181 Returns Level Value as a float or integer for the Level token
182 given.
183
184 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
189 dump_state
190 Return certain state information about the amplifier backend.
191
192 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
197 TODO: Ensure this is in a consistent format so it can be read
198 into a hash, dictionary, etc. Bug reports requested.
199
200 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
205 _, get_info
206 Return information from the amplifier backend.
207
208 R, reset 'Reset'
209 Perform amplifier 'Reset'.
210
211 Reset is an integer value: ‘0’ = None, ‘1’ = Memory reset, ‘2’ =
212 Fault reset, ‘3’ = Amplifier reset.
213
214 set_powerstat 'Power Status'
215 Set 'Power Status'.
216
217 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
221 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
228 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
232 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
236 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
242 Example set frequency and mode commands (Perl code (typed text shown in
243 bold)):
244
245 print $socket "F 14250000\n";
246 print $socket "\\set_powerstat 1\n"; # escape leading '\'
247
248 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
252 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
257 Example get frequency (Perl code):
258
259 print $socket "f\n";
260 "14250000\n"
261
262 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
265 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
272 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
276 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
281 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
285 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
290 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
294 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
298 An example response to a set_frequency command sent from the shell
299 prompt (note the prepended ‘+’):
300
301 $ echo "+F 14250000" | nc -w 1 localhost 4531
302 set_freq: 14250000
303 RPRT 0
304
305 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
309 An example response to a get_freq query:
310
311 $ echo "+\get_freq" | nc -w 1 localhost 4531
312 get_freq:
313 Frequency(Hz): 14250000
314 RPRT 0
315
316 Note: The ‘\’ is still required for the long command name even
317 with the ERP character.
318
319 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
323 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
331 Separator character summary:
332
333 ‘+’ Each record of the response is appended with a newline (‘\n’).
334
335 ‘;’, ‘|’, or, ‘,’
336 Each record of the response is appended by the given character
337 resulting in entire response on one line.
338
339 These are common record separators for text representations of
340 spreadsheet data, etc.
341
342 ‘?’ Reserved for help in ampctl.
343
344 ‘_’ Reserved for get_info short command
345
346 ‘#’ Reserved for comments when reading a command file script.
347
348 Note: Other punctuation characters have not been tested! Use at
349 your own risk.
350
351 For example, invoking a get_freq query with a leading ‘;’ returns:
352
353 get_freq:;Frequency(Hz): 14250000;RPRT 0
354
355 Or, using the pipe character ‘|’ returns:
356
357 get_freq:|Frequency(Hz): 14250000|RPRT 0
358
359 And a set_freq command prepended with a ‘|’ returns:
360
361 set_freq: 14250000|RPRT 0
362
363 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
372 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
382 $ ampctld -m 201 -r /dev/ttyUSB1 &
383
384 Start ampctld for an Elecraft KPA-1500 using COM2 on MS Windows:
385
386 $ ampctld -m 201 -r COM2
387
388 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
392 $ echo "\set_freq 14266000" | nc -w 1 localhost 4531
393
394 Connect to a running ampctld with ampctl on the local host:
395
396 $ 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
403 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
410 No method to exit the daemon so the kill(1) command must be used to
411 terminate it.
412
413 Multiple clients using the daemon may experience contention with the
414 connected amplifier.
415
416 Report bugs to:
417
418 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
427 Copyright © 2000-2010 Stephane Fillod
428 Copyright © 2000-2018 the Hamlib Group (various contributors)
429 Copyright © 2011-2020 Nate Bargmann
430
431 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⟩.
441
442
443
444Hamlib 2020-09-09 AMPCTLD(1)