================================================================================ AlertDisplay v1.1.0 – Installation Guide A companion program for SitRepMapper Designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================ UPDATING FROM AN OLDER VERSION ------------------------------- Updating uses the same steps as a fresh install: stop the monitor and close the settings window, extract the new ZIP into your existing alertdisplay folder, overwriting files when prompted, then open the settings window and start the monitor again. AlertDisplay 1.1.0 and later tell you when a newer version is out: when the settings window opens, a box offers to open the download page (Settings tab: "Check for updates when this window opens", and Check for Updates Now). It never downloads or installs anything itself; you update with the steps below. 1. Stop the monitor: open the settings window and press Stop Monitor, or run: python3 /home//alertdisplay/alertdisplay.py --stop Wait until the settings window shows "Monitor: not running". 2. Close the settings window. 3. Extract the ZIP over the existing folder. Use every file in the ZIP; mixing old and new program files can break AlertDisplay. 4. Open the settings window again and press Start Monitor. 5. Check the Log tab: the "Monitor started" line names the version and the folder the monitor is running from. Why steps 1, 2 and 4 matter: a running program keeps using the code it started with, even after its files are replaced. A monitor or settings window left running from before the update goes on behaving like the old version (for example, logging "unknown placeholder" for a placeholder the new version added) until it is closed and started again. Your settings, profiles and callsign lists are stored in your config folder (~/.config/alertdisplay/ on Linux/Raspberry Pi, C:\Users\\.config\alertdisplay\ on Windows), not the program folder, so extracting the ZIP never touches them. See AlertDisplay_CHANGELOG.txt for what's new in this version. TABLE OF CONTENTS ----------------- 1. System Requirements 2. Installation: Linux / Raspberry Pi 3. Installation: Windows 4. First-Time Setup 5. Starting the Monitor Automatically 6. Checking the Installation 7. Removing AlertDisplay 8. Troubleshooting ================================================================================ 1. SYSTEM REQUIREMENTS ================================================================================ - SitRepMapper v1.18.0 or later (companion display support, and the Status Board file that Status Board triggers read). AlertDisplay runs without SitRepMapper open, but SitRepMapper is where its alerts appear. - JS8Call, writing its DIRECTED.TXT log. (SitRepMapper's Settings should have the path to it; AlertDisplay uses the same path.) - Python 3.9 or newer, with tkinter. - No other Python packages. AlertDisplay uses only the Python standard library, so there is nothing to pip install. - Runs on Raspberry Pi OS (Pi 4B or newer recommended), desktop Linux, and Windows 10/11. It uses very little CPU, so it shares a Pi with SitRepMapper, JS8Call and JS8Spotter comfortably. Contents of the ZIP (all in an alertdisplay/ folder): alertdisplay.py The program (run this) ad_*.py The program's other parts alertdisplay.desktop Desktop launcher (Linux / Pi) AlertDisplay_SitRep_Group_Profile.json SitRepNet's profile, installed for you on first start AlertDisplay_Group_Template.json Starting point for your own group's profile AlertDisplay_Installation_Guide.txt This file AlertDisplay_User_Manual.txt How to use it AlertDisplay_ProfileBuilding.txt How to build profiles and triggers, with examples AlertDisplay_Overview.txt Overview for groups: what it does, benefits, adding your group AlertDisplay_Info.txt One-page summary AlertDisplay_CHANGELOG.txt What changed in each version ================================================================================ 2. INSTALLATION: LINUX / RASPBERRY PI ================================================================================ Step 1 — Copy the program files --------------------------------- Extract the ZIP. It contains an alertdisplay folder. Place it wherever you prefer. The recommended location for a single-user installation is the home directory: /home//alertdisplay For example, with the ZIP in your Downloads folder: cd ~ unzip ~/Downloads/AlertDisplay_v1.1.0.zip Step 2 — Make sure tkinter is installed ----------------------------------------- Raspberry Pi OS usually has it already, and if SitRepMapper runs, it's there. Otherwise: sudo apt update sudo apt install python3-tk Fedora / RPM-family distros: sudo dnf install python3-tkinter There are no pip packages to install. Step 3 — Install the desktop launcher (optional) -------------------------------------------------- The launcher opens the settings window from the application menu or the Desktop. The file alertdisplay/alertdisplay.desktop is pre-configured for an installation at /opt/alertdisplay. For the recommended home-directory location, adjust the path while copying it (replace with your user name): sed 's|/opt/alertdisplay|/home//alertdisplay|g' \ /home//alertdisplay/alertdisplay.desktop \ > ~/.local/share/applications/alertdisplay.desktop cp ~/.local/share/applications/alertdisplay.desktop ~/Desktop/ update-desktop-database ~/.local/share/applications On Raspberry Pi OS, double-clicking a Desktop launcher the first time may ask whether to execute it; choose Execute. If the Desktop icon does nothing, right-click it and allow launching, or run: chmod +x ~/Desktop/alertdisplay.desktop The launcher opens the settings window. The monitor is started from there (Section 4), or automatically at login (Section 5). Step 4 — Open the settings window ----------------------------------- From the launcher, or from a terminal: python3 /home//alertdisplay/alertdisplay.py Then continue with Section 4. ================================================================================ 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." The standard python.org installer includes tkinter. Verify the installation: python --version Step 2 — Copy the program files --------------------------------- Extract the ZIP and place the alertdisplay folder in a convenient location, for example: C:\Users\\alertdisplay Step 3 — Create a desktop shortcut ------------------------------------- 1. Right-click the Desktop and select New > Shortcut. 2. In the Location field, enter (adjust the path to match your install): pythonw "C:\Users\\alertdisplay\alertdisplay.py" (pythonw opens the settings window without a black console window. If pythonw isn't found, use python instead.) 3. Click Next, name it "AlertDisplay", and click Finish. Step 4 — Open the settings window ----------------------------------- Double-click the shortcut, or from a Command Prompt: python "C:\Users\\alertdisplay\alertdisplay.py" Then continue with Section 4. ================================================================================ 4. FIRST-TIME SETUP ================================================================================ 1. In SitRepMapper's Settings, check that your station callsign and the path to JS8Call's DIRECTED.TXT are set. AlertDisplay reads both from there. 2. In AlertDisplay's settings window, open the Settings tab. The line under DIRECTED.TXT should show the path with "(found)". If it says NOT FOUND, set the path in SitRepMapper, or type it here and Save. 3. On the Profiles tab, SitRepNet (@SITREP) is already there and turned on: AlertDisplay installs SitRepNet's profile the first time it starts. If your group sent you its own profile, add it with Import Group Profile... (Coordinators: to make one, see "Adding your group" in AlertDisplay_Overview.txt.) 4. Press Start Monitor at the top of the window. See AlertDisplay_User_Manual.txt for everything else. ================================================================================ 5. STARTING THE MONITOR AUTOMATICALLY ================================================================================ On the Settings tab, tick "Start the monitor automatically when I log in". That's all; it takes effect at the next login. It creates: Linux / Pi: ~/.config/autostart/alertdisplay.desktop Windows: AlertDisplay.cmd in your Startup folder (%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup) Untick it to remove the entry. If you move the alertdisplay folder later, untick and tick it again so the entry points to the new place. The monitor has no window. To check it's running, look at the toolbar block on SitRepMapper (green "Watching") or the top line of the settings window. ================================================================================ 6. CHECKING THE INSTALLATION ================================================================================ With SitRepMapper open and the monitor started: 1. SitRepMapper's toolbar shows a block reading "Watching" (green) within a few seconds. Yellow means a setting needs attention; the word says which (see the User Manual, WHAT SHOWS ON SITREPMAPPER). 2. In the settings window, open Test a Message, type a message that one of your triggers should match, for example KN4AM: @SITREP ALERT TEST and click Test. The result shows which trigger matched and the banner text. 3. Click Show on SitRepMapper. Within about 10 seconds SitRepMapper shows the message with "TEST:" at the start. It clears by itself after 2 minutes. If all three work, AlertDisplay is installed correctly. ================================================================================ 7. REMOVING ALERTDISPLAY ================================================================================ 1. In the settings window, untick "Start the monitor automatically when I log in" (Settings tab), then press Stop Monitor. 2. Delete the alertdisplay program folder. 3. Delete the config folder, ~/.config/alertdisplay/ (C:\Users\\.config\alertdisplay\ on Windows). This removes your profiles and callsign lists too; copy any you want to keep first. 4. Delete ALR.banner, NTF.banner and ALR.indicator from ~/.config/sitrepmapper/companions/ if they're still there. 5. Linux / Pi: delete ~/.local/share/applications/alertdisplay.desktop and ~/Desktop/alertdisplay.desktop if you installed the launcher. Windows: delete the desktop shortcut. ================================================================================ 8. TROUBLESHOOTING ================================================================================ "AlertDisplay needs Python 3.9 or newer." Install a newer Python. Raspberry Pi OS Bullseye and newer already have one. "ModuleNotFoundError: No module named 'tkinter'" On Raspberry Pi OS, Ubuntu, or Debian: sudo apt install python3-tk On Windows, re-run the python.org installer, choose Modify, and make sure "tcl/tk and IDLE" is checked. The launcher icon does nothing Check the path on the Exec= line in the .desktop file matches where you put the alertdisplay folder, and that the file is allowed to run (Section 2, Step 3). The toolbar block never appears on SitRepMapper The monitor isn't running, or SitRepMapper is older than v1.18.0. Check the top line of the settings window, and press Start Monitor. The block shows YELLOW "No log" AlertDisplay can't find DIRECTED.TXT. Check the path on the Settings tab (Section 4, step 2). The monitor doesn't start at login Untick and tick "Start the monitor automatically when I log in" so the entry points to the current program folder and Python. Some minimal Linux desktops don't run ~/.config/autostart entries; on those, add python3 /home//alertdisplay/alertdisplay.py --monitor to the desktop's own startup programs. For problems while using AlertDisplay, see TROUBLESHOOTING in AlertDisplay_User_Manual.txt, and the Log tab in the settings window. ================================================================================ End of AlertDisplay Installation Guide Designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================