================================================================================
  JS8Reporter  –  User Manual
  Version 1.7.7
  Stephen Clay McGehee, KN4AM
================================================================================


TABLE OF CONTENTS
-----------------
  1.  Overview
  2.  Requirements and Installation
  3.  Starting the Program
  4.  Interface Layout
  5.  Loading Data
      5.1  Open Assessments Database
      5.2  Import F505 File
      5.3  Import F104 File
      5.4  Import All Files from Folder
      5.5  Automatic Deduplication
      5.6  Ignoring Call Signs (IGNORE.TXT)
  6.  The Assessment List
  7.  The Map
      7.1  Map Symbols and Markings
      7.2  F!104 Situation Report Pins
      7.3  F!309 Situation Map Pins
      7.4  Map Legend
      7.5  Pop-Out Map
      7.6  Flag Pins
      7.7  Grid Converter
  8.  Assessment Detail and Summary Table
  9.  Date Filter
  10. Circle Filter
  11. Time Lapse
  12. ALERT Detection
  13. Reports
  14. Exporting Data
  15. Settings
  16. Keyboard Shortcuts
  17. Troubleshooting


================================================================================
1.  OVERVIEW
================================================================================

JS8Reporter is a companion program to JS8Spotter. It reads MCF505 Area
Assessment (F!505) and F!104 Situation Report form data received via
JS8Call / JS8Spotter and displays that data on an offline map of North
America, allowing emergency managers to visualize operational status and
situational awareness across a wide area.

JS8Reporter operates entirely offline at runtime. No internet connection is
required once the program and its map data are installed.

Key capabilities:
  - Displays color-coded F!505 map pins showing infrastructure condition
    at each reporting station's grid square location
  - Displays F!104 Situation Report diamond pins showing operational status
    (Normal / Degraded / Significant Problems) at each station's location
  - Both pin types respect all filters: Date Filter, Circle Filter, and
    Time Lapse
  - Flag Pins: manually-placed SitRep markers annotating the map with
    information from any source; import/export in a format interoperable
    with MHGridMapper for net distribution
  - New pin highlight: optional magenta ring drawn around recently-received
    pins to make new arrivals visible at a glance (configurable time window)
  - Tabulated summary and detail views of all received assessments
  - Date filtering to focus on a specific time window
  - Circle filter to focus on a geographic area
  - Time Lapse playback to visualize how conditions change over time
  - ALERT detection for both F!505 and F!104 records, with prominent
    notification identifying the form type, callsign, and grid square
  - Twelve analytical report types for F!505 data; F!104 Summary report
  - Export of map images and tabular data

MCF505 / F!505 Form Reference:  https://sitrepnet.com/mcforms/MCF505.txt
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 JS8Reporter program folder.

  Quick summary:
    1. Open a terminal (or Command Prompt on Windows) and navigate to
       the js8reporter folder.
    2. Run:   python3 setup.py   (Linux / Raspberry Pi)
              python  setup.py   (Windows)
    3. Verify map data with Help > Map Setup (setup.py)…


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

Linux / Raspberry Pi
---------------------
  Double-click the JS8Reporter icon on the Desktop.

  Or from a terminal:
      bash /home/<username>/js8reporter/run.sh

Windows
--------
  Double-click the JS8Reporter shortcut on the Desktop.

  Or from a Command Prompt:
      C:\Users\<username>\js8reporter\run.bat

On startup, JS8Reporter will automatically reload the last database that
was opened, if one is available.

If IGNORE.TXT contains any call signs, an "IGNORE.TXT Active" dialog
will appear listing the ignored call signs. See Section 5.6.

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


================================================================================
4.  INTERFACE LAYOUT
================================================================================

The JS8Reporter window is divided into four main areas:

  +------------------------------------------------------------------+
  |  Menu Bar:  File  View  Circle  Reports  Settings  Tools  Help   |
  +------------------+-----------------------------------------------+
  |                  |                                               |
  |  Loaded          |   MAP                                         |
  |  Assessments     |   (color-coded map pins on North America)     |
  |  (list)          |                                               |
  |                  |   Navigation toolbar (zoom, pan, home)        |
  +------------------+-----------------------------------------------+
  |  Date Filter     |   Assessment Detail / Summary Table           |
  +------------------+-----------------------------------------------+
  |  Status Bar                                        | Mode        |
  +------------------------------------------------------------------+

Menu Bar
--------
  All program functions are accessed through the menu bar. See the
  individual sections below for details on each menu.

Left Panel — Loaded F505 Assessments
--------------------------------------
  Lists all assessments currently loaded into the program. Each entry
  shows the callsign, grid square, and report timestamp.

  Color coding in the list:
    - Normal text   : Valid assessment
    - Bold red      : Assessment contains an ALERT
    - Gray / italic : Assessment marked as invalid (excluded from map)

  Click an entry to select it and view its full detail below.

  Press the Delete key while an entry is selected to mark it as invalid
  (or to restore it if it is already invalid). Marking an assessment
  as invalid removes it from the map and from all reports, but keeps
  it visible in the list for reference.

Date Filter
-----------
  Located below the assessment list. Allows filtering by date range.
  See Section 9 for full details.

Map Area
--------
  Shows a color-coded map of North America with two types of map symbols:

  F!505 Area Assessment pins (▼ inverted triangle + circle):
    Color indicates infrastructure condition:
      Green  (#28a745)  =  Score 3  –  Fully Operational
      Yellow (#ffc107)  =  Score 2  –  Degraded
      Orange (#fd7e14)  =  Score 1  –  Severely Impaired
      Red    (#dc3545)  =  Score 0  –  Destroyed
    The score displayed is determined by the Pin Color Mode setting.

  F!104 Situation Report pins (◆ solid diamond):
    Color indicates reported operational status:
      Green  (#28a745)  =  Status 1  –  Normal
      Yellow (#ffc107)  =  Status 2  –  Degraded
      Red    (#dc3545)  =  Status 3  –  Significant Problems
    F!104 pins carry no label. Click a diamond to see its detail.

  F!309 Situation Map pins (▲ upward triangle):
    Color indicates severity:
      Green  (#28a745)  =  Severity 1  –  Minor / Limited Impact
      Yellow (#ffc107)  =  Severity 2  –  Moderate
      Orange (#fd7e14)  =  Severity 3  –  Severe
      Red    (#dc3545)  =  Severity 4  –  Major / Catastrophic
      Gray   (#888888)  =  Severity 5  –  Unknown or N/A
    Description text appears as a label to the right of the pin.
    Expired pins are hidden automatically. Click a triangle to see its detail.

  F!505 and F!104 pins display a red "!" badge when an active ALERT is present.

  The navigation toolbar below the map provides:
    Home    – Return to the default full-map view
    Back    – Go to previous zoom/pan view
    Forward – Go to next zoom/pan view
    Pan     – Click and drag to pan the map
    Zoom    – Draw a rectangle to zoom in; auto-exits after one use

  Press Escape at any time to exit Pan or Zoom mode and return the
  cursor to normal.

  Click any map pin to view its detail in the panel below.

  Use View > Show F!104 Pins / Show F!309 Pins to toggle those layers.

Report Detail / Assessment Detail
-----------------------------------
  The panel title and content change depending on what is selected:

  "Report Detail" — shown when an F!505 assessment is selected, or when
    no pin is selected (summary table mode).

  "F!104 Detail" — shown when an F!104 diamond pin is clicked. Displays
    callsign, grid, status label, and filed date for that record.

  "F!309 Map Pin" — shown when an F!309 triangle pin is clicked. Displays
    callsign, grid, description, category, severity, time frame, status,
    filed date, and expiration date/time.

  To return to the summary table, use View > Show Summary or click an
  empty area of the assessment list.

Status Bar
----------
  Shows the most recent program message (e.g., "Loaded 12 assessments
  from spotter.db").

Mode Indicator
--------------
  The blue label at the right of the status bar shows the current
  interaction mode (e.g., "Click map to set circle center").


================================================================================
5.  LOADING DATA
================================================================================

JS8Reporter can load F!505 assessment data, F!104 Situation Report data,
and F!309 Situation Map Pin data from multiple sources:

5.1  Open Assessments Database  (File > Open Assessments Database…)
--------------------------------------------------------------------
  Opens a JS8Spotter SQLite database file (.db). This is the primary way
  to load data that has been received over the air by JS8Spotter.

  JS8Reporter opens the database read-only and is safe to use while
  JS8Spotter is actively running and writing to the same file.

  F!505 assessments, F!104 Situation Reports, and F!309 Situation Map
  Pins are all loaded from the same database file automatically.

  The database path is remembered and the database is automatically
  reloaded the next time JS8Reporter starts.

5.2  Import F505 File  (File > Import F505 File…)
--------------------------------------------------
  Imports F!505 assessments from a single plain text file or a
  JS8Spotter CSV export file. Useful for loading manually prepared
  assessments or data exported from another system, including files
  created by File > Export as F505….

  Supported formats:
    - Plain text F505 form (as transmitted over JS8Call)
    - JS8Spotter CSV export
    - F505 export file created by File > Export as F505…

5.3  Import F104 File  (File > Import F104 File…)
--------------------------------------------------
  Imports F!104 Situation Report records from a single plain text file
  or a JS8Spotter CSV export file.

  Supported formats:
    - Plain text F!104 form (as transmitted over JS8Call)
    - JS8Spotter CSV export containing F!104 records

  F!104 records are added to the existing display without clearing
  any loaded F!505 assessments.

5.4  Import All Files from Folder  (File > Import All Files from Folder…)
--------------------------------------------------------------------------
  Imports F!505, F!104, and F!309 records from every .txt and .csv file
  found in the configured Import Records folder, and imports flag pins from
  every .flags.json file found there (see Settings > Export > Import
  Records folder). Each .txt/.csv file is automatically scanned for all
  three form types.

  Before importing, JS8Reporter will display a confirmation message
  showing the folder path and warn that all currently loaded F!505, F!104,
  and F!309 records will be cleared. Flag pins are merged (not cleared)
  using the same timestamp-based merge as a normal flag pin import. Click
  Yes to proceed or No to cancel.

  After clearing, all files in the folder are parsed and combined. Any
  records that appear in more than one file are automatically deduplicated
  before being added to the display.

  The Import Records folder is set in Settings > Export > Import Records
  folder. It defaults to the  data/imports/  folder inside the JS8Reporter
  program folder.

5.5  Automatic Deduplication
-----------------------------
  When loading data, JS8Reporter automatically handles duplicates:

  F!505 Station + Date deduplication:
    If the same callsign submitted more than one assessment on the same
    calendar day, only the most recent submission for that day is shown.

  F!505 Grid square deduplication:
    If more than one F!505 assessment maps to the same grid square, the
    behavior is controlled by the Settings > Filters > Duplicate
    grid-square handling option (use most recent, or average scores).

  F!104 Grid square deduplication:
    If more than one F!104 record maps to the same grid square, only the
    most recently received record for that grid square is shown.

5.6  Ignoring Call Signs  (IGNORE.TXT)
---------------------------------------
  Assessments from call signs listed in IGNORE.TXT are silently
  discarded and never added to JS8Reporter's display.

  IGNORE.TXT is a plain text file located in the main JS8Reporter
  program folder (the same folder as js8reporter.py). If the file does
  not exist, no call signs are ignored.

  File format:
    - One call sign per line
    - Call signs are not case-sensitive
    - Lines beginning with # are treated as comments and skipped
    - Blank lines are skipped

  Example IGNORE.TXT:
    # Operators whose assessments should not be displayed
    W1ABC
    KG5XYZ

  The filter applies to every data source:
    - JS8Spotter database (open, auto-reload on startup, and the
      periodic background refresh while a database is open)
    - File imports  (File > Import F505 File…)
    - Folder imports  (File > Import All Files from Folder…)

  On startup, if IGNORE.TXT contains any entries, JS8Reporter displays
  an "IGNORE.TXT Active" dialog listing the ignored call signs.

  To stop ignoring a call sign, remove it from IGNORE.TXT and restart
  JS8Reporter.


================================================================================
6.  THE ASSESSMENT LIST
================================================================================

The list on the left side of the window shows all loaded assessments,
sorted by report creation date (most recent first).

Selecting an Assessment
-----------------------
  Click any entry to select it. The Assessment Detail panel updates to
  show that assessment's full field-by-field detail.

  Click an empty area of the list to deselect and return to the
  Summary Table view.

Marking as Invalid / Restoring
--------------------------------
  Select an assessment and press the Delete key.

  - If the assessment is valid, you will be asked to confirm marking it
    as invalid. Invalid assessments are grayed out in the list and
    excluded from the map and all reports.

  - If the assessment is already invalid (grayed out), you will be asked
    to confirm restoring it as valid.

  Invalid/valid status is remembered between sessions for the same
  database.

ALERT Records
-------------
  Assessments whose text contains the word "ALERT" are shown in bold
  red in the list and trigger the ALERT notification. See Section 12.


================================================================================
7.  THE MAP
================================================================================

The map shows two types of data pins (F!505 and F!104), an optional
Circle Filter overlay, and ALERT badges. All are described in 7.1 below.

Map Navigation
--------------
  Use the navigation toolbar below the map to zoom and pan.
  The Home button returns to the full North America view.

  When Time Lapse is running, use the Left and Right arrow keys to step
  backward and forward through dates.

Pin Color Modes  (Settings > Pin Colors)
-----------------------------------------
  Applies to F!505 Area Assessment pins only.

  Lowest score across all fields:
    Pin color reflects the single worst-scoring field in the assessment.

  Average of all fields:
    Pin color reflects the overall average score (default).

  Average within selected category:
    Pin color reflects the average score for one specific category.

  Lowest score within selected category:
    Pin color reflects the worst field within one specific category.

7.1  MAP SYMBOLS AND MARKINGS
------------------------------

F!505 Area Assessment Pin
  Each F!505 assessment with a valid grid square appears on the map as
  a two-part pin symbol:

    Circle (head):
      A solid filled circle positioned above the triangle. The circle
      has no independent meaning — together with the triangle it forms
      a single "map pin" symbol, similar to a thumbtack. The larger
      circular head makes the pin easier to see at a glance and easier
      to click. It is the same color as the triangle below it.

    Triangle (stem/pointer):
      A downward-pointing triangle whose tip marks the exact grid square
      location on the map. The triangle color represents the assessment
      score, determined by the active Pin Color Mode (see above).

  Color scale:
    Green  (#28a745)  =  Score 3  –  Fully Operational
    Yellow (#ffc107)  =  Score 2  –  Degraded
    Orange (#fd7e14)  =  Score 1  –  Severely Impaired
    Red    (#dc3545)  =  Score 0  –  Destroyed
    Gray   (#888888)  =  All fields X  –  No scoreable data

  A record where every score field is X (unknown/N/A) appears as a gray
  pin. The operator checked in but reported no data for any field. Gray
  pins are otherwise treated the same as scored pins (date filter,
  deduplication, circle filter, and MHGridMapper sync all apply).

  Label:
    When pin labels are enabled (Settings > Pin Colors > "Always display
    Map Pin info"), the callsign and score appear to the right of scored
    pins. Gray (all-X) pins carry no label.

F!104 Situation Report Diamond
  Each F!104 record with a valid grid square appears as a solid filled
  diamond (◆) at that grid square location.

  Color scale:
    Green  (#28a745)  =  Status 1  –  Normal
    Yellow (#ffc107)  =  Status 2  –  Degraded
    Red    (#dc3545)  =  Status 3  –  Significant Problems

  F!104 diamonds carry no label. Click a diamond to see its detail.
  Use View > Show F!104 Pins to show or hide the diamond layer.

F!309 Situation Map Pin
  Each F!309 record with a valid grid square appears as a solid filled
  upward triangle (▲) at that grid square location. The description
  field is annotated as a label to the right of the pin.

  Color scale (by Severity field):
    Green  (#28a745)  =  Severity 1  –  Minor / Limited Impact
    Yellow (#ffc107)  =  Severity 2  –  Moderate
    Orange (#fd7e14)  =  Severity 3  –  Severe
    Red    (#dc3545)  =  Severity 4  –  Major / Catastrophic
    Gray   (#888888)  =  Severity 5  –  Unknown or N/A

  F!309 pins expire automatically. Each pin carries an expiration time
  encoded in the report (24 hours, 48 hours, 3 days, 1 week, or 2 weeks
  past the report's filing time). Expired pins are hidden from the map
  and detail panel automatically — the underlying record is retained but
  not displayed.

  Click a triangle to see its full detail (see Section 8).
  Use View > Show F!309 Pins to show or hide the triangle layer.

ALERT Badge
  When an F!505 assessment or F!104 record carries an active ALERT:
    - A red circle with a white "!" appears above the pin or diamond.
    - F!505 pins change to a red-orange color.
    - F!104 diamonds keep their status color but gain the "!" badge.
  Dismissing the ALERT banner with "Cancel Alert" removes all badges.
  New alert records arriving afterward will trigger the badge again.

Circle Filter Overlay
  When the Circle Filter is enabled, a dashed blue circle with a center
  crosshair (+) and a diameter label is drawn on the map. Assessments
  and records outside the circle are excluded from the map and reports.
  See Section 10 for full details.

7.2  F!104 SITUATION REPORT PINS
----------------------------------
  F!104 Situation Report pins appear as solid colored diamonds (◆) on the
  map. They are separate from, and drawn on top of, the F!505 pin layer.

  Colors:
    Green  (#28a745)  –  Status 1: All operations normal
    Yellow (#ffc107)  –  Status 2: Under control, degraded
    Red    (#dc3545)  –  Status 3: Significant current problems

  F!104 pins carry no callsign label. Click any diamond to open its
  detail in the "F!104 Detail" panel (callsign, grid, status, filed date).

  Clicking an F!505 pin or clearing the selection returns the panel to
  "Report Detail" mode.

  Show / Hide:
    Use View > Show F!104 Pins to toggle F!104 diamond pins on or off.
    The setting is saved and restored on the next startup.

  Data source:
    F!104 records are loaded from the same JS8Spotter database as F!505
    assessments (automatically), or from a file via File > Import F!104
    File…, or from a folder via File > Import All Files from Folder.

7.3  F!309 SITUATION MAP PINS
------------------------------
  F!309 Situation Map Pins appear as solid upward triangles (▲) on the
  map. They are separate from, and drawn above, the F!505 and F!104 pin
  layers.

  Colors (by Severity):
    Green  (#28a745)  –  Severity 1: Minor / Limited Impact
    Yellow (#ffc107)  –  Severity 2: Moderate
    Orange (#fd7e14)  –  Severity 3: Severe
    Red    (#dc3545)  –  Severity 4: Major / Catastrophic
    Gray   (#888888)  –  Severity 5: Unknown or N/A

  Description label:
    The brief description field (up to 15 characters as transmitted)
    appears as a text label to the right of the pin.

  Expiration:
    Every F!309 pin has an expiration time — 24 hours, 48 hours, 3 days,
    1 week, or 2 weeks past the report's filing timestamp. Once a pin
    expires it is automatically hidden from the map. The record remains
    in memory and is visible in the stored data but no longer displayed.

  Detail panel:
    Click any triangle to open its detail in the "F!309 Map Pin" panel:
      Callsign      – Sending station
      Grid          – Maidenhead grid square
      Description   – Brief event description
      Affected Area – This Grid Square / city or county / state / region
      Category      – Event category (e.g., Flood, Fire, Medical…)
      Severity      – Minor through Major/Catastrophic, or Unknown
      Time Frame    – Imminence / on-going / anticipated / chronic
      Status        – New / Ongoing / Resolved / Unknown
      Filed         – Date and time the report was prepared (UTC)
      Expires       – Computed expiration date and time (UTC)

  Show / Hide:
    Use View > Show F!309 Pins to toggle the triangle layer on or off.
    The setting is saved and restored on the next startup.

  Clear:
    Use View > Clear All F309 Map Pins to remove all loaded F!309 records
    from memory (with confirmation). This does not affect the database.

  Data source:
    F!309 records are loaded from the same JS8Spotter database as F!505
    and F!104 records (automatically on open and on every poll cycle), or
    from a file via File > Import All Files from Folder.

  IGNORE.TXT:
    The same callsign ignore list that applies to F!505 and F!104 records
    also applies to F!309 pins. See Section 5.6.

  MHGridMapper live sync:
    When MHGridMapper live sync is active, unexpired F!309 pins are
    exported to  data/exports/mhgridmapper_f309.txt  alongside the
    existing F!505 and F!104 sync files.

  Right-click menu:
    Right-clicking near an F!309 pin adds a "View F309 Pin: [callsign]"
    entry to the combined context menu, alongside any nearby F!505, F!104,
    or flag pins.

7.4  MAP LEGEND
---------------
  A single combined legend is displayed in the lower-left corner of the
  map. It is organized into three sections:

  Map Symbols:
    Shows all map symbols with representative markers:
      ▼  F!505 Area Assessment pin
      ◆  F!104 Situation Report diamond
      ▲  F!309 Situation Map Pin
      ▼  Flag Pin (SitRep) — teardrop shape, user-chosen color
      ○  Selection Circle

  F!505 Status ▼:
    Color scale for F!505 Area Assessment pins.

  F!104 Status ◆:
    Color scale for F!104 Situation Report diamonds.
    This section is omitted when View > Show F!104 Pins is unchecked.

  F!309 Map Pin ▲:
    Color scale for F!309 Situation Map Pin triangles.
    This section is omitted when View > Show F!309 Pins is unchecked.

  Flag Pins ⚑:
    Appears when at least one flag pin exists. Shows a teardrop pin
    marker (▼) in the default red color with a "SitRep Flag Pin" label.

7.5  POP-OUT MAP
----------------
  The map can be detached from the main window into its own resizable
  window via View > Pop Out Map. This is useful when you want to keep the
  map continuously visible while working in the main window — for example,
  while reviewing individual assessment details or scrolling the assessment
  list.

  For routine monitoring, the pop-out map is often the better arrangement.
  With the map in its own window (or on a second monitor), the main window
  is free to display the full assessment list and detail panel without the
  map competing for vertical space.

  The pop-out map is fully live: it updates on the same automatic polling
  cycle as the rest of the application, so new records appear on the map
  within approximately one minute of arrival — no manual refresh needed.

  Dock Map button:
    The "Dock Map" button at the bottom of the pop-out window returns the
    map to its original position inside the main window. The window size
    and position are remembered, so the next time you pop the map out it
    reopens where you left it.

  Closing the pop-out window has the same effect as clicking "Dock Map" —
  the map returns to the main window rather than being dismissed entirely.


7.6  FLAG PINS
--------------
Flag pins are manually-placed situational awareness markers. They are
independent of received F!505/F!104 radio traffic and can represent
information gathered from any source — radio nets, voice reports, written
messages, etc.

Placing a Flag Pin:
  Right-click any location on the map and select "Add Flag Pin Here…".
  Fill in the fields in the dialog:
    Description:  Free-text note (appears as a label on the map).
    Grid Square:  Maidenhead locator — auto-fills lat/lon (or vice versa).
    Date / Time:  UTC timestamp for the event (defaults to now).
    Source:       Where the information came from. Pre-filled with the
                  station callsign set in Settings > General; edit as
                  needed (e.g., "W5XYZ via voice net").
    Color:        Pin color — click the color swatch to choose.

Editing or Deleting a Flag Pin:
  Right-click anywhere near a flag pin on the map. The context menu shows
  the pin's description and offers "Edit Flag Pin: [description]…" and
  "Delete Flag Pin".

  If an F505, F104, or F309 pin is also near the click location, the same
  menu additionally shows "View Assessment: [callsign]", "View F104
  Report: [callsign]", and/or "View F309 Pin: [callsign]", so all
  overlapping pins are accessible from a single right-click.

Importing Flag Pins (File menu):
  File > Import Flag Pins… imports a .flags.json file directly from the
  File menu, without opening the Flag Pins dialog.

Exporting Flag Pins (File menu):
  File > Export Flag Pins… saves all current flag pins directly, without
  opening the Flag Pins dialog.

Managing All Flag Pins  (View > Flag Pins…):
  Opens the Flag Pins management dialog listing all current pins.
  Buttons: Add, Edit, Delete, Jump to Map, Import, Export.

Exporting Flag Pins:
  Click Export in the Flag Pins dialog. The file is saved in the
  sitrep_flags JSON format (.flags.json). The station callsign
  set in Settings > General is written to the file as created_by.

Importing Flag Pins:
  Click Import in the Flag Pins dialog. Select a .flags.json file.
  New pins are added; existing pins (matched by ID) are replaced only
  if the incoming pin has a newer updated_at timestamp. The count of
  pins added or updated is shown on completion.

Net Distribution Workflow:
  One operator (e.g., net control or SitRep officer) creates flag pins
  from multiple sources and exports the file. The .flags.json file is
  distributed over the radio net. Recipients import it — corrections and
  additions in the redistributed file update existing pins automatically
  via the timestamp-based merge.

  Flag pins are stored in data/flags.flags.json and persist between
  sessions. The .flags.json format is fully interoperable with MHGridMapper.

Flag Pin Appearance:
  JS8Reporter displays flag pins as a teardrop map-pin shape (▼) in the
  user-chosen color — the same shape used for F!505 and F!104 pins.
  MHGridMapper displays the same pin data as a traditional flag icon (⚑).
  The visual symbols differ between programs; the underlying data and file
  format are identical.


7.7  GRID CONVERTER  (Tools > Grid Converter…)
----------------------------------------------
  Converts between Maidenhead grid squares, MGRS/USNG military grid
  coordinates, and decimal Lat/Lon. Enter any supported format in the
  input field and click Convert (or press Enter) — the format is detected
  automatically.

  Accepted input formats:
    Maidenhead    e.g.  EL99hc
    MGRS / USNG   e.g.  15RYP53780
    Lat, Lon      e.g.  34.5678, -86.1234

  Results displayed:
    Detected format  –  Maidenhead, MGRS, or Lat/Lon
    Maidenhead       –  Grid square (4, 6, or 8 characters)
    MGRS / USNG      –  Military grid reference
    Latitude         –  Decimal degrees N/S
    Longitude        –  Decimal degrees E/W

  Options:
    MGRS precision     –  10 m / 100 m / 1 km / 10 km
    Maidenhead length  –  4-char, 6-char (default), or 8-char

  Buttons: Copy Maidenhead, Copy MGRS, Close.


================================================================================
8.  ASSESSMENT DETAIL AND SUMMARY TABLE
================================================================================

The detail panel title and content change based on what is selected.

Summary Table  (title: "Report Detail")
----------------------------------------
  Shown on startup and whenever no pin is selected.
  Displays a grid of category averages for all currently visible F!505
  assessments, with Min / Max / Avg columns.

  To return to the summary table at any time:
    - Use View > Show Summary, or
    - Click an empty area in the assessment list.

F!505 Assessment Detail  (title: "Report Detail")
---------------------------------------------------
  Shown when an F!505 assessment is selected from the list or by clicking
  a pin on the map. Displays full information for that assessment:

    - Callsign, grid square, coordinates, state, city/county
    - Report prepared timestamp and received timestamp
    - Age (time elapsed since the report was filed)
    - Source, SNR, frequency
    - Overall average score with color bar
    - Per-category scores with color bars
    - Field-by-field scores (fields 1–32)
    - Notes, if any

  Score values:
    3  –  Fully Operational
    2  –  Degraded
    1  –  Severely Impaired
    0  –  Destroyed
    X  –  Unknown / Not Applicable (excluded from averages)

F!104 Situation Report Detail  (title: "F!104 Detail")
-------------------------------------------------------
  Shown when an F!104 diamond pin is clicked on the map.
  Displays compact information for that record:

    - Callsign
    - Grid square
    - Status code and full status label
    - Filed date/time (UTC)
    - Age (time elapsed since the report was filed)
    - ALERT: Active  (if an alert flag is set)

  The F!104 detail panel does not affect the Assessment List selection.
  Click an empty area of the assessment list or use View > Show Summary
  to return to the summary table.

F!309 Situation Map Pin Detail  (title: "F!309 Map Pin")
---------------------------------------------------------
  Shown when an F!309 upward-triangle pin is clicked on the map.
  Displays the full decoded content of that report:

    - Callsign       – Sending station
    - Grid           – Maidenhead grid square
    - Description    – Brief event description (up to 15 characters)
    - Affected Area  – Grid Square / city or county / state / region
    - Category       – Event category (Flood, Fire, Medical, etc.)
    - Severity       – Minor through Major/Catastrophic, or Unknown
    - Time Frame     – Imminence classification
    - Status         – New / Ongoing Deteriorating / Improving / Resolved
    - Filed          – Report preparation date and time (UTC)
    - Expires        – Computed expiration date and time (UTC)
    - Age            – Time elapsed since the report was filed

  Clicking an F!505 pin or clearing the selection returns the panel to
  "Report Detail" mode.


================================================================================
9.  DATE FILTER
================================================================================

The Date Filter is located in the lower-left panel, below the assessment
list. It restricts the map and all reports to assessments within a
specified date range.

Enabling and Disabling
-----------------------
  Check or uncheck the "Enable" checkbox, then click Apply.

Date Format
-----------
  Dates must be entered as:  YYYY/MM/DD  (e.g., 2025/03/14)

  The From and To fields use overtype mode — type digits directly over
  the existing date. The cursor skips over the "/" separators
  automatically.

Adjusting Dates
---------------
  With the cursor in a date field, press:
    +  or  =   to advance the date by one day
    -          to move the date back by one day

Default Range
-------------
  When the filter is first enabled, it defaults to the past 30 days.

Buttons
-------
  Apply  –  Activates the filter with the current From / To dates.
  Clear  –  Removes the date filter (shows all dates).


================================================================================
10. CIRCLE FILTER
================================================================================

The Circle Filter restricts the map and all reports to assessments whose
grid square falls within a specified radius of a center point.

Setting the Circle Center
--------------------------
  Circle > Set Circle Center…

  The mode indicator changes to "Click map to set circle center."
  Click anywhere on the map to place the center point.
  The circle is drawn immediately.

Configuring the Circle
-----------------------
  Circle > Configure Circle…

  Opens the Settings dialog to the Circle tab, where you can enter
  the center latitude, longitude, and radius in miles directly.

Disabling the Circle
---------------------
  Circle > Disable Circle

  Removes the circle overlay and includes all assessments regardless
  of location.

Notes
-----
  The circle is drawn as a geographic ellipse on the equal-aspect
  lat/lon map. It appears wider east-west at higher latitudes, which
  correctly represents equal distances in all directions.


================================================================================
11. TIME LAPSE
================================================================================

Time Lapse steps the map through assessment dates, allowing you to
visualize how conditions have changed over time.

Starting and Stopping
----------------------
  View > Time Lapse  (checkbutton — checkmark shows when running)

  A checkmark next to the menu item indicates Time Lapse is active.
  Select it again to cancel.

  If no dated assessments are available, Time Lapse cannot start and
  the checkmark is cleared automatically.

Navigation
----------
  Use the Left and Right arrow keys to step through dates:

  Left arrow   –  Step back one date
  Right arrow  –  Step forward one date

  Dates wrap around at both ends.

Time Lapse Modes
-----------------
  Set in Settings > Filters > Time Lapse Mode:

  Rolling Window (default):
    Shows assessments within a sliding window of N days ending on the
    current playback date. The window size is user-configurable
    (default: 14 days). This is the most useful mode for showing recent
    conditions as the date advances.

  Cumulative:
    Shows all assessments up to and including the current playback date.
    The map "builds up" as time advances. Assessments from the current
    playback date are highlighted.

  Snapshot:
    Shows only assessments from the exact current playback date.

Time Lapse Settings
--------------------
  View > Time Lapse Settings…  opens the full Settings dialog where
  the mode and rolling window size can be configured.


================================================================================
12. ALERT DETECTION
================================================================================

JS8Reporter automatically scans incoming records for ALERT conditions:

  F!505 assessments:  the word "ALERT" in the message text
  F!104 records:      an active alert flag (CSA character 3 = 'E')

When an ALERT Is Detected
--------------------------
  - The ALERT notification bar appears at the top of the window in bold
    red, identifying the form type, callsign, and grid square:
        F!505 ALERT: W4XYZ (EM73)
        F!104 ALERT: K5ABC (DM79)
  - A "Cancel Alert" button appears next to the notification
  - F!505 assessments with an alert are displayed in bold red in the
    assessment list
  - The alerting pin or diamond shows a red "!" badge on the map

  The bar shows the details of the first alert received. Subsequent
  alerts in the same session are recorded but do not update the bar
  text until after Cancel is pressed.

Canceling the Alert
--------------------
  Click the "Cancel Alert" button to dismiss the notification.

  All active alert records of both types are cleared in the current
  session. They will not re-trigger the notification unless new alert
  records arrive after the cancel.

Marking an F!505 Alert Record as Invalid
------------------------------------------
  If an F!505 ALERT record is marked as invalid using the Delete key,
  the notification banner is automatically dismissed (since the record
  is no longer considered active).

Enabling / Disabling ALERT Detection
--------------------------------------
  Settings > Preferences… > Filters tab > Alert enabled checkbox.

Alert Age Threshold
--------------------
  On startup or reload, ALERT records older than a configurable number of
  hours are suppressed automatically — they will not fire the notification
  bar or display "!" badges. This prevents stale alerts from re-triggering
  every time the program is restarted.

  Default: 24 hours.
  Setting: Settings > Preferences… > Filters tab > "Suppress alerts older
           than N hours (on startup/load; 0 = always alert)"

  Set to 0 to disable the threshold and always alert regardless of age.

  Note: An alert received while the program was off will still fire if the
  record falls within the configured window. With the default 24-hour
  threshold, an overnight alert received up to 24 hours ago will still
  trigger the notification when the program starts.

GPIO Alert Output  (Raspberry Pi only)
----------------------------------------
  On a Raspberry Pi, JS8Reporter can drive a GPIO pin to signal an active
  ALERT to external hardware — for example, a warning light or a buzzer
  wired to the pin.

  How it works:
    - The configured GPIO pin goes HIGH when an ALERT is detected.
    - The pin returns LOW when the alert is cancelled (by clicking
      "Cancel Alert" or by marking the ALERT record as invalid).

  To enable:
    Settings > Preferences… > Filters tab > GPIO Alert Output section
      Check: "Drive a GPIO pin HIGH while an ALERT is active"
      Enter the BCM pin number to use (default: 17)
    Click OK, then restart JS8Reporter for the change to take effect.

  Pin numbering:
    The pin number uses Broadcom (BCM) numbering, not physical board
    pin numbers. BCM 17 is physical pin 11 on the 40-pin header.
    Refer to a Raspberry Pi GPIO pinout diagram for other options.

  Hardware wiring note:
    GPIO pins source 3.3 V at low current. For driving an LED directly,
    use a current-limiting resistor (typically 330 Ω). For higher-current
    devices (buzzers, relays), use a transistor or a relay module rated
    for 3.3 V logic.

  Permission requirement:
    The user running JS8Reporter must be a member of the "gpio" group.
    On a standard Raspberry Pi OS installation with the default user,
    this is already the case. If you see a "GPIO Unavailable" warning
    at startup, see Section 17 (Troubleshooting) for instructions.

  This feature is not available on Windows or non-Raspberry Pi Linux
  systems. The GPIO section does not appear in Settings on those platforms.

  If RPi.GPIO is not installed:
    The GPIO Alert Output section still appears on Raspberry Pi hardware,
    but the controls are replaced by a message:
      "RPi.GPIO not found — install it to enable GPIO output:
         pip install RPi.GPIO"
    Install the package (or use the apt method in Section 17) and restart
    JS8Reporter to make the controls appear.


================================================================================
13. REPORTS
================================================================================

The Reports menu generates analytical text reports from the currently
visible assessments (respecting the active Date Filter and Circle Filter).

All reports open in a viewer window with:
  - Full scrollable text display
  - Save to Export Folder button  (saves automatically with a timestamp)
  - Save As… button  (choose any location)
  - Close button

The report header shows which filters were active when the report
was generated.

Report Descriptions
--------------------

Area Assessment Summary
  The primary summary table showing category averages for each reporting
  station, with Min / Max / Avg columns. This is the same table shown
  in the Assessment Detail / Summary Table panel.

Full Detail Report
  Complete field-by-field detail for every visible assessment,
  formatted for printing or filing.

Score Rankings
  All stations sorted from worst to best overall average score.
  Useful for quickly identifying the most severely affected areas.

Category Focus  (submenu)
  Select any of the eight MCF505 categories to see all stations'
  field-level scores for that category only. Stations are sorted
  worst to best for that category.

  Categories available:
    Water          Sewage/Waste   Power          Communications
    Economy        Transportation Health/Safety  Social/Political

Alert Records
  Lists only the assessments that contain an ALERT, with full detail
  for each. Shows "No ALERT records found" if none are present.

Geographic Summary
  Assessments grouped and subtotaled by state, sorted alphabetically.
  Useful for briefing by jurisdiction.

Critical Infrastructure
  Lists every infrastructure field (1–32) that has been scored 0
  (Destroyed) or 1 (Severely Impaired) by any station. Sorted by
  field number, showing which stations reported each critical condition.

Trend Analysis
  Shows only stations that submitted assessments on more than one date,
  with scores for each date and an arrow (↑ / ↓ / →) indicating the
  direction of change. Useful for tracking whether conditions are
  improving or deteriorating.

Infrastructure Heat Map
  For each category, shows how many field scores fall at each level
  (0 / 1 / 2 / 3 / N/A), with percentages. Gives a quick overview of
  the overall distribution of conditions.

Data Quality / Coverage
  Lists each station with the number of fields reported, the completion
  percentage, and the age of the assessment in days. Useful for
  identifying incomplete or outdated reports.

Worst Conditions
  Ranks stations by their single worst category average score (lowest
  first). Highlights where the most severe problems are concentrated.

Network Coverage
  Lists all reporting grid squares with their latitude/longitude
  coordinates and the date of their most recent assessment. Sorted
  north-to-south, west-to-east. Useful for mapping network coverage.

F!104 Summary
  Lists all currently-filtered F!104 Situation Report records in a
  compact table: callsign, grid square, status (code and label), and
  filed date. Records with an active alert are marked with "!".
  Respects the active Date Filter and Circle Filter.


================================================================================
14. EXPORTING DATA
================================================================================

14.1  Save Text Report  (File > Save Text Report…  Ctrl+S)
-----------------------------------------------------------
  Saves a combined text file containing the Area Assessment Summary
  table followed by the full detail for every visible assessment.

14.2  Export F505 Data  (File > Export F505 Data (CSV/TSV)…  Ctrl+T)
----------------------------------------------------------------------
  Exports all visible F!505 assessments as a CSV or TSV file with one
  row per assessment. Columns include callsign, grid, state, timestamps,
  all category averages, and all 32 individual field scores.

  The format (CSV or TSV) is set in Settings > Export.

14.3  Export Map Image  (File > Export Map Image…  Ctrl+E)
----------------------------------------------------------
  Saves the current map view as an image file.
  Supported formats: PNG (default), JPEG, SVG.
  The format is set in Settings > Export.

14.4  Export as F505  (File > Export as F505…)
---------------------------------------------------------------
  Saves all currently loaded and visible assessments to a plain-text
  file in the same F505 format as originally received — either the
  over-the-air JS8Spotter message text, or the format used when
  importing via File > Import F505 File….

  Purpose: compile received F505 reports and transfer them to another
  operator so they can import the file into their copy of JS8Reporter
  using File > Import F505 File….

  The exported file contains one F505 record per line and can be
  re-imported directly. The currently active Date Filter and Circle
  Filter are respected — only visible assessments are included.

  The file is saved to the default export folder unless you choose
  a different location in the Save dialog.

14.5  Export as F104  (File > Export as F104…)
----------------------------------------------
  Saves all currently visible F!104 Situation Report records to a
  plain-text file (one record per line in the over-the-air F!104 format).
  Useful for transferring records to another operator. The exported file
  can also be opened directly in MH Grid Mapper (File > Open Stations…)
  to plot F104 reports on the map.

14.6  Export Flag Pins  (File > Export Flag Pins…)
---------------------------------------------------
  Saves all current flag pins to a .flags.json file in the sitrep_flags
  format, interoperable with MHGridMapper. The station callsign (Settings >
  General) is written as the created_by field. This option is also
  available via the Export button in the View > Flag Pins… dialog.

14.7  Export Folder
--------------------
  Report viewer windows include a "Save to Export Folder" button that
  saves the report automatically to the designated export folder with
  a timestamp-based filename (no dialog required).

  The default export folder is:   <program folder>/data/exports/

  A custom export folder can be set in Settings > Export > Default
  export folder.


================================================================================
15. SETTINGS
================================================================================

Open via Settings > Preferences…

General Tab
-----------
  Station callsign:
    Your amateur radio callsign. Stored in settings and written to the
    created_by field of every flag pin export file, so recipients know
    which station produced the SitRep flag set.

  New pin highlight:
    Enter a number of hours (1–99) to draw a bright magenta ring around
    F!505, F!104, and F!309 pins received within that window. The ring
    makes recently-arrived pins stand out against busy topo or shapefile
    backgrounds. Set to 0 (default) to disable.

Pin Colors Tab
--------------
  Pin color mode:
    Controls what score drives the color of each map pin.
    Options: Lowest all fields, Average all fields (default),
             Average in category, Lowest in category.

  Category:
    The category used when a category-specific pin color mode is selected.

  Rounding for averages:
    How averaged scores are rounded to a whole-number color level.
    Options: Standard rounding (default), Always round up, Always round down.

  Map pin labels:
    When checked, each pin shows the callsign and score.
    When unchecked, only the color pin is shown (click to see details).

Filters Tab
-----------
  Duplicate grid-square handling:
    When two assessments share the same grid square, use only the most
    recent (default) or average the scores.

  Category display filter:
    Limit the map and reports to selected categories only.
    Leave all checked (default) to include all categories.

  Time Lapse mode:
    Rolling Window (default), Cumulative, or Snapshot. See Section 11.

  Rolling window days:
    Number of days in the rolling window (default: 14).

  Alert enabled:
    Enable or disable ALERT detection.

  GPIO Alert Output  (Raspberry Pi only — section visible only on Pi):
    Enable or disable GPIO pin output during an active ALERT.
    BCM pin number: the Broadcom pin number to drive (default: 17).
    Changes take effect after restarting JS8Reporter.
    If RPi.GPIO is not installed, the controls are replaced by an install
    hint; see Section 12 for full details, wiring notes, and permissions.

Circle Tab
----------
  Circle center latitude and longitude, and radius in miles.
  These can also be set by clicking on the map (Circle > Set Circle
  Center…) or via Circle > Configure Circle….

Export Tab
----------
  Map image format:  PNG (default), JPEG, SVG.

  Tabular data export format:  CSV (default) or TSV.

  Default export folder:
    Folder used by "Save to Export Folder" in report windows.
    Leave blank to use the default  data/exports/  folder.
    Click Browse… to select a folder.

  Import Records folder:
    Folder scanned by File > Import All Files from Folder….
    Leave blank to use the default  data/imports/  folder.
    Click Browse… to select a folder.

Auto-Update Tab
---------------
  Check for updates on startup:
    When enabled, JS8Reporter checks SitRepNet.com for a newer release
    at startup (requires internet). Offline operation is never affected.

  Version check URL:
    The URL used for version checks. Defaults to the SitRepNet.com
    JS8Reporter download page. Leave blank to disable.

Tools Menu
----------
  The Tools menu provides utility functions not specific to data loading
  or export:

  Grid Converter…
    Opens the Grid Converter dialog. See Section 7.6.


================================================================================
16. KEYBOARD SHORTCUTS
================================================================================

  Escape    Exit Pan or Zoom map mode; dismiss right-click context menus

  Delete    Mark selected assessment as invalid / restore if invalid

  + or =    (in date field) Advance date by one day
  -         (in date field) Move date back by one day

  Left      (Time Lapse) Step back one date
  Right     (Time Lapse) Step forward one date


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

No assessments loaded from the database
-----------------------------------------
  Use Help > DB Diagnostic… to inspect the database. JS8Reporter looks
  for rows in the "forms" table with typeid containing "505". Verify
  that JS8Spotter has received and stored at least one MCF505 form.

  Common causes:
    - The database file selected is not a JS8Spotter database
    - No MCF505 forms have been received yet
    - The forms were stored under an unexpected typeid value
      (the diagnostic will show what typeids are present)

No F!104 pins appear after opening the database
-------------------------------------------------
  F!104 records are loaded automatically alongside F!505 records when
  a database is opened. If no diamonds appear:

    - Confirm View > Show F!104 Pins has a checkmark.
    - Verify the database contains F!104 records: use Help > DB
      Diagnostic… and check for a typeid value of "F!104".
    - Confirm the active Date Filter includes the dates of those records.
    - If the records arrived recently, wait up to one minute for the
      automatic background poll to pick them up, or use View > Refresh
      Map to force an immediate update.

Map pins appear but in the wrong location
------------------------------------------
  The grid square field in the assessment may contain an invalid or
  unusual grid locator. Select the assessment and check the Grid field
  in the detail panel.

Date filter is not showing expected assessments
------------------------------------------------
  Verify the From and To dates are entered correctly in YYYY/MM/DD
  format. Check that the Enable checkbox is checked and Apply was
  pressed.

  Also check whether the assessment's date falls in the filter range.
  The filter uses the received date if available, otherwise the
  report prepared date.

Time Lapse starts but the map does not change
----------------------------------------------
  If only one unique date is present in the visible assessments, Time
  Lapse has nothing to step through. Try disabling the Date Filter or
  expanding the date range.

Auto-update check fails silently
----------------------------------
  The update check runs in the background and fails silently if the
  network is unavailable. This is by design — offline operation is
  never affected.

  To disable the check entirely: Settings > Preferences > Auto-Update >
  uncheck "Check for updates on startup".

GPIO controls not visible in Settings > Preferences… > Filters tab  (Raspberry Pi)
-----------------------------------------------------------------------------------
  The GPIO Alert Output section is shown on Raspberry Pi hardware but the
  controls are replaced by a red message if RPi.GPIO is not installed.

  To install RPi.GPIO:
    Option 1 — pip (inside the JS8Reporter virtual environment):
         ~/js8reporter/venv/bin/pip install RPi.GPIO --ignore-installed

      Note: plain "pip install RPi.GPIO" may report "Requirement already
      satisfied" even though the package is not inside the venv.  The
      --ignore-installed flag forces it to install correctly.

    Option 2 — apt (system-wide):
         sudo apt install python3-rpi.gpio

  After installing, restart JS8Reporter. The controls will appear.

"GPIO Unavailable" warning at startup  (Raspberry Pi)
------------------------------------------------------
  JS8Reporter displays this warning when GPIO alert output is enabled
  in Settings but the GPIO pin could not be initialized.

  Most common cause: the user running JS8Reporter is not a member of
  the "gpio" group.

  To fix:
    1. Open a terminal and run:
           sudo usermod -aG gpio <your-username>
       (replace <your-username> with your actual username)

    2. Log out and log back in, or reboot, for the group change
       to take effect.

    3. Restart JS8Reporter.

  To verify group membership before restarting:
       groups
  The word "gpio" should appear in the output.

  If the warning persists after adding the user to the gpio group and
  logging back in, confirm that RPi.GPIO is installed:
       /home/<username>/js8reporter/venv/bin/python3 -c "import RPi.GPIO"
  If that command reports an error, see the entry above for install steps.


================================================================================
  End of JS8Reporter User Manual
  JS8Reporter is designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================
