Auslöser: CLI-Befehle

CAP-Alarm-Auslöser

Ein Trigger ermöglicht es einem Notifikationssystem wie Everbridge, Rave, Alertus oder einem IPAWS-Relay, Bildschirme mit CAP 1.2-Warnungen zu übernehmen. Jeder Trigger hat seine eigene URL, Benutzername und Passwort, die Sie im sendenden System als dessen CAP-HTTP-POST-Ziel mit HTTP-Basic-Authentifizierung eingeben. Eine Organisation hat höchstens 20 Trigger über alle ihre Projekte.

Trigger gibt es in zwei Arten. Ein CAP-Trigger, hier beschrieben, nimmt die Meldungen eines Notfallsystems an. Ein Overlay-Trigger zeigt, was ein beliebiger Absender sendet, etwa Home Assistant, ein Sensor-Hub oder ein Alarmierungswerkzeug, als Streifen über dem Laufenden oder als Übernahme; triggers create --kind overlay legt einen an, und triggers update, triggers clear und triggers rotate-secret bedienen beide Arten, während triggers deliveries das Protokoll eines Overlay-Triggers liest.

Ein Trigger zielt auf ein Tag, das bei jedem Eintreffen einer Warnung aufgelöst wird, oder auf bis zu 500 Bildschirm-IDs. Jede Warnung wird zur Übernahme der eigenen Playlist des Triggers: eine Vollbildkarte in der Farbe ihrer Schwere, mit Ereignis, Überschrift, Beschreibung und Anweisung. Eine Übung fügt ein EXERCISE-Banner hinzu. Die Übernahme hält bis zum <expires> der Warnung, sonst bis zum Standard --for des Triggers (1 Minute bis 7 Tage, 1 Stunde, wenn nicht gesetzt), und niemals länger als 7 Tage. Ein Update zeichnet die Karte neu, und ein Abbruch oder AllClear gibt jeden Bildschirm zurück zu dem, was er vorher spielte. Eine neue Warnung ersetzt die angezeigte. Test-, System- und Entwurfsnachrichten, Ack- und Fehlermeldungen sowie abgelaufene Warnungen werden ignoriert, und ein wiederholter Absender und Bezeichner ist ein Duplikat. Ein Bildschirm benötigt eine Standard-Playlist, um übernommen zu werden; andere Bildschirme werden übersprungen.

Das Passwort, srtg_…, wird nur von triggers create und triggers rotate-secret angezeigt, mit der Warnung trigger_password_shown_once. Die CLI hält es aus ihrer Konfiguration, dem Betriebsprotokoll und dem Wiederherstellungszustand heraus. Die URL und der Benutzername sind nicht geheim.

triggers create --name NAME [--kind cap|overlay] (--tag TAG | --screen-id ID...) [--for DURATION] [--pull FILE]
    [--show bar|takeover] [--edge bottom|top] [--style FILE] [--map FILE] [--signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]]
    [--handshake VENDOR]

screenrig triggers create --name "Campus alerts" --tag Campus
screenrig triggers create --name "Campus alerts" --tag Campus --pull pull.json
screenrig triggers create --name "Lobby sensors" --kind overlay --show bar --tag Lobby
screenrig triggers create --name "Doorbell" --kind overlay --show takeover --tag Lobby --for 30s
screenrig triggers create --name "Payments" --kind overlay --show bar --tag Lobby --verify stripe --verify-secret-file stripe.secret --map stripe-map.json
screenrig triggers create --name "Boards" --kind overlay --show bar --tag Lobby --handshake trello

triggers list

screenrig triggers list

triggers show <id>

screenrig triggers show trg_01EXAMPLETRIGGER00

triggers test <id>

screenrig triggers test trg_01EXAMPLETRIGGER00

triggers update <id> [--name NAME] [--tag TAG | --screen-id ID...] [--for DURATION] [--pull FILE | --no-pull]
    [--edge bottom|top] [--style FILE | --clear-style] [--map FILE | --clear-map] [--enable | --disable]
    [--signing | --no-signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS] | --clear-verify]
    [--handshake VENDOR | --clear-handshake] [--expect-rev REVISION]

screenrig triggers update trg_01EXAMPLETRIGGER00 --tag Lobby
screenrig triggers update trg_01EXAMPLETRIGGER00 --edge top --style style.json
screenrig triggers update trg_01EXAMPLETRIGGER00 --map map.json --signing
screenrig triggers update trg_01EXAMPLETRIGGER00 --verify github --verify-secret-file github.secret
screenrig triggers update trg_01EXAMPLETRIGGER00 --clear-verify

triggers deliveries <id> [--limit N]

screenrig triggers deliveries trg_01EXAMPLETRIGGER00 --limit 20

triggers clear <id> [--alert-id ID]

screenrig triggers clear trg_01EXAMPLETRIGGER00
screenrig triggers clear trg_01EXAMPLETRIGGER00 --alert-id front-door

triggers rotate-secret <id> [--signing] [--expect-rev REVISION]

screenrig triggers rotate-secret trg_01EXAMPLETRIGGER00

triggers delete <id> [--expect-rev REVISION]

screenrig triggers delete trg_01EXAMPLETRIGGER00

Overlay-Trigger

Ein Overlay-Trigger zeigt, was ein externes System sendet. Home Assistant, ein Tür- oder Bewegungsmelder-Hub, ein Kamerasystem oder ein Alarmierungswerkzeug sendet mit einem HTTP-POST wenige Worte, und die Bildschirme des Triggers zeigen sie, bis sie ablaufen oder der Absender sie beendet. Er ist ein Trigger wie ein CAP-Trigger: triggers create --kind overlay legt ihn an, und er zählt zum selben Limit von 20 pro Organisation.

--show bar zeichnet einen Streifen über das, was auf jedem Zielbildschirm läuft, am unteren Rand oder mit --edge top am oberen. Der Streifen gleitet ein, wenn eine Meldung beginnt, und aus, wenn die letzte endet; Playlist, Seiten und Timing bleiben unverändert. Ein Bildschirm hält einen Streifen pro Rand: Ein Overlay-Trigger, dessen Rand auf einem Bildschirm schon ein anderer Overlay-Trigger belegt, erscheint dort nicht (triggers show zählt diese Bildschirme als edge_taken), und eine Seite mit eigenem Streifen mit Präsenz an diesem Rand behält ihn. Eine Eck- oder Chip-Karte an diesem Rand rückt über die Höhe des Streifens hinaus nach innen, ob er sichtbar ist oder nicht. Auf einer Werbeplatz-Seite und während einer Übernahme wird kein Streifen gezeichnet. --show takeover spielt die Meldung vollbildlich auf den Zielbildschirmen ab, die eine Standard-Playlist haben, von der ersten Meldung bis zum Ende der letzten. Ein Übernahme-Trigger ersetzt nie eine Übernahme, die schon auf einem Bildschirm läuft, etwa die eines Operators oder einer Notfallmeldung, und eine CAP-Meldung ersetzt ihn.

Ein Tag-Ziel wird aufgelöst, wenn eine Meldung beginnt; ein später mit dem Tag versehener Bildschirm erhält den Streifen mit der nächsten beginnenden Meldung. Bildschirme ohne Standard-Playlist überspringt eine Übernahme. Ein Bildschirm, der offline ist, holt beim Wiederverbinden auf.

Der Absender sendet JSON, ein Formular oder multipart/form-data (Dateiteile werden ignoriert) an data.url mit Authorization: Bearer SECRET oder mit HTTP Basic, die Trigger-ID als Benutzername und das Geheimnis als Passwort. Das Geheimnis steht nie in der URL. Eine Sendung hat diese Felder; ein unbekanntes Feld wird abgelehnt und benannt.

Ein Auslösen braucht mindestens eines von label, title, message und note. Längerer Text wird abgelehnt, ebenso duration außerhalb von 10 Sekunden bis 7 Tagen, beides mit invalid_request, das das Feld nennt. Jedes Auslösen oder Aktualisieren hält seine Meldung duration ab dieser Sendung; ein Bewegungsmelder, der alle paar Sekunden sendet, hält den Streifen oben, und er verschwindet duration nach der letzten Sendung. Ein Trigger zeigt seine neueste Meldung; endet sie, erscheint die davor wieder. Er hält zehn Meldungen, die elfte ersetzt die älteste. Eine Meldung endet etwa zehn Sekunden nach ihrer Zeit. Ein zweimal gesendetes Beenden beendet die Meldung nur einmal, und das Beenden einer nicht aktiven Meldung ändert nichts.

Die Antwort ist eine Quittung: outcome (shown, updated, unchanged, ended oder ignored), alert_id, until (null bei einem Alarm, der bis zum Löschen gehalten wird) und active, die Alarme, die der Trigger nach dem Post hält. Ein Idempotency-Key-Header von 8 bis 200 Zeichen beantwortet die Wiederholung eines Absenders 24 Stunden lang mit der ersten Quittung. Ein Trigger nimmt 120 Posts pro Minute an. Ein Post zählt nicht zum Limit für Agentenanfragen, und ein Löschen wird nie abgelehnt, sodass ein Alarm immer von den Bildschirmen genommen werden kann.

curl -X POST https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay \
  -H "Authorization: Bearer srtg_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"front-door","title":"Front door","message":"The front door is open","duration":"10m"}'

Eine falsche Adresse, ein falsches Geheimnis, ein deaktivierter Trigger, eine fehlende oder falsche Signatur und jedes GET geben dasselbe 404 not_found; ein Absender oder die Linkvorschau erfährt so nichts darüber, was es war. triggers deliveries zeigt dem Projekt den Grund für die letzten sieben Tage, ohne den Body der Sendung. --style FILE legt theme, accent, background, backgroundColor, textColor und align der Textkarte fest; ein Trigger pro Aussehen.

--map FILE baut die Meldung aus dem Body, den ein Alarmierungswerkzeug sendet, mit der Vorlagensprache der Karten-Webhooks. Ein String mit {{body.title}} ist Text, ein String, der genau ein Platzhalter ist, behält seinen Typ, {"$text": "{{body.message}}", "$max": 400} kürzt Text, und ein Pfad beginnt mit body oder query. Diese Vorlage bildet eine Meldung eines Überwachungswerkzeugs ab und beendet sie, wenn ihr Status resolved ist:

{"alert_id": "{{body.groupKey}}", "title": "{{body.title}}", "message": {"$text": "{{body.message}}", "$max": 400}, "state": "{{body.status}}"}

--signing verlangt außerdem ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, geschlüsselt mit data.signing_secret (whsec_…, nur einmal angezeigt), wobei t höchstens fünf Minuten von der Uhr des Servers abweichen darf. Ein Absender darf zwei v1-Werte mitsenden, während er das Geheimnis rotiert.

body='{"alert_id":"front-door","title":"Front door","message":"The front door is open"}'
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST "$URL" -H "Authorization: Bearer $SECRET" -H "ScreenRig-Signature: t=$t,v1=$sig" \
  -H "Content-Type: application/json" -d "$body"

Ein Alarmierungstool oder ein Anbieter, der seine eigenen Zustellungen signiert, kann seine Signatur anstelle des Secrets prüfen lassen, und sein Einrichtungs-Handshake wird beantwortet, wie bei Karten-Webhooks: triggers create und triggers update nehmen --verify VENDOR mit --verify-secret-file FILE und --handshake VENDOR an, und triggers update nimmt --clear-verify und --clear-handshake an, um jeweils eines zu entfernen. Die Anbieter, ihre Header und die generic_hmac-Optionen sind die dort aufgeführten. Eine Zustellung mit der gültigen Signatur des Anbieters wird ohne das srtg_-Passwort des Triggers akzeptiert, das daneben weiter funktioniert; --verify schließt --signing aus, und ein Handshake ändert keinen Alarm. triggers deliveries zeigt, warum eine Signatur fehlgeschlagen ist.

Ein rest_command von Home Assistant sendet an den Trigger. Das Geheimnis gehört in secrets.yaml; jede Automatisierung nennt die Meldung, die sie auslöst oder beendet:

# secrets.yaml
screenrig_lobby_overlay: "Bearer srtg_YOUR_SECRET"

# configuration.yaml
rest_command:
  screenrig_lobby:
    url: "https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay"
    method: post
    headers:
      Authorization: !secret screenrig_lobby_overlay
    content_type: "application/json"
    payload: >-
      {{ {"alert_id": alert_id | default(""), "title": title | default(""),
          "message": message | default(""), "duration": duration | default("10m"),
          "clear": clear | default(false)} | tojson }}

# automations.yaml
- alias: Front door open on the lobby screens
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, title: Front door, message: The front door is open, duration: until_cleared}
- alias: Front door closed
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "off"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, clear: true}
- alias: Driveway motion
  triggers:
    - trigger: state
      entity_id: binary_sensor.driveway_motion
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: driveway, title: Driveway, message: Motion at the driveway, duration: 2m}

Zwei Dinge sorgen dafür, dass das funktioniert. Jede Bewegungssendung hält den Streifen 2 Minuten ab dieser Sendung; er bleibt, solange die Bewegung anhält, und verschwindet 2 Minuten nach dem letzten Ereignis. Und Home Assistant rendert die {{ }}-Vorlage vor dem Senden, sodass der Trigger schlichtes JSON erhält; die eigene --map-Vorlage des Triggers ist ein getrennter Schritt, der jede Sendung durch die Vorlage laufen lässt; lassen Sie --map daher bei einem Absender weg, der die Overlay-Felder bereits selbst sendet, wie Home Assistant hier, oder geben Sie diesem Absender einen eigenen Trigger.