WSJT User Guide

Still to come …

This guide refers to installation of WSJT on Mac OSX 10.7 and 10.9. This scheme should also work on OSX 10.8 but has not been tested. There are problems with Tcl/Tk libraries which prevent the code from running on OSX 10.10. You will need to be familiar with Unix commands in a Terminal window.

and if all has proceeded without error, WSJT should launch.

You will need a Mac driver to control the serial link between your Mac and the transmitter.

Source code is available from the public repository at SourceForge. To compile the program you will need to install the following packages:

With Subversion installed, the full source code for WSJT can be downloaded with the command:

For some basic instructions on building WSJT from source code, see the section Compiling WSJT-X near the end of this Guide.

You can control the fonts and colors used in WSJT. A text file named wsjtrc.win (on Windows) or wsjtrc (on Linux and FreeBSD) is supplied with the following contents:

You can edit this file with a text editor (such as Windows Notepad). For example, to make the on-screen fonts slightly larger you can increase the numbers on the first three lines to 9, 9, and 10. It might be wise to save a backup of the original file under a different name, in case you need to restore the original contents.

Decoding and operating procedures are different for the various WSJT modes, so it helps to practice with each mode before using it on the air. As a useful starting point, take at least the following steps:

To follow the full tutorial — and it’s strongly recommended that you should do this — download the collection of sample wave files available in zip (Windows) or tar (Linux) format. These files contain recordings of real signals in typical on-the-air situations, for each of the WSJT modes.

It’s convenient to think of the WSJT protocols in two groups — fast and slow. The fast modes (JTMS, FSK441, ISCAT, and JT6M) send text messages character-by-character, without forward error correction, at rates ranging from nearly 200 characters per second (JTMS) down to about 14 cps (JT6M). JTMS and FSK441 attempt to make the best possible use of the common, very short pings of meteor scatter, with durations around 0.1 s and even less. ISCAT and JT6M perform well with somewhat longer signal enhancements, including those characteristic of meteor/ionospheric scatter at 50 and 70 MHz, and also aircraft scatter at 10 GHz. The fast modes generally use T/R sequences of length 30 s, with 15 s as an option.

The slow modes in WSJT are designed for signals that are very weak — perhaps averaging 10 dB or more below the audible threshold — but more or less steady. These modes use strong error-control coding, so the software generally decodes a transmission exactly as it was sent, or not at all. T/R sequence lengths are usually one minute.

WSJT should now be set up and ready to operate. If you are a new WSJT user, we strongly recommend that you work through the operating tutorial in the next section.

By longstanding tradition, a minimal valid QSO requires the exchange of callsigns, a signal report or some other information, and acknowledgments. WSJT is designed to facilitate making such minimal QSOs under difficult conditions, and the process can be made easier if you follow standard operating practices. The recommended procedure is as follows:

Slightly different procedures may be used in different parts of the world, or in the different operating modes. Hitting the F5 key will cause WSJT to display a screen that reminds you of the recommended procedures.

To prepare for making a QSO, enter the other station’s callsign in the To radio box and click Lookup and Gen Msgs to generate a sequence of the commonly used messages. If Lookup does not find the callsign in the database file CALL3.TXT, you may enter the grid locator manually. Decide whether you or the other station will transmit first, and check or uncheck Tx First appropriately. Select the message for your next transmission by clicking the small circle to the right of the message text. Toggle Auto ON to start an automatic sequence of transmission and reception intervals. You can switch messages while a transmission is in progress by clicking on one of the buttons Tx1 to Tx6, to the right of the circles.

Spectral information is displayed in real time on the SpecJT screen. Spectrograms normally scroll horizontally in the fast modes (FSK441, JTMS, ISCAT, and JT6M) and vertically in the slow modes (JT65 and JT4). You can choose different scrolling speeds at the top right of the SpecJT window.

At the end of each receiving period, WSJT enters a decode cycle and displays various properties of a received signal on the main screen. An example for JT6M mode is shown below. A green line in the main graphical area illustrates signal strength vs. time, and other lines or images display spectral information and synchronization results, depending on the mode.

Decoded text appears in the large box below the graphical area and is also written to a cumulative output file, ALL.TXT. The program’s best estimate of DF, a detected signal’s frequency offset, is included on each text line. The accuracy of these estimates depends on the mode: approximately ±7 Hz for JTMS signals, ±25 Hz for FSK441, ±20 Hz for ISCAT and JT6M, and ±3 Hz for JT65. Within these tolerances (and subject to the stability of oscillators and the propagation path) you should see consistent numbers in the DF column during any QSO that produces usable signals.

Double-clicking on a callsign in either one of the decoded text windows will cause that callsign to be copied into the To radio box. The corresponding Grid locator will be looked up in the database and the callsign inserted in Tx message boxes #1 and #2. If the decoded text line includes CQ before the selected callsign, message #1 will be selected for your next transmission. Otherwise, #2 will be selected. If Double-click on callsign sets TxFirst was checked on the Setup menu, the status of Tx First is set according to the time-stamp on the decoded message.

The JTMS, FSK441, ISCAT, and JT6M operating modes use 30-second periods (optionally, 15-second periods) for transmission and reception. When a reception interval is completed the program looks for signal enhancements produced by short-lived reflections from meteor trails, or signal peaks from other types of scatter propagation. Usable “pings” are audible when they occur, and you will see them as spikes on the green line and brighter colors in the scrolling spectrogram. One or more lines of decoded text may result from each ping. By clicking in the graphical area you can force a decoding attempt at a particular spot in a record. You can also make the program decode in real time, just after hearing a signal enhancement, by clicking on the appropriate spot in the SpecJT display.

WSJT attempts to compensate for relative mistuning between transmitting and receiving stations. By default the frequency search range is ±400 Hz. You can reduce the tolerance range by setting the value of Tol to a smaller value. Adjustments to the decoding parameters can be made at any time by right- or left-clicking on the parameter labels. The control labeled S or Sync sets the minimum level for acceptable signals.

In FSK441 mode, if DF lies outside the range ±100 Hz it will help to retune your receiver to compensate. Do this with your transceiver’s RIT control, or by using split Rx/Tx VFOs. In the JTMS, ISCAT, and JT6M modes you can accomplish the same effect by checking Freeze and using the keyboard right/left arrows to move Freeze DF (as displayed in the bottom-of-screen status bar) to the desired value. In general you should not change your transmitting frequency during a QSO, since your partner will be trying to tune you in at the same time.

In addition to the green line for overall signal strength, JT6M produces a yellow line showing the detected strength of a JT6M synchronizing tone (see illustration above). JT6M attempts to decode both individual enhancements and an average message based on the entire transmission (or selected portions thereof). An average message is flagged with an asterisk at the right end of the decoded text line. Clicking with the left mouse button decodes a 4 s block of data near the mouse pointer, while the right button decodes a 10 s segment. As in FSK441, with marginal signals you should experiment as necessary for best decoding. ISCAT and JT6M can work with signals many dB weaker than those required for JTMS and FSK441. You will sometimes find that clicking on a smooth green line, even where nothing was heard and nothing can be seen, causes callsigns or other information to pop up out of the noise.

Standard messages in the fast modes are generated with the aid of templates defined on the Setup | Options screen. Default templates are provided conforming to standard operating practices in North America and Europe, and you can edit the templates to suit your own requirements. Your edits will be saved on program termination and restored when you restart WSJT. Normal fast-mode messages can contain any arbitrary text up to 28 characters. The supported character set includes 0-9, A-Z, plus . , / # ? $ and <space>.

JTMS and FSK441 provide a special shorthand format to transmit four simple messages in a highly efficient way. The supported shorthands are R26, R27, RRR, and 73; FSK441 and JTMS send pure tones at 882, 1323, 1764, or 2205 Hz to convey these messages. If activity levels are high enough that there could be some doubt about who has transmitted a shorthand message, it is better to use normal messages tagged with callsigns or portions thereof. Check Rx ST and Tx ST enable single-tone messages.

A typical minimal QSO in one of the fast modes might look something like the sequence of transmissions below. You should step ahead to the next message in your sequence only when you have received your QSO partner’s information from his sequence.

In North America, shorthand messages R26, RRR and 73 are often substituted for messages 4, 5, and 6, so the QSO would proceed like this:

JT65 and JT4, the slow modes in WSJT-X, aim to facilitate minimal QSOs by using short structured messages. The process works best if you use these formats and follow standard operating practices. The recommended basic QSO goes something like this:

Standard messages consist of two callsigns (or CQ, QRZ, or DE and one callsign) followed by the transmitting station’s grid locator, a signal report, R plus a signal report, or the final acknowledgements RRR or 73. JT65 and JT4 compress and encode these standard messages in a highly efficient way, and strong error-control coding makes them very reliable. In uncompressed form they may contain as many as 18 characters.

Signal reports are specified as signal-to-noise ratio (S/N) in dB, using a standard reference noise bandwidth of 2500 Hz. Thus, in example message #3 above, K1ABC is telling G0XYZ that his signal is 19 dB below the noise power in bandwidth 2500 Hz. In message #4, G0XYZ acknowledges receipt and responds with a -22 dB signal report. JT65 reports are constrained to lie in the range -30 to -1 dB, while JT9 supports the extended range -50 to +49 dB.

Shorthand messages are transmitted in JT65 as a sequence of alternating tones, repeating approximately every 3 seconds. Different tone spacings correspond to the shorthand messages RO, RRR, and 73; these messages can be easily recognized on the waterfall and also by ear. EME QSOs often use the shorthand messages, and in that case a typical QSO proceeds like this:

Free text messages are often used to convey some friendly chit-chat at the end of a QSO. Arbitrary messages such as “TNX ROBERT 73” or “5W VERT 73 GL” are supported, up to a maximum of 13 characters (including spaces). It should be obvious that the JT9 and JT65 protocols are not well suited for extensive conversations or rag-chewing.

Compound callsigns such as xxx/K1ABC or K1ABC/x are handled in one of two possible ways. A list of about 350 of the most common prefixes and suffixes can be displayed from the Help menu:

A single compound callsign involving one item from this list can be used instead of a third message word in a structured message. Thus, the following examples are all acceptable Type 1 messages involving compound callsigns:

The following messages are not valid, because a third word is not permitted in a Type 1 compound-callsign message:

A QSO involving a station using a Type 1 compound callsign might look like this:

Notice that both operators send and receive the full compound callsign in their first transmission. After that, they omit the add-on prefix or suffix and use the standard structured messages and base callsigns.

Type 2 compound callsigns involve a prefix or suffix not found in the short displayable list. In that case the compound callsign must be the second word in a two- or three-word message, the first word of which must be CQ, DE, or QRZ. Prefixes can be 1 to 4 alphanumeric characters, suffixes 1 to 3 characters. A third word conveying a locator, signal report, RRR, or 73 is permitted. The following are valid Type 2 messages with compound callsigns:

In each case, the message is treated as Type 2 because the add-on prefix or suffix is not one of those in the fixed list displayed above. Note that a second callsign is never permissible in messages involvinf Type 2 compound callsigns.

QSOs involving Type 2 compound callsigns might look like one of the following sequences

Each operator sends his own compound callsign in the first (and possibly also last) transmission, as may be required by licensing authorities. Subsequent transmissions use the standard structured messages without callsign prefix or suffix.

To get the best out of JT4 on the upper microwave bands (in particular 10 and 24 GHz), it has been found advantageous to use single tones for simple messages such as RRR and 73, after callsigns have been exchanged. For this to work unambiguously, high frequency accuracy and stability are needed. This can be accomplished using GPS locking and automatic Doppler correction on the EME path, as described in http://www.physics.princeton.edu/pulsar/K1JT/small_station_eme.pdf. The recommended mode for 10 and 24 GHz is JT4F. The exchange of numerical signal reports in dB is also encouraged, to ensure that unknown information is exchanged.

You can transmit a pure tone at frequency XXXX by entering @XXXX in the active TX box. The resulting signal has all its energy at a single frequency, so much easier to see on the waterfall. With good calibration the frequency can be read directly from the waterfall. Once one aligns on the 1270 Hz TUNE tone and checks Freeze on the main window there will be two red ticks on the waterfall, marking the RRR and 73 messages. WSJT also provides a facility to integrate spectra over a full transmission, to gain a further sensitivity improvement. Check Plot average JT4 spectrum on the Setup menu.

Single tones and their meanings are as follows:

You can insert these frequently used tones as templates on the Setup | Options window:

One small quirk is that if you double right click on the other station’s callsign to pick up the report this will return the format to the standard (non-single tone) arrangement. This is readily overcome by clicking on Gen Msgs when one is ready to TX single tones.

This procedure has also proved effective for terrestrial contacts using JT4F on tropo-scatter, ducting, and rain-scatter.

The MinW parameter allows settings of A to F. The letters represent Doppler-spread widths corresponding to tone spacings of the JT4 submodes:

The JT4 decoder tests increasing bin-widths, starting from the letter set in MinW, to optimize decoding in relation to Doppler spread. It’s generally best to set MinW one or two steps below the predicted full spreading, which for EME is available in the Astronomical Data window. If the antenna beamwidth is smaller than the moon, actual spreading will be less.

False decodes are rare at microwave frequencies, where there is little man-made noise. You can safely set Sync to 0 to allow the program to synchronize on the weakest signals.

The WSJT CW mode is provided as a convenience for operators attempting EME contacts using timed transmissions of 1, 2, or 2.5 minutes duration. The program sends EME-style messages by keying an 800 Hz audio tone, and takes care of the timing and T/R switching. Receiving is left up to you, the operator. Set the desired CW speed under Miscellaneous on the Setup | Options window, and the T/R period by right- or left-clicking on the label at bottom center of the main window. Present conventions typically use 1 minute sequences on 50 MHz, either 1 or 2 minutes on 144 MHz, and 2.5 minutes on 432 MHz and above.

The following buttons appear just under the decoded text windows on the main screen. Note that some controls appear only in certain operating modes.

Controls related to the DX station and date and time are found at lower left of the main window:

Near the center of the main window are controls frequencly used during a QSO. Some controls are available only in certain modes; the following images apply to modes JTMS (left) and JT4 (right):

Controls for tranmitted messages appear at the right of the main window. You can insert a desired message into any of the six entry fields. The Gen Msgs button does this auromatically, in the appropriate format for the mode in use. The message marked in one of the circles will be the one sent at the start of the next Tx sequence. You can start a message immediately by clicking one of the Tx1 through Tx6 buttons.

JTMS uses Minimum Shift Keying (MSK) at 11025 / 8 = 1378.125 baud. Messages are free-form and have lengths 5,7,9,11,13,17,19,23 or 29 characters, padded when required with one or more trailing blanks. Characters are mapped to numerical values in the range 0 to 63 according to position in the first line below. (The second and third lines may be used to read off an index value: for example, B has the value 11 and ? is 38.)

The 6-bit binary representation for each character value is augmented with an even parity bit. The resulting 7-bit sequences are sent using audio frequency 1155.47 Hz to represent 0 and 1855.53 Hz to represent 1. A message is transmitted repeatedly for a full transmission, maintaining phase continuity at all transitions between tones.

Four single-tone messages are defined in JTMS: R26, R27, RRR and 73. They are transmitted as pure tones of 882, 1323 and 1764, and 2205 Hz respectively. Pings from these transmissions are easily recognized by the human ear, easily seen on spectrum displays, and readily detected by appropriate software.

FSK441 uses four-tone frequency shift keying at 441 baud. The frequencies of the audio tones are 882, 1323, 1764, and 2205 Hz. Each encoded character uses three tone intervals and therefore requires 3/441 seconds (approximately 2.3 ms) for transmission. FSK441 accommodates an alphabet of 43 characters, as listed in the table below:

In the table the four tones are labeled 0-3, representing the tones 882, 1323, 1764, and 2205 Hz. For example, the letter T has the code 210 and is transmitted by sending sequentially the tones at 1764, 1323, and 882 Hz. Note that the character <space> is encoded as 033, and that tone sequences starting with the highest tone (number 3) are not used. It follows that if transmitted messages always include at least one space, a decoding algorithm can establish proper synchronization from the message content itself, with zero overhead. This encoding strategy is one of the secrets of the high efficiency of FSK441 for meteor scatter communications.

The four possible single-tone character codes, namely 000, 111, 222, and 333, are reserved for special use as shorthand messages. When sent repeatedly, these reserved characters generate pure single-frequency carriers. Their pings are easily recognized by the human ear and also by appropriate software. The shorthand messages are defined to mean R26, R27, RRR, and 73, respectively. These messages are frequently used in meteor scatter QSOs, after callsigns have been exchanged. They are not used in IARU Region 1, where activity levels are high enough that messages should always be accompanied by callsigns.

FSK315 is a variant of FSK441 designed for use in North America on 10m. Baud rate is 315 baud and tones of 945, 1260, 1575 and 1890 Hz are used. FSK315 supports shorthand messages with R26, R27, RRR and 73 being assigned to 945, 1260, 1575 and 1890Hz respectively.

ISCAT messages are free-form, up to 28 characters in length. Modulation is 42-tone frequency-shift keying at 11025 / 512 = 21.533 baud (ISCAT-A), or 11025 / 256 = 43.066 baud (ISCAT-B). Tone frequencies are spaced by an amount equal to the baud rate. The available character set is

Transmissions consist of sequences of 24 symbols: a “sync” pattern of four symbols at tone numbers 0, 1, 3, and 2, followed by two symbols with tone number corresponding to the message length, and finally 18 symbols conveying the user’s message, sent repeatedly character by character. The message always starts with @, the beginning-of-message symbol. The sync pattern and message-length indicator have a fixed repetition period, recurring every 24 symbols. Message information occurs periodically within the 18 symbol positions set aside for its use, repeating at its own natural length.

For example, consider the user message CQ WA9XYZ. Including the beginning-of-message symbol @, the message is 10 characters long. Using the character sequence displayed above to indicate tone numbers, the transmitted message will therefore start out as shown in the first line below:

Note that the first six symbols (four for sync, two for message length) repeat every 24 symbols. Within the 18 information-carrying symbols in each 24, the user message @CQ WA9XYZ repeats at its own natural length, 10 characters. The resulting sequence is extended as many times as will fit into a Tx sequence.

JT6M uses 44-tone FSK with a synchronizing tone and 43 possible data tones — one for each character in the supported alphanumeric set, the same set used for FSK441. The sync tone is at frequency 100 x 11025 / 1024 = 1076.66 Hz, and the 43 other possible tones are spaced at intervals of 11025 / 512 = 21.53 HZ up to 2002.59 Hz. Transmitted symbols are keyed at a rate of 21.53 baud, so each one lasts for 1/21.53 = 0.04644 seconds. Every third symbol is the sync tone.The transmission rate of user data is therefore 21.53 x (2/3) = 14.4 characters per second.

A detailed description of the JT65 protocol was published in QEX for September-October 2005. Briefly stated, JT65 uses 60 s T/R sequences and carefully structured messages. Standard messages are compressed so that two callsigns and a grid locator can be transmitted with just 71 bits. A 72nd bit serves as a flag to indicate that the message consists of arbitrary text (up to 13 characters). Special formats allow other information such as add-on callsign prefixes or numerical signal reports to be substituted for the grid locator. The aim of source encoding is to compress the common messages used for weak-signal QSOs into a minimum fixed number of bits. After compression, a Reed Solomon (63,12) error-correcting code converts 72-bit user messages into sequences of 63 six-bit channel symbols.

JT65 requires tight synchronization of time and frequency between transmitter and receiver. Each transmission is divided into 126 contiguous time intervals or symbols, each of length 4096/11025 = 0.372 s. Within each interval the waveform is a constant-amplitude sinusoid at one of 65 pre-defined frequencies, and frequency changes between intervals are accomplished in a phase-continuous manner. Half of the channel symbols are devoted to a pseudo-random synchronizing vector interleaved with the encoded information symbols. The sync vector allows calibration of relative time and frequency offsets between transmitter and receiver. A transmission nominally begins at t = 1 s after the start of a UTC minute and finishes at t = 47.8 s. The synchronizing tone is at 11025 x 472 / 4096 = 1270.5 Hz, and is normally sent in each interval having a 1 in the following pseudo-random sequence:

Encoded user information is transmitted during the 63 intervals not used for the sync tone. Each channel symbol generates a tone at frequency 1275.8 + 2.6917 Nm Hz, where N is the value (0 - 63) of the six-bit symbol, and m is 1, 2, or 4 for JT65 sub-modes A, B, or C. The signal report OOO is conveyed by reversing sync and data positions in the transmitted sequence. Shorthand messages dispense with the sync vector and use intervals of 1.486 s (16,384 samples) for the alternating tones. The lower frequency is always 1270.5 Hz, the same as that of the sync tone, and the frequency separation is 26.92 nm Hz with n = 2, 3, 4 for the messages RO, RRR, and 73.

JT4 uses 72-bit structured messages nearly identical 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) x 2 = 206 information-carrying bits. Modulation is 4-tone frequency-shift keying at 11025 / 2520 = 4.375 baud. The frequency spacing between tones and total bandwidth depends on the submode.

After a clean install of WSJT on Windows the following files should be present in the installation directory:

Additional files will appear in the installation directory after the program has been run. These include the following: