================================================================================
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/<username>/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\<username>\.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/<username>/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 <username> with your
  user name):

      sed 's|/opt/alertdisplay|/home/<username>/alertdisplay|g' \
          /home/<username>/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/<username>/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\<username>\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\<username>\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\<username>\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\<username>\.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/<username>/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
================================================================================
