w4kek
/
WSJT-X
mirror of https://github.com/saitohirga/WSJT-X.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

User Guide edits from Dave, KC3GPM.

This commit is contained in:
Joe Taylor 2020-08-10 09:31:44 -04:00 committed by Bill Somerville
parent 6838a6b484
commit ade1eb861d
No known key found for this signature in database
GPG Key ID: D864B06D1E81618F
8 changed files with 84 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/user_guide/en/install-from-source.adoc
View File

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

18
doc/user_guide/en/install-linux.adoc
View File

@ -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:

8
doc/user_guide/en/install-mac.adoc
View File

@ -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:

10
doc/user_guide/en/introduction.adoc
View File

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

24
doc/user_guide/en/logging.adoc
View File

@ -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 <<INSTALL,Installation>> and <<PLATFORM,Platform
Dependencies>> 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
<<COLORS,Decode Highlighting>>.
Additional features are provided for *Contest* and *Fox* logging.
(more to come, here ...)

8
doc/user_guide/en/make-qso.adoc
View File

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

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

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

21
doc/user_guide/en/protocols.adoc
View File

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