WSJT-X/doc/user_guide/en/measurement_tools.adoc

=== Frequency Calibration

Many _WSJT-X_ capabilities depend on signal-detection bandwidths no
more than a few Hz.  Frequency accuracy and stability are therefore
unusually important.  We provide tools to enable accurate frequency
calibration of your radio, as well as precise frequency measurement of
on-the-air signals.  The calibration procedure works by automatically
cycling your CAT-controlled radio through a series of preset
frequencies of carrier-based signals at reliably known frequencies,
measuring the error in dial frequency for each signal.

You will probably find it convenient to define and use a special
<<CONFIG-MENU,Configuration>> dedicated to frequency calibration.
Then complete the following steps, as appropriate for your system.

- Switch to FreqCal mode

- In the _Working Frequencies_ box on the *Settings -> Frequencies*
tab, delete any default frequencies for *FreqCal* mode that are not
relevant for your location.  You may want to replace some of them with
reliably known frequencies receivable at your location.

+

TIP: We find major-city AM broadcast stations generally serve well as
frequency calibrators at the low frequency end of the spectrum.  In
North America we also use the standard time-and-frequency broadcasts
of WWV at 2.500, 5.000, 10.000, 15.000, and 20.000 MHz, and CHU at
3.330, 7.850, and 14.670 MHz.  Similar shortwave signals are available
in other parts of the world.

- In most cases you will want to start by deleting any existing file
`fmt.all` in the directory where your log files are kept.

- To cycle automatically through your chosen list of calibration
frequencies, check *Execute frequency calibration cycle* on the
*Tools* menu.  _WSJT-X_ will spend 30 seconds at each
frequency. Initially no measurement data is saved to the `fmt.all`
file although it is displayed on screen, this allows you to check your
current calibration parameters.

- During the calibration procedure, the radio's USB dial frequency is
offset 1500 Hz below each *FreqCal* entry in the default frequencies
list.  As shown in the screen shot below, detected signal carriers
therefore appear at about 1500 Hz in the _WSJT-X_ waterfall.

- To start a measurement session, check the *Measure* option and let
the calibration cycle run for at least one complete sequence. Note
that, while measuring, any existing calibration parameters are
automatically disabled so you may have to increase the *FTol* range if
your rig is off frequency by more than a few Hertz in order to capture
valid measurements.

image::FreqCal.png[align="left",alt="FreqCal"]

With modern synthesized radios, small measured offsets from 1500 Hz
will exhibit a straight-line dependence on frequency.  You can
approximate the calibration of your radio by simply dividing the
measured frequency offset (in Hz) at the highest reliable frequency by
the nominal frequency itself (in MHz).  For example, the 20 MHz
measurement for WWV shown above produced a measured tone offset of
24.6 Hz, displayed in the _WSJT-X_ decoded text window.  The resulting
calibration constant is 24.6/20=1.23 parts per million.  This number
may be entered as *Slope* on the *settings -> Frequencies* tab.

A more precise calibration can be effected by fitting the intercept
and slope of a straight line to the whole sequence of calibration
measurements, as shown for these measurements in the graph plotted
below.  Software tools for completing this task are included with the
_WSJT-X_ installation, and detailed instructions for their use are
available at https://physics.princeton.edu/pulsar/k1jt/FMT_User.pdf.

Using these tools and no specialized hardware beyond your
CAT-interfaced radio, you can calibrate the radio to better than 1 Hz
and compete very effectively in the ARRL's periodic Frequency
Measuring Tests.

image::FreqCal_Graph.png[align="left",alt="FreqCal_Graph"]

After running *Execute frequency calibration cycle* at least once with
good results, check and edit the file `fmt.all` in the log directory
and delete any spurious or outlier measurements.  The line-fitting
procedure can then be carried out automatically by clicking *Solve for
calibration parameters* on the *Tools* menu.  The results will be
displayed as in the following screen shot.  Estimated uncertainties
are included for slope and intercept; `N` is the number of averaged
frequency measurements included in the fit, and `StdDev` is the root
mean square deviation of averaged measurements from the fitted
straight line. If the solution seems valid you will be offered an
*Apply* button to push that will automatically set the calibration
parameters in *Settings -> Frequencies -> Frequency Calibration*.

image::FreqCal_Results.png[align="center",alt="FreqCal_Results"]

For a quick visual check of the resulting calibration, stay in
*FreqCal* mode with the *Measure* option cleared. _WSJT-X_ will show
the adjusted results directly on the waterfall and the displayed
records.

=== Reference Spectrum

_WSJT-X_ provides a tool that can be used to determine the detailed
shape of your receiver's passband.  Disconnect your antenna or tune to
a quiet frequency with no signals.  With _WSJT-X_ running in one of
the 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.  When you check
*Ref Spec* on the *Wide Graph*, the recorded reference spectrum will
then be used to flatten your overall effective passband.

=== 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 your receiver passband. Careful application of this
facility can reduce intersymbol interference, resulting in improved
decoding sensitivity.  If you use a software-defined receiver with
linear-phase filters there is no need to apply phase equalization.

After a frame of received data has been decoded, *Measure phase
response* generates an undistorted audio waveform equal to the one
generated by the transmitting station.  Its Fourier transform is then
used as a frequency-dependent phase reference to compare with the
phase of the received frame's Fourier coefficients.  Phase differences
between the reference spectrum and received spectrum will include
contributions from the originating station's transmit filter, the
propagation channel, and filters in the receiver. If the received
frame originates from a station known to transmit signals having
little phase distortion (say, a station known to use a properly
adjusted software-defined-transceiver) and if the received signal is
relatively free from multipath distortion so that the channel phase is
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
signal-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 open each
of the wav files in turn. The mode character on decoded text lines
will change from `&` to `^` while _WSJT-X_ is measuring the phase
response, and it will change back to `&`  after the measurement is
completed. The program needs to average a number of high-SNR frames to
accurately estimate the phase, so it may be necessary to process
several wav files. The measurement can be aborted at any time by
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`.

- 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
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.

- Once you are satisfied with a fitted curve, push the *Apply* button
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. Click the
*Discard Measured*  button to remove the captured data from the plot, 
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 printed at the end of each MSK144 decode line can be
used to assess the improvement provided by equalization. These numbers
are: `N` = Number of frames averaged, `H` = Number of hard 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
but is not yet finished. The three numbers at the end of the line
indicate that one frame was used to obtain the decode, there were no
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.  Larger positive eye openings are associated with reduced
likelihood of bit errors and higher likelihood that a frame will be
successfully decoded.  In this case, the larger eye-opening tells us
that phase equalization was successful, but it is important to note
that this test does not by itself tell us whether the applied phase
equalization curve is going to improve decoding of signals other than
those from the reference station, K0TPP.

It's a good idea to carry out before and after comparisons using a
large number of saved wav files with signals from many different
stations, to help decide whether your equalization curve improves
decoding for most signals. When doing such comparisons, keep in mind
that equalization may cause _WSJT-X_ to successfully decode a frame
that was not decoded before equalization was applied.  For this
reason, be sure that the time "T" of the two decodes are the same
before comparing their end-of-line quality numbers.

When comparing before and after decodes having the same "T", keep in
mind that a smaller first number means that decoding has improved,
even if the second and third numbers appear to be "worse". For
example, suppose that the end-of-line quality numbers before
equalization are `2 0 0.2` and after equalization `1 5 -0.5`. These
numbers show improved decoding because the decode was obtained using
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}.