===============================================================================
  SitRepTools  —  F!505 and F!104 Record Processor
  User Manual  —  Version 1.1.0
===============================================================================

  Designed and developed by Stephen Clay McGehee, KN4AM
  SitRepNet.com

-------------------------------------------------------------------------------
  TABLE OF CONTENTS
-------------------------------------------------------------------------------

  1.  Introduction
  2.  Quick Start
  3.  Main Window
  4.  Operations
        4.1  Combine F!505 Records
        4.2  Extract F!505 Records
        4.3  Combine F!104 Records
        4.4  Extract F!104 Records
  5.  Preferences
        5.1  Folders
        5.2  Output Format
        5.3  Auto-Update
  6.  IGNORE.TXT
  7.  Output Files
        7.1  File Naming
        7.2  Export Formats
        7.3  Summary File
  8.  Accepted Input Formats
  9.  Importing into JS8Reporter
  10. Notes and Tips
  11. About

===============================================================================
  SECTION 1 — INTRODUCTION
===============================================================================

SitRepTools is a utility for net operators running F!505 Area Assessment
and F!104 Situation Report nets.  It reads records from one or more files,
combines and deduplicates them, and writes clean output files that can be
imported directly into JS8Reporter.

Four operations are provided:

  Combine F!505 Records
      Reads all .txt and .csv files from a folder, validates and
      deduplicates F!505 records, sorts by timestamp, and writes a
      single output file.  Use this when you have received F!505 export
      files from multiple stations and need to merge them into one.

  Extract F!505 Records
      Reads a single file and filters F!505 records by date/time range
      and/or Maidenhead grid prefix.  Use this when you need a subset of
      records from a larger collection.

  Combine F!104 Records
      Same as Combine F!505 Records, but for F!104 Situation Report
      records.

  Extract F!104 Records
      Same as Extract F!505 Records, but for F!104 Situation Report
      records.

SitRepTools does not require an internet connection to operate.  An
optional automatic update check notifies you when a new version is
available at SitRepNet.com.

===============================================================================
  SECTION 2 — QUICK START
===============================================================================

  1. Launch SitRepTools by double-clicking the SitRepTools icon on
     your Desktop.  See the Installation Guide for first-time setup.

  2. Select the desired operation from the Operations menu.

  3. Browse to the required input folder or file.

  4. Confirm or change the output folder and filename.

  5. Click Run.

  6. The result summary appears in the main log area.  The output file
     is ready to import into JS8Reporter.

===============================================================================
  SECTION 3 — MAIN WINDOW
===============================================================================

The main window contains three areas:

  Menu bar
      Operations  — run Combine F!505, Extract F!505, Combine F!104,
                    or Extract F!104 Records
      Settings    — open Preferences
      Help        — About dialog

  Log area
      Scrollable display showing messages, operation summaries, and
      results.  The log is replaced after each operation.

  Status bar
      One-line summary at the bottom showing the most recent operation
      name, output filename, and record count.

On startup, the log shows the program version and whether an IGNORE.TXT
file was found.  Window size and position are saved automatically when
you close the program.

===============================================================================
  SECTION 4 — OPERATIONS
===============================================================================

  ─────────────────────────────────────────────────────────────────────────────
  4.1  Combine F!505 Records
  ─────────────────────────────────────────────────────────────────────────────

  Purpose:  Merge F!505 Area Assessment records from multiple files into
            one output file, removing duplicates in the process.

  To use:
      1. Open Operations > Combine F!505 Records.

      2. In the Input folder field, browse to or type the path of the
         folder containing your F!505 export files (.txt and/or .csv).

      3. In Output folder and Output filename, confirm or change the
         destination.  The default output filename is:
             f505_combined_YYYYMMDD_HHMMSS.txt

      4. Click Run.

  What Combine Records does:
      - Reads all .txt and .csv files in the input folder.  Subfolders
        are not searched.
      - Validates each line.  Invalid lines are counted and skipped.
      - Removes duplicate records.  Two records are considered duplicates
        if they share identical score strings, grid locators, and
        datecodes.
      - Sorts the remaining records by UTC timestamp, earliest first.
        Records with no datecode appear at the end.
      - Writes the output file in the format selected in Preferences >
        Output Format.

  After the run, the log shows a summary: record count, earliest and
  latest timestamps, duplicate and invalid counts, and grid locators.

  The input and output folder selections are saved as new defaults for
  the next run.

  Note on IGNORE.TXT:
      Callsign filtering is only effective when input files are in CSV
      format and include callsign information.  Plain .txt export files
      do not contain callsigns; IGNORE.TXT has no effect on them.
      See Section 6 for details.

  ─────────────────────────────────────────────────────────────────────────────
  4.2  Extract F!505 Records
  ─────────────────────────────────────────────────────────────────────────────

  Purpose:  Filter F!505 Area Assessment records from a single file by
            date/time range and/or Maidenhead grid prefix.

  To use:
      1. Open Operations > Extract F!505 Records.

      2. In the Input file field, browse to or type the path of the file
         to read.

      3. Optionally enter a date/time range in UTC:
           From — earliest date/time to include (YYYY-MM-DD HH:MM)
           To   — latest date/time to include   (YYYY-MM-DD HH:MM)
         You may enter just a date (YYYY-MM-DD) to mean midnight UTC.
         Leave either field blank to apply no limit on that end.

      4. Optionally enter a Grid prefix filter.
         Examples:  EL    — include only records in EL grids
                    EL99  — include only records in grid square EL99
                    EM85  — include only records in grid square EM85

      5. In Output folder and Output filename, confirm or change the
         destination.  The default output filename is:
             f505_extract_YYYYMMDD_HHMMSS.txt

      6. Click Run.

  Date/time range behavior (F!505):
      - A record is included if its timestamp falls within [From, To],
        inclusive on both ends.
      - Records with no datecode (no timestamp) are always included,
        regardless of any date/time filter.
      - If only From is given, all records from that time forward are
        included (plus records with no timestamp).
      - If only To is given, all records up to that time are included
        (plus records with no timestamp).

  Grid prefix behavior:
      - Only records whose grid locator begins with the prefix are
        included.  Matching is case-insensitive.
      - Records with no grid locator are excluded when a prefix filter
        is active.
      - Leave the field blank to include records from all grids.

  Output, deduplication, and sorting work the same as Combine F!505 Records.

  The output folder selection is saved as the new default.

  ─────────────────────────────────────────────────────────────────────────────
  4.3  Combine F!104 Records
  ─────────────────────────────────────────────────────────────────────────────

  Purpose:  Merge F!104 Situation Report records from multiple files into
            one output file, removing duplicates in the process.

  To use:
      1. Open Operations > Combine F!104 Records.

      2. In the Input folder field, browse to or type the path of the
         folder containing your F!104 files (.txt and/or .csv).

      3. In Output folder and Output filename, confirm or change the
         destination.  The default output filename is:
             f104_combined_YYYYMMDD_HHMMSS.txt

      4. Click Run.

  What Combine F!104 Records does:
      - Reads all .txt and .csv files in the input folder.
      - Validates each record.  A valid F!104 record must have a CSA
        status code (e.g. 100, 200, 30E) and at least one of: grid
        square or state.  Invalid records are counted and skipped.
      - Removes duplicate records.  Two records are considered duplicates
        if they share identical CSA codes, grid locators, and datecodes.
      - Sorts the remaining records by UTC timestamp, earliest first.
        Records with no datecode appear at the end.
      - Writes the output file in the format selected in Preferences >
        Output Format (see Section 5.2).

  After the run, the log shows a summary: record count, date range,
  status breakdown (Normal / Degraded / Problems), active alert count,
  duplicate and invalid counts, and grid locators covered.

  Note on IGNORE.TXT:
      Callsign filtering only applies when input files include callsign
      data (CSV format).  See Section 6.

  ─────────────────────────────────────────────────────────────────────────────
  4.4  Extract F!104 Records
  ─────────────────────────────────────────────────────────────────────────────

  Purpose:  Filter F!104 Situation Report records from a single file by
            date/time range and/or Maidenhead grid prefix.

  To use:
      1. Open Operations > Extract F!104 Records.

      2. In the Input file field, browse to or type the path of the file
         to read.

      3. Optionally enter a date/time range in UTC:
           From — earliest date/time to include (YYYY-MM-DD HH:MM)
           To   — latest date/time to include   (YYYY-MM-DD HH:MM)
         You may enter just a date (YYYY-MM-DD) to mean midnight UTC.
         Leave either field blank to apply no limit on that end.

      4. Optionally enter a Grid prefix filter.
         Examples:  EL    — include only records in EL grids
                    EL99  — include only records in grid square EL99

      5. In Output folder and Output filename, confirm or change the
         destination.  The default output filename is:
             f104_extract_YYYYMMDD_HHMMSS.txt

      6. Click Run.

  Date/time range and grid prefix behavior for F!104 is identical to the
  F!505 Extract operation described in Section 4.2.

  Output, deduplication, and sorting work the same as Combine F!104 Records.

  The output folder selection is saved as the new default.

===============================================================================
  SECTION 5 — PREFERENCES
===============================================================================

  Open via Settings > Preferences.  Changes take effect when you click Save.

  ─────────────────────────────────────────────────────────────────────────────
  5.1  Folders
  ─────────────────────────────────────────────────────────────────────────────

  Default input folder
      Pre-fills the Input folder field when you open a Combine operation.
      Also updated automatically each time you run a Combine operation.

  Default output folder
      Pre-fills the Output folder field in both operations.
      Updated automatically after each successful run.

  ─────────────────────────────────────────────────────────────────────────────
  5.2  Output Format
  ─────────────────────────────────────────────────────────────────────────────

  Three export formats are available.  The same setting applies to all
  four operations.  Select the one that matches your workflow.

  Minimal (default)
      F!505: writes the score string, one location field (grid preferred,
      then state, then city), and the datecode.  No F!505 marker.

          33333333333333333333333333333333 GR[EL99HC] #CTKP

      F!104: writes the F!104 marker, CSA code, and one location field.
      The F!104 marker is always included (unlike F!505 Minimal) because
      there is no score string to identify the record without it.

          F!104 200 GR[EL99HC]

      This is the standard import format for JS8Reporter.  Most
      operators should use this setting.

  Minimal + Date Decode
      Same as Minimal for each form type, but appends the decoded UTC
      date and time as a human-readable string.

          33333333333333333333333333333333 GR[EL99HC] #CTKP 2026-05-18 14:30 UTC
          F!104 200 GR[EL99HC] 2026-05-18 14:30 UTC

      The date/time text is for reference only; it has no effect on
      JS8Reporter import.

  Full
      Writes a complete record with the form marker and all available
      fields.

      F!505:
          F!505 33333333333333333333333333333333 ST[FL] GR[EL99HC] CT[VOLUSIA] #CTKP

      F!104:
          F!104 200 ST[FL] GR[EL99HC] #CTKP

      Use Full format when you want the output file to serve as input
      for another run (all fields are preserved), or for archival.

  Important note on F!505 Minimal format:
      When a record has multiple location fields (state, grid, city),
      Minimal format writes only the highest-priority one:
          grid  is written if present; otherwise
          state is written if present; otherwise
          city  is written.
      Use Full format if you need all location fields preserved.
      F!104 Minimal uses the same priority (grid preferred, then state).

  Save Combine Records summary to a .txt file
      When checked, a summary file is written alongside the output file
      after each Combine operation (F!505 or F!104), named:
          f505_combined_YYYYMMDD_HHMMSS_SUMMARY.txt
          f104_combined_YYYYMMDD_HHMMSS_SUMMARY.txt
      It contains the same information shown in the main log.

  Include ALERT in exported records
      Applies to F!505 only.  When checked, any F!505 record that
      contained the ALERT keyword on import will have ALERT appended to
      its output line.  This option is off by default.

          33333333333333333333333333333333 GR[EL99HC] #CTKP ALERT
          F!505 33333333333333333333333333333333 ST[FL] GR[EL99HC] CT[VOLUSIA] #CTKP ALERT

      For F!104 records, alert status is always encoded in the CSA string
      (third character = E when an alert is active) and is therefore
      always present in output regardless of this setting.

  ─────────────────────────────────────────────────────────────────────────────
  5.3  Auto-Update
  ─────────────────────────────────────────────────────────────────────────────

  Check for updates on startup
      When checked, SitRepTools contacts SitRepNet.com on startup to
      check for a newer version.  If one is found, a dialog appears
      offering to open the download page.
      Uncheck this box to disable automatic update checks.

  Version check URL
      The URL used for the update check.  The default points to
      SitRepNet.com and does not normally need to be changed.

      Note: offline operation is never affected by this setting.  If the
      update check fails for any reason (no internet, server unreachable),
      it is silently ignored and the program continues normally.

===============================================================================
  SECTION 6 — IGNORE.TXT
===============================================================================

IGNORE.TXT is an optional file that excludes records from specific
callsigns.  It applies to all four operations (F!505 and F!104).

Location:
    Place IGNORE.TXT in the same folder as sitreptools.py (the main
    SitRepTools program file).

Format:
    One callsign per line.
    Lines beginning with # are treated as comments.
    Blank lines are ignored.
    Matching is case-insensitive.

    Example IGNORE.TXT:
        # Stations to exclude
        W1AW
        K0ABC
        N0TEST

Behavior:
    - Callsign filtering only applies to input files that contain
      callsign data.  JS8Reporter CSV exports include callsigns;
      plain .txt exports do not.  IGNORE.TXT has no effect when
      reading plain .txt files.
    - Records excluded by IGNORE.TXT are counted in the "IGNORE.TXT
      removed" line of the operation summary.
    - If IGNORE.TXT is not present, no callsign filtering is applied.

At startup, SitRepTools reports whether IGNORE.TXT was found and how
many entries it contains.

===============================================================================
  SECTION 7 — OUTPUT FILES
===============================================================================

  ─────────────────────────────────────────────────────────────────────────────
  7.1  File Naming
  ─────────────────────────────────────────────────────────────────────────────

  Default output filenames are generated using the UTC date and time at
  the moment the dialog opens:

      Combine F!505 Records:   f505_combined_YYYYMMDD_HHMMSS.txt
      Extract F!505 Records:   f505_extract_YYYYMMDD_HHMMSS.txt
      Combine F!104 Records:   f104_combined_YYYYMMDD_HHMMSS.txt
      Extract F!104 Records:   f104_extract_YYYYMMDD_HHMMSS.txt

  You may type any valid filename in the Output filename field before
  clicking Run.  If you omit the .txt extension it is added automatically.

  If the output path already exists, it is overwritten without warning.

  ─────────────────────────────────────────────────────────────────────────────
  7.2  Export Formats
  ─────────────────────────────────────────────────────────────────────────────

  See Section 5.2 for a description of each export format and example
  output lines.

  The output file contains one record per line with no blank lines.

  ─────────────────────────────────────────────────────────────────────────────
  7.3  Summary File
  ─────────────────────────────────────────────────────────────────────────────

  After each operation the log and (optionally) the _SUMMARY.txt file
  display:

      Records in output       — number of records written to the file
      Earliest datetime       — UTC timestamp of the oldest record
      Latest datetime         — UTC timestamp of the newest record
      Duplicates removed      — records discarded as duplicates
      IGNORE.TXT removed      — records excluded by callsign filter
      Invalid / skipped       — lines that could not be parsed
      Grid squares covered    — all unique Maidenhead locators in output

  F!104 operations additionally show a status breakdown:

      1 Normal                — count of status-1 records in output
      2 Degraded              — count of status-2 records in output
      3 Problems              — count of status-3 records in output
      ALERT active            — count of records with alert flag set (CSA[2] = E)

===============================================================================
  SECTION 8 — ACCEPTED INPUT FORMATS
===============================================================================

SitRepTools recognizes the following input file types automatically.
The F!505 and F!104 operations each parse only their own form type from
any given file.

  F!505 — JS8Reporter export files (.txt)
      Standard format produced by JS8Reporter's F!505 export.  Each
      record begins with the F!505 marker.  Multiple records per file
      are supported.

  F!505 — Minimal-format .txt files
      Output files from a previous SitRepTools run in Minimal or
      Minimal + Date Decode format.  Each line has a score string and
      optional location field and datecode, without the F!505 marker.
      SitRepTools recognizes this format automatically.

  F!505 — Full-format .txt files
      Output from a previous SitRepTools run in Full format, or any
      plain-text file containing standard F!505 records with the F!505
      marker.

  F!104 — Plain-text files (.txt)
      Any plain-text file containing F!104 records.  Each record must
      contain the F!104 marker and a valid CSA status code (three
      characters: status + sitrep + alert, e.g. 100, 200, 30E).

  F!104 — SitRepTools output files (.txt)
      Output files from a previous Combine or Extract F!104 run in any
      of the three export formats.

  JS8Spotter CSV exports (.csv) — both form types
      Comma-separated files with a header row.  SitRepTools looks for
      common column names (msgtxt, fromcall, etc.).  Callsign data from
      CSV files is used for IGNORE.TXT filtering.

  F!505 ALERT keyword
      If an imported F!505 record contains the word ALERT, that flag is
      preserved internally.  Whether ALERT appears in the output file
      depends on the "Include ALERT in exported records" setting in
      Preferences > Output (see Section 5.2).

  F!104 alert status
      F!104 alert status is encoded in the CSA string (third character
      = E when an alert is active) and is always preserved in output.

  Character encoding
      Character encoding errors are handled gracefully.  Undecodable
      characters are replaced and processing continues.

  For each file, SitRepTools reports how many records were valid and
  how many could not be parsed.

  Note:  Combine operations read every .txt and .csv file in the input
  folder.  Keep input and output folders separate to avoid re-reading
  previous output in a later run.

===============================================================================
  SECTION 9 — IMPORTING INTO JS8REPORTER
===============================================================================

  Importing F!505 records:
      1. Run Combine F!505 Records or Extract F!505 Records.
      2. Note the output file path shown in the log or status bar.
      3. In JS8Reporter, use File > Import F505 File… and select the
         output file.
      4. JS8Reporter reads and displays the F!505 assessment pins.

  Importing F!104 records:
      1. Run Combine F!104 Records or Extract F!104 Records.
      2. Note the output file path shown in the log or status bar.
      3. In JS8Reporter, use File > Import F!104 File… and select the
         output file.
      4. JS8Reporter reads and displays the F!104 situation report
         diamond pins.

  Importing both form types at once:
      If your input files contain both F!505 and F!104 records, run
      both the F!505 and F!104 Combine or Extract operations on the
      same input folder/file, then import each output file into
      JS8Reporter using the appropriate import menu item.

      Alternatively, use JS8Reporter's File > Import All Files from
      Folder, which automatically detects and loads both form types
      from all files in the configured import folder.

  The Minimal format output is designed for direct JS8Reporter import.
  If JS8Reporter does not recognize a file, try the Full format
  (Settings > Preferences > Output > Full).

===============================================================================
  SECTION 10 — NOTES AND TIPS
===============================================================================

  Re-using output as input
      Output files from SitRepTools (all three formats) can be used
      as input for a later Combine or Extract operation.

  Input and output folders
      Keep your input and output folders separate when using Combine
      Records.  If they are the same folder, output files from previous
      runs will be included in the next run.  Deduplication handles this
      correctly, but the result may be confusing.

  Duplicate detection
      F!505: two records are duplicates when they share the same score
      string, grid locator, and datecode.  Differences in state or city
      alone do not prevent deduplication.

      F!104: two records are duplicates when they share the same CSA
      code, grid locator, and datecode.

      Callsigns (from CSV input) are not part of the duplicate key for
      either form type.

  Records without timestamps
      Some records may lack a datecode and therefore have no timestamp.
      These records:
        - Are valid and will appear in output.
        - Are placed at the end of the output file, after all
          timestamped records.
        - Always pass through date/time range filters in Extract operations,
          even when a date range is specified.

  Datecode year
      The datecode encodes month, day, hour, and minute but not year.
      SitRepTools assumes the current calendar year when decoding.
      If your data spans a year boundary, verify that timestamps decode
      to the correct year.

  Launching SitRepTools
      Use the Desktop shortcut created by setup.py, or run run.sh
      (Linux/Raspberry Pi) or run.bat (Windows) directly.  On GNOME
      desktops (Ubuntu and similar), setup.py also pins SitRepTools to
      the dash so you can launch it from the icon bar on the side of the
      screen; clicking the dash icon while the app is running brings the
      window to the foreground.  Do not move sitreptools.py to a
      different folder; the run scripts and the program use their location
      to find data files, IGNORE.TXT, and the icon.  If you move the
      SitRepTools folder, run setup.py again to recreate the Desktop
      shortcut and dash icon pointing to the new location.

  Internet access
      SitRepTools does not require internet access.  The automatic
      update check is the only network activity and fails silently when
      the network is unavailable.

===============================================================================
  SECTION 11 — ABOUT
===============================================================================

  SitRepTools Version 1.1.0
  F!505 and F!104 Record Processor

  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding assistance: Claude Code AI

  For information, downloads, and updates:
      SitRepNet.com

  F!505 Area Assessment is part of the SitRep Net protocol.
  JS8Reporter is required to use the records produced by this program.

===============================================================================
  END OF USER MANUAL
===============================================================================
