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 two test programs, rigctl(1) for testing radio
16 back ends and rotctl(1) for testing rotator back ends and the two net‐
17 work daemons, rigctld(1) and rotcltd(1) for radio and rotator access
18 via network sockets. Also included are three demonstation utilities,
19 rigmem(1), rigsmtr(1), and rigswr(1) which provide functional examples
20 of how Hamlib may be used to accomplish various tasks.
21
23 rigctl(1) is the most frequently used Hamlib utility. As the other ctl
24 utilities share many of the same characteristics, much of the introduc‐
25 tory information presented in this section is applicable to the other
26 utility programs.
27 Introduction to rigctl
29 Most likely the first of the Hamlib utility programs that is used is
30 rigctl(1). rigctl is a character based interactive program and a com‐
31 mand line program able to set or query a radio's value with a single
32 command. rigctl is invoked from a shell command prompt with various
33 options and additional commands.
34 In its most simple use as a command line program, rigctl is used to set
36 frequency and mode by typing commands after any rigctl options:
37 rigctl F 14205000
39 rigctl M USB 2400
40 and then query those values:
42 rigctl f
44 rigctl m
45 Entering interactive mode is a simple matter of not placing any com‐
47 mands after any rigctl options:
48 rigctl
50 Entering interactive mode allows successive commands to be entered
52 without exiting rigctl. Recent additions to rigctl allow command edit‐
53 ing and history recall through use of the Readline
54 ⟨https://tiswww.case.edu/php/chet/readline/rltop.html⟩ library.
55 Interactive mode is indicated by the spartan prompt:
57 Rig command:
59 Commands are given at the prompt and follow the general rule that upper
61 case letters set a value and lower case letters query a value:
62 Rig command: M
64 Mode: USB
65 Passband: 2500
66 Rig command: m
68 Mode: USB
69 Passband: 2500
70 Rig command:
72 An additional prompt is printed when more information is required by
74 the command. For M above, rigctl prompted for the Mode and Passband
75 values. For m above, rigctl returned the Mode and Passband values
76 without further prompts. The command prompt is returned after each
77 command invocation.
78 The above examples invoked rigctl without specifying a radio model.
80 This is a feature where the Hamlib internal radio model 1 dummy is used
81 instead. The dummy radio provides a way to test Hamlib functions with‐
82 out the need for actual radio hardware. However, to develop the Hamlib
83 backend capability for a given radio, having the actual radio connected
84 to the computer is necessary for debugging.
85 For example, to quickly set frequency on an Elecraft K3:
87 rigctl -m 229 -r /dev/rig F 3900000
89 and to query the frequency and then mode:
91 rigctl -m 229 -r /dev/rig f
93 3900000
94 rigctl -m 229 -r /dev/rig m
96 LSB
97 2000
98 Note: the returned values do not have the prompt strings associated
100 with interactive mode as shown above.
101 The -m option takes a numeric value that corresponds to a given radio
103 back end model. The -r option takes the path to the port device on
104 POSIX and the device name on Microsoft Windows.
105 Note: A complete list of supported radio models may be seen by use of
107 the -l option:
108 rigctl -l
110 Rig # Mfg Model Version Status
111 1 Hamlib Dummy 0.5 Beta
112 2 Hamlib NET rigctl 0.3 Beta
113 101 Yaesu FT-847 0.5 Beta
114 103 Yaesu FT-1000D 0.0.6 Alpha
115 .
116 .
117 .
118 2702 Rohde&Schwarz EB200 0.1 Untested
119 2801 Philips/Simoco PRM8060 0.1 Alpha
120 2901 ADAT www.adat.ch ADT-200A 1.36 Beta
121 The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll‐
123 Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir‐
124 tual terminal window (cmd window on Microsoft Windows) or the output
125 can be piped to more(1) or less(1), e.g. “rigctl -l | more” to scroll
126 back up the list. The list is sorted numerically by model number since
127 Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are
128 grouped together.
129 rigctl reference
131 The complete reference for rigctl can be found in the rigctl(1) manual
132 page.
133
135 Identical in function to rigctl(1), rotctl(1) provides a means for
136 testing Hamlib functions useful for rotator control and QTH (Maidenhead
137 gridsquare system, see Maidenhead Locator System
138 ⟨https://en.wikipedia.org/wiki/Maidenhead_Locator_System⟩) locator com‐
139 putations. As rotators have a much narrower scope than radios, there
140 are fewer command line options and commands for rotctl.
141 Introduction to rotctl
143 rotctl(1) is a character based interactive program and a command line
144 program able to set or query a rotator's value with a single command.
145 rotctl is invoked from a shell command prompt with various options and
146 additional commands.
147 In its most simple use as a command line program, rotctl is used to set
149 azimuth position and (optionally) elevation by typing commands after
150 any rotctl options:
151 rotctl P 145.0 23.0
153 rotctl M 8 25
154 and then query those values:
156 rotctl p
158 Entering interactive mode is a simple matter of not placing any com‐
160 mands after any rotctl options:
161 rotctl
163 Entering interactive mode allows successive commands to be entered
165 without exiting rotctl. Interactive mode allows for command editing
166 and history recall through the use of the Readline
167 ⟨https://tiswww.case.edu/php/chet/readline/rltop.html⟩ library.
168 Interactive mode is indicated by the spartan prompt:
170 Rotator command:
172 Commands are given at the prompt:
174 Rotator command: M
176 Direction: 16
177 Speed: 60
178 Rotator command: p
180 Azimuth: 11.352000
181 Elevation: 0.000000
182 Rotator command: p
184 Azimuth: 27.594000
185 Elevation: 0.000000
186 Rotator command:
188 An additional prompt is printed when more information is required by
190 the command. For M above, rotctl prompted for the Direction and Speed
191 values. For p above, rotctl returned the Azimuth and Elevation values
192 without further prompts. The command prompt is returned after each
193 command invocation.
194 The above examples invoked rotctl without specifying a rotator model.
196 This is a feature where the Hamlib internal rotator model 1 dummy is
197 used instead. The dummy rotator provides a way to test Hamlib func‐
198 tions without the need for actual rotator hardware. However, to
199 develop back end capability for a given rotator, having the actual con‐
200 troller connected to the computer is necessary for debugging.
201 For example, to quickly set position for RotorEZ:
203 rotctl -m 401 -r /dev/rotor P 100.0 0.0
205 and to query the position:
207 rotctl -m 401 -r /dev/rotor p
209 100.000000
210 0.000000
211 The returned values do not have the prompt strings associated with
213 interactive mode as shown above.
214 The -m option takes a numeric value that corresponds to a given rotator
216 back end model. The -r option takes the path to the port device on
217 POSIX or the device name on Microsoft Windows.
218 Note: A complete list of supported rotator models may be seen by use of
220 the -l option:
221 rotctl -l
223 Rot # Mfg Model Version Status
224 1 Hamlib Dummy 0.5 Beta
225 2 Hamlib NET rotctl 0.3 Beta
226 201 Hamlib EasycommI 0.3 Beta
227 202 Hamlib EasycommII 0.3 Beta
228 .
229 .
230 .
231 1201 AMSAT IF-100 0.1 Untested
232 1301 LA7LKA ts7400 0.1 Beta
233 1401 Celestron NexStar 0.1 Untested
234 The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll‐
236 Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir‐
237 tual terminal window (cmd window on Microsoft Windows) or the output
238 can be piped to more(1) or less(1), e.g. “rotctl -l | more” to scroll
239 back up the list. The list is sorted numerically by model number since
240 Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are
241 grouped together.
242 rotctl reference
244 The complete reference for rotctl can be found in the rotctl(1) manual
245 page.
246
248 The rigctld(1) program is a network server that accepts the familiar
249 commands of rigctl(1) and provides the response data over a TCP/IP net‐
250 work socket to an application. In this manner an application can
251 access a rigctld instance from nearly anywhere (caveat, no security is
252 currently provided by rigctld). Applications using rigctld do not link
253 directly to Hamlib nor use its C API.
254 Introduction to rigctld
256 rigctld(1) communicates to a client through a TCP network socket using
257 text commands shared with rigctl(1). The protocol is simple; commands
258 are sent to rigctld on one line and rigctld responds to get commands
259 with the requested values, one per line, when successful, otherwise, it
260 responds with one line RPRT x, where x is a negative number indicating
261 the Hamlib error code. Commands that do not return values respond with
262 the line RPRT x, where x is zero when successful, otherwise a negative
263 number indicating the Hamlib error code. Each line is terminated with
264 a newline, \n, character. This protocol is primarily for use by the
265 NET rigctl (radio model 2) backend.
266 A separate Extended Response protocol extends the above behavior by
268 echoing the received command string as a header, any returned values as
269 a key: value pair, and the RPRT x string as the end of response marker
270 which includes the Hamlib success or failure value. Consider using
271 this protocol for clients that will interact with rigctld directly
272 through a TCP network socket.
273 Multiple radios can be controlled on different TCP ports by use of mul‐
275 tiple rigctld processes each listening on a unique TCP port. It is
276 hoped that rigctld will be especially useful for client authors using
277 languages such as Perl ⟨http://www.perl.org/⟩, Python
278 ⟨http://www.python.org/⟩, PHP ⟨http://php.net/⟩, Ruby ⟨http://www.ruby-
279 lang.org/en/⟩, TCL ⟨http://www.tcl.tk/⟩, and others.
280 rigctld reference
282 The complete reference for rigctld can be found in the rigctld(1) man‐
283 ual page.
284
286 The rotctld(1) program is a network server that accepts the familiar
287 commands of rotctl(1) and provides the response data over a TCP/IP net‐
288 work socket to an application. In this manner an application can
289 access a rotctld instance from nearly anywhere (caveat, no security is
290 currently provided by rotctld). Applications using rotctld do not link
291 directly to Hamlib nor use its C API.
292 Introduction to rotctld
294 rotctld(1) communicates to a client through a TCP network socket using
295 text commands shared with rotctl(1). The protocol is simple, commands
296 are sent to rotctld on one line and rotctld responds to get commands
297 with the requested values, one per line, when successful, otherwise, it
298 responds with one line RPRT x, where x is a negative number indicating
299 the Hamlib error code. Commands that do not return values respond with
300 the line RPRT x, where x is zero when successful, otherwise a negative
301 number indicating the Hamlib error code. Each line is terminated with
302 a newline, \n character. This protocol is primarily for use by the NET
303 rotctl (rotator model 2) backend.
304 A separate Extended Response protocol extends the above behavior by
306 echoing the received command string as a header, any returned values as
307 a key: value pair, and the RPRT x string as the end of response marker
308 which includes the Hamlib success or failure value. Consider using
309 this protocol for clients that will interact with rotctld directly
310 through a TCP network socket.
311 Multiple rotators can be controlled on different TCP ports by use of
313 multiple rotctld processes each listening on a unique TCP port. It is
314 hoped that rotctld will be especially useful for client authors using
315 languages such as Perl ⟨http://www.perl.org/⟩, Python
316 ⟨http://www.python.org/⟩, PHP ⟨http://php.net/⟩, Ruby ⟨http://www.ruby-
317 lang.org/en/⟩, TCL ⟨http://www.tcl.tk/⟩, and others.
318 rotctld reference
320 The complete reference for rotctld can be found in the rotctld(1) man‐
321 ual page.
322
324 rigmem may be used to backup and restore memory of radio transceivers
325 and receivers.
326 Introduction to rigmem
328 Backup and restore memory of radio transceivers and receivers. rigmem
329 accepts commands from the command line only.
330 rigmem reference
332 The complete reference for rigmem can be found in the rigmem(1) manual
333 page.
334
336 rigsmtr uses Hamlib to control a radio to measure S-Meter value versus
337 antenna azimuth.
338 Introduction to rigsmtr
340 rigsmtr rotates the antenna from minimum azimuth to maximum azimuth.
341 Every second, or time_step if specified in seconds, it retrieves the
342 signal strength. Azimuth in degrees and the corresponding S-Meter level
343 in dB relative to S9 are then printed on stdout.
344 To work correctly, rigsmtr needs a radio that could measure S-Meter and
346 a Hamlib backend that is able to retrieve it, connected to a Hamlib
347 supported rotator.
348 rigsmtr reference
350 The complete reference for rigsmtr can be found in the rigsmtr(1) man‐
351 ual page.
352
354 rigswr may be used to measure VSWR vs frequency.
355 Introduction to rigswr
357 rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing
358 Wave Ratio) over a frequency range.
359 It scans frequencies from start_freq to stop_freq with an optional
361 increment of freq_step (default step is 100 kHz). All values must be
362 entered as an integer in Hertz (cycles per second).
363 Note: rigswr assumes that start_freq is less than or equal to
365 stop_freq. If it is greater, rigswr will exit without doing anything.
366 For each frequency, rigswr transmits at 25% of total POWER during 0.5
368 second in CW mode and reads VSWR.
369 Frequency and the corresponding VSWR are then printed on stdout.
371 To work correctly, rigswr needs a radio that can measure VSWR and a
373 Hamlib backend that supports reading VSWR from the radio.
374 rigswr reference
376 The complete reference for rigswr can be found in the rigswr(1) manual
377 page.
378
380 This file is part of Hamlib, a project to develop a library that sim‐
381 plifies radio and rotator control functions for developers of software
382 primarily of interest to radio amateurs and those interested in radio
383 communications.
384 Copyright © 2001-2018 Hamlib Group (various contributors)
386 This is free software; see the file COPYING for copying conditions.
388 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
389 PARTICULAR PURPOSE.
390
392 less(1), more(1), rigctl(1), rigctld(1), rotctl(1), rotctld(1), rig‐
393 mem(1), rigsmtr(1), rigswr(1), hamlib(7), hamlib-primer(7)
394
396 Links to the Hamlib Wiki, Git repository, release archives, and daily
397 snapshot archives:
398 hamlib.org ⟨http://www.hamlib.org⟩.
400Hamlib 2018-05-27 HAMLIB-UTILITIES(7)