w4kek/WSJT-X
1
0
Fork 0
mirror of https://github.com/saitohirga/WSJT-X.git synced 2025-09-02 21:27:52 -04:00
Code Issues Packages Projects Releases Wiki Activity

User guide updates for frequency calibration mode

Browse Source 
Also some instances of non-italicized WSJT-X fixed.

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@8169 ab8295b8-cf94-4d9e-aec4-7959e3be5d79
This commit is contained in:
Bill Somerville 2017-10-13 22:34:48 +00:00
parent 895ff4dcc0
commit 29423748c9
6 changed files with 234 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/user_guide/en/controls-functions-menus.adoc
View File

@ -5,7 +5,7 @@ and operation. Most of the items are self-explanatory; a few
additional details are provided below. Keyboard shortcuts for some additional details are provided below. Keyboard shortcuts for some
frequently used menu items are listed at the right edge of the menu. frequently used menu items are listed at the right edge of the menu.
==== WSJT-X menu ==== _WSJT-X_ menu
image::MacAppMenu.png[align="left",alt="Mac App Menu"] image::MacAppMenu.png[align="left",alt="Mac App Menu"]
This menu appears on the Macintosh only. *Settings* appears here, This menu appears on the Macintosh only. *Settings* appears here,

2
doc/user_guide/en/decoder_notes.adoc
View File

@ -44,7 +44,7 @@ successful decode used MyCall as hypothetically known information.
|=============================================== |===============================================
Table 2 lists the six possible QSO states that are tracked by the Table 2 lists the six possible QSO states that are tracked by the
WSJT-X auto-sequencer, along with the type of AP decoding that would _WSJT-X_ auto-sequencer, along with the type of AP decoding that would
be attempted in each state. be attempted in each state.
[[AP_DECODING_TYPES_TABLE]] [[AP_DECODING_TYPES_TABLE]]

5
doc/user_guide/en/faq.adoc
View File

@ -69,6 +69,9 @@ command-prompt window:
sudo apt remove appmenu-qt5 sudo apt remove appmenu-qt5
+ +
Alternatively, you can disable the common menu bar for just WSJT-X by starting the application with the environment variable QT_QPA_PLATFORMTHEME set to empty (the space after the '=' character is necessary): Alternatively, you can disable the common menu bar for just _WSJT-X_
by starting the application with the environment variable
QT_QPA_PLATFORMTHEME set to empty (the space after the '=' character
is necessary):
QT_QPA_PLATFORMTHEME= wsjtx QT_QPA_PLATFORMTHEME= wsjtx

439
doc/user_guide/en/measurement_tools.adoc
View File

@ -1,213 +1,226 @@
=== Frequency Calibration === Frequency Calibration
Many _WSJT-X_ capabilities depend on signal-detection bandwidths no Many _WSJT-X_ capabilities depend on signal-detection bandwidths no
more than a few Hz. Frequency accuracy and stability are therefore more than a few Hz. Frequency accuracy and stability are therefore
unusually important. We provide tools to enable accurate frequency unusually important. We provide tools to enable accurate frequency
calibration of your radio, as well as precise frequency measurement of calibration of your radio, as well as precise frequency measurement of
on-the-air signals. The calibration procedure works by automatically on-the-air signals. The calibration procedure works by automatically
cycling your CAT-controlled radio through a series of preset cycling your CAT-controlled radio through a series of preset
frequencies of carrier-based signals at reliably known frequencies, frequencies of carrier-based signals at reliably known frequencies,
measuring the error in dial frequency for each signal. measuring the error in dial frequency for each signal.
You will probably find it convenient to define and use a special You will probably find it convenient to define and use a special
<<CONFIG-MENU,Configuration>> dedicated to frequency calibration. <<CONFIG-MENU,Configuration>> dedicated to frequency calibration.
Then complete the following steps, as appropriate for your system. Then complete the following steps, as appropriate for your system.
- Switch to FreqCal mode - Switch to FreqCal mode
- In the _Working Frequencies_ box on the *Settings -> Frequencies* - In the _Working Frequencies_ box on the *Settings -> Frequencies*
tab, delete any default frequencies for *FreqCal* mode that are not tab, delete any default frequencies for *FreqCal* mode that are not
relevant for your location. You may want to replace some of them with relevant for your location. You may want to replace some of them with
reliably known frequencies receivable at your location. reliably known frequencies receivable at your location.
TIP: We find major-city AM broadcast stations generally serve well as TIP: We find major-city AM broadcast stations generally serve well as
frequency calibrators at the low frequency end of the spectrum. In frequency calibrators at the low frequency end of the spectrum. In
North America we also use the standard time-and-frequency broadcasts 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 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 3.330, 7.850, and 14.670 MHz. Similar shortwave signals are available
in other parts of the world. in other parts of the world.
- In most cases you will want to start by deleting any existing file - In most cases you will want to start by deleting any existing file
`fmt.all` in the directory where your log files are kept. `fmt.all` in the directory where your log files are kept.
- Enter `0.0` for both *Slope* and *Intercept* under _Frequency - To cycle automatically through your chosen list of calibration
Calibration_ on the *Settings -> Frequencies* tab. frequencies, check *Execute frequency calibration cycle* on the
*Tools* menu. _WSJT-X_ will spend 30 seconds at each
- To cycle automatically through your chosen list of calibration frequency. Initially no measurement data is saved to the `fmt.all`
frequencies, check *Execute frequency calibration cycle* on the file although it is displayed on screen, this allows you to check you
*Tools* menu. _WSJT-X_ will spend 30 seconds at each frequency, current calibration parameters.
writing its measurements to file `fmt.all` in the log directory.
- During the calibration procedure, the radio's USB dial frequency is
- During the calibration procedure, the radio's USB dial frequency is offset 1500 Hz below each *FreqCal* entry in the default frequencies
offset 1500 Hz below each *FreqCal* entry in the default frequencies list. As shown in the screen shot below, detected signal carriers
list. As shown in the screen shot below, detected signal carriers therefore appear at about 1500 Hz in the _WSJT-X_ waterfall.
therefore appear at about 1500 Hz in the _WSJT-X_ waterfall.
- To start a measurement session check the *Measure* option and let
image::FreqCal.png[align="left",alt="FreqCal"] the calibration cycle run for at least one complete sequence. Note
that, while measuring, any existing calibration parameters are
With modern synthesized radios, small measured offsets from 1500 Hz automatically disabled so you may have to increase the *FTol* range if
will exhibit a straight-line dependence on frequency. You can your rig is off freqeuncy by more than a few Hertz in order to capture
approximate the calibration of your radio by simply dividing the valid measurements.
measured frequency offset (in Hz) at the highest reliable frequency by
the nominal frequency itself (in MHz). For example, the 20 MHz image::FreqCal.png[align="left",alt="FreqCal"]
measurement for WWV shown above produced a measured tone offset of
24.6 Hz, displayed in the _WSJT-X_ decoded text window. The resulting With modern synthesized radios, small measured offsets from 1500 Hz
calibration constant is 24.6/20=1.23 parts per million. This number will exhibit a straight-line dependence on frequency. You can
may be entered as *Slope* on the *settings -> Frequencies* tab. approximate the calibration of your radio by simply dividing the
measured frequency offset (in Hz) at the highest reliable frequency by
A more precise calibration can be effected by fitting the intercept the nominal frequency itself (in MHz). For example, the 20 MHz
and slope of a straight line to the whole sequence of calibration measurement for WWV shown above produced a measured tone offset of
measurements, as shown for these measurements in the graph plotted 24.6 Hz, displayed in the _WSJT-X_ decoded text window. The resulting
below. Software tools for completing this task are included with the calibration constant is 24.6/20=1.23 parts per million. This number
_WSJT-X_ installation, and detailed instructions for their use are may be entered as *Slope* on the *settings -> Frequencies* tab.
available at https://physics.princeton.edu/pulsar/k1jt/FMT_User.pdf.
A more precise calibration can be effected by fitting the intercept
Using these tools and no specialized hardware beyond your and slope of a straight line to the whole sequence of calibration
CAT-interfaced radio, you can calibrate the radio to better than 1 Hz measurements, as shown for these measurements in the graph plotted
and compete very effectively in the ARRL's periodic Frequency below. Software tools for completing this task are included with the
Measuring Tests. _WSJT-X_ installation, and detailed instructions for their use are
available at https://physics.princeton.edu/pulsar/k1jt/FMT_User.pdf.
image::FreqCal_Graph.png[align="left",alt="FreqCal_Graph"]
Using these tools and no specialized hardware beyond your
After running *Execute frequency calibration cycle* at least once with CAT-interfaced radio, you can calibrate the radio to better than 1 Hz
good results, check and edit the file `fmt.all` in the log directory and compete very effectively in the ARRL's periodic Frequency
and delete any spurious or outlier measurements. The line-fitting Measuring Tests.
procedure can then be carried out automatically by clicking *Solve for
calibration parameters* on the *Tools* menu. The results will be image::FreqCal_Graph.png[align="left",alt="FreqCal_Graph"]
displayed as in the following screen shot. Estimated uncertainties
are included for slope and intercept; `N` is the number of averaged After running *Execute frequency calibration cycle* at least once with
frequency measurements included in the fit, and `StdDev` is the root good results, check and edit the file `fmt.all` in the log directory
mean square deviation of averaged measurements from the fitted and delete any spurious or outlier measurements. The line-fitting
straight line. procedure can then be carried out automatically by clicking *Solve for
calibration parameters* on the *Tools* menu. The results will be
image::FreqCal_Results.png[align="center",alt="FreqCal_Results"] displayed as in the following screen shot. Estimated uncertainties
are included for slope and intercept; `N` is the number of averaged
=== Reference Spectrum frequency measurements included in the fit, and `StdDev` is the root
mean square deviation of averaged measurements from the fitted
_WSJT-X_ provides a tool that can be used to determine the detailed straight line. If the solution seems valid you will be offered an
shape of your receiver's passband. Disconnect your antenna or tune to *Apply* button to push that will automatically set the calibration
a quiet frequency with no signals. With WSJT-X running in one of the parameters in *Settings -> Frequencies -> Frequency Calibration*.
slow modes, select *Measure reference spectrum* from the *Tools* menu.
Wait for about a minute and then hit the *Stop* button. A file named image::FreqCal_Results.png[align="center",alt="FreqCal_Results"]
`refspec.dat` will appear in your log directory.
For a quick visual check of the resulting calibration, stay in
[ ... more to come ... ] *FreqCal* mode with the *Measure* option cleared. _WSJT-X_ will show
the adjusted results directly on the waterfall and the displayed
=== Phase Equalization records.
*Measure phase response* under the *Tools* menu is for advanced MSK144 === Reference Spectrum
users. Phase equalization is used to compensate for group-delay
variation across your receiver passband. Careful application of this _WSJT-X_ provides a tool that can be used to determine the detailed
facility can reduce intersymbol interference, resulting in improved shape of your receiver's passband. Disconnect your antenna or tune to
decoding sensitivity. If you use a software-defined receiver with a quiet frequency with no signals. With _WSJT-X_ running in one of
linear-phase filters there is no need to apply phase equalization. the slow modes, select *Measure reference spectrum* from the *Tools*
menu. Wait for about a minute and then hit the *Stop* button. A file
After a frame of received data has been decoded, *Measure phase named `refspec.dat` will appear in your log directory.
response* generates an undistorted audio waveform equal to the one
generated by the transmitting station. Its Fourier transform is then [ ... more to come ... ]
used as a frequency-dependent phase reference to compare with the
phase of the received frame's Fourier coefficients. Phase differences === Phase Equalization
between the reference spectrum and received spectrum will include
contributions from the originating station's transmit filter, the *Measure phase response* under the *Tools* menu is for advanced MSK144
propagation channel, and filters in the receiver. If the received users. Phase equalization is used to compensate for group-delay
frame originates from a station known to transmit signals having variation across your receiver passband. Careful application of this
little phase distortion (say, a station known to use a properly facility can reduce intersymbol interference, resulting in improved
adjusted software-defined-transceiver) and if the received signal is decoding sensitivity. If you use a software-defined receiver with
relatively free from multipath distortion so that the channel phase is linear-phase filters there is no need to apply phase equalization.
close to linear, the measured phase differences will be representative
of the local receiver's phase response. After a frame of received data has been decoded, *Measure phase
response* generates an undistorted audio waveform equal to the one
Complete the following steps to generate a phase equalization curve: generated by the transmitting station. Its Fourier transform is then
used as a frequency-dependent phase reference to compare with the
- Record a number of wav files that contain decodable signals from phase of the received frame's Fourier coefficients. Phase differences
your chosen reference station. Best results will be obtained when the between the reference spectrum and received spectrum will include
signal-to-noise ratio of the reference signals is 10 dB or greater. contributions from the originating station's transmit filter, the
propagation channel, and filters in the receiver. If the received
- Enter the callsign of the reference station in the DX Call box. frame originates from a station known to transmit signals having
little phase distortion (say, a station known to use a properly
- Select *Measure phase response* from the *Tools* menu, and open each adjusted software-defined-transceiver) and if the received signal is
of the wav files in turn. The mode character on decoded text lines relatively free from multipath distortion so that the channel phase is
will change from `&` to `^` while _WSJT-X_ is measuring the phase close to linear, the measured phase differences will be representative
response, and it will change back to `&` after the measurement is of the local receiver's phase response.
completed. The program needs to average a number of high-SNR frames to
accurately estimate the phase, so it may be necessary to process Complete the following steps to generate a phase equalization curve:
several wav files. The measurement can be aborted at any time by
selecting *Measure phase response* again to toggle the phase - Record a number of wav files that contain decodable signals from
measurement off. 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.
When the measurement is complete _WSJT-X_ will save the measured
phase response in the *Log directory*, in a file with suffix - Select *Measure phase response* from the *Tools* menu, and open each
".pcoeff". The filename will contain the callsign of the reference of the wav files in turn. The mode character on decoded text lines
station and a timestamp, for example `K0TPP_170923_112027.pcoeff`. will change from `&` to `^` while _WSJT-X_ is measuring the phase
response, and it will change back to `&` after the measurement is
- Select *Equalization tools ...* under the *Tools* menu and click the completed. The program needs to average a number of high-SNR frames to
*Phase ...* button to view the contents of the *Log directory*. Select accurately estimate the phase, so it may be necessary to process
the desired pcoeff file. The measured phase values will be plotted as several wav files. The measurement can be aborted at any time by
filled circles along with a fitted red curve labeled "Proposed". This is selecting *Measure phase response* again to toggle the phase
the proposed phase equalization curve. It's a good idea to repeat the measurement off.
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 When the measurement is complete _WSJT-X_ will save the measured
to save the proposed response. The red curve will be replaced with a phase response in the *Log directory*, in a file with suffix
light green curve labeled "Current" to indicate that the phase ".pcoeff". The filename will contain the callsign of the reference
equalization curve is now being applied to the received data. Another station and a timestamp, for example `K0TPP_170923_112027.pcoeff`.
curve labeled "Group Delay" will appear. The "Group Delay" curve shows
the group delay variation across the passband, in ms. Click the - Select *Equalization tools ...* under the *Tools* menu and click the
*Discard* button to remove the captured data, leaving only the applied *Phase ...* button to view the contents of the *Log directory*. Select
phase equalization curve and corresponding group delay curve. the desired pcoeff file. The measured phase values will be plotted as
filled circles along with a fitted red curve labeled "Proposed". This is
- To revert to no phase equalization, push the *Restore Defaults* the proposed phase equalization curve. It's a good idea to repeat the
button followed by the *Apply* button. phase measurement several times, using different wav files for each
measurement, to ensure that your measurements are repeatable.
The three numbers printed at the end of each MSK144 decode line can be
used to assess the improvement provided by equalization. These numbers - Once you are satisfied with a fitted curve, push the *Apply* button
are: `N` = Number of frames averaged, `H` = Number of hard bit errors to save the proposed response. The red curve will be replaced with a
corrected, `E` = Size of MSK eye diagram opening. light green curve labeled "Current" to indicate that the phase
equalization curve is now being applied to the received data. Another
Here is a decode of K0TPP obtained while *Measure phase response* was measuring curve labeled "Group Delay" will appear. The "Group Delay" curve shows
the phase response: the group delay variation across the passband, in ms. Click the
*Discard* button to remove the captured data, leaving only the applied
103900 17 6.5 1493 ^ WA8CLT K0TPP +07 1 0 1.2 phase equalization curve and corresponding group delay curve.
The "^" symbol indicates that a phase measurement is being accumulated - To revert to no phase equalization, push the *Restore Defaults*
but is not yet finished. The three numbers at the end of the line button followed by the *Apply* button.
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 The three numbers printed at the end of each MSK144 decode line can be
scale. Here's how the same decode looks after phase equalization: used to assess the improvement provided by equalization. These numbers
are: `N` = Number of frames averaged, `H` = Number of hard bit errors
103900 17 6.5 1493 & WA8CLT K0TPP +07 1 0 1.6 corrected, `E` = Size of MSK eye diagram opening.
In this case, equalization has increased the eye opening from 1.2 to Here is a decode of K0TPP obtained while *Measure phase response* was measuring
1.6. Larger positive eye openings are associated with reduced the phase response:
likelihood of bit errors and higher likelihood that a frame will be
successfully decoded. In this case, the larger eye-opening tells us 103900 17 6.5 1493 ^ WA8CLT K0TPP +07 1 0 1.2
that phase equalization was successful, but it is important to note
that this test does not by itself tell us whether the applied phase The "^" symbol indicates that a phase measurement is being accumulated
equalization curve is going to improve decoding of signals other than but is not yet finished. The three numbers at the end of the line
those from the reference station, K0TPP. 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
It's a good idea to carry out before and after comparisons using a scale. Here's how the same decode looks after phase equalization:
large number of saved wav files with signals from many different
stations, to help decide whether your equalization curve improves 103900 17 6.5 1493 & WA8CLT K0TPP +07 1 0 1.6
decoding for most signals. When doing such comparisons, keep in mind
that equalization may cause _WSJT-X_ to successfully decode a frame In this case, equalization has increased the eye opening from 1.2 to
that was not decoded before equalization was applied. For this 1.6. Larger positive eye openings are associated with reduced
reason, be sure that the time "T" of the two decodes are the same likelihood of bit errors and higher likelihood that a frame will be
before comparing their end-of-line quality numbers. successfully decoded. In this case, the larger eye-opening tells us
that phase equalization was successful, but it is important to note
When comparing before and after decodes having the same "T", keep in that this test does not by itself tell us whether the applied phase
mind that a smaller first number means that decoding has improved, equalization curve is going to improve decoding of signals other than
even if the second and third numbers appear to be "worse". For those from the reference station, K0TPP.
example, suppose that the end-of-line quality numbers before
equalization are `2 0 0.2` and after equalization `1 5 -0.5`. These It's a good idea to carry out before and after comparisons using a
numbers show improved decoding because the decode was obtained using large number of saved wav files with signals from many different
only a single frame after equalization whereas a 2-frame average was stations, to help decide whether your equalization curve improves
needed before equalization. This implies that shorter and/or weaker decoding for most signals. When doing such comparisons, keep in mind
pings could be decodable. that equalization may cause _WSJT-X_ to successfully decode a frame
that was not decoded before equalization was applied. For this
NOTE: Further details on phase equalization and examples of fitted reason, be sure that the time "T" of the two decodes are the same
phase curves and eye diagrams can be found in the article on MSK144 by before comparing their end-of-line quality numbers.
K9AN and K1JT published in {msk144}.
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}.

2
doc/user_guide/en/settings-audio.adoc
View File

@ -1,6 +1,6 @@
// Status=review // Status=review
image::settings-audio.png[align="center",alt="WSJT-X Audio Configuration Screen"] image::settings-audio.png[align="center",alt="_WSJT-X_ Audio Configuration Screen"]
Select the *Audio* tab to configure your sound system. Select the *Audio* tab to configure your sound system.

2
doc/user_guide/en/wsjtx-main.adoc
View File

@ -1,5 +1,5 @@
// This is a comment line, anything with // is ignored at process time. // This is a comment line, anything with // is ignored at process time.
= WSJT-X User Guide = _WSJT-X_ User Guide
Joseph H Taylor, Jr, K1JT Joseph H Taylor, Jr, K1JT
:revnumber: {VERSION} :revnumber: {VERSION}
// For web-pages, adding :badges: is ok, but is a security issue for // For web-pages, adding :badges: is ok, but is a security issue for