Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HAMLIB-UTILITIES(7)	   Hamlib Information Manual	   HAMLIB-UTILITIES(7)

NAME
       hamlib-utilties - radio and rotator control utilities of	Hamlib

DESCRIPTION
       Included	 with  the  Hamlib  distribution are several utility programs.
       Besides providing a way for developers to test new code and bug	fixes,
       the  programs  also offer a reference implementation for	interfacing to
       the Hamlib library functions both through the C API  (Application  Pro-
       gramming	Interface) and offering	a network accessible API.

       This page summarizes the	two test programs, rigctl(1) for testing radio
       back ends and rotctl(1) for testing rotator back	ends and the two  net-
       work  daemons,  rigctld(1)  and rotcltd(1) for radio and	rotator	access
       via network sockets.  Also included are three  demonstation  utilities,
       rigmem(1),  rigsmtr(1), and rigswr(1) which provide functional examples
       of how Hamlib may be used to accomplish various tasks.

rigctl
       rigctl(1) is the	most frequently	used Hamlib utility.  As the other ctl
       utilities share many of the same	characteristics, much of the introduc-
       tory information	presented in this section is applicable	to  the	 other
       utility programs.

   Introduction	to rigctl
       Most  likely  the  first	of the Hamlib utility programs that is used is
       rigctl(1).  rigctl is a character based interactive program and a  com-
       mand  line  program  able to set	or query a radio's value with a	single
       command.	 rigctl	is invoked from	a shell	command	 prompt	 with  various
       options and additional commands.

       In its most simple use as a command line	program, rigctl	is used	to set
       frequency and mode by typing commands after any rigctl options:

	    rigctl F 14205000
	    rigctl M USB 2400

       and then	query those values:

	    rigctl f
	    rigctl m

       Entering	interactive mode is a simple matter of not  placing  any  com-
       mands after any rigctl options:

	    rigctl

       Entering	 interactive  mode  allows  successive	commands to be entered
       without exiting rigctl.	Recent additions to rigctl allow command edit-
       ing    and    history	recall	  through    use   of	the   Readline
       <https://tiswww.case.edu/php/chet/readline/rltop.html> library.

       Interactive mode	is indicated by	the spartan prompt:

	    Rig	command:

       Commands	are given at the prompt	and follow the general rule that upper
       case letters set	a value	and lower case letters query a value:

	    Rig	command: M
	    Mode: USB
	    Passband: 2500

	    Rig	command: m
	    Mode: USB
	    Passband: 2500

	    Rig	command:

       An  additional  prompt  is printed when more information	is required by
       the command.  For M above, rigctl prompted for the  Mode	 and  Passband
       values.	 For  m	 above,	 rigctl	 returned the Mode and Passband	values
       without further prompts.	 The command prompt  is	 returned  after  each
       command invocation.

       The  above  examples  invoked  rigctl without specifying	a radio	model.
       This is a feature where the Hamlib internal radio model 1 dummy is used
       instead.	 The dummy radio provides a way	to test	Hamlib functions with-
       out the need for	actual radio hardware.	However, to develop the	Hamlib
       backend capability for a	given radio, having the	actual radio connected
       to the computer is necessary for	debugging.

       For example, to quickly set frequency on	an Elecraft K3:

	    rigctl -m 229 -r /dev/rig F	3900000

       and to query the	frequency and then mode:

	    rigctl -m 229 -r /dev/rig f
	    3900000

	    rigctl -m 229 -r /dev/rig m
	    LSB
	    2000

       Note: the returned values do not	have  the  prompt  strings  associated
       with interactive	mode as	shown above.

       The  -m	option takes a numeric value that corresponds to a given radio
       back end	model.	The -r option takes the	path to	 the  port  device  on
       POSIX and the device name on Microsoft Windows.

       Note:  A	 complete list of supported radio models may be	seen by	use of
       the -l option:

	    rigctl -l
	     Rig #  Mfg		     Model	   Version    Status
		 1  Hamlib	     Dummy	   0.5	      Beta
		 2  Hamlib	     NET rigctl	   0.3	      Beta
	       101  Yaesu	     FT-847	   0.5	      Beta
	       103  Yaesu	     FT-1000D	   0.0.6      Alpha
	    .
	    .
	    .
	      2702  Rohde&Schwarz    EB200	   0.1	      Untested
	      2801  Philips/Simoco   PRM8060	   0.1	      Alpha
	      2901  ADAT www.adat.ch ADT-200A	   1.36	      Beta

       The list	is long	so use Shift-PageUp/Shift-PageDown on  Linux,  Scroll-
       Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir-
       tual terminal window (cmd window	on Microsoft Windows)  or  the	output
       can  be	piped to more(1) or less(1), e.g. "rigctl -l | more" to	scroll
       back up the list.  The list is sorted numerically by model number since
       Hamlib  1.2.15.1.   Model numbers of a manufacturer/protocol family are
       grouped together.

   rigctl reference
       The complete reference for rigctl can be	found in the rigctl(1)	manual
       page.

rotctl
       Identical  in  function	to  rigctl(1),	rotctl(1) provides a means for
       testing Hamlib functions	useful for rotator control and QTH (Maidenhead
       gridsquare      system,	    see	     Maidenhead	    Locator	System
       <https://en.wikipedia.org/wiki/Maidenhead_Locator_System>) locator com-
       putations.   As	rotators have a	much narrower scope than radios, there
       are fewer command line options and commands for rotctl.

   Introduction	to rotctl
       rotctl(1) is a character	based interactive program and a	 command  line
       program	able  to set or	query a	rotator's value	with a single command.
       rotctl is invoked from a	shell command prompt with various options  and
       additional commands.

       In its most simple use as a command line	program, rotctl	is used	to set
       azimuth position	and (optionally) elevation by  typing  commands	 after
       any rotctl options:

	    rotctl P 145.0 23.0
	    rotctl M 8 25

       and then	query those values:

	    rotctl p

       Entering	 interactive  mode  is a simple	matter of not placing any com-
       mands after any rotctl options:

	    rotctl

       Entering	interactive mode allows	 successive  commands  to  be  entered
       without	exiting	 rotctl.   Interactive mode allows for command editing
       and   history   recall	through	   the	  use	 of    the    Readline
       <https://tiswww.case.edu/php/chet/readline/rltop.html> library.

       Interactive mode	is indicated by	the spartan prompt:

	    Rotator command:

       Commands	are given at the prompt:

	    Rotator command: M
	    Direction: 16
	    Speed: 60

	    Rotator command: p
	    Azimuth: 11.352000
	    Elevation: 0.000000

	    Rotator command: p
	    Azimuth: 27.594000
	    Elevation: 0.000000

	    Rotator command:

       An  additional  prompt  is printed when more information	is required by
       the command.  For M above, rotctl prompted for the Direction and	 Speed
       values.	 For p above, rotctl returned the Azimuth and Elevation	values
       without further prompts.	 The command prompt  is	 returned  after  each
       command invocation.

       The  above  examples invoked rotctl without specifying a	rotator	model.
       This is a feature where the Hamlib internal rotator model  1  dummy  is
       used  instead.	The  dummy rotator provides a way to test Hamlib func-
       tions without the need for actual rotator hardware.   However,  to  de-
       velop  back  end	capability for a given rotator,	having the actual con-
       troller connected to the	computer is necessary for debugging.

       For example, to quickly set position for	RotorEZ:

	    rotctl -m 401 -r /dev/rotor	P 100.0	0.0

       and to query the	position:

	    rotctl -m 401 -r /dev/rotor	p
	    100.000000
	    0.000000

       The returned values do not have the prompt strings associated with  in-
       teractive mode as shown above.

       The -m option takes a numeric value that	corresponds to a given rotator
       back end	model.	The -r option takes the	path to	 the  port  device  on
       POSIX or	the device name	on Microsoft Windows.

       Note: A complete	list of	supported rotator models may be	seen by	use of
       the -l option:

	    rotctl -l
	     Rot #  Mfg		     Model	   Version    Status
		 1  Hamlib	     Dummy	   0.5	      Beta
		 2  Hamlib	     NET rotctl	   0.3	      Beta
	       201  Hamlib	     EasycommI	   0.3	      Beta
	       202  Hamlib	     EasycommII	   0.3	      Beta
	    .
	    .
	    .
	      1201  AMSAT	     IF-100	   0.1	      Untested
	      1301  LA7LKA	     ts7400	   0.1	      Beta
	      1401  Celestron	     NexStar	   0.1	      Untested

       The list	is long	so use Shift-PageUp/Shift-PageDown on  Linux,  Scroll-
       Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir-
       tual terminal window (cmd window	on Microsoft Windows)  or  the	output
       can  be	piped to more(1) or less(1), e.g. "rotctl -l | more" to	scroll
       back up the list.  The list is sorted numerically by model number since
       Hamlib  1.2.15.1.   Model numbers of a manufacturer/protocol family are
       grouped together.

   rotctl reference
       The complete reference for rotctl can be	found in the rotctl(1)	manual
       page.

rigctld
       The  rigctld(1)	program	 is a network server that accepts the familiar
       commands	of rigctl(1) and provides the response data over a TCP/IP net-
       work  socket  to	an application.	 In this manner	an application can ac-
       cess a rigctld instance from nearly anywhere (caveat,  no  security  is
       currently provided by rigctld).	Applications using rigctld do not link
       directly	to Hamlib nor use its C	API.

   Introduction	to rigctld
       rigctld(1) communicates to a client through a TCP network socket	 using
       text  commands shared with rigctl(1).  The protocol is simple; commands
       are sent	to rigctld on one line and rigctld responds  to	 get  commands
       with the	requested values, one per line,	when successful, otherwise, it
       responds	with one line RPRT x, where x is a negative number  indicating
       the Hamlib error	code.  Commands	that do	not return values respond with
       the line	RPRT x,	where x	is zero	when successful, otherwise a  negative
       number  indicating the Hamlib error code.  Each line is terminated with
       a newline, \n, character.  This protocol	is primarily for  use  by  the
       NET rigctl (radio model 2) backend.

       A  separate  Extended  Response	protocol extends the above behavior by
       echoing the received command string as a	header,	any returned values as
       a  key: value pair, and the RPRT	x string as the	end of response	marker
       which includes the Hamlib success or  failure  value.   Consider	 using
       this  protocol  for  clients  that  will	interact with rigctld directly
       through a TCP network socket.

       Multiple	radios can be controlled on different TCP ports	by use of mul-
       tiple  rigctld  processes  each	listening on a unique TCP port.	 It is
       hoped that rigctld will be especially useful for	client	authors	 using
       languages     such     as     Perl    <http://www.perl.org/>,	Python
       <http://www.python.org/>, PHP <http://php.net/>,	Ruby <http://www.ruby-
       lang.org/en/>, TCL <http://www.tcl.tk/>,	and others.

   rigctld reference
       The  complete reference for rigctld can be found	in the rigctld(1) man-
       ual page.

rotctld
       The rotctld(1) program is a network server that	accepts	 the  familiar
       commands	of rotctl(1) and provides the response data over a TCP/IP net-
       work socket to an application.  In this manner an application  can  ac-
       cess  a	rotctld	 instance from nearly anywhere (caveat,	no security is
       currently provided by rotctld).	Applications using rotctld do not link
       directly	to Hamlib nor use its C	API.

   Introduction	to rotctld
       rotctld(1)  communicates	to a client through a TCP network socket using
       text commands shared with rotctl(1).  The protocol is simple,  commands
       are  sent  to  rotctld on one line and rotctld responds to get commands
       with the	requested values, one per line,	when successful, otherwise, it
       responds	 with one line RPRT x, where x is a negative number indicating
       the Hamlib error	code.  Commands	that do	not return values respond with
       the  line RPRT x, where x is zero when successful, otherwise a negative
       number indicating the Hamlib error code.	 Each line is terminated  with
       a newline, \n character.	 This protocol is primarily for	use by the NET
       rotctl (rotator model 2)	backend.

       A separate Extended Response protocol extends  the  above  behavior  by
       echoing the received command string as a	header,	any returned values as
       a key: value pair, and the RPRT x string	as the end of response	marker
       which  includes	the  Hamlib  success or	failure	value.	Consider using
       this protocol for clients that  will  interact  with  rotctld  directly
       through a TCP network socket.

       Multiple	 rotators  can	be controlled on different TCP ports by	use of
       multiple	rotctld	processes each listening on a unique TCP port.	It  is
       hoped  that  rotctld will be especially useful for client authors using
       languages    such    as	   Perl	    <http://www.perl.org/>,	Python
       <http://www.python.org/>, PHP <http://php.net/>,	Ruby <http://www.ruby-
       lang.org/en/>, TCL <http://www.tcl.tk/>,	and others.

   rotctld reference
       The complete reference for rotctld can be found in the rotctld(1)  man-
       ual page.

rigmem
       rigmem  may  be used to backup and restore memory of radio transceivers
       and receivers.

   Introduction	to rigmem
       Backup and restore memory of radio transceivers and receivers.	rigmem
       accepts commands	from the command line only.

   rigmem reference
       The  complete reference for rigmem can be found in the rigmem(1)	manual
       page.

rigsmtr
       rigsmtr uses Hamlib to control a	radio to measure S-Meter value	versus
       antenna azimuth.

   Introduction	to rigsmtr
       rigsmtr	rotates	 the  antenna from minimum azimuth to maximum azimuth.
       Every second, or	time_step if specified in seconds,  it	retrieves  the
       signal strength.	Azimuth	in degrees and the corresponding S-Meter level
       in dB relative to S9 are	then printed on	stdout.

       To work correctly, rigsmtr needs	a radio	that could measure S-Meter and
       a  Hamlib  backend  that	 is able to retrieve it, connected to a	Hamlib
       supported rotator.

   rigsmtr reference
       The complete reference for rigsmtr can be found in the rigsmtr(1)  man-
       ual page.

rigswr
       rigswr may be used to measure VSWR vs frequency.

   Introduction	to rigswr
       rigswr uses Hamlib to control a radio to	measure	VSWR (Voltage Standing
       Wave Ratio) over	a frequency range.

       It scans	frequencies from start_freq to stop_freq with an optional  in-
       crement of freq_step (default step is 100 kHz).	All values must	be en-
       tered as	an integer in Hertz (cycles per	second).

       Note:  rigswr  assumes  that  start_freq	 is  less  than	 or  equal  to
       stop_freq.  If it is greater, rigswr will exit without doing anything.

       For  each  frequency, rigswr transmits at 25% of	total POWER during 0.5
       second in CW mode and reads VSWR.

       Frequency and the corresponding VSWR are	then printed on	stdout.

       To work correctly, rigswr needs a radio that can	 measure  VSWR	and  a
       Hamlib backend that supports reading VSWR from the radio.

   rigswr reference
       The  complete reference for rigswr can be found in the rigswr(1)	manual
       page.

COPYING
       This file is part of Hamlib, a project to develop a library  that  sim-
       plifies	radio and rotator control functions for	developers of software
       primarily of interest to	radio amateurs and those interested  in	 radio
       communications.

       Copyright (C) 2001-2018 Hamlib Group (various contributors)

       This  is	 free  software;  see the file COPYING for copying conditions.
       There is	NO warranty; not even for MERCHANTABILITY  or  FITNESS	FOR  A
       PARTICULAR PURPOSE.

SEE ALSO
       less(1),	 more(1),  rigctl(1),  rigctld(1), rotctl(1), rotctld(1), rig-
       mem(1), rigsmtr(1), rigswr(1), hamlib(7), hamlib-primer(7)

COLOPHON
       Links to	the Hamlib Wiki, Git repository, release archives,  and	 daily
       snapshot	archives:

	      hamlib.org <http://www.hamlib.org>.

Hamlib				  2018-05-27		   HAMLIB-UTILITIES(7)

NAME | DESCRIPTION | rigctl | rotctl | rigctld | rotctld | rigmem | rigsmtr | rigswr | COPYING | SEE ALSO | COLOPHON

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hamlib-utilities&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help