/******************************************************************************
 * 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.4.8

\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 images/ic-7300/ui_small.png "" width=4in
\image html images/ic-7300/ui_small.png ""
</center>
<br>

<center>
<table>
<tr>
<td>
<center>
\image latex images/ic-7300/ic-7300-main-extras.png "With embedded extras tab" width=4in
\image html images/ic-7300/ic-7300-main-extras.png "With embedded extras tab"
</center>
</td>
<td>
<center>
\image latex images/ic-7300/ic-7300-main-extras-dialog.png "Separate extras tab dialog" width=4in
\image html images/ic-7300/ic-7300-main-extras-dialog.png "Separate extras tab dialog"
</center>
</td>
</tr>
</table>
</center>
<br>
<center>
\image latex images/ic-7300/ui_wide.png "" width=6in
\image html images/ic-7300/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"     |<br>                             |
|<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_PowerSDR  "PowerSDR"      |
|<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"      |\ref o_Flex1500 "Flex 1500"      |
|<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"       |\ref o_Xiegu-5105 "Xiegu 5105"   |
|<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"     |\ref o_Xiegu-G90 "Xiegu G90"     |
|<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"       |\ref o_FDMDUO "FDM-DUO"          |
|<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"       |\ref o_TX500 "TX500"             |
|<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"     |\ref o_QCXplus "QRP Labs QCX+"   |
|<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"  |\ref o_SunSDR2 "SunSDR2 Pro"     |
|<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 - CMedia</b> - configure PTT using Cmedia codec pin 13</li>
	<li><b>PTT - Generic</b> - configure PTT using serial port CAT, DTR or RTS</li>
	<li><b>PTT - GPIO</b> - configure PTT using GPIO port, Pi hardware platform</li>
	<li><b>AUX</b> - configure separate auxiliary serial ports (if used)</li>
	<li><b>Server</b> - change XmlRpc server port designation</li>
	<li><b>Polling</b> - select and configure transceiver parameters to poll</li>
	<li><b>Commands</b> - add/delete/modify user created CAT commands</li>
	<li><b>Send command</b> - edit/send single CAT command</li>
	<li><b>Restore</b> - select and configure transceiver parameters to read and restore</li>
	<li><b>Trace</b> - select and display program execution paths</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-generic.png "I/O Ports - PTT" width=4.9in
\image html config/PTT-generic.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 ssCMEDIA Configure CMEDIA PTT

<center>
\image latex config/PTT-cmedia.png "Cmedia PTT control" width = 4.9in
\image html  config/PTT-cmedia.png "Cmedia PTT control"
</center>

Cmedia audio codec chips are used in a number of inexpensive USB audio thumbnail devices.  
It is also used in the DRA@ series of sound card adapters.  The DRA is a radio optimized 
sound card used to connect a two-way radio to a computer for digital communications. 
The DRA-Series digital radio adapter is used for Packet Radio or other digital programs 
and applications like VARA-FM, VARA-HF, SoundModem or fldigi. 

All RA Series radio adapters include GPIO support.  The Cmedia device supports 4 unbuffered 
input/output lines, GPIO-1 ... GPIO4.  GPIO-3 is used to drive a fully buffered and deadman 
protected PTT circuit.  All DRA Series radio adapters include a Heartbeat Monitor. When the 
Cmedia device is reading or writing audio data, the HeartBeat status LED (HB) flashing. If 
everything is okay, (HB LED is flashing) a Blue LED called "COMM OK" illuminates. If the HB 
LED stops flashing because the radio adapter or the computer/appliance has failed, or the 
software has stopped reading or writing audio data, the Blue COMM OK LED goes out. The Blue 
LED indicates the health status of the system, and illuminates when everything is okay.

The PTT line on any DRA Series radio adapter is interrupted with the failure of this health 
status. This function will kill the PTT line the audio stream is interrupted.  This will 
occur if fldigi and similar modem program is not reading/writing audio data.

The circuitry was designed to operate correctly no matter if the Heartbeat has stuck in the 
on or off state. 

The PTT type, the device and the GPIO line must be selected.
If multiple C-Media devices are discovered they will enumerate as C-Media-A, C-Media-B, etc.  
You must test the selected interface as it is not possible to know which is the correct one 
for the DRA interface.  Pressing the TEST button will cause the PTT line to rapidly toggle 
for a period of 2 seconds.  This will cause the RED PTT led to flash and the transceiver PTT 
to toggle on and off.

\subsection ssGPIO Use Pi GPIO PTT

<center>
\image latex config/PTT-gpio.png "GPIO PTT control" width = 4.9in
\image html  config/PTT-gpio.png "GPIO PTT control"
</center>

The Pi series of miniature computers offer a large array of possibilities for
controlling devices.  It has a array of General Purpose Input Output, gpio, 
lines of a 40 pin in-line header.  17 of these gpio lines can be used for
things like push-to-talk.  There are several add on boards for the Pi3 and Pi4,
such as the NW Digital Radio UDRC-II, that has a full interface for digital
operations, including PTT and audio codecs.

Access to hardware ports is always limited to the user who either is root 
or has root privileges.  setuid and setgid (short for set user ID upon 
execution, and set group ID upon execution, respectively) are Linux
access rights flags that allow users to run an executable with the 
permissions of the executable's owner or group respectively and to change 
behaviour in directories. They are often used to allow users on a computer 
system to run programs with temporarily elevated privileges in order to 
perform a specific task. While the assumed user id or group id privileges 
provided are not always elevated, at a minimum they are specific.

It is possible to give full gpio access and control privileges by elevating
flrig with setuid root.  But this is not advisable as flrig is also
granted access to both serial and network services.  There is a way to
provide the access via a second program that does have the elevated privilege

This is a copy of material at 

\verbatim
https://projects.drogon.net/raspberry-pi/wiringpi/download-and-install/
\endverbatim

for installing WiringPi which includes a really nice utility called gpio.

To obtain WiringPi using GIT:

\verbatim
$ git clone git://git.drogon.net/wiringPi
\endverbatim

If you have already used the clone operation for the first time, then

\verbatim
$ cd wiringPi
$ git pull origin
\endverbatim

Will fetch an updated version then you can re-run the build script below.

To build/install there is a simplified script:

\verbatim
$ cd wiringPi
$ ./build
\endverbatim

The build script will compile and install it all for you.  It does 
use the sudo command at one point, so you may wish to inspect the script 
before running it.

<b>Test wiringPi's installation</b>

run the gpio command to check the installation:

\verbatim
$ gpio -v
$ gpio readall
\endverbatim

That should give you some confidence that it’s working OK.

WiringPi is released under the GNU Lesser Public License version 3.

flrig uses the gpio program for initializing the gpio port, which also
happens to the change the privilege of the temporary sys file for setting
the port state.

<b>Read the man document for gpio</b>
\verbatim
GPIO is  a  swiss  army knife of a command line tool to allow the user 
easy access to the GPIO pins on the Raspberry Pi and the SPI A/D and D/A 
converters on  the  Gertboard.  It's designed for simple testing and 
diagnostic purposes, but can be used in shell scripts for general if 
somewhat slow control of the GPIO pins.

It can also control the IO's on the PiFace IO board and load the SPI and 
I2C  kernel  modules if required.

Additionally, it can be used to set the exports in the /sys/class/gpio 
system directory to allow subsequent programs to use the /sys/class/gpio 
interface without needing to  be run as root."

After installing gpio on your Pi you can set the gpio port on flrig's
GPIO configuration tab.  The UDRC-II for example uses pin 16, BCM # 23,
for push to talk.  It has an LED indicator on the board to show when PTT
has been enabled.  For this board you select "BCM 23" and select the
corresponding "= 1 (on)" check box.
\endverbatim

During start up flrig uses the gpio program to set up the gpio pins with
the command 
\verbatim
$ gpio export NN out
\endverbatim
This is the command to export a GPIO pin in the /sys/class/gpio directory. 
Note  that  the  pin number  is  the  BCM_GPIO number.  'out' sets the pin
to be an output control, and 'in' an input control.

Once a GPIO pin has been exported, the gpio program changes the  ownership  of  the
<br>

/sys/class/gpiogpioX/value
<br>

and if present in later kernels, the
<br>

/sys/class/gpio/gpioX/edge
<br>

pseudo files to that of the user running the  gpio  program. This means 
that you can have a small script of gpio exports to setup the gpio
pins as your program requires without the need to run anything as root,
or with the sudo command.

During shutdown flrog uses the gpio program to disable access to the gpio
pins used with PTT by invoking the command
<br>

gpio unexport NN.
<br>

You can check that this is working correctly from a terminal window using the
command
\verbatim
$ gpio readall
\endverbatim


\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 your 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 as 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 ssCommands User-Defined Commands

<center>
\image latex config/cmds.png "Defining Commands for Extra Controls A, B, C Tabs" width=4.9in
\image html config/cmds.png "Defining Commands for Extra Controls A, B, C Tabs"
</center>
<br>

flrig supports 24 unshifted and 24 shifted user-defined commands.  The commands are defined via
the Configuration dialog "Commands" tab and are invoked via buttons on the A, B, and C tabs on the flrig
extra controls dialog.  Refer to your rig's remote interface control documentation to learn how
to construct a command.

As shown in the Figure, the user provides text for the button label and an appropriate command string
for their radio.  The command can be tested by clicking on the button in the extra controls dialog
and examining the response in the Configuration dialog.  In the example, the unshifted command sets
the frequency in use on the Main band of an Icom IC-7610 radio to the 80 meter CW range, and the
shifted command sets it to the 40 meter CW range (these commands only affect frequency - not mode).
In the label in this example, the '/' is used as a way to distinguish the unshifted/shifted functions.

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; e.g.,

\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;
e.g.,

\verbatim
Yaesu:  x00 x00 x00 x01 x05

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


Additionally, the user can define commands that should be executed during program start-up or termination
by making entries on the Start/Exit tab of the Commands configuration page.



\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 button "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 Yaesu FT991A.

<center>
\image latex ft-991a/FT-991A-xtras-band.png "" width=4.25in
\image html ft-991a/FT-991A-xtras-band.png ""
</center>
<br>
Left-click on a Band button to QSY to that band.  Typically this will apply the settings saved in the top
register in your rig's Band Stacking Registers for that band, if your rig supports BSR.
This should provide similar functionality to physically pressing the rig's Band button.
For example, on an Icom IC-7610, this will recall the frequency, mode, filter selection, and
if FM mode, the tone frequencies last used on the selected band.

Additionally, if your rig supports the functionality, right-clicking on a Band button
will store current values in the top register for that Band.  You must right-click on the
Band you are currently on.  Most, if not all, rigs will reject attempts to set
frequency values outside of the ham band limits in the BSR for a given band.
<br>
<br>

<center>

\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 sFrequencyControls Frequency 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; it displays frequency in kHz.  In
addition to allowing you to set the rig frequency, it will track with changes
made on the rig itself.

The number of digits that may be entered and the number of decimal digits displayed
are determined by hard-coded data for the rig selected if using rig control.  The intent
is to match the actual rig display.

If you select NONE for rig control, 7 digits to the left of the decimal and 3 digits
to the right are displayed.

In the rig control case, the maximum frequency is determined by the rig; in the NONE
case, the maximum frequency is 9,999,999.999 kHz.

The maximum frequency <B><I>based on the number of digits displayed</I></B> is given in the tooltip.
Note that this may be greater than the maximum frequency possible for your rig.  If you attempt
to set an unsupported frequency, the result depends on the rig.

You can set the frequency two ways without the
control being in "focus" and several more ways with it in focus.

<B> With or without Focus </B>

<ul>
<li>Move the mouse cursor over a digit and roll the wheel
<li>Highlight a numeric frequency in text in the application and
then move the mouse cursor over the control and press the middle mouse button to paste selection
</ul>

<B> With Focus </B>

<b>Shift-Left-Click</b> (hold keyboard SHIFT button and press left mouse button) in the control to set focus.  The foreground and background
colors reverse to indicate the control has focus.

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

Each digit is sensitive to the mouse.  Clicking the left or right button over
the top half of a digit increments it while clicking over the lower half decrements it.
Holding the mouse button down will cause the number to rapidly increase or decrease.
In all cases the numbers "roll over" - i.e., you can change the digit you point to
and all digits to the left of it.

Arrow and Page Up / Page Down Keys can be used to increment and decrement digits.
Digits are numbered 0-9, right to left, with the digit's significance matching that of the rig's display.
For example, if the rig's resolution is 1 Hz, D0's range is 0-9 Hz.
<br>

<center>
<table style="width: 80%">
	<tr>
		<th>Keys</th>
		<th>Normal</th>
		<th>SHIFT + key</th>
		<th>CTRL + key</th>
	</tr>
	<tr>
		<td><center>right / left arrow</center></td>
		<td><center>+/- D0</center></td>
		<td><center>+/- D1</center></td>
		<td><center>+/- D2</center></td>
	<tr>
		<td><center>up / down arrow</center></td>
		<td><center>+/- D3</center></td>
		<td><center>+/- D4</center></td>
		<td><center>+/- D5</center></td>
	</tr>
	<tr>
		<td><center>Page Up / Page Down</center></td>
		<td><center>+/- D6</center></td>
		<td><center>+/- D7</center></td>
		<td><center>+/- D8</center></td>
	</tr>
</table>
</center>
<br>

All of the foregoing change techniques result in immediate changes to the
frequency of a controlled rig.

There are two additional ways to set the frequency when the control has focus:
<B>PASTE from clipboard</B> and <B>direct keyboard entry</B>.

You can paste from the clipboard (Ctrl/Meta-v) in addition to from the Selection buffer (middle mouse button).
When pasting from a selection (highlighted number), the selection must be from text within
the application whereas the clipboard paste will paste values copied from any application.
The value pasted is expected to be numeric in units of kHz and can include a decimal point.
If the value being pasted would exceed the maximum frequency allowed, the Paste action is silently ignored.
Paste actions result in an immediate command to set the frequency on a controlled rig.

Lastly, you may enter a frequency directly from the number keys or keypad of a keyboard.
Enter the frequency in kHz, including decimal point if there are non-zero decimal components,
using either the number keys or the keypad.  You may use any legal floating point format.
For example:

<ul>
<li>7070</li>
<li>14070.235</li>
<li>14.07e3 (Remember that the numeric value is in kHz so this example is 14070 kHz or 14.070 MHz)</li>
</ul>


When you press the first number, the decimal point in the display will blink to indicate
you are in numeric entry mode.  While in numeric entry mode, all other entry modes are
disabled (i.e., no mouse clicks, rolls, or pastes are possible).

Continue to enter numbers, and optionally a decimal and more numbers.  The value does NOT
get sent to a controlled rig until you press the ENTER key.  Pressing the ENTER key
sends the value to the rig and exits the numeric entry mode.

If you want to make changes as you are entering numbers, you can use the backspace key
to delete undesired numbers digit by digit, or Ctrl/Meta-Backspace to clear all digits
on the side of the decimal point you are currently entering; use Ctrl/Meta-Backspace again
to clear the left of decimal numbers as well if you have already entered a digit to the
right of the decimal point, and then resume entering numbers.

If you attempt to enter more digits on either side of the decimal than there are
digits available, the excess digit entries are ignored.

If you want to abort the process you can press the ESC (escape) key or click outside
the control in a widget that will take focus (like a text field) or outside the application
and the frequency will remain as it was; this exits numeric entry mode.

Vfo-A and Vfo-B are separate controls, A on the left, B on the right.  If your radio has
two VFOs, you can make one or the other active for transmission and reception by clicking
on the corresponding button.  Note that many radios allow you to change the frequency of
an inactive VFO through remote command, in which case you do not have to click on the
corresponding button to set its frequency.

Left click on the A/B button to swap several of the parameters of the VFOs (e.g., frequency,
filter setting, mode) and change the active VFO to follow (so effectively your operation
has not changed but you are using the other VFO).

Shift-click to copy just the frequency from Vfo-A to Vfo-B, and Ctrl-Click
to copy in the other direction.


<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

Operating frequency, mode, and bandwidth can be saved to a memory file.  Save the current values to the 
memory file using the "Memory / Save" menu item.  Open the memory manager using the
"Memory / Manage" menu item

<center>
\image latex MemoryDialog.png "" width=3.0in
\image html MemoryDialog.png ""
</center>

The "Add", "Pick", "Del" and "Clr" buttons operate as labeled.

Left click on a line to enable modifying the Tag line for that entry.  Terminate the tag entry with the "Enter" key.

The contents of a typical transceiver .mat file contains:
<br>
<pre>
020000 2 5 "40 CW"
7070000 11 16 "PSK sub band"
7089000 11 16 "Feld Hell net"
</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 sIC7100 IC 7100
\ref ic7100_how_to_page
\subsection sIC7300 IC 7300
\ref ic7300_how_to_page
\subsection sIC7600 IC 7600
\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

Open the keyer dialog

<center>
\image latex cw-keyer/cwkeyer.png "" width=2.0in
\image html  cw-keyer/cwkeyer.png ""
</center>

 with the main dialog menu item "Keyer/CW keyer"
 
 <center>
\image latex menus/keyer_menu.png "" width = 2.0in
\image html  menus/keyer_menu.png ""
</center>

<ul>
<li>WPM slider selects the keyer speed</li>
<li>Clear - clears the text in the transmit buffer</li>
<li>transmit text will marquee to the left as each character is transmitted</li>
<li>Send/Pause button toggles sending text.</li>
<li>macro buttons / function keys load transmit buffer with canned message
<ul>
<li>left click to load macro contents into transmit buffer</li>
<li>control left click to open macro editor dialog</li>
</ul>
</li>
<li>the transmit text buffer must have keyboard focus for character entry.  left click on the entry area to gain keyboard focus.</li>
</ul>

Tip for the function / macro buttons: 

<center>
\image latex cw-keyer/cwkeyer_tooltip.png "" width=2.0in
\image html  cw-keyer/cwkeyer_tooltip.png ""
</center>

Control-left-click opens:

<center>
\image latex cw-keyer/cwkeyer_editor.png "" width=2.0in
\image html  cw-keyer/cwkeyer_editor.png ""
</center>

A CQ macro with start/stop (ptt enable/disable): <pre>[CQ CQ DE W1HKJ K]</pre>

Prosign characters can be configured by the user.  The macros and prosign assignments are save in the transceiver prefs file.

Config opens:

<center>
\image latex cw-keyer/cwkeyer_config.png "" width=5.0in
\image html  cw-keyer/cwkeyer_config.png ""
</center>

The DTR/RTS port can be either
<ul>
<li>shared with the CAT port</li>
<li>shared with the SEP port</li>
<li>shared with the AUX port</li>
<li>a unique serial port configured on this dialog</li>
</ul>

Select either DTR or RTS for the keyline as required by h/w.

Calibrate button sends standard "PARIS " word, WPM times.  Program 
measures actual time to transmit and sets compensation value.  WPM Comp msec 
can be adjusted by user.

Xcvr comp msec is used to increase or decrease each key down interval by 
the specified time interval.  

<center>
\image latex flrig-24wpm.png "7300 CW DTR/RTS keying @ 24 WPM" width=6.0in
\image html  flrig-24wpm.png "7300 CW DTR/RTS keying @ 24 WPM"
</center>

The effect of a -2 msec Xcvr comp adjustment is clearly seen and easily heard.  
It is especially important to correct weight errors introduced by the transceiver 
keying circuits when operating QRQ (high speed CW).  At 80 wpm 2 msec is a significant
part of the target dit interval of 15 msec.

PTT delay is in milliseconds.  Enter a non-zero value to enable a delay 
between the PTT-on and the first CW keyline closure.  The same delay will 
be applied to the last CW keyline closure and PTT-off.

\section sfskio_keyer FSK Keyer

Open the FSK keyer dialog

<center>
\image latex fskio-keyer/fskio_dialog.png "" width=5.0in
\image html  fskio-keyer/fskio_dialog.png ""
</center>

 with the main dialog menu item "Keyer/FSK keyer"
 
 <center>
\image latex menus/keyer_menu.png "" width = 2.0in
\image html  menus/keyer_menu.png ""
</center>

Config opens:

<center>
\image latex fskio-keyer/fskio_config.png "" width=5.0in
\image html  fskio-keyer/fskio_config.png ""
</center>

The DTR/RTS port can be either
<ul>
<li>shared with the CAT port</li>
<li>shared with the AUX port</li>
<li>shared with the SEP port</li>
<li>shared port with CWIO (if separate)</li>
<li>a unique serial port configured on this dialog</li>
<li>Inverted - enable if interface requires a Mark/Space reversed signal level</li>
<li>select either DTR or RTS for the keyline as required by h/w, 
selection must not conflict with CW keyline</li>
</ul>

PTT delay is in milliseconds.  Enter a non-zero value to enable a delay 
between the PTT-on and the first FSK keyline closure.  The same delay will 
be applied to the last FSK keyline closure and PTT-off.

Control-left-click opens:

<center>
\image latex fskio-keyer/fskio_editor.png "" width=5.0in
\image html  fskio-keyer/fskio_editor.png ""
</center>

An RY macro with start/stop (ptt enable/disable):
<pre>[RYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRYRY DE W1HKJ K]</pre>

\ref cw_keyer

\ref sFlrigDesc "Top of Page"
*/
