================================================================================ Flag Pin Tool – Installation Guide Designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================ 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. 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) Required Python Packages ------------------------ Flag Pin Tool uses only the Python standard library for its core features. One additional package is required for the Tools > Grid Converter feature: mgrs (MGRS/USNG coordinate conversion) Install it with pip: pip3 install mgrs (Linux / Raspberry Pi) pip install mgrs (Windows) If mgrs is not installed, Flag Pin Tool will start and run normally — only the Grid Converter tool will be unavailable. Tkinter is pre-installed on Raspberry Pi OS and most Linux distributions. See Troubleshooting (Section 6) if it is missing on your system. Internet Connection ------------------- Not required for normal operation. An internet connection is only used for the optional startup version check, which runs as a silent background thread and does not affect program function if the network is unavailable. ================================================================================ 2. INSTALLATION: LINUX / RASPBERRY PI ================================================================================ Step 1 — Copy the program files --------------------------------- Place the flagpintool folder wherever you prefer. The recommended location for a single-user installation is the home directory: /home//flagpintool The program creates its data/ subdirectory automatically on first run. No other directories need to be created in advance. Step 2 — Verify Python and tkinter ------------------------------------- Open a terminal and run: python3 --version python3 -c "import tkinter; print('tkinter OK')" If python3 is not found, install it: sudo apt install python3 If tkinter is missing, install it: sudo apt install python3-tk Step 3 — Install the desktop launcher --------------------------------------- See Section 4 for full details. Quick install: cp /home//flagpintool/flagpintool.desktop \ ~/.local/share/applications/ cp /home//flagpintool/flagpintool.desktop ~/Desktop/ chmod +x ~/Desktop/flagpintool.desktop update-desktop-database ~/.local/share/applications Step 4 — Launch the program ----------------------------- From the terminal: python3 /home//flagpintool/flagpintool.py Or use the desktop launcher once it has been installed (Step 3). ================================================================================ 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 Tkinter is included with the standard Python Windows installer. No additional packages are needed. Step 2 — Copy the program files --------------------------------- Place the flagpintool folder in a convenient location, for example: C:\Users\\flagpintool Step 3 — 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\\flagpintool\flagpintool.py" 3. Click Next, name it "Flag Pin Tool", and click Finish. 4. To add the icon: right-click the shortcut > Properties > Change Icon…, browse to: C:\Users\\flagpintool\FlagPinTool.png Note: Windows shortcut icons require .ico format. If the PNG does not display correctly, skip this step — the shortcut will still work. Alternatively, create a batch file (flagpintool.bat) with these contents and create a shortcut to it: @echo off python "C:\Users\\flagpintool\flagpintool.py" Step 4 — Launch the program ----------------------------- Double-click the desktop shortcut, or from a Command Prompt: python C:\Users\\flagpintool\flagpintool.py ================================================================================ 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 flagpintool.desktop File ------------------------------ The file flagpintool/flagpintool.desktop is pre-configured for an installation at /home/stephen/flagpintool. If you installed to a different username or location, edit the Exec= and Icon= lines before copying: Exec=/home//flagpintool/run.sh Icon=/home//flagpintool/FlagPinTool.png The run.sh Launcher Script ---------------------------- The run.sh script in the flagpintool folder is the launch command used by the .desktop file. It performs a quick tkinter availability check and shows a user-friendly error dialog (via zenity) if tkinter is missing, rather than silently failing. run.sh does not set up a virtual environment — no venv is needed because Flag Pin Tool has no external dependencies. Installing the Launcher ------------------------ Copy the (adjusted) .desktop file to two locations: ~/.local/share/applications/flagpintool.desktop Makes Flag Pin Tool appear in the application menu. ~/Desktop/flagpintool.desktop Places a clickable icon on the Desktop (only if ~/Desktop/ exists). After copying, refresh the application database: update-desktop-database ~/.local/share/applications Full one-line install (adjust path if needed): cp /home//flagpintool/flagpintool.desktop \ ~/.local/share/applications/ && \ cp /home//flagpintool/flagpintool.desktop ~/Desktop/ && \ chmod +x ~/Desktop/flagpintool.desktop && \ update-desktop-database ~/.local/share/applications If the Desktop Icon Did Not Appear ------------------------------------- 1. Verify the Exec= and Icon= paths in the .desktop file match your actual installation location and that flagpintool.py exists there. 2. Verify run.sh is executable: chmod +x /home//flagpintool/run.sh 3. Mark the Desktop copy as executable: chmod +x ~/Desktop/flagpintool.desktop 4. Some GNOME configurations hide .desktop file icons on the Desktop by default. Right-click the Desktop and look for "Allow Launching." 5. Try logging out and back in to force a full desktop refresh. 6. Check that ~/Desktop/ exists. Flag Pin Tool will still appear in the application menu even if no Desktop icon was created. Running Without a Desktop Icon -------------------------------- Flag Pin Tool can always be launched from a terminal: python3 /home//flagpintool/flagpintool.py Or via the launcher script: bash /home//flagpintool/run.sh ================================================================================ 5. STARTING THE PROGRAM ================================================================================ Linux / Raspberry Pi --------------------- Double-click the Flag Pin Tool icon on the Desktop or in the application menu. Or from a terminal: python3 /home//flagpintool/flagpintool.py Windows -------- Double-click the Flag Pin Tool shortcut on the Desktop. Or from a Command Prompt: python C:\Users\\flagpintool\flagpintool.py First-Time Use --------------- On first launch the pin list is empty. Use Add… in the toolbar or the Quick Add strip at the bottom to create new pins, or use Import CSV/TSV… to import existing data. The station callsign and default color can be set in the options bar at the top of the window or in Settings > Settings… Data Storage ------------- All data is stored in the flagpintool/data/ directory: data/settings.json Application settings (auto-saved on exit) data/imports/ Default folder for imported CSV/TSV files data/exports/ Default folder for exported .flags.json files Flag pin data is NOT auto-saved to a fixed file as in MH Grid Mapper. In Flag Pin Tool, you control which file pins are saved to via File > Save or File > Save As. This gives you full control over multiple pin datasets. ================================================================================ 6. TROUBLESHOOTING ================================================================================ "ModuleNotFoundError: No module named 'tkinter'" ------------------------------------------------- Tkinter is not installed. On Raspberry Pi OS, Ubuntu, or Debian: sudo apt install python3-tk On Fedora / RHEL / Rocky Linux: sudo dnf install python3-tkinter On Windows: tkinter is bundled with the standard Python installer from python.org. If it is missing, re-run the Python installer and ensure the "tcl/tk and IDLE" component is checked. Program launches but the window appears blank or very small ----------------------------------------------------------- This can happen if a saved window geometry from a previous session is incompatible with the current display resolution. Reset it by deleting: /home//flagpintool/data/settings.json The program will recreate it with defaults on next launch. 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 it 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. Tools > Grid Converter… shows an error or does nothing ------------------------------------------------------ The Grid Converter requires the mgrs package. Install it: pip3 install mgrs (Linux / Raspberry Pi) pip install mgrs (Windows) Then restart Flag Pin Tool. "Check for Updates Now" shows "Check Failed" -------------------------------------------- The version check URL is unreachable. Confirm you have an active internet connection. The URL can be verified or changed in Settings > Settings… > Auto-Update tab. Leaving the URL blank disables all update checks. Imported CSV data shows 0 pins imported ----------------------------------------- Every imported row must have either a valid Grid value (Maidenhead locator such as EL99hc) or both Latitude and Longitude values. Rows where neither is valid are skipped. Check the column mapping in the import dialog and confirm the source data has recognizable grid or coordinate values. Saved .flags.json file is not recognized by JS8Reporter or MH Grid Mapper -------------------------------------------------------------------------- Verify the file was saved or exported using File > Save / Save As / Export .flags.json…. The file must have "format": "sitrep_flags" in its header. Opening the file in a text editor and checking the first few lines will confirm this. If the file was created by another program or has a different format, use Import CSV/TSV… or Merge Flag Pins… to load and re-export it. Config file location --------------------- Settings are saved to: Linux / Raspberry Pi: /home//flagpintool/data/settings.json Windows: C:\Users\\flagpintool\data\settings.json Deleting this file resets all settings to defaults. Flag pin data is not affected — it is stored in whichever .flags.json file you last saved. ================================================================================ End of Flag Pin Tool Installation Guide Designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================