=============================================================================== 505PROCESSOR — F!505 Area Assessment Record Processor Installation Guide — Version 1.0.0 =============================================================================== Designed and developed by Stephen Clay McGehee, KN4AM SitRepNet.com ------------------------------------------------------------------------------- TABLE OF CONTENTS ------------------------------------------------------------------------------- 1. Requirements 2. Installing on Windows 3. Installing on Linux and Raspberry Pi 4. Running 505Processor 5. Upgrading to a New Version 6. Troubleshooting =============================================================================== SECTION 1 — REQUIREMENTS =============================================================================== All platforms: Python 3.7 or later, with tkinter included. No additional Python packages are required. Windows: Python 3.7 or later (download from python.org). Tkinter is included with the standard Python installer for Windows. Tested on Windows 10 and Windows 11. Linux and Raspberry Pi: Python 3.7 or later (usually pre-installed). The python3-tk package must be installed separately if not present (see Section 3). Tested on Raspberry Pi OS (Bookworm) and Debian/Ubuntu-based systems. =============================================================================== SECTION 2 — INSTALLING ON WINDOWS =============================================================================== Step 1 — Check Python ───────────────────── Open a Command Prompt (search for "cmd" in the Start menu) and run: python --version If Python 3.7 or later is shown (for example, Python 3.11.4), go to Step 2. If Python is not found, download and install it from: https://www.python.org/downloads/windows/ During installation, check "Add Python to PATH." This is required. After installing, close and reopen the Command Prompt, then verify: python --version Step 2 — Extract 505Processor ────────────────────────────── Unzip the 505Processor download to a folder of your choice. A path with no spaces is recommended. Example: C:\505Processor Step 3 — Run Setup ────────────────── In the Command Prompt, navigate to the 505Processor folder and run: cd C:\505Processor python setup.py You will see confirmation that Python and tkinter are available and that setup completed successfully. Setup also creates a 505Processor shortcut on your Desktop with the 505 icon. This step only needs to be done once after a fresh install. Step 4 — Launch ──────────────── Double-click the 505Processor icon on your Desktop. Alternatively, double-click run.bat in the 505Processor folder, or run it from a Command Prompt: run.bat =============================================================================== SECTION 3 — INSTALLING ON LINUX AND RASPBERRY PI =============================================================================== Step 1 — Check Python ───────────────────── Open a terminal and run: python3 --version Python 3.7 or later is required. On most modern Raspberry Pi OS and Debian/Ubuntu systems, Python 3 is pre-installed. If Python 3 is not installed: sudo apt update sudo apt install python3 Step 2 — Check tkinter ────────────────────── Test that tkinter is available: python3 -c "import tkinter; print('tkinter OK')" If you see "tkinter OK", proceed to Step 3. If you see an error, install python3-tk: sudo apt install python3-tk Then run the test again to confirm. Step 3 — Extract 505Processor ────────────────────────────── Copy or extract the 505Processor download to a convenient location. Example: /home/pi/505processor Step 4 — Run Setup ────────────────── In a terminal, change to the 505Processor directory and run: cd /home/pi/505processor python3 setup.py You will see confirmation that Python, tkinter, and the virtual environment are ready. Setup also marks run.sh executable, creates a 505Processor shortcut on your Desktop with the 505 icon, and on GNOME desktops pins the app icon to the dash (the vertical icon bar on the side of the screen). This step only needs to be done once after a fresh install. Step 5 — Launch ──────────────── Double-click the 505Processor icon on your Desktop. On GNOME desktops, you can also click the 505Processor icon in the dash. While the app is running, the dash icon shows a dot indicator; clicking it brings the window to the foreground. Alternatively, open a terminal in the 505Processor directory and run: ./run.sh =============================================================================== SECTION 4 — RUNNING 505PROCESSOR =============================================================================== After installation, always use run.sh (Linux/Raspberry Pi) or run.bat (Windows) to start 505Processor. These scripts use the private virtual environment created by setup.py and ensure the correct Python is used. Running processor505.py directly Advanced users may run the program directly using the system Python: python3 processor505.py If you do this, make sure Python 3 and tkinter are available in your environment. The virtual environment (venv) created by setup.py is not required for direct invocation on a system with a compatible Python. Do not move the 505Processor folder after running setup.py The virtual environment stores absolute paths. If you need to move the folder to a new location, delete the venv subfolder and run setup.py again from the new location. =============================================================================== SECTION 5 — UPGRADING TO A NEW VERSION =============================================================================== When a new version is available, 505Processor notifies you at startup (if auto-update checking is enabled in Preferences > Auto-Update). To upgrade: 1. Download the new version from SitRepNet.com. 2. Close 505Processor if it is running. 3. Back up your IGNORE.TXT file if you have one. 4. Replace the contents of your 505Processor folder with the new version files. Do not delete the data subfolder — it contains your saved preferences (settings.json). 5. The existing venv folder from your previous installation can usually be kept as-is. If you experience problems after upgrading, delete the venv folder and run setup.py again. 6. Copy your IGNORE.TXT back into the 505Processor folder. 7. Launch using run.sh or run.bat as usual. =============================================================================== SECTION 6 — TROUBLESHOOTING =============================================================================== "505Processor setup has not been run yet." The run script could not find the virtual environment. Run setup.py before using the launcher: python3 setup.py (Linux / Raspberry Pi) python setup.py (Windows) "python3: command not found" (Linux) "python is not recognized" (Windows) Python is not installed or not in the system PATH. Install Python as described in Section 2 or 3 and ensure it is added to PATH. "ModuleNotFoundError: No module named '_tkinter'" (Linux) tkinter is not installed. Run: sudo apt install python3-tk Then run setup.py again. The program window does not appear after launch The window may have opened off-screen from a previous session on a different monitor or display. To reset the window position: 1. Close 505Processor. 2. Open the file data/settings.json in a text editor. 3. Delete the "window_geometry" line and save the file. 4. Restart 505Processor. "Input folder not found" or "Input file not found" The path entered in the dialog does not exist. Use the Browse button to select a valid folder or file. Output file contains fewer records than expected Check the summary in the log for "Duplicates removed" and "Invalid lines skipped" counts. Records that fail parsing are counted but not written to the output. Combine Records finds no records Confirm the input folder contains .txt or .csv files with valid F!505 records. Subfolders are not searched. IGNORE.TXT does not seem to filter any records Callsign filtering requires callsign data in the input file, which is only present in CSV exports. Plain .txt export files do not include callsigns; IGNORE.TXT has no effect on them. =============================================================================== END OF INSTALLATION GUIDE ===============================================================================