Hardware Support: MQTT

JMRI can connect to IOT devices via the MQTT protocol.

Naming

The default system letter is "M", so we'll use that in examples.

Limitations

Older code (i.e. JMRI 4.12 and later) only supports Turnouts. We hope to add Sensor, Light and Reporter support soon.

Connecting

You tell JMRI about how to connect to your MQTT hardware via the Connections pane in the Preferences window. Select "MQTT" as the manufacturer name.

Currently, JMRI can handle only one MQTT connection at a time. You can combine that MQTT connection with other connection types, but two MQTT connections won't work properly. This may be improved at some later point if people find a reason to need two MQTT connections.

Topics

JMRI MQTT Turnouts are specified with JMRI system names like "MTabcd". The "M" is the system connection letter, "T" specifies Turnout, and all after that is a suffix that is used to generate the specific topic which JMRI publishes and subscribes to when communicating with the layout.

By default, the MQTT topic for a Turnout is constructed by prepending "/trains/track/turnout/" to the suffix. For example, a JMRI Turnout with system name MTabcd will publish and subscribe to the topic /trains/track/turnout/abcd. There are two parts to that: A base topic common to everything JMRI does on that connection, and a type-specific topic specific to each type.

By default the base topic is "/trains/"; the turnout-specific part is "track/turnout/", leading to a complete prefix of "/trains/track/turnout/". When e.g. Sensors become available, they might have e.g. a type-specific part of "track/sensor/".

You can change the base topic by going to the JMRI Connection preferences, selecting your MQTT connection's preference pane, checking the "Additional Connection Settings" box, and then entering the desired value in the "MQTT channel" selection box. Depending on which kind of computer you have, you might have to click once or twice in that box before you can enter your new prefix text. Then save your changes and restart the program.

You can change the type-specific part of the prepended string using a script at startup time. See the jython/SetMqttPrefix.py sample script for an example. Note that any changes should be made at startup time before creating any Turnout objects, i.e. the script must be run as the first startup action before any panel files are loaded. Changing the prefix only affects Turnouts that are created after the change.

Message Content

Turnouts

By default, the message content for turnouts is "CLOSED" and "THROWN".

Changing the Coding

Since JMRI 4.15.5 You can use scripting to install a new jmri.jmrix.mqtt.MqttContentParser object to code and decode the content of messages. See the jython/SetMqttParser.py sample script for how to do that. For a Java example, see the inner class implementation in MqttTurnout.

Note that you can call setParser(...) on the jmri.jmrix.mqtt.MqttTurnoutManager or on an individual jmri.jmrix.mqtt.MqttTurnout object. If you call it on an individual MqttTurnout, that's the only one that's affected. If you call it on the MqttTurnoutManager all later created MqttTurnout objects will use the new parser; earlier-created ones will not be changed. This means you should call a script to change this before loading any panel files if you want all MqttTurnouts to be modified.

Debugging

If you don't have an MQTT system, and want to play with this connection type, you can enter "test.mosquitto.org" for the host name to use a publicly-available (non-JMRI) test server. For more information on this server, see the test.mosquitto.org web page.

If you install the mosquitto tools on your machine, you can use a command like

    mosquitto_sub -h test.mosquitto.org -v -t '/trains/#'
to subscribe and print JMRI turnout info as it's published. To publish a change for JMRI to pick up:
    mosquitto_pub -h test.mosquitto.org -t /trains/track/turnout/123 -r -m "CLOSED"
    mosquitto_pub -h test.mosquitto.org -t /trains/track/turnout/123 -r -m "THROWN"
These commands can be run on the same machine as JMRI, or on a separate machine.

There are also MQTT tools available for iOS devices and Android devices that can be useful for monitoring, testing and operating your layout.