JMRI web access

JMRI has built-in support for viewing your layout from a web browser.

JMRI's built-in support can be reconfigured to some extent.

Miniserver

Advanced Uses

The JMRI web components can be used in your own web server.

Frame servlet

JMRI: Web Access

JMRI can provide web access to your model railroad.

The basic method was developed by Konrad Froetzheim and colleagues in the early 1990's for their "Internet Model Railroad". A standard web server communicates with the user's normal web browser, accepting HTTP requests in the usual way. These requests are handed to a small "JMRI connector", which interprets them and returns the information from JMRI back to the browser.

For example, the user can have their browser request the current contents of a JMRI panel, which is returned back to the browser as an image to be displayed. Or the user can click on the image of a JMRI panel, which causes the browser to request a click in the same position on a JMRI panel. JMRI acts on that click, and also sends back an image of the updated panel.

Starting Web Access

JMRI web access is included in the usual JMRI downloads. To use it, you just have to start it.

Before attempting to use web access, please make sure that the basic configuration of your JMRI application is working. Check that you can properly communicate with and operate your layout.

To start web access from the menus, select "Start Mini Web Server" under the "Tools" menu. A small window will open to confirm that it started, and to show you the URL that it's using.

Next, check the connection.

If you're using a Bonjour/Zeroconf-enabled web browser like Safari or Firefox, you should see a "JMRI on (your computer name)" web site in the "Bonjour" tab. You can just click on that to get to the welcome page of the JMRI web server.

Otherwise, enter the starting URL from the "Web server started ..." message, which will be something like "http://10.0.1.7:12080/index.html" (or if you're browsing on the same computer right now, click here, or press the "Open in Browser" button). The default port is 12080, but this can be changed in MiniServer Preferences. You should see a welcome screen, which serves as the home page for the mini web server. This page (by default) contains a number of useful examples and links.

Next, let's make sure you can access JMRI functions. From the JMRI Tools menu select "Power Control", which should open a new window. Then click on this link or enter the URL

http://localhost:12080/panel/Power%20Control.html

This should display the Power Control window on your web browser. (Note: "localhost" is an alias for your computer; if you want to access the computer running JMRI from some other computer, replace "localhost" with the IP address displayed on the main screen, e.g.

http://127.0.0.1:12080/panel/Power%20Control.html

or something similar) If everything is working, you should see the Power Control window on your browser screen. Click the "On" button to turn layout power on.

Configuring

You can use "Preferences" to tell JMRI to start the server each time you start the program.

To do this, open the Preferences window, select the "Start Up" tab, and click "Add Action". In the new selection box that appears, select "Start Web Miniserver". Don't forget to save your changes!

The MiniServer defaults to port 12080, but this can be changed using the MiniServer Preferences dialog.

The "index.html" page that you used in the previous section is automatically created by the program in the JMRI preferences directory. You can edit it to display whatever you want; by default, JMRI won't modify if it exists. You can include links to web pages outside JMRI, and links to various JMRI-served pages, see below. On the other hand, we periodically improve the page, so you might want to turn on "Rebuild index.html?" in Preferences to let JMRI replace it with the newest version.

Access URLs

You can create your own web pages using any tool you'd like. To access JMRI from those pages, you just need to know the proper URLs to request the services you'd like. Several examples are linked from the index.html (mini server home page),

Open Window (Frame) Access

To display any already open JMRI window as a clickable image that periodically refreshes, use a URL like: http://127.0.0.1:12080/frame/Monitor%20Slots.html http://127.0.0.1:12080/frame/Analog%20Clock.html http://127.0.0.1:12080/frame/Turnout%20Table.html

Note the frame title in the URL, followed by ".html". Replace any spaces in the title with "%20".

For current, dynamically-generated list of available windows, use this URL: http://127.0.0.1:12080/frame

Note: Adjust defaults such as refresh timing, disallowed frames and ajax usage in MiniServer Preferences.

You can override the defaults for individual pages by using the following parms in your URL:

plain (hide the footer links)
protect (protect the frame from user clicks, i.e. read-only image, but with refresh)
ajax (use ajax for updates)

Example, showing no links, protected, using ajax to refresh every 12 seconds: http://127.0.0.1:12080/frame/Power%20Control.html?ajax=true&plain=true&protect=true&retry=12

inControl throttle web application

To use the throttle web application, you can go to:

http://localhost:12080/web/Scan2BeInControl.html

It will generate and display a scannable and clickable locomotive list from your JMRI roster.
Each smartphone scan will open an inControl web throttle in it.
Each click on a link will open a new inControl web throttle browser window or tab. You may also call the inControl directly:

http://localhost:12080/web/inControl.html

See mini web server starting page for more info or jump to the inControl help page:

/help/en/package/jmri/jmrit/inControl/inControl.shtml

To Display a Local File

A local HTML file (web page), graphic or text file can be displayed using the appropriate URL.

Files in your JMRI preferences directory can be accessed via a URL that starts with "prefs":

http://localhost:12080/prefs/index.html

(The index.html file is in your preferences directory)

Files in certain directories in the JMRI program directory can be accessed via a URL that starts with "dist":

http://localhost:12080/dist/help/en/webindex.shtml

will reference the index to the help system, while

http://localhost:12080/dist/resources/logo.gif

will load a JMRI logo graphic from the resources directory. "dist/web" and "dist/xml" also work as prefixes.

Displaying Formatted Panel Files

The "panel files" that JMRI uses to store configuration and display information can be displayed in a convenient format by a web browser. The JMRI web server works with your browser to do this formatting. You can then view, print, save, etc the formatted file. For example, to display "MyFile.xml" from the JMRI preferences directory, use

http://localhost:12080/prefs/MyFile.xml

To Display a formatted JMRI roster list

To get a nicely formatted view of your JMRI roster simply go to:

http://localhost:12080/prefs/roster.xml

Note that this is your roster.xml file displayed only using a xslt transformation.

XML and Ajax access

JMRI provides XML and Ajax access via a XML IO custom servlet.

There are three 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.

By default, this is configured to handle URLs that start with "/xmlio". Information on use and customization can be found on a separate page.

Basic Use

Advanced Configuration

Advanced Uses