Additions to User Guide.

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

doc/user_guide/en/controls-functions-wide-graph.adoc

@@ -51,3 +51,38 @@ and your own preferences.
 Smoothing the displayed spectrum over more than one bin can enhance
 your ability to detect weak EME signals with Doppler spread more than
 a few Hz.
+
+[[CONTROLS_FAST]]
+=== Fast Graph
+
+Three sliders at the bottom of the Fast Graph window can be used to
+optimize gain and zero-offset of the displayed information.  Hover the
+mouse over a control to display a tip reminding you of its function.
+Clicking the *Auto Level* button will produce reasonable settings
+as a starting point.  The waterfall palette used on this graph is
+the same as the one selected on the Wide Graph.
+
+image::fast-graph-controls.png[align="center",alt="Fast Graph Controls"]
+
+[[CONTROLS_ECHO]]
+=== Echo Graph
+
+Controls at the bottom of the Echo Graph
+
+- *Bins/Pixel* controls the displayed frequency resolution.  Set this
+value to 1 for the highest possible resolution, or to higher numbers
+to compress the spectral display.
+
+- *Gain* and *Zero* sliders control scaling and offset of plotted
+spectra.
+
+- *Smooth* values greater than 0 apply running averages to the plotted
+spectra.
+
+- Label *N* shows the number of echo pulses averaged.
+
+- Click the *Colors* button to cycle through 6 possible choices of
+color and line width for the plots.
+
+image::echo-graph-controls.png[align="center",alt="EchoGraph Controls"]
+

doc/user_guide/en/protocols.adoc

@@ -1,106 +1,110 @@
-[[JT65PRO]]
+[[PROTOCOL_OVERVIEW]]
-=== JT65
+=== Overview
 
-JT65 was designed for making minimal QSOs via EME ("`moon-bounce`") on
+All QSO modes except ISCAT benefit from the use of structured
-the VHF and UHF bands. A detailed description of the protocol and its
+messages.  Each such message consists of two 28-bit fields for
-implementation in program _WSJT_ was published in {jt65protocol} for
+callsigns and a 15-bit field for a grid locator, report,
-September-October, 2005. Briefly stated, JT65 uses 60 s T/R sequences
+acknowledgment, or a "`73`" sign-off indicator.  Alternatively, a
-and carefully structured messages. Standard messages are compressed so
+72^nd^ bit flags a message containing arbitrary alphanumeric text, up
-that two callsigns and a grid locator can be transmitted in just 71
+to 13 characters.  Special formats allow other information such as
-information bits.  A 72^nd^ bit serves as a flag to indicate that a
+add-on callsign prefixes (e.g., ZA/K1ABC) or suffixes (e.g., K1ABC/4)
-message consists of arbitrary text (up to 13 characters) instead of
+to be encoded. The basic aim is to compress the most common messages
-callsigns and a grid locator.  Special formats allow other information
+used for minimally valid QSOs into a fixed 72-bit length.  To be
-such as add-on callsign prefixes (e.g., ZA/K1ABC) or numerical signal
+useful, this kind of lossless message compression requires use of a
-reports (in dB) to be substituted for the grid locator. The basic aim
+strong forward error correcting (FEC) code.  Different FEC codes are
-is to compress the most common messages used for minimally valid QSOs
+used for each mode.  These modes require good synchronization of time
-into a minimum fixed number of bits. After compression, a Reed Solomon
+and frequency between transmitting and receiving stations.  As an aid
-(63,12) error-control code converts 72-bit user messages into
+to the decoders, each protocol includes a "`synch vector`" of known
-sequences of 63 six-bit channel symbols.
+symbols along with the information-carrying symbols.  Generated
-
+waveforms for all of the _WSJT-X_ modes have continuous phase and
-JT65 requires tight synchronization of time and frequency between
+a constant envelope.
-transmitting and receiving stations. Each transmission is divided into
-126 contiguous tone intervals or "`symbols`" of length 4096/11025 =
-0.372 s. Within each interval the waveform is a constant-amplitude
-sinusoid at one of 65 pre-defined frequencies. Frequency steps between
-intervals are accomplished in a phase-continuous manner. Half of the
-channel symbols are devoted to a pseudo-random synchronizing vector
-interleaved with the encoded information symbols. The sync vector
-allows calibration of time and frequency offsets between transmitter
-and receiver. A transmission nominally begins at t = 1 s after the
-start of a UTC minute and finishes at t = 47.8 seconds. The
-synchronizing tone is at 11025 × 472/4096 = 1270.46 Hz, and is
-normally sent in each interval having a “1” in the following
-pseudo-random sequence:
-
- 100110001111110101000101100100011100111101101111000110101011001
- 101010100100000011000000011010010110101010011001001000011111111
-
-Encoded user information is transmitted during the 63 intervals not
-used for the sync tone. Each channel symbol generates a tone at
-frequency 11025 × 472/4096 + 11025/4096 × (N+2) × m, where N is the
-value of the six-bit symbol, 0 ≤ N ≤ 63, and m is 1, 2, or 4 for JT65
-sub-modes A, B, or C.  Sub-mode JT65A is always used at HF.
-
-For EME (but, conventionally, not on the HF bands) the signal report
-OOO is sometimes used instead of numerical signal reports. It is
-conveyed by reversing sync and data positions in the transmitted
-sequence.  Shorthand messages for RO, RRR, and 73 dispense with the
-sync vector entirely and use time intervals of 16384/11025 = 1.486 s
-for pairs of alternating tones. The lower frequency is always 1270.46
-Hz, the same as that of the sync tone, and the frequency separation is
-110250/4096 = 26.92 Hz multiplied by n × m, with n = 2, 3, 4 for the
-messages RO, RRR, and 73.
 
 [[JT4PRO]]
 === JT4
 
-JT4 uses 72-bit structured messages nearly identical to those in
+FEC in JT4 uses a strong convolutional code with constraint length
-JT65. Error control coding (ECC) uses a strong convolutional code with
+K=32, rate r=1/2, and a zero tail. This choice leads to an encoded
-constraint length K=32, rate r=1/2, and a zero tail, leading to an
+message length of (72+31) x 2 = 206 information-carrying bits.
-encoded message length of (72+31) x 2 = 206 information-carrying
+Modulation is 4-tone frequency-shift keying (4-FSK) at 11025 / 2520 =
-bits. Modulation is 4-tone frequency-shift keying at 11025 / 2520 =
 4.375 baud.  Each symbol carries one information bit (the most
-significant bit) and ony synchronizing bit (the least signicifant
+significant bit) and one synchronizing bit.  The pseudo-random sync
-bit).  The pseudo-random sync vector is the following sequence:
+vector is the following sequence:
 
  000011000110110010100000001100000000000010110110101111101000
  100100111110001010001111011001000110101010101111101010110101
  011100101101111000011011000111011101110010001101100100011111
  10011000011000101101111010
 
+The two 32-bit polynomials used for convolutional encoding have
+hexadecimal values f2d05351 and e4613c47.
+
 [[JT9PRO]]
 === JT9
 
-JT9 is designed for making minimally valid QSOs at LF, MF, and HF. It
+FEC in JT9 uses the same strong convolutional code aa JT4: constraint
-uses 72-bit structured messages nearly identical (at the user level)
+length K=32, rate r=1/2, and a zero tail, leading to an encoded
-to those in JT65. Error control coding (ECC) uses a strong
+message length of (72+31) × 2 = 206 information-carrying
-convolutional code with constraint length K=32, rate r=1/2, and a zero
+bits. Modulation is nine-tone frequency-shift keying, 9-FSK at
-tail, leading to an encoded message length of (72+31) × 2 = 206
+12000.0/6912 = 1.736 baud.  Eight tones are used for data, one for
-information-carrying bits. Modulation is nine-tone frequency-shift
-keying, 9-FSK.  Eight tones are used for data, one for
 synchronization. Eight data tones means that three data bits are
 conveyed by each transmitted information symbol. Sixteen symbol
 intervals are devoted to synchronization, so a transmission requires a
 total of 206 / 3 + 16 = 85 (rounded up) channel symbols. The sync
 symbols are those numbered 1, 2, 5, 10, 16, 23, 33, 35, 51, 52, 55,
-60, 66, 73, 83, and 85 in the transmitted sequence.  Each symbol lasts
+60, 66, 73, 83, and 85 in the transmitted sequence.  Tone spacing of
-for 6912 sample intervals at 12000 samples per second, or about 0.576
+the 9-FSK modulation for JT9A is equal to the keying rate, 1.736 Hz.
-seconds. Tone spacing of the 9-FSK modulation is 12000/6912 = 1.736
+The total occupied bandwidth is 9 × 1.736 = 15.6 Hz.
-Hz, the inverse of the symbol duration. The total occupied bandwidth
+
-is 9 × 1.736 = 15.6 Hz.
+[[JT65PRO]]
+=== JT65
+
+A detailed description of the JT65 protocol was published in
+{jt65protocol} for September-October, 2005. A Reed Solomon (63,12)
+error-control code converts 72-bit user messages into sequences of 63
+six-bit information-carrying symbols.  These are interleaved with
+another 63 symbols of synchronizing information according to the
+following pseudo-random sequence:
+
+ 100110001111110101000101100100011100111101101111000110101011001
+ 101010100100000011000000011010010110101010011001001000011111111
+
+
+The synchronizing tone is normally sent in each interval having a
+"`1`" in the sequence. Modulation is 65-FSK at 11025/4096 = 2.692
+baud.  Frequency spacing between tones is equal to the keying rate for
+JT65A, and 2 and 4 times larger for JT65B and JT65C.  For EME QSOs the
+signal report OOO is sometimes used instead of numerical signal
+reports. It is conveyed by reversing sync and data positions in the
+transmitted sequence.  Shorthand messages for RO, RRR, and 73 dispense
+with the sync vector entirely and use time intervals of 16384/11025 =
+1.486 s for pairs of alternating tones. The lower frequency is the
+same as that of the sync tone used in long messages, and the frequency
+separation is 110250/4096 = 26.92 Hz multiplied by n for JT65A, with n
+= 2, 3, 4 used to convey the messages RO, RRR, and 73.
 
 [[QRA64_PROTOCOL]]
 === QRA64
 
-TBD
+Still to come ...
 
+[[SLOW_SUMMARY]]
+=== Slow Modes
 
-[[PROTOCOL_SUMMARY]]
+[[SLOW_TAB]]
-=== Comparison of Slow Modes
+.Parameters of Slow Modes
+[width="90%",cols="3h,^3,^2,^1,^2,^2,^2,^2,^2,^2",frame=topbot,options="header"]
+|===============================================================================
+|Mode  |FEC Type   |(k,n)   | Q|  Mod | Baud |BW (Hz)|fSync|TxT (s)|S/N (dB)
+|JT4A  |K=32, r=1/2|(206,72)| 2| 4-FSK| 4.375|  17.5 | 0.50| 47.1   | -23
+|JT9A  |K=13, r=1/2|(206,72)| 8| 9-FSK| 1.736|  15.6 | 0.19| 49.0   | -27
+|JT65A |RS         |(63,12) |64|65-FSK| 2.692| 177.6 | 0.50| 46.8   | -25
+|QRA64A|QRA        |(63,12) |64|64-FSK| 1.736| 111.1 | 0.25| 48.4   | -28
+| WSPR |K=32, r=1/2|(162,50)| 2| 4-FSK| 1.465|   5.9 | 0.50|110.6   | -29
+|===============================================================================
 
 Frequency spacing between tones, total occupied bandwidth, and
-approximate decoding thresholds are given for the various submodes of
+approximate threshold signal-to-noise ratios are given for the various
-JT4, JT9, and JT65 in the following table:
+submodes of JT4, JT9, JT65, and QRA64 in the following table:
 
  Submode Spacing   BW    S/N
            (Hz)   (Hz)    dB
@@ -125,28 +129,16 @@ JT4, JT9, and JT65 in the following table:
  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
-support nearly identical message structures.
-
 JT4 and JT65 signal reports are constrained to the range –1 to –30
 dB. This range is more than adequate for EME purposes, but not enough
 for optimum use at HF. S/N values displayed by the JT4 and JT65
-decoders are clamped at an upper limit –1 dB, and the S/N scale is
+decoders are clamped at an upper limit –1 dB, and the S/N scale
-nonlinear above –10 dB.
+becomes significantly nonlinear above –10 dB.  JT9 allows signal
-
+reports in the range –50 to +49 dB. It manages this by taking over a
-By comparison, JT9 allows for signal reports in the range –50 to +49
+small portion of "`message space`" that would otherwise be used for
-dB. It manages this by taking over a small portion of "`message
+grid locators within 1 degree of the south pole. The S/N scale of the
-space`" that would otherwise be used for grid locators within 1 degree
+present JT9 decoder is reasonably linear (although it's not intended
-of the south pole. The S/N scale of the present JT9 decoder is
+to be a precision measurement tool).
-reasonably linear (although it's not intended to be a precision
-measurement tool).  
-
-JT9 is an order of magnitude better than JT65 in spectral
-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.
 
 === ISCAT
 
@@ -190,74 +182,44 @@ many times as will fit into a Tx sequence.
 
 === MSK144
 
-(this section needs work ...)
+Standard MSK144 messages are structured in the same way as those in
-
+the slow modes, with a 72 bits of user information.  Forward error
-MSK144 is intended for meteor-scatter QSOs on the VHF bands.  Standard
+correction is implemented by first augmenting the 72 message bits with
-messages are structured in the same way as those in the slow modes,
+an 8-bit CRC calculated from the message bits. The CRC is used to
-with a 72 bits of user information.  Forward error correction is
+detect and eliminate most false decodes at the receiver. The resulting
-implemented by first augmenting the 72 message bits with an 8-bit CRC
+80-bit augmented message is mapped to a 128-bit codeword using a
-calculated from the message bits. The CRC is used to detect and
+(128,80) binary low-density-parity-check (LDPC) code designed by K9AN
-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
+are conveyed 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
+duration is 72 ms, so the effective character transmission rate for
-standard messages is as high as 250 cps.
+standard messages is up to 250 cps.
 
 MSK144 also supports short-form messages that can be used after QSO
-partners have exchanged callsigns.  These consist of 4 bits that
+partners have exchanged both callsigns.  Short messages consist of 4
-encode a signal report, R+report, RRR, or 73, together with a 12-bit
+bits encoding a signal report, R+report, RRR, or 73, together with a
-hash code based on the ordered pair of callsigns is use.  A specially
+12-bit hash code based on the ordered pair of "`to`" and "`from`"
-designed LDPC (32,16) code provides error-correction, and an 8-bit
+callsigns.  Another specially designed LDPC (32,16) code provides
-synchronizing vector is appended to make up a 40-bit frame.
+error correction, and an 8-bit synchronizing vector is appended to
-Short-message duration is thus 20 ms, and short messages can be
+make up a 40-bit frame.  Short-message duration is thus 20 ms, and
-conveyed by very short meteor "pings".
+short messages can be decoded from very short meteor pings.
 
-As in the other fast modes in WSJT-X, the 72 ms or 20 ms frames of
+The 72 ms or 20 ms frames of MSK144 messages are repeated without gaps
-MSK144 messages are repeated without gaps for the full duration of a
+for the full duration of a transmission cycle. For most purposes, a
-transmission cycle. For most purposes, a cycle duration of 15s is
+cycle duration of 15 s is suitable and recommended for MSK144.
-recommended for MSK144.
 
 The modulated MSK144 signal occupies the full bandwidth of a SSB
-transmitter, so transmissions are always centered on audio frequency
+transmitter, so transmissions are always centered at 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
+300Hz to 2700Hz. The maximum permissible frequency offset between you
-between you and your QSO partner should be ± 100 Hz.
+and your QSO partner ± 200 Hz.
 
-Details:
+=== Fast Modes
-
-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.
-
-
-=== Summary
-
-[[SLOW_TAB]]
-.Parameters of Slow Modes
-[width="90%",cols="3h,^3,^2,^1,^2,^2,^2,^2,^2,^2",frame=topbot,options="header"]
-|===============================================================================
-|Mode  |FEC Type   |(k,n)   | Q|  Mod | Baud |BW (Hz)|fSync|TxT (s)|S/N (dB)
-|JT4A  |K=32, r=1/2|(206,72)| 2| 4-FSK| 4.375|  17.5 | 0.50| 47.1   | -23
-|JT9A  |K=13, r=1/2|(206,72)| 8| 9-FSK| 1.736|  15.6 | 0.19| 49.0   | -27
-|JT65A |RS         |(63,12) |64|65-FSK| 2.692| 177.6 | 0.50| 46.8   | -25
-|QRA64A|QRA        |(63,12) |64|64-FSK| 1.736| 111.1 | 0.25| 48.4   | -28
-| WSPR |K=32, r=1/2|(162,50)| 2| 4-FSK| 1.465|   5.9 | 0.50|110.6   | -29
-|===============================================================================
 
 .Parameters of Fast Modes
 [width="90%",cols="3h,^3,^2,^1,^2,^2,^2,^2,^2,^2",frame="topbot",options="header"]

doc/user_guide/en/vhf-features.adoc

@@ -116,7 +116,7 @@ averaging* over successive transmissions and/or correlation decoding,
 image::decoding_depth.png[align="center",alt="Decoding Depth"]
 
 IMPORTANT: Additional hints for using JT4 and Echo mode on the
-EME path have been compiled by G3WDG and are available here: {jt4eme}.
+*EME path have been compiled by G3WDG and are available here: {jt4eme}.
 
 === JT65
 
@@ -142,6 +142,14 @@ _WSJT-X_, Version 1.7.  The protocol is still subject to change, and
 some features of the decoder will likely change.  In most ways
 operation of QRA64 is similar to JT65.
 
+=== ISCAT
+
+ISCAT is a useful mode for signals that are weak but more or less
+steady in amplitude, at least for several seconds.  Aircraft scatter
+at 10 GHz is a good example.  ISCAT messages are free-format and may
+have any length from 1 to 28 characters.  The protocol includes no
+error-correction facility.
+
 === MSK144
 
 Meteor-scatter QSOs can be made any time on the VHF bands at distances
@@ -199,10 +207,6 @@ IMPORTANT: There is little or no advantage to using MSK144 *Sh*
 messages at 50 or 70 MHz.  At these frequencies most pings are long
 enough to support standard messages.
 
-=== Scatter Propagation with ISCAT
-
-TBD ...
-
 === Echo Mode
 
 *Echo* mode allows you to make sensitive measurements of your own

doc/user_guide/en/wsjtx-main.adoc

@@ -148,10 +148,6 @@ include::wspr.adoc[]
 [[COMMAND_REF]]
 == On-Screen Controls
 
-[[CONTROLS_WIDE]]
-=== Wide Graph
-include::controls-functions-wide-graph.adoc[]
-
 [[CONTROLS_MAIN]]
 === Main Window
 include::controls-functions-main-window.adoc[]
@@ -176,6 +172,10 @@ include::controls-functions-status-bar.adoc[]
 === Menus
 include::controls-functions-menus.adoc[]
 
+[[CONTROLS_WIDE]]
+=== Wide Graph
+include::controls-functions-wide-graph.adoc[]
+
 [[LOGGING]]
 == Logging
 include::logging.adoc[]
@@ -201,19 +201,20 @@ include::protocols.adoc[]
 == Astronomical Data
 include::astro_data.adoc[]
 
+
+////
 [[TXRX]]
 == Implementation Details
 include::implementation.adoc[]
 
-////
 [[TROUBLE_SHOOTING]]
 == Troubleshooting
 To be added (?) ...
-////
 
 [[UTIL]]
 == Utility Programs
 include::utilities.adoc[]
+////
 
 [[SUPPORT]]
 == Support