Intégrations MQTT

Créez un service externe qui suit Presenter ou échange des messages sur vos propres topics. Les identifiants persistants ont un mot de passe affiché une seule fois et des droits limités. Ils ne permettent jamais de commander la projection.

Les identifiants Locaux exigent une licence Presenter Own, Flex ou une ancienne licence payante éligible, y compris via Complete. Ils restent sur cet ordinateur et ne nécessitent aucun compte cloud. SundayAssist Cloud exige un abonnement Complete actif, une connexion au compte, l’appartenance à l’organisation et le rôle de propriétaire ou d’administrateur. Un essai gratuit ne donne pas cet accès.

Créer des identifiants

  1. Ouvrez Connexions → Télécommande par téléphone → Identifiants d’intégration et choisissez Local ou SundayAssist Cloud.
  2. Choisissez Créer des identifiants, nommez le service et saisissez ses Topics de publication et Topics d’abonnement, un par ligne. Laissez vide le sens inutilisé. Pour l’exemple ci-dessous, activez Lire les événements Presenter et laissez les topics personnalisés vides.
  3. Enregistrez immédiatement le mot de passe dans le coffre à secrets du service. Copier les paramètres de connexion l’inclut. Il ne s’affiche qu’une fois et ne peut pas être récupéré ensuite.
  4. Utilisez des identifiants distincts pour chaque service. Un jeu autorise jusqu’à 20 entrées de topics. Au maximum 20 jeux peuvent être actifs par installation locale, ou par compte et organisation dans le cloud.

Se connecter au bon broker

Utilisez MQTT 3.1.1 ou 5. Copiez l’adresse locale et les ports indiqués par Presenter ; les ports habituels sont TCP 1883 et WebSocket 9883, avec des alternatives s’ils sont occupés. Le trafic local n’est pas chiffré : utilisez un réseau de confiance et n’exposez jamais ces ports à Internet. Le cloud utilise TLS sur le port 8883, ou WebSocket sécurisé sur le port 443 avec le chemin /mqtt. Gardez la vérification des certificats activée. Chaque connexion simultanée exige un identifiant client unique commençant par le préfixe attribué.

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

Choisir les topics personnalisés

Les publications exigent des noms exacts. Les abonnements acceptent un topic exact ou un /# final sous un espace de noms fixe, comme church/lyrics/#. Le joker +, un # seul, les niveaux vides, les espaces et $ sont refusés. Le premier espace de noms ne peut pas être sundayassist, quelle que soit la casse. Le droit explicite de lecture des événements est l’exception réservée.

Les droits locaux concernent cette installation Presenter. Les topics cloud sont isolés dans l’organisation : utilisez le même topic sur les deux clients, sans préfixe d’organisation. Des personnes de la même organisation dont les droits se recoupent peuvent échanger des messages. Ces identifiants ne permettent pas d’associer Remote, d’accéder à son protocole de présentation/état, d’utiliser l’IA, le relais ou Presenter-link, ni de publier sur les topics réservés à SundayAssist. Les publications personnalisées acceptent QoS 0 ou 1, sans rétention, jusqu’à 1 MiB.

Lire les événements Presenter

Activez Lire les événements Presenter et abonnez-vous à sundayassist/integrations/v1/events/#, ou limitez à sundayassist/integrations/v1/events/<presenterId>/state. Presenter publie un instantané JSON conservé en QoS 1 selon le contrat public suivant. Les titres sont inclus ; paroles, notes, chemins de fichiers, captures et données de compte sont exclus. La carte ou la section peut être 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}
  }
}

Utilisez eventId pour dédupliquer et sequence pour ordonner les messages dans le même runId. Un redémarrage de Presenter crée une nouvelle exécution. Une reconnexion peut rejouer le même événement. Les identifiants de carte et section sont des références opaques aux occurrences ; modifier ou réordonner la présentation peut les changer. Les indices commencent à zéro ; subIndex peut valoir -1 pour une diapositive par défaut.

Les changements sont regroupés pendant au maximum 1 seconde, avec un nouvel instantané normalement toutes les 15 secondes, même sans changement. Vérifiez occurredAt et l’indicateur MQTT de rétention avant d’agir. Un instantané conservé peut survivre à Presenter et ne prouve pas qu’il est connecté. Il s’agit du dernier état connu, pas d’un journal complet ni du déroulé à venir.

Essayer la vue en direct Node.js

Téléchargez l’exemple fonctionnel ou ouvrez l’aperçu simulé. Avec Node.js 22 ou plus récent, lancez une vue de la carte en direct et une chronologie des cartes reçues, sans broker ni licence :

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

Pour les événements réels, copiez .env.example vers .env et renseignez l’URL du broker, le nom d’utilisateur, le mot de passe et le préfixe client générés. Définissez PRESENTER_ID si plusieurs Presenters partagent l’organisation cloud, puis lancez npm start. Ouvrez http://127.0.0.1:4188. Sans identifiant, le premier Presenter est sélectionné. Les identifiants restent dans Node ; seuls les champs publics projetés arrivent au navigateur via Server-Sent Events. Gardez .env privé. Cet exemple est un serveur local de développement, pas un service hébergé partagé.

Dans Node-RED, reliez un nœud MQTT in au broker indiqué. Saisissez les identifiants générés et un identifiant client unique commençant par le préfixe attribué ; activez TLS avec vérification des certificats pour le cloud. Choisissez le topic des événements ci-dessus et QoS 1, puis reliez JSON → debug. Lisez msg.payload.state.cue.title, vérifiez msg.payload.occurredAt et dédupliquez msg.payload.eventId avant de déclencher une action. Consultez la référence officielle MQTT.js et le guide MQTT de Node-RED.

Recevoir du texte en direct

Pour le texte local, autorisez le service externe à publier sur church/lyrics/slide. Dans Connexions → Télécommande par téléphone → Même Wi-Fi, réglez Topic des paroles sur church/lyrics/slide. Ajoutez une carte de paroles en direct depuis la bibliothèque et projetez-la. Publiez du texte UTF-8 brut vers le broker local, sans enveloppe JSON.

Pour le texte cloud avec Complete, créez d’autres identifiants dans la même organisation avec uniquement un abonnement à church/lyrics/slide. Choisissez Serveur personnel dans Presenter, saisissez wss://mqtt.sundayassist.com/mqtt, ces identifiants et le même Topic des paroles, puis enregistrez et testez. La connexion locale des téléphones reste disponible. Serveur personnel utilise cette connexion manuelle à la place de Partout (Complete) automatique ; ces identifiants ne donnent pas accès à Remote par le cloud.

Remplacer, révoquer et gérer les interruptions

Remplacer le mot de passe invalide les anciens paramètres et affiche les nouveaux une seule fois ; mettez à jour tous les clients concernés. Révoquer désactive ces identifiants définitivement. Les identifiants locaux survivent aux redémarrages de Presenter ; les mots de passe n’ont pas de date d’expiration. L’accès payant et les droits restent nécessaires. Vous pouvez encore consulter et révoquer les identifiants après la fin de l’accès payant.

L’éligibilité cloud et les connexions actives sont vérifiées environ toutes les 30 secondes. La révocation n’est pas instantanée ; une interruption du contrôle des droits peut retarder la déconnexion de quelques minutes. Les clients cloud doivent se reconnecter au moins une fois par heure avec le mot de passe actuel. Activez la reconnexion et le réabonnement automatiques. QoS 1 peut livrer des doublons ; une panne réseau, une maintenance ou un basculement peut interrompre la livraison. Rendez les actions sans danger en cas de répétition et gardez du contenu local préparé. TLS protège la connexion réseau, pas le contenu de bout en bout.