Update the WSJT-X User Guide to v1.8

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@7859 ab8295b8-cf94-4d9e-aec4-7959e3be5d79

doc/CMakeLists.txt

@@ -49,6 +49,7 @@ set (UG_SRCS
   transceiver-setup.adoc
   tutorial-example1.adoc
   tutorial-example2.adoc
+  tutorial-example3.adoc
   tutorial-main-window.adoc
   tutorial-wide-graph-settings.adoc
   utilities.adoc
@@ -59,6 +60,7 @@ set (UG_SRCS
 
 set (UG_IMGS
   images/130610_2343-wav-80.png
+  images/170709_135615.wav.png
   images/AstroData_2.png
   images/Astronomical_data.png
   images/band-settings.png
@@ -69,6 +71,7 @@ set (UG_IMGS
   images/download_samples.png
   images/file-menu.png
   images/freemsg.png
+  images/ft8_decodes.png
   images/help-menu.png
   images/JT4F.png
   images/JT65B.png

doc/user_guide/en/introduction.adoc

@@ -7,27 +7,29 @@ K1**JT**,`" while the suffix "`-X`" indicates that _WSJT-X_ started as
 an extended and experimental branch of the program
 _WSJT_.
 
-_WSJT-X_ Version 1.7 offers eight protocols or modes: *JT4*, *JT9*,
+_WSJT-X_ Version 1.8 offers nine different protocols or modes: *FT8*,
-*JT65*, *QRA64*, *ISCAT*, *MSK144*, *WSPR*, and *Echo*.  The first
+*JT4*, *JT9*, *JT65*, *QRA64*, *ISCAT*, *MSK144*, *WSPR*, and *Echo*.
-four are designed for making reliable QSOs under extreme weak-signal
+The first five are designed for making reliable QSOs under extreme
-conditions. They use nearly identical message structure and source
+weak-signal conditions. They use nearly identical message structure
-encoding.  JT65 and QRA64 were designed for EME ("`moonbounce`") on
+and source encoding.  JT65 and QRA64 were designed for EME
-the VHF/UHF bands and have also proven very effective for worldwide
+("`moonbounce`") on the VHF/UHF bands and have also proven very
-QRP communication on the HF bands.  QRA64 has a number of advantages
+effective for worldwide QRP communication on the HF bands.  QRA64 has
-over JT65, including better performance on the very weakest signals.
+a number of advantages over JT65, including better performance on the
-We imagine that over time it may replace JT65 for EME use.  JT9 was
+very weakest signals.  We imagine that over time it may replace JT65
-originally designed for the LF, MF, and lower HF bands.  Its submode
+for EME use.  JT9 was originally designed for the LF, MF, and lower HF
-JT9A is 2 dB more sensitive than JT65 while using less than 10% of the
+bands.  Its submode JT9A is 2 dB more sensitive than JT65 while using
-bandwidth.  JT4 offers a wide variety of tone spacings and has proven
+less than 10% of the bandwidth.  JT4 offers a wide variety of tone
-highly effective for EME on microwave bands up to 24 GHz.  All of these
+spacings and has proven highly effective for EME on microwave bands up
-"`slow`" modes use one-minute timed sequences of alternating
+to 24 GHz.  These four "`slow`" modes use one-minute timed sequences
-transmission and reception, so a minimal QSO takes four to six minutes
+of alternating transmission and reception, so a minimal QSO takes four
-— two or three transmissions by each station, one sending in odd UTC
+to six minutes — two or three transmissions by each station, one
-minutes and the other even. On the HF bands, world-wide QSOs are
+sending in odd UTC minutes and the other even.  FT8 is operationally
-possible using power levels of a few watts (or even milliwatts) and
+similar but four times faster (15-second T/R sequences) and less
-compromise antennas.  On VHF bands and higher, QSOs are possible (by
+sensitive by a few dB.  On the HF bands, world-wide QSOs are possible
-EME and other propagation types) at signal levels 10 to 15 dB below
+with any of these modes using power levels of a few watts (or even
-those required for CW.
+milliwatts) and compromise antennas.  On VHF bands and higher, QSOs
+are possible (by EME and other propagation types) at signal levels 10
+to 15 dB below those required for CW.
 
 *ISCAT*, *MSK144*, and optionally submodes *JT9E-H* are "`fast`"
 protocols designed to take advantage of brief signal enhancements from

doc/user_guide/en/make-qso.adoc

@@ -158,6 +158,6 @@ as the following checklist:
 
 - Radio filters centered and set to widest available passband (up to 5 kHz).
 
-TIP: Remember that in many circumstances JT4, JT9, JT65, and WSPR do
+TIP: Remember that in many circumstances FT8, JT4, JT9, JT65, and WSPR
-not require high power. Under most HF propagation conditions, QRP is
+do not require high power. Under most HF propagation conditions, QRP
-the norm.
+is usually the norm.

doc/user_guide/en/new_features.adoc

@@ -1,35 +1,28 @@
-=== New in Version 1.7
+=== New in Version 1.8
 
 For quick reference, here's a short list of features and capabilities
-added to _WSJT-X_ since Version 1.6.0:
+added to _WSJT-X_ since Version 1.7.0:
 
-- New modes: ISCAT, MSK144, QRA64
+- New modes: *FT8* and *FreqCal*
 
-- Newly implemented submodes: JT65B-C, JT9B-H
+- Improved decoding performance for JT65, QRA64, and MSK144
 
-- Fast submodes of JT9E-H
+- *SWL* option for third-partty decoding short-format MSK144 messages
 
-- New Franke-Taylor decoder to replace the Koetter-Vardy decoder
+- Experimental amplitude and phase equalization for MSK144
-previously used for JT65. Separate program `kvasd[.exe]` is no longer
-used.
     
-- Improvements to the JT4, JT9, and JT65 decoders
+- Options to minimize screen space used by the *Main* and *Wide Graph*
+windows
     
-- Multi-pass decoding for JT65 and WSPR.  Decoded signals are
+- New set of suggested default frequencies specific to the three IARU
-subtracted from the received data, allowing decoding of weaker
+Regions.
-signals that were otherwise masked.
 
-- Improved convenience features for EME Doppler tracking
+- Enhanced scheme for managing table of default operating frequencies
 
-- Saving and restoring of multiple program configurations
+- Improved CAT control for many rigs, including those controlled
+through Commander or OmniRig.
 
-- Sample-file download facility
+- Bug fixes and tweaks to the user interface
-
-- Many corrections and improvements to the Hamlib library, fixing
-balky rig-control features
-
-- Power settings for Transmit and Tune remembered and optionally
-restored for each band
 
 === Documentation Conventions
 

doc/user_guide/en/protocols.adoc

@@ -2,15 +2,16 @@
 === Overview
 
 All QSO modes except ISCAT use structured messages that compress
-user-readable information into fixed-length packets of exactly 72
+user-readable information into fixed-length packets of 72 bits.  Each
-bits.  Each message consists of two 28-bit fields normally used for
+message consists of two 28-bit fields normally used for callsigns and
-callsigns and a 15-bit field for a grid locator, report,
+a 15-bit field for a grid locator, report, acknowledgment, or 73.  An
-acknowledgment, or 73.  An additional bit flags a message containing
+additional bit flags a message containing arbitrary alphanumeric text,
-arbitrary alphanumeric text, up to 13 characters.  Special cases allow
+up to 13 characters.  Special cases allow other information such as
-other information such as add-on callsign prefixes (e.g., ZA/K1ABC) or
+add-on callsign prefixes (e.g., ZA/K1ABC) or suffixes (e.g., K1ABC/P)
-suffixes (e.g., K1ABC/P) to be encoded. The basic aim is to compress
+to be encoded. The basic aim is to compress the most common messages
-the most common messages used for minimally valid QSOs into a fixed
+used for minimally valid QSOs into a fixed 72-bit length.  Information
-72-bit length.
+payloads in FT8 include 3 additional bits (75 bits total), with
+definitions yet to be defined.
 
 A standard amateur callsign consists of a one- or two-character
 prefix, at least one of which must be a letter, followed by a digit
@@ -57,6 +58,19 @@ _WSJT-X_ modes have continuous phase and constant envelope.
 [[SLOW_MODES]]
 === Slow Modes
 
+[[FT8PRO]]
+==== FT8
+
+Forward error correction (FEC) in FT8 uses a low-density
+parity check (LDPC) code with 75 information bits, a 12-bit cyclic
+redundancy check (CRC), and 174 channel symbols.  It is thus called an
+LDPC (174,87) code.  Synchronization uses 7×7 Costas arrays at the
+beginning, middle, and end of each transmission.  Modulation is 8-tone
+frequency-shift keying (8-FSK) at 12000/1920 = 6.25 baud.  Each
+transmitted symbol carries three bits, so the total number of channel
+symbols is 174/3 + 21 = 79.  The total occupied bandwidth is
+8 × 6.25 = 50 Hz.
+
 [[JT4PRO]]
 ==== JT4
 
@@ -160,12 +174,12 @@ which the probability of decoding is 50% or higher.
 |===============================================================================
 |Mode |FEC Type |(n,k) | Q|Modulation type|Keying rate (Baud)|Bandwidth (Hz)
 |Sync Energy|Tx Duration (s)|S/N Threshold (dB)
-|JT4A |K=32, r=1/2|(206,72)| 2| 4-FSK| 4.375| 17.5 |
+|FT8  |LDPC, r=1/2|(174,87)| 8| 8-FSK| 6.25 | 50.0 | 0.27| 12.6 | -21
-0.50| 47.1 | -23 |JT9A |K=32, r=1/2|(206,72)| 8| 9-FSK| 1.736| 15.6 |
+|JT4A |K=32, r=1/2|(206,72)| 2| 4-FSK| 4.375| 17.5 | 0.50| 47.1 | -23
-0.19| 49.0 | -27 |JT65A |Reed Solomon|(63,12) |64|65-FSK| 2.692| 177.6
+|JT9A |K=32, r=1/2|(206,72)| 8| 9-FSK| 1.736| 15.6 | 0.19| 49.0 | -27
-| 0.50| 46.8 | -25 |QRA64A|Q-ary Repeat Accumulate|(63,12) |64|64-FSK|
+|JT65A |Reed Solomon|(63,12) |64|65-FSK| 2.692| 177.6 | 0.50| 46.8 | -25
-1.736| 111.1 | 0.25| 48.4 | -26 | WSPR |K=32, r=1/2|(162,50)| 2|
+|QRA64A|Q-ary Repeat Accumulate|(63,12) |64|64-FSK|1.736|111.1|0.25|48.4| -26
-4-FSK| 1.465| 5.9 | 0.50|110.6 | -28
+| WSPR |K=32, r=1/2|(162,50)| 2| 4-FSK| 1.465| 5.9 | 0.50|110.6 | -28
 |===============================================================================
 
 Submodes of JT4, JT9, JT65, and QRA64 offer wider tone spacings for
@@ -179,6 +193,7 @@ comparable to tone spacing.
 [width="50%",cols="h,3*^",frame=topbot,options="header"]
 |=====================================
 |Mode  |Tone Spacing  |BW (Hz)|S/N (dB)
+|FT8   |6.25 |  50.0  |-21
 |JT4A  |4.375|  17.5  |-23
 |JT4B  |8.75 |  30.6  |-22
 |JT4C  |17.5 |  56.9  |-21

doc/user_guide/en/settings-reporting.adoc

@@ -11,3 +11,5 @@ reception reports to the {pskreporter} mapping facility.
 address and port number used by a program that will receive status
 updates from _WSJT-X_.  Cooperating applications like _JTAlert_ use
 this feature to obtain information about a running _WSJT-X_ instance.
+If you are using _JTAlert_, be sure to check the three boxes at lower
+right.

doc/user_guide/en/transceiver-setup.adoc

@@ -15,13 +15,13 @@ AGC action.
 .Bandwidth and Frequency Setting
 
 - If your transceiver offers more than one bandwidth setting in USB
-mode, you should normally choose the widest one possible, up to about
+mode, it may be advantageous to choose the widest one possible, up to
-5 kHz.  This choice has the desirable effect of allowing the *Wide
+about 5 kHz.  This choice has the desirable effect of allowing the
-Graph* (waterfall and 2D spectrum) to display the conventional JT65
+*Wide Graph* (waterfall and 2D spectrum) to display the conventional
-and JT9 sub-bands simultaneously on most HF bands.  Further details
+JT65 and JT9 sub-bands simultaneously on most HF bands.  Further
-are provided in the <<TUTORIAL,Basic Operating Tutorial>>.  A wider
+details are provided in the <<TUTORIAL,Basic Operating Tutorial>>.  A
-displayed bandwidth may also be helpful at VHF and above, where JT4,
+wider displayed bandwidth may also be helpful at VHF and above, where
-JT65, and QRA64 signals are found over much wider ranges of
+JT4, JT65, and QRA64 signals are found over much wider ranges of
 frequencies.
 
 - If you have only a standard SSB filter you won’t be able to display
@@ -31,9 +31,10 @@ generally used for one mode (JT65 or JT9) and part of the sub-band for
 the other mode.
 
 - Of course, you might prefer to concentrate on one mode at a time,
-setting your dial frequency to (say) 14.076 for JT65 or 14.078 for
+setting your dial frequency to (say) 14.074 for FT8, 14.076 for JT65,
-JT9.  Present conventions have the nominal JT9 dial frequency 2 kHz
+or 14.078 for JT9.  Present conventions have the nominal JT9 dial
-higher than the JT65 dial frequency on most bands.
+frequency 2 kHz higher than the JT65 dial frequency on most bands, and
+the FT8 frequency 2 kHz lower.
 
 .Transmitter Audio Level
 
@@ -46,13 +47,9 @@ clicks or glitches.  Make sure that this is true even when you
 simultaneously use the computer to do other tasks such as email, web
 browsing, etc.
 
-* Open the computer's audio mixer controls for output ("`Playback`")
+* Adjust the *Pwr" slider (at the right edge of the main window)
-devices and adjust the volume slider downward from its maximum until
+downward from its maximum until the RF output from your transmitter
-the RF output from your transmitter falls slightly.  This is generally
+falls slightly.  This is generally a good level for audio drive.
-a good level for audio drive.
-
-* Alternatively, you can make the Tx audio level adjustment using the
-digital slider labeled *Pwr* at the right edge of the main window.
 
 * Toggle the *Tune* button once more or click *Halt Tx* to stop your
 test transmission.

doc/user_guide/en/tutorial-example2.adoc

@@ -114,6 +114,3 @@ waterfall and the several types of spectra.  Good starting values
 should be close to mid-scale.  You might want to uncheck *Flatten*
 when adjusting the sliders.  Re-open the wave file after each change,
 to see the new results.
-
-IMPORTANT: When finished with this Tutorial, don’t forget to re-enter
-your own callsign as *My Call* on the *Settings | General* tab.

doc/user_guide/en/tutorial-example3.adoc

@@ -0,0 +1,27 @@
+// Status=review
+.Main Window:
+- Select *FT8* on the *Mode* menu.
+- Set Tx and Rx frequencies to 1200 Hz.
+- Double-click on *Erase* to clear both text windows.
+
+.Wide Graph Settings:
+
+- *Bins/Pixel* = 4
+- Adjust the width of the Wide Graph window so that the upper
+frequency limit is approximately 2500 Hz.
+
+.Open a Wave File:
+
+- Select *File | Open* and navigate to +...\save\samples\FT8\170709_135615.wav+.
+The waterfall should look something like this:
+
+[[X14]]
+image::170709_135615.wav.png[align="left",alt="Wide Graph Decode 170709_135615"]
+
+- You should see decodes of the three FT8 signals in the *Band Activity*
+text box, as shown below:
+
+image::ft8_decodes.png[align="left"]
+
+IMPORTANT: When finished with this Tutorial, don’t forget to re-enter
+your own callsign as *My Call* on the *Settings | General* tab.

doc/user_guide/en/vhf-features.adoc

@@ -1,6 +1,9 @@
-_WSJT-X_ v1.7 introduces a number of new features designed for use
+_WSJT-X_ v1.8 suppports a number of features designed for use
 on the VHF and higher bands.  These features now include:
 
+- *FT8*, a mode optimized for weak, fading signals such as those often
+encountered with multi-hop sporadic E propagation on 50 MHz.
+
 - *JT4*, a mode particularly useful for EME on the microwave bands
 
 - *JT9* fast modes, useful for scatter propagation on VHF bands
@@ -21,8 +24,8 @@ propagation
 - *Doppler tracking*, which becomes increasingly important for EME
 on bands above 1.2 GHz.
 
-- *Auto-sequencing* of transmitted messages for the fast modes with
+- *Auto-sequencing* of transmitted messages for FT8 and the fast modes
-forward error control
+with forward error control
 
 [[VHF_SETUP]]
 === VHF Setup

doc/user_guide/en/wsjtx-main.adoc

@@ -133,6 +133,10 @@ include::tutorial-example1.adoc[]
 === JT9+JT65
 include::tutorial-example2.adoc[]
 
+[[TUT_EX3]]
+=== FT8
+include::tutorial-example3.adoc[]
+
 [[MAKE_QSOS]]
 == Making QSOs
 include::make-qso.adoc[]

wsjtx.pro

@@ -66,7 +66,7 @@ SOURCES += \
   main.cpp decodedtext.cpp wsprnet.cpp messageaveraging.cpp \
   echoplot.cpp echograph.cpp fastgraph.cpp fastplot.cpp Modes.cpp \
   WSPRBandHopping.cpp MessageAggregator.cpp SampleDownloader.cpp qt_helpers.cpp\
-  MultiSettings.cpp PhaseEqualizationDialog.cpp
+  MultiSettings.cpp PhaseEqualizationDialog.cpp IARURegions.cpp
 
 HEADERS  += qt_helpers.hpp \
   pimpl_h.hpp pimpl_impl.hpp \
@@ -81,7 +81,8 @@ HEADERS  += qt_helpers.hpp \
   Configuration.hpp wsprnet.h signalmeter.h meterwidget.h \
   logbook/logbook.h logbook/countrydat.h logbook/countriesworked.h logbook/adif.h \
   messageaveraging.h echoplot.h echograph.h fastgraph.h fastplot.h Modes.hpp WSPRBandHopping.hpp \
-  WsprTxScheduler.h SampleDownloader.hpp MultiSettings.hpp PhaseEqualizationDialog.hpp
+  WsprTxScheduler.h SampleDownloader.hpp MultiSettings.hpp PhaseEqualizationDialog.hpp \
+  IARURegions.hpp
 
 INCLUDEPATH += qmake_only