FFFF IIIII L TTTTT 888 3333 666
F I L T 8 8 3 6
FFFF I L T 888 v v 33 6666
F I L T 8 8 v v 3 6 6
F IIIII LLLL T 888 v 3333 .. 666
/*************************************************************************************
Filt8 - a filter for QSO output from WSJT-X
Copyright (C) 2023 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/>.
*************************************************************************************/
WARNING WARNING WARNING
If you are a filt8 version 1.x or 2.x user, the config file is not compatible with v3.x.
Most of the *.py files are substantial rewrites and additions. Install all new.
The filter files are updated due to prefix changes as well.
!!! Please use a fresh install of all files. !!!
-------------------------------------------------
Filt8 provides a very lightweight filtering option for the WSJT-X FT8 protocol.
The WSJT-X software is required for filt8 to work. "filt8" has been tested with
WSJT-X 2.7.1rc on Mac with Ventura (v13.x) and Windows 10. It works in Debian Linux
and should work with other Linux but is not tested. (Let us know!)
I wrote this because JTAlert is not on Macs and GridTracker is too much for my
older slow Mac. I needed something light for a QRP field trip... here it is.
=============
REQUIREMENTS:
=============
- PYTHON3 -- You MUST have python 3.
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 scripts require 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
For audio announcements to work on Windows and Linux the "pygame" library
must be installed. To install pygame if you don't have the module, enter
this at a terminal or cmd prompt:
pip3 install pygame
-- or --
pip install pygame
If you don't need audio announcements, you do not need pygame. Just disable audio
announcements in the setup.py program.
======
FILES:
======
Files for "filt8" are stored on SourceForge as follows:
1. filt8.zip = contains configs, sound files, scripts, state callsign data
(YOU ONLY NEED this file to run filt8 program)
2. statecallsigns.txt = in case you want to update state data without replacing
the script code.
3. usterritory.txt = used when States are switched on. Provides better mapping
of callsigns to U.S. Territories of American Samoa, Guam, Mariana Is, Puerto Rico
and Virgin Is. Unfortunately this is needed as there is inconsistent allocation
of callsigns across USA and US Territories reuiring these extra mappings for
accuracy.
4. READMEfilt8.txt = (you are reading it now)
========
INSTALL:
========
Download filt8.zip and unzip into one directory. The actual directory
does not matter, but you MUST have write access as Filt8 has to update
configuration files and write temporary files for history viewing.
This software assumes you have Python 3.x installed and that Python
must contain the Tkinter module. setup.py will check for this.
Run:
"python setup.py"
sometimes the binary for python is named python3:
"python3 setup.py"
setup.py will figure out if the python you are running is acceptable and will
create startup files.
To start filt8:
./startfilt8.sh - on a Mac OS or Linux system
./startfilt8.bat - Windows
To start filt8freq which is a horizontal frequency based waterfall style, try:
./startfreq8.sh - on a Mac OS or Linux system
./startfreq8.bat - Windows
================================
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 "edit filter", "edit colors" or "history"
windows in Filt8 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 Pyton3.10 or later. Please install this
in the location "/usr/local/bin/python3". Then edit the first line of each python
script to "#!/usr/local/bin/python3" (no quotes). There are only 3 scripts.
This ensures that the old version of Python stored in "/Library..." is NOT used
by Filt8.
================================
There are 6 scripts:
-----------------------------------------------------------
setup.py - Allows you to setup various filt8 parameters:
My recommendation is to set the "Path to WSJT-X" and "My Callsign".
then "Save & Quit".
- Path to WSJT-X directory is where the ADIF file is stored. This is so
it can read the ADIF for the "worked before" feature
- Full Path to Python binary
This may be unnecessary to use this if Python is in your PATH. But on MacOS
(as mentioned above) it ships with a version of Python that does not work
MacOS 12.x and above, and if you execute their broken version of Python
the Tkinter windows will be blank and flicker. If this occurs, please
install a version of Python 3.10 or greater, and then set this path to
point to that executable, preferably /usr/local/bin/python3, but you can
set this variable to point to your installation.
This is not a problem on Windows, and if python3 is in your path
(usually the executable is called PY.EXE), then this setting likely is not
needed.
- Set your callsign so it is highlighted when someone calls you.
Leave the other settings alone till you run the program,
otherwise you will not understand the impact of these settings.
The following 4 lines only apply to filt8 window, they do not impact filt8freq.py
- number of columns in display (default: 3)
- number of rows for CQs (default: 12)
- number of rows for 73s (default: 6)
- number of rows for In-progress QSOs (default: 16)
- IP address: - don't change (default 127.0.0.1)
- Port #: don't change unless you are running other software talking
to WSJT-X such as a logger (default: 2237)
- MAPPort #: don't change. This port is used by filt8 to talk to filt8map
Only change if there is a conflict with software on your system. (default: 2230)
- Show if you QSO'd callsign before: (default: checked)
filt8 does this by reading the entire ADIF file from WSJT-X
This can cause a very....very... slow startup if the file is huge.
You've been warned. This will display (B4) after a call that you
have QSO'd before. Shut it off if you don't care... or shut it off
if startup is just too slow.
- Ability to show/filter U.S.A states: (default: checked)
filt8 does this by reading an ~8M+ file of every callsign the FCC
knows in the USA. If you don't care, shut it off. It is another
potential slow down, but if you want to highlight specific states
such as when pursuing Worked All States (WAS) then it is necessary.
- Show 73s: (default: checked)
filt8 categorizes QSOs in 3 buckets... those calling CQ, those
sending 73s and those that are somewhere in between (in-progress)
If you are just overwhelmed with the volume of data you have the
option to shut off 73's. I find it useful to know when someone is
finishing up so I can call them!
- Show In-progress QSOs: (default: checked)
filt8 categorizes QSOs in 3 buckets... those calling CQ, those
sending 73s and those that are somewhere in between (in-progress)
If you are just overwhelmed with the volume of data you have the
option to shut off the in-progress (which is usually the LARGEST
bucket by far!!)
- Audio Announcements?: (default: checked)
Will announce any of your highlights that are triggered with one
of two announcements. "DX!" for a country or "STATE!" if U.S. state.
- QSO History?: (default: checked)
Filt8 stores away up to 12,000 QSO records (about an hour's worth
at busy times). You can then launch the history viewer and search
through the QSOs. A MUCH better option than trying to stop "Monitor"
on WSJT-X and scroll back through them!
"Save & Quit" saves your changes.... "Quit" makes no changes.
-----------------------------------------------------------
filt8.py - starts the highlight, filter window (for a horizontal view of waterfall
try filt8freq.py instead!)
Provided you have a working copy of WSJT-X, you should now be able to run
"filt8", provided you ran setup.py.
This app is the reason you downloaded the package. But you've done all the
difficult settings above (which really weren't that difficult).
The window is separated into 3 buckets. CQ,s, 73's, In-progress QSOs.
The app automatically sorts these for you. You can double-click on a CQ
(it has to be a CQ) and filt8 will instruct WSJT-X to start a reply to
the calling station. Refer to the WSJT-X app to watch the progress of your
QSO... be sure you have selected an open frequency in the WSJT-X waterfall.
There are 8 buttons at the bottom of the window.
----
"Halt Transmit" - tells WSJT-X to stop transmitting immediately if it was
transmitting.
----
"Country Heard" - this button shows a report of the countries and states
heard, how many times they were heard, and the time they were last heard.
----
"Grid Heard" - this button shows a report of the grids heard, how many
times they were heard, the time they were last heard, what band they
were heard on, and which callsign activated the grid square.
----
"History" - launches the history viewer, provided you enabled QSO History.
This report shows time, SNR, band, frequency offset, mode, message sent,
and the country/state from which it was sent. There is a text search box
that allows you to search on any of the data.
----
"Halt Transmit" - tells WSJT-X to stop transmitting immediately if it was
transmitting.
----
"Audio On/Muted" - tap this button to toggle audio announcements on and off.
Audio must be enabled for this button to work. If audio module fails to load
this button may say that Audio is Disabled.
----
"Map" - launches our map feature.
This map does NOT use a database and does NOT require Internet access
except for the "Lookup" feature which accesses the internet, but is NOT
needed for normal operation.
Mapping is real-time based on QSOs that contain a 4 character Maidenhead
Locator. The map has controls in the bottom left hand to launch regional
views for details and a world map as the main screen.
The colors of the dots resemble PSKReporter colors for the different
bands. The ONLY stations that show on this map are stations YOUR radio is
receiving, and as it only uses 4 character Maidenhead locators, it puts the
dot on the map in the center of that Maidenhead locator, so there is some
small degree of error in placement.
This is great for QRP and "OTA" operators that want to see a quick map of
stations that they can hear, but they do not have an Internet connection.
Just click on different region buttons in lower left hand corner to see
different maps. Hover over a dot and get the callsign, grid, SNR, and
band information for that operator! Clicking on this will do a "lookup"
on either QRZ or HamCall depending on the radio button selecion at bottom
of window. This is the one feature that DOES require Internet access.
Let us know what you think.
Across the top of the map you will see buttons corresponding to the HF
bands. Clicking on these will filter the stations so only those matching
the filter will be shown. CLicking on "ALL" shows all bands.
Lastly, the callsigns can be shown listed in alphabetical order by
clicking on "List by Call" or the grids can be shown in alphabetical
order by clicking on "List by Grid". The window is scrollable and can
be closed independent of the map (usually by clicking the "X" button
at the top of this windows frame).
----
"-->" - takes you to the second menu
----
"Quit" - shuts down filt8. Filt8 will also shut down if WSJT-X is quit.
----
THESE MENU ITEMS APPEAR ON THE SECOND MENU. CLICK "-->" TO ACCESS.
"Edit Colors" - launches filt8colors.py which configures the color scheme
for the different types of highlights. More details are below
under filt8color.py.
----
"Edit Filters" - launches filt8filter.py which configures filters. More
details on filtering under the filt8filter.py section below.
----
"Clear History" - zeros the history logging. Max history is 12,000 entries
but you can clear it if you are stepping away for 10 minutes and want to
come back and see what happened, without looking at 12,000 entries. :-D
----
"Clear Country" - clears info stored for country report.
----
"Clear Grid" - clears info stored for grid report.
----
"Clear History" - zeros the history logging. Max history is 12,000 entries
but you can clear it if you are stepping away for 10 minutes and want to
come back and see what happened, without looking at 12,000 entries. :-D
----
"Reload Fltr/Clr" - re-loads the filter and color settings updating
them if they were changed. This is useful when you have changed a filter
or a color, you do NOT need to restart the whole app. *** Setup features
such as changing rows and column sizes, "Worked B4", enabling audio,
changing callsign, etc. do require filt8.py to be restarted.
----
"Edit Colors" - launches filt8colors.py which configures the color scheme
for the different types of highlights. More details are below
under filt8color.py.
----
"Edit Filters" - launches filt8filter.py which configures filters. More
details on filtering under the filt8filter.py section below.
----
"<--" - Takes you back to first menu.
----
"Quit" - shuts down filt8. Filt8 will also shut down if WSJT-X is quit.
----
The documentation below is IMPORTANT... BUT...
YOU DO NOT NEED TO RUN ANY OF THE PROGRAMS BELOW SEPARATE FROM FILT8.
All the programs below launch from buttons at the bottom of filt8's
main screen.
-----------------------------------------------------------
"Edit Colors" button in Filt8.
Allows you to setup the color scheme for filt8
You do NOT need to run this program separately. It can be run from
the "Edit Colors" button in "filt8".
My recommendation is don't change the colors till you have ran filt8.
Once you know how it looks you will know how the app uses colors.
Otherwise, you will have no idea what you are changing.
Filt8 allows you to configure different colors for the following:
CQ's, 73's, In-progress QSOs, Highlights, Your Callsign, a watchlist
of callsigns and a list of grids (watchlist and grids are configured
in the filt8filter app).
The first 3 (CQ's, 73's, In-progress QSOs) are the QSOs that filt8
sorts for you, so the color may not be as important. What you really
want are your Highlights, "My Call", and any watchlist or grids.
"My Call" is the color of your callsign when a message that contains
your callsign is received.
Highlights are anything that you have marked in a filter as requiring
a highlight. You can use different colors for different highlights,
regular highlights can be different from watchlist and grid items.
The top half of the screen is background color, the bottom half is
text color. Each time you change a color a sample button at the bottom
of the window shows you what it will look like.
If you like your choices click "Save" and all is saved. If you "Quit"
no changes will be saved.
-----------------------------------------------------------
"Edit Filters" button in Filt8.
Allows you to edit filters.
You do NOT need to run this program separately. It can be run from
the "Edit Filters" button in "filt8".
filt8filter.py allows you to edit filters so you can highlight countries,
states, or regions of interest. This does NOT affect WSJT-X output.
WSJT-X will continue to receive everything. These options just allow
you to highlight or filter out regions, countries, and states from filt8's
window so you can narrow results.
Across the top of the "REGIONAL SELECTION" screen are the 6 regional buttons
and a "USA States" button. Clicking these buttons allows you to edit the
filters for the regions or the USA States. More on that in a minute.
CALLSIGN WATCHLIST
------------------
Under the regional buttons is a callsign watchlist of 7 boxes.
In these boes you can put a string you would like to match against
callsigns. An example is you could put W1AW in this box and it will
highlight this callsign if spotted in WSJT-X. The pattern is always
assumed to match from the beginning of the callsign.
Example: "W1" will match "W1AW", but will not match "AW1A"
There is one special character you can put in the callsign watchlist
and that is a dollar sign at the end of the search string. This forces
the match to the end of the callsign instead of the beginning. This
could be useful if you wanted to watch for callsigns using a postfix.
Example: "/QRP$" will match "W1AW/QRP".
GRID WATCHLIST
--------------
Under callsign watchlist is the grid watchlist. Any character or number
placed in these boxes tries to match the grid fields as displayed in
WSJT-X.
Ex: "EM52" will match grid "EM52".
Ex: "EM" will match any grid containing "EM" such as "EM01", "EM99", etc
Ex: "20" will match any grid containing "20" such as "FN20", "EM20", etc
"Save" will save the changes you have made, choosing "Quit" simply quits
the program so be sure to click "Save" first.
REGIONAL FILTERING
------------------
CAUTION: This looks very messy at first, but easy to understand once you
look at it for a minute. Trust me, it is the MOST complex of all the apps
and after you've used it the rest of "filt8" is EASY. :-D
When you click a regional button you will see the 11 amateur bands.
The first row under the bands is labeled "TEMPLATE -->"
There is a column of pulldowns under each band and on the left hand side
the countries for the region are listed along with a checkbox next to the
name.
The 4 options in the pulldowns are:
Normal - this is the default, there wil be no highlights.
Highlight - select this for color highlighting anything in the region
Audio+HL - provided you have loaded the Python pygame module on
Windows and Linux (MacOS uses "afplay" which comes with the OS) and
enabled audio, then you will get an audio alert along with the
Highlight color.
QRM - QRM is an amateur radio Q-code meaning noise/interference.
Selecting this option will filter out a whole region you don't want
to see.
The easiest way to set your filters is to select the option for each band
in the "TEMPLATE" row. Then go down the left-hand column clicking the
checkbox next to the country you would like to apply these settings to.
If you want ALL countries in the region to have these options then click
"Select All -->" checkbox.
Now go to the bottom of the screen and click "Apply Template". The settings
in the "TEMPLATE" row will be applied to the countries you selected.
Now click "Save Changes" to save these settings, or click
"Cancel (No Changes!)" if you made a mistake.
That's it, you have created a filter. You can do this for each region and
"filt8" will highlight (or audio alert) the items you have selected on a
per band basis.
The "USA States" is a special button created for operators that are trying
to collect all 50 states. For this to work you MUST select
"Ability to show/filter U.S.A. states?" in the setup.py program.
If you click on this button the filter works the same way as a regional
filter, but it is USA States instead of countries. *** Important note:
turning on state filtering OVERRIDES the USA filtering setting in the
"North America" region.
Once you have saved your filters and quit the filtering program please press
the "Reload Filter/Color" button in the "filt8" screen and your new
filters will load without you having to restart "filt8".
-----------------------------------------------------------
"History" button in Filt8.
Opens the history viewer.
It gives you a window with the QSO's it has captured (up to 12,000).
You can search on any string, and best of all filt8 keeps collecting
in the background while you look through the history log.
History contains, country, state (if applicable), and band.
The contents being displayed were written to a file tmphist.tmp in the
filt8 directory, in case you want to print it, open it in your favorite
text editor, etc.
"Find/Find Next" - searches forward for the text in the search text box.
"Previous" - searches backwards through the text.
"Top" - jumps to the beginning of the History (going back in time)
"End" - jumps to the end of the history file so you see the latest.
"Close" - closes the History screen.
-----------------------------------------------------------
filt8freq.py - filt8 but in a horizontal frequency-oriented output.
We break the waterfall into 100 Hz segments and map the QSOs by frequency to
show the distribution of the signals. It makes for an interesting display but
it does not attemtpt to sort by QSO-type (such as CQ, 73, etc...). It still
uses the color coding indicating the QSO-type. Let us now what you think.
-----------------------------------------------------------
That's all I can think of... there isn't much to it.
Please drop us an email and tell us what you think.
Your valuable feedback went into filt8 v2.6, thanks!
-----------------------------------------------------------
Download Latest Version
filt8.zip (6.9 MB)
