Provided by: libhamlib-utils_3.3-5_amd64 bug

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 Programming 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 network 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 introductory 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 command 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 commands after any  rigctl
       options:

            rigctl

       Entering interactive mode allows successive commands to be entered without exiting rigctl.
       Recent additions to rigctl allow command editing 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  without 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,   ScrollLock   then
       PageUp/PageDown  on  Free  BSD,  or  use the scrollbar to the virtual 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
       computations.  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 commands 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 functions without the  need  for  actual  rotator  hardware.
       However,  to develop back end capability for a given rotator, having the actual controller
       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  interactive  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,  ScrollLock  then
       PageUp/PageDown on Free BSD, or use the scrollbar to  the  virtual  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 network socket to an application.  In this
       manner an application can access 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 multiple 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) manual 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 network socket to an  application.   In  this
       manner  an  application  can  access  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) manual 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) manual 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 increment of freq_step
       (default step is 100 kHz).  All values must be entered 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  simplifies  radio  and
       rotator  control  functions  for  developers  of  software  primarily of interest to radio
       amateurs and those interested in radio communications.

       Copyright © 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), rigmem(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⟩.