From 29423748c935fb4c1b55aa677912d6a3478ab994 Mon Sep 17 00:00:00 2001 From: Bill Somerville Date: Fri, 13 Oct 2017 22:34:48 +0000 Subject: [PATCH] User guide updates for frequency calibration mode 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 --- .../en/controls-functions-menus.adoc | 2 +- doc/user_guide/en/decoder_notes.adoc | 2 +- doc/user_guide/en/faq.adoc | 5 +- doc/user_guide/en/measurement_tools.adoc | 439 +++++++++--------- doc/user_guide/en/settings-audio.adoc | 2 +- doc/user_guide/en/wsjtx-main.adoc | 2 +- 6 files changed, 234 insertions(+), 218 deletions(-) diff --git a/doc/user_guide/en/controls-functions-menus.adoc b/doc/user_guide/en/controls-functions-menus.adoc index 50e8e43a2..6c2a3b26f 100644 --- a/doc/user_guide/en/controls-functions-menus.adoc +++ b/doc/user_guide/en/controls-functions-menus.adoc @@ -5,7 +5,7 @@ and operation. Most of the items are self-explanatory; a few additional details are provided below. Keyboard shortcuts for some 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"] This menu appears on the Macintosh only. *Settings* appears here, diff --git a/doc/user_guide/en/decoder_notes.adoc b/doc/user_guide/en/decoder_notes.adoc index 1fc20933a..83e8a8b05 100644 --- a/doc/user_guide/en/decoder_notes.adoc +++ b/doc/user_guide/en/decoder_notes.adoc @@ -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 -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. [[AP_DECODING_TYPES_TABLE]] diff --git a/doc/user_guide/en/faq.adoc b/doc/user_guide/en/faq.adoc index 64568daac..ea10a5022 100644 --- a/doc/user_guide/en/faq.adoc +++ b/doc/user_guide/en/faq.adoc @@ -69,6 +69,9 @@ command-prompt window: 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 diff --git a/doc/user_guide/en/measurement_tools.adoc b/doc/user_guide/en/measurement_tools.adoc index 07bb3113e..9007c5046 100644 --- a/doc/user_guide/en/measurement_tools.adoc +++ b/doc/user_guide/en/measurement_tools.adoc @@ -1,213 +1,226 @@ -=== 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 -<> 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. - -- Enter `0.0` for both *Slope* and *Intercept* under _Frequency -Calibration_ on the *Settings -> Frequencies* tab. - -- 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, -writing its measurements to file `fmt.all` in the log directory. - -- 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. - -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. - -image::FreqCal_Results.png[align="center",alt="FreqCal_Results"] - -=== 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. - - [ ... more to come ... ] - -=== 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* 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 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}. +=== 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 +<> 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 you +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 freqeuncy 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. + + [ ... more to come ... ] + +=== 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* 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 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}. diff --git a/doc/user_guide/en/settings-audio.adoc b/doc/user_guide/en/settings-audio.adoc index 00a6e19ef..478416836 100644 --- a/doc/user_guide/en/settings-audio.adoc +++ b/doc/user_guide/en/settings-audio.adoc @@ -1,6 +1,6 @@ // 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. diff --git a/doc/user_guide/en/wsjtx-main.adoc b/doc/user_guide/en/wsjtx-main.adoc index b19612261..71f0e3c4a 100644 --- a/doc/user_guide/en/wsjtx-main.adoc +++ b/doc/user_guide/en/wsjtx-main.adoc @@ -1,5 +1,5 @@ // 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 :revnumber: {VERSION} // For web-pages, adding :badges: is ok, but is a security issue for