JJJJJ SSS 888 M M AAA PPP PPP EEEEE RRR 4 22
J S 8 8 MM MM A A P P P P E R R 44 2 2
J SSS 888 M MM M AAAAA PPP PPP EEE RRR 4444 2
J J S 8 8 M M A A P P E R R v v 4 2
JJJ SSS 888 M M A A P P EEEEE R R v 4 . 2222
/************************************************************************
js8mapper - maps stations by their grid data from JS8CALL
Copyright (C) 2024,2025 TCJC
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
<https://www.gnu.org/licenses/>.
*************************************************************************/
js8mapper provides a very lightweight filtering option for the JS8 protocol.
The JS8CALL software is required for js8mapper to work.
ALL MAPS IN THIS APP COURTESY OF: "OpenStreetMap contributors" !!!
New features added with js8mapper 4.2:
1. Tracks grids for those who stations that are grid collectors.
2. Has a new Grid oriented map. Keeps track of grids with which you
have had a QSO. Tracks the last time you have "heard" the other grids.
3. Alerts can be configured to spot grids, callsigns, countries/DX entity,
continents, and match patterns in the text of JS8.
4. Alerts can be paused while you review them in alert window.
5. Allows for different rulesets per band
6. Rules editor for simple rule construction.
7. Recalls settings of previous session.
8. Information window can be changed to left or right margin (In settings).
9. Mark feature removed since the rulesets are much better for tracking
callsigns.
10. Grid examiner allows you to look at grids on World Map or Continent
maps so you can see which grids you are missing, which ones you've
heard, which ones you have QSO'd with.
============
REQUIREMENTS
============
- PYTHON3 -- You MUST have python 3.6 at a minimum.
IMPORTANT NOTE FOR MacOS MONTEREY (12.x or LATER): you MUST run python 3.10
or later.
*** Please see note below under INSTALL section for a brief explanation of
Apple's problem cause by shipping incompatible versions of Python with
their OS release.
The script requires Python 3 that supports Tkinter. The Mac version of
Python 3 may require an upgrade as the Mac version has a deprecated Tkinter.
"Brew" may be used to upgrade python, do so at your own risk or run
deprecated version.
To install tkinter if you don't have the module, enter this at a terminal
or cmd prompt:
pip3 install tk
-- or --
pip install tk
=====
FILES
=====
config.txt - holds settings
csalerts.bin - generated after first use, holds callsign alert data
dxccalerts.bin - generated after 1st use, holds country alert data
js8mapper.py - the application script, run this
grid1.db - sqlite database that holds grid data, generated
gridalerts.bin - generated after 1st use, holds grid alert data
mapwcfgX.bin - generated after 1st use, holds map/window data
msgalerts.bin - generated after first use, holds message alert data
README.txt - help file
stationX.bin - generated after first use, holds station data
wm-af.png - Africa map
wm-as.png - Asia map
wm-eu.png - Europe map
wm-na.png - North America map
wm-oc.png - Oceania map
wm-sa.png - South America map
wm.png - World map
If config.txt is corrupt, shutdown app, delete file and restart. Go to
"Settings", leave the defaults and click "Save". This will write a new
config.txt file.
If grid data becomes corrupt, shutdown app and delete grid1.db.
If map/window settings are corrupt, shutdown app and delete mapwcfgX.bin
If station data becomes corrupt, shutdown app and delete stationX.bin
If any alert rules become corrupt delete corresponding .bin file
All of these files are generated at first run of application. Deleting
file and restarting application generates new files.
If application appears corrupted, re-download.
=============
INSTALL & RUN
=============
Download js8mapper.zip and unzip its contents into one directory. The
actual directory does not matter.
Run the Python script js8mapper.py. You may need to change the first
line of the script to point to the path of your Python 3.x interpreter.
You can also run from a command line: python js8mapper.py
On some systems this may be: python3 js8mapper.py
Run JS8CALL, making sure that on the "Reporting" tab that
"Accept UDP Requests" is checked.
Make sure UDP server port is set to 2242.
Read the "HOW TO USE" section below for useful info...
===============================
RUNNING TKINTER PYTHON ON A MAC
===============================
There is an odd behavior on Macs with certain newer OS versions
(12.x Monterey and later) and certain versions of Python (3.9.x and earlier).
If you experience blank or flickering in js8mapper then you have a bad
combination of Python and MacOS.
This is because MacOS ships an old version of Python (3.9 or earlier) that
seems incompatible with changes in MacOS Monterey 12.x.
To resolve this bug be sure to run at least Python3.10 or later. Please
install this in the location "/usr/local/bin/python3". Then edit the
first line of the python script to "#!/usr/local/bin/python3" (no quotes).
There is only 1 script. This ensures that the old version of Python
stored in "/Library..." is NOT used by js8mapper.
==========
HOW TO USE
==========
Launch the program.
The World Map should open with a number of buttons under it.
At the top of the main window you will see buttons representing the ham
radio bands of 160 meters - 2 meters. These buttons do NOT change your radio
settings, JS8CALL handles that. These buttons act as filters showing stations
that you have heard within the last 24-hours on the various bands. The band
colors and the time pulldown were chosen to match with PSK-Reporter for
consistency. To see current activity please select the band that the radio
is listening to. To review stations you have heard previously on different
bands you can select that band and js8mapper will show stations associated
with that band. If you use different modes, be sure to choose the mode from
the pulldown to see different modes as well.
At the bottom of the map are a series of buttons that control the program.
The first 3 columns of buttons are the map controls. They control opening
the continent views and the World Map. Clicking on them will change the view.
The 4th column of buttons are pulldowns. The top pulldown controls the
time limit of the stations being displayed, with 24 hours worth of
stations being the default. The time you select ensures that only stations
that have been captured within that time frame are shown.
The 2nd pulldown selects which website to use for callsign lookup. It
defaults to QRZ.com, with HamCall also being available.
The 5th column of buttons controls the alert rules and the alert window.
The top button opens an alert window which will be empty if no stations
matching the alerts have been heard and it will also be empty if no alert
rules have been programmed. Clicking this button when alert window is open
closes it. The "Active Alert Rules" button shows you the rules that are
currently active for the band and mode you are currently listening to.
The "Config Alert Rules" button allows you to configure the alerts the way
the user wants them.
The 6th column has the "Station Map" button which shows the station map which
comes up by default when the app is launched. As stations are heard in
JS8CALL they are mapped by the maidenhead locator that they are advertising.
Underneath the "station map" button is the "Settings" button. The settings
allow you to configure the port and IP address you wish to listen to for
JS8CALL. The "Info Window" can be set here to show up on the right or left
of the screen. The right-side is the default, although Asian users would
likely want the left-side so the window does not cover Asia. There is a
setting which shows "QSO's only" on the grid map to cut down on the number
of grids displayed. This is off by default. There is also a setting for the
"Last heard number of days". This setting limits the number of days that a
"last heard" grid is displayed. For example if this is set to 5, then only
the last 5 days worth of grids heard will be displayed. Again, this is to
limit clutter on the grid map. It is 0 (zero) by default meaning that every
grid heard will be marked as such on the grid map.
The 7th column of buttons contains "Grid Map". This changes the map display
from "stations" to "grids". All grids that have been heard are mapped by
default in the band color on which they were heard (band selection will be
explained shortly) and the grids with which you have had a QSO is marked
in a different color.
Below "Grid Map" is the "Clear" button. This deletes all stations from
the station map and clears their content from the "Info" window. Use with
caution as this is not recoverable. It does NOT clear the grid map. Since
the grid map is there to show you when you have last heard a grid, or which
grids you have QSO's with it is not effected by the "Clear" button by design.
Grid data is stored in a database.
The last column of buttons is "Info". The Info button allows the user to
review station data in a real-time updated listing that is pre-sorted with
each pass of the JS8CALL decoder. Clicking "Info" a second time closes
the Info window.
Lastly, there is the "Quit" button which saves windows settings, etc. and
closes the app.
===========
STATION MAP
===========
When first launched the "World Map" appears in station mode. As stations
are heard in JS8CALL they are mapped according to the grid locator they are
advertising. If a station does not give a maidenhead locator then they will
not be mapped. A 4-letter grid locator must be given for mapping to occur.
Stations appear as a circle and when clicked they will open the web browser
and take you to a callsign lookup site.
When hovered over you get a station information window showing the station's
callsign, country (dx), grid, band/frequency, offset from the frequency,
the SNR, time heard, mode and the last message the station sent.
If multiple stations are advertising the same grid, a triangle will appear
instead of a circle. Hovering over a triangle lists the stations heard from
this grid and clicking on the triangle opens a station information window
that the user can scroll reviewing all of the station's information, similar
to hovering over a station shown as a circle.
The outer edges of the map show the grid locator letters.
Note: stations are mapped in the center of the maidenhead locator they are
advertising. This may make a station appear floating in the middle of a lake
or offshore when located next to an ocean. 6-character locations would be
required to solve this problem. The best you can do with 4-characters and no
internet connection to lookup further information is to place the station in
the middle of the grid. This does distort station locations somewhat.
========
GRID MAP
========
If the "Grid Map" button is clicked, then the map displays rectangles the size
and shape of the maidenhead locator at that position. The grids shown are the
grids of stations that are advertising their grid locators.
Hovering over a grid gives the user its 4-character maidenhead locator, the
band it was heard on, the country represented (dx), the callsign of the
station and the time it was last heard and the mode being used at the time.
Clicking on a grid opens a grid report and highlights the grid with red cross
lines showing the location of the 100 sub-grids that make up the 4-character
maidenhead locator.
A grid report window opens and gives a 100 line report showing which grids
have been heard, which ones have been QSO'd with and those that have never
been heard.
This window can shuffle from left to right if it is blocking part of the
map the user wishes to view.
If a regional map is selected and a grid is clicked the user not only gets
the grid report but they can also hover over the map and see the grids for
which they have not received any communications. These grid names appear as
small yellow tags with their 4-character grid name in them such as "JN53".
Note: the further the grids get from the equator the larger they are as a
mercator map distorts the latitude of the map.
====
INFO
====
When the user clicks on the "Info" button it opens a window on the right side
of the main window (or left if chosen in "settings"). This window has
4 sub-functions labeled C, G, M, and T.
"C" - shows callsigns sorted alphabetically, their mode, grid and the band
"G" - shows stations listed alphabetically by their grid. All other info is
same as "C".
"M" - shows callsigns sorted alphabetically and the last message that
JS8CALL recorded from this station.
"T" - shows stations sorted by the latest time sequence, so the most
recently heard stations are at the top.
If a different time is selected in the time pulldown the "Info" window
corresponds by only showing station data heard within that time limit.
Clicking "Info" a second time closes the Info window. Info is useful for
seeing all the activity in the current band, and by selecting different bands
from the filters at the top of the map window, other band data can be seen
if the radio was used on that band to collect data. Reminder: all station
data expires at 24 hours.
======
ALERTS
======
To start using alerts the user has to have some rules configured.
Click "Config Alert Rules".
A "band plan" will appear, by default the band and mode should reflect the
setting of the radio. Select a different band or mode if desired.
Clicking "Edit Plan" will present the user with 5 types of alerts that
can be programmed.
1. Grid Rules
2. Callsign Rules
3. Country/DXCC Rules
4. Continent Rules
5. Message Rules
==========
GRID RULES
==========
Grid Rules are rules that alert when a particular grid is heard. When clicked
a window will open where "Add Entry" button is seen. Clicking this button
allows the user to add an entry which must be at least 1 character long and a
maximum of 4-characters in length. The entry must follow the format of a
maidenhead locator: the first 2 characters being alphabetic from A to R and
the last two being numeric, 0 to 9. "J" will give you every grid heard that
starts with "J". "JN" will return every grid starting with "JN", "JN2" and
"JN20" work accordingly. Care should be taken to be fairly specific in the
grid the user is looking for so that alert output is not overly busy.
To delete an entry, the minus sign (-) next to it can be clicked, clicking
plus (+) re-adds the entry. "Save" must be clicked to save the changes and
"Cancel" closes the window with no changes being made.
==============
CALLSIGN RULES
==============
Callsign rules work somewhat differently. A callsign added as an entry is
assumed to be the full callsign. "AB2CD" will only match that specific callsign
and no other callsign. A wildcard may be used but ONLY at the end of the
callsign. Suppose the user wants all stations beginning with "XE", then they
should add "XE*" as an entry. All station callsigns starting with "XE" will
now generate an alert. If the user decides they want to delete an entry they
can click the minus sign (-) next to the entry and it will highlight in red,
indicating that it has been deleted. Clicking plus (+) re-adds it. "Save"
must be clicked to save any changes and "Cancel" leaves the menu without
making any of the changes.
==================
COUNTRY/DXCC RULES
==================
Country/DXCC Rules are rules created by selecting the callsign prefix or
country for which the user wants to be alerted. When clicking Country/DXCC
button the user is presented with a menu showing buttons representing the
continents. By clicking on one of these buttons the user is presented with a
list of DX entities (countries) that belong in that region. Multiple DX entity
can be selected and the other continent buttons and be clicked to select
countries in other regions as well. When done the user must click "Save".
If the user does not want to save the changes "Cancel" should be clicked.
===============
CONTINENT RULES
===============
Continent Rules opens a window where multiple continents can be selected.
Any callsigns heard from the selected continent will produce an alert. Care
should be taken to not select too many continents to control the number of
alerts that are received. "Save" will keep these changes and "Cancel" will
exit this menu without saving any changes.
=============
MESSAGE RULES
=============
Message Rules do simple pattern matches and do not support wildcards.
Adding an entry of "SOTA" (without quotes) will alert on any station message
that contains the string SOTA. This can be used to spot CQ, 73, POTA, SOTA,
IOTA, etc. "Save" stores the changes whereas "Cancel" exits without saving
changes.
======
REVIEW
======
Once a plan has been saved the user can click the "Review" button back at the
main "Band Plan" menu. This will show a window containing all the effective
rules contained in that band plan. This allows the user to check which rules
have been applied.
"Close" will close the band plan window and return to the map.
==================
ACTIVE ALERT RULES
==================
The "Active Alert Rules" button allows a rule review similar to the review
button in the "Config Alert Rules" menu.
============
ALERT WINDOW
============
If rules are set and the alert window is not open, a red warning sign will
appear in the upper right hand corner of the map window stating there are
"ALERTS !!!". Clicking the "Alert Window" button eliminates this red flag
and opens the alert window which shows the alert rules that have been
matched. The window scrolls as alerts are added and shows a timestamp
indicating when the alert was triggered.
If the Alert window is blocking your view you can click the
"Move" button on the window to shuffle it to the opposite side of the window.
===================
BAND FILTER BUTTONS
===================
The band filtering buttons are located at the top of the map. The band that is chosen (such as "40") only stations in that band are shown.
The band filter buttons also filter output in the "Message", "Time", "Call"
and "Grid" windows when they are open. Output in this window is restricted
to the band that has been chosen.
The "Clear" button is also affected by Band filter buttons. The band that is selected determines which stations will be deleted when "Clear" is clicked.
========================================================
Please drop us an email, we value your feedback, thanks!
========================================================
Download Latest Version
js8mapper4-beta.zip (4.6 MB)
