Why MQTT?
Presenter already uses MQTT for QR Remote, live state, and local AI topics. The same broker is available to your own clients on the church LAN. The embedded broker is MQTT v5 compliant and also accepts MQTT v3.1.1 / v3.0 clients — so you can connect with either. You publish and subscribe like any MQTT app; Presenter reacts to control messages and publishes deck and state updates.
Connect to the embedded broker
When Presenter is running, the broker listens on the machine’s LAN address. If the default port is busy, Presenter tries the next candidate in the range.
| Transport | Endpoints | Notes |
|---|---|---|
| MQTT over TCP | tcp://<presenter-lan-ip>:1883–1887 | Best for desktop scripts, Node, Python, and hardware bridges. |
| MQTT over WebSocket | ws://<presenter-lan-ip>:9883–9887/mqtt | Path is always /mqtt. Use from browsers or WebSocket-capable clients. |
tcp://192.168.1.40:1883
ws://192.168.1.40:9883/mqttGetting started
Use an MQTT v5 or v3.x client (TCP or WebSocket). Point it at the Presenter host while a gathering is open (or after Remote has started so the broker is up). Presenter’s own Remote traffic uses MQTT 3.1.1; v5-only features are fine for your clients and are downgraded when mixed with v3 peers.
- Stay on the same Wi-Fi / LAN as the Presenter computer for local access.
- Discover the host IP from Presenter’s network / Remote QR UI, or from your router’s client list.
- If 1883 or 9883 fails, try the next port in the fallback range — Presenter logs the bound ports at startup.
- QoS 0 is typical for live control; keep payloads small and JSON-encoded UTF-8.
Remote topic tree
Most integration work uses the Remote topic prefix. Replace {prefix} with proweave/remote on a typical LAN setup, or proweave/<machine-scope>/remote when Presenter is scoped to a machine MAC.
Prefix: proweave/remote (LAN default) or proweave/<scope>/remote. Session IDs come from pairing — pair first, then publish under that session.
| Topic pattern | Direction | Purpose |
|---|---|---|
| {prefix}/pair | Client → Presenter | OTP / pairing request to create a session |
| {prefix}/<sessionId>/paired | Presenter → Client | Pair accepted or rejected |
| {prefix}/<sessionId>/control | Client → Presenter | Commands (advance, goto, blank, …) |
| {prefix}/<sessionId>/heartbeat | Client → Presenter | Keep the session alive; include role controller or viewer |
| {prefix}/<sessionId>/deck | Presenter → Client | Full deck JSON for controllers / builders |
| {prefix}/<sessionId>/state | Presenter → Client | Live beamer / controller state |
| {prefix}/<sessionId>/viewer/state | Presenter → Client | Viewer slide raster envelope (and chunked variants) |
| {prefix}/ai/* | Engine ↔ Presenter | Local AI topics |
Control payload shape
Publish JSON to {prefix}/<sessionId>/control after a successful pair. Field names match Presenter’s remoteControlPayload (cmd plus optional navigation fields).
{
"cmd": "advance"
}
{
"cmd": "goto",
"deckIdx": 2,
"page": 0
}| cmd | Meaning |
|---|---|
| present | Start presenting |
| stop | Stop presenting |
| advance | Next cue / slide step |
| back | Previous cue / slide step |
| goto | Jump using deckIdx / page (and related fields) |
| blank | Blank or restore the screen |
| nextItem | Next deck item |
| prevItem | Previous deck item |
| setStanza | Jump within song structure |
| setPage | Set PDF / multi-page cue page |
| ping | Liveness check |
Safety and limits
- Treat the broker as a LAN service — do not port-forward it to the public internet.
- Anyone who can publish to a paired session’s /control topic can drive the live deck; protect the network and pairing flow.
- Topic paths under proweave/<scope>/remote/ may also be bridged to ProWeave Cloud when Team cloud remote is enabled — test on LAN first.
- This page documents the integration surface as shipped; fields may grow. Prefer observing /deck and /state from a real Remote session while you prototype.
- Breaking changes to topic names are rare; if you ship a public integration, tell us at [email protected] so we can warn you before a rename.
Build with us
Want to contribute upstream, or need a stable contract for a church AV product? We are glad to talk.