PSK Reporter Python Plotter

This is a Python project that uses Matplotlib and Cartopy to map PSK Reporter signal reports over a global map. The script(s) use the PSK Reporter API to fetch data. The Data is returned in XML format. The script then parses the XML. The Maidenhead grid locator data is then converted to latitude and longitude and mapped onto a Robinson projection.

This only maps reception reports received by a given callsign, not reports of signals sent by you, although I may add this in the future.

Purpose

This is for amateur radio (ham) operators that use any of the WJST modes (ie FT8, FT4) or any other mode that is tracked by PSK Reporter. While PSK Reporter has a great interactive map to track signal reports, I wanted to create static maps of signals received over a given time period, in my case 5 minutes. Each time period is then plotted to a PNG file. The PNG files can then be animated by ffmpeg or some other software so that band propagation can be viwed over time.

Requirements:

• Any Linux flavor should work or Windows WSL Ubuntu
  • You may be able to run this directly in Windows but you may have to heavily edit the code to support Windows style file paths
• Python 3.11.1 or newer
• Various libraries, listed in requirements.txt
  • Install by running: pip install -r requirements.txt

Usage:

There are four versions of these scripts for different methods of usage. Make sure you put your callsign and Maidenhead locator in the pskrfunctions.py file before using these scripts

• pskr-plot-singlerun.py

This version fetches data directly from PSK Reporter's API and parses the data for mapping, and outputs the plot to the plots directory. This only runs a single time and bypasses the XML file creation step. Please respect the API fetching limits of 5 minutes.

• pskr-plot-xmldata.py

This version ingests XML files located in the pskr-xmldata directory one at a time, and outputs one PNG file in the plots directory for each XML file

• pskr-plot-xmldata-all.py

This is basically the same as the script above except it outputs ONE PNG file for all the XML files in the pskr-xmldata directory

• pskr-plot-continuous.py

Future addition

This script runs until you interrupt it with CTRL+C or a kill signal of some kind. The script will fetch data from the PSKR API and generate a PNG file in the plots directory for as long as it is running. This method does not use XML files generated by the pskr-plot-retrievedata.sh helper script.

Helper Scripts:

• pskr-plot-retrievedata.sh

This script is meant to be run as a cronjob. It will fetch reception reports from PSK Reporter and output the result to a XML file with a timestamp in the file name. XML files are saved in teh directory pskr-xmldata

• pskr-plot-animatepngs.sh (requires ffmpeg or ImageMagick)

This script animates all PNG files found in the plots directory to an animated GIF file. You can output to another type of file like mp4 or mkv but will require some modifying. Uncomment the method you would like to use before invoking the script.

Usage:

sh pskr-plot-animatepngs.sh

-OR-

chmod u+x pskr-plot-animatepngs.sh (only need to run this command once)

then

./pskr-plot-animatepngs.sh

NOTE:

PSK Reporter is kind enough to allow access to their reporting data via API. They do ask that you do not fetch data more than every 5 minutes. Doing so will at the least result in 403 Forbidden errors, and may even result in an IP ban.

Personal Note:

I developed this to plot my own signal reception reports mainly to animate and see how band conditions change over time. I am sure there are other, better solutions for this out there. I am not a professional coder, more of a hobyist but I am releasing this in case it is helpful to anyone else. I know the code is messy, but please feel free to add any features or modifications and submit a pull request.

Todo:

• Separate all reused functions across the scripts into a single file and use an import. (Started)
• Finish documenting code.
• Clean up code.
• Finish pskr-plot-continuous.py
• Add support or start a new project to use interactive maps.

Credits:

• Philip Gladstone - N1DQ

Creator and main maintainer of PSK Reporter and its API.

• Joe Taylor (K1JT) et al.

Creator(s) and maintainers of WSJT and WSJT-X. While this script isn't specifically limited to the WSJT modes (FT8, FT4, etc.) this was my main focus for the script.

• The matplotlib team.
• The Cartopy team.

License:

MIT License. I don't care what you do with this, but please do include attribution.

MIT License

Copyright (c) 2025 Jason Jasper - KE7BUA

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.