Skip to main content

JMRI Web Access
Basic Use
JMRI supports working with your layout from a web browser.
Services
Details of the JMRI web services.
Applications
By the community of JMRI.org:

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI.org

JMRI: XML I/O Servlet - no longer supported

The XML I/O protocol was removed from JMRI in the 3.11 development cycle.
Affected applications should be ported to using the JSON protocol.
This page is only for reference of older versions.

The JMRI XML I/O Servlet provides bidirectional web access to JMRI services.

The servlet lives in the jmri.web.servlet.xmlio package, and provides web access to the JMRI XML I/O package. By default, the JMRI Web Server will send any URL that starts with /xmlio to this servlet. It will list all known elements of a specified type, accept changes to the value/state of elements, and respond with current value/state of elements. If sent a list of elements with current values, it will "monitor" for changes to any of those elements, returning the new values.

Element types fully supported: Element types list-only: Throttle is a unique case, with a slightly different syntax, supporting read and change, but not list or monitoring: There are several sample pages that (used to) show how this can be used:
web/request.html
Makes a single XML request for all available sensors, and shows their status in a table.
web/monitor.html
Uses delayed requests to monitor the status of all sensors, updating a table when any change.
web/throttle.html
Sends a speed command to a DCC locomotive on the layout when a button is pressed.
web/turnoutPanel.html
Example of a control panel on a web page.
web/turnoutMonitor.html
More complex turnout table, with buttons to throw and close turnouts.
web/JMRI_XMLIO_test.html
Useful for sending various commands to xmlio server and viewing the responses.
web/JMRIMobile.html
This tool uses the xmlio server for retrieving data from JMRI, sending changes and monitoring for changes to elements.

Please note that the XML I/O servlet was only supported with the JMRI Web Server, and may not work with other servlet containers.

Request Format

The XML schema is defined in the xmlio.xsd schema document.

There is also an attribute-based syntax available (see status examples below). The xmlio server responds with the same syntax used in the request.

Below are some example requests and responses.

Get the status of individual objects

Request: 
<xmlio>
  <item>
    <type>turnout</type>
    <name>IT12</name>
  </item>
  <item>
    <type>sensor</type>
    <name>West sensor</name>
  </item>
  <item>
    <type>power</type>
    <name>power</name>
  </item>
</xmlio>
Reply: 
<xmlio>
  <item>
    <type>turnout</type>
    <name>IT12</name>
    <value>2</value>
  </item>
  <item>
    <type>sensor</type>
    <name>West sensor</name>
    <value>4</value>
  </item>
  <item>
    <type>power</type>
    <name>power</name>
    <value>2</value>
  </item>
</xmlio>
The "value" element is inserted in the request, and then it's returned as the reply. You can just turn the reply around and use it as another request. If "value" elements are present for all items, the response will only be returned when one or more of the included item's state has changed to something different.

Get all objects of a type

Request: 
<xmlio>
  <list>
    <type>sensor</type>
  </list>
</xmlio>
Reply: 
<xmlio>
  <item>
    <type>sensor</type>
    <name>IS1</name>
    <value>2</value>
  </item>
  <item>
    <type>sensor</type>
    <name>IS2</name>
    <value>4</value>
  </item>
  <item>
    <type>sensor</type>
    <name>West sensor</name>
    <value>2</value>
  </item>
</xmlio>
The response can be turned around and used as the next request.

Set the status of an object

Request: 
<xmlio>
  <item>
    <type>turnout</type>
    <name>IT12</name>
    <set>2</set>
  </item>
</xmlio>
Reply: 
<xmlio>
  <item>
    <type>turnout</type>
    <name>IT12</name>
    <value>2</value>
  </item>
</xmlio>
The "set" element in the request results in the state being set to the given value, and then it's returned in the reply as a value element with the proper value at that point.

All writes are done before the values are collected for any reads, but there is no guarantee that the consequences of the writes have propagated completely.

Set the status of an object (attribute-based syntax)

Request: 
<turnout name="IT12" set="2" />
Reply: 
<turnout name="IT12" value="2" />

Control a Throttle

A <throttle> element can be used to control a DCC Throttle via the default ThrottleManager. The first use allocates the throttle, and all later ones set any attributes present: 
<xmlio>
    <throttle>
        <address>1234</address>
        <speed>0.75</speed>
        <forward>true</forward>
        <F3>false</F3>
    </throttle>
</xmlio>
A throttle element is returned unchanged.

Related Documentation