Hardware Support: MQTTJMRI can connect to IOT devices via the MQTT protocol.
The default system letter is "M", so we'll use that in examples.
LimitationsOlder code (i.e. JMRI 4.12 and later) only supports Turnouts. We hope to add Sensor, Light and Reporter support soon.
ConnectingYou 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.
TopicsJMRI 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.
TurnoutsBy default, the message content for turnouts is "CLOSED" and "THROWN".
Changing the CodingSince 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
or on an individual
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.
DebuggingIf 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.