JS8Spotter v1.21.0 Installation Guide ===================================== JS8Spotter is a companion program for JS8Call. It watches JS8Call's traffic for the callsigns and words you choose, answers E? Expect requests, and handles MCForms and CommStat StatReps. Download page: https://sitrepnet.com/js8spotter/ Download file: JS8Spotter_v1.21.0.zip (one ZIP for Windows, Linux and macOS) CONTENTS -------- 1. Before you start: set up JS8Call 2. New install on Windows 3. New install on Linux (including Raspberry Pi) 4. New install on macOS 5. Upgrading from an older version 6. First start: settings 7. Troubleshooting 8. Checking the download (optional) 9. Help and support 1. BEFORE YOU START: SET UP JS8CALL ----------------------------------- JS8Spotter talks to JS8Call over JS8Call's TCP API. Turn it on once: 1. In JS8Call, open File > Settings, then the Reporting tab. 2. Check all three of these boxes: - Allow setting station information - Enable TCP Server API - Accept TCP Requests 3. Leave the TCP server at 127.0.0.1, port 2442, unless you have a reason to change it. 4. Click OK. Always start JS8Call FIRST, then JS8Spotter. JS8Spotter connects only when it starts. If JS8Call isn't running, JS8Spotter shows a TCP Error and the status bar says NOT CONNECTED TO JS8CALL; start JS8Call, then close and restart JS8Spotter. 2. NEW INSTALL ON WINDOWS ------------------------- There is no installer. JS8Spotter runs from the folder you unzip it to. 1. Download JS8Spotter_v1.21.0.zip. 2. Right-click the ZIP and choose Extract All. 3. Click Browse, choose your Documents folder, and click Extract. You now have a folder Documents\js8spotter. Keep it OUTSIDE "Program Files". JS8Spotter saves its database in its own folder, and Windows doesn't allow that in Program Files. 4. Open Documents\js8spotter and double-click js8spotter.exe. 5. Optional: right-click js8spotter.exe > Show more options > Create shortcut, and move the shortcut to your desktop. The first time you run it, Windows shows a blue window, "Windows protected your PC", with only a "Don't run" button. This is normal: the program isn't signed with a paid code-signing certificate, so Windows lists it as "Unknown publisher". Click "More info", then "Run anyway". Windows asks only once for each copy you extract. Go on to section 6, First start. 3. NEW INSTALL ON LINUX (INCLUDING RASPBERRY PI) ------------------------------------------------ On Linux, JS8Spotter runs from its Python source with your system's Python 3. The ZIP also contains the Windows files; Linux ignores them. 1. Install Python 3 and the libraries it needs. On Debian, Ubuntu, Linux Mint and Raspberry Pi OS: sudo apt install python3 python3-tk python3-pil python3-pil.imagetk python3-requests For sound alerts (optional): sudo apt install python3-tksnack If your system has no python3-tksnack package, JS8Spotter still works; it shows an "Audio not loaded" message at startup, which you can turn off in File > Settings. 2. Unzip the download into your home folder: cd ~ unzip ~/Downloads/JS8Spotter_v1.21.0.zip You now have a folder ~/js8spotter. 3. Start JS8Call, then start JS8Spotter: cd ~/js8spotter python3 js8spotter.py Always start it from inside its folder, as shown. It finds its database and files relative to the current folder. 4. Optional, for a menu entry and desktop icon, run this once: cd ~/js8spotter bash desktop_icon_setup.sh If you later move the folder, run it again. If it complains about a missing module, see section 7. README.linux in the program folder has more detail. Go on to section 6, First start. 4. NEW INSTALL ON macOS ----------------------- On macOS, JS8Spotter also runs from its Python source. Unzip the download, then follow README.macos in the js8spotter folder. It uses Homebrew to install Python and the needed libraries (requests, Pillow, simpleaudio). Go on to section 6, First start. 5. UPGRADING FROM AN OLDER VERSION ---------------------------------- Your callsign, settings, profiles, search terms, Expect entries and logs are all in one file: js8spotter.db in your JS8Spotter folder. An upgrade keeps that file. IMPORTANT: starting with v1.21.0, JS8Spotter is more than the single file js8spotter.py. It is js8spotter.py PLUS the js8spotter folder inside the program folder. Copy the WHOLE new program folder, not just js8spotter.py. 1. Close JS8Spotter. 2. Back up js8spotter.db: copy it somewhere safe. 3. Unzip JS8Spotter_v1.21.0.zip somewhere temporary (for example your Downloads folder). 4. Open the new js8spotter folder, select everything in it, and copy it into your existing JS8Spotter folder. When asked, choose "Replace the files in the destination" (Windows) or "Replace" / overwrite (Linux). The download has no js8spotter.db in it, so your own database is not touched. 5. Start JS8Call, then JS8Spotter. The title bar should show v1.21.0, and Help > About should say "JS8Spotter version 1.21.0". Coming from v1.17 or newer: no database upgrade is needed. Coming from v1.16 or older: your database needs converting first with the JS8Spotter DB Upgrade Tool from the download page. README.upgrade in the program folder lists which versions need it. Leftover files from the old version (such as an old title.txt or an older Python DLL) are harmless and can stay. From v1.21.0 on, JS8Spotter tells you when a new version is out. You can also check any time with Help > Check for Updates. 6. FIRST START: SETTINGS ------------------------ On a new install, JS8Spotter creates a fresh js8spotter.db and shows "Settings Incomplete". Open File > Settings and enter: - Your callsign. Use the SAME callsign as in JS8Call. If they differ, the status bar shows a CALLSIGN MISMATCH notice. - Your grid square. - TCP address and port: leave 127.0.0.1 and 2442 unless you changed them in JS8Call. Click Save. Leave the other settings at their defaults until you need them. To learn the program, see HELP.txt and the PDF manuals in the program folder. 7. TROUBLESHOOTING ------------------ "TCP Error" / NOT CONNECTED TO JS8CALL JS8Call isn't running, or its TCP API is off (section 1), or the address and port in File > Settings don't match JS8Call's. Fix it, then restart JS8Spotter. Windows: "VCRUNTIME140.dll was not found" or a similar DLL error Install the Microsoft Visual C++ Redistributable, linked on the download page, then try again. Windows: the program won't start, or can't find its files Make sure the folder is not in Program Files, and that you started js8spotter.exe from inside the extracted folder, not from inside the ZIP. Windows can show a ZIP's contents without extracting it; always use Extract All first. Linux: "No module named 'tkinter'" sudo apt install python3-tk Linux: "cannot import name 'ImageTk' from 'PIL'" sudo apt install python3-pil python3-pil.imagetk Linux: "No module named 'requests'" sudo apt install python3-requests Linux: odd errors about missing files or the database Start it from inside its folder: cd ~/js8spotter, then python3 js8spotter.py. "Audio not loaded" at startup No sound library is installed. JS8Spotter works without one. Install one for sound (Linux: python3-tksnack), or hide the message with the checkbox in File > Settings. After an upgrade: errors about a missing module named "js8spotter" Only js8spotter.py was copied. Copy the whole new program folder, including the js8spotter folder inside it (section 5). 8. CHECKING THE DOWNLOAD (OPTIONAL) ----------------------------------- To confirm the download is complete and unaltered, compare its SHA-256 with this value: 1212f7db984cad7e6867f4ab4612023d53f23d9dc095f8e5b04df07e06f63d9e Windows (PowerShell): Get-FileHash JS8Spotter_v1.21.0.zip Linux: sha256sum JS8Spotter_v1.21.0.zip macOS: shasum -a 256 JS8Spotter_v1.21.0.zip (Windows shows it in capital letters; that's the same value.) A PGP signature, JS8Spotter_v1.21.0.zip.sig, is also on the download page. 9. HELP AND SUPPORT ------------------- JS8Spotter was written by Joe Lyman, KF7MIX, and is now maintained by Stephen McGehee, KN4AM. It is open source under the MIT License. For questions or problems, contact KN4AM. More information: https://sitrepnet.com