Skip to content

MQTT

Jump to bottom
Jeff Uchitjil edited this page Oct 27, 2026 · 1 revision

MQTT

Radio Automation uses MQTT in two independent ways:

  1. Triggering events - an MQTT message can run the same events the cron scheduler runs.
  2. Publishing the current song - the title/artist/album is published each time the track changes.

Both use the broker configured in Options > Preferences > MQTT Info: MQTT Broker (host name or IP) and MQTT Broker Port (default 1883). Each feature keeps its own connection to the broker, and they connect at startup and whenever the event schedule is reloaded.

Triggering events from MQTT

In the event editor set Trigger Type to Mqtt, then fill in:

Field Meaning
Topic The topic to subscribe to, e.g. lights/show/control
Message The payload text that should trigger this event, e.g. start

When a message arrives, every enabled event whose topic and message both match runs. Everything else about the event is the same as for cron events - the same actions, and the same Immediate vs Delayed rules.

Example - start and stop the show from a controller:

Name Topic Message Demand Action
Remote start lights/show/control start Immediate Play
Remote stop lights/show/control stop Immediate Stop
Say the time lights/show/announce time Delayed Time Announcement

Test it from any MQTT client:

mosquitto_pub -h <broker> -t lights/show/control -m start

Matching rules and limitations

  • Topic and message are compared as exact, case-sensitive text. Start does not match start, and trailing spaces/newlines count.
  • Wildcard topics (+, #) don't work. The subscription is made, but incoming messages are looked up by their exact topic, so nothing matches.
  • Several events can share one topic and be told apart by their message.
  • Events subscribe with QoS 1.
  • Retained messages fire the event when the app subscribes. If a retained start message sits on the topic, it will run again each time the schedule is loaded. Publish trigger messages without the retain flag.
  • The connection is plain TCP on the configured port. Username/password and TLS are not supported, so use a broker that allows anonymous access on your network.
  • Event subscriptions are refreshed when the event schedule is applied, so after editing MQTT events click Ok in the Events window.
  • If the schedule contains enabled MQTT events but no broker is configured or the connection fails, a message warns you at startup and those events won't fire. Fix the broker in Preferences.

Publishing the current song

In Preferences > Song Publishing tick Enable MQTT Publishing and enter the MQTT Song Topic, e.g. lights/show/nowplaying.

Each time the current track changes a JSON message is published:

{"title":"Jingle Bells","artist":"Frank Sinatra","album":"Christmas Songs"}
  • The message is retained (QoS 1), so subscribers get the latest song as soon as they connect.
  • When nothing is playing (stopped), the three fields are empty strings.
  • Publishing is skipped if the topic is blank or the broker isn't connected.

Writing the song to a file

Enable File System Publishing (on by default) writes the current track as a single line of text to the Current Song Path file each time the track changes, or Nothing Playing when stopped. This is handy for lighting software or overlays that read a text file. The folder must already exist.

Radio Automation

Clone this wiki locally