1. Introduction

WSPR (pronounced “whisper”) stands for Weak Signal Propagation Reporter. WSPR implements a protocol designed for probing potential propagation paths using low-power transmissions. Normal transmissions carry a station’s callsign, grid locator, and transmitter power in dBm. The program can decode signals with S/N as low as -28 dB in a 2500 Hz bandwidth. Stations with internet access can automatically upload their reception reports to a central database called WSPRnet, with a mapping facility, archival storage, and many other features.

Like its sister programs WSJT, MAP65, WSJT-X, and WSPR-X, WSPR is part of an open-source project released under the GNU General Public License (GPL v3). If you have programming or documentation skills or would like to contribute to the project in other ways, please make your interests known to the development team. The project’s source-code repository is SourceForge, and most communication among the developers takes place on the email reflector wsjt-devel.

2. System Requirements

  • SSB receiver or transceiver, and antenna

  • Computer running Windows (XP or later), Linux, or OS X

  • 1.5 GHz or faster CPU and 100 MB of available memory

  • Monitor with at least 800 x 600 resolution (more is better)

  • Computer-to-radio interface using a serial port for T/R switching, or CAT control, or VOX, as required for your radio-to-computer setup

  • Audio device(s) supported by your operating system, capable of 48 kHz sample rate

  • Audio or equivalent USB connections between transceiver and computer

  • A means for synchronizing computer clock to UTC within ±1 second

3. Installation

3.1. Windows

  • Download WSPR from the WSJT Home Page. Click on WSPR at the left margin and then on the desired download link.

  • Execute the downloaded file and follow its installation instructions.

  • Install WSPR into its own directory rather than the conventional location C:\Program Files\WSPR. The suggested default directory is C:\WSPR.

  • All files relating to WSPR will be stored in the chosen installation directory and its subdirectories. You can uninstall WSPR by removing the installation directory and its contents.

  • The built-in Windows facility for time synchronization is usually not adequate. We recommend Meinberg NTP: see Network Time Protocol Setup for downloading and installation instructions.

Caution If you are using a sound card that is also the Windows default audio device, be sure to turn off all Windows sounds so they are not transmitted over the air.

3.2. OS X

NH6Z has made a binary available for download. Download and follow his instructions here.

3.3. Linux

For Ubuntu and other recent 32/64 bit Debian-based systems, you can download an installation file from another link on the WSPR Home Page. To install and execute WSPR, put the downloaded file in your home directory and execute the following commands from a command-prompt window, if necessary substituting the correct revision number for the one shown:

$ sudo dpkg --instdir=. -i wspr_3.00r2319_i386.deb
$ cd WSPR
$ ./wspr

3.4. Source Code

Building WSPR from source code is straightforward but takes time and requires some experience. Source code can be downloaded from here, the public repository at SourceForge. Detailed instructions are available in the Dev-Guide. You will need the following development tools:

  • Subversion

  • gcc or equivalent C compiler

  • gfortran

  • fftw3 (headers and libraries)

  • portaudio19-dev (headers and libraries)

  • samplerate (headers and libraries)

  • python3, python3-dev, python3-numpy, python3-pil or pillow, python3-tk python3-imaging-tk, autoconf, autotools-dev

  • hamlib utilities

4. Setup and Configuration

4.1. Station Parameters

  • Connect appropriate interface cables between radio and computer. Details will depend on your interface hardware; in general you will need to connect the radio’s audio output to the computer’s soundcard input, and for receive-only systems that’s all you need! If you will also be transmitting you must patch soundcard output to the radio’s microphone or data input. For T/R switching and CAT control you may need a serial data cable or cables.

  • Start WSPR and select Station parameters from the Setup menu. Enter your callsign and 6-digit grid locator, select audio input and output devices, and select your transmitter power in dBm. (See Appendix A for a Watts-to-dBm conversion table.) Compound callsigns such as PJ4/K1ABC, W7/VE3DEF, and WA2XYZ/37 are permitted but should be used only when necessary. Double-compound callsigns such as PJ4/K1ABC/P are not supported. SWLs should provide a unique identifier (up to 8 characters) in place of a callsign.

images/Station_Parameters.png
  • If you choose to transmit as well as receive, WSPR will control the T/R sequencing. Select the desired PTT method (DTR, RTS, CAT, or VOX). For DTR- or RTS-controlled switching, select a PTT port. For receive-only or VOX-controlled systems, set PTT port to None.

  • WSPR offers limited CAT control of your transceiver, usable for T/R switching and frequency setting. To use this feature check Enable CAT and fill in the remaining parameters. Consult the manual for your radio to determine necessary parameter values for the serial connection.

4.2. Fonts

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

*font:                  Arial 8
*Label*font:            Arial 8
*Text*font:             "Courier New" 10
*Canvas*font:           "Lucida Console" 16
*background:            gray85
*Text*background:       white
*Entry*background:      white
*foreground:            black
*Listbox*foreground:    RoyalBlue

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 11. 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.

5. Basic Operation

Confirm proper operation of the WSPR decoder by opening a sample audio file recorded by WSPR. Select File | Open, navigate to the …\save\Samples directory under the installation directory, and open the file 091022_0436.wav. A total of six WSPR signals should be decoded, and your screen should look like the image below. You might find it interesting to listen to the sample file using Windows Sound Recorder or a similar utility program. The WSPR signals are barely audible, if audible at all, and the recording includes many atmospheric static crashes… and yet WSPR decodes the signals without errors.

images/Sample_File_Decoded.png

To prepare for on-the-air operation, proceed as follows:

  • Select an operating band from the Band menu. The default WSPR frequency will appear in the Dial frequency box. For example, you should see 10.138700 MHz for the 30 m band. Set your transceiver to this frequency in USB mode, or a USB-based data mode. If you have enabled CAT control, frequency setting should occur automatically. Select a desired Tx frequency by double-clicking somewhere in the graphical display area. Available Tx frequencies fall in the range 1400–1600 Hz above the dial frequency. Clicking near the bottom of the graphical area gives a frequency near the lower limit, and clicking near the top puts you near the upper limit.

  • WSPR uses two-minute time slots for transmitting and receiving. The slider labeled Tx fraction sets the average proportion of time allocated for transmitting. The default setting of 20% is a good compromise under most conditions: it means that you will transmit approximately once every ten minutes and receive the rest of the time. The exact T/R sequence will be randomized so as to maximize your chances of receiving other WSPR stations. For receive-only operation, set the Tx fraction slider to zero.

  • While in Idle mode, you may click the Tune button to produce a short unmodulated test transmission. Duration of the transmission (in seconds) is set by the Tx fraction slider.

  • If you have internet access and wish to upload your reports automatically to WSPRnet, check the box labeled Upload spots.

  • Be sure that your computer clock is correct to within about ±1 second.

  • To begin normal operation, clear the Idle checkbox. WSPR will then begin a receive sequence at the start of the next even-numbered UTC minute. After reception has started, use the computer’s sound mixer and/or the volume controls on your radio or soundcard interface to adjust the audio level (lower left corner of main WSPR screen) to about midscale.

  • At the end of each reception interval, the waterfall will update and any decoded WSPR messages will appear in the main text window. The decoder looks for all detectable WSPR signals in a 200 Hz passband and displays its results in a waterfall spectrogram, a text window, and a Band Map. The spectrogram covers a narrow frequency range (about 200 Hz) in the vertical direction; the last three digits of the received frequency, in Hz, are displayed on a scale at right. Time runs from left to right in the spectrogram. On a typical computer screen each two-minute interval is a strip about 1 cm wide. The times of your own transmissions are denoted by thin green vertical lines in the spectrogram.

images/Spectrogram.png
  • Each decoded WSPR signal produces text showing the UTC, measured signal-to-noise ratio in dB (in a 2500 Hz reference bandwidth), time offset DT in seconds, measured frequency in MHz, drift rate in Hz/minute, and the decoded message. Time offsets greater than about ±2 seconds indicate a significant timing error at transmitter or receiver, or possibly both. For best performance your computer clock should be kept accurate to within ±1 second. Apparent frequency drifts greater than ±1 Hz per minute can usually be traced to the transmitter, and should be corrected if possible. Of course, receiver drifts could also contribute to a measured drift — but they are easily recognized because nearly all signals will then appear to drift by the same amount.

images/Decoded_Text.png
  • Color coding is used in the Band Map to indicate elapsed time since a station was decoded. Calls in red have been seen within 15 minutes of the last line of decoded text; yellow callsigns are 15-30 minutes old, light gray 30-45 minutes, and darker gray 45-60 minutes. Callsigns more than an hour older than the most recent one are deleted from the Band Map.

images/Band_Map.png
  • For best performance the background noise level going into the computer should be set to show approximately midscale on the "thermometer" scale at lower left. Deviations as large as ±20 dB from nominal will not affect WSPR decoding capability significantly. The idea is to have the baseline noise level high enough for quantization noise to be negligible, but low enough to give adequate dynamic range. Signal levels reported for each WSPR decode are the measured ratio of signal power to average baseline noise power, scaled to a reference bandwidth of 2500 Hz. Within broad limits, this ratio is independent of the level setting.

  • Under most conditions a receiver bandwidth normal for voice SSB communication, say 2.4 kHz, is a good choice. Narrower bandwidths are perfectly acceptable if you have problems with strong signals well outside the 200 Hz WSPR passband. There is no particular advantage in using a bandwidth as small as 200 Hz, however, since WSPR does all necessary narrow-band filtering in software.

  • Usually it is not critical whether AGC is on or off. A good default procedure is to leave it on, and set the desired audio level by reducing the RF gain. In effect this means that AGC will be activated only when very strong signals are present in the passband. Slow-recovery AGC settings are generally not desirable for WSPR.

6. Advanced Setup

  • The Advanced dialog can be called up from the Setup menu or by typing F7. As shown in the screen shot below, a slider control allows you to reduce your Tx audio signal by a specified amount. The normal setting for full output is 0 dB (slider all the way to the right). You can reduce power by up to 30 dB by moving the slider to the left. Changes take effect at the start of the next transmission. It may be convenient to adjust this slider by setting Tx fraction to 100% and clicking the Tune button to produce a series of transmitted dashes. Each dash will then reflect any new slider setting.

images/advanced.png
  • If your licensing authority requires callsign identification in Morse code at specified intervals, you may set the interval in the CW ID (min) field. Your callsign will then be sent in CW at the end of WSPR transmissions, at the specified interval. Because CW at 25 wpm uses several times more bandwidth than a WSPR signal, it is strongly recommended that you not use the CW ID feature unless required to do so.

  • Users of homebrew receiving equipment may require a different BFO frequency than the standard 1500 Hz used for SSB transceivers. You can enter a nonstandard value in the field labeled Rx BFO (Hz).

  • Many modern transceivers use a master oscillator from which most other frequencies are synthesized. If the master oscillator is slightly off frequency, all dial readings may be high or low in a predictable way. Appendix C outlines a simple procedure for determining whether your radio can be calibrated in this way, and if so how to determine the calibration constants A and B. Then, if you are using CAT control, you can improve the accuracy of your transmitted and received frequencies by entering these values and checking Enable frequency correction on the Advanced setup screen. Frequencies sent to the radio will then be adjusted according to your calibration constants. The button labeled Measure an audio frequency may be useful in determining values for A and B. See Appendix C for details. If using CAT control, you can force a frequency-setting command by clicking Update rig frequency.

7. I-Q Mode

7.1. Basic Parameters

  • I-Q mode is intended for use with direct conversion receivers or transceivers like the SoftRock. To use such a radio select PTT method = CAT and Rig number = 2509 on the Setup | Station Parameters screen. Then select IQ Mode from the Setup menu or type F8, which will display the screen shown below.

images/IQmode.png
  • Depending on how you have wired your SoftRock, you may or may not need to check Reverse Rx I,Q or Reverse Tx I,Q. The parameter Fiq (Hz) determines the frequency offset between Dial frequency specified on the WSPR main screen and the frequency (times 1/4) of the SoftRock’s Si570 programmable oscillator. The default value for Fiq is 12000 Hz; this puts the 200 Hz WSPR band 12 kHz above mid-band. For example, when operating on the 30 m band you might set Dial frequency = 10.1387 MHz and Fiq = 12000 Hz. These settings result in a commanded Si570 frequency of (10.138700–0.012000) × 4 = 40.506800 MHz.

  • You will probably need to calibrate the frequencies produced by your Si570 oscillator. Use the procedure outlined in Appendix C.

Tip Remember that for most effective use of WSPR, you will want your frequencies to be correct within a few Hz.
  • If your direct conversion receiver has a fixed local oscillator frequency, compute the value of Fiq from the equation below. Be sure all values are in Hz, and remember that (unless you have changed it) the BFO frequency is 1500 Hz so the last two terms will cancel.

    +f~iq~ = f~dial~ – f~LO~ – f~BFO~ {plus} 1500.+

7.2. Image Rejection

WSPR 4.0 includes facilities for optimizing image rejection on transmit and receive. You should start by establishing whether Reverse Rx I,Q or Reverse Tx I,Q need to be checked. (With these boxes unchecked, the assumed routing of in-phase and quadrature signals to the soundcard is “I=Left, Q=right.”) A typical SoftRock should exhibit around 30 dB of unwanted sideband rejection without further adjustment. However, rejections of 60 dB or more can easily be achieved in WSPR. Here’s how.

To adjust Tx image rejection you need a separate communications receiver:

  • Start WSPR, select the desired band, check the Idle box, set Tx fraction to 100%, and click the Tune button. WSPR will send a series of long dashes at the selected frequency. * Tune in the main signal on the separate receiver; then find the unwanted image, which will be offset in frequency by twice the sum of Fiq and the Rx BFO frequency.

(For the example setup described above, the image is 27 kHz below the desired signal.)

  • While listening to the unwanted image, slowly adjust the sliders labeled Tx I/Q Balance and Tx Phase on the Setup | I-Q Mode *screen, seeking a null.

There are two sliders for each parameter — the upper one for coarse adjustments, the lower for fine. New settings are applied at the start of each transmitted dash.

  • When you have found the best null you may exit WSPR. The program will remember your last settings of Tx I/Q Balance and Tx Phase.

Rx image rejection is accomplished in a semi-automatic way. With another transmitter or stable signal generator, generate a moderately strong signal inside (or within ± 500 Hz of) the 200 Hz WSPR band you will be receiving.

  • Start WSPR, clear the Idle box, and set Tx fraction to 0.

  • After a reception interval starts, check the box Adjust Rx phasing and watch the numbers labeled Bal and Pha converge to stable values. This may take 30 seconds or so. You may then uncheck Adjust phasing and check Apply Rx phasing corrections.

The measured phasing parameters will then be applied to received signals at the end of each Rx interval. With this procedure, unwanted sideband suppression should be better than 60 dB. An example is illustrated by the following screen shot showing the WSPR waterfall for two successive Rx

images/Image_Rejection.png

At the start of the first interval the signal generator was set near the center of the WSPR band, producing the bright unmodulated carrier just above 200 Hz.

  • Adjust Rx phasing was checked at t = 10 s and unchecked at t = 50 s, by which time the Bal and Pha numbers had stabilized. * At t = 60 s, halfway through the 2-minute Rx interval, the signal generator was moved 27 kHz lower, to the image frequency. The partially suppressed image is visible on the waterfall just below 200 Hz. (The small frequency offset is twice the error in the SoftRock’s LO frequency setting.)

  • During the second Rx interval, the box Apply Rx phasing corrections was checked. As shown in the second waterfall segment, the newly determined phasing parameters suppress the unwanted signal enough to make it completely invisible. The measured suppression was more than 70 dB.

  • I-Q Phasing and balance parameters are saved and restored on a “per band” basis. Use button Save for this Band to save settings you have determined for the current band. You can make those settings the default for all bands by clicking Save for all bands.

8. Special Messages

Normal WSPR messages consist of a callsign, 4-digit grid locator, and power level in dBm. These messages are always preferred when appropriate. However, compound callsigns (i.e., callsigns with add-on prefix or suffix) cannot fit into the 28 bits allocated in a standard message. Similarly, 6-digit locators cannot fit into 15 bits. Messages using these components are therefore sent using a two-transmission sequence. For example, if the callsign is PJ4/K1ABC, the 6-digit grid locator is FK52UD, and the power level 37 dBm, the following messages will be sent in alternating transmissions:

PJ4/K1ABC 37
<PJ4/K1ABC> FK52UD 37

If you have special need to use a 6-digit locator with a normal callsign, check the box Force transmission of 6-digit locator on the Advanced setup screen. If the callsign is K1ABC, the 6-digit grid locator FN42AX, and the power level 37 dBm, the following messages will then be sent in alternating transmissions:

K1ABC FN42 37
<K1ABC> FN42AX 37

Callsigns enclosed in angle brackets are actually sent as 15-bit hash codes. If such a code is received by another station before the full callsign has been received, it will be displayed as <…> on the decoded text line. Once the full callsign has been received, the decoder will thereafter recognize the hash code and fill in the blanks. Two very different callsigns might have the same hash code, but the 15-bit hash-code length ensures that in practice such hashing collisions will be rare.

9. Band Hopping

WSPR 4.0 allows those with CAT-controlled radios to investigate propagation on many bands without user intervention.

  • Select Band Hopping on the Setup menu or type F9, and you’ll see the screen shown below. You can select any mix of active bands and Tx fractions. If you then check Band Hop in the main window, WSPR will switch bands randomly after each 2-minute interval. If the box labeled Tuneup is checked for a particular band, WSPR will transmit an unmodulated carrier for several seconds just after switching to that band and before the normal Rx or Tx period starts. This feature can be used to activate an automatic antenna tuner (ATU) to tune a multi-band antenna to the newly selected band. Check the box Coordinated hopping to enable sequential hopping through as many as ten bands, according to the schedule shown in the table below.

images/BandHopping.png

Coordinated hopping enables a sizable group of stations around the world to move together from band to band, thereby maximizing the chances of identifying open propagation paths.

Band (m)   160  80  60  40  30  20  17  15  12  10
UTC Minute  00  02  04  06  08  10  12  14  16  18
            20  22  24  26  28  30  32  34  36  38
            40  42  44  46  48  50  52  54  56  58

The band-selection schedule repeats starting at UTC minutes 20 and 40, for a total of three full ten-band sequences in each hour. If the designated band for a given time slot has not been checked as active, a random choice is made among the active bands. The algorithm for choosing whether to receive or transmit guarantees at least one transmission on each active band every two hours. If all ten bands are active, up to three transmissions may be made on a given band in a two hour period.

Depending on your station and antenna setup, band changes might require other switching besides retuning your radio. To make this possible in an automated way, whenever WSPR executes a successful band-change command to a CAT-controlled radio, it looks for a file named user_hardware.bat, user_hardware.cmd, user_hardware.exe, or user_hardware in the working directory. If one of these is found, WSPR tries to execute the command

user_hardware nnn

where nnn is the band-designation wavelength in meters. You will need to write your own program, script, or batch file to do the necessary switching at your station. I wrote a simple Python program for this purpose. One of my antennas is an all-band dipole fed with open-wire line through a 4:1 current balun and an automatic ATU. Other antennas include a shunt-fed tower for 160 m and a tri-band trap dipole for 20, 15, and 10 m. The desired antenna is selected automatically, by band. When the all-band dipole is selected, the ATU adjusts itself during the several seconds just before a transmission or reception period begins.

10. WSPR Command Line

Some special-purpose applications can benefit from a simple implementation of the WSPR protocol in a program driven from the command line. The standard WSPR 4.0 distribution includes a simple program WSPR0 for this purpose. As distributed, WSPR0 always uses the system default audio devices and it does not implement automatic uploading of spots, rig control, I/Q mode, or band hopping. The program runs in a single thread. Its source code is easy to modify as desired for particular applications. Full operational details are described in an accompanying document, WSPR0 Guide.

11. WSPRnet

To access the features of WSPRnet, point your browser to wsprnet.org. This excellent web site is designed and maintained by Bruce Walker, W1BW. It provides a chat facility, band-by-band counts of stations reporting or spotted in the past ten minutes, a world map showing active WSPR stations and open propagation paths, an interface to the historical database, and statistical summaries derived from the data. The map can be zoomed and panned, and you can set various criteria to determine what spots are shown. An example of the world-wide map is shown below: