Skip to main content

JMRI web access

Basic Use

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

Advanced Configuration

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

Advanced Uses

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

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 animage 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 "Debug" 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). You should see a welcome screen.

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 the "Advanced Preferences" to set JMRI to start the server each time you start the program.

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

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; JMRI won't modify it once you've changed it. 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, you you might want to delete the old one and 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 how the proper URLs to request the services you'd like. Several examples are available in the "web" directory of the distribution.

To Display a Clickable JMRI Window

To display any open JMRI window as a clickable image that periodically refreshes, use a URL like: 
http://localhost:12080/panel/Power%20Control.html
where the last part of the URL is the name of the desired window. Note that you have to replace spaces by "%20" to make the name a valid URL, and that the name ends in ".html".

By default, that image refreshes every 5 seconds, and also refreshes one second after you click on it. You can change the refresh interval by adding a modifier to the end of the URL: 

http://localhost:12080/panel/Power%20Control.html?retry=12.3

To Display a JMRI Window as an Image

To display the contents of any open JMRI window as an image, use a URL like: 
http://localhost:12080/panel/Power%20Control.png
where the "file name" part of the URL is the name of the desired window. Note that you have to replace spaces by "%20" to make the name a valid URL. You can also embed this URL in a IMG tag.

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

XML and Ajax accress

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.