WSJT-X/WSJT_Source_Code.txt

284 lines
12 KiB
Plaintext
Raw Normal View History

WSJT DEVELOPMENT OVERVIEW
-------------------------
1 Introduction
----------------------------------------------------------------------
WSJT is a computer program designed to facilitate Amateur Radio
communication under extreme weak-signal conditions. Three very
different coding and modulation methods are provided: one for
communication by "meteor scatter" techniques on the VHF bands; one for
meteor and ionospheric scatter, primarily on the 6 meter band; and one
for the very challenging EME (Earth-Moon-Earth) path.
2 Program Overview
----------------------------------------------------------------------
WSJT's user interface is written in Python. The major Python
source-code files include:
1. wsjt.py Defines the main-screen GUI for user interactions;
acts as "traffic cop" for orchestrating all
event-driven and time-shared activities.
2. specjt.py Provides real-time display of received signals as
two-dimensional "waterfall" spectra.
3. options.py Provides entry fields for user-defined parameters.
4. astro.py Displays astronomical data for sun, moon, sky
temperature, etc.
Smaller Python files serve various utility purposes.
Both wsjt.py and specjt.py make calls to external procedures compiled
from Fortran and C. A variety of global data is shared among modules
through common blocks defined in Fortran. The Python code runs in a
single thread, although timers make the functions of the several main
modules appear concurrent. Fortran routines create additional threads
to be used for soundcard I/O and the decoding of received messages.
As a small part of its overall task, the decoder for JT65 invokes an
external program named KVASD.EXE or KVASD, located in the main
WSJT directory. If this program is present it uses information on
received 64-FSK symbols and attempts to decipher it according to a
Reed Solomon (63,12) code, using the algebraic soft-decision algorithm
of Koetter and Vardy. If KVASD is not present, WSJT uses its own
internal hard-decision Reed Solomon decoder instead. Interprocess
communication between WSJT and KVASD takes place through a shared disk
file. KVASD is not an integral part of WSJT. Its algorithm is
patented, and the source code is the property of CodeVector
Technologies, LLC. However, compiled versions of KVASD may be freely
used in conjunction with WSJT for the purposes of amateur radio
weak-signal communication.
3 Some Functional Details
----------------------------------------------------------------------
WSJT execution starts at the top of Python file wsjt.py. The
other Python modules are loaded and executed as needed. Fortran
routines are called to start a high-priority thread to handle
continuous A/D and D/A streams, and a background thread to decode
received or previously recorded signals. The top-level Python
code determines the overall state of program operation, e.g.,
Idle, Monitoring, or Transmitting. In normal usage the operator
puts the program into Auto mode, resulting in a timed sequence of
alternating transmission and reception intervals.
4 Other Open-Source Software used in WSJT
----------------------------------------------------------------------
WSJT 5.9 uses the following open source libraries:
1. FFTW, by Matteo Frigo and Steven Johnson, for computing Fourier
transforms
2. PortAudio, by Ross Bencina and Phil Burk, for audio I/O
3. "Secret Rabbit Code" or "libsamplerate", by Erik de Castro, for
accomplishing band-limited resampling of data
4. RS, by Phil Karn, KA9Q, for Reed Solomon encoding and
hard-decision decoding.
5 Platform-Dependent Notes
----------------------------------------------------------------------
The Python code should run on any supported Python platform. Most of
the remaining code can be compiled for Linux, FreeBSD, unix, or OS/X,
as well as Windows. Platform-dependent versions of FFTW, PortAudio,
and libsamplerate may need to be installed.
Methods are provided for creating additional threads and setting their
runtime priorities in Windows, Linux, and FreeBSD.
6 Partial List of Functions and Subroutines, and their purposes
----------------------------------------------------------------------
Routines for audio startup, decoding, display computations
blanker.f90 Noise blanker
fivehz.f90 Called by PortAudio callback
flat2.f Flatten the spectrum for waterfall display
pix2d65.f90 Computes pixels for waterfall display
pix2d.f90 Computes pixels for waterfall display
runqqq.f90 Executes another process
wsjtgen.f90 Generates Tx waveforms
abc441.f90 Part of FSK441 generator
gen65.f Generate JT65 waveform
chkmsg.f Check a JT65 message for presence of 'OOO'
encode65.f Encode a JT65 message
getpfx1.f Handle extra DXCC prefixes
getpfx2.f ...
graycode.f Convert binary to/from Gray code
nchar.f Convert number, letter, space to 0-36
packcall.f Routines for JT65 source encoding
packdxcc.f ...
packgrid.f ...
packmsg.f ...
packtext.f ...
pfx.f ...
gen6m.f Generate JT6M waveform
gentone.f Generate tone for JT6M message
gencw.f Generate CW waveform
morse.f Convert ascii to morse dits
gencwid.f Generate a CW ID message
grid2k.f Convert grid locator to integer
interleave63.f Interleave JT65 symbols
gcom1.f90 Global commons for sharing data among Fortran routines
gcom2.f90 and between Fortran and Python
gcom3.f90
gcom4.f90
makedate.f90 Gererates makedate_sub.f90
Astronomical calculations:
astro.f Computes Az, El, Doppler for Sun, Moon, etc.
astropak.f "Includes" for astro supoport routines
azdist.f Computes azimuth, distance, etc., between two locators
coord.f Spherical trig utility
dcoord.f Spherical trig utility in double precision
deg2grid.f Convert lat/long (degrees) to grid locator
dot.f Compute dot product
ftsky.f Get sky temperature from data file
geocentric.f Convert geodetic to geocentric coords
GeoDist.f Compute azimuth and distance between two locators
grid2deg.f Convert grid locator to lat/long
moon2.f Compute moon location at specified date and time
MoonDop.f Compute lunar doppler shift and related quantities
sun.f Compure sun location at specified date and time
toxyz.f Convert between polar and cartesian coords
Utilities:
db.f Compute decibels from ratio
gasdev.f Generate Gaussian random numbers
igray.f Gray code
indexx.f Sort routine
set.f Move, add, zero, ...
pctile.f Sort an array and get specified percentile
ran1.f Uniform random numbers
rfile2.f Read a binary file (Linux)
sort.f Sort an array
FFTs:
fftw3.f Fortran definitions for FFTW
four2a.f Wrapper to make FFTW look like four2
four2.f FFT in Fortran (a;ternative to using FFTW)
ps.f Compute power spectrum
xfft.f Real to complex FFT wrapper
Routines for Decoding:
wsjt1.f Top-level decoding routine; handles FSK441 especially
avesp2.f Computes average spectrum
bzap.f Find and remove birdies
detect.f Measure power in FSK441 tones
flatten.f Flatten the spectrum
longx.f Decode normal FSK441 messages
lpf1.f Quick-and-dirty lowpass filter
mtdecode.f Multi-tone decoding
ping.f Find pings
s2shape.f Flatten the 2d spectrum
smooth.f Smooth by boxcar averaging
spec2d.f Compute 2d spectrum for FSK441
stdecode.f Decode FSK441 shorthand messages
sync.f Synchronize FSK441 data
wsjt65.f JT65 decoder
afc65.f AFC for JT65
avemsg65.f Decode average message
decode65.f Decode JT65 message
deep65.f Deep search decoder
demod64a.f Compute probabilities of transmitted symbols
extract.f Extract message from JT65 symbol probabilities
flat1.f Flatten the passband
getsnr.f Compute snr or shorthand message
k2grid.f Convert integer to 4-digit grid locator
limit.f Clipper for JT65
peakup.f Interpolate to find fractional-bin peak
setup65.f Initialize pseudorandom sync vector
short65.f Detect JT65 shorthand messages
slope.f Remove a straight-line slope
spec2d65.f Compute 2d spectrum for JT65
spec441.f Compute spectra for FSK441 decoding
sync65.f Synchronize a JT65 signal
unpackcall.f Unpack JT65 message parts ...
unpackgrid.f ...
unpackmsg.f ...
unpacktext.f ...
xcor.f Compute cross-correlation for JT65 sync
decode6m.f Decode JT65 signal
syncf0.f First frequency sync
syncf1.f Second freq sync
synct.f First time sync
avemsg6m.f Get average JT65 message
JT65code.f Program to illustrate and test JT65 coding
Hard-Decision Reed Solomon Codec
decode_rs.c Decoder
encode_rs.c Encoder
init_rs.c Initialization routine
wrapkarn.c Wapper for Fortran
cutil.c Fortran wrappers for some basic C functions
jtaudio.c Audio I/O, calls PortAudio routines
padevsub.c Select desired audio device
ptt.c PTT via serial port DTR/RTS
ptt_linux.c Ditto for Linux (dummy at present)
resample.c Wrapper for resample routine
start_threads.c Start audio and decoder threads
7 Compiling Instructions
----------------------------------------------------------------------
Scripts are provided for compiling WSJT in both Windows and Linux.
They are presently set up to use Compaq Visual Fortran (v6.6) and
Microsoft C (v6.0) in Windows, and g95 and gcc in Linux. My
installation has Python 2.3. Additional tools include f2py, which
compiles Fortran and C to make Python extensions; the Python Imaging
Library; Numeric Python; and the SciPy distribution utilities.
Linux Windows Function
-------------------------------------------------------------------
g0 g0.bat Compiles the hard-decision Reed Solomon Decoder
Needs to be done only once.
g1 g1.bat Compiles the remaining Fortran and C to produce Python
extension module audio.pyd (Windows) or audio.so
(Linux).
g2 g2.bat Uses McMillan Installer to create an f2py specification
file, wsjt.spec
g3 g3.bat Uses Installer to produce a distributable file WSJT6.EXE
(Windows).
g99 g99.bat Runs all of the g[0-3] scripts.
These steps produce a distributable file WSJT6.EXE (Windows) or wsjt6
(Linux) that contains all necessary software components, so that the
end user does not need to install Python or any of its other
extensions, or the compilers.
A configuration script and Makefile facility is also provided.
Assuming that all of the pre-requisites are properly installed, WSJT
can now be compiled in Windows as follows:
C> copy Makefile.win Makefile
C> nmake
In Linux or FreeBSD, do the following:
$ ./configure --enable-portaudio (or --enable-alsa or --enable-oss)
$ make
8 Present status (January 17, 2006)
----------------------------------------------------------------------
WSJT version 5.9.2 (built from SVN revision 115) has been released for
Windows. It is is fully functional in Linux and BSD, as well, but
presently need to be compiled locally. In due course we plan to
provide distributions for standard *nix distributions.