Déclencheurs : commandes CLI

Déclencheurs d’alerte CAP

Un déclencheur permet à un système de notification d’urgence, tel Everbridge, Rave, Alertus ou un relais IPAWS, de prendre le contrôle des écrans avec des alertes CAP 1.2. Chaque déclencheur a sa propre URL, nom d’utilisateur et mot de passe, que vous saisissez dans le système d’envoi comme destination HTTP POST CAP avec authentification HTTP Basic. Une organisation a au plus 20 déclencheurs, tous projets confondus.

Les déclencheurs sont de deux types. Un déclencheur CAP, décrit ici, reçoit les alertes d’un système d’urgence. Un déclencheur de superposition montre ce que n’importe quel expéditeur publie, comme Home Assistant, un concentrateur de détecteurs ou un outil d’alertes, en bande par-dessus ce qui est diffusé ou en prise de contrôle ; triggers create --kind overlay en crée un, et triggers update, triggers clear et triggers rotate-secret servent les deux types, tandis que triggers deliveries lit le journal d’un déclencheur de superposition.

Un déclencheur cible une étiquette, résolue à l’arrivée de chaque alerte, ou jusqu’à 500 identifiants d’écran. Chaque alerte devient une prise de contrôle de la playlist propre au déclencheur : une carte plein écran de la couleur de sa gravité, avec l’événement, le titre, la description et l’instruction. Un exercice ajoute une bannière EXERCISE. La prise de contrôle dure jusqu’à <expires> de l’alerte, sinon la valeur par défaut --for du déclencheur (1 minute à 7 jours, 1 heure sauf réglage), et jamais plus de 7 jours. Une mise à jour redessine la carte, et un annuler ou tout clair rend chaque écran à ce qu’il jouait avant. Une nouvelle alerte remplace celle affichée. Les messages Test, Système et Brouillon, les messages Ack et Erreur et les alertes expirées sont ignorés, et un expéditeur et identifiant répétés sont des doublons. Un écran a besoin d’une playlist par défaut pour être pris en charge ; les autres écrans sont ignorés.

Le mot de passe, srtg_…, est montré uniquement par triggers create et triggers rotate-secret, avec l’avertissement trigger_password_shown_once. Le CLI le garde hors de sa configuration, du journal d’opération et de l’état de récupération. L’URL et le nom d’utilisateur ne sont pas secrets.

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

Déclencheurs de superposition

Un déclencheur de superposition montre ce qu’un système externe publie. Home Assistant, un concentrateur de détecteurs de porte ou de mouvement, un système de caméras ou un outil d’alertes envoie quelques mots par une requête HTTP POST, et les écrans du déclencheur les affichent jusqu’à leur échéance ou jusqu’à ce que l’expéditeur y mette fin. C’est un déclencheur comme un déclencheur CAP : triggers create --kind overlay le crée, et il compte dans la même limite de 20 par organisation.

--show bar affiche une bande par-dessus ce qui est diffusé sur chaque écran ciblé, sur le bord inférieur ou, avec --edge top, sur le bord supérieur. La bande glisse à l’écran quand une alerte commence et en sort quand la dernière se termine ; la liste de lecture, ses pages et son rythme restent intacts. Un écran porte une bande par bord : une superposition dont le bord est déjà occupé sur un écran par une autre superposition n’y apparaît pas (triggers show compte ces écrans sous edge_taken), et une page qui a sa propre bande avec présence sur ce bord la conserve. Une carte de coin ou de pastille sur ce bord se déplace au-delà de la hauteur de la bande, qu’elle soit affichée ou non. Aucune bande n’est dessinée sur une page d’espace publicitaire ni pendant une prise de contrôle. --show takeover diffuse l’alerte en plein écran sur les écrans ciblés qui ont une liste de lecture par défaut, de la première alerte jusqu’à la fin de la dernière. Un déclencheur de prise de contrôle ne remplace jamais une prise de contrôle déjà en cours sur un écran, comme celle d’un opérateur ou d’une alerte d’urgence, et une alerte CAP la remplace.

Une cible par étiquette est résolue quand une alerte commence ; un écran étiqueté plus tard reçoit la bande à la prochaine alerte qui commence. Les écrans sans liste de lecture par défaut sont ignorés par une prise de contrôle. Un écran hors ligne se met à jour à sa reconnexion.

L’expéditeur publie du JSON, un formulaire ou multipart/form-data (les parties fichier sont ignorées) à data.url avec Authorization: Bearer SECRET, ou en HTTP Basic avec l’identifiant du déclencheur comme nom d’utilisateur et le secret comme mot de passe. Le secret ne figure jamais dans l’URL. Un envoi comporte les membres suivants ; un membre inconnu est refusé et nommé.

Un déclenchement exige au moins un de label, title, message et note. Un texte plus long que sa limite est refusé, tout comme duration hors de 10 secondes à 7 jours, les deux avec invalid_request qui nomme le membre. Chaque déclenchement ou mise à jour retient son alerte pendant duration à partir de cet envoi : un détecteur de mouvement qui envoie toutes les quelques secondes garde la bande affichée, et elle disparaît duration après le dernier envoi. Un déclencheur affiche son alerte la plus récente ; quand elle prend fin, la précédente reparaît. Il retient dix alertes, et la onzième remplace la plus ancienne. Une alerte prend fin dans les dix secondes environ suivant son échéance. Un arrêt envoyé deux fois met fin à l’alerte une seule fois, et l’arrêt d’une alerte qui n’est pas active ne change rien.

La réponse est un reçu : outcome (shown, updated, unchanged, ended ou ignored), alert_id, until (nul pour une alerte maintenue jusqu’à sa levée) et active, les alertes que le déclencheur détient après l’envoi. Un en-tête Idempotency-Key de 8 à 200 caractères répond à la nouvelle tentative d’un expéditeur avec le premier reçu pendant 24 heures. Un déclencheur accepte 120 envois par minute. Un envoi ne compte pas dans le plafond de requêtes d’agent, et une levée n’est jamais refusée, de sorte qu’une alerte peut toujours être retirée des écrans.

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

Une mauvaise adresse, un mauvais secret, un déclencheur désactivé, une signature absente ou mauvaise et tout GET donnent le même 404 not_found : l’expéditeur ou l’aperçu d’un lien n’apprend rien sur la cause. triggers deliveries montre au projet pourquoi, pour les sept derniers jours, sans corps d’envoi. --style FILE règle theme, accent, background, backgroundColor, textColor et align de la carte de texte ; utilisez un déclencheur par apparence.

--map FILE construit la publication à partir du corps qu’envoie un outil d’alertes, avec le langage de gabarits des webhooks de cartes. Une chaîne avec {{body.title}} est du texte, une chaîne qui est exactement un espace réservé garde son type, {"$text": "{{body.message}}", "$max": 400} coupe le texte, et un chemin commence par body ou query. Ce gabarit transforme une alerte d’un outil de surveillance et l’arrête lorsque son statut est resolved :

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

--signing exige aussi ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, avec la clé data.signing_secret (whsec_…, affichée une seule fois), où t se situe à moins de cinq minutes de l’horloge du serveur. L’expéditeur peut envoyer deux valeurs v1 pendant qu’il fait la rotation du secret.

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"

Un outil d’alerte ou un fournisseur qui signe ses propres envois peut faire vérifier sa signature à la place du secret, et sa poignée de main de configuration peut recevoir une réponse, comme pour les webhooks de carte : triggers create et triggers update acceptent --verify VENDOR avec --verify-secret-file FILE, et --handshake VENDOR, et triggers update accepte --clear-verify et --clear-handshake pour supprimer chacun. Les fournisseurs, leurs en-têtes et les options generic_hmac sont ceux qui y sont listés. Un envoi qui porte la signature valide du fournisseur est accepté sans le mot de passe srtg_ du déclencheur, qui continue de fonctionner à côté ; --verify exclut --signing, et une poignée de main ne change aucune alerte. triggers deliveries montre pourquoi une signature a échoué.

Une commande rest_command de Home Assistant envoie au déclencheur. Gardez le secret dans secrets.yaml et donnez à chaque automatisation l’alerte qu’elle déclenche ou arrête :

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

Deux faits expliquent le fonctionnement. Chaque envoi de mouvement retient la bande pendant 2 minutes à partir de cet envoi : elle reste tant que le mouvement continue et disparaît 2 minutes après le dernier événement. Et Home Assistant produit le gabarit {{ }} avant d’envoyer, de sorte que le déclencheur reçoit du JSON ordinaire ; le gabarit --map du déclencheur est une étape distincte qui fait passer chaque envoi par ce gabarit ; omettez donc --map pour un expéditeur qui envoie déjà les membres de la superposition, comme Home Assistant ici, ou donnez-lui son propre déclencheur.