================================================================================ JS8Reporter – Installation Guide Stephen Clay McGehee, KN4AM ================================================================================ TABLE OF CONTENTS ----------------- 1. System Requirements 2. First-Time Setup: Linux / Raspberry Pi 3. First-Time Setup: Windows 4. What setup.py Does 5. The Desktop Launcher (Linux / Raspberry Pi) 6. Starting the Program 7. Troubleshooting Setup Problems ================================================================================ 1. SYSTEM REQUIREMENTS ================================================================================ Supported Platforms ------------------- - Raspberry Pi 4B running Raspberry Pi OS Bullseye (primary platform) - 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 one-time setup only. After setup, JS8Reporter runs completely offline. GPIO Alert Output (Raspberry Pi — optional feature) ----------------------------------------------------- JS8Reporter can optionally drive a GPIO pin to signal an active ALERT (see Section 12 of the User Manual). This feature requires: - Raspberry Pi hardware (feature is automatically hidden on other platforms; no action needed for Windows or non-Pi Linux users) - The user running JS8Reporter must be a member of the "gpio" group. On a standard Raspberry Pi OS installation with the default user this is already the case. If it is not, run: sudo usermod -aG gpio Then log out and back in (or reboot) before starting JS8Reporter. - RPi.GPIO package (included with Raspberry Pi OS by default; no additional installation is required) ================================================================================ 2. FIRST-TIME SETUP: LINUX / RASPBERRY PI ================================================================================ 1. Open a terminal and navigate to the JS8Reporter folder: cd /home//js8reporter 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 JS8Reporter (see Section 6) and verify the map data installed correctly: Help > Map Setup (setup.py)… The dialog will show "Map data status: Installed ✓" if successful. 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 JS8Reporter folder: cd C:\Users\\js8reporter 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 JS8Reporter (see Section 6) and verify the map data installed correctly: Help > Map Setup (setup.py)… The dialog will show "Map data status: Installed ✓" if successful. 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 js8reporter/venv/ folder. This keeps JS8Reporter'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. On Debian/Ubuntu/Raspberry Pi OS, setup.py checks that the python3.X-venv package is available before removing the old environment and prints an apt install command if it is missing. Packages installed into the virtual environment: - matplotlib (map rendering and charting) - numpy (numerical operations) - pyshp (shapefile map data reader) - pillow (image export support) - mgrs (MGRS/USNG coordinate conversion for Grid Converter) Step 2 of 3 – Offline Map Data -------------------------------- Downloads four Natural Earth 1:50m shapefiles used for the offline map: - Land masses - Country borders - State / province borders - Lakes Map data is saved to: js8reporter/data/shapefiles/ setup.py skips the download automatically if the current files are already present. When updating JS8Reporter to a new version, re-run setup.py to ensure the correct map files are downloaded. 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 a JS8Reporter.lnk shortcut on the Desktop using the JS8Reporter.ico icon. The shortcut points to run.bat in the js8reporter 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 js8reporter.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/js8reporter.desktop Makes JS8Reporter appear in the application menu under the Science / HamRadio category. ~/Desktop/js8reporter.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 js8reporter.desktop File in the Program Folder ----------------------------------------------------- The file js8reporter/js8reporter.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//js8reporter 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 JS8Reporter will still be in the application menu. Running Without a Desktop Icon -------------------------------- JS8Reporter can always be launched from a terminal without any icon: bash /home//js8reporter/run.sh Or directly via the virtual environment Python: /home//js8reporter/venv/bin/python3 \ /home//js8reporter/js8reporter.py ================================================================================ 6. STARTING THE PROGRAM ================================================================================ Linux / Raspberry Pi --------------------- Double-click the JS8Reporter icon on the Desktop. Or from a terminal: bash /home//js8reporter/run.sh If setup has not been run yet, the launcher will display an error message explaining what to do. Windows -------- Double-click the JS8Reporter shortcut on the Desktop. Or from a Command Prompt: C:\Users\\js8reporter\run.bat On startup, JS8Reporter will automatically reload the last database that was opened, if one is available. First-Time Use --------------- The first time you start JS8Reporter, you must open the JS8Spotter database to retrieve F!505 Area Assessment Surveys: File > Open Assessments Database Navigate to your JS8Spotter folder and select js8spotter.db. JS8Reporter will remember this database on all subsequent startups. ================================================================================ 7. 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) 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//js8reporter python3 setup.py Then restart JS8Reporter. This can also happen after an OS upgrade that changes the Python version (e.g. Python 3.13 → 3.14). As of v1.4.7, the launcher detects this automatically and shows a prompt before starting. Re-running setup.py rebuilds the virtual environment for the new Python version; existing map data is not re-downloaded. setup.py reports "venv module not available" (Debian / Ubuntu / Raspberry Pi OS) ---------------------------------------------------------------------------------- After a major Python version upgrade the system package for the new version's venv module may not be installed. Find your Python version, install the matching package, then re-run setup.py: python3 --version (note the X.Y version) sudo apt install python3.X-venv (replace X with the minor version) python3 setup.py Example: if python3 --version shows Python 3.14.x, run: sudo apt install python3.14-venv Map displays but shows no country / state borders --------------------------------------------------- The shapefile map data did not download. Re-run setup.py (see above). Confirm success with Help > Map Setup (setup.py)…. "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//js8reporter python3 setup.py Desktop icon does not appear after setup (Linux / Raspberry Pi) ----------------------------------------------------------------- See "If the Desktop Icon Did Not Appear" in Section 5 above. Desktop shortcut not visible after setup (Windows) ---------------------------------------------------- If setup.py reported "Desktop shortcut created" but the shortcut is not visible on the Desktop, the most common cause on Windows 11 is a OneDrive Desktop redirect. When OneDrive is active, the Desktop folder is typically located at: C:\Users\\OneDrive\Desktop rather than the standard: C:\Users\\Desktop setup.py places the shortcut in the standard location. If your Desktop is managed by OneDrive, look for JS8Reporter.lnk at: C:\Users\\Desktop and move or copy it to your OneDrive Desktop folder, or create a new shortcut there pointing to run.bat in the js8reporter folder. Alternatively, re-run setup.py and check the exact path reported in the output — the line "Desktop shortcut created at ..." shows exactly where the file was placed. 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 JS8Reporter Installation Guide JS8Reporter is designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================