Disparadores: comandos CLI

Disparadores de alertas CAP

Un disparador permite que un sistema de notificación de emergencia, como Everbridge, Rave, Alertus o un relé IPAWS, tome el control de las pantallas con alertas CAP 1.2. Cada disparador tiene su propia URL, nombre de usuario y contraseña, que debe ingresar en el sistema de envío como destino CAP HTTP POST con autenticación HTTP Basic. Una organización tiene como máximo 20 disparadores en todos sus proyectos.

Los activadores son de dos tipos. Un activador CAP, descrito aquí, recibe las alertas de un sistema de emergencias. Un activador de superposición muestra lo que publica cualquier remitente, como Home Assistant, un concentrador de sensores o una herramienta de alertas, como una franja sobre lo que se reproduce o como una toma de control; triggers create --kind overlay crea uno, y triggers update, triggers clear y triggers rotate-secret sirven a los dos tipos, mientras que triggers deliveries lee el registro de un activador de superposición.

Un disparador apunta a una etiqueta, resuelta cuando llega cada alerta, o hasta 500 ids de pantalla. Cada alerta se convierte en una toma de la lista de reproducción propia del disparador: una tarjeta a pantalla completa con el color de su gravedad, con el evento, titular, descripción e instrucción. Un ejercicio añade un banner EXERCISE. La toma se mantiene hasta el <expires> de la alerta, o el --for predeterminado del disparador (1 minuto a 7 días, 1 hora a menos que se establezca), y nunca más de 7 días. Una actualización redibuja la tarjeta, y una cancelación o AllClear devuelve cada pantalla a lo que mostraba antes. Una alerta nueva reemplaza a la que se muestra. Se ignoran mensajes de prueba, sistema y borrador, mensajes de acuse y error y alertas expiradas; un remitente e identificador repetidos son duplicados. Una pantalla necesita una lista de reproducción predeterminada para ser tomada; otras pantallas se omiten.

La contraseña, srtg_…, se muestra solo por triggers create y triggers rotate-secret, con la advertencia trigger_password_shown_once. La CLI la mantiene fuera de su configuración, registro de operaciones y estado de recuperación. La URL y el nombre de usuario no son secretos.

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

Activadores de superposición

Un activador de superposición muestra lo que publica un sistema externo. Home Assistant, un concentrador de sensores de puerta o de movimiento, un sistema de cámaras o una herramienta de alertas envía unas pocas palabras con un HTTP POST, y las pantallas del activador las muestran hasta que caducan o el remitente las termina. Es un activador como uno CAP: triggers create --kind overlay lo crea y cuenta para el mismo límite de 20 por organización.

--show bar dibuja una franja sobre lo que se reproduce en cada pantalla de destino, en el borde inferior o, con --edge top, en el superior. La franja entra cuando empieza una alerta y sale cuando termina la última; la lista de reproducción, sus páginas y sus tiempos no cambian. Una pantalla tiene una franja por borde, así que un activador de superposición cuyo borde ya ocupa otro activador en una pantalla no se muestra allí (triggers show cuenta esas pantallas como edge_taken), y una página que tiene su propia franja con presencia en ese borde la conserva. Una tarjeta de esquina o de ficha en ese borde se desplaza más allá de la altura de la franja, se muestre esta o no. No se dibuja ninguna franja en una página de espacio publicitario ni mientras hay una toma de control. --show takeover reproduce la alerta a pantalla completa en las pantallas de destino que tienen una lista de reproducción predeterminada, desde la primera alerta hasta que termina la última. Un activador de toma de control nunca reemplaza una toma de control que ya está en una pantalla, como la de un operador o una alerta de emergencia, y una alerta CAP la reemplaza.

Un destino por etiqueta se resuelve cuando empieza una alerta; una pantalla etiquetada después recibe la franja con la siguiente alerta que empiece. Una toma de control omite las pantallas sin lista de reproducción predeterminada. Una pantalla sin conexión se pone al día cuando se reconecta.

El remitente envía JSON, un formulario o multipart/form-data (las partes de archivo se ignoran) a data.url con Authorization: Bearer SECRET, o con HTTP Basic usando el id del activador como usuario y el secreto como contraseña. El secreto nunca va en la URL. Un envío tiene estos miembros; un miembro desconocido se rechaza y se nombra.

Una activación necesita al menos uno de label, title, message y note. Se rechaza el texto más largo que su límite y también duration fuera del rango de 10 segundos a 7 días, ambos con invalid_request que nombra el miembro. Cada activación o actualización mantiene su alerta durante duration desde ese envío, así que un sensor de movimiento que envía cada pocos segundos mantiene la franja y esta se retira duration después del último envío. Un activador muestra su alerta más reciente; al terminarla se vuelve a mostrar la anterior. Mantiene diez alertas y la undécima reemplaza a la más antigua. Una alerta termina unos diez segundos después de su hora. Una finalización enviada dos veces termina la alerta una sola vez, y la finalización de una alerta que no está activa no cambia nada.

La respuesta es un recibo: outcome (shown, updated, unchanged, ended o ignored), alert_id, until (nulo para una alerta mantenida hasta que se despeje) y active, las alertas que el disparador mantiene tras el envío. Un encabezado Idempotency-Key de 8 a 200 caracteres responde al reintento de un remitente con el primer recibo durante 24 horas. Un disparador admite 120 envíos por minuto. Un envío no cuenta para el límite de solicitudes de agentes, y un borrado nunca se rechaza, de modo que una alerta siempre puede retirarse de las pantallas.

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

Una dirección incorrecta, un secreto incorrecto, un activador desactivado, una firma ausente o incorrecta y cualquier GET dan el mismo 404 not_found, de modo que un remitente o la vista previa de un enlace no averigua cuál fue. triggers deliveries muestra al proyecto el motivo, durante los últimos siete días, sin el cuerpo del envío. --style FILE define theme, accent, background, backgroundColor, textColor y align de la tarjeta de texto; use un activador por aspecto.

--map FILE construye la publicación a partir del cuerpo que envía una herramienta de alertas, con el lenguaje de plantillas de los webhooks de tarjetas. Una cadena con {{body.title}} es texto, una cadena que es exactamente un marcador conserva su tipo, {"$text": "{{body.message}}", "$max": 400} recorta el texto y una ruta empieza con body o query. Esta plantilla transforma una alerta de una herramienta de monitorización y la termina cuando su estado es resolved:

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

--signing también exige ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, con la clave data.signing_secret (whsec_…, que se muestra una sola vez), donde t debe estar a menos de cinco minutos del reloj del servidor. El remitente puede enviar dos valores v1 mientras rota el secreto.

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"

Una herramienta de alertas o un proveedor que firma sus propios envíos puede hacer que se verifique su firma en lugar del secreto, y que se responda su handshake de configuración, como en los webhooks de tarjeta: triggers create y triggers update aceptan --verify VENDOR con --verify-secret-file FILE, y --handshake VENDOR, y triggers update acepta --clear-verify y --clear-handshake para quitar cada uno. Los proveedores, sus encabezados y las opciones de generic_hmac son los que se listan allí. Un envío que lleva la firma válida del proveedor se acepta sin la contraseña srtg_ del activador, que sigue funcionando a su lado; --verify excluye --signing, y un handshake no cambia ninguna alerta. triggers deliveries muestra por qué falló una firma.

Un rest_command de Home Assistant envía al activador. Guarde el secreto en secrets.yaml y dé a cada automatización la alerta que activa 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}

Dos hechos hacen que esto funcione. Cada envío de movimiento mantiene la franja 2 minutos desde ese envío, así que permanece mientras continúa el movimiento y se retira 2 minutos después del último evento. Y Home Assistant genera la plantilla {{ }} antes de enviar, de modo que el activador recibe JSON simple; la plantilla --map del propio activador es un paso aparte que hace pasar cada envío por ella; por eso, deje --map fuera para un remitente que ya envía los miembros de la superposición, como hace aquí Home Assistant, o dele su propio activador.