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) $ 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.