JMRI Web Access

JMRI can provide web access to your model railroad.

Starting Web Access

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.

Start web access by selecting "Start JMRI Web Server" under the "Tools" menu.

Test the connection:

If you're using a Bonjour/Zeroconf-enabled web browser like Safari you should see a "My JMRI Railroad" web site in the "Bonjour" tab.
Otherwise, enter the starting URL, which will be something like "http://192.168.1.7:12080" (or if you're browsing on the same computer right now, click here. The default port is 12080, but this can be changed in Web Server Preferences. You should see a welcome screen, which serves as the home page for the JMRI web server. This page (by default) contains a number of useful examples and links.

Configure Web Access

Automatically start

JMRI can automatically start the web server when launched.

Open the Preferences Window to configure JMRI to start the server each time you start the program.

Select the "Start Up" tab, click "Add ▾", and select "Perform action...". In the new selection box that appears, select "Start Web Server". Don't forget to save your changes!

Web Server Preferences

Web Server Preferences are in two categories:

Web Server

Port#: The port the web server listens for HTTP requests. This defaults to 12080. You may need to change this value if another program expects to be listening on this port as well. Some Anti-Virus services use this port.
Disable power control in menus: The menus on many of the JMRI web pages include a layout power button. You can disable this button to ensure that users of the web site can see the power status, but cannot turn off or turn on layout power.

Frame Server

Disable Frames: Disable the frame server. Disabling the frame server disables most other preferences. The frame server is disabled by default.
Use Panels Instead: If the frame server is disabled, requests for frames can be redirected to panels. Redirection to panels is enabled by default.
Click Delay: Wait the specified number of seconds after a click on the window (frame) image before refreshing the image.
Refresh Delay: The number of seconds before the window image is automatically refreshed.
Use Ajax?: Use features that improve performance on modern browsers. Turn off to support obsolete browsers.
Disallowed Frames: A list of windows that will not be displayed in the browser.

Services

JMRI Web Access provides a number of web services.

All links below assume you are currently using a web browser on the same computer you are running JMRI on and that JMRI is using the default port 12080.

JMRI Web Access home page at http://localhost:12080 provides direct access to all of the web services. Most JMRI web access pages provide direct access to the panels, roster, and operations services.

Panels

Loaded JMRI panels can be used in a modern web browser on computers, smart phones, and tablets. A list of the loaded panels is at http://localhost:12080/panel.

Roster

The web roster at http://localhost:12080/roster provides a list of roster entries. Clicking on an entry will open the web throttle for that entry.

Throttles

JMRI supports using a modern browser on a smart phone, tablet, or other computer as a throttle device at http://localhost:12080/web (see Web Throttle Help).

Operations

Operations services at http://localhost:12080/operations are at the proof of concept stage. Currently the conductor view is complete, but other operations views are missing or are works in progress.

Windows

JMRI can display most already open windows as a somewhat usable image to allow partial remote control of JMRI.

The list of viewable windows is at http://localhost:12080/frame. Please note that not all open windows are viewable. See Window Services for more information.

File System

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

Files in your JMRI preferences directory can be accessed via a URL path that starts with "/prefs": http://localhost:12080/prefs/

Files in certain directories in the JMRI program directory can be accessed via a URL path 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.

Note that if a directory contains a file named index.html it will display the contents of the index.html file instead of listing the directory contents.

JSON Protocol

JMRI provides a JSON Protocol to access and manipulate for a number of JMRI-defined entities. See the JMRI JSON Protocol for more information.

Customizing Web Access

If you create a directory web in your User Files directory, configuration profile root directory, or settings directory, any file in that directory that has the same name and directory hierarchy as a file the web directory in the JMRI distribution directory will override the default file used for that purpose. This provides the ability to replace images, scripts, and other content with personal content.

The standard web services use templates in the web/servlet directory. Note that these templates are tightly linked with JMRI. While modifying these templates is the recommended way to customize the web access, care must be taken to ensure modifications do not cause the templates to break entirely. If web access does not work as expected after modifying a template, check the JMRI logs for the cause.

Request Redirection

Some requests are automatically redirected by one of the JMRI web services to ensure that old bookmarks or software can still be used:

/index.html: Redirects to / since the static HTML root was replaced with a dynamic HTML root.
/prefs/index.html: Redirects to / since the static HTML root was replaced with a dynamic HTML root. Some WiThrottle clients refuse to allow access to the web server if a request to /prefs/index.html returns an error.
/prefs/roster.xml: Redirects to /roster?format=xml since users can opt to have the roster outside the normal preferences file location, and the roster servlet can load the roster from any location.
/web/operationsConductor.html: Redirects to /operations since this page was replaced with the operations servlet.
/web/operationsManifest.html: Redirects to /operations since this page was replaced with the operations servlet.
/web/operationsTrains.html: Redirects to /operations since this page was replaced with the operations servlet.
/web/showPanel.html: Redirects to /panel.

Security

By default, JMRI only allows limited access to your computer. Only files that are located within the JMRI distribution directory or the JMRI preferences directory will be provided in response to requests. This is not air-tight security, however, and you should be careful to not put important content in those directories or link them to other parts of your computer.