w4kek/WSJT-X
1
0
Fork 0
mirror of https://github.com/saitohirga/WSJT-X.git synced 2024-11-25 13:48:42 -05:00
Code Issues Packages Projects Releases Wiki Activity

Another extensive round of edits for the WSJT-X User's Guide.

Browse Source 
git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@3657 ab8295b8-cf94-4d9e-aec4-7959e3be5d79
This commit is contained in:
Joe Taylor 2014-01-23 22:13:32 +00:00
parent fd4bc2d602
commit d3d0d437f6
18 changed files with 197 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/source/acknowledgements.txt
View File

@ -1,17 +1,19 @@
// Status=review
- Many users of WSJT, too numerous to mention here individually, have
Many users of WSJT, too numerous to mention here individually, have
contributed suggestions and advice that have greatly aided the
development of {wsjtx} and its sister programs. Since 2005 the
overall project (including WSJT, MAP65, WSPR, {wsjtx}, and WSPR-X) has
been “open source”, all code being licensed under the GNU Public
been “open source”, with all code licensed under the GNU Public
License (GPL).
- For {wsjtx} in particular, I wish to acknowledge contributions from:
*AC6SL, AE4JY, DJ0OT, G4KLA, G4WJS, K3WYC, KA6MAL, KA9Q, KK1D, PY2SDR,
VK3ACF, VK4BDJ, and W4TV*.
For {wsjtx} in particular, we acknowledge contributions from *AC6SL,
AE4JY, DJ0OT, G4KLA, G4WJS, K3WYC, KA6MAL, KA9Q, KI7MT, KK1D, PY2SDR,
VK3ACF, VK4BDJ, and W4TV*. Each of these amateurs has helped to bring
the program’s design, code, and documentation to its present
state.
- Each has helped to bring the program’s design, code, and
documentation to its present state. Most of the color palettes for the
{wsjtx} waterfall were shamelessly copied from the excellent, well
documented, open-source program fldigi, by W1HKJ and friends.
Most of the color palettes for the {wsjtx} waterfall were copied from
the excellent, well documented, open-source program _fldigi_, by *W1HKJ*
and friends.

39
doc/source/app-a-functional-procedures.txt
View File

@ -1,39 +0,0 @@
// Status=review
.Algorithms and Source Code
- For those wishing to study the program’s algorithms and source code,
perhaps with an eye toward future improvements, the blocks are labeled
here with the names of functional procedures in the code:
.Block Steps
[width="80%",cols="<2,60",options="header",valign="middle"]
|========
|Block/Step|Functional Procedure
|sync9:|Use sync symbols to find candidate JT9 signals in the specified frequency range. +
Then, at the frequency of each plausible candidate
|downsam9:|Mix, filter and down-sample to 16 complex samples/symbol
|peakdt9:|Using sync symbols, time-align to start of JT9 symbol sequence
|afc9:|Measure frequency offset and any possible drift
|twkfreq:|Remove frequency offset and drift
|symspec2:|Compute 8-bin spectra for 69 information-carrying symbols, using the +
time- and frequency-aligned data transform to yield 206 single-bit soft symbols
|interleave9:|Remove single-bit symbol interleaving imposed at the transmitter
|decode9:|Retrieve a 72-bit user message using the sequential ``Fano'' algorithm +
for convolutional codes
|unpackmsg:|Unpack a human-readable message from the 72-bit compressed format
|========
:shannonfano: http://en.wikipedia.org/wiki/Shannon%E2%80%93Fano_coding[ Fano Algorithm]
- With marginal or unrecognizable signals the sequential {shannonfano}
can take exponentially long times to completion.
- If the first step in the above sequence finds many seemingly worthy
candidate signals, and if many of them turn out to be undecodable, the
decoding loop could take a very long time.
- For this reason the decode9 step is programmed to “time out” and
report failure if it takes too long.
- The choice Fast | Normal | Deepest on the Decode menu provides a
three-step control of this timeout limit.

14
doc/source/app-a-jt9-mode-table.txt
View File

@ -1,14 +0,0 @@
// Status=review
.JT9-Modes
[width="80%",cols="<2,^2,^2,^2,^2,^2,^2",options="header",valign="middle"]
|========
|Submode|nsps|Symbol Duration (s)|Tone Spacing (Hz)|Signal Bandwidth (Hz)|S/N Threshold* (dB)|QSO Time (min)
|JT9-1|6912|0.58|1.736|15.6|-27|6
|JT9-2|15360|1.28|0.781|7.0|-30|12
|JT9-5|40960|3.41|0.293|2.6|-34|30
|JT9-10|82944|6.91|0.145|1.3|-37|60
|JT9-30|252000|21.00|0.048|0.4|-42|180
|========
NOTE: Noise power measured in 2500 Hz bandwidth.

28
doc/source/app-a-rcv-decode.txt
View File

@ -1,28 +0,0 @@
// Status=review
- {wsjtx} acquires 16-bit integer samples from the sound card at a
12000 Hz rate. Spectra from overlapping data segments are computed
for the waterfall display and saved at intervals of half the JT9
symbol length.
- As shown in screen shots earlier in this Guide, a *JT9* signal
appears in the Cumulative spectrum as a nearly rectangular shape about
16 Hz wide. Although there is no clearly visible “sync tone” like the
one in *JT65*, by convention the nominal frequency of a *JT9* signal
is nevertheless taken to be that of the lowest tone at the left edge
of the spectrum.
- At the end of a reception sequence, about 50 seconds into the UTC
minute, received data samples are forwarded to the decoder. For
operator convenience the decoder goes through its full procedure
twice:
* first over a narrow range around the selected Rx frequency
* Then in the full displayed frequency range (or in *JT9+JT65* mode, the
displayed range above the blue *JT65 nnnn JT9* marker).
- Decoding of clean *JT9* signals in a white-noise background starts
to fail around signal-to-noise ratio –25 dB and reached the 50% level
at -26 dB
- Each decoding pass can be described as a sequence of discrete blocks.

7
doc/source/app-a-transmitting.txt
View File

@ -1,7 +0,0 @@
// Status=review
- Immediately before the start of a transmission {wsjtx} encodes a
user’s message and computes the sequence of tones to be sent. The
transmitted audio waveform is computed on-the-fly, with 16-bit integer
samples at a 48000 Hz rate. The digital samples are converted to an
analog waveform in the sound card or equivalent USB interface.

44
doc/source/app-a.txt
View File

@ -1,44 +0,0 @@
// Status=review
//Needs work!
.The JT9 Protocol and its Implementation
- *JT9* is a mode designed for making QSOs at HF, MF, and LF. The
mode uses essentially the same 72-bit structured messages as *JT65*.
- Error control coding (ECC) uses a strong convolutional code with
constraint length K=32, rate r=1/2, and a zero tail. WIth 72-bit
user messages, this leads to an encoded message length of
(72+31) × 2 = 206 bits.
- Modulation is 9-FSK: 8 tone frequencies for data, and one for
synchronization. In a given transmission sixteen tone intervals
(those numbered 1, 2, 5, 10, 16, 23, 33, 35, 51, 52, 55, 60, 66, 73,
83, and 85 in the sequence) are devoted to synchronization. Thus, a
transmission requires a total of (206 / 3) + 16 = 85 (rounded up) tone
intervals.
- Symbol lengths are chosen so that nsps, the number of samples
per symbol (at 12000 samples per second) is a number with no prime
factor greater than 7. This choice makes for efficient FFTs. Tone
spacing of the 9-FSK modulation is:
-----
df = 1 / tsym = 12000 / nsps, equal to the keying rate
-----
- Symbol durations are approximately (TRperiod - 8) / 85, where
TRperiod is the T/R sequence length in seconds.
- The total occupied bandwidth is 9 × df. The generated signal has
continuous phase and constant amplitude, so there are no key
clicks. For experimental purposes, submodes of *JT9* were defined with
transmission lengths greater than one minute.
- Parameters of all submodes are summarized in the following table,
along with approximate decoding thresholds measured by simulation on
an additive white Gaussian noise (AWGN) channel. Numbers following
*``JT9-''* in the submode names specify the T/R sequence length in
minutes. When not otherwise specified in this Guide, *JT9* implies
submode *JT9-1*, the only submode implemented in current versions of
{wsjtx}.

35
doc/source/app-c.txt
View File

@ -1,35 +0,0 @@
// Status=review
.Rig Specific Configuration
- Some rigs work with DTR, RTS, Polling, CaT, PTT while others do
not. The number of possible combinations is virtually endless.
- The intent of this Appendix is to provide configuration information
for specific rigs model, e.g. Icom 756 Pro-III, Yaesu FT-1000MP,
Flex-5000, etc. in order to make Installation & Configuration
easier. This is a work-in-progress. Some rigs may never be covered,
but we should try to cover many as possible.
- The table below will link brands (Yaesu, Icom, Kenwood, etc) to
specific models within each brand. If a model is not available, please
consider drafting a configuration file (a simple text file), using the
template provided, and submit it to the development team for inclusion
to future documentation releases.
:yaesu: link:yaesu.html[Yaesu]
:rigtemplate: link:rigtemplate.html[Template]
NOTE: If your manufacturer is not listed, it means we do not have
configuration files for any of the models for that particular
manufacturer. Please consider using the Rig Template and submit to
the development team at: {devemail}
.Select Manufacturer
[align="center",valign="middle",halign="center"]
|========
|ADAT|AOR|Alinco|Drake|Electro Craft
|Kenwood|Icom|SoftRock|Ten-Tec|{YAESU}
|{rigtemplate}||||
|========

2
doc/source/configuration-station.txt
View File

@ -5,7 +5,7 @@ the following information:
- *Call Sign*: <Your Call Sign>
- *Grid*: <Your Maidenhead Locator>
- *PTT method*: choose from RTS, DTR, CAT, VOX, or None.
- *PTT port*: if you will use RTS or DTR, choose a serial port,
- *PTT port*: if you will use RTS or DTR, choose a serial port.
- *PSK Reporter*: check to enable sending reception reports to the
{pskreporter} mapping facility.
- *CW ID*: Check to send your callsign in CW after sending 73.

6
doc/source/install-from-source.txt
View File

@ -18,8 +18,6 @@ following packages:
The full source code for {wsjtx} can be downloaded with the command:
[source,bash]
-----
$ svn co svn://svn.berlios.de/wsjt/branches/wsjtx
-----
$ svn co svn://svn.berlios.de/wsjt/branches/wsjtx
// Need further compiling Instructions

2
doc/source/install-mac.txt
View File

@ -1,6 +1,6 @@
// Status=review
- Read installation instructions {osx-instructions}.
- Read the OS X installation instructions {osx-instructions}.
- Download the required installation package
* {osx-108}
* {osx-109}

15
doc/source/install-ubuntu.txt
View File

@ -6,17 +6,12 @@ available at {launchpadurl}
Archive (PPA) at the above link, execute the following instruction at
the command prompt:
[source,bash]
-----
$ sudo add-apt-repository ppa:jnogatch/wsjtx
-----
Accept the PPA Key, then:
$ sudo add-apt-repository ppa:jnogatch/wsjtx
[source,bash]
-----
$ sudo apt-get update
$ sudo apt-get install wsjtx
-----
- Accept the PPA Key, then:
$ sudo apt-get update
$ sudo apt-get install wsjtx
- Download the soft-decision Reed Solomon decoder {kvasd} and put it
in the same directory as the executable binaries wsjtx and

4
doc/source/app-b-installed-files.txt → doc/source/installed-files.txt
View File

@ -1,6 +1,8 @@
// Status=review
.Files Present After Installation
After installing {wsjtx} as described in <<X3, Installation>>, the
following files will be present in the installation directory:
.Files Present After Installation
[width="60%",cols="2,60",options="header",valign="middle"]
|========
|File Name|Description

60
doc/source/jt65-jt9-differences.txt
View File

@ -1,41 +1,37 @@
// Status=review
//This section needs work!
- *JT65* is a mature mode described in the literature some years
ago. Details of the *JT9* protocol are presented in <<X16,Appendix A>>
of this Guide.
- To users already familiar with *JT65*, the most striking difference
The JT65 protocol was described in a {jt65protocol} in 2005; details
of the JT9 protocol are presented in the next section of this Guide.
To users already familiar with JT65, the most striking difference
between the two modes is the much smaller occupied bandwidth of JT9:
15.6 Hz, compared with 177.6 Hz for *JT65A*. Transmissions in the two
15.6 Hz, compared with 177.6 Hz for JT65A. Transmissions in the two
modes are essentially the same length, and both modes use exactly 72
bits to carry message information. At the user level the two modes
support the same message structures.
support nearly identical message structures.
- *JT65* signal reports are constrained to the range –1 to –30 dB —
more than adequate for EME purposes, but not enough dynamic range for
ideal use at HF and below.
JT65 signal reports are constrained to the range –1 to –30 dB — more
than adequate for EME purposes, but not enough dynamic range for ideal
use at HF and below. S/N values displayed by the JT65 decoder are
clamped at an upper limit –1 dB, because that’s all the original
protocol can handle. Moreover, the S/N scale in present JT65 decoders
becomes increasingly nonlinear above –10 dB. By comparison, JT9
allows for signal reports in the range –50 to +49 dB. It manages this
by co-opting a small portion of ``message space'' that would otherwise
be used for grid locators within 1 degree of the south pole. The S/N
scale of the present JT9 decoder is reasonably linear (although it’s
not intended as a precision measurement tool). With clean signals and
a clean nose background, JT65 achieves nearly 100% probability of
correct decoding down to S/N = –22 dB and 50% at –24 dB. JT9 is about
2 dB better, achieving 50% decoding at about –26 dB. Both modes
produce extremely low false-decode rates.
- S/N values displayed by the *JT65* decoder are clamped at –1 dB,
because that’s all the original protocol can handle; the S/N scale in
present *JT65* decoders becomes increasingly nonlinear above –10 dB.
Early experience suggests that under most HF propagation conditions
the two modes have comparable reliability. The tone spacing of JT9 is
about two-thirds that of JT65, so in some disturbed ionospheric
conditions in the higher portion of the HF spectrum, JT65 may do
better. JT9 is an order of magnitude better in spectral efficiency.
On a busy HF band, we often find the 2-kHz-wide JT65 sub-band filled
wall-to-wall with signals. Ten times as many JT9 signals can fit
into the same frequency range, without overlap.
- By comparison, *JT9* allows for signal reports in the range –50 to
\+49 dB. It manages this by co-opting a small amount of message space
otherwise used for grid locator's within 1 degree of the south
pole. The S/N scale of the present *JT9* decoder is reasonably linear,
although it’s not intended as a precision measurement tool. With clean
signals in a clean nose background, *JT65* achieves nearly 100%
probability of correct decoding down to S/N = –22 dB and 50% at –24
dB. *JT9* is about 2 dB better, achieving 50% decoding at about –26
dB. Both modes produce extremely low false-decode rates.
- Early experience suggests that under most HF propagation conditions
the two modes have comparable reliability, with perhaps a slight edge
to *JT9*. The tone spacing of *JT9* is about two-thirds that of
*JT65*, so in some disturbed ionospheric conditions in the higher
portion of the HF spectrum, *JT65* may do better. *JT9* is an order of
magnitude better in spectral efficiency. On a busy HF band, we often
find the 2-kHz-wide *JT65* sub-band filled wall-to-wall with signals.
Ten times as many JT9 signals could fit into the same space, without
overlap.

96
doc/source/jt9-protocol.txt Normal file
View File

@ -0,0 +1,96 @@
// Status=review
//Needs work!
.JT9 Protocol and Implementation
JT9 is a mode designed for making minimal QSOs at LF, MF, and HF. It
uses 72-bit structured messages that are nearly identical (at the user
level) to those in JT65. Error control coding (ECC) uses a strong
convolutional code with constraint length K=32, rate r=1/2, and a zero
tail, leading to an encoded message length of (72+31) × 2 = 206
information-carrying bits. Modulation is 9-FSK: eight tones are used
for data, one for synchronization. Sixteen symbol intervals are
devoted to synchronization, so a transmission requires a total of 206
/ 3 + 16 = 85 (rounded up) channel symbols. The sync symbols are
those numbered 1, 2, 5, 10, 16, 23, 33, 35, 51, 52, 55, 60, 66, 73,
83, and 85 in the transmitted sequence.
Each symbol lasts for 6912 sample intervals at 12000 samples per
second, or about 0.576 s. Tone spacing of the 9-FSK modulation is
12000/6912 = 1.736 Hz, the inverse of the symbol duration. The total
occupied bandwidth is therefore 9 × 1.736 = 15.6 Hz. The generated
JT9 signal has continuous phase and constant amplitude. There are no
key clicks, and the transmitter's power amplifier need not be highly
linear.
.Transmitting
Immediately before the start of a transmission WSJT-X encodes a
user’s message and computes the sequence of tones to be sent. The
transmitted audio waveform is computed on-the-fly, using 16-bit
integer samples at a 48000 Hz rate. The digital samples are converted
to an analog waveform in the sound card (or equivalent D/A interface).
.Receiving and Decoding
WSJT-X acquires 16-bit integer samples from the sound card at a 48000
Hz rate, and immediately downsamples the data stream to 12000 Hz.
Spectra from overlapping data segments are computed for the waterfall
display and saved at intervals of 0.188 s, half the JT9 symbol length.
As shown in screen shots earlier in this guide, a JT9 signal appears
in the *Cumulative* spectrum as a nearly rectangular shape about 16 Hz
wide. Although there is no clearly visible “sync tone” like the one
at the low-frequency edge of a JT65 signal, by convention the nominal
frequency of a JT9 signal is taken to be that of the lowest tone, at
the left edge of the spectrum.
At the end of a reception sequence, about 50 seconds into the UTC
minute, received data samples are forwarded to the decoder. For
operator convenience the decoder goes through its full procedure
twice: first at the selected Rx frequency, and then in the full
displayed frequency range (or in JT9+JT65 mode, the displayed range
above the blue *JT65 nnnn JT9* marker). Decoding of clean JT9 signals
in a white-noise background starts to fail around signal-to-noise
ratio –25 dB and reaches 50% copy at -26 dB.
Each decoding pass can be described as a sequence of discrete blocks.
For those wishing to study the program’s algorithms and source code,
perhaps with an eye toward future improvements, the blocks are labeled
here with the names of functional procedures in the code.
sync9: Use sync symbols to find candidate JT9 signals
in the specified frequency range
Then, at the frequency of each plausible candidate:
downsam9: Mix, filter and downsample to 16 complex
samples/symbol
peakdt9: Using sync symbols, time-align to start of JT9 symbol
sequence
afc9: Measure frequency offset and any possible drift
twkfreq: Remove frequency offset and drift
symspec2: Compute 8-bin spectra for 69 information-carrying
symbols, using the time- and frequency-aligned data;
transform to yield 206 single-bit soft symbols
interleave9: Remove single-bit symbol interleaving imposed at the
transmitter
decode9: Retrieve a 72-bit user message using the sequential
Fano algorithm for convolutional codes
unpackmsg: Unpack a human-readable message from the 72-bit
compressed format
With marginal or unrecognizable signals the sequential Fano algorithm
can take exponentially long times. If the first step in the above
sequence finds many seemingly worthy candidate signals, and if many of
them turn out to be undecodable, the decoding loop could take a very
long time. For this reason the decode9 step is programmed to “time
out” and report failure if it takes too long. The choices *Fast |
Normal | Deepest* on the Decode menu provide a three-step adjustment
of this timeout limit.

33
doc/source/rig-configuration.txt Normal file
View File

@ -0,0 +1,33 @@
// Status=review
.Rig Specific Configuration
Some rigs work with DTR, RTS, Polling, CAT, and PTT while others do
not. The number of possible combinations is virtually endless. The
intent of this Appendix is to provide configuration information for
specific rig models, e.g. Icom 756 Pro-III, Kenwood TS-2000, Yaesu
FT-1000MP, Flex-5000, etc., in order to make installation and
configuration easier. This is a work-in-progress, and some rigs may
never be covered.
The table below will link manufacturer names (Icom, Kenwood, Yaesu,
etc.) to specific models within each brand. If a model is not
available, please consider drafting a configuration file (a simple
text file), using the template provided, and submit it to the
development team for inclusion in future documentation releases.
:yaesu: link:yaesu.html[Yaesu]
:rigtemplate: link:rigtemplate.html[Template]
NOTE: If your manufacturer is not listed, it means we do not have
configuration files for any of the models for that particular
manufacturer. Please consider using the Rig Template and submit to
the development team at: {devmail}
.Select Manufacturer
[align="center",valign="middle",halign="center"]
|========
|ADAT|AOR|Alinco|Drake|Electro Craft
|Kenwood|Icom|SoftRock|Ten-Tec|{YAESU}
|{rigtemplate}||||
|========

9
doc/source/app-b-runtime-files.txt → doc/source/runtime-files.txt
View File

@ -1,11 +1,10 @@
// Status=review
.After First Run
- You might be curious about additional files that appear in the WSJTX
installation directory after using the program for a while. These
include:
You might be curious about additional files that appear in the WSJTX
installation directory after using the program. These include the
following:
.Files Created After Running WSJT-X The First Time
.Files created when running WSJT-X
[width="60%",cols="2,60",options="header",valign="middle"]
|========
|File Name|Description

44
doc/source/wsjtx-main.txt
View File

@ -26,7 +26,7 @@
:osx-108: http://physics.princeton.edu/pulsar/K1JT/wsjtx_3nov13.tar.gz[ OS X 10.6, 10.7, and 10.8 ]
:osx-109: http://physics.princeton.edu/pulsar/K1JT/wsjtx_10.9_29nov13.tar.gz[OS X 10.9]
:pskreporter: http://pskreporter.info/pskmap.html[PSK Reporter]
:jt65protocol: http://physics.princeton.edu/pulsar/K1JT/JT65.pdf[QEX article]
// These [[X?]] numbers are HTML anchors, and can be used to
// navigate though the document easily: <<[X1],See Introduction]>> will
@ -159,49 +159,29 @@ include::controls-functions-kb-shortcuts.txt[]
=== Mouse Commands
include::controls-functions-special-mouse-cmds.txt[]
[[X9]]
[[X8]]
== JT65 & JT9 Differences
include::jt65-jt9-differences.txt[]
[[X9]]
== The JT9 Protocol
include::jt9-protocol.txt[]
[[XA10]]
== Appendix A
include::app-a.txt[]
// Note to Dev-Team, this list of files needs to be updated.
[[XA11]]
=== JT9 Mode Table
include::app-a-jt9-mode-table.txt[]
=== Installed Files
include::installed-files.txt[]
[[XA12]]
=== Transmitting
include::app-a-transmitting.txt[]
[[XA13]]
=== Receiving & Decoding
include::app-a-rcv-decode.txt[]
[[XA14]]
=== Functional Procedures
include::app-a-functional-procedures.txt[]
=== Runtime Files
include::runtime-files.txt[]
[[XB10]]
== Appendix B
.Installed Files
- After installing {wsjtx} as described in <<X3, Installation>>, the
following files will be present in the installation directory:
// Note to Dev-Team, this list of files needs to be updated.
[[XB11]]
=== Installed Files
include::app-b-installed-files.txt[]
[[XB12]]
=== Runtime Files
include::app-b-runtime-files.txt[]
[[XC10]]
== Appendix C
include::app-c.txt[]
include::rig-configuration.txt[]
[[XACK10]]
== Acknowledgments

2
wsjtx.iss
View File

@ -1,6 +1,6 @@
[Setup]
AppName=wsjtx
AppVerName=wsjtx Version 1.2.2 r3620
AppVerName=wsjtx Version 1.2.2 r3644
AppCopyright=Copyright (C) 2001-2014 by Joe Taylor, K1JT
DefaultDirName=c:\wsjtx1.2
DefaultGroupName=wsjtx1.2