Additions to Section 13.3 of WSJT-X User Guide: "Phase Equalkization".

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

doc/common/links.adoc

@@ -77,6 +77,7 @@ d). Edit lines as needed. Keeping them in alphabetic order help see dupes.
 :launchpadki7mt: https://launchpad.net/~ki7mt[KI7MT PPA's]
 :log4om: http://www.log4om.com[Log4OM]
 :lunarEchoes: http://physics.princeton.edu/pulsar/K1JT/LunarEchoes_QEX.pdf[QEX]
+:msk144: http://physics.princeton.edu/pulsar/k1jt/MSK144_Protocol_QEX.pdf[QEX]
 :msys_url: http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/[MSYS Download]
 :ntpsetup: http://www.satsignal.eu/ntp/setup.html[Network Time Protocol Setup]
 :osx_instructions: http://physics.princeton.edu/pulsar/K1JT/OSX_Readme[Mac OS X Install Instructions]

doc/user_guide/en/measurement_tools.adoc

@@ -72,60 +72,61 @@ slow modes, select *Measure reference spectrum* from the *Tools* menu.
 Wait for about a minute and then hit the *Stop* button.  A file named
 `refspec.dat` will appear in your log directory.  
 
- [ ... TBD ... ]
+ [ ... more to come ... ]
 
-=== Phase Response and Equalization
+=== Phase Equalization
 
 *Measure phase response* under the *Tools* menu is for advanced MSK144
 users. Phase equalization is used to compensate for group-delay
-variation across the passband of receiver filters. Careful application
+variation across your receiver passband. Careful application of this
-of this facility can reduce intersymbol interference, resulting in
+facility can reduce intersymbol interference, resulting in improved
-improved decoding sensitivity.  If you use a software-defined receiver
+decoding sensitivity.  If you use a software-defined receiver with
-with linear-phase filters there is no need to apply phase
+linear-phase filters there is no need to apply phase equalization.
-equalization.
 
-After a received frame is decoded *Measure phase response* generates
+After a frame of received data has been decoded, *Measure phase
-an undistorted waveform whose Fourier transform is used as a
+response* generates an undistorted audio waveform equal to the one
-frequency-dependent phase reference to compare with the phase of the
+generated by the transmitting station.  Its Fourier transform is then
-received frame's Fourier coefficients.  Phase differences between the
+used as a frequency-dependent phase reference to compare with the
-reference and the received waveform include contributions from the
+phase of the received frame's Fourier coefficients.  Phase differences
-originating station's transmit filter, the propagation channel, and
+between the reference spectrum and received spectrum will include
-filters in the receiver. If the received frame originates from a
+contributions from the originating station's transmit filter, the
-station known to transmit signals having little phase distortion (say,
+propagation channel, and filters in the receiver. If the received
-a station known to use a properly adjusted
+frame originates from a station known to transmit signals having
-software-defined-transceiver) and if the received signal is relatively
+little phase distortion (say, a station known to use a properly
-free from multipath distortion so that the channel phase is close to
+adjusted software-defined-transceiver) and if the received signal is
-linear, the measured phase differences will be representative of the
+relatively free from multipath distortion so that the channel phase is
-local receiver's phase response.
+close to linear, the measured phase differences will be representative
+of the local receiver's phase response.
 
 Complete the following steps to generate a phase equalization curve:
 
 - Record a number of wav files that contain decodable signals from
 your chosen reference station. Best results will be obtained when the
-SNR of the reference signals is at least 9 dB.
+aignal-to-noise ratio of the reference signals is 10 dB or greater.
 
 - Enter the callsign of the reference station in the DX Call box.
 
-- Select *Measure phase response* from the *Tools* menu, and process
+- Select *Measure phase response* from the *Tools* menu, and open each
-the wav files. The mode character will change from `&` to `^` while
+of the wav files in turn. The mode character on decoded text lines
-_WSJT-X_ is measuring the phase response and it will change back to
+will change from `&` to `^` while _WSJT-X_ is measuring the phase
-`&` after the measurement is completed. The program needs to average a
+response, and it will change back to `&`  after the measurement is
-number of high-SNR frames to accurately estimate the phase, so it may
+completed. The program needs to average a number of high-SNR frames to
-be necessary to process several wav files. The measurement can be
+accurately estimate the phase, so it may be necessary to process
-aborted at any time by selecting *Measure phase response* again to
+several wav files. The measurement can be aborted at any time by
-toggle the phase measurement off.
+selecting *Measure phase response* again to toggle the phase
+measurement off.
 
 +
 
 When the measurement is complete _WSJT-X_ will save the measured
 phase response in the *Log directory*, in a file with suffix
 ".pcoeff". The filename will contain the callsign of the reference
-station and a timestamp.  For example: K0TPP_170923_112027.pcoeff
+station and a timestamp, for example `K0TPP_170923_112027.pcoeff`.
 
 - Select *Equalization tools ...* under the *Tools* menu and click the
 *Phase ...* button to view the contents of the *Log directory*. Select
 the desired pcoeff file. The measured phase values will be plotted as
-discrete circles along with a fitted curve labeled "Proposed". This is
+filled circles along with a fitted red curve labeled "Proposed". This is
 the proposed phase equalization curve. It's a good idea to repeat the
 phase measurement several times, using different wav files for each
 measurement, to ensure that your measurements are repeatable.
@@ -135,55 +136,59 @@ to save the proposed response. The red curve will be replaced with a
 light green curve labeled "Current" to indicate that the phase
 equalization curve is now being applied to the received data. Another
 curve labeled "Group Delay" will appear. The "Group Delay" curve shows
-the group delay variation across the passband, in ms. Push the
+the group delay variation across the passband, in ms. Click the
 *Discard*  button to remove the captured data, leaving only the applied
 phase equalization curve and corresponding group delay curve.
 
 - To revert to no phase equalization, push the *Restore Defaults*
 button followed by the *Apply* button.
 
-The three numbers that are printed at the end of each MSK144 decode line
+The three numbers printed at the end of each MSK144 decode line can be
-can be used to assess the improvement provided by equalization. These numbers
+used to assess the improvement provided by equalization. These numbers
-`N` `H` `E` are:
+are: `N` = Number of frames averaged, `H` = Number of hard bit errors
- `N` - Number of frames averaged,
+corrected, `E` = Size of MSK eye diagram opening.
- `H` - Number of bit errors corrected,
- `E` - Size of MSK eye diagram opening. 
 
 Here is a decode of K0TPP obtained while *Measure phase response* was measuring
 the phase response:
 
   103900  17  6.5 1493 ^  WA8CLT K0TPP +07       1  0  1.2
 
-The "^" symbol indicates that a phase measurement is being accumulated. The 
+The "^" symbol indicates that a phase measurement is being accumulated
-three numbers at the end of the line indicate that one frame was
+but is not yet finished. The three numbers at the end of the line
-used to obtain the decode, there were no bit errors, and the 
+indicate that one frame was used to obtain the decode, there were no
-eye-opening was 1.2. Here's how the same decode looks after phase equalization:
+hard bit errors, and the eye-opening was 1.2 on a -2 to +2
+scale.  Here's how the same decode looks after phase equalization:
 
   103900  17  6.5 1493 &  WA8CLT K0TPP +07       1  0  1.6
 
-In this case, equalization has increased the eye opening from 1.2 to 1.6.
+In this case, equalization has increased the eye opening from 1.2 to
-Larger eye openings are associated with reduced likelihood of bit errors and
+1.6.  Larger positive eye openings are associated with reduced
-higher likelihood that a frame will be successfully decoded. 
+likelihood of bit errors and higher likelihood that a frame will be
-In this case, the larger eye-opening 
+successfully decoded.  In this case, the larger eye-opening tells us
-tells us that phase equalization was successful, but it is important to note
+that phase equalization was successful, but it is important to note
-that this test does not tell us whether the applied phase equalization curve
+that this test does not by itself tell us whether the applied phase
-is going to improve decoding of signals other than those from the reference 
+equalization curve is going to improve decoding of signals other than
-station, K0TPP! 
+those from the reference station, K0TPP.
 
-We strongly advise you to carry out before and after comparisons 
+It's a good idea to carry out before and after comparisons using a
-using a large number of saved wav files with signals from many different 
+large number of saved wav files with signals from many different
-stations to decide whether or not the equalization curve improves decoding for most 
+stations, to help decide whether your equalization curve improves
-signals. When doing before and after comparisons, keep in mind that 
+decoding for most signals. When doing such comparisons, keep in mind
-equalization may cause _WSJT-X_ to successfully decode a frame 
+that equalization may cause _WSJT-X_ to successfully decode a frame
-that was not decoded before equalization was applied.  
+that was not decoded before equalization was applied.  For this
-For this reason, be sure that the time "T" of
+reason, be sure that the time "T" of the two decodes are the same
-the two decodes are the same before comparing their end-of-line quality numbers.
+before comparing their end-of-line quality numbers.
 
-When comparing before and after decodes having the same "T", keep in mind
+When comparing before and after decodes having the same "T", keep in
-that a smaller first number means that decoding has improved, even if the 
+mind that a smaller first number means that decoding has improved,
-second and third numbers appear to be "worse". For example, suppose that the quality
+even if the second and third numbers appear to be "worse". For
-numbers before equalization are "2 0  0.2" and after equalization 
+example, suppose that the end-of-line quality numbers before
-"1 5 -0.5". These numbers show improved decoding because 
+equalization are `2 0 0.2` and after equalization `1 5 -0.5`. These
-the decode was obtained using only a single
+numbers show improved decoding because the decode was obtained using
-frame after equalization whereas a 2-frame average was needed before equalization.
+only a single frame after equalization whereas a 2-frame average was
+needed before equalization.  This implies that shorter and/or weaker
+pings could be decodable.
 
+NOTE: Further details on phase equalization and examples of fitted
+phase curves and eye diagrams can be found in the article on MSK144 by
+K9AN and K1JT published in {msk144}.