MQTT Reader
The MQTT reader lets Zaparoo Core listen to an MQTT topic and treat each non-empty message as ZapScript.
Use it when another system already speaks MQTT, such as Home Assistant or a custom button, script, or device that publishes launch commands.
Platforms
Configure the reader
Add an MQTT reader to your config.toml:
[[readers.connect]]
driver = "mqtt"
path = "localhost:1883/zaparoo/tokens"
The path is the broker address followed by the topic Core should subscribe to: broker:port/topic. The example above connects to localhost:1883 and listens on zaparoo/tokens.
Restart Core after changing the config. MQTT readers are not auto-detected, so the [[readers.connect]] entry is what enables this reader.
For an encrypted broker, use mqtts:// in the reader path:
[[readers.connect]]
driver = "mqtt"
path = "mqtts://broker.example.com:8883/zaparoo/tokens"
Add broker credentials
If your broker needs a username and password, add them to auth.toml. Match the broker address, not the full topic path:
["mqtt://broker.example.com:1883"]
username = "your_username"
password = "your_password"
If you want the same credentials to work with either mqtt:// or mqtts://, use only the host and port:
["192.168.1.100:1883"]
username = "your_username"
password = "your_password"
For encrypted brokers, use an mqtts:// credential key. Core also treats ssl:// auth entries as mqtts://.
Send a message
Publish ZapScript to the topic configured in config.toml:
mosquitto_pub -h localhost -t zaparoo/tokens -m "@Genesis/Sonic the Hedgehog"
The @ prefix is shorthand for a title launch. You can send any valid ZapScript, including commands such as **launch.random:snes.
Choose whatever topic name fits your setup. For example, you could use zaparoo/tokens, zaparoo/devices/living_room/tokens, or homeassistant/zaparoo/commands. The important part is that the published topic matches the topic in your reader path.
The MQTT reader is read-only. It can receive ZapScript, but it cannot write anything back to NFC tags, cards, or other tokens.
Home Assistant integration
Set up Home Assistant's MQTT integration to use the same broker as Zaparoo Core, then publish ZapScript from an automation. This example runs when an input button changes:
automation:
- alias: "Launch Random SNES Game"
triggers:
- trigger: state
entity_id: input_button.random_game
actions:
- action: mqtt.publish
data:
topic: "zaparoo/tokens"
payload: "**launch.random:snes"
Change topic to match your reader path, and change payload to the ZapScript you want to run.
Troubleshooting
No connection
Enable debug logging in config.toml, restart Core, then check the Core logs:
debug_logging = true
For a working connection, you should see messages like:
mqtt reader: connected to localhost:1883
mqtt reader: subscribed to topic zaparoo/tokens
If Core does not connect, check the broker host, port, network access, and whether encrypted brokers use mqtts:// in the reader path.
Authentication fails
Check that your auth.toml entry matches the broker address and port. Do not include the MQTT topic in the auth key.
For example, if the reader path is mqtts://broker.example.com:8883/zaparoo/tokens, the auth key should be mqtts://broker.example.com:8883.
Messages do nothing
Check these first:
- The publisher is using the same topic as the reader path.
- The payload is not empty.
- The payload is valid ZapScript.
- Core logs show the MQTT message being received.
Test the same ZapScript with another reader or through the app. If it still does not work, the ZapScript probably needs fixing.