================================================================================
AlertDisplay v1.1.0 — Overview for Groups
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
================================================================================


WHAT IT IS
----------
AlertDisplay watches what your station receives on JS8Call and puts the
things that matter on SitRepMapper's screen: a red ALERT strip for what
must not be missed, and a notification strip for what's worth knowing.

It looks at two things:

  Messages      Every message JS8Call logs (its DIRECTED.TXT file): an
                ALERT to your group, a tornado warning, a call for help,
                traffic for your station, a net activation.
  The Status    SitRepMapper's processed picture of every station's
  Board         latest reports (F!104, F!309, F!505, F!500, CommStat):
                who is reporting problems, what kind, how bad, and how
                many stations at once.

What to look for, and how to show it, comes from a profile. Every
station gets SitRepNet's profile, SitRepNet (@SITREP), installed and
turned on with AlertDisplay: it covers the reports, weather and
traffic that matter to everyone. A group adds its own small profile
alongside it for traffic to its own group callsign; its coordinator
issues it, and every member who imports it sees the same alerts. Each
operator can also build personal profiles for their own station, for
anything else, and use them alongside the others.

It runs silently in the background, beside SitRepMapper, on a Raspberry
Pi, Linux or Windows. It makes no sound and never transmits.


THE PROBLEM IT SOLVES
---------------------
JS8Call receives a steady stream of traffic: heartbeats, SNR queries,
other nets, and now and then the one message that matters. Reports
arrive on the map, but the map doesn't ask for your attention. An
operator who steps away, or is busy on another frequency, can miss:

  - an ALERT sent to the group,
  - a station reporting a flood, a fire or an outage,
  - several stations reporting problems at once,
  - a situation that is getting worse, or one that has eased.

AlertDisplay turns those into short lines on the screen you're already
watching, and keeps them there until they've had time to be seen.


WHAT A MEMBER SEES
------------------
Examples from SitRepNet's profile:

  Red ALERT strip
    ALERT from N0ABC: ALERT POWER OUT ALL COUNTY
    Natural Disaster: N0ABC Severe: Flood FM05OW 495 mi N
    Natural Disaster: N0ABC Major: Tsunami (was Severe: Flood) FM05OW
    Spreading: 3 stations reporting disasters/public safety (last 1 d)
    F!104 Problems: N0DEF EM73TU 373 mi NW

  Notification strip
    23 stations reporting; 4 flagged (2 F!104, 1 F!505, 1 CommStat),
    last 7 days
    WX: SEVERE THUNDERSTORM WARNING ORANGE CO (via N0ABC)
    Outage: N0GHI Moderate: Power Failure EL98HC 69 mi S
    Easing: N0ABC Moderate: Flood (was Severe: Flood) FM05OW 495 mi N
    Eased: N0DEF now Minor: Earthquake (was Severe: Earthquake)
    Spreading eased: 2 stations reporting disasters/public safety
    N0ABC has traffic for you

Distance and direction ("495 mi N") are worked out from the reported
grid and your own station's grid.

The first notification line is the same summary that SitRepMapper's
Bulletin Summary starts with, and it stays up all the time.

The Log
  Everything AlertDisplay does is also written to its log, which the
  settings window shows on its Log tab, with the time (UTC) of each
  entry:
    - every message that matched a trigger, with the full message
      text, and whether it was shown, was a repeat, or came from a
      station on an ignore list;
    - every Status Board event, including ones that weren't shown, and
      alerts that cleared by themselves;
    - alerts and notifications cleared or timed out;
    - the monitor starting and stopping, and any problem such as
      DIRECTED.TXT or the Status Board not being found.
  So after time away from the radio, a member can see what came in
  and what was shown, even after it has left the screen.


BENEFITS FOR A GROUP
--------------------
Everyone sees the same thing
  One profile, issued by the coordinator, means every member is alerted
  to the same events, in the same words, at the same level. No member
  has to work out for themselves what deserves attention.

Install, start, run
  AlertDisplay comes with SitRepNet's profile installed and turned on.
  A member installs it and starts the monitor, and it's working; a
  group member also imports the group's profile. There is nothing else
  to set up. Profiles use {MYCALL} (each member's own callsign, read
  from SitRepMapper), so one file works for every member. A newer
  AlertDisplay brings SitRepNet's latest profile with it, and
  AlertDisplay tells the member when a newer version is out (see
  Staying up to date, below).

Built on the reports you already send
  It uses the forms groups already use (F!104, F!309, F!505, F!500,
  CommStat StatRep) and SitRepMapper's own Sub-Optimal Thresholds. No
  new forms, codes or procedures are needed on the air.

The whole picture, not just single reports
  Besides single stations, it alerts when problems spread: several
  stations reporting a disaster, or a third of all stations flagged.
  It follows an incident as it builds (first report, getting worse,
  spreading) and as it subsides (easing, eased, resolved, spreading
  eased, back to normal). It removes an alert by itself when the
  station's newer report shows the problem has passed, or when an
  incident report is marked Resolved or reaches its own expiration
  time. Incident alerts show where the incident is, not just where the
  reporting station is.

Coordinator control, member choice
  A group profile opens read-only, so members can't change it by
  accident. Each member can still turn single triggers off (net
  check-ins, for instance), and those choices survive the group's next
  release.

Easy to update
  The coordinator edits the profile, exports a new release (numbered
  by date, e.g. 2026-11-12.1) and sends the file. Members import it
  over the old one.

One common base, several groups at once
  Every station has SitRepNet's profile, so every station alerts on
  the same reports in the same way, whichever groups it belongs to.
  Each group's own profile is small: just the traffic to its group
  callsign. A station in several groups imports each one. Each
  watches for its own group callsign, and a message that matches more
  than one shows once.

Safe for radio stations
  No sound (audio can interfere with a Pi's radio interface), no
  transmitting, and no internet connection needed.

Staying up to date
  When the settings window opens, AlertDisplay checks SitRepNet.com
  for a newer version and, if there is one, offers to open the download
  page. With no internet it says nothing and works as usual; the
  monitor never checks. A member can turn the check off, or check at
  any time, on the Settings tab. Nothing is downloaded or installed
  without the member doing it.

Fewer false alarms
  Matching is by whole word or phrase, so ALERT doesn't fire on
  ALERTED. Repeats and relays of the same message are shown once.
  General words like ALERT are a full alert only when sent to your
  group; from other nets they are a notification.

A record of what happened
  The Log keeps every match and every alert with its time, so a member
  can catch up after being away, and a coordinator can check why an
  alert did or didn't show when tuning the group's profile.


THE STANDARD PROFILE: SITREPNET (@SITREP)
-----------------------------------------
SitRepNet's profile is installed with AlertDisplay on every station,
and kept up to date with each new AlertDisplay. It has 33 triggers:

  SitRep's own
    SitRep's own alert code, SITREP-ALERT, sent to @SITREP: a red
    alert showing the text after the code. SitRep net activation is
    off until SitRepNet sets the wording.

  Messages, same for every group
    ALERT or EMERGENCY, and life-threatening weather warnings, to the
    group (and, as a notification, from anyone else);
    other weather warnings and watches; evacuation orders; traffic for
    your station; F!309 incident reports to the group; net check-ins
    (off).

  Incident reports (F!309), by category
    Natural disasters (severe weather, flood, earthquake, tsunami) and
    public safety (fire, civil disturbance, terrorism, evacuation) are
    alerts, as is any Major report. Infrastructure outages (power,
    internet/cell, water, roads) and supply reports (food, fuel,
    medical and others) are notifications.

  Station reports
    F!104 Problems, CommStat Red and F!505 below 1.00 are alerts.
    F!104 Degraded, CommStat Yellow, F!505 and F!500 problems are
    notifications. So are "got worse", "improving" and "back to
    normal".

  The whole picture
    Incidents spreading (3 stations), a regional event (10 stations),
    and widespread problems (a third of the stations reporting), each
    with a notice when it eases.

Each trigger has a description saying what it does; open the profile
in the settings window (Profiles tab) to read them.


ADDING YOUR GROUP
-----------------
Keep SitRepNet's profile on; add your group's profile alongside it.
AlertDisplay_Group_Template.json, in the program folder, is the
starting point. It has just the three triggers that belong to your
group alone, all off until you set them up:

    Group net activation   ALR   your net control's activation words
    Group alert code       ALR   your group's own alert code
    Net check-ins          NTF   check-ins to your group (optional)

Everything else (ALERT and EMERGENCY, weather warnings, evacuation
orders, traffic for your station, and every report on the Status
Board) already comes from SitRepNet's profile, so it isn't repeated,
and nothing shows twice. ALERT, EMERGENCY or a life-threatening
weather warning sent to your group shows as a notification from
SitRepNet's profile (it's a red alert only for @SITREP); to make it a
red alert for your group too, add a trigger for it (see below).

In the settings window (Profiles tab):

  1. Import Group Profile... and choose AlertDisplay_Group_Template.json
     from the program folder. It comes in as a personal profile, so you
     can edit it. (Your members will get a group profile; step 5 makes
     that.)
  2. Open it. Change its Name to your group's (e.g. Lake County ARES),
     and set Group callsign to your group's call, with the @ (e.g.
     @LCARES). Every trigger that says {GROUP} now means your group.
  3. Edit the two YOUR GROUP triggers, and turn on Net check-ins if
     your members want them:
       - Group net activation: change the words to what your net
         control sends, and turn it on.
       - Group alert code: use the standard form, your group name
         and -ALERT (e.g. LCARES-ALERT for @LCARES), and turn it on.
         It's matched as a whole word anywhere in a message to your
         group, so it also works when sent with MSG. Test it on the
         air once.
  4. Test a Message tab: paste a few real messages and check what
     shows.
  5. Select it on the Profiles tab and click Export as Group
     Profile... This is the step that makes it a group profile: the
     file it writes is marked as a group profile, with your callsign as
     Author and a Release number (e.g. 2026-11-12.1). It also offers a
     Profile ID made from your group callsign (e.g. lcares); keep that
     ID for every later release. Save the file.
  6. Send that file to your members. Each imports it with Import Group
     Profile... It opens read-only for them, and their on/off choices
     for its triggers survive your later releases.

Your own copy stays a personal profile, so you can keep editing it.
For a new release: edit your copy, Test a Message, Export as Group
Profile again (it offers the next Release number and the same Profile
ID), and send the new file. Members import it over the old one.

That's all most groups will need. Beyond that, a coordinator can:

  - Turn a trigger off for everyone, or on (the On box).
  - Change a trigger between alert (ALR) and notification (NTF).
  - Change how long it stays up (Minutes shown) and how soon a repeat
    can show again (Cooldown minutes).
  - Change its wording (Banner text), using placeholders such as
    {FROM}, {STATUS}, {GRID} and {RANGE}.
  - Add words or phrases your area uses, e.g. a local net's activation
    phrase or a regional weather term.
  - Make ALERT or EMERGENCY to your group a red alert: add a trigger
    matching ALERT, ALERTS and EMERGENCY (Whole word), To {GROUP},
    Display ALR. AlertDisplay_ProfileBuilding.txt, Example 6, shows how.
  - Add triggers for your own codes, for traffic from particular
    stations (From), or to particular stations or groups (To).
  - Add a Status Board trigger for something SitRepNet's profile
    doesn't cover, narrowed to what your group cares about: only F!104
    Problems, only CommStat Red, some F!309 categories or severities,
    F!505 below a chosen score, or its own levels for spreading
    problems.

Things that are set elsewhere, not in the profile:

  - What counts as a problem ("flagged") for F!104, F!309, F!505, F!500
    and CommStat, and how many days the Status Board covers: in each
    member's SitRepMapper (Settings > Sub-Optimal Thresholds, and
    Reports > Status Board). A group can give members recommended
    values.
  - Each member's own callsign and grid: in SitRepMapper.
  - Whether a member keeps a trigger on, which stations they ignore,
    and how the notification strip looks: in the member's own
    AlertDisplay. That includes SitRepNet's triggers: a member can turn
    any of them off, and the choice survives each new release.

AlertDisplay_ProfileBuilding.txt explains every setting, with worked
examples.


WHAT A MEMBER NEEDS
-------------------
  - SitRepMapper v1.18.0 or later, set up with the member's callsign
    and grid.
  - JS8Call, writing its DIRECTED.TXT log (it does by default).
  - Python 3.9 or newer with tkinter. Nothing else to install.
  - A Raspberry Pi 4B or newer, desktop Linux, or Windows 10/11.


WHAT IT DOESN'T DO
------------------
  - It doesn't transmit or acknowledge anything. Replies are up to the
    operator (JS8Call's MSG function).
  - It makes no sound.
  - It doesn't download or install updates by itself; it only says
    when one is available.
  - It doesn't decide what counts as a problem in a report;
    SitRepMapper's thresholds do. It only chooses what to show.


FOR MORE INFORMATION
--------------------
  AlertDisplay_Installation_Guide.txt   Installing and updating
  AlertDisplay_User_Manual.txt          Everything about the program
  AlertDisplay_ProfileBuilding.txt      Building profiles and triggers


================================================================================
Designed and developed by Stephen Clay McGehee, KN4AM
Coding done using Claude Code AI
See SitRepNet.com for more information
================================================================================
