/******************************************************************************
 * Copyright (C) 2014 David Freese, W1HKJ,
 *               2014 Robert Stiles, KK5VD
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby
 * granted. No representations are made about the suitability of this software
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 * Requires Doxygen for HTML output
 * plus LiveTeX (LaTeX) for PDF output
 *
 */


/*!

\mainpage FLRIG Users Manual - Version 1.3

\tableofcontents

<center>
\image latex flriglogo.png "" width=0.5in
\image html flriglogo.png ""
</center>

<!--FLRIG User Manual-->
\section sFlrigDesc Transceiver Control

FLRIG is a transceiver control program designed to be used either stand
alone or as an adjunct to FLDIGI.  The supported transceivers all have some
degree of CAT.  The FLRIG user interface changes to accommodate the degree
of CAT support available for the transceiver in use.

Three different main dialog aspect ratios can be selected to suit the
computer screen dimensions and operator preferences.  The wide aspect
ratio can be resized horizontally.  The narrow aspect ratios are fixed
in width and height.

<center>
\image latex IC7100-ui-small.png "" width=6in
\image html IC7100-ui-small.png ""
</center>
<br>

<center>
\image latex IC7100-ui-narrow.png "" width=4.3in
\image html IC7100-ui-narrow.png ""
</center>
<br>

<center>
\image latex IC7100-ui-wide.png "" width=4.3in
\image html IC7100-ui-wide.png ""
</center>
<br>

A fourth interface is available for all transceivers.  It is suitable for use on
a touch screen

<center>
\image latex ft-991a/FT-991A-ui-touch.png "Shown at 75% of full size" width=5in
\image html ft-991a/FT-991A-ui-touch.png "Shown at 75% of full size"
</center>
<br>

The back end control code for each transceiver is unique to FLRIG. No
additional libraries or definition files are required.

\section sSupportedTRX Supported Transceivers

<center>
| Elecraft          |Icom                                  |Kenwood                        |Ten-Tec                  | Yaesu                          | Other                           |
|:-----------------:|:------------------------------------:|:-----------------------------:|:-----------------------:|:------------------------------:|:-------------------------------:|
|\ref ek_k2_a "K2"  |\ref icom_703_a "IC-703"              |\ref kwd_ts140_a "TS 140"      |\ref tt_516_a   "TT 516" |\ref yaesu_100d_a "FT 100D"     |\ref o_pcr1000_a "PCR 1000"      |
|\ref ek_k3_a "K3"  |\ref icom_706mk2g_a "IC 706 MK IIG"   |\ref kwd_ts450s_a "TS 450"     |\ref tt_535_a   "TT 535" |\ref yaesu_450_a "FT-450"       |\ref o_ray152_a  "RAY 152"       |
|\ref ek_kx3_a "KX3"|\ref icom_718_a "IC-718"              |\ref kwd_ts480hx_a "TS 480HX"  |\ref tt_538_a   "TT 538" |\ref yaesu_450d_a "FT-450D"     |\ref o_Xiegu-5105 "Xiegu 5105"   |
|<br>               |\ref icom_728_a "IC 728"              |\ref kwd_ts480sat_a "TS 480SAT"|\ref tt_550_a   "TT 550" |\ref yaesu_747gx_a "FT 747GX"   |\ref o_Xiegu-G90 "Xiegu G90"     |
|<br>               |\ref icom_735_a "IC 735"              |\ref kwd_ts570_a   "TS 570"    |\ref tt_omni6_a "TT 563" |\ref yaesu_767_a  "FT 767"      |<br>                             |
|<br>               |\ref icom_746_a "IC 746"              |\ref kwd_ts590s_a  "TS 590S"   |\ref tt_566_a   "TT 566" |\ref yaesu_817_a "FT 817"       |<br>                             |
|<br>               |\ref icom_746pro_a "IC 746 Pro"       |\ref kwd_ts590sg_a  "TS 590SG" |\ref tt_omni7_a "TT 588" |\ref yaesu_847_a "FT 847"       |<br>                             |
|<br>               |\ref icom_756pro2_a "IC 756 Pro II"   |\ref kwd_ts990_a   "TS 990"    |\ref tt_599_a   "TT 599" |\ref yaesu_857d_a "FT 857D"     |<br>                             |
|<br>               |\ref icom_756pro3_a "IC 756 Pro III"  |\ref kwd_ts2000_a  "TS 2000"   |<br>                     |\ref yaesu_897d_a "FT 897D"     |<br>                             |
|<br>               |\ref icom_910h_a "IC 910H"            |<br>                           |<br>                     |\ref yaesu_950_a "FT-950"       |<br>                             |
|<br>               |\ref icom_7000_a "IC 7000"            |<br>                           |<br>                     |\ref yaesu_991 "FT-991"         |<br>                             |
|<br>               |\ref icom_7100_a "IC 7100"            |<br>                           |<br>                     |\ref yaesu_991A "FT-991A"       |<br>                             |
|<br>               |\ref icom_7200_a "IC 7200"            |<br>                           |<br>                     |\ref yaesu_1000mp_a "FT-1000MP" |<br>                             |
|<br>               |\ref icom_7300_a "IC 7300"            |<br>                           |<br>                     |\ref yaesu_2000_a "FT 2000"     |<br>                             |
|<br>               |\ref icom_7410_a "IC 7410"            |<br>                           |<br>                     |\ref yaesu_1200dx_a "FTdx1200"  |<br>                             |
|<br>               |\ref icom_7600_a "IC 7600"            |<br>                           |<br>                     |\ref yaesu_3000dx_a "FTdx3000"  |<br>                             |
|<br>               |\ref icom_7610_a "IC 7610"            |<br>                           |<br>                     |\ref yaesu_3000dx_a "FTdx3000"  |<br>                             |
|<br>               |\ref icom_7700_a "IC 7700"            |<br>                           |<br>                     |\ref yaesu_9000dx_a "FTdx9000"  |<br>                             |
|<br>               |\ref icom_7610_a "IC 7610"            |<br>                           |<br>                     |<br>                            |<br>                             |
|<br>               |\ref icom_7700_a "IC 7700"            |<br>                           |<br>                     |<br>                            |<br>                             |
|<br>               |\ref icom_7851_a "IC 7851"            |<br>                           |<br>                     |<br>                            |<br>                             |
|<br>               |\ref icom_9100_a "IC 9100"            |<br>                           |<br>                     |<br>                            |<br>                             |
|<br>               |\ref icom_9700_a "IC 9700"            |<br>                           |<br>                     |<br>                            |<br>                             |
|<br>               |\ref icom_f8101 "IC F8101"            |<br>                           |<br>                     |<br>                            |<br>                             |
</center> 

\section sSetUp Setup

Select the transceiver with the "Config / Setup / Transceiver" menu item.

<center>
\image latex menus/config-setup-menu.png "" width=1.6in
\image html menus/config-setup-menu.png ""
</center>
<br>

Each of the menu items will open the configuration dialog to the respecive tab:
<ul>
	<li><b>Transceiver</b> - select transceiver and configure serial i/o parameters</li>
	<li><b>tcpip</b> - configure interface to a remote tcpip/serial controlled transceiver</li>
	<li><b>PTT</b> - configure PTT</li>
	<li><b>AUX</b> - configure separate auxiliary serial ports (if used)</li>
	<li><b>Polling</b> - select and configure transceiver parameters to poll</li>
	<li><b>Trace</b> - select and display program execution paths</li>
	<li><b>Restore</b> - select and configure transceiver parameters to read and restore</li>
</ul>
<br>

\subsection ssXcvrSelect Xcvr Select

<center>
\image latex config/xcvr.png "I/O Ports - Xcvr" width=4.9in
\image html config/xcvr.png "I/O Ports - Xcvr"
</center>
<br>

Select the rig in use from the "Rig" combo box.

The default values associated with that transceiver will be preset for you.
These have been verified by the test team but might require some tweaking for
your particular h/w.

\subsection ssPTT Configure PTT

<center>
\image latex config/ptt.png "I/O Ports - PTT" width=4.9in
\image html config/ptt.png "I/O Ports - PTT"
</center>
<br>

Select CAT PTT if your transceiver supports a CAT command for PTT on/off.  This
control will default to checked if CAT PTT is supported.

You may prefer to use h/w PTT signaling instead of CAT PTT.  The h/w PTT may be
shared with the CAT serial port.  Note that both RTS/CTS handshake and RTS PTT
cannot both be used on a single serial port.

If your serial connection is a CI-V device you might need to check "Echo"
and also set either RTS or DTR to +12 if CI-V power is derived from the
serial port.

Your PTT h/w control may also make use of a second serial port.  If that port
is the secondary serial port of the SCU-17 then you must also enable the "Serial Port is SCU-17 auxiliary"
control.

\subsection ssAUX Configure auxiliary ports
<center>
\image latex config/aux.png "I/O Ports - Aux" width=4.9in
\image html config/aux.png "I/O Ports - Aux"
</center>
<br>

<center>
\image latex ui/aux-controls.png "Aux Controls" width=3.45in
\image html ui/aux-controls.png "Aux Controls"
</center>
<br>

You might also need access to special h/w functions.  FLRIG provides this
via the DTR and RTS signal lines of an independent serial port.  Additional
main dialog controls are enabled and shown if you select anything other than
NONE (the default). Enable the "Serial Port is SCU-17 auxiliary"
if you are using the SCU-17 secondary serial port.

\subsection ssPOLLING Configure Polling
<center>
\image latex config/polling.png "I/O Ports - Polling" width=4.9in
\image html config/polling.png "I/O Ports - Polling"
</center>
<br>

Providing you transceiver supports the various meters and controls, you
can elect to poll these every time the poll cycle occurs.  Polling a value
causes FLRIG to follow and well as control a particular transceiver function
or control.  The polling cycle will slow down as you elect to poll more and
more values.

\subsection ssSENDING Send Command String

<center>
\image latex config/send.png "I/O Ports - Sending" width=4.9in
\image html config/send.png "Sending"
</center>
<br>

Testing your transceiver commands.  FLRIG might not support a particular CAT
command for your transceiver.  You can test the support for a particular
command using the "Send Cmd" tab.  The command string must comply with the
transceiver requirements.  If ASCII text is used, as with transceivers based
on the Kenwood command set you enter the string without spaces, i.e.

\verbatim
FA;
\endverbatim
to read the A vfo .

For binary strings, used in older Yaesu transceivers, and all Icom CI-V type
transceivers you need to enter the string as space delineated hex values,
i.e.

\verbatim
Yaesu:  x00 x00 x00 x01 x05

Icom: xFE xFE x70 xE0 x1A x05 x00 x92 x00 xFD
\endverbatim

The buttone "ICOM pre" and "ICOM post" will insert the preamble and postamble
hex code sequences for the selected Icom transceiver.

Press the SEND button to transfer the command to the transceiver.  The
response will appear in the lower text control.

The diamond indicators will be lit for transceiver and fldigi connections respectively.

\subsection ssTRACE Configure Command Tracing

<center>
\image latex config/config-trace.png "Configure code execution trace" width=5.0in
\image html  config/config-trace.png "Configure code execution trace"
</center>

Several debugging tools are available in flrig, including the ability to observe code
execution in various parts of the program.  The trace tool sends time annotated data to
both a viewing dialog and a file named "trace.txt" which is written to the flrig files
folder.

<ul>
<li> Trace support code - main processing loop execution points</li>
<li> Trace debug code - replicate the event log debugging output</li>
<li> Trace rig class code - execution points within a specific transceiver class (not for all)</li>
<li> Trace xml_server code - execution points within the xmlrpc interface code for i/o to/from fldigi</li>
<li> Trace xmlrpcpp code - sent and received xmlrpc data packets<br>
six levels of detail 0 ... 5 can be specified</li>
</ul>

<center>
\image latex debugging/trace-dialog.png "Example showing support code trace" width=5.0in
\image html  debugging/trace-dialog.png "Example showing support code trace"
</center>

\subsection ssRESTORE Configure Read/Restore Xvcr Settings

flrig will read various transceiver parameters and restore them upon closing.
The next image shows the available read/restore parameters for the Icom 7200.  If
a parameter is not available (or coded) it will be disabled and grayed out.  Check
each parameter that you want to read and restore.  Reading and restoring transceiver
parameters takes time, especially on older transceivers with low baud rate serial
i/o.  Check "Use xcvr data" i\If you want flrig to NOT change the transceiver operating state
when it begins execution.

<center>
\image latex config/restore.png "Restoring transceiver Status" width=4.9in
\image html config/restore.png "Restoring transceiver Status"
</center>

\subsection ssSERVER Configure XmlRpc Server
<center>
\image latex config/server.png "Configure server" width=5.0in
\image html  config/server.png "Configure server"
</center>

flrig accepts remote control via an XmlRpc socket interface.  fldigi uses this 
access method for reading and writing transceiver parameters via flrig.  WSJT-X and
several other third party programs also use this method.  See \ref xmlrpc_commands.

\subsection ssUserInterface User Interface

<center>
\image latex menus/config-ui-menu.png "" width=1.6in
\image html menus/config-ui-menu.png ""
</center>
<br>

\subsection ssMetering Meter Display and Filters

<center>
\image latex ui/meter-filters.png "Meter Filter Controls" width=4.18in
\image html ui/meter-filters.png "Meter Filter Controls"
</center>
<br>

You can control the behavior of both the average and peak values of the
S-meter and Power out meters.  Setting the controls to 1 for both average
and peak will simply display the latest value available from the
transceiver.  The average setting results in the display showing the
average of the last N readings.  The peak value will display the average
peak value over the last M readings.
<br>

<center>
\image latex ui/power-scale-select.png "Meter Scale" width=4.6in
\image html ui/power-scale-select.png "Meter Scale"
</center>
<br>

Right click on the main dialog power meter scale to open up this selection
dialog.  Each of the 4 scales and the "Auto scaled" box are buttons.  Press
the one you want to use.  Auto-scaling adjusts the meter scale to the
smallest scale consistent with the current measured peak power.  If that
power is fluctuating near the transistion point between two scales you
might want to fix the scale to either the larger or smaller.
<br>

\subsection ssSliders Slider sizing

When the user interface is configured to be "small" then the UI submenu will
contain the item "Small sliders".  Toggling this menu item will immediately
change the size and positions of the various slider controls. Select the toggle button 
"Small sliders" on the Config menu for 1/2 size sliders and a dialog layout 
that uses less vertical space.

<center>
\image latex FT-991A-ui-small.png "Small UI - Large Sliders" width=4.6in
\image html FT-991A-ui-small.png "Small UI - Large Sliders"
</center>
<br>

<center>
\image latex FT-991A-ui-narrow.png "Small UI - Small Sliders" width=4.6in
\image html FT-991A-ui-narrow.png "Small UI - Small Sliders"
</center>
<br>

\subsection ssAdditionalControls Additional Controls

Additional control settings may be available depending on the transceiver
being controlled.  These are in a drop-down area toggled by the arrow button
to the left of the attenuator button on the small aspect ratio dialog view.
These are the controls for the Yeasu FT991A.

<center>
\image latex ft-991a/FT-991A-xtras-band.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-band.png ""
<br>
\image latex ft-991a/FT-991A-xtras-cw.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-cw.png ""
<br>
\image latex ft-991a/FT-991A-xtras-qsk.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-qsk.png ""
<br>
\image latex ft-991a/FT-991A-xtras-vox.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-vox.png ""
<br>
\image latex ft-991a/FT-991A-xtras-spch.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-spch.png ""
<br>
\image latex ft-991a/FT-991A-xtras-misc.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-misc.png ""
<br>
\image latex ft-991a/FT-991A-xtras-cmd-a.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-cmd-a.png ""
</center>

Select the User Interface menu item to configure various user preferences including \ref config_fonts_colors.
<br>

\section sOpControls Operating Controls

<center>
\image latex ui/frequency-control.png "Frequency Control" width=4.6in
\image html ui/frequency-control.png "Frequency Control"
</center>
<br>

The frequency display is also a control.  Each numeric is sensitive to the mouse
left/right buttons for up/down and to the mouse scroll wheel for rapidly
changing value.  Click on upper half of the digit to increase frequency, and
the lower half of the digit to decrease the frequency. Put the mouse over any of 
the numeric segments and you can enter a new frequency using the keyboard 
numeric keypad.  If you make an error simply enter a non-numeric key.  Set the 
newly entered frequency by pressing the Enter key.

To paste a frequency from the clipboard (kHz only), press control-V followed
by the Enter key

Vfo-A and Vfo-B are separate controlS, A on the left, B on the right.

Left click on the A->B button to swap vfos.  Right click on the A->B button
to transfer vfoA to vfoB.

When the mouse pointer is over the frequency display you can also change
frequency values using the arrow and page key buttons:

<ul>
	<li>left / right arrow - increase / decrease 1 Hz</li>
	<li>up / down arrow - increase / decrease 10 Hz</li>
	<li>Page Up / Page Down - increase / decrease 100 Hz</li>
</ul>
<br>

<center>
\image latex ui/buttons-sliders.png "Control Sliders" width=2.24in
\image html ui/buttons-sliders.png "Control Sliders"
</center>
<br>

The buttons that have a light box are toggles - activated when the lighted
box is colored.  Some of these are linked to a slider.  If the button state
is inactive then that associated slider will be greyed out.  In the example
the volume control is active and the NR control is inactive.
<br>

<center>
\image latex ui/flrig-fldigi.png "FLRIG/FLDIGI" width=4.37in
\image html ui/flrig-fldigi.png "FLRIG/FLDIGI"
</center>
<br>

Operating FLRIG with FLDIGI requires a simple setup in FLDIGI.  Deselect all
but the "xmlrpc" rig control.  Xmlrpc is used via a local socket device for
the two programs to communicate.  FLDIGI acts as the server and FLRIG the
client.  There is no requirement for start / stop ordering of the programs.

FLRIG sends rig configuration data to FLDIGI when the two programs initially
recognize each other.  This data is used to populate the rig name, the
available modes and the available bandwidths.

After this initial communications the operator can set the paired controls
from either FLDIGI or FLRIG.  The two programs will remain synchronized.  The
data from the computer to the transceiver is always from FLRIG.

PTT can be activated at FLRIG or using the T/R button on FLDIGI.  FLDIGI
also engages the PTT via the macro \<TX\> \<RX\> tags.  When operating digital
modes with FLDIGI you should use the PTT from FLDIGI.

\section sFileStores Configuration/Data files

Configuration and data files used by flrig consist of the following:

<center>
| OS            |Folder                                             |File                  |Usage |
|:--------------|:--------------------------------------------------|:---------------------|:-----------------------------------|
|Windows XP     |c:\\Documents and Settings\\user-name\\flrig.files |flrig.prefs           |names transceiver file & xmlrpc port|
|Windows XP     |c:\\Documents and Settings\\user-name\\flrig.files |IC-7100.prefs (1)(2)  |IC-7100 specifc configuration items |
|Windows XP     |c:\\Documents and Settings\\user-name\\flrig.files |IC-7100.mat   (1)(2)  |IC-7100 specific memory file        |
|Windows 7/8/10 |c:\\Users\\user-name\\flrig.files                  |flrig.prefs           |names transceiver file & xmlrpc port|
|Windows 7/8/10 |c:\\Users\\user-name\\flrig.files                  |IC-7100.prefs (1)(2)  |names transceiver file & xmlrpc port|
|Windows 7/8/10 |c:\\Users\\user-name\\flrig.files                  |IC-7100.mat   (1)(2)  |names transceiver file & xmlrpc port|
|Linux/Unix/OS-X|$HOME/.flrig                                       |flrig.prefs           |names transceiver file & xmlrpc port|
|Linux/Unix/OS-X|$HOME/.flrig                                       |IC-7100.prefs (1)(2)  |names transceiver file & xmlrpc port|
|Linux/Unix/OS-X|$HOME/.flrig                                       |IC-7100.mat   (1)(2)  |names transceiver file & xmlrpc port|
</center> 

(1) Several TRANSCEIVER.prefs and mat files may be in the folder.  Each specifc to the configured transceiver<br>
(2) Files such as IC-7100.prefs.1, IC-7100.mat.1, up to a prefix of 5 may appear in the folder.  These are aged files, with the oldest
file having the largest prefix value.  The mat files are only created if the user actually saved items to memory.

Transceiver Prefs details are shown in this file: \ref prefs_file_contents.

The file is human readable.  Editing the file is not recommended.

\subsection sMatFile  Memory File

The contents of a typical transceiver prefs file contains:
<br>
<pre>
7070000 9 34 "40 meter digital"
14070000 9 34 "20 meter digital"
</pre>
Each line contains a frequency (Hz), Mode Nr., Bandwidth Nr., and "text tag"

The file is human readable.  Editing the file is not recommended.

\subsection sEventLog Event Log

<center>
\image latex debugging/flrig-event-log.png "Event Log" width=7.5in
\image html debugging/flrig-event-log.png "Event Log"
</center>
<br>

The event log is opened from the "Debug" menu.  It allows you to view the
serial and xmlrpc data exchanges between FLRIG, FLDIGI, xmlrpc transactions,
and the transceiver.


\section ssMultipleConfigDir Controlling Multiple Transceivers

You can have multiple instances of flrig running, each controlling a separate
and unique transceiver.  Doing this requires a separate configuration folder
for each target transceiver.  Either start flrig from a command line or
copy the desktop launch icon and then modify it's "target" executable.  In
either case you will be adding a command line parameter

"--config-dir <target-dir>"

Note the double dash.  The <target-dir> will be unique to each supported
transceiver, for example: "C:\Users\<user-name>\flrig.ic7200" on Win-10, 
"/home/<user>/flrig.ic7200" on Linux or OS X.  You will have to configure
each instance with the correct interface parameters.

<center>
\image latex mulitple_configs.png "" width=2.48in
\image html mulitple_configs.png ""
</center>

\section stransceiver_how_to Transceiver How-To
\subsection sFT991a FT 991A
\ref ft991a_how_to_page
\subsection sIC7600 IC 7600
Andy's (VE3NVK / G8VTV) \ref ic7600_how_to_page
\subsection sTT550 TT 550
The TenTec Pegasus, TT-550 is a computer only transceiver.  FLRIG controls
all aspects of this transceiver.
\ref tt550_ops_page

\section scw_keyer CW Keyer
\ref cw_keyer

\ref sFlrigDesc "Top of Page"
*/
