1HAMLIB-UTILITIES(7) Hamlib Information Manual HAMLIB-UTILITIES(7)
2
6 hamlib-utilties - radio and rotator control utilities of Hamlib
7
9 Included with the Hamlib distribution are several utility programs.
10 Besides providing a way for developers to test new code and bug fixes,
11 the programs also offer a reference implementation for interfacing to
12 the Hamlib library functions both through the C API (Application Pro‐
13 gramming Interface) and offering a network accessible API.
14 This page summarizes the three test programs, ampctl(1) for testing
16 amplifier back ends, rigctl(1) for testing radio back ends, and
17 rotctl(1) for testing rotator back ends and the three network daemons,
18 ampctld(1), rigctld(1), and rotcltd(1) for amplifier, radio, and rota‐
19 tor access via network sockets. Also included are three demonstration
20 utilities, rigmem(1), rigsmtr(1), and rigswr(1) which provide func‐
21 tional examples of how Hamlib may be used to accomplish various tasks.
22
24 rigctl(1) is the most frequently used Hamlib utility. As the other ctl
25 utilities share many of the same characteristics, much of the introduc‐
26 tory information presented in this section is applicable to the other
27 utility programs.
28 Introduction to rigctl
30 Most likely the first of the Hamlib utility programs that is used is
31 rigctl(1). rigctl is a character based interactive program and a com‐
32 mand line program able to set or query a radio's value with a single
33 command. rigctl is invoked from a shell command prompt with various
34 options and additional commands.
35 In its most simple use as a command line program, rigctl is used to set
37 frequency and mode by typing commands after any rigctl options:
38 rigctl F 14205000
40 rigctl M USB 2400
41 and then query those values:
43 rigctl f
45 rigctl m
46 Entering interactive mode is a simple matter of not placing any com‐
48 mands after any rigctl options:
49 rigctl
51 Entering interactive mode allows successive commands to be entered
53 without exiting rigctl. Recent additions to rigctl allow command edit‐
54 ing and history recall through use of the Readline
55 ⟨https://tiswww.case.edu/php/chet/readline/rltop.html⟩ library.
56 Interactive mode is indicated by the spartan prompt:
58 Rig command:
60 Commands are given at the prompt and follow the general rule that upper
62 case letters set a value and lower case letters query a value:
63 Rig command: M
65 Mode: USB
66 Passband: 2500
67 Rig command: m
69 Mode: USB
70 Passband: 2500
71 Rig command:
73 An additional prompt is printed when more information is required by
75 the command. For M above, rigctl prompted for the Mode and Passband
76 values. For m above, rigctl returned the Mode and Passband values
77 without further prompts. The command prompt is returned after each
78 command invocation.
79 The above examples invoked rigctl without specifying a radio model.
81 This is a feature where the Hamlib internal radio model 1 dummy is
82 used. The dummy radio provides a way to test Hamlib functions without
83 the need for actual radio hardware. However, to develop the Hamlib
84 backend capability for a given radio, having the actual radio connected
85 to the computer is necessary for debugging.
86 For example, to quickly set frequency on an Elecraft K3:
88 rigctl -m 2029 -r /dev/rig F 3900000
90 and to query the frequency and then mode:
92 rigctl -m 2029 -r /dev/rig f
94 3900000
95 rigctl -m 2029 -r /dev/rig m
97 LSB
98 2000
99 Note: the returned values do not have the prompt strings associ‐
101 ated with interactive mode as shown above.
102 The -m option takes a numeric value that corresponds to a given radio
104 back end model. The -r option takes the path to the port device on
105 POSIX and the device name on Microsoft Windows.
106 Note: A complete list of supported radio models may be seen by
108 use of the -l option:
109 rigctl -l
111 Rig # Mfg Model Version Status
112 1 Hamlib Dummy 0.5 Beta
113 2 Hamlib NET rigctl 0.3 Beta
114 1001 Yaesu FT-847 0.5 Beta
115 1003 Yaesu FT-1000D 0.0.6 Alpha
116 .
117 .
118 .
119 27002 Rohde&Schwarz EB200 0.1 Untested
120 28001 Philips/Simoco PRM8060 0.1 Alpha
121 29001 ADAT www.adat.ch ADT-200A 1.36 Beta
122 The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll‐
124 Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir‐
125 tual terminal window (cmd window on Microsoft Windows) or the output
126 can be piped to more(1) or less(1), e.g., “rigctl -l | more” to scroll
127 back up the list. The list is sorted numerically by model number since
128 Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are
129 grouped together.
130 rigctl reference
132 The complete reference for rigctl can be found in the rigctl(1) manual
133 page.
134
136 Identical in function to rigctl(1), rotctl(1) provides a means for
137 testing Hamlib functions useful for rotator control and QTH (Maidenhead
138 gridsquare system, see Maidenhead Locator System
139 ⟨https://en.wikipedia.org/wiki/Maidenhead_Locator_System⟩) locator com‐
140 putations. As rotators have a much narrower scope than radios, there
141 are fewer command line options and commands for rotctl.
142 Introduction to rotctl
144 rotctl(1) is a character based interactive program and a command line
145 program able to set or query a rotator's value with a single command.
146 rotctl is invoked from a shell command prompt with various options and
147 additional commands.
148 In its most simple use as a command line program, rotctl is used to set
150 azimuth position and (optionally) elevation by typing commands after
151 any rotctl options:
152 rotctl P 145.0 23.0
154 rotctl M 8 25
155 and then query those values:
157 rotctl p
159 Entering interactive mode is a simple matter of not placing any com‐
161 mands after any rotctl options:
162 rotctl
164 Entering interactive mode allows successive commands to be entered
166 without exiting rotctl. Interactive mode allows for command editing
167 and history recall through the use of the Readline
168 ⟨https://tiswww.case.edu/php/chet/readline/rltop.html⟩ library.
169 Interactive mode is indicated by the spartan prompt:
171 Rotator command:
173 Commands are given at the prompt:
175 Rotator command: M
177 Direction: 16
178 Speed: 60
179 Rotator command: p
181 Azimuth: 11.352000
182 Elevation: 0.000000
183 Rotator command: p
185 Azimuth: 27.594000
186 Elevation: 0.000000
187 Rotator command:
189 An additional prompt is printed when more information is required by
191 the command. For M above, rotctl prompted for the Direction and Speed
192 values. For p above, rotctl returned the Azimuth and Elevation values
193 without further prompts. The command prompt is returned after each
194 command invocation.
195 The above examples invoked rotctl without specifying a rotator model.
197 This is a feature where the Hamlib internal rotator model 1 dummy is
198 used instead. The dummy rotator provides a way to test Hamlib func‐
199 tions without the need for actual rotator hardware. However, to
200 develop back end capability for a given rotator, having the actual con‐
201 troller connected to the computer is necessary for debugging.
202 For example, to quickly set position for RotorEZ:
204 rotctl -m 401 -r /dev/rotor P 100.0 0.0
206 and to query the position:
208 rotctl -m 401 -r /dev/rotor p
210 100.000000
211 0.000000
212 The returned values do not have the prompt strings associated with
214 interactive mode as shown above.
215 The -m option takes a numeric value that corresponds to a given rotator
217 back end model. The -r option takes the path to the port device on
218 POSIX or the device name on Microsoft Windows.
219 Note: A complete list of supported rotator models may be seen by
221 use of the -l option:
222 rotctl -l
224 Rot # Mfg Model Version Status
225 1 Hamlib Dummy 0.5 Beta
226 2 Hamlib NET rotctl 0.3 Beta
227 201 Hamlib EasycommI 0.3 Beta
228 202 Hamlib EasycommII 0.3 Beta
229 .
230 .
231 .
232 1201 AMSAT IF-100 0.1 Untested
233 1301 LA7LKA ts7400 0.1 Beta
234 1401 Celestron NexStar 0.1 Untested
235 The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll‐
237 Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir‐
238 tual terminal window (cmd window on Microsoft Windows) or the output
239 can be piped to more(1) or less(1), e.g. “rotctl -l | more” to scroll
240 back up the list. The list is sorted numerically by model number since
241 Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are
242 grouped together.
243 rotctl reference
245 The complete reference for rotctl can be found in the rotctl(1) manual
246 page.
247
249 The ampctl(1) utility is a recent addition to the Hamlib utilities as a
250 part of the 4.0 development cycle. It is intended to test the Hamlib
251 implementation of amplifier control and is similar in function to the
252 utilities previously described. See the ampctl(1) manual page for the
253 complete reference.
254
256 The rigctld(1) program is a network server that accepts the familiar
257 commands of rigctl(1) and provides the response data over a TCP/IP net‐
258 work socket to an application. In this manner an application can
259 access a rigctld instance from nearly anywhere (caveat, no security is
260 currently provided by rigctld). Applications using rigctld do not link
261 directly to Hamlib nor use its C API.
262 Introduction to rigctld
264 rigctld(1) communicates to a client through a TCP network socket using
265 text commands shared with rigctl(1). The protocol is simple; commands
266 are sent to rigctld on one line and rigctld responds to get commands
267 with the requested values, one per line, when successful, otherwise, it
268 responds with one line RPRT x, where x is a negative number indicating
269 the Hamlib error code. Commands that do not return values respond with
270 the line RPRT x, where x is zero when successful, otherwise a negative
271 number indicating the Hamlib error code. Each line is terminated with
272 a newline, \n, character. This protocol is primarily for use by the
273 NET rigctl (radio model 2) backend.
274 A separate Extended Response protocol extends the above behavior by
276 echoing the received command string as a header, any returned values as
277 a key: value pair, and the RPRT x string as the end of response marker
278 which includes the Hamlib success or failure value. Consider using
279 this protocol for clients that will interact with rigctld directly
280 through a TCP network socket.
281 Multiple radios can be controlled on different TCP ports by use of mul‐
283 tiple rigctld processes each listening on a unique TCP port. It is
284 hoped that rigctld will be especially useful for client authors using
285 languages such as Perl ⟨http://www.perl.org/⟩, Python
286 ⟨http://www.python.org/⟩, PHP ⟨http://php.net/⟩, Ruby ⟨http://www.ruby-
287 lang.org/en/⟩, TCL ⟨http://www.tcl.tk/⟩, and others.
288 rigctld reference
290 The complete reference for rigctld can be found in the rigctld(1) man‐
291 ual page.
292
294 The rotctld(1) program is a network server that accepts the familiar
295 commands of rotctl(1) and provides the response data over a TCP/IP net‐
296 work socket to an application. In this manner an application can
297 access a rotctld instance from nearly anywhere (caveat, no security is
298 currently provided by rotctld). Applications using rotctld do not link
299 directly to Hamlib nor use its C API.
300 Introduction to rotctld
302 rotctld(1) communicates to a client through a TCP network socket using
303 text commands shared with rotctl(1). The protocol is simple, commands
304 are sent to rotctld on one line and rotctld responds to get commands
305 with the requested values, one per line, when successful, otherwise, it
306 responds with one line RPRT x, where x is a negative number indicating
307 the Hamlib error code. Commands that do not return values respond with
308 the line RPRT x, where x is zero when successful, otherwise a negative
309 number indicating the Hamlib error code. Each line is terminated with
310 a newline, \n character. This protocol is primarily for use by the NET
311 rotctl (rotator model 2) backend.
312 A separate Extended Response protocol extends the above behavior by
314 echoing the received command string as a header, any returned values as
315 a key: value pair, and the RPRT x string as the end of response marker
316 which includes the Hamlib success or failure value. Consider using
317 this protocol for clients that will interact with rotctld directly
318 through a TCP network socket.
319 Multiple rotators can be controlled on different TCP ports by use of
321 multiple rotctld processes each listening on a unique TCP port. It is
322 hoped that rotctld will be especially useful for client authors using
323 languages such as Perl ⟨http://www.perl.org/⟩, Python
324 ⟨http://www.python.org/⟩, PHP ⟨http://php.net/⟩, Ruby ⟨http://www.ruby-
325 lang.org/en/⟩, TCL ⟨http://www.tcl.tk/⟩, and others.
326 rotctld reference
328 The complete reference for rotctld can be found in the rotctld(1) man‐
329 ual page.
330
332 The ampctld(1) utility is a recent addition to the Hamlib utilities as
333 a part of the 4.0 development cycle. It provides network socket access
334 for the Hamlib implementation of amplifier control and is similar in
335 function to the network utilities previously described. See the
336 ampctld(1) manual page for the complete reference.
337
339 rigmem may be used to backup and restore memory of radio transceivers
340 and receivers.
341 Introduction to rigmem
343 Backup and restore memory of radio transceivers and receivers. rigmem
344 accepts commands from the command line only.
345 rigmem reference
347 The complete reference for rigmem can be found in the rigmem(1) manual
348 page.
349
351 rigsmtr uses Hamlib to control a radio to measure S-Meter value versus
352 antenna azimuth.
353 Introduction to rigsmtr
355 rigsmtr rotates the antenna from minimum azimuth to maximum azimuth.
356 Every second, or time_step if specified in seconds, it retrieves the
357 signal strength. Azimuth in degrees and the corresponding S-Meter level
358 in dB relative to S9 are then printed on stdout.
359 To work correctly, rigsmtr needs a radio that could measure S-Meter and
361 a Hamlib backend that is able to retrieve it, connected to a Hamlib
362 supported rotator.
363 rigsmtr reference
365 The complete reference for rigsmtr can be found in the rigsmtr(1) man‐
366 ual page.
367
369 rigswr may be used to measure VSWR vs frequency.
370 Introduction to rigswr
372 rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing
373 Wave Ratio) over a frequency range.
374 It scans frequencies from start_freq to stop_freq with an optional
376 increment of freq_step (default step is 100 kHz). All values must be
377 entered as an integer in Hertz (cycles per second).
378 Note: rigswr assumes that start_freq is less than or equal to
380 stop_freq. If it is greater, rigswr will exit without doing anything.
381 For each frequency, rigswr transmits at 25% of total POWER during 0.5
383 second in CW mode and reads VSWR.
384 Frequency and the corresponding VSWR are then printed on stdout.
386 To work correctly, rigswr needs a radio that can measure VSWR and a
388 Hamlib backend that supports reading VSWR from the radio.
389 rigswr reference
391 The complete reference for rigswr can be found in the rigswr(1) manual
392 page.
393
395 This file is part of Hamlib, a project to develop a library that sim‐
396 plifies radio and rotator control functions for developers of software
397 primarily of interest to radio amateurs and those interested in radio
398 communications.
399 Copyright © 2001-2020 Hamlib Group (various contributors)
401 This is free software; see the file COPYING for copying conditions.
403 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
404 PARTICULAR PURPOSE.
405
407 less(1), more(1), ampctl(1), ampctld(1), rigctl(1), rigctld(1),
408 rotctl(1), rotctld(1), rigmem(1), rigsmtr(1), rigswr(1), hamlib(7),
409 hamlib-primer(7)
410
412 Links to the Hamlib Wiki, Git repository, release archives, and daily
413 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
414Hamlib 2020-09-08 HAMLIB-UTILITIES(7)