[amateur-radio-guide] Beginnings of hamlib documentation

John J. McDonough jjmcd at fedoraproject.org
Tue Mar 25 01:59:17 UTC 2014


commit 461e035e53d866b2316db6486f60369d2b1a6341
Author: John J. McDonough <jjmcd at fedoraproject.org>
Date:   Mon Mar 24 21:59:11 2014 -0400

    Beginnings of hamlib documentation

 en-US/Amateur_Radio_Guide.xml       |    2 +-
 en-US/images/rig-hamlib/hamlib1.png |  Bin 0 -> 9524 bytes
 en-US/images/rig-hamlib/hamlib2.png |  Bin 0 -> 9926 bytes
 en-US/images/rig-hamlib/hamlib4.png |  Bin 0 -> 11389 bytes
 en-US/images/rig-hamlib/hamlib5.png |  Bin 0 -> 9784 bytes
 en-US/rig-hamlib.xml                |  343 +++++++++++++++++++++++++++++++++++
 en-US/rig.xml                       |    4 +-
 7 files changed, 346 insertions(+), 3 deletions(-)
---
diff --git a/en-US/Amateur_Radio_Guide.xml b/en-US/Amateur_Radio_Guide.xml
index 3219462..45d30db 100644
--- a/en-US/Amateur_Radio_Guide.xml
+++ b/en-US/Amateur_Radio_Guide.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docarticle/xml/4.5/docarticlex.dtd" [
 ]>
 
-<article>
+<article status="draft">
   <xi:include href="Article_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
   <section id="intro">
     <title>Introduction</title>
diff --git a/en-US/images/rig-hamlib/hamlib1.png b/en-US/images/rig-hamlib/hamlib1.png
new file mode 100644
index 0000000..152f0dc
Binary files /dev/null and b/en-US/images/rig-hamlib/hamlib1.png differ
diff --git a/en-US/images/rig-hamlib/hamlib2.png b/en-US/images/rig-hamlib/hamlib2.png
new file mode 100644
index 0000000..ff99542
Binary files /dev/null and b/en-US/images/rig-hamlib/hamlib2.png differ
diff --git a/en-US/images/rig-hamlib/hamlib4.png b/en-US/images/rig-hamlib/hamlib4.png
new file mode 100644
index 0000000..3d4100a
Binary files /dev/null and b/en-US/images/rig-hamlib/hamlib4.png differ
diff --git a/en-US/images/rig-hamlib/hamlib5.png b/en-US/images/rig-hamlib/hamlib5.png
new file mode 100644
index 0000000..b59ec3d
Binary files /dev/null and b/en-US/images/rig-hamlib/hamlib5.png differ
diff --git a/en-US/rig-hamlib.xml b/en-US/rig-hamlib.xml
index fcdbce8..01522a5 100644
--- a/en-US/rig-hamlib.xml
+++ b/en-US/rig-hamlib.xml
@@ -5,6 +5,62 @@
 <section id="rig-hamlib">
   <title>hamlib</title>
   <para>
+    <package>hamlib</package> is a library to be used by other
+    programs to interface to radios and rotors.  However, since
+    <package>hamlib</package> maintains no configuration information
+    (type of rig, connection method, etc.)  itself, programs must
+    provide that configuration.
+  </para>
+  <para>
+    Som programs sigh as <application>fldigi</application> provide the
+    necessary <package>hamlib</package> information in a fashion
+    somewhat hidden from the user, but others
+    (<application>grig</application>,
+    <application>soundmodem</application>) require the user understand
+    <package>hamlib</package> configuration.  Even with
+    <application>fldigi</application>, advanced users may find it
+    necessary to provide <package>hamlib</package> commands.
+  </para>
+  <para>
+    While promarily for use with other programs,
+    <package>hamlib</package> includes a few applications which may
+    be used directly, including:
+    <itemizedlist spacing="compact">
+      <listitem>
+	<para>
+	  <application>rigctl</application> - allows for control of
+	  the rig from the command line
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <application>rigmem</application> - save and restore a
+	  radio's memories
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <application>rigswr</application> - measure SWR across a
+	  range of frequencies
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <application>rigsmtr</application> - collect S meter
+	  readings, when used with rotctl, show S reading versus rotor
+	  position 
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <application>rotctl</application> - control the rotor
+	</para>
+      </listitem>
+    </itemizedlist>
+    In addition, there are daemons provided for controllig the rig and rotor.
+  </para>
+<!--
+  <para>
     yum info as placeholder
 <screen>
 Description: Hamlib provides a standardised programming interface that
@@ -16,4 +72,291 @@ Description: Hamlib provides a standardised programming interface that
            : interactive interface.
 </screen>
   </para>
+-->
+  <para>
+    The various <package>hamlib</package> applications require certain
+    switches to describe the rig and its connection, and most take a
+    number of commands.
+      <table frame="all">
+        <title>Rig description switches</title>
+        <tgroup cols="2">
+	  <colspec colnum="1" colname="c1" colwidth="2*" />
+	  <colspec colnum="2" colname="c2" colwidth="3*" />
+          <thead>
+            <row>
+              <entry>Switch</entry>
+              <entry>Meaning</entry>
+            </row>
+          </thead>
+          <tbody>
+	    <row>
+	      <entry><command>-m, --model=id</command></entry>
+	      <entry>Select radio model number. See model list (use
+	      '<command>rigctl -l</command>').</entry>
+	    </row>
+	    <row>
+	      <entry><command>-r, --rig-file=device</command></entry>
+	      <entry>Use device as the file name of the port the radio
+	      is connected.  Often a serial port, but could be a USB
+	      to serial adapter.  Typically
+	      <filename>/dev/ttyS0</filename>,
+	      <filename>/dev/ttyS1</filename>,
+	      <filename>/dev/ttyUSB0</filename>, etc.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-p, --ptt-file=device</command></entry>
+	      <entry>Use device as the file name of the Push-To-Talk
+	      device using a device file as described above.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-d, --dcd-file=device</command></entry>
+	      <entry>Use device as the file name of the Data Carrier
+	      Detect device using a device file as described
+	      above.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-P, --ptt-type=type</command></entry>
+	      <entry>Use type of Push-To-Talk device.  Supported types
+	      are RIG, DTR, RTS, PARALLEL, NONE, overriding PTT type
+	      defined in the rig's backend.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-D, --dcd-type=type</command></entry>
+	      <entry>Use type of Data Carrier Detect device.
+	      Supported types are RIG, DSR, CTS, CD, PARALLEL,
+	      NONE.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-s, --serial-speed=baud</command></entry>
+	      <entry>Set serial speed to baud rate. Uses maximum
+	      serial speed from rig backend capabilities as the
+	      default.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-c, --civaddr=id</command></entry>
+	      <entry>Use id as the CI-V address to communicate with
+	      the rig. Only useful for Icom rigs.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-t, --send-cmd-term=char</command></entry>
+	      <entry>Change the termination char for text protocol
+	      when using the send_cmd command.  The default value is
+	      &lt;CR&gt; (0x0d).  Non ASCII printable characters can
+	      be specified as an ASCII number, in hexadecimal format,
+	      prepended with 0x. You may pass an empty string for no
+	      termination char. The string '<command>-1</command>'
+	      tells rigctl to switch to binary protocol. See the
+	      send_cmd command for further explanation.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-L, --show-conf</command></entry>
+	      <entry>List all config parameters for the radio defined
+	      with <command>-m</command> above.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-C,
+	      --set-conf=parm=val[,parm=val]</command>
+	      </entry>
+	      <entry>Set config parameter.
+	      e.g. <command>stop_bits=2</command>.  Use
+	      <command>-L</command> option for a list.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-l, --list</command></entry>
+	      <entry>List all model numbers defined in Hamlib and
+	      exit.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-u, --dump-caps</command></entry>
+	      <entry>Dump capabilities for the radio defined with
+	      <command>-m</command> above and exit.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-o, --vfo</command></entry>
+	      <entry>Set vfo mode, requiring an extra VFO argument in
+	      front of each appropriate command.  Otherwise, VFO_CURR
+	      is assumed when this option is not set.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-v, --verbose</command></entry>
+	      <entry>Set verbose mode, cumulative.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-h, --help</command></entry>
+	      <entry>Show summary of these options and exit.</entry>
+	    </row>
+	    <row>
+	      <entry><command>-V, --version</command></entry>
+	      <entry>Show version of rigctl and exit.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+  </para>
+  <para>
+    For example, to communicate with an Icom 7000 on
+    <filename>/dev/ttyUSB0</filename> at 19,200 baud:
+<screen>
+rigctl -m 360 -r /dev/ttyUSB0 -s 19200 -c 0x70
+</screen>
+  </para>
+  <para>
+    <application>rigtcl</application> can accept a large number of
+    commands, either on the command line or in interactive mode.  The
+    following table lists some of the more commom commands.  For more
+    details see <command>man rigctl</command>.
+      <table frame="all">
+        <title>Rig description switches</title>
+        <tgroup cols="2">
+	  <colspec colnum="1" colname="c1" colwidth="2*" />
+	  <colspec colnum="2" colname="c2" colwidth="4*" />
+          <thead>
+            <row>
+              <entry>Command</entry>
+              <entry>Meaning</entry>
+            </row>
+          </thead>
+          <tbody>
+	    <row>
+	      <entry><command>F, set_freq 'Frequency'</command></entry>
+	      <entry>Set 'Frequency', in Hz.</entry>
+	    </row>
+	    <row>
+	      <entry><command>f, get_freq</command></entry>
+	      <entry>Get 'Frequency', in Hz.</entry>
+	    </row>
+	    <row>
+	      <entry><command>M, set_mode 'Mode' 'Passband'</command></entry>
+	      <entry>Set 'Mode': USB, LSB, CW, CWR, RTTY, RTTYR, AM,
+	      FM, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB,
+	      FAX, SAM, SAL, SAH, DSB.</entry>
+	    </row>
+	    <row>
+	      <entry><command>m, get_mode</command></entry>
+	      <entry>Get 'Mode' 'Passband'.</entry>
+	    </row>
+	    <row>
+	      <entry><command>V, set_vfo 'VFO'</command></entry>
+	      <entry>Set 'VFO': VFOA, VFOB, VFOC, currVFO, VFO, MEM,
+	      Main, Sub, TX, RX.</entry>
+	    </row>
+	    <row>
+	      <entry><command>v, get_vfo</command></entry>
+	      <entry>Get current 'VFO'.</entry>
+	    </row>
+	    <row>
+	      <entry><command>R, set_rptr_shift 'Rptr
+	      Shift'</command></entry>
+	      <entry>Set 'Rptr Shift': "+", "-" or something else for
+	      none.</entry>
+	    </row>
+	    <row>
+	      <entry><command>r, get_rptr_shift</command></entry>
+	      <entry>Get 'Rptr Shift'.  Returns "+", "-" or
+	      "None".</entry>
+	    </row>
+	    <row>
+	      <entry><command>O, set_rptr_offs 'Rptr
+	      Offset'</command></entry>
+	      <entry>Set 'Rptr Offset', in Hz.</entry>
+	    </row>
+	    <row>
+	      <entry><command>o, get_rptr_offs</command></entry>
+	      <entry>Get 'Rptr Offset', in Hz.</entry>
+	    </row>
+	    <row>
+	      <entry><command>U, set_func 'Func' 'Func
+	      Status'</command></entry>
+	      <entry> Set 'Func' 'Func Status'.  Func is one of: FAGC,
+	      NB, COMP, VOX, TONE, TSQL, SBKIN, FBKIN, ANF, NR, AIP,
+	      APF, MON, MN, RF, ARO, LOCK, MUTE, VSC, REV, SQL, ABM,
+	      BC, MBC, AFC, SATMODE, SCOPE, RESUME, TBURST,
+	      TUNER.</entry>
+	    </row>
+	    <row>
+	      <entry><command>u, get_func</command></entry>
+	      <entry>Get 'Func' 'Func Status'.</entry>
+	    </row>
+	    <row>
+	      <entry><command>L, set_level 'Level' 'Level Value'</command></entry>
+	      <entry>Set 'Level' and 'Level Value'.  Level is one of:
+	      PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR, PBT_IN,
+	      PBT_OUT, CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF,
+	      COMP, AGC (0:OFF, 1:SUPERFAST, 2:FAST, 3:SLOW, 4:USER,
+	      5:MEDIUM, 6:AUTO), BKINDL, BAL, METER, VOXGAIN, ANTIVOX,
+	      SLOPE_LOW, SLOPE_HIGH, RAWSTR, SWR, ALC, STRENGTH.  The
+	      Level Value can be a float or an integer.</entry>
+	    </row>
+	    <row>
+	      <entry><command>l, get_level</command></entry>
+	      <entry>Get 'Level' 'Level Value'.  Returns Level as a
+	      string from set_level above and Level value as a float
+	      or integer.</entry>
+	    </row>
+	    <row>
+	      <entry><command></command></entry>
+	      <entry></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+  </para>
+  <para>
+    For example, the following command asks to display the frequency
+    and mode.  The mode display always also shows the bandwidth:
+    <figure float="0"><title>rigctl - show mode and frequency</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata scale="99" scalefit="1" 
+                   fileref="images/rig-hamlib/hamlib2.png" 
+                   format="PNG"/>
+      </imageobject>
+      <textobject>
+        <para>
+          rigctl
+        </para>
+      </textobject>
+    </mediaobject>
+    </figure>
+  </para>
+  <para>
+    The following example asks whether the tone squelch is on and what
+    are the volume and squelch control settings:
+    <figure float="0"><title>rigctl - show tone squelch, AF and
+    Squelch controls</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata scale="99" scalefit="1" 
+                   fileref="images/rig-hamlib/hamlib4.png" 
+                   format="PNG"/>
+      </imageobject>
+      <textobject>
+        <para>
+          rigctl
+        </para>
+      </textobject>
+    </mediaobject>
+    </figure>
+  </para>
+  <para>
+    The radio can be controlled as well.  In the following example the
+    radio is set to CW mode with a 500 Hz filter, and the frequency is
+    set to 3.563 MHz:
+    <figure float="0"><title>rigctl - set frequency and mode</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata scale="99" scalefit="1" 
+                   fileref="images/rig-hamlib/hamlib5.png" 
+                   format="PNG"/>
+      </imageobject>
+      <textobject>
+        <para>
+          rigctl
+        </para>
+      </textobject>
+    </mediaobject>
+    </figure>
+  </para>
+
+
 </section>
diff --git a/en-US/rig.xml b/en-US/rig.xml
index 56ef8d3..6f04b03 100644
--- a/en-US/rig.xml
+++ b/en-US/rig.xml
@@ -8,8 +8,8 @@
     This section describes rig control applications.
   </para>
   <xi:include href="rig-chirp.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />  <xi:include href="rig-grig.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<!--
+
   <xi:include href="rig-hamlib.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
--->
+
 
 </section>


More information about the docs-commits mailing list