================================================================================ 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\\ .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//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//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//sitrepmapper/venv/bin/python3 /home//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//sitrepmapper|g' \ /home//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\\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\\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\\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\\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//sitrepmapper/main.py %u Icon=/home//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//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//sitrepmapper/main.py Windows -------- Double-click the SitRepMapper shortcut on the Desktop. Or from a Command Prompt: python C:\Users\\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\\OneDrive\Desktop rather than: C:\Users\\Desktop Create the shortcut directly in the OneDrive Desktop folder, or look for the shortcut in C:\Users\\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\\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\\.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 ================================================================================