================================================================================
  F104Mapper  –  User Manual
  Version 1.2.2
  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
================================================================================

  Full installation instructions, system requirements, desktop launcher
  setup, and setup troubleshooting are in a separate document:

      Installation_Guide.txt

  This file is included in the F104Mapper program folder.

  Quick summary:
    1. Open a terminal (or Command Prompt on Windows) and navigate to
       the f104mapper folder.
    2. Run:   python3 setup.py   (Linux / Raspberry Pi / macOS)
              python  setup.py   (Windows)
    3. Verify the map loaded correctly — the map of North America should
       display with land masses, borders, and coastlines.


================================================================================
3.  STARTING THE PROGRAM
================================================================================

DESKTOP ICON / SHORTCUT
-----------------------
Linux / Raspberry Pi / macOS:
    Double-click the F104Mapper icon on the Desktop (created by setup.py).

Windows:
    Double-click the F104Mapper shortcut on the Desktop (created by
    setup.py).

COMMAND LINE
------------
    bash /home/<username>/f104mapper/run.sh   (Linux / Raspberry Pi / macOS)
    C:\Users\<username>\f104mapper\run.bat    (Windows)

If setup has not been run yet, see Installation_Guide.txt.

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
================================================================================

SETUP / INSTALLATION PROBLEMS
------------------------------
  For problems related to setup — missing packages, missing map data,
  desktop icon not appearing, or "virtual environment not found" errors —
  see the troubleshooting section in:

      Installation_Guide.txt

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.2.2
  SitRepNet.com
================================================================================
