JMRI: XML IO Servlet

The JMRI XML Servlet provides web access to JMRI services.

The servlet lives in the jmri.web.servlet.xmlio package, and provides web access to the JMRI XML IO package. By default, the JMRI mini server will send any URL that starts with /xmlio to this servlet.

There are several sample pages that 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. To use it, configure JMRI to use "LocoNet Simulator" (if you don't have a LocoNet connection already; in JMRI 2.9.7 or later, the demo uses "internal" devices and this is not necessary) and create turnouts 1 through 4.
web/turnoutMonitor.html: More complex turnout table, with buttons to throw and close turnouts.

Please note that this servlet has only been used with the JMRI mini-server, and may not work with other servlet containers. We're committed to making it work, however, so just get in touch with the JMRI developers if you encounter any problems.

Request Format

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

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

<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</value>
  </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.

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.

Basic Use

Advanced Configuration

Advanced Uses

JMRI: XML IO Servlet

Request Format

Get the status of individual objects

Get all objects of a type

Set the status of an object

Control a Throttle

Related Documentation