================================================================================ F104Mapper – User Manual Version 1.1.0 Stephen Clay McGehee, KN4AM ================================================================================ TABLE OF CONTENTS ----------------- 1. Overview 2. Requirements and Installation 3. Starting the Program 4. Interface Layout 5. Loading Report Data 6. The Report List 7. The Map 8. Report Detail 9. Date Filter 10. Settings 11. Troubleshooting ================================================================================ 1. OVERVIEW ================================================================================ F104Mapper is a companion program to JS8Spotter. It reads F!104 Situation Report form data received via JS8Call / JS8Spotter and displays that data on an offline map of North America, allowing operators to quickly see the operational status at each reporting station's location. F104Mapper operates entirely offline at runtime. No internet connection is required once the program and its map data are installed. Key capabilities: - Displays color-coded map pins showing current status at each reporting station's Maidenhead grid square location - Formatted detail view of each received report, shown when a pin is clicked - Date filtering to focus on a specific time window - Automatic 60-second polling of an open JS8Spotter database for new reports - Export of the map as a PNG, JPG, or SVG image More information: SitRepNet.com ================================================================================ 2. REQUIREMENTS AND INSTALLATION ================================================================================ SUPPORTED PLATFORMS ------------------- - Raspberry Pi 4b running Raspberry Pi OS Bullseye or Bookworm - Linux (Python 3.9+) - macOS (Python 3.9+) - Windows (Python 3.9+) DEPENDENCIES ------------ The following are required at runtime: python3-tk GUI toolkit (usually pre-installed with Python) matplotlib Map rendering numpy Required by matplotlib Pillow (PIL) Image support pyshp Shapefile reading (for detailed map) These are installed automatically by setup.py (see below). Map data (Natural Earth shapefiles) is downloaded once by setup.py and stored in the data/shapefiles/ folder. After that, no internet connection is ever required. INSTALLATION ------------ 1. Obtain the F104Mapper files and place them in a folder of your choice. 2. Run the one-time setup (requires internet): Linux / macOS / Raspberry Pi: python3 setup.py Windows: python setup.py This creates a Python virtual environment, installs dependencies, and downloads the map shapefiles. 3. After setup, launch the program using the provided scripts: Linux / macOS / Raspberry Pi: run.sh Windows: run.bat Or launch directly: python3 f104mapper.py (Linux / macOS / Pi) python f104mapper.py (Windows) ================================================================================ 3. STARTING THE PROGRAM ================================================================================ On first launch the program opens with an empty map and no reports loaded. The status bar at the bottom reads: Ready. Import a file or open a JS8Spotter database. On subsequent launches, F104Mapper automatically reloads data from the last JS8Spotter database that was opened (if the database file still exists). Auto-Update Check ----------------- If an update check URL is configured in Settings → Auto-Update, the program silently checks for a newer version in the background at startup. If one is found, a prompt asks whether to open the download page. The program always starts normally regardless of the result, and this check is skipped entirely when offline. ================================================================================ 4. INTERFACE LAYOUT ================================================================================ The window is divided into three main areas: LEFT PANEL ---------- Loaded Reports list Shows all reports currently in memory, most recent first. Each entry displays: [status] date source callsign | grid | state Status codes in the list: [1] Green – Normal [2] Yellow – Degraded [3] Red – Significant Problems [ ] Status could not be parsed Color-coding in the list matches the map pin color. Gray (dimmed) entries are records marked as invalid. Date Filter Controls which reports are visible on the map. See Section 9 for details. RIGHT PANEL (upper) ------------------- The map of North America with color-coded pins for each visible report. A navigation toolbar below the map provides zoom, pan, and home controls. RIGHT PANEL (lower) ------------------- Report Detail pane. Displays the full parsed view of the selected report. Click a map pin or select a row in the list to populate this pane. STATUS BAR ---------- A single line at the very bottom of the window showing the most recent action result (file imported, DB loaded, poll update, export saved, etc.). ================================================================================ 5. LOADING REPORT DATA ================================================================================ Reports can be loaded from three sources. Multiple loads may be performed in the same session; records are merged (duplicates are not added twice). FILE → IMPORT F!104 FILE ------------------------ Opens a plain text file or JS8Spotter CSV export containing F!104 form data. Plain text: The file may contain one or more raw F!104 lines, one per row. Example: F!104 100 ST[OK] GR[EM15] #CLSC F!104 200 ST[TX] GR[EL29] #BHMF CSV export: A JS8Spotter export file with columns for message text, callsign, and optional timestamp. F104Mapper looks for the F!104 marker in each line and ignores any line that does not contain one. FILE → OPEN JS8SPOTTER DATABASE -------------------------------- Opens a JS8Spotter SQLite database file (.db, .sqlite, .sqlite3) in read-only mode. This is safe to use while JS8Spotter is running. F104Mapper queries the 'forms' table for rows where typeid = 'F!104' or where the message text contains 'F!104'. Once a database is open, F104Mapper polls it every 60 seconds and automatically adds any new F!104 records without user action. The last-used database path is saved and automatically reloaded on startup. NOTES ON FORM FORMAT -------------------- The F!104 over-the-air format is: F!104 [CSA] ST[state] GR[grid] FM[ref] [comment] #datetime CSA 3-character status code (e.g. "100", "2E0") Char 1: 1=Normal (Green) 2=Degraded (Yellow) 3=Problems (Red) Char 2: 0=No sitrep E=Sitrep active Char 3: 0=No alert E=Alert active ST[XX] 2-letter US state abbreviation GR[XXXX] Maidenhead grid square (4 or 6 characters) FM[text] Optional – reference to another form (e.g. FM[F!505]) comment Free text outside brackets (from the Comment field) #XXXX Filed date/time code (4-character JS8Spotter format) Field order is not guaranteed. FM[] is sometimes misused for narrative text; F104Mapper stores whatever is in FM[] and displays it verbatim. ================================================================================ 6. THE REPORT LIST ================================================================================ The left panel shows all reports currently in memory, sorted with the most recently filed or received report at the top. SELECTING A REPORT ------------------ Click any row to select it. The Report Detail pane (lower right) will show the full parsed view of that report, and the corresponding map pin will be highlighted. Clicking empty space in the list deselects the current report. MARKING A REPORT AS INVALID ----------------------------- Select the report in the list, then press the Delete key. A confirmation dialog will ask whether to mark the record as invalid. Invalid records are: - Shown in gray in the list - Excluded from the map - Excluded from the date filter count To restore an invalid record, select it and press Delete again. The confirmation dialog will offer a Restore option instead. Invalid status is remembered across sessions for the same database. NOTES ----- [off-map] This suffix appears when the grid square is valid Maidenhead but falls outside the North America map area. The report is still in the list but no pin is plotted. ================================================================================ 7. THE MAP ================================================================================ The map shows North America with color-coded pins for each visible report. PIN COLORS ---------- Green (status 1) All operations normal, nothing significant to report Yellow (status 2) Under control, but degraded current or anticipated situation Red (status 3) Significant current problems (no pin) Status could not be parsed, or report is filtered out Each pin consists of a downward-pointing triangle (tip at the grid square location) with a circle head above it. When a pin is selected, its outline turns black and it is drawn on top of all others. PIN LABELS ---------- When "Always display callsign and status on each pin" is enabled in Settings, each pin shows the station callsign and a short status label. When disabled, only the color-coded pin is shown. Click any pin to see full details. CLICKING A PIN -------------- Left-click a pin to select it. The Report Detail pane populates with the full parsed view, and the pin is highlighted. The corresponding row in the Loaded Reports list is also selected and scrolled into view. If multiple pins are close together, the nearest pin within 18 screen pixels of the click point is selected. NAVIGATION TOOLBAR ------------------ The toolbar below the map provides standard matplotlib navigation: Home Return to the default full-map view Back/Fwd Navigate through previous zoom/pan states Pan Click and drag to pan the map Zoom Draw a rectangle to zoom in Save Save the current map view as an image file Zoom and pan state is preserved when the map redraws (on new data, filter changes, pin selection, etc.). POP-OUT MAP ----------- View → Pop Out Map opens the map in a separate, fully resizable window. This is useful for displaying the map on a second monitor or enlarging it independently of the rest of the interface. Click "Dock Map" in the pop-out window to return the map to the main window. EXPORTING THE MAP ----------------- File → Export Map Image saves the current map view (including pins and legend) as a PNG, JPG, or SVG file. The format is set in Settings → Export. ================================================================================ 8. REPORT DETAIL ================================================================================ When a report is selected (by clicking a pin or a list row), the lower-right pane shows the full parsed view. Example: ────────────────────────────────────────────────────────────────── KJ5MIW | EM15 | Oklahoma ────────────────────────────────────────────────────────────────── From : KJ5MIW To : @SITREP Filed : 2026-03-12 18:04 UTC Received : 2026-03-14 13:06 UTC Source : database Status : 1 – All operations normal, nothing significant to report [Normal] Sitrep : Nothing to report Alert : Nothing to report State : OK (Oklahoma) Grid : EM15 (35.50°N, 97.00°W) Form Ref : (none) Comment : Raw : F!104 100 ST[OK] GR[EM15] #CLSC ────────────────────────────────────────────────────────────────── FIELDS EXPLAINED ---------------- From Callsign of the originating station To Destination callsign or group (e.g. @SITREP) Filed Date/time the form was prepared, decoded from the #XXXX code Received Date/time JS8Spotter logged the message Source "database" or "file" Status The first character of the CSA code, with its full description Sitrep The second character of the CSA code: "Nothing to report" — no active situation report "Situation report active — send E? F!304 for details" Alert The third character of the CSA code: "Nothing to report" — no active awareness/alert report "Awareness/Alert active — send E? F!305 for details" State 2-letter state code with full state name Grid Maidenhead grid square with decoded coordinates Form Ref Contents of the FM[] field, if present. This field is meant to reference another form (e.g. "F!505"), but may occasionally contain narrative text if the sender used it incorrectly. Comment Free text from the sender's Comment field (text outside brackets) Raw The original over-the-air line exactly as received SITREP AND ALERT FLAGS ---------------------- When Sitrep or Alert shows an active flag (E), the receiving station should use JS8Spotter's Expect function to request the additional report: Active Sitrep: send E? F!304 to the originating station Active Alert: send E? F!305 to the originating station ================================================================================ 9. DATE FILTER ================================================================================ The Date Filter in the lower-left panel controls which reports appear on the map and in the detail pane. Reports outside the filter window are hidden but not deleted — they remain in memory and reappear if the filter is changed. FILTER MODES ------------ No Filter All loaded reports are shown regardless of date. Previous N-Days Shows reports from today back N days (default: 14). The window updates automatically at midnight — no manual action needed when the program runs continuously overnight. Specified Dates Shows only reports with a date on or between the From and To dates. Format: YYYY/MM/DD DATE ENTRY SHORTCUTS -------------------- When a date entry field is focused: + or = Advance the date by one day - Move the date back by one day Digit keys Overtype mode — type directly over the existing date / key Skip over the separator Click the Apply button (or change the filter mode) to update the map. ================================================================================ 10. SETTINGS ================================================================================ Open Settings via: Settings → Preferences… DISPLAY TAB ----------- Always display callsign and status on each pin When checked, each map pin shows the station callsign and a short status label ("Normal", "Degraded", or "Problems"). When unchecked, only the color-coded pins are shown. Click any pin to see full details in the Report Detail pane. EXPORT TAB ---------- Map image format Choose PNG, JPG, or SVG for map image exports. Default export folder The folder where exported map images are saved by default. Leave blank to use the data/exports/ folder inside the program directory. AUTO-UPDATE TAB --------------- Check for updates on startup When enabled, F104Mapper silently checks the configured URL for a newer version. If one is found, you are asked whether to open the download page. The program always starts normally regardless of the result, and this check is skipped entirely when offline. Version check URL The URL to check for version information. Leave blank to disable update checks entirely. ================================================================================ 11. TROUBLESHOOTING ================================================================================ MAP DATA NOT SHOWING -------------------- If the map shows a plain green rectangle with the message "Run setup.py to download map data", the shapefile data has not been installed. Run setup.py once (requires internet) to download it: python3 setup.py (Linux / macOS / Raspberry Pi) python setup.py (Windows) After setup, the program works fully offline. NO REPORTS FOUND IN DATABASE ------------------------------ F104Mapper looks for rows in the JS8Spotter 'forms' table where typeid = 'F!104' or where message text contains 'F!104'. Use Help → DB Diagnostic to inspect the database. The diagnostic shows: - All tables present - All typeid values in the forms table with row counts - Up to 10 sample rows matching '104' This is useful for confirming that JS8Spotter has stored F!104 records and for verifying the exact typeid value being used. REPORT APPEARS IN LIST BUT NOT ON MAP --------------------------------------- Possible reasons: - The report's grid square could not be parsed (check the Raw line in the detail view to confirm the GR[] field is present and correctly formatted) - The grid square is outside the North America map area (shown as [off-map] in the list) - The report's status character is not 1, 2, or 3 (no pin color assigned) - The report is excluded by the active date filter DATE FILTER SHOWS NO REPORTS ------------------------------ If reports are loaded but none appear on the map, the date filter may be excluding them. Try switching the Date Filter to "No Filter" to see all loaded reports, then adjust the filter as needed. FILED TIME SHOWS INCORRECTLY ------------------------------ The Filed time is decoded from the 4-character #XXXX date/time code embedded in the raw form. This code uses 2-minute resolution and does not include the year. The year is inferred from the received time. If the form was received near a year boundary (late December / early January), the year displayed may be off by one. The Received time (from the database timestamp) is always exact. ================================================================================ F104Mapper v1.1.0 SitRepNet.com ================================================================================