================================================================================ F104Mapper – Installation Guide Stephen Clay McGehee, KN4AM ================================================================================ TABLE OF CONTENTS ----------------- 1. System Requirements 2. First-Time Setup: Linux / Raspberry Pi / macOS 3. First-Time Setup: Windows 4. What setup.py Does 5. The Desktop Launcher (Linux / Raspberry Pi) 6. Starting the Program 7. First-Time Use 8. Troubleshooting Setup Problems ================================================================================ 1. SYSTEM REQUIREMENTS ================================================================================ Supported Platforms ------------------- - Raspberry Pi 4B running Raspberry Pi OS Bullseye or Bookworm (primary platform) - Linux (Ubuntu, Debian, and derivatives) - macOS - Windows 10 / 11 Python Version -------------- Python 3.9 or newer is required. Check your version: python3 --version (Linux / Raspberry Pi / macOS) python --version (Windows) Internet Connection ------------------- An internet connection is required for the one-time setup only. After setup, F104Mapper runs completely offline. ================================================================================ 2. FIRST-TIME SETUP: LINUX / RASPBERRY PI / MACOS ================================================================================ 1. Open a terminal and navigate to the F104Mapper folder: cd /home//f104mapper 2. Run the setup script: python3 setup.py Setup will display progress as it works through three steps: [1/3] Installing Python packages [2/3] Downloading offline map data [3/3] Installing desktop launcher The entire process takes a few minutes depending on your internet connection speed. 3. When setup completes, start F104Mapper (see Section 6) and verify the map loaded correctly — the map of North America should display with its land masses, country borders, and state/province borders. setup.py is safe to re-run at any time — it will skip steps that are already complete and reinstall anything that is missing. ================================================================================ 3. FIRST-TIME SETUP: WINDOWS ================================================================================ 1. Open a Command Prompt and navigate to the F104Mapper folder: cd C:\Users\\f104mapper 2. Run the setup script: python setup.py Setup will display progress as it works through three steps: [1/3] Installing Python packages [2/3] Downloading offline map data [3/3] Installing desktop launcher The entire process takes a few minutes depending on your internet connection speed. 3. When setup completes, start F104Mapper (see Section 6) and verify the map loaded correctly — the map of North America should display with its land masses, country borders, and state/province borders. setup.py is safe to re-run at any time — it will skip steps that are already complete and reinstall anything that is missing. ================================================================================ 4. WHAT SETUP.PY DOES ================================================================================ Step 1 of 3 – Python Virtual Environment ----------------------------------------- Creates a self-contained Python environment in the f104mapper/venv/ folder. This keeps F104Mapper's packages isolated from any other Python software on the system and ensures consistent behavior regardless of what else is installed. If a virtual environment already exists for a different Python version, setup.py removes it and creates a fresh one for the current version. Packages installed into the virtual environment: - matplotlib (map rendering) - numpy (numerical operations) - pyshp (shapefile map data reader) - pillow (image export support) Step 2 of 3 – Offline Map Data -------------------------------- Downloads four Natural Earth 1:110m shapefiles used for the offline map: - Land masses - Country borders - State / province borders - Lakes Map data is saved to: f104mapper/data/shapefiles/ These files are downloaded once and never change. If the download is interrupted, re-run setup.py to resume. Step 3 of 3 – Desktop Launcher -------------------------------- Linux / Raspberry Pi: Creates a desktop launcher in the standard FreeDesktop locations. See Section 5 for full details. Windows: Creates an F104Mapper.lnk shortcut on the Desktop using the 104_icon.ico icon. The shortcut points to run.bat in the f104mapper folder. ================================================================================ 5. 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 .lnk shortcut files for the same purpose. setup.py creates the correct launcher type automatically for each platform. What setup.py Installs ------------------------ setup.py reads f104mapper.desktop from the program folder, fills in the correct Exec= and Icon= paths for your system, marks it executable, and copies it to two locations: ~/.local/share/applications/f104mapper.desktop Makes F104Mapper appear in the application menu. ~/Desktop/f104mapper.desktop Places a clickable icon on the Desktop (only if ~/Desktop/ exists). After copying, setup.py refreshes the desktop application database so the launcher appears immediately — no logout is required. The f104mapper.desktop File in the Program Folder --------------------------------------------------- The file f104mapper/f104mapper.desktop is a template used by setup.py. It contains placeholder paths that setup.py fills in at install time. Do not use this file directly as a launcher. The paths it contains will not match your system unless setup.py has already run and patched them. Always use the installed copy in ~/.local/share/applications/ or on your Desktop. If the Desktop Icon Did Not Appear ------------------------------------- If setup.py ran without errors but no Desktop icon appeared: 1. Re-run setup.py — it is safe to run again: cd /home//f104mapper python3 setup.py 2. If the icon still does not appear after re-running, try logging out and back in to force a full desktop refresh. 3. Some GNOME configurations hide .desktop file icons on the Desktop by default. Right-click the Desktop and look for an option such as "Allow Launching" to enable it. 4. Check that ~/Desktop/ exists. If your system uses a different folder name for the Desktop (uncommon), the icon will not appear there, but F104Mapper will still be in the application menu. Running Without a Desktop Icon -------------------------------- F104Mapper can always be launched from a terminal without any icon: bash /home//f104mapper/run.sh Or directly via the virtual environment Python: /home//f104mapper/venv/bin/python3 \ /home//f104mapper/f104mapper.py ================================================================================ 6. STARTING THE PROGRAM ================================================================================ Linux / Raspberry Pi --------------------- Double-click the F104Mapper icon on the Desktop. Or from a terminal: bash /home//f104mapper/run.sh If setup has not been run yet, the launcher will display an error message explaining what to do. Windows -------- Double-click the F104Mapper shortcut on the Desktop. Or from a Command Prompt: C:\Users\\f104mapper\run.bat ================================================================================ 7. FIRST-TIME USE ================================================================================ The first time you start F104Mapper, you must open the JS8Spotter database to retrieve F!104 SITREP forms: File > Open JS8Spotter Database… Navigate to your JS8Spotter folder and select js8spotter.db. F104Mapper will remember this database on all subsequent startups. ================================================================================ 8. TROUBLESHOOTING SETUP PROBLEMS ================================================================================ setup.py fails during package installation -------------------------------------------- Confirm you have an active internet connection, then re-run setup.py. Check that Python 3.9 or newer is installed: python3 --version (Linux / Raspberry Pi / macOS) python --version (Windows) setup.py fails during map data download ------------------------------------------ The Natural Earth data server (naciscdn.org) must be reachable. Check your internet connection and re-run setup.py. The download will restart from the beginning (files are small — under 1 MB each). Map does not display / shows "matplotlib not installed" --------------------------------------------------------- The Python packages were not installed successfully. Re-run setup.py: cd /home//f104mapper python3 setup.py Then restart F104Mapper. Map displays a plain green rectangle -------------------------------------- The shapefile map data did not download. Re-run setup.py (see above). The map should display land masses, borders, and coastlines after successful setup. "Virtual environment not found" error on launch ------------------------------------------------- setup.py has not been run yet, or the venv/ folder was deleted. Open a terminal and run: cd /home//f104mapper python3 setup.py Desktop icon does not appear after setup ------------------------------------------ See "If the Desktop Icon Did Not Appear" in Section 5 above. Application menu entry does not appear after setup ---------------------------------------------------- The desktop application database may need a manual refresh: update-desktop-database ~/.local/share/applications Then check the application menu. If it still does not appear, try logging out and back in. ================================================================================ End of F104Mapper Installation Guide F104Mapper is designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================