Back to WSPR Matrix

User Guide

Prototype v2026.07.21

Basic Workflow

1. Open WSPR Matrix.
2. Enter the reporter callsign, UTC date, and local UTC offset if local time is wanted beside UTC.
3. Choose Path 1 and Path 2 destination areas using continent, city, and radius, or use Map grids in Map Setup.
4. Select the live data server if live data will be used.
5. Select up to 18 bands in the fixed toolbar.
6. Press Go! to collect live data and build the matrix, or press Load to build from one or more saved data files.
7. Use the Close setup button to hide the setup panel.
8. Choose the counting mode: Raw Spots, Unique Beacons Per Bin, or Cumulative Unique Beacons.
9. Use Save if you want to keep the collected JSON data for later review.
10. Select Path Matrix to view beacons heard from both selected paths, or select Global Matrix to view all-beacons-heard from all continents.
11. Use Export CSV or Print / PDF for reports.

Fixed Toolbar

The fixed toolbar stays available while the matrix is being reviewed. It contains the high-use controls so the user does not need to scroll back to the top of the page.

• Go! collects live data for the entered callsign and UTC date, then rebuilds the matrix. If saved data has already been loaded, Go! rebuilds from the loaded data.
• Save saves the current collected data as a JSON file.
• Load opens saved JSON, CSV, HTML, or WSPRnet-style data files and builds the matrix. Multiple files can be selected together.
• Clear clears the current matrix and collection state.
• Counting cycles through Raw Spots, Unique Beacons Per Bin, and Cumulative Unique Beacons.
• Open setup and Close setup are the action labels on the green setup button. Open setup shows the callsign, date, and destination setup panel. Close setup hides the panel and moves the matrix to its home position below the fixed toolbar.
• Band buttons show the bands returned from the server or from a loaded file. Band buttons can be deselected and re-selected.
• Live data server selects the ClickHouse-compatible live source used by Go!.
• Diagnostics opens details about live data requests and failures.
• Export CSV saves the current matrix as a CSV file.
• Print / PDF opens the browser print flow for paper or PDF output.
• Row height changes matrix row spacing. This setting is useful when aligning two browser windows side by side.
• Destination mode switches between City radius and Map grids.
• Path radius controls adjust the endpoint radius for each selected path area when City radius mode is used.
• Path Matrix jumps directly to the selected-path matrix.
• Global Matrix jumps directly to the all-beacons-heard matrix.
• User Guide opens the landing page, where the User Guide and other project pages are available.

Path Matrix and Global Matrix

Path matrix: the first matrix is filtered by the selected Path 1 and Path 2 destination areas. The active Destination mode decides how each path area is defined.

Global matrix: the second matrix shows every beacon heard by the reporter callsign in the loaded or collected data. It is not filtered by Path 1 or Path 2.

Both matrices use the same toolbar counting mode and selected band buttons.

Map Setup

Map Setup provides a visual way to define Path 1 and Path 2 destination areas. The maps show two-letter Maidenhead fields, city labels, and a light world outline. Click a field to select it; click it again to remove it. Use Select All when a path should include every two-letter field, or Clear to remove map-grid selections for that path.

City radius mode: the app uses the selected continent, city, and radius. A beacon is counted for a path when its grid is within the selected radius from that city. The map also shades the two-letter Maidenhead fields whose field centres fall within the selected radius, giving a visual indication of destination coverage.

Map grids mode: the app uses the selected two-letter Maidenhead fields on the maps. A beacon is counted for a path when the first two letters of its grid match a selected field. City and radius selections are not used in this mode.

One selected map grid on only one path is valid. If Map grids mode is selected and no grids are selected on either path, the app prompts the user to select grids before loading or collecting data.

Counting Modes

Raw Spots counts every imported or collected report row.

Unique Beacons Per Bin counts each beacon callsign once within each 30-minute band/destination cell.

Cumulative Unique Beacons counts each beacon callsign once across the UTC day and shows the running total by time bin.

Using Saved Data

Use Load to import saved data and build the matrix.

Saved data can be collected JSON from this app or compatible WSPRnet-style files. When several files are selected together, exact duplicate rows are removed automatically.

Important Notes

• JSON data should contain headers and rows, or an array of spot objects with reporter, date, band/frequency, grid, and callsign fields.
• Blank cells mean no matching observed reports in the imported or collected data, not proof that propagation was closed.
• Endpoint radius controls which beacon grids are included in each path area when City radius mode is used. The shaded radius fields on the map are a visual guide to this same destination area.
• Two-letter Maidenhead fields are broad 20 degree longitude by 10 degree latitude areas. In Map grids mode, selected fields define the destination area directly.
• SNR is deliberately not used by WSPR Matrix.