Integraciones MQTT

Crea un servicio externo que siga a Presenter o intercambie mensajes en tus propios temas. Las credenciales persistentes tienen una contraseña mostrada una sola vez y permisos limitados. Nunca permiten enviar órdenes de proyección.

Las credenciales Locales requieren una licencia Presenter Own, Flex o una licencia anterior de pago compatible, también mediante Complete. Permanecen en ese equipo y no necesitan cuenta en la nube. SundayAssist Cloud exige una suscripción Complete activa, iniciar sesión, pertenecer a la organización y ser propietario o administrador. Una prueba gratuita no da este acceso.

Crear credenciales

  1. Abre Conexiones → Control desde el teléfono → Credenciales de integración y elige Local o SundayAssist Cloud.
  2. Elige Crear credenciales, asigna un nombre al servicio e introduce sus Temas de publicación y Temas de suscripción, uno por línea. Deja vacía la dirección que no uses. Para el ejemplo siguiente, activa Leer eventos de Presenter y deja vacíos los temas personalizados.
  3. Guarda inmediatamente la contraseña en el almacén de secretos del servicio. Copiar datos de conexión la incluye. Solo se muestra una vez y no se puede recuperar después.
  4. Usa credenciales distintas para cada servicio. Cada credencial permite hasta 20 entradas de temas. Puede haber hasta 20 activas por instalación local, o por cuenta y organización en la nube.

Conectar al broker adecuado

Usa MQTT 3.1.1 o 5. Copia la dirección local y los puertos que muestra Presenter; los habituales son TCP 1883 y WebSocket 9883, con alternativas si están ocupados. La conexión local no está cifrada: usa una red de confianza y nunca expongas estos puertos a Internet. La nube usa TLS en el puerto 8883, o WebSocket seguro en el puerto 443 con la ruta /mqtt. Mantén la verificación de certificados. Cada conexión simultánea necesita un identificador de cliente único que empiece por el prefijo asignado.

Local:
  mqtt://<presenter-lan-ip>:1883
  ws://<presenter-lan-ip>:9883/mqtt
Complete cloud:
  mqtts://mqtt.sundayassist.com:8883
  wss://mqtt.sundayassist.com/mqtt
username: <generated-username>
password: <shown-once-password>
clientId: <assigned-client-id-prefix>external-1

Elegir temas personalizados

Las publicaciones requieren temas exactos. Las suscripciones permiten un tema exacto o un /# final bajo un espacio de nombres literal, como church/lyrics/#. Se rechazan el comodín +, un # solo, niveles vacíos, espacios y $. El primer espacio de nombres no puede ser sundayassist, independientemente de las mayúsculas. El permiso explícito de lectura de eventos es la excepción reservada.

Los permisos locales corresponden a esa instalación de Presenter. Los temas en la nube están aislados por organización: usa el mismo tema en ambos clientes, sin prefijo de organización. Las personas de la misma organización con permisos que se solapen pueden intercambiar mensajes. Estas credenciales no permiten vincular Remote, acceder a su protocolo de presentación/estado, usar IA, relay o Presenter-link ni publicar en temas reservados de SundayAssist. Las publicaciones personalizadas permiten QoS 0 o 1, sin retención, hasta 1 MiB.

Leer eventos de Presenter

Activa Leer eventos de Presenter y suscríbete a sundayassist/integrations/v1/events/#, o limita a sundayassist/integrations/v1/events/<presenterId>/state. Presenter publica una instantánea JSON retenida con QoS 1 y el siguiente contrato público. Incluye títulos; excluye letras, notas, rutas de archivos, capturas y datos de cuenta. La tarjeta o sección puede ser null.

{
  "schemaVersion": 1,
  "eventId": "boot-id:42",
  "presenterId": "opaque-installation-id",
  "runId": "boot-id",
  "sequence": 42,
  "occurredAt": "2026-10-27T12:00:00Z",
  "type": "presenter.state",
  "state": {
    "presenting": true,
    "blanked": false,
    "phase": "active",
    "cue": {"id": "opaque-occurrence", "type": "lyrics", "title": "Welcome", "index": 0},
    "section": {"id": "opaque-section", "title": "Gathering", "index": 0},
    "position": {"subIndex": 0, "page": 0}
  }
}

Usa eventId para eliminar duplicados y sequence para ordenar mensajes dentro del mismo runId. Reiniciar Presenter crea una ejecución nueva. Reconectar puede repetir el mismo evento. Los identificadores de tarjeta y sección son referencias opacas a apariciones; editar o reordenar la presentación puede cambiarlos. Los índices empiezan en cero; subIndex puede ser -1 para una diapositiva predeterminada.

Los cambios se agrupan durante un máximo de 1 segundo, con una instantánea nueva normalmente cada 15 segundos aunque nada cambie. Comprueba occurredAt y el indicador de retención MQTT antes de actuar. Una instantánea retenida puede durar más que Presenter y no demuestra que esté conectado. Es el último estado conocido, no un registro completo ni el programa futuro.

Prueba la vista en directo de Node.js

Descarga el ejemplo funcional o abre la vista previa simulada. Con Node.js 22 o posterior puedes iniciar una vista de la tarjeta actual y una cronología de tarjetas recibidas, sin broker ni licencia:

unzip mqtt-showcase.zip
cd mqtt-showcase
npm ci
npm run demo

Para eventos reales, copia .env.example a .env y completa la URL del broker, usuario, contraseña y prefijo de cliente generados. Configura PRESENTER_ID si varios Presenters comparten la organización en la nube y ejecuta npm start. Abre http://127.0.0.1:4188. Sin identificador se selecciona el primer Presenter. Las credenciales permanecen en Node; el navegador solo recibe los campos públicos seleccionados por Server-Sent Events. Mantén .env privado. El ejemplo es un servidor local de desarrollo, no un servicio alojado compartido.

En Node-RED, conecta un nodo MQTT in al broker indicado. Introduce el usuario y contraseña generados y un identificador de cliente único con el prefijo asignado; activa TLS con verificación de certificados para la nube. Configura el tema de eventos anterior y QoS 1, y conecta JSON → debug. Lee msg.payload.state.cue.title, comprueba msg.payload.occurredAt y elimina duplicados por msg.payload.eventId antes de iniciar una acción. Consulta la referencia oficial de MQTT.js y el recetario MQTT de Node-RED.

Recibir texto en directo

Para texto local, permite que el servicio externo publique en church/lyrics/slide. En Conexiones → Control desde el teléfono → Mismo Wi-Fi, configura el Tema de letras en church/lyrics/slide. Añade una tarjeta de letras en directo desde la biblioteca y proyéctala. Publica texto UTF-8 simple en el broker local, sin envoltorio JSON.

Para texto en la nube de Complete, crea otras credenciales en la misma organización con suscripción solo a church/lyrics/slide. Elige Servidor propio en Presenter, introduce wss://mqtt.sundayassist.com/mqtt, esas credenciales y el mismo Tema de letras, guarda y prueba. La conexión local del teléfono sigue disponible. Servidor propio usa esta conexión manual en lugar de Desde cualquier lugar (Complete) automático; estas credenciales no dan acceso a Remote en la nube.

Reemplazar, revocar y gestionar interrupciones

Reemplazar contraseña invalida los datos anteriores y muestra los nuevos una sola vez; actualiza todos los clientes que los usen. Revocar desactiva esas credenciales permanentemente. Las credenciales locales persisten al reiniciar Presenter; las contraseñas no tienen caducidad fija. El acceso de pago y los permisos siguen siendo obligatorios. Puedes consultar y revocar las credenciales después de que termine el acceso de pago.

La elegibilidad en la nube y las conexiones activas se comprueban aproximadamente cada 30 segundos. Revocar no es instantáneo; una interrupción del control de permisos puede retrasar la desconexión unos minutos. Los clientes en la nube deben reconectar al menos una vez por hora con la contraseña actual. Activa la reconexión y la nueva suscripción automáticas. QoS 1 puede entregar duplicados; fallos de red, mantenimiento y conmutación por error pueden interrumpir la entrega. Haz que repetir las acciones sea seguro y conserva contenido local preparado. TLS protege la conexión de red, no el contenido de extremo a extremo.