From ade1eb861d4322419a134f79c0d8800d5d166628 Mon Sep 17 00:00:00 2001 From: Joe Taylor Date: Mon, 10 Aug 2020 09:31:44 -0400 Subject: [PATCH] User Guide edits from Dave, KC3GPM. --- doc/user_guide/en/install-from-source.adoc | 6 +- doc/user_guide/en/install-linux.adoc | 18 +++--- doc/user_guide/en/install-mac.adoc | 8 +-- doc/user_guide/en/introduction.adoc | 10 ++-- doc/user_guide/en/logging.adoc | 24 ++++---- doc/user_guide/en/make-qso.adoc | 8 +-- doc/user_guide/en/measurement_tools.adoc | 66 +++++++++++----------- doc/user_guide/en/protocols.adoc | 21 ++++--- 8 files changed, 84 insertions(+), 77 deletions(-) diff --git a/doc/user_guide/en/install-from-source.adoc b/doc/user_guide/en/install-from-source.adoc index f106aa59b..b70e89c55 100644 --- a/doc/user_guide/en/install-from-source.adoc +++ b/doc/user_guide/en/install-from-source.adoc @@ -1,7 +1,7 @@ -// Status=review +// Status=edited Source code for _WSJT-X_ is available from a public repository at -{devrepo}. To compile the program you will need to install at least the +{devrepo}. To compile the program, at a minimum you must install the following packages: - Git @@ -19,7 +19,7 @@ cd wsjtx git checkout wsjtx-{VERSION} ===== -and for the current development branch, +and for the current development branch: ===== git clone git://git.code.sf.net/p/wsjt/wsjtx diff --git a/doc/user_guide/en/install-linux.adoc b/doc/user_guide/en/install-linux.adoc index ad905f32d..6461ac77e 100644 --- a/doc/user_guide/en/install-linux.adoc +++ b/doc/user_guide/en/install-linux.adoc @@ -1,16 +1,14 @@ -// Status=review +// Status=edited Debian, Ubuntu, and other Debian-based systems including Raspbian: -NOTE: The project team release binary installer packages for Linux -when a new _WSJT-X_ release is announced. These are built to -target one contemporary version of a Linux distribution. Although -these may work on newer Linux versions or even different -distributions, it is unlikely that they will work on older -versions. Check the notes provided with the release for details of the -targeted Linux distributions and versions. If the binary package is -not compatible with your Linux distribution or version you must build -the application from sources. +NOTE: The project team release binary installer packages targeted for +one contemporary version of a Linux distribution. Although these may +work on newer Linux versions or even different distributions, it is +unlikely that they work on older versions. Check the notes provided +with the release for details of the targeted Linux distributions and +versions. If the binary package is not compatible with your Linux +distribution or version, you must build the application from sources. * 32-bit: {debian32} - To install: diff --git a/doc/user_guide/en/install-mac.adoc b/doc/user_guide/en/install-mac.adoc index 26384805f..6595ba1c9 100644 --- a/doc/user_guide/en/install-mac.adoc +++ b/doc/user_guide/en/install-mac.adoc @@ -1,12 +1,12 @@ // These instructions are up-to-date for WSJT-X v2.2 -*OS X 10.12* and later: Download the file {osx} to your desktop, -double-click on it and consult its `ReadMe` file for important +*macOS10.13* and later: Download the file {osx} to your desktop, +double-click it and consult its `ReadMe` file for important installation notes. If you have already installed a previous version, you can retain it by -changing its name in the *Applications* folder (say, from _WSJT-X_ to -_WSJT-X_2.1_). You can then proceed to the installation phase. +changing its name in the *Applications* folder (such as from _WSJT-X_ to +_WSJT-X_2.2_). You can then proceed to the installation phase. Take note also of the following: diff --git a/doc/user_guide/en/introduction.adoc b/doc/user_guide/en/introduction.adoc index a592e5325..f172b5d35 100644 --- a/doc/user_guide/en/introduction.adoc +++ b/doc/user_guide/en/introduction.adoc @@ -4,7 +4,7 @@ _WSJT-X_ is a computer program designed to facilitate basic amateur radio communication using very weak signals. The first four letters in the program name stand for "`**W**eak **S**ignal communication by K1**JT**,`" while the suffix "`-X`" indicates that _WSJT-X_ started as -an e**Xt**ended and e**X**perimental branch of the program _WSJT_, +an extended and experimental branch of the program _WSJT_, first released in 2001. Bill Somerville, G4WJS, and Steve Franke, K9AN, have been major contributors to program development since 2013 and 2015, respectively. @@ -16,7 +16,7 @@ making reliable QSOs under weak-signal conditions. They use nearly identical message structure and source encoding. JT65 and QRA64 were designed for EME ("`moonbounce`") on the VHF/UHF bands and have also proven very effective for worldwide QRP communication on the HF bands. -QRA64 has a some advantages over JT65, including better performance +QRA64 has some advantages over JT65, including better performance for EME on the higher microwave bands. JT9 was originally designed for the LF, MF, and lower HF bands. Its submode JT9A is 2 dB more sensitive than JT65 while using less than 10% of the bandwidth. JT4 @@ -27,7 +27,7 @@ reception, so a minimal QSO takes four to six minutes — two or three transmissions by each station, one sending in odd UTC minutes and the other even. FT8 is operationally similar but four times faster (15-second T/R sequences) and less sensitive by a few dB. FT4 is -faster still (7.5 s T/R sequences) and especially well suited for +faster still (7.5 s T/R sequences) and especially well-suited for radio contesting. On the HF bands, world-wide QSOs are possible with any of these modes using power levels of a few watts (or even milliwatts) and compromise antennas. On VHF bands and higher, QSOs @@ -45,7 +45,7 @@ protocols designed to take advantage of brief signal enhancements from ionized meteor trails, aircraft scatter, and other types of scatter propagation. These modes use timed sequences of 5, 10, 15, or 30 s duration. User messages are transmitted repeatedly at high rate (up -to 250 characters per second, for MSK144) to make good use of the +to 250 characters per second for MSK144) to make good use of the shortest meteor-trail reflections or "`pings`". ISCAT uses free-form messages up to 28 characters long, while MSK144 uses the same structured messages as the slow modes and optionally an abbreviated @@ -80,4 +80,4 @@ be beta releases leading up to the final release of v2.1.0. Release candidates should be used _only_ during a short testing period. They carry an implied obligation to provide feedback to the program development group. Candidate releases should not be used on -the air after a full release with the same number has been made. +the air after a full release with the same number is made. diff --git a/doc/user_guide/en/logging.adoc b/doc/user_guide/en/logging.adoc index 4176a2a40..a3193ba25 100644 --- a/doc/user_guide/en/logging.adoc +++ b/doc/user_guide/en/logging.adoc @@ -1,7 +1,9 @@ +//status: edited + A basic logging facility in _WSJT-X_ saves QSO information to files named `wsjtx.log` (in comma-separated text format) and `wsjtx_log.adi` (in standard ADIF format). These files can be imported directly into -other programs, for example spreadsheets and popular logging programs. +other programs (such as spreadsheets and popular logging programs). As described in the <> and <> sections, different operating systems may place your local log files in different locations. You can always navigate to @@ -12,30 +14,32 @@ applications like {jtalert}, which can log QSOs automatically to other applications including {hrd}, {dxlsuite}, and {log4om}. The program option *Show DXCC entity and worked before status* -(selectable on the *Settings | General* tab) is intended mostly for +(selectable on the *File | Settings | General* tab) is intended mostly for use on non-Windows platforms, where {jtalert} is not available. When -this option is checked _WSJT-X_ appends some additional information to +this option is checked, _WSJT-X_ appends some additional information to all CQ messages displayed in the _Band Activity_ window. The name of the DXCC entity is shown, abbreviated if necessary. Your "`worked before`" status for this callsign (according to log file `wsjtx_log.adi`) is indicated by highlighting colors, if that option -has been selected. +is selected. _WSJT-X_ includes a built-in `cty.dat` file containing DXCC prefix information. Updated files can be downloaded from the {cty_dat} web -site when required. If an updated `cty.dat` is present in the logs -folder and readable, it will be used in preference to the built-in -one. +site when required. If an updated and readable `cty.dat` file is +present in the logs folder, it is used in preference to the +built-in file. The log file `wsjtx_log.adi` is updated whenever you log a QSO from -_WSJT-X_. (Keep in mind that if you erase this file you will lose all +_WSJT-X_. (Keep in mind that if you erase this file, you lose all "`worked before`" information.) You can append or overwrite the `wsjtx_log.adi` file by exporting your QSO history as an ADIF file from another logging program. Turning *Show DXCC entity and worked -before status* off and then on again will cause _WSJT-X_ to re-read +before status* off and then on again causes _WSJT-X_ to re-read the log file. Very large log files may cause _WSJT-X_ to slow down -when searching for calls. If the ADIF log file has been changed +when searching for calls. If the ADIF log file has been changed outside of _WSJT-X_ you can force _WSJT-X_ to reload the file from the *Settings | Colors* tab using the *Rescan ADIF Log* button, see <>. +Additional features are provided for *Contest* and *Fox* logging. +(more to come, here ...) diff --git a/doc/user_guide/en/make-qso.adoc b/doc/user_guide/en/make-qso.adoc index 03f02fd46..725bafe73 100644 --- a/doc/user_guide/en/make-qso.adoc +++ b/doc/user_guide/en/make-qso.adoc @@ -37,7 +37,7 @@ assigns more reliable numbers to relatively strong signals. NOTE: Signals become visible on the waterfall around S/N = –26 dB and audible (to someone with very good hearing) around –15 dB. Thresholds for decodability are around -20 dB for FT8, -23 dB for JT4, –25 dB for -JT65, –27 dB for JT9. +JT65, and –27 dB for JT9. NOTE: Several options are available for circumstances where fast QSOs are desirable. Double-click the *Tx1* control under _Now_ or _Next_ @@ -75,7 +75,7 @@ When calling CQ you may also choose to check the box *Call 1st*. _WSJT-X_ will then respond automatically to the first decoded responder to your CQ. -NOTE: When *Auto-Seq* is enabled the program de-activates *Enable Tx* +NOTE: When *Auto-Seq* is enabled, the program de-activates *Enable Tx* at the end of each QSO. It is not intended that _WSJT-X_ should make fully automated QSOs. @@ -259,7 +259,7 @@ that a second callsign is never permissible in these messages. NOTE: During a transmission your outgoing message is displayed in the first label on the *Status Bar* and shown exactly as another station -will receive it. You can check to see that you are actually +receives it. You can check to see that you are actually transmitting the message you wish to send. QSOs involving *Type 2* compound callsigns might look like either @@ -287,7 +287,7 @@ standard structured messages without callsign prefix or suffix. TIP: If you are using a compound callsign, you may want to experiment with the option *Message generation for type 2 compound -callsign holders* on the *Settings | General* tab, so that messages +callsign holders* on the *File | Settings | General* tab, so that messages will be generated that best suit your needs. === Pre-QSO Checklist diff --git a/doc/user_guide/en/measurement_tools.adoc b/doc/user_guide/en/measurement_tools.adoc index 766939e7c..fe501d650 100644 --- a/doc/user_guide/en/measurement_tools.adoc +++ b/doc/user_guide/en/measurement_tools.adoc @@ -1,6 +1,8 @@ +//Status: edited + === Frequency Calibration -Many _WSJT-X_ capabilities depend on signal-detection bandwidths no +Many _WSJT-X_ capabilities depend on signal-detection bandwidths of 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 @@ -11,11 +13,11 @@ 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. +Then complete the following steps, as appropriate, for your system. - Switch to FreqCal mode -- In the _Working Frequencies_ box on the *Settings -> Frequencies* +- In the _Working Frequencies_ box on the *File | 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. @@ -29,14 +31,14 @@ 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. +- In most cases, 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 +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 @@ -61,7 +63,7 @@ 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. +may be entered as *Slope* on the *File | 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 @@ -81,19 +83,19 @@ 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 +calibration parameters* on the *Tools* menu. The results are 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*. +straight line. If the solution seems valid, you are offered an +*Apply* button to push that automatically sets the calibration +parameters in *File | 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 +*FreqCal* mode with the *Measure* option cleared. _WSJT-X_ shows the adjusted results directly on the waterfall and the displayed records. @@ -103,8 +105,8 @@ _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 +menu. Wait for about a minute and then click *Stop*. A file +named `refspec.dat` appears 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. @@ -122,39 +124,39 @@ 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 +between the reference spectrum and received spectrum 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 +little phase distortion (such as 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 +- Record a number of `wav` files that contain decodable signals from +your chosen reference station. Best results are 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 +of the `wav` files in turn. The mode character on decoded text lines +changes from `&` to `^` while _WSJT-X_ is measuring the phase +response, and it changes 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 +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 +When the measurement is complete, _WSJT-X_ saves the measured phase response in the *Log directory*, in a file with suffix -".pcoeff". The filename will contain the callsign of the reference +".pcoeff". The filename contains 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 @@ -165,23 +167,23 @@ 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 +- Once you are satisfied with a fitted curve, click the *Apply* button +to save the proposed response. The red curve is 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 +curve labeled "Group Delay" appears. 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* +- To revert to no phase equalization, click 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. +corrected, and `E` = Size of MSK eye diagram opening. Here is a decode of K0TPP obtained while *Measure phase response* was measuring the phase response: @@ -196,7 +198,7 @@ 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 +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 @@ -206,7 +208,7 @@ 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 +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 diff --git a/doc/user_guide/en/protocols.adoc b/doc/user_guide/en/protocols.adoc index d9a7d8ada..e22911266 100644 --- a/doc/user_guide/en/protocols.adoc +++ b/doc/user_guide/en/protocols.adoc @@ -1,3 +1,5 @@ +//status: edited + [[PROTOCOL_OVERVIEW]] === Overview @@ -30,17 +32,17 @@ of 4-digit Maidenhead grid locators on earth is 180×180 = 32,400, which is less than 2^15^ = 32,768; so a grid locator requires 15 bits. Some 6 million of the possible 28-bit values are not needed for -callsigns. A few of these slots have been assigned to special message +callsigns. A few of these slots are assigned to special message components such as `CQ`, `DE`, and `QRZ`. `CQ` may be followed by three digits to indicate a desired callback frequency. (If K1ABC transmits -on a standard calling frequency, say 50.280, and sends `CQ 290 K1ABC +on a standard calling frequency such as 50.280, and sends `CQ 290 K1ABC FN42`, it means that s/he will listen on 50.290 and respond there to any replies.) A numerical signal report of the form `–nn` or `R–nn` can be sent in place of a grid locator. (As originally defined, numerical signal reports `nn` were required to fall between -01 -and -30 dB. Program versions 2.3 and later accommodate reports between --50 and +50 dB.) A country prefix or portable suffix may be -attached to one of the callsigns. When this feature is used the +and -30 dB. Recent program versions 2.3 and later accommodate reports between +-50 and +49 dB.) A country prefix or portable suffix may be +attached to one of the callsigns. When this feature is used, the additional information is sent in place of the grid locator or by encoding additional information into some of the 6 million available slots mentioned above. @@ -147,7 +149,8 @@ following pseudo-random sequence: 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 +JT65A, and 2 and 4 times larger for JT65B and JT65C, respectively. +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 @@ -155,7 +158,7 @@ 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. += 2, 3, 4 used to convey the messages RO, RRR, and 73, respectively. [[QRA64_PROTOCOL]] ==== QRA64 @@ -225,7 +228,7 @@ the sync bit. [[SLOW_SUMMARY]] ==== Summary -Table 7 provides a brief summary parameters for the slow modes in +Table 7 provides a brief summary of parameters for the slow modes in _WSJT-X_. Parameters K and r specify the constraint length and rate of the convolutional codes; n and k specify the sizes of the (equivalent) block codes; Q is the alphabet size for the @@ -305,7 +308,7 @@ available character set is: Transmissions consist of sequences of 24 symbols: a synchronizing pattern of four symbols at tone numbers 0, 1, 3, and 2, followed by two symbols with tone number corresponding to (message length) and -(message length + 5), and finally 18 symbols conveying the user's +(message length + 5), and, finally, 18 symbols conveying the user's message, sent repeatedly character by character. The message always starts with `@`, the beginning-of-message symbol, which is not displayed to the user. The sync pattern and message-length indicator