WSJT-X/WSJT_Source_Code.txt

			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.