More additions to the WSJT-X User Guide.

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

doc/user_guide/en/install-mac.adoc

@@ -6,7 +6,7 @@ installation notes.
 
 If you have already installed a previous version, you can retain it by
 changing its name in the *Applications* folder (say, from _WSJT-X_ to
-_WSJT-X_1.5_).  You can then proceed to the installation phase.
+_WSJT-X_1.6_).  You can then proceed to the installation phase.
 
 Take note also of the following:
 

doc/user_guide/en/install-windows.adoc

@@ -3,19 +3,19 @@
 Download and execute the package file {win32}, following these
 instructions:
 
-- Install _WSJT-X_ into its own directory rather than in the conventional
-location +C:\Program Files\WSJTX+.  Suggested installation directories are
-+C:\WSJTX+ or +C:\WSJT\WSJTX+.
+- Install _WSJT-X_ into its own directory such as `C:\WSJTX` or
+`C:\WSJT\WSJTX` rather than the conventional location
+`C:\Program Files\WSJTX`.
 
 - All program files relating to _WSJT-X_ will be stored in the chosen
 installation directory and its subdirectories. 
 
 - Logs and other writeable files will normally be found in the 
-directory +C:\Users\<username>\AppData\Local\WSJT-X+.
+directory `C:\Users\<username>\AppData\Local\WSJT-X`.
 
 IMPORTANT: Your computer may be configured so that this directory is
 "`invisible`".  It's there, however, and accessible.  An alternative
-(shortcut) directory name is %LOCALAPPDATA%\WSJT-X\.
+(shortcut) directory name is `%LOCALAPPDATA%\WSJT-X\`.
 
 - The built-in Windows facility for time synchronization is usually
 not adequate. We recommend the program _Meinberg NTP_ (see {ntpsetup}

doc/user_guide/en/introduction.adoc

@@ -4,11 +4,11 @@ _WSJT-X_ is a computer program designed to facilitate basic amateur
 radio communication using very weak signals. The first four letters in
 the program name stand for "`**W**eak **S**ignal communication by
 K1**JT**,`" while the suffix "`-X`" indicates that _WSJT-X_ started as
-an extended (and originally experimental) branch of the program
+an extended and experimental branch of the program
 _WSJT_.
 
-_WSJT-X_ Version 1.7 offers eight protocols or "`modes`": *JT4*,
-*JT9*, *JT65*, *QRA64*, *WSPR*, *Echo*, *ISCAT*, and *MSK144*.  The
+_WSJT-X_ Version 1.7 offers eight protocols or modes: *JT4*,
+*JT9*, *JT65*, *QRA64*, *WSPR*, *ISCAT*, *MSK144*, and *Echo*.  The
 first four are designed for making reliable QSOs under extreme
 weak-signal conditions. They use nearly identical message structure
 and source encoding.  JT65 and QRA64 were designed for EME
@@ -29,36 +29,36 @@ even 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'"
+*ISCAT*, *MSK144*, and optionally submodes *JT9E-H* are "`fast`"
 protocols designed to take advantage of brief signal enhancements from
-ionized meteor trails and other types of scatter propagation. These
-modes use timed sequences of 5, 10, 15, or 30 s duration.  User
-messages are transmitted repeatedly at high rate (up to 250 characters
-per second, for MSK144) to make good use of the shortest meteor
-"`pings`".  ISCAT uses free-form messages up to 28 characters long,
-while MSK144 uses the same structured messages as the slow modes
-together with an abbreviated format with hashed callsigns for messages
-sent after initial contact has been established between two stations.
+ionized meteor trails, aircraft scatter, and other types of scatter
+propagation. These modes use timed sequences of 5, 10, 15, or 30 s
+duration.  User messages are transmitted repeatedly at high rate (up
+to 250 characters per second, for MSK144) to make good use of the
+shortest meteor-trail reflections or "`pings`".  ISCAT uses free-form
+messages up to 28 characters long, while MSK144 uses the same
+structured messages as the slow modes together with an abbreviated
+format with hashed callsigns.  
 
-*WSPR* (pronounced "`whisper`") stands for Weak Signal Propagation
-Reporter.  The WSPR protocol was designed for probing potential
-propagation paths using low-power transmissions. WSPR messages
-normally carry the transmitting station’s callsign, grid locator, and
-transmitter power in dBm, and they can be decoded at signal-to-noise
-ratios as low as -28 dB in a 2500 Hz bandwidth.  WSPR users with
-internet access can automatically upload their reception reports to a
-central database called {wsprnet} that provides a mapping facility,
-archival storage, and many other features.
+*WSPR* (pronounced "`whisper`") stands for **W**eak **S**ignal
+**P**ropagation **R**eporter.  The WSPR protocol was designed for probing
+potential propagation paths using low-power transmissions. WSPR
+messages normally carry the transmitting station’s callsign, grid
+locator, and transmitter power in dBm, and they can be decoded at
+signal-to-noise ratios as low as -28 dB in a 2500 Hz bandwidth.  WSPR
+users with internet access can automatically upload their reception
+reports to a central database called {wsprnet} that provides a mapping
+facility, archival storage, and many other features.
 
-*Echo* mode allows you to detect and measure your own lunar echoes,
-even if they are far below the audible threshold.
+*Echo* mode allows you to detect and measure your own station's echoes
+from the moon, even if they are far below the audible threshold.
 
-_WSJT-X_ provides spectral displays for passbands up to 5 kHz,
-flexible rig control for nearly all modern radios used by amateurs,
-and a wide variety of special aids such as automatic Doppler tracking
-for EME QSOs and Echo testing.  The program runs equally well on
-Windows, Macintosh, and Linux systems, and installation packages are
-available for all three platforms.
+_WSJT-X_ provides spectral displays for receiver passbands as wide as
+5 kHz, flexible rig control for nearly all modern radios used by
+amateurs, and a wide variety of special aids such as automatic Doppler
+tracking for EME QSOs and Echo testing.  The program runs equally well
+on Windows, Macintosh, and Linux systems, and installation packages
+are available for all three platforms.
 
 _WSJT-X_ is an open-source project released under the {gnu_gpl}
 (GPL). If you have programming or documentation skills or would like

doc/user_guide/en/new_features.adoc

@@ -3,23 +3,24 @@
 For quick reference, here's a short list of features and capabilities
 added to _WSJT-X_ since Version 1.6.0:
 
-- New modes: ISCAT, MSK144, QRA64.
+- New modes: ISCAT, MSK144, QRA64
 
-- Newly implemented submodes of existing modes: JT65B-C, JT9B-H (wide
-and fast).
+- Newly implemented submodes of existing modes: JT65B-C, JT9B-H
+
+- Fast submodes of JT9
 
 - New Franke-Taylor decoder replaces the Koetter-Vardy decoder in
 JT65; the separate program `kvasd[.exe]` is no longer used.
 
-- Improvements to the JT4, JT9, and JT65 decoders.
+- Improvements to the JT4, JT9, and JT65 decoders
 
-- Multi-pass decoding for JT65 and WSPR.
+- Multi-pass decoding for JT65 and WSPR
 
-- Improved convenience features for EME Doppler tracking.
+- Improved convenience features for EME Doppler tracking
 
-- Multiple program configurations can be saved and restored.
+- Multiple program configurations can be saved and restored
 
-- A new sample-file download facility.
+- A new sample-file download facility
 
-- A number of corrections to the Hamlib library, fixing balky
-rig-control features.  
+- Many corrections and improvements to the Hamlib library, fixing
+balky rig-control features.

doc/user_guide/en/protocols.adoc

@@ -89,6 +89,12 @@ seconds. Tone spacing of the 9-FSK modulation is 12000/6912 = 1.736
 Hz, the inverse of the symbol duration. The total occupied bandwidth
 is 9 × 1.736 = 15.6 Hz.
 
+[[QRA64_PROTOCOL]]
+=== QRA64
+
+TBD
+
+
 [[PROTOCOL_SUMMARY]]
 === Comparison of Slow Modes
 
@@ -113,6 +119,12 @@ JT4, JT9, and JT65 in the following table:
  JT65B  5.3833   355.3   -24
  JT65C  10.767   710.6   -23
 
+ QRA64A  1.736   111.1   -28?
+ QRA64B  3.472   222.2   
+ QRA64C  6.944   444.4
+ QRA64D 13.889   888.9
+ QRA64E 27.228  1777.8
+
 
 Transmissions in all three modes are essentially the same length, and
 all use 72 bits to carry message information. At user level the modes
@@ -136,10 +148,6 @@ efficiency. On a busy HF band, the conventional 2-kHz-wide JT65
 sub-band is often filled with overlapping signals. Ten times as many
 JT9 signals can fit into the same frequency range, without collisions.
 
-=== QRA64
-
-TBD
-
 === ISCAT
 
 ISCAT messages are free-form, up to 28 characters in length.
@@ -154,14 +162,14 @@ available character set is
 
 Transmissions consist of sequences of 24 symbols: a synchronizing
 pattern of four symbols at tone numbers 0, 1, 3, and 2, followed by
-two symbols with tone number corresponding to the message length, and
-finally 18 symbols conveying the user's message, sent repeatedly
-character by character.  The message always starts with +@+, the
-beginning-of-message symbol, which is not displayed to the user.  The
-sync pattern and message-length indicator have a fixed repetition
-period, recurring every 24 symbols.  Message information occurs
-periodically within the 18 symbol positions set aside for its use,
-repeating at its own natural length.
+two symbols with tone number corresponding to (message length) and
+(message length + 5), and finally 18 symbols conveying the user's
+message, sent repeatedly character by character.  The message always
+starts with +@+, the beginning-of-message symbol, which is not
+displayed to the user.  The sync pattern and message-length indicator
+have a fixed repetition period, recurring every 24 symbols.  Message
+information occurs periodically within the 18 symbol positions set
+aside for its use, repeating at its own natural length.
 
 For example, consider the user message +CQ WA9XYZ+.  Including the
 beginning-of-message symbol +@+, the message is 10 characters long.
@@ -170,7 +178,7 @@ the transmitted message will therefore start out as shown in the first
 line below:
 
 ----
- 0132AA@CQ WA9XYZ@CQ WA9X0132AAYZ@CQ WA9XYZ@CQ W0132AAA9X ...
+ 0132AF@CQ WA9XYZ@CQ WA9X0132AFYZ@CQ WA9XYZ@CQ W0132AFA9X ...
  sync##                  sync##                 sync##
 ----
 
@@ -182,4 +190,58 @@ many times as will fit into a Tx sequence.
 
 === MSK144
 
-TBD
+(this section needs work ...)
+
+MSK144 is intended for meteor-scatter QSOs on the VHF bands.  Standard
+messages are structured in the same way as those in the slow modes,
+with a 72 bits of user information.  Forward error correction is
+implemented by first augmenting the 72 message bits with an 8-bit CRC
+calculated from the message bits. The CRC is used to detect and
+eliminate most false decodes at the receiver. The resulting 80-bit
+augmented message is then mapped to a 128-bit codeword using a
+(128,80) binary low-density-parity-check (LDPC) code designed
+specifically for this purpose.  Two 8-bit synchronizing sequences are
+added to make a message frame 144 bits long.  Modulation is Offset
+Quadrature Phase-Shift Keying (OQPSK) at 2000 baud. Even-numbered bits
+are conveted over the in-phase channel, odd-numbered bits on the
+quadrature channel.  Individual symbols are shaped with half-sine
+profiles, thereby ensuring a generated waveform with constant
+envelope, equivelent to a Minimum Shift Keying (MSK) waveform.  Frame
+duration is 72 ms so the effective character transmission rate for
+standard messages is as high as 250 cps.
+
+MSK144 also supports short-form messages that can be used after QSO
+partners have exchanged callsigns.  These consist of 4 bits that
+encode a signal report, R+report, RRR, or 73, together with a 12-bit
+hash code based on the ordered pair of callsigns is use.  A specially
+designed LDPC (32,16) code provides error-correction, and an 8-bit
+synchronizing vector is appended to make up a 40-bit frame.
+Short-message duration is thus 20 ms, and short messages can be
+conveyed by very short meteor "pings".
+
+As in the other fast modes in WSJT-X, the 72 ms or 20 ms frames of
+MSK144 messages are repeated without gaps for the full duration of a
+transmission cycle. For most purposes, a cycle duration of 15s is
+recommended for MSK144.
+
+The modulated MSK144 signal occupies the full bandwidth of a SSB
+transmitter, so transmissions are always centered on audio frequency
+1500 Hz. For best results, transmitter and receiver filters should be
+adjusted to provide the flattest possible response over the range
+300Hz to 2700Hz. Further, the maximum permissible frequency offset
+between you and your QSO partner should be ± 100 Hz.
+
+Details:
+
+Standard 72ms MSK frames contain 144 bits and consist of a standard
+JT-mode 72-bit message augmented with 56 bits for error detection and
+correction. The 72+56=128-bit codeword is combined with two 8-bit sync
+words to form a 144-bit frame. The frame is constructed as
+S8,D48,S8,D80, where S8 represents an 8-bit sync word and D48,D80
+represent the first 48 bits and last 80 bits of the 128-bit codeword,
+respectively. (At present, the 128-bit codeword is re-ordered to put
+even/odd bits at the beginning/end of the codeword — this is a
+holdover from JTMSK and is probably not necessary.) The 144-bit frame
+is repeated for the duration of a transmission cycle.
+
+

doc/user_guide/en/system-requirements.adoc

@@ -3,6 +3,7 @@
 - SSB transceiver and antenna 
 - Computer running Windows (XP or later), Linux, or OS X
 - 1.5 GHz or faster CPU and 200 MB of available memory
+- MSK144 benefits greatly from a multi-core CPU
 - Monitor with at least 1024 x 780 resolution
 - Computer-to-radio interface using a serial port or equivalent USB 
   device for T/R switching, or CAT control, or VOX, as required for 

doc/user_guide/en/vhf-features.adoc

@@ -1,23 +1,27 @@
 === VHF Setup
 
-_WSJT-X_ v1.7 builds on for VHF and
-higher bands first introduced in v1.6.  These features now include:
+_WSJT-X_ v1.7 builds on the features for VHF and higher bands first
+introduced in v1.6.  These features now include:
 
 - *JT4*, a mode particularly useful for EME on the microwave bands
 
-- *QRA64*, a mode for EME using a "`Q-ary Repeat Accumulate`" code, a
-low-density partity-check (LDPC) code using a 64-character symbol
+- *QRA64*, a mode for EME using a "`Q-ary Repeat Accumulate`" code --
+a low-density partity-check (LDPC) code with a 64-character symbol
 alphabet
 
-- *MSK144*, a mode for meteor scatter using a binary LDPC code
-and Offset Quadrature Phase-Shift Keying (OQPSK), a waveform also
-known as Minimum Shift Keying (MSK)
+- *MSK144*, a mode for meteor scatter using a binary LDPC code and
+Offset Quadrature Phase-Shift Keying (OQPSK), a waveform also
+describable as Minimum Shift Keying (MSK)
 
-- *ISCAT*, intended for other types of scatter propagation.
+- *ISCAT*, intended for aircraft scatter and other types of scatter
+propagation
 
 - *Echo* mode, for detecting and measuring your own lunar echoes
 
-- Automatic *Doppler tracking* for the EME path
+- Automatic *Doppler tracking* for the EME path.  This is increasingly
+important on bands above 1.2 GHz.
+
+- Optional *Auto-sequencing* of messages for the fast modes.
 
 To activate the VHF-and-up features:
 
@@ -27,11 +31,11 @@ To activate the VHF-and-up features:
 - In most cases you will also want to check *Single decode*.
 
 - If you will be doing EME, check the box *Decode at t = 52 s*
-to allow for the EME path delay on received signals
+to allow for the EME path delay on received signals.
 
 - If you will use automatic Doppler tracking and your radio accepts
 QSY commands while transmitting, check the box *Allow Tx frequency
-changes while transmitting*.  Transceivers that allow such changes
+changes while transmitting*.  Transceivers known to permit such changes
 include the IC-735, IC-756 Pro II, IC-910-H, FT-817, FT-847, FT-857,
 FT-897, TS-590S, TS-590SG, TS-2000 (with Rev 9 firmware upgrade), Flex
 1500 and 5000, HPSDR, Anan-10, Anan-100, and KX3. On the *Radio* tab
@@ -40,16 +44,27 @@ to experiment with both options to find one that works best with your
 radio).
 
 - If your radio does not accept commands to change frequency while
-transmissing, Doppler tracking is accomplished by making a single Tx
-frequency adjustment before transmitting, using a value computed for
-the middle of the Tx period.
+transmitting, Doppler tracking will be approximated by making a single
+Tx frequency adjustment before transmitting, using a value computed
+for the middle of the Tx period.
 
-- The main window reconfigures itself as necessary to include controls
-supporting features of each mode.  For example, in JT4 mode the
-central part of the main window might look something like this:
+- The main window will reconfigure itself as necessary to display
+controls supporting the features of each mode.  For example, in JT4 mode
+the central part of the main window might look something like this:
 
 image::VHF_controls.png[align="center",alt="VHF Controls"]
 
+- If you are using transverters, set appropriate frequency offsets on
+the *Settings | Frequencies* tab.  Offset is defined as (transceiver
+dial reading) minus (on-the-air frequency).  For example, when using a
+144 MHz radio at 10368 MHz, *Offset (MHz)* = (144 - 10368) =
+-10224.000.  If the band is already in the table, you can edit the
+offset by double clicking on the offset field itself.  Otherwise a new
+band can be added by right clicking in the table and selecting
+*Insert*.
+
+image::Add_station_info.png[align="center",alt="Station information"]
+
 - On the *View* menu, select *Astronomical data* to display a window
 with important information for tracking the Moon and performing
 automatic Doppler control.  Check the box labeled *Doppler tracking*
@@ -88,18 +103,8 @@ Higher spacings are used on the higher microwave bands, to allow for
 larger Doppler spreads. For example, submode JT4F is generally used
 for EME on the 10 GHz band.
 
-- If using a transverter, set the appropriate offset on the *Settings
-| Frequencies* tab.  Offset is defined as (transceiver dial reading)
-minus (on-the-air frequency).  For example, when using a 144 MHz radio
-at 10368 MHz, *Offset (MHz)* = (144 - 10368) = -10224.000.  If the
-band is already in the table, you can edit the offset by double
-clicking on the offset field itself.  Otherwise a new band can be
-added by right clicking in the table and selecting *Insert*.
-
-image::Add_station_info.png[align="center",alt="Station information"]
-
-- The JT4 decoder in _WSJT-X_ includes optional facilities for
-averaging over successive transmissions and also correlation decoding,
+- The JT4 decoder in _WSJT-X_ includes optional capabilities for
+averaging over successive transmissions, and correlation decoding,
 also known as "`Deep Search`".  Either or both of these options may
 be selected from the *Decode* menu.
 
@@ -109,8 +114,8 @@ image::decoding_depth.png[align="center",alt="Decoding Depth"]
 consisting of a single tone.  To activate automatic generation of
 these messages, check the box labeled *Sh* on the main window.
 
-IMPORTANT: Thanks to G3WDG, many additional hints for using JT4 and
-Echo mode on the EME path are available in {jt4eme}.
+IMPORTANT: Additional hints for using JT4 and Echo mode on the
+EME path have been compiled by G3WDG and are available here: {jt4eme}.
 
 === EME with JT65
 
@@ -122,7 +127,50 @@ TBD ...
 
 === Meteor Scatter with MSK144
 
-TBD ...
+Meteor-scatter QSOs can be made at any time on the VHF bands, at
+distances up to about 2100 km or 1300 miles.  Completing a QSO takes
+longer in the evening than in the morning, longer at 144 MHz than at
+50 MHz, and longer at 2000 km than 1500 km; but with patience, at
+least 100 Watts, and a single yagi it can usually be done.
+
+- Select *Tab 1* to present the traditional format for selecting Tx
+messages.
+
+- Select *MSK144* from the *Mode* and *Fast* from the *Decode* menu.
+
+- Set the audio receiving frequency to *Rx 1500 Hz*, frequency
+tolerance to *F Tol 100*, and T/R sequence duration to 15 s.
+
+- MSK144 does decodes received signals in real time, so you can see
+decoded messages almost as soon as you hear them.  To match decoding
+depth to your computer's capability, click *Monitor* (if
+necessary) to start a receiving sequence, and observe the percentage
+of CPU usage displayed on the _Receiving_ label in the Status Bar:
+
+image::Rx_pct_MSK144.png[align="center",alt="MSK144 Percent CPU"]
+
+- This number (here 17%) measures the fraction of CPU capability used
+being used by the MSK144 real-time decoder.  If it is well below, say,
+80% you may increase the decoding depth from *Fast* to *Normal* or
+*Deep*, and increase *F Tol* from 100 to 200 Hz.
+
+IMPORTANT: Most modern multi-core computers can easily handle these
+maximum parameters, but some slower machines may not be able to keep
+up.  In that case there will be some loss in decoding capability for
+the weakest pings.
+
+- You may now proceed to make QSOs using essentially the same
+procedures described in <<MAKE_QSOS,Making QSOs>>.
+
+- T/R sequences of 15 seconds or less make it sometimes desirable to
+switch transmitted messages very quickly.  Check the *Auto Seq* box
+to have the computer make the necessary decisions automatically.
+
+- For operation at 144 MHz or above, you might choose to use the
+MSK144 short-format messages for Tx3, Tx4, and Tx5.  Check the box
+labeled *Sh* to enable this feature.  (There is little need for this
+option at 50 or 70 MHz, where most pings are long enough to support
+the standard MSK144 message length.)
 
 === Scatter Propagation with ISCAT
 

doc/user_guide/en/wsjtx-main.adoc

@@ -134,6 +134,10 @@ include::tutorial-example1.adoc[]
 === JT9+JT65
 include::tutorial-example2.adoc[]
 
+[[MAKE_QSOS]]
+== Making QSOs
+include::make-qso.adoc[]
+
 [[WSPR]]
 == WSPR Mode
 include::wspr.adoc[]
@@ -142,10 +146,6 @@ include::wspr.adoc[]
 == VHF+ Features
 include::vhf-features.adoc[]
 
-[[MAKE_QSOS]]
-== Making QSOs
-include::make-qso.adoc[]
-
 [[COMMAND_REF]]
 == On-Screen Controls