===============================================================================
  505PROCESSOR  —  F!505 Area Assessment Record Processor
  User Manual  —  Version 1.0.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 Records
        4.2  Extract 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
===============================================================================

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

Two operations are provided:

  Combine Records
      Reads all .txt and .csv files from a folder, validates and
      deduplicates them, 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 Records
      Reads a single file and filters records by date/time range and/or
      Maidenhead grid prefix.  Use this when you need a subset of records
      from a larger collection.

505Processor 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 505Processor by double-clicking the 505Processor icon on
     your Desktop.  See the Installation Guide for first-time setup.

  2. Select Operations > Combine Records or Operations > Extract Records
     from the menu bar.

  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 Records or Extract 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 Records
  ─────────────────────────────────────────────────────────────────────────────

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

  To use:
      1. Open Operations > Combine 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 Records
  ─────────────────────────────────────────────────────────────────────────────

  Purpose:  Filter records from a single file by date/time range and/or
            Maidenhead grid prefix.

  To use:
      1. Open Operations > Extract 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:
      - 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 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 Combine Records.
      Also updated automatically each time you run Combine Records.

  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.  Select the one that matches what
  JS8Reporter expects or what is most useful for your workflow.

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

      Example line:
          33333333333333333333333333333333 GR[EL99HC] #CTKP

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

  Minimal + Date Decode
      Same as Minimal, but appends the decoded UTC date and time as a
      human-readable string after the datecode.

      Example line:
          33333333333333333333333333333333 GR[EL99HC] #CTKP 2026-05-18 14:30 UTC

      The date/time text is for reference when viewing the file in a
      text editor; it has no effect on JS8Reporter import.

  Full
      Writes a complete record with the F!505 marker and all available
      fields: state, grid, city, and datecode.

      Example line:
          F!505 33333333333333333333333333333333 ST[FL] GR[EL99HC] CT[VOLUSIA] #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 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.
      State and city are not written if a grid is present.
      Use Full format if you need all location fields preserved.

  Save Combine Records summary to a .txt file
      When checked, a summary file is written alongside the output file
      after each Combine Records run, named:
          f505_combined_YYYYMMDD_HHMMSS_SUMMARY.txt
      It contains the same information shown in the main log.

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

  Check for updates on startup
      When checked, 505Processor 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.

Location:
    Place IGNORE.TXT in the same folder as processor505.py (the main
    505Processor 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, 505Processor 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 Records:   f505_combined_YYYYMMDD_HHMMSS.txt
      Extract Records:   f505_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 lines skipped   — lines that could not be parsed
      Grid locations          — all unique Maidenhead locators in output

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

505Processor recognizes the following input file types automatically.

  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.

  Minimal-format .txt files
      Output files from a previous 505Processor 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.
      505Processor recognizes this format automatically.

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

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

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

  For each file, 505Processor reports how many lines were valid and
  how many could not be parsed.

  Note:  Combine Records reads every .txt and .csv file it finds in the
  input folder.  If you keep your input and output folders separate you
  will avoid accidentally re-reading previous output in a later run.

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

  1. Run Combine Records or Extract Records in 505Processor.
  2. Note the output file path shown in the log or status bar.
  3. In JS8Reporter, open the F!505 import function.
  4. Select the output file created by 505Processor.
  5. JS8Reporter reads and displays the records.

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

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

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

  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
      Two records are considered duplicates when they share the same
      score string, grid locator, and datecode.  Differences in state
      or city alone do not prevent deduplication.  Callsigns (from CSV)
      are not part of the duplicate key.

  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 Records,
          even when a date range is specified.

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

  Launching 505Processor
      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 505Processor 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 processor505.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
      505Processor folder, run setup.py again to recreate the Desktop
      shortcut and dash icon pointing to the new location.

  Internet access
      505Processor 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
===============================================================================

  505Processor Version 1.0.0
  F!505 Area Assessment 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
===============================================================================
