Thursday, October 22, 2020

Using the jt9 executable to receive FST4W signals


Since originally posted, WSJT-X v2.3.0-rc2 was released, adding a feature to the "JT9" executable that simplifies this process (the "-F" parameter) as described below.  Note that most of this post was originally written soon after "rc1" had become available.

* * *

As a heavy user of K1JT's WSPR and operating on the 2200 and 630 meter bands, I have noted with interest the introduction of the "FST4W" mode in the recent (v2.3.0-rc1) wsjt-x release.  Operating using the same detection bandwidth as WSPR (when FST4W is operated in the 120 second mode) it offers a theoretical 1.4dB improvement in detection sensitivity.

Being involved with wsprdaemon (link to that project here ) - an open-source project that automates and optimizes reception of WSPR signals on all bands, particularly if multiple receivers/antennas are used - we have been watching this development with interest, particularly since FST4W has the likelihood of supplanting conventional WSPR operation, especially on the lowest amateur bands (2200, 630 and possibly 160 meters) where minimal of Doppler shift is expected.

Internally, WSJT-X  uses the subordinate wsprd program as the decoding (and encoding) engine.  As a stand-alone program, the wsprd executable code may be invoked with a command line to decode signals contained within a .wav file that was captured during the standard two minute interval - aligned with even UTC minutes - and produce a text file containing the decoded signals.

Why use the executable rather than the entire wsjt-x suite?  The fact is that the use of the wsjt-x suite does not lend itself easily to script-driven, bare-minimum, lightweight implementations where further processing of the decoded data (to remove duplicate decodes from multiple receivers, antennas and to use this same data for further analysis of signal/noise) is desired.

The "jt9" executable:

After a bit of digging about, it was "discovered" that FST4W - being an offshoot of the JT9 protocol - was handled not by the wsprd executable, but the jt9 executable.  Simply executing this program with no arguments will yield a list of command-line arguments which, on the face of it, made it appear that updating the wsprdaemon to include the decoding of FST4W signals would be a relatively simple matter.

Except that it didn't work.

Initial testing with strong, off-air FST4W signals that was known to be decodable (because farther-flung stations were able to decode the very same transmissions) yielded no results when the .wav file was applied to the jt9 program - but automatic execution over many hours yielded the occasional off-air decode.  Confused by this, I sought help on the WSJT-X forum.  Fortunately, Joe Taylor and several of the developers offered a clue:  The "-f" parameter of the jt9 executable, described minimally as "Receive Frequency Offset".

Apparently, the default center frequency of the jt9 executable - at least when in FST4W mode (and maybe others) is 1500 Hz - a fact implied when one gets the display of command-line arguments.  What is not so clear - and only alluded to in the available documentation - is that the apparent bandwidth of the decoding, at least in the 120 second mode, is on the order of 40 Hz (+/- 20 Hz)Addendum:  This issue was fixed with the "-F" parameter - see below.

At a quick glance through the source code (file "jt9.f90"), this bandwidth setting appears to be hard-coded into a shared variable (apparently accessible by other programs in the WSJT-X suite) called "ntol" (likely a number referring to the "frequency tolerance" setting in the GUI) that is not available via the jt9 command line - at least, not without modification of the source code.  (The possibility of directly accessing these shared variables exists - but this would be platform-specific, a bit messy and somewhat dangerous!)

Unfortunately, this fixed +/-20Hz bandwidth does not appear to be compatible with the way that the FST4W mode has (already!) found use on 2200 and 630 meters where it is used along-side the WSPR mode in the 200 Hz subbands.

A hell of a kludge:

Update - kludge no longer needed:

As of version 2.3.0-rc2 it appears that a new parameter "-F" was added to allow something other than a +/-20Hz bandwidth (referred to as "tolerance") to be used, likely eliminating the need for multiple decodes, below.  A possible command-line for this would be:
jt9 -W -p 120 -f 1500 -F 200 <wav file to be processed> 
With the center frequency (-f) being the center of the passband (1500 Hz) and the "-F" parameter referred to as"tolerance" (e.g. detection bandwidth) being 200 Hz. 
Initial testing indicates that the -F parameter does what it's supposed to do and the kludge below is now longer required.

This fact implies that in order to use something other than the GUI version of the wsjt-x software, a work-around must be invoked.  The following is a bare-minimum example of how one might do this via the command line:

jt9 -W -p 120 -f 1420 <wav file to be processed> 

jt9 -W -p 120 -f 1460 <wav file to be processed>

jt9 -W -p 120 -f 1500 <wav file to be processed>

jt9 -W -p 120 -f 1540 <wav file to be processed>

jt9 -W -p 120 -f 1580 <wav file to be processed>

(One might include the -H, -L and -d parameters in actual practice.)

In other words, in order to cover the entire 200 Hz WSPR subband, the JT9 executable (v2.3.0-rc1) must be executed - processing the same .wav file - at least five times:  The results of the decoding will, in each case, be found in the file "decoded.txt".  If one wishes to implement an equivalent of the -w parameter of the wsprd executable (e.g. +/- 150 Hz "wideband" mode), you will need even more invocations than above.

The result from the above mess will be five different decoding results, each of which must be saved (e.g. renamed) between subsequent executions to prevent overwriting by the previous instance.  After this, the five results would be concatenated to yield a single file - but there is a catch:  It is likely - particularly if the signal is strong - that the same signal will be decoded more than once.  Apparently, the "+/- 20Hz" limit isn't the result of a "brick-wall" filter:  Signals beyond this frequency range may be decoded, but the reported S/N values will likely be reduced as distance of the received signal from the specified center frequency increases.  In short, this means that the results of the concatenated version of the "decoded" file(s) must be sorted and all but the single, "strongest" decode (e.g. best SNR) for each station must be discarded.


It would appear that just five iterations to cover the 200 Hz bandwidth is not enough:  I received correspondence from a reader of this blog that observed that a frequency variation of less than 10 Hz from that defined by the "-f" parameter can affect the S/N reading by about 1 dBMake of that what you will!

* * * * * * * * *

If one wishes to integrate the FST4W decodes into the existing WSPR captures for processing, yet another step must be undertaken:  "Fixing" the formatting.  Not surprisingly, the output in the "decoded.txt" is not formatted the same as the results of the decoding from the wsprd executable meaning that one will need to do a few things, after the fact, to "fix" them - particularly if you wish to forward them to, including:

  • Supply the date.  The "decoded.txt" includes the time - but not the date.  Because date of the .wav file may not be the same as the system date (e.g. later processing of the .wav files - or the interval being processed occurred just before the new day) - one must use the actual date of the recording.  The obvious place to obtain this is from the name of the .wav file being processed.
  • Frequency offset.  The information that one might send to must include the carrier frequency of the received signal, but the output in the "decoded" file has only the audio frequency:  One must obtain the LO frequency of the receiver being used from "somewhere else" and calculate this on the fly.
  • Supply missing information.  The "decoded.txt" file does not have all of the same information fields that one might supply when uploading WSPR spots, so this information must be added as necessary.
  • Arrange the fields in the proper order.  Once the needed information is applied, one will probably want to use "awk" or similar to produce the same order as the wsprd data - assuming this wasn't already done in the process.

* * *

There are two outputs from the jt9 executable - one directly from the program itself to the standard console and that output to the file "decoded.txt" - and the latter is the most useful. 

Console output:

0416 -24  0.7 1515 `  KA7OEI DN40 17                                 
<DecodeFinished>   0   1

The fields are:  <time UTC> <SNR in dB> <DT?> <Audio frequency in Hz> <always "`"> <Callsign received> <Grid of received station> <Reported TX power in dBm>

From the "decoded.txt" file:

0416   0  -24   0.7   1515.   0   KA7OEI DN40 17                        FST4

 The fields are:  <time UTC> <unknown - possibly drift in Hz> <SNR in dB> <DT?> <Audio frequency in Hz> <unknown> <Callsign received> <Grid of received station> <Reported TX power in dBm> <Always "FST4">

* * *

There you have it:  The germ of what would be needed if one wishes to supplement the existing WSPR decodes with the newer FST4W mode using just the bare executables.  If one wishes to decode other than the 120 second FST4W mode, things get even more complicated!

Sample audio file:

An audio file containing both FST4W-120 and WSPR transmissions may be found HERE - right-click to download.  This file contains an FST4W-120 transmission by KA7OEI from about 116km distant and (at least) two WSPR transmissions.

* * * 
Note:  It appears that the "-F" parameter, above, modifies the default ntol setting as described above.

P.S.:  While it would be pretty trivial tweak the code to allow modification of the ntol variable via command line, this would complicate the ongoing maintenance of the wsprdaemon code.  We can only hope that the current authors see fit to include a means by which the entire wspr subband can be monitored with a single invocation of the jt9 executable.


This page stolen from