kopia lustrzana https://github.com/jamescoxon/dl-fldigi
446 wiersze
19 KiB
Plaintext
446 wiersze
19 KiB
Plaintext
|
/******************************************************************************
|
||
|
* Copyright (C) 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 FLARQ Users Manual - Version 4.3
|
||
|
|
||
|
\tableofcontents
|
||
|
|
||
|
<center>
|
||
|
\image latex flarqlogo.png "" width=0.5in
|
||
|
\image html flarqlogo.png ""
|
||
|
</center>
|
||
|
|
||
|
<!--FLARQ User Manual-->
|
||
|
\section sFlarqDesc Transceiver Control
|
||
|
|
||
|
|
||
|
<b>F</b>ast <b>L</b>ight <b>A</b>utomatic <b>R</b>epeat re<b>Q</b>uest is a
|
||
|
file transfer application that is based on the
|
||
|
<a href="aux/ARQ2.pdf">ARQ specification</a> developed by Paul Schmidt,
|
||
|
K9PS. It is capable of transmitting and receiving frames of ARQ data
|
||
|
via either FLDIGI or MultiPsk on Windows, or FLDIGI on Linux/Macintosh OSX.
|
||
|
The interaction between FLARQ and FLDIGI requires no operator intervention.
|
||
|
Program data exchange between FLARQ and FLDIGI is accomplished using a
|
||
|
localhost socket interface. The socket interface requires that one program
|
||
|
act as the server and the other the client. FLARQ is a client program and
|
||
|
FLDIGI is a server program.
|
||
|
|
||
|
FLARQ will not execute unless either FLDIGI (preferred) or MultiPsk is
|
||
|
already running on the host computer. If MultiPsk is used it must be set
|
||
|
to the "socket" mode before executing FLARQ. If you attempt to run FLARQ
|
||
|
without FLDIGI already running you will view an information window asking
|
||
|
you to first start FLDIGI.
|
||
|
|
||
|
The ARQ transfer must take place between two systems both of which are
|
||
|
running the FLARQ / FLDIGI. The ARQ specification and the source code
|
||
|
for FLARQ are GPL licensed. Other developers wishing to duplicate or
|
||
|
expand upon the FLARQ ARQ implementation may freely do so.
|
||
|
|
||
|
FLARQ can be used with the following digital modem as the transport layer:
|
||
|
|
||
|
BPSK all baud rates<br>
|
||
|
QPSK all baud rates<br>
|
||
|
MFSK all baud rates<br>
|
||
|
DOMINOEX 11 or faster (do not use FEC)<br>
|
||
|
THOR all baud rates, 11 or faster recommended<br>
|
||
|
MT63 - all baud rates, FLARQ timing should be increased to accommodate mt63
|
||
|
latency<br>
|
||
|
|
||
|
Please note that Olivia IS NOT compatible with FLARQ transmissions. Olivia
|
||
|
does not allow the transmission of the control codes required for FLARQ.
|
||
|
|
||
|
The main screen dialog for FLARQ is:
|
||
|
|
||
|
<center>
|
||
|
\image latex maindialog.png "Main Dialog" width=5.5in
|
||
|
\image html maindialog.png "Main Dialog"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
ARQ data is sent in data frames which clearly delineate from whom the data
|
||
|
is being sent, it's purpose or type, the actual data, and a checksum value.
|
||
|
The "Beacon" button will cause the transmission of the ARQ equivalent of a
|
||
|
"CQ" frame which can be easily recognized by a receiving station. Upon
|
||
|
receipt of the beacon frame a monitoring FLARQ will automatically insert
|
||
|
the sending stations callsign into the edit box to the right of the
|
||
|
"Connect" button. The receiving station can then press the "Connect"
|
||
|
button and the connect process begins.
|
||
|
|
||
|
<center>
|
||
|
|
||
|
|Diamond Color | Indicator |
|
||
|
|:------------:|:-------------------------|
|
||
|
| WHITE | Not Connected |
|
||
|
| YELLOW | Connecting |
|
||
|
| GREEN | Connected - Receiving |
|
||
|
| RED | Connected - Transmitting |
|
||
|
| BLACK | Timed Out |
|
||
|
|
||
|
</center>
|
||
|
|
||
|
The state of the connection also appears in plain text to the right of the
|
||
|
diamond indicator.
|
||
|
|
||
|
Pressing the "Beacon" button sends both the text and T/R commands to the
|
||
|
modem program. The beacon will repeat with a wait time between transmissions
|
||
|
set by the Beacon interval in seconds on the Configure dialog. During the
|
||
|
silent period between beacon transmissions the Beacon button will show the
|
||
|
count down timer. You can stop the beacon at any time it is in the count
|
||
|
down mode by simply pressing that button or by pressing the Abort button.
|
||
|
The default beacon interval is 60 seconds. The minimum is 15 seconds and
|
||
|
the maximum 300 seconds. If you find that stations are having difficulty
|
||
|
connecting to your beacon call then you probably need to increase the time
|
||
|
between beacons to avoid ARQ collisions similar to doubling on voice. When
|
||
|
FLARQ is in the Beacon mode the words BEACON ON, and the green light on the
|
||
|
Beacon button will be lit.
|
||
|
|
||
|
The status bar at the bottom of the main dialog contains a status text
|
||
|
message area to the left and a progress bar to the right. During a file
|
||
|
transfer you will be notified of actions and also see the transfer percent
|
||
|
completion in the progress bar.
|
||
|
|
||
|
\section sConfigure Configuring FLARQ
|
||
|
|
||
|
|
||
|
Before using FLARQ (and upon its initial execution) you will have to enter
|
||
|
some configuration parameters:
|
||
|
|
||
|
<center>
|
||
|
\image latex configdialog.png "Configure Dialog" width=5.5in
|
||
|
\image html configdialog.png "Configure Dialog"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
The highlighted field, "My Call" is the only one that you must fill in to
|
||
|
start using the application. The folder locations for Text/Binary Files
|
||
|
and also for the Mail Client files should all be OK as preconfigured for
|
||
|
the operating system in use.
|
||
|
|
||
|
Read through the ARQ specification for additional detail. The Exponent is
|
||
|
a 2^N factor which delineates the size of the text data block that is
|
||
|
transmitted in a data frame. 2^5 is 32 and should be satisfactory for
|
||
|
most s/n conditions. If you are experiencing many repeats you can lower
|
||
|
the Exponent value. If the path between rx and tx stations is very good
|
||
|
you could increase its value. FLARQ allows the following range of values:
|
||
|
|
||
|
<center>
|
||
|
|
||
|
|Exponent | Block size |
|
||
|
|:-------:|:----------:|
|
||
|
| 4 | 16 |
|
||
|
| 5 | 32 |
|
||
|
| 6 | 64 |
|
||
|
| 7 | 128 |
|
||
|
| 8 | 256 |
|
||
|
|
||
|
</center>
|
||
|
|
||
|
Retries specifies how many times a repeat request should be made before
|
||
|
the link is declared DOWN.
|
||
|
|
||
|
Wait time is the time between retries.
|
||
|
|
||
|
Timeout is the time period during which NO RECEPTION of frames has occured
|
||
|
before the link is declared DOWN.
|
||
|
|
||
|
The Tx delay is the time between the end of the Rx and the beginning of the
|
||
|
Tx cycle for an ARQ exchange. One-half second should be more than
|
||
|
sufficient for most transceivers. You might be able to lower the value
|
||
|
for your rig. Older rigs may need the value increased.
|
||
|
|
||
|
Beacon text - will be transmitted with each beacon transmission.
|
||
|
|
||
|
Sylpheed Mail Client - Sylpheed stores the message files using numeric file
|
||
|
names without extension. Check this box to insure that FLARQ stores the
|
||
|
files in sequential numeric order without creating duplicates. This is
|
||
|
primarily for Linux users. Windows users should leave this box unchecked
|
||
|
unless they are using the Sylpheed Mail Client.
|
||
|
|
||
|
\section sConnecting Connecting
|
||
|
|
||
|
The normal connection process is that the station with traffic will request
|
||
|
the connecting station to send a beacon. This tests the ability of the
|
||
|
connecting station to forward. The station with traffic will then be the
|
||
|
one to press the Connect button. The receiving station will see the
|
||
|
beacon message displayed in the FLARQ text area and also see the beacon
|
||
|
stations callsign appear in the callsign box. The connecting station
|
||
|
presses the connect button and after a few automatic exchanges the diamond
|
||
|
indicator to the right of the callsign turns green indicating that they
|
||
|
are successfully connected. A connect may take a few retries if the
|
||
|
transmission path s/n is marginal. During the connect process the diamond
|
||
|
indicator will be yellow.
|
||
|
|
||
|
After the two stations are CONNECTED either operator may effect a file
|
||
|
transfer. Who goes first may be negotiated using FLDIGI in a plain text
|
||
|
mode or using the FLARQ "Plain Talk" facility, once connected. The FLDIGI
|
||
|
T/R functions can be used in parallel with any ARQ transmissions. It might
|
||
|
be best to conclude those negotiations before establishing the ARQ
|
||
|
connection.
|
||
|
|
||
|
Either station may initiate a DISCONNECT process.
|
||
|
|
||
|
This is what the outgoing beacon will look like on FLDIGI:
|
||
|
|
||
|
|
||
|
<center>
|
||
|
\image latex beacon.png "Beacon Message" width=2.7in
|
||
|
\image html beacon.png "Beacon Message"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
The \<soh\> and \<eot\> are control codes that surround every ARQ frame.
|
||
|
FLDIGI recognizes that it is connected to FLARQ and shows the control codes as
|
||
|
ASCII named equivalents since they are not normally printable.
|
||
|
|
||
|
The text will appear very similar on the receiving end of the exchange.
|
||
|
|
||
|
\section sTransfering Transferring files
|
||
|
|
||
|
You may transfer several different file types:
|
||
|
|
||
|
<center>
|
||
|
\image latex SendMenu.png "Send - File Transfer" width=2.7in
|
||
|
\image html SendMenu.png "Send - File Transfer"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
<ul>
|
||
|
<li>Email - created using FLARQ's composer, Outlook Express,
|
||
|
Outlook, Thunderbird, Sylpheed or any other email client,
|
||
|
or received via the internet and handled by the email client.</li>
|
||
|
<li>Text - any ASCII file which does not contain non-printable text</li>
|
||
|
<li>Image - any image file, jpeg, png, bmp, etc.</li>
|
||
|
<li>Binary - any file containing arbtrary data where each byte is
|
||
|
anything from 00 hex to FF hex.</li>
|
||
|
</ul>
|
||
|
|
||
|
|
||
|
\subsection ssTransferingTIB Transfering Text, Images or Binary Files
|
||
|
|
||
|
If you select Text, Image or Binary file for transfer a regular file picker
|
||
|
dialog is opened. You can navigate anywhere in the file system to pick a
|
||
|
file. The default location for the files are unique in Windows and
|
||
|
Linux/MacOSX. In Linux the default location is in $HOME/ARQsend and in
|
||
|
Windows it is c:\\NBEMS\\ARQsend. Move files to that location to make
|
||
|
finding the target file easy. Use the file manager or move the file using
|
||
|
command line processing in a terminal window. Image and binary files will be
|
||
|
converted into ASCII text files using base64 conversion. This basically is
|
||
|
the same type of conversion that an email client would perform on an image or
|
||
|
binary attachment. The file is encoded using base64 coding at the sending
|
||
|
end and then decoded back to its original form at the receiving end.
|
||
|
At the conclusion of a satisfactory ARQ transfer the two files will be
|
||
|
identical, including name and size. The target directory for received
|
||
|
files is $HOME/ARQrcvd in Linux, and c:\\NBEMS\\ARQrcvd in Windows. The
|
||
|
receiving station opens the c:\\NBEMS\\Mail\\ARQin folder and drags the
|
||
|
incoming message placed there by FLARQ over to the Outlook Express email
|
||
|
client, or just double-clicks on the .eml message to open it in the default
|
||
|
email client. It is the reciprocal process from that which the sending
|
||
|
station uses.
|
||
|
|
||
|
During the transfer the sending station transmits blocks of data. Each
|
||
|
block has a header, data, checksum and trailing component. The receiving
|
||
|
station acknowledges which blocks have been correctly received and which
|
||
|
need retransmission. Missing blocks sometimes occur in the middle of the
|
||
|
set of acknowledged blocks. The text in the FLARQ text window will only
|
||
|
update as contiguous blocks are available. So you might see the update
|
||
|
occur in what appears to be random intervals. As the sending and receiving
|
||
|
stations go from receive-to-transmit-to-receive the diamond indicator will
|
||
|
toggle from green to red and back to green.
|
||
|
|
||
|
|
||
|
\subsection ssComposingEmail Composing Email
|
||
|
|
||
|
FLARQ has a built-in email composer that creates files with a minimum of
|
||
|
email overhead. It is a text only composer with no attachment or other
|
||
|
niceties associated with a normal email client. It does produce very
|
||
|
small email files which is a benefit when transmitting files over slower
|
||
|
modem baud rates. Click on the "Compose" menu item. That will open the
|
||
|
following dialog:
|
||
|
|
||
|
<center>
|
||
|
\image latex composer.png "Composer" width=5.25in
|
||
|
\image html composer.png "Composer"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
Enter the email address of the destination addressee, the subject and the
|
||
|
email body text. Then press "Save" to save the file for later transmission.
|
||
|
|
||
|
You can create a template for later use and then save the template by
|
||
|
pressing SHIFT while clicking on the Save button. Here is an example of a
|
||
|
template in preparation:
|
||
|
|
||
|
<center>
|
||
|
\image latex wxstatus_tpl.png "Composer WX Template" width=5.25in
|
||
|
\image html wxstatus_tpl.png "Composer WX Template"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
This file will be saved as "wxstatus.tpl". FLARQ recognizes the tpl
|
||
|
extension as the template file. When you later click the Template button
|
||
|
the new "wxstatus.tpl" template will be available to load and use in
|
||
|
creating the wx status report. After opening a template you can either
|
||
|
modify it and save as a new or overwrite the existing template, or you
|
||
|
can save the filled-in template as a regular file for subsequent
|
||
|
transmission.
|
||
|
|
||
|
\subsection ssUsingEmailClient Using Email client - Outlook Express
|
||
|
|
||
|
You can use Outlook Express for the email client to create outgoing ARQ
|
||
|
traffic. Just remember that you should create all email traffic as ASCII
|
||
|
text and not HTML text to reduce the size of the message body. You are
|
||
|
going to send this via an RF link and not over the internet with a high
|
||
|
speed connection.
|
||
|
|
||
|
Create your email just as you would for transfer over the internet and
|
||
|
then save it in the Drafts folder. In Outlook Express, click Create
|
||
|
Email and use the format, name\@phonenumber, such as information
|
||
|
\@8005551212, for the address if it is to be delivered by phone, and is
|
||
|
not an email. Save each message in the Drafts folder by clicking File,
|
||
|
and then Save. Exit the composition window. Open the ARQout folder
|
||
|
(located at c:\\NBEMS\\Mail\\ARQout) on the desktop along with Outlook
|
||
|
Express as shown below. Then drag the message from the "To ... Subject"
|
||
|
area of Outlook Express and drop it on the ARQout folder. This places
|
||
|
them in a folder that FLARQ can locate.
|
||
|
|
||
|
<center>
|
||
|
\image latex OLxpress.png "Outlook Express" width=5.5in
|
||
|
\image html OLxpress.png "Outlook Express"
|
||
|
\image latex ARQout.png "Outlook Express EMail Files" width=4.7in
|
||
|
\image html ARQout.png "Outlook Express EMail Files"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
When you select the FLARQ menu item "Send / Email" a dialog will open
|
||
|
that shows the contents of the messages that are in the ARQout folder:
|
||
|
|
||
|
|
||
|
<center>
|
||
|
\image latex SelectFromARQout.png "Select Message" width=5.25in
|
||
|
\image html SelectFromARQout.png "Select Message"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
Multiple email entries would appear on separate lines with scroll bars as
|
||
|
appropriate. You highlight the desired file and then press "Send" or the
|
||
|
Enter key to commence the file transfer. The email may contain attachments
|
||
|
(which may be images) or be just plain text. Remember that this is a
|
||
|
fairly slow transfer process so small is beautiful. If the email has
|
||
|
images then it will be in html and base-64 format. That adds a lot of
|
||
|
overhead to the email. "Cancel" aborts the email transfer process. After
|
||
|
a successful transfer from sending to receiving station the email is
|
||
|
automatically moved from the ARQout to the ARQsent folder. If you are
|
||
|
using Outlook Express you can open the c:\\NBEMS\\Mail\\ARQsent folder the
|
||
|
same way that the ARQout folder can be opened. At the receiving end the
|
||
|
email will be placed in the Sylpheed ARQin folder. Sylpheed does not
|
||
|
need to be executing for this to occur at either end.
|
||
|
|
||
|
\subsection ssUsingEmailClientSylpheed Using Email client - Sylpheed
|
||
|
|
||
|
FLARQ has been optimally designed to interoperate with Sylpheed as its
|
||
|
email client for emergency communications of email traffic. When you
|
||
|
install Sylpheed you will be asked to choose a default directory for the
|
||
|
mail store. On Linux/MacOSX this should be the default $HOME/Mail. On Windows
|
||
|
you should choose c:\\NBEMS\\Mail. Three additional folders are used for
|
||
|
transferring files between the FLARQ application and Sylpheed.
|
||
|
These are:
|
||
|
|
||
|
<ul>
|
||
|
<li>ARQin</li>
|
||
|
<li>ARQout, and</li>
|
||
|
<li>ARQsent</li>
|
||
|
</ul>
|
||
|
|
||
|
You can create these folders from within the Sylpheed application.
|
||
|
|
||
|
<center>
|
||
|
\image latex sylpheed-arqout.png "Sylpheed EMail Client" width=3.09in
|
||
|
\image html sylpheed-arqout.png "Sylpheed EMail Client"
|
||
|
</center>
|
||
|
<br>
|
||
|
|
||
|
The above image shows the folders already in place. If they were not
|
||
|
present they could be created by right clicking on the "Mailbox (MH)"
|
||
|
icon and selecting "Create new folder". Name each new folder as
|
||
|
specified above and shown in the image. These folders are required
|
||
|
for FLARQ to be able to work with the Sylpheed email messages. Each
|
||
|
message in Sylpheed is a separate file. These are usually numbered
|
||
|
sequentially in each of the Sylpheed folders. FLARQ manages the correct
|
||
|
sequential naming of files as they are transferred in, out and moved
|
||
|
between these three folders. If you run the FLARQ application before
|
||
|
Sylpheed then the c:\\NBEMS\\Mail and the c:\\NBEMS\\Mail\\ARQin, ARQout, and
|
||
|
ARQsent folders will be created by that application and will appear in the
|
||
|
Sylpheed folder system.
|
||
|
|
||
|
To create a new email traffic you press the "Compose" button. Fill out the
|
||
|
email as usual and then press the "Draft" button from within the composer.
|
||
|
The new message for transfer via FLARQ is now in the Drafts folder shown
|
||
|
above. Open that folder by clicking on it. Select the desired draft
|
||
|
message and drag and drop in onto the ARQout folder icon. That's it!
|
||
|
The message is now ready for FLARQ to perform the ARQ transfer.
|
||
|
|
||
|
Upon completion of the transfer FLARQ will move the message to the ARQsent
|
||
|
folder. Sylpheed will not immediately recognize that the change has
|
||
|
occured. That is easily accomplished by either changing to another folder
|
||
|
and then back again or by right clicking on the ARQout (or ARQin, or
|
||
|
ARQsent) folder icon and selecting "Update summary". Sylpheed will re-read
|
||
|
the folder contents and adjust it's views accordingly.
|
||
|
|
||
|
Incoming traffic will be placed in the ARQin folder. You may have to refresh
|
||
|
the folder as described above.
|
||
|
|
||
|
FLARQ can find and parse the newly created email document that has been moved
|
||
|
or copied to the ARQout folder. If you select to send email a picker dialog
|
||
|
will appear that lists all of the out going email traffic that is contained
|
||
|
in the Sylpheed ARQout folder.
|
||
|
|
||
|
\subsection ssOtherClients Other Email clients
|
||
|
|
||
|
If you use an email client other than Sylpheed or Outlook Express you can
|
||
|
transfer emails as above. Just be sure that the emails have file names
|
||
|
with the extension "eml" as in "mytest_message.eml".
|
||
|
|
||
|
|
||
|
\subsection ssAbortingTX Aborting a transmission
|
||
|
|
||
|
The transmission may be aborted by either the sending or the receiving
|
||
|
station at any time during the file transfer. When Connected and
|
||
|
transferring a file, the Connect button is re-labeled <b>Abort</b>. Since
|
||
|
data is sent in multiple blocks the actual abort will take place at
|
||
|
the conclusion of the current group transmission. Abort will cause
|
||
|
the transfer to be interrupted. The connection will be maintained
|
||
|
and a new transfer can be initiated if required.
|
||
|
|
||
|
\section sPlainTalk Plain Talk
|
||
|
|
||
|
After a connection is established the two stations can exchange text using
|
||
|
the "Plain Talk" entry control at the bottom of the main dialog. Enter up
|
||
|
to 80 characters and then press the Enter key to transmit the text. This
|
||
|
text is sent UNPROTO, which means that NO repeat request will be made. The
|
||
|
block is sent without any acknowledgement from the receiving station. This
|
||
|
is not an ACK/NACK system, but meant only as a way of allowing quick
|
||
|
operator to operator exchanges without having to disconnect and use the
|
||
|
digital modem program keyboard entry. "Plain Talk"can be interspersed
|
||
|
with normal ARQ file transfer blocks.
|
||
|
|
||
|
\ref sFlarqDesc "Top of Page"
|
||
|
*/
|