================================================================================
SitRepMapper v1.12.1 – Installation Guide

Designed and developed by Stephen Clay McGehee, KN4AM
Coding done using Claude Code AI
See SitRepNet.com for more information
================================================================================


UPDATING FROM AN OLDER VERSION
-------------------------------
  Already have SitRepMapper installed? Updating uses the exact same steps
  as a fresh install (Section 2 or 3 below) — just extract the new ZIP
  into your existing SitRepMapper folder instead of a new one, overwriting
  files when prompted, then restart the program. There is no separate
  update package or procedure.

  Nothing else to do first:
    - Settings, flag pins, and areas are stored in your config folder
      (~/.config/sitrepmapper/ on Linux/Raspberry Pi, C:\Users\<username>\
      .config\sitrepmapper\ on Windows), not the program folder, so they
      are never touched by extracting the ZIP.
    - Tile data is not part of the ZIP at all, so your tiles/ folder (or
      flash drive) is unaffected either way.
    - Re-running Step 2 (pip install) in Section 2 or 3 is optional —
      harmless if nothing changed, only actually needed if
      SitRepMapper_CHANGELOG.txt mentions a new required package.

  See SitRepMapper_CHANGELOG.txt for what's new in this version.


TABLE OF CONTENTS
-----------------
  1.  System Requirements
  2.  Installation: Linux / Raspberry Pi
  3.  Installation: Windows
  4.  The Desktop Launcher (Linux / Raspberry Pi)
  5.  Starting the Program
  6.  Tile Data Setup
  7.  Troubleshooting


================================================================================
1.  SYSTEM REQUIREMENTS
================================================================================

Supported Platforms
-------------------
  - Raspberry Pi 4B running Raspberry Pi OS Bookworm or Bullseye (primary)
  - Linux (Ubuntu, Debian, and derivatives)
  - Windows 10 / 11

Python Version
--------------
  Python 3.9 or newer is required.

  Check your version:
      python3 --version       (Linux / Raspberry Pi)
      python  --version       (Windows)

Internet Connection
--------------------
  An internet connection is required for the initial package installation
  and tile data download only. After that, SitRepMapper runs completely
  offline.

Required Python Packages
--------------------------
  Pillow    >= 9.2    (map tile rendering; also Export Map Image, which
                       additionally needs Ghostscript — a system package,
                       not a Python one; see Section 7)
  mgrs      >= 1.4    (MGRS/USNG coordinate conversion, Tools > Grid Converter)
  requests  >= 2.28   (for TileDownloader, bundled in the tiledownloader/
                       subfolder — File > Download Tiles…)

  Tkinter is also required. It is pre-installed on Raspberry Pi OS and most
  Linux distributions. See Troubleshooting (Section 7) if it is missing.

  Neither JS8Spotter nor JS8Call is required to run SitRepMapper, but you
  need one of the two (JS8Spotter's database, or JS8Call's own Directed
  Log — see the User Manual's REPORT SOURCES section) to have any
  F!505/F!104/F!309/CommStat reports to display.

JS8Call Send Feature (Optional)
----------------------------------
  Sending F!104/F!309/F!505/CommStat reports (the Send menu — see the User
  Manual's SENDING REPORTS section) requires JS8Call itself, with two
  settings enabled on JS8Call's own Settings > Reporting tab:
    - "Enable TCP Server API" — turned on (SitRepMapper connects to
      127.0.0.1:2442, JS8Call's own default port)
    - "TCP Max Connections" — raised to at least 2. SitRepMapper's Send
      feature holds one API connection open for its entire runtime, so
      JS8Call's default cap of 1 will reject SitRepMapper outright
      whenever JS8Spotter (or any other API client) is also connected —
      even if neither program is actively sending anything at that moment.
  This is entirely optional: SitRepMapper's map and report-viewing
  features never touch JS8Call's API, and work exactly the same whether
  or not these two settings are changed.


================================================================================
2.  INSTALLATION: LINUX / RASPBERRY PI
================================================================================

Step 1 — Copy the program files
---------------------------------
  Place the sitrepmapper folder wherever you prefer. The recommended
  location for a single-user installation is the home directory:

      /home/<username>/sitrepmapper

  For a system-wide installation accessible to all users, use:

      /opt/sitrepmapper

  The .desktop launcher file is pre-configured for /opt/sitrepmapper. If
  you install to a different location, see Section 4 for how to adjust
  the paths.

Step 2 — Install Python packages
----------------------------------
  Open a terminal and run:

      pip3 install Pillow mgrs requests

  If you see an error about "externally managed environment" (common on
  Ubuntu 23.04 and newer, Raspberry Pi OS Bookworm and newer), use one of
  these alternatives:

  Option A — Install for the current user only (recommended):
      pip3 install --user Pillow mgrs requests

  Option B — Install system-wide (requires elevated privileges):
      pip3 install Pillow mgrs requests --break-system-packages

  Option C — Use a virtual environment (cleanest approach):
      cd /home/<username>/sitrepmapper
      python3 -m venv venv
      venv/bin/pip install Pillow mgrs requests

      If using a virtual environment, replace all python3 and pip3 commands
      in these instructions with:
          /home/<username>/sitrepmapper/venv/bin/python3
          /home/<username>/sitrepmapper/venv/bin/pip

Step 3 — Install the desktop launcher
---------------------------------------
  See Section 4 for full details on the desktop launcher.

  Quick install (adjust the path to match your installation location):
      sed 's|/opt/sitrepmapper|/home/<username>/sitrepmapper|g' \
          /home/<username>/sitrepmapper/sitrepmapper.desktop \
          > ~/.local/share/applications/sitrepmapper.desktop
      cp ~/.local/share/applications/sitrepmapper.desktop ~/Desktop/
      update-desktop-database ~/.local/share/applications

  Or install from /opt (if using the recommended system-wide path, no
  path substitution is needed):
      cp /opt/sitrepmapper/sitrepmapper.desktop \
          ~/.local/share/applications/
      cp /opt/sitrepmapper/sitrepmapper.desktop ~/Desktop/
      chmod +x ~/Desktop/sitrepmapper.desktop
      update-desktop-database ~/.local/share/applications

Step 4 — TileDownloader (included — nothing to do)
--------------------------------------------------------------------------
  File > Download Tiles… launches TileDownloader, a separate standalone
  program, as an independent process — it's bundled with SitRepMapper as
  a tiledownloader/ subfolder inside your install, so there is nothing
  extra to install or download. See tiledownloader/UserGuide.txt for how
  to use it (choosing an area, zoom levels, and managing your tile
  library).

  If you're working from a dev checkout instead of a packaged release,
  SitRepMapper also looks for it at ~/ClaudeProjects/tiledownloader/
  main.py as a sibling repo, so the two can be developed independently
  without the subfolder being present.

  TileDownloader is entirely optional: without it, tiles can still be
  produced by any other tool that outputs .mbtiles files, or copied in
  from another machine; only the File > Download Tiles… menu item is
  affected.

Step 5 — Get tile data
-------------------------
  See Section 6. Tiles are required for the map to display; the program
  is otherwise fully usable without them.


================================================================================
3.  INSTALLATION: WINDOWS
================================================================================

Step 1 — Install Python
-------------------------
  If Python is not already installed, download it from python.org.
  During installation, check the box labeled "Add Python to PATH."

  Verify the installation:
      python --version

Step 2 — Copy the program files
---------------------------------
  Place the sitrepmapper folder in a convenient location, for example:

      C:\Users\<username>\sitrepmapper

Step 3 — Install Python packages
----------------------------------
  Open a Command Prompt and run:

      pip install Pillow mgrs requests

Step 4 — Create a desktop shortcut
-------------------------------------
  Windows does not use .desktop launcher files. To create a shortcut:

  1. Right-click the Desktop and select New > Shortcut.
  2. In the Location field, enter (adjust the path to match your install):
         python "C:\Users\<username>\sitrepmapper\main.py"
  3. Click Next, name it "SitRepMapper", and click Finish.
  4. To add the icon: right-click the shortcut > Properties > Change Icon…,
     browse to:
         C:\Users\<username>\sitrepmapper\assets\icon.ico

  Alternatively, create a batch file (sitrepmapper.bat) in the program
  folder with the following contents and create a shortcut to it:
      @echo off
      python "C:\Users\<username>\sitrepmapper\main.py"

Step 5 — Get tile data
-------------------------
  See Section 6.


================================================================================
4.  THE DESKTOP LAUNCHER (LINUX / RASPBERRY PI)
================================================================================

What Is a .desktop File?
--------------------------
  On Linux desktops (including Raspberry Pi OS with LXDE, as well as GNOME,
  KDE, XFCE, and others), a .desktop file is the standard way to define a
  clickable application launcher. It tells the desktop environment the
  program name, the command to run, and which icon to display.

  Windows uses shortcut (.lnk) files for the same purpose. See Section 3
  for Windows shortcut creation.

The sitrepmapper.desktop File
-------------------------------
  The file sitrepmapper/sitrepmapper.desktop is pre-configured for an
  installation at /opt/sitrepmapper. If you installed to a different
  location, edit the Exec= and Icon= lines to reflect the correct path
  before copying it:

      Exec=/usr/bin/python3 /home/<username>/sitrepmapper/main.py %u
      Icon=/home/<username>/sitrepmapper/assets/icon.png

Installing the Launcher
------------------------
  Copy the (adjusted) .desktop file to two locations:

    ~/.local/share/applications/sitrepmapper.desktop
        Makes SitRepMapper appear in the application menu.

    ~/Desktop/sitrepmapper.desktop
        Places a clickable icon on the Desktop (only if ~/Desktop/ exists).

  After copying, refresh the application database:
      update-desktop-database ~/.local/share/applications

If the Desktop Icon Did Not Appear
-------------------------------------
  1. Verify the Exec= path in the .desktop file points to your actual
     installation location and that main.py exists there.

  2. Mark the Desktop copy as executable:
         chmod +x ~/Desktop/sitrepmapper.desktop

  3. Some GNOME configurations hide .desktop file icons on the Desktop
     by default. Right-click the Desktop and look for "Allow Launching."

  4. Try logging out and back in to force a full desktop refresh.

  5. Check that ~/Desktop/ exists. SitRepMapper will still appear in
     the application menu even if no Desktop icon was created.

Running Without a Desktop Icon
--------------------------------
  SitRepMapper can always be launched from a terminal:

      python3 /home/<username>/sitrepmapper/main.py


================================================================================
5.  STARTING THE PROGRAM
================================================================================

Linux / Raspberry Pi
---------------------
  Double-click the SitRepMapper icon on the Desktop or application menu.

  Or from a terminal:
      python3 /home/<username>/sitrepmapper/main.py

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

  Or from a Command Prompt:
      python C:\Users\<username>\sitrepmapper\main.py

First-Time Use
----------------
  On first launch the map canvas will be gray — tile data has not been
  loaded yet. See Section 6 to get tile data. The program is otherwise
  fully functional: you can enter grid locators, use the Grid Converter,
  open a JS8Spotter database or JS8Call Directed Log, and manage flag pins
  before tiles are present.


================================================================================
6.  TILE DATA SETUP
================================================================================

SitRepMapper requires local tile data to display the map. Tiles only need
to be obtained once, and are separate from the program files — they can
be stored anywhere: the local hard drive, an external drive, or a USB
flash drive.

Auto-Detection
----------------
  On startup, SitRepMapper automatically searches for .mbtiles files in:
    1. A USB drive labelled SRMAP_NA (plug in before launching)
    2. Any mounted drive under /mnt, /media, or /run/media
    3. The local tiles/ directory inside the program folder

  All .mbtiles files found are loaded simultaneously, so an overview file
  and regional detail files work together without any manual selection.

Getting Tile Data
--------------------
  Tiles are fetched with TileDownloader, a separate standalone program
  bundled with SitRepMapper (see Step 4 of Section 2). File > Download
  Tiles… in SitRepMapper launches it directly, with a dialog for region
  presets, zoom range, estimated tile count, and a progress bar.

  TileDownloader can also be run standalone from a terminal, including a
  command-line mode for scripting a download without opening its GUI;
  see tiledownloader/UserGuide.txt for details.

Flash Drive Setup
--------------------
  To use a USB flash drive for portable tile storage:
    1. Format the drive (exFAT recommended for files over 4 GB).
    2. Label the drive SRMAP_NA.
    3. Copy your .mbtiles files to the root of the drive.
    4. Plug in the drive before launching SitRepMapper.

  Other files on the drive do not interfere with map operation.

  On Linux, relabelling an exFAT drive requires it to be unmounted first:
      sudo umount /dev/sdXN
      sudo exfatlabel /dev/sdXN SRMAP_NA

  On Windows, drives are lettered (e.g. E:\) rather than mounted by
  volume label, so the SRMAP_NA label itself is just for your own
  reference — any drive letter with .mbtiles files at its root is
  auto-detected, regardless of what it's labelled.

Loading a Tile File Manually
-------------------------------
  If tiles are not auto-detected, load them manually:
      File > Open MBTiles…    — select a single .mbtiles file
      File > Select Tile Folder… — select a directory tile cache


================================================================================
7.  TROUBLESHOOTING
================================================================================

"ModuleNotFoundError: No module named 'PIL'" on launch
--------------------------------------------------------
  Pillow is not installed. Open a terminal and run:
      pip3 install Pillow            (Linux / Raspberry Pi)
      pip install Pillow             (Windows)

  If you see "externally managed environment," add --user:
      pip3 install --user Pillow

"ModuleNotFoundError: No module named 'mgrs'" / Tools > Grid Converter does nothing
-------------------------------------------------------------------------------------
  The mgrs library is not installed. This error fires when you open
  Tools > Grid Converter, not on launch, so the rest of the app works.
  Install it with:
      pip3 install mgrs              (Linux / Raspberry Pi)
      pip install mgrs               (Windows)

"ModuleNotFoundError: No module named 'tkinter'"
-------------------------------------------------
  Tkinter is not installed. On Raspberry Pi OS, Ubuntu, or Debian:
      sudo apt install python3-tk

  Then launch SitRepMapper again.

"Export Error" / Ghostscript message using File > Export Map Image…
---------------------------------------------------------------------------
  Ghostscript is not installed. This is a system tool, not a Python
  package, and is only needed for this one feature — the rest of the
  app works without it. Install it with:
      sudo apt install ghostscript   (Linux / Raspberry Pi)
      choco install ghostscript      (Windows, via Chocolatey — or download
                                       the installer from ghostscript.com)

  Then try File > Export Map Image… again.

"TileDownloader Not Found" using File > Download Tiles…
----------------------------------------------------------
  TileDownloader is bundled with SitRepMapper as a tiledownloader/
  subfolder — this means either that subfolder is missing from your
  install (reinstall to fix), or you're running a dev checkout where it
  lives separately at ~/ClaudeProjects/tiledownloader/main.py (both
  locations are checked; see Step 4 of Section 2). You can always fetch
  tile data another way instead and load it with File > Open MBTiles…
  / File > Select Tile Folder….

Gray canvas on launch / no map visible
------------------------------------------
  No tile data has been found. Either:
    - Tiles have not been obtained yet (see Section 6).
    - The .mbtiles files are not in an auto-detected location.
  Use File > Open MBTiles… to load a file manually, or see Section 6 to
  get tiles and place them in an auto-detected location.

Desktop icon does not appear after installation (Linux / Raspberry Pi)
---------------------------------------------------------------------------
  See "If the Desktop Icon Did Not Appear" in Section 4 above.

Desktop shortcut not visible after creation (Windows)
----------------------------------------------------------
  The most common cause on Windows 11 is a OneDrive Desktop redirect.
  When OneDrive is active, the Desktop folder may be at:
      C:\Users\<username>\OneDrive\Desktop
  rather than:
      C:\Users\<username>\Desktop

  Create the shortcut directly in the OneDrive Desktop folder, or look
  for the shortcut in C:\Users\<username>\Desktop and move it.

Application menu entry does not appear (Linux)
--------------------------------------------------
  Refresh the desktop application database:
      update-desktop-database ~/.local/share/applications
  Then check the application menu. If it still does not appear, try
  logging out and back in.

Program opens but immediately closes (Windows)
----------------------------------------------------
  This usually means Python could not find a required module. Run the
  program from a Command Prompt to see the error message:
      python C:\Users\<username>\sitrepmapper\main.py
  Then install any missing packages reported (see above).

Database will not open / "Could not read database"
-------------------------------------------------------
  Confirm the file is a genuine JS8Spotter .db (SQLite) file, and that
  it is not on a network location that blocks read-only SQLite access.

Config file location
-----------------------
  Settings are saved to:
      Linux / Raspberry Pi:  ~/.config/sitrepmapper/config.json
      Windows:                C:\Users\<username>\.config\sitrepmapper\config.json

  Deleting this file resets all settings to defaults.

"Not Connected" / "Connections Full" using the Send menu
--------------------------------------------------------------
  See the "JS8Call Send Feature (Optional)" note in Section 1. "Not
  Connected" means JS8Call's TCP Server API is off; "Connections Full" (or
  a connection-rejected message) means TCP Max Connections is still at
  JS8Call's default of 1 and another program already holds the slot. Full
  detail on both, plus what "JS8Call Appears Busy" and "Sent —
  Unconfirmed" mean, is in the User Manual's SENDING REPORTS and
  TROUBLESHOOTING sections.


================================================================================
  End of SitRepMapper Installation Guide
  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================
