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):
243 print $socket "F 14250000\n";
245 print $socket "\\set_powerstat 1\n"; # escape leading '\'
246 A one line response will be sent as a reply to set commands, “RPRT x\n”
248 where x is the Hamlib error code with ‘0’ indicating success of the
249 command.
250 Responses from ampctld get commands are text values and match the same
252 tokens used in the set commands. Each value is returned on its own
253 line. On error the string “RPRT x\n” is returned where x is the Hamlib
254 error code.
255 Example get frequency (Perl code):
257 print $socket "f\n";
259 "14250000\n"
260 Most get functions return one to three values. A notable exception is
262 the dump_caps command which returns many lines of key:value pairs.
263 This protocol is primarily used by the “NET ampctl” (ampctl model 2)
265 backend which allows applications already written for Hamlib's C API to
266 take advantage of ampctld without the need of rewriting application
267 code. An application's user can select amplifier model 2 (“NET
268 ampctl”) and then set amp_pathname to “localhost:4531” or other network
269 host:port (set by the -T/-t options, respectively, above).
270 Extended Response Protocol
272 The Extended Response protocol adds several rules to the strings
273 returned by ampctld and adds a rule for the command syntax.
274 1. The command received by ampctld is echoed with its long command name
276 followed by the value(s) (if any) received from the client terminated
277 by the specified response separator as the first record of the
278 response.
279 2. The last record of each block is the string “RPRT x\n” where x is
281 the numeric return value of the Hamlib backend function that was called
282 by the command.
283 3. Any records consisting of data values returned by the amplifier
285 backend are prepended by a string immediately followed by a colon then
286 a space and then the value terminated by the response separator. e.g.
287 “Frequency: 14250000\n” when the command was prepended by ‘+’.
288 4. All commands received will be acknowledged by ampctld
290 with records from rules 1 and 2. Records from rule 3 are only
291 returned when data values must be returned to the client.
292 4. All commands received will be acknowledged by ampctld with records
294 from rules 1 and 2. Records from rule 3 are only returned when data
295 values must be returned to the client.
296 An example response to a set_frequency command sent from the shell
298 prompt (note the prepended ‘+’):
299 $ echo "+F 14250000" | nc -w 1 localhost 4531
301 set_freq: 14250000
302 RPRT 0
303 In this case the long command name and values are returned on the first
305 line and the second line contains the end of block marker and the
306 numeric amplifier backend return value indicating success.
307 An example response to a get_freq query:
309 $ echo "+\get_freq" | nc -w 1 localhost 4531
311 get_freq:
312 Frequency(Hz): 14250000
313 RPRT 0
314 Note: The ‘\’ is still required for the long command name even
316 with the ERP character.
317 In this case, as no value is passed to ampctld, the first line consists
319 only of the long command name. The final line shows that the command
320 was processed successfully by the amplifier backend.
321 Invoking the Extended Response Protocol requires prepending a command
323 with a punctuation character. As shown in the examples above, prepend‐
324 ing a ‘+’ character to the command results in the responses being sepa‐
325 rated by a newline character (‘\n’). Any other punctuation character
326 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
327 cause that character to become the response separator and the entire
328 response will be on one line.
329 Separator character summary:
331 ‘+’ Each record of the response is appended with a newline (‘\n’).
333 ‘;’, ‘|’, or, ‘,’
335 Each record of the response is appended by the given character
336 resulting in entire response on one line.
337 These are common record separators for text representations of
339 spreadsheet data, etc.
340 ‘?’ Reserved for help in ampctl.
342 ‘_’ Reserved for get_info short command
344 ‘#’ Reserved for comments when reading a command file script.
346 Note: Other punctuation characters have not been tested! Use at
348 your own risk.
349 For example, invoking a get_freq query with a leading ‘;’ returns:
351 get_freq:;Frequency(Hz): 14250000;RPRT 0
353 Or, using the pipe character ‘|’ returns:
355 get_freq:|Frequency(Hz): 14250000|RPRT 0
357 And a set_freq command prepended with a ‘|’ returns:
359 set_freq: 14250000|RPRT 0
361 Such a format will allow reading a response as a single event using a
363 preferred response separator. Other punctuation characters have not
364 been tested!
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 Start ampctld for an Elecraft KPA-1500 using a USB-to-serial adapter
379 and backgrounding:
380 $ ampctld -m 201 -r /dev/ttyUSB1 &
382 Start ampctld for an Elecraft KPA-1500 using COM2 on MS Windows:
384 $ ampctld -m 201 -r COM2
386 Connect to the already running ampctld and set the frequency to 14.266
388 MHz with a 1 second read timeout using the default protocol from the
389 shell prompt:
390 $ echo "\set_freq 14266000" | nc -w 1 localhost 4531
392 Connect to a running ampctld with ampctl on the local host:
394 $ ampctl -m2
396
398 No authentication whatsoever; DO NOT leave this TCP port open wide to
399 the Internet. Please ask if stronger security is needed or consider
400 using a Secure Shell (ssh(1)) tunnel.
401 As ampctld does not need any greater permissions than ampctl, it is
403 advisable to not start ampctld as “root” or another system user account
404 in order to limit any vulnerability.
405
407 The daemon is not detaching and backgrounding itself.
408 No method to exit the daemon so the kill(1) command must be used to
410 terminate it.
411 Multiple clients using the daemon may experience contention with the
413 connected amplifier.
414 Report bugs to:
416 Hamlib Developer mailing list
418 ⟨hamlib-developer@lists.sourceforge.net⟩
419
421 This file is part of Hamlib, a project to develop a library that sim‐
422 plifies radio, rotator, and amplifier control functions for developers
423 of software primarily of interest to radio amateurs and those inter‐
424 ested in radio communications.
425 Copyright © 2000-2010 Stephane Fillod
427 Copyright © 2000-2018 the Hamlib Group (various contributors)
428 Copyright © 2011-2019 Nate Bargmann
429 This is free software; see the file COPYING for copying conditions.
431 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
432 PARTICULAR PURPOSE.
433
435 kill(1), ampctl(1), ssh(1), hamlib(7)
436
438 Links to the Hamlib Wiki, Git repository, release archives, and daily
439 snapshot archives:
440 hamlib.org ⟨http://www.hamlib.org⟩.
442Hamlib 2019-12-10 AMPCTLD(1)