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. Enter the starting URL from the window (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.

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 JMRI Window

To display the contents of any open JMRI window, use a URL like: 
http://localhost:12080/panel/Power%20Control
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.

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".

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.