1AMPCTLD(1)                     Hamlib Utilities                     AMPCTLD(1)
2
3
4

NAME

6       ampctld - TCP amplifier control daemon
7

SYNOPSIS

9       ampctld [-hlLuV] [-m id] [-r device] [-s baud] [-T IPADDR] [-t number]
10               [-C parm=val] [-v[-Z]]
11

DESCRIPTION

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

OPTIONS

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

COMMANDS

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

PROTOCOL

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

DIAGNOSTICS

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

EXAMPLES

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

SECURITY

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

BUGS

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

COPYING

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

SEE ALSO

436       kill(1), ampctl(1), ssh(1), hamlib(7)
437

COLOPHON

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)
Impressum