MQTT-integraties

Bouw een externe dienst die Presenter volgt of berichten uitwisselt op je eigen topics. Blijvende inloggegevens hebben een eenmalig getoond wachtwoord en nauw gekozen rechten. Ze geven nooit presentatieopdrachten.

Lokale inloggegevens vereisen een betaalde Presenter Own-, Flex- of ondersteunde oudere licentie, ook via Complete. Ze blijven op die computer en hebben geen cloudaccount nodig. SundayAssist Cloud vereist een actief Complete-abonnement, aanmelding, organisatielidmaatschap en de rol eigenaar of beheerder. Een onbetaalde proefperiode geeft geen toegang.

Inloggegevens maken

  1. Open Verbindingen → Telefoonbediening → Integratie-inloggegevens en kies Lokaal of SundayAssist Cloud.
  2. Kies Inloggegevens maken, geef de dienst een herkenbare naam en vul de Publicatietopics en Abonnementstopics in, één per regel. Laat een ongebruikte richting leeg. Zet voor het onderstaande voorbeeld Presenter-gebeurtenissen lezen aan en laat eigen topics leeg.
  3. Bewaar het wachtwoord direct in de geheime opslag van de dienst. Verbindingsgegevens kopiëren bevat het wachtwoord. Je ziet het maar één keer en kunt het later niet opvragen.
  4. Gebruik aparte inloggegevens voor elke dienst. Een set staat maximaal 20 topicregels toe. Per lokale installatie, of per account en organisatie in de cloud, zijn maximaal 20 sets actief.

De juiste broker verbinden

Gebruik MQTT 3.1.1 of 5. Neem het lokale adres en de gebonden poorten over die Presenter toont; normaal TCP-poort 1883 en WebSocket-poort 9883, met alternatieven als die bezet zijn. Lokaal verkeer is onversleuteld: gebruik een vertrouwd netwerk en stel deze poorten nooit open voor internet. Cloud-TLS gebruikt poort 8883; beveiligde WebSocket gebruikt poort 443 en pad /mqtt. Laat certificaatcontrole aanstaan. Elke gelijktijdige verbinding heeft een unieke client-ID met het toegewezen voorvoegsel nodig.

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

Eigen topics kiezen

Publicatierechten gelden voor exacte topics. Abonnementen staan een exact topic of een afsluitende /# onder een vaste naamruimte toe, zoals church/lyrics/#. De wildcard +, een losse #, lege niveaus, witruimte en $ worden geweigerd. De eerste naamruimte mag niet sundayassist zijn, ongeacht hoofdletters. Het expliciete alleen-lezen gebeurtenisrecht is de gereserveerde uitzondering.

Lokale rechten gelden voor die Presenter-installatie. Cloudtopics blijven binnen de organisatie: gebruik op beide clients hetzelfde topic zonder organisatievoorvoegsel. Personen in dezelfde organisatie met overlappende topicrechten kunnen berichten uitwisselen. Integratie-inloggegevens kunnen geen Remote koppelen, diens deck/statusprotocol benaderen, AI, relay of Presenter-link gebruiken of op SundayAssist-topics publiceren. Eigen publicaties staan QoS 0 of 1 toe, zonder retain-vlag en maximaal 1 MiB per bericht.

Presenter-gebeurtenissen lezen

Zet Presenter-gebeurtenissen lezen aan en abonneer op sundayassist/integrations/v1/events/#, of beperk het tot sundayassist/integrations/v1/events/<presenterId>/state. Presenter publiceert een bewaarde QoS 1 JSON-momentopname met het volgende openbare formaat. Titels zijn inbegrepen; liedteksten, notities, bestandspaden, schermafbeeldingen en accountgegevens niet. De cue of sectie kan null zijn.

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

Gebruik eventId om dubbele berichten te verwijderen en sequence voor de volgorde binnen dezelfde runId. Een herstart van Presenter begint een nieuwe run. Opnieuw verbinden kan dezelfde gebeurtenis bezorgen. Cue- en sectie-ID’s zijn ondoorzichtige verwijzingen naar een voorkomen; deckwijzigingen of een andere volgorde kunnen ze veranderen. Indexen beginnen bij nul; subIndex kan -1 zijn voor een standaardslide.

Wijzigingen worden maximaal 1 seconde samengevoegd, met normaal elke 15 seconden een nieuwe momentopname, ook als er niets verandert. Controleer occurredAt en de MQTT-retainindicator voordat je handelt. Een bewaarde momentopname kan langer bestaan dan een draaiende Presenter en bewijst niet dat deze online is. Dit is de laatst bekende status, geen volledig logboek of toekomstig draaiboek.

Probeer het live overzicht in Node.js

Download het werkende voorbeeld of open de gesimuleerde preview. Met Node.js 22 of hoger start je zo een live cue-overzicht en een tijdlijn van ontvangen cues, zonder broker of licentie:

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

Kopieer voor echte gebeurtenissen .env.example naar .env en vul de gemaakte broker-URL, gebruikersnaam, wachtwoord en het client-ID-voorvoegsel in. Stel PRESENTER_ID in bij meerdere Presenters in dezelfde cloudorganisatie en voer npm start uit. Open http://127.0.0.1:4188. Zonder ID wordt de eerste Presenter gekozen. Inloggegevens blijven in Node; de browser ontvangt alleen de geselecteerde gebeurtenisvelden via Server-Sent Events. Houd .env privé. Het voorbeeld is een lokale ontwikkelserver, geen gedeelde gehoste dienst.

Verbind in Node-RED een MQTT in-node met het overgenomen brokeradres. Vul de gemaakte gebruikersnaam, het wachtwoord en een unieke client-ID met het toegewezen voorvoegsel in; zet voor de cloud TLS met certificaatcontrole aan. Stel het gebeurtenistopic hierboven en QoS 1 in en verbind JSON → debug. Lees msg.payload.state.cue.title, controleer msg.payload.occurredAt en verwijder dubbele msg.payload.eventId-waarden voordat je een actie start. Zie de officiële MQTT.js-referentie en het Node-RED MQTT-kookboek.

Live tekst ontvangen

Geef de externe dienst lokaal publicatierechten op church/lyrics/slide. Stel in Verbindingen → Telefoonbediening → Dezelfde wifi het Liedteksttopic in op church/lyrics/slide. Voeg vanuit de bibliotheek een cue voor live gestreamde liedteksten toe aan je deck en presenteer deze. Publiceer vanuit de dienst gewone UTF-8-tekst naar de lokale broker, zonder JSON-verpakking.

Maak voor live tekst via de Complete-cloud aparte inloggegevens in dezelfde organisatie met alleen een abonnement op church/lyrics/slide. Kies Eigen server in Presenter, vul wss://mqtt.sundayassist.com/mqtt, die inloggegevens en hetzelfde Liedteksttopic in, sla op en test. De lokale telefoonverbinding blijft beschikbaar. Eigen server gebruikt deze handmatige verbinding in plaats van automatisch Overal (Complete); integratie-inloggegevens geven geen cloudtoegang voor Remote.

Vervangen, intrekken en onderbrekingen afhandelen

Wachtwoord vervangen maakt de oude verbindingsgegevens ongeldig en toont de nieuwe één keer; werk elke client met die set bij. Intrekken schakelt die set definitief uit. Lokale inloggegevens blijven na Presenter-herstarts bestaan; wachtwoorden verlopen niet op een vaste datum. Betaalde toegang en rechten blijven verplicht. Je kunt inloggegevens nog bekijken en intrekken nadat betaalde toegang eindigt.

Cloudtoegang en actieve verbindingen worden ongeveer elke 30 seconden gecontroleerd. Intrekken werkt niet onmiddellijk; een storing in de rechtencontrole kan verbreken enkele minuten vertragen. Cloudclients moeten minstens elk uur opnieuw verbinden met hetzelfde huidige wachtwoord. Zet automatisch opnieuw verbinden en abonneren aan. QoS 1 kan dubbele berichten geven; netwerkuitval, onderhoud en omschakeling bij storingen kunnen bezorging onderbreken. Maak gevolgen veilig herhaalbaar en houd voorbereide lokale inhoud beschikbaar. TLS beschermt de netwerkverbinding, niet de berichtinhoud van eindpunt tot eindpunt.