Trigger: comandi CLI

Trigger alert CAP

Un trigger permette a un sistema di notifiche di emergenza, come Everbridge, Rave, Alertus o un relay IPAWS, di prendere il controllo degli schermi con avvisi CAP 1.2. Ogni trigger ha il proprio URL, nome utente e password, che inserisci nel sistema mittente come destinazione CAP HTTP POST con autenticazione HTTP Basic. Un’organizzazione ha al massimo 20 trigger in tutti i suoi progetti.

I trigger sono di due tipi. Un trigger CAP, descritto qui, accetta gli avvisi di un sistema di emergenza. Un trigger di sovrapposizione mostra ciò che pubblica qualsiasi mittente, come Home Assistant, un hub di sensori o uno strumento di allerta, come fascia sopra ciò che viene riprodotto o come acquisizione; triggers create --kind overlay ne crea uno, e triggers update, triggers clear e triggers rotate-secret servono entrambi i tipi, mentre triggers deliveries legge il registro di un trigger di sovrapposizione.

Un trigger mira a un tag, risolto all’arrivo di ogni avviso, o fino a 500 ID schermo. Ogni Alert diventa un takeover della playlist del trigger: una scheda a schermo intero nel colore della sua gravità, con evento, titolo, descrizione e istruzioni. Un Exercise aggiunge un banner EXERCISE. Il takeover dura fino a <expires> dell’avviso, altrimenti il default --for del trigger (da 1 minuto a 7 giorni, 1 ora se non impostato), e mai oltre 7 giorni. Un Update ridisegna la scheda, e un Cancel o AllClear restituisce ogni schermo a ciò che riproduceva prima. Un nuovo Alert sostituisce quello mostrato. Messaggi Test, System e Draft, Ack ed Error e avvisi scaduti sono ignorati, e un mittente e identificatore ripetuti sono duplicati. Uno schermo necessita di una playlist predefinita per essere preso in takeover; altri schermi sono saltati.

La password, srtg_…, è mostrata solo da triggers create e triggers rotate-secret, con l’avviso trigger_password_shown_once. Il CLI la tiene fuori dalla sua configurazione, log operativo e stato di recupero. L’URL e il nome utente non sono segreti.

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

Trigger di sovrapposizione

Un trigger di sovrapposizione mostra ciò che pubblica un sistema esterno. Home Assistant, un hub di sensori di porta o di movimento, un sistema di telecamere o uno strumento di allerta invia poche parole con un HTTP POST, e gli schermi del trigger le mostrano finché scadono o il mittente le termina. È un trigger come un trigger CAP: triggers create --kind overlay lo crea e rientra nello stesso limite di 20 per organizzazione.

--show bar disegna una fascia sopra ciò che viene riprodotto su ogni schermo di destinazione, sul bordo inferiore o, con --edge top, su quello superiore. La fascia entra quando inizia un avviso ed esce quando termina l'ultimo; la playlist, le sue pagine e i suoi tempi non cambiano. Uno schermo ha una fascia per bordo: un trigger di sovrapposizione il cui bordo è già occupato su uno schermo da un altro trigger non vi compare (triggers show conta questi schermi come edge_taken), e una pagina che ha una propria fascia con presenza su quel bordo la mantiene. Una scheda d'angolo o a pastiglia su quel bordo si sposta verso l'interno oltre l'altezza della fascia, che sia visibile o no. Nessuna fascia viene disegnata su una pagina di spazio pubblicitario né durante un'acquisizione. --show takeover riproduce l'avviso a schermo intero sugli schermi di destinazione che hanno una playlist predefinita, dal primo avviso alla fine dell'ultimo. Un trigger di acquisizione non sostituisce mai un'acquisizione già presente su uno schermo, come quella di un operatore o di un avviso di emergenza, e un avviso CAP lo sostituisce.

Una destinazione per tag viene risolta quando inizia un avviso; uno schermo etichettato dopo riceve la fascia con il prossimo avviso che inizia. Gli schermi senza playlist predefinita vengono saltati da un'acquisizione. Uno schermo offline si aggiorna quando si riconnette.

Il mittente invia JSON, un modulo o multipart/form-data (le parti file vengono ignorate) a data.url con Authorization: Bearer SECRET, oppure con HTTP Basic usando l'id del trigger come nome utente e il segreto come password. Il segreto non va mai nell'URL. Un invio ha questi membri; un membro sconosciuto viene rifiutato e nominato.

Un'attivazione richiede almeno uno tra label, title, message e note. Il testo più lungo del suo limite viene rifiutato, come duration fuori da 10 secondi - 7 giorni, entrambi con invalid_request che nomina il membro. Ogni attivazione o aggiornamento trattiene il suo avviso per duration da quell'invio; un sensore di movimento che invia ogni pochi secondi mantiene la fascia, e questa esce duration dopo l'ultimo invio. Un trigger mostra il suo avviso più recente; quando termina, riappare quello precedente. Trattiene dieci avvisi, e l'undicesimo sostituisce il più vecchio. Un avviso termina circa dieci secondi dopo la sua scadenza. Una chiusura inviata due volte termina l'avviso una sola volta, e la chiusura di un avviso non attivo non cambia nulla.

La risposta è una ricevuta: outcome (shown, updated, unchanged, ended o ignored), alert_id, until (nullo per un avviso mantenuto finché non viene cancellato) e active, gli avvisi che il trigger mantiene dopo l’invio. Un’intestazione Idempotency-Key da 8 a 200 caratteri risponde al nuovo tentativo di un mittente con la prima ricevuta per 24 ore. Un trigger accetta 120 invii al minuto. Un invio non conta nel limite di richieste agente, e una cancellazione non viene mai rifiutata, quindi un avviso può sempre essere tolto dagli schermi.

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"}'

Un indirizzo errato, un segreto errato, un trigger disattivato, una firma mancante o errata e qualsiasi GET danno lo stesso 404 not_found, così un mittente o l'anteprima di un link non capisce quale fosse. triggers deliveries mostra al progetto il motivo, per gli ultimi sette giorni, senza il corpo dell'invio. --style FILE imposta theme, accent, background, backgroundColor, textColor e align della scheda di testo; usi un trigger per ogni aspetto.

--map FILE costruisce il messaggio dal corpo inviato da uno strumento di allerta, con il linguaggio di modelli dei webhook delle schede. Una stringa con {{body.title}} è testo, una stringa che è esattamente un segnaposto mantiene il suo tipo, {"$text": "{{body.message}}", "$max": 400} taglia il testo e un percorso inizia con body o query. Questo modello converte un avviso di uno strumento di monitoraggio e lo termina quando il suo stato è resolved:

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

--signing richiede inoltre ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, firmato con data.signing_secret (whsec_…, mostrato una sola volta), dove t deve distare al massimo cinque minuti dall'orologio del server. Il mittente può inviare due valori v1 mentre ruota il segreto.

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"

Uno strumento di allerta o un fornitore che firma i propri invii può far verificare la sua firma al posto del segreto, e far rispondere al suo handshake di configurazione, come per i webhook delle schede: triggers create e triggers update accettano --verify VENDOR con --verify-secret-file FILE, e --handshake VENDOR, e triggers update accetta --clear-verify e --clear-handshake per rimuovere ciascuno. I fornitori, le loro intestazioni e le opzioni di generic_hmac sono quelli elencati lì. Un invio che porta la firma valida del fornitore è accettato senza la password srtg_ del trigger, che continua a funzionare accanto; --verify esclude --signing, e un handshake non cambia alcun allarme. triggers deliveries mostra perché una firma è fallita.

Un rest_command di Home Assistant invia al trigger. Tenga il segreto in secrets.yaml e dia a ogni automazione l'avviso che attiva o termina:

# 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}

Due fatti lo fanno funzionare. Ogni invio di movimento trattiene la fascia per 2 minuti da quell'invio, quindi resta finché il movimento continua ed esce 2 minuti dopo l'ultimo evento. E Home Assistant genera il modello {{ }} prima di inviare, così il trigger riceve JSON semplice; il modello --map del trigger è un passaggio separato che fa passare ogni invio attraverso di esso; quindi lascia --map fuori per un mittente che invia già i membri della sovrapposizione, come fa qui Home Assistant, oppure dagli un trigger tutto suo.