Skip to main content

JMRI Web Access

Basic Use

JMRI supports working with your layout from a web browser.

Services

Details of the JMRI web services.

Applications

By the community of JMRI.org:

JMRI Help:
Contents/ Index
Glossary/ FAQ

Donate to JMRI Donate to JMRI.org

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:

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 JMRI 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.
Start automatically with application
This will add the action "Start JMRI Web Server" to your Start Up Preferences.
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 allowed in the browser.

Services

JMRI Web Access provides a number of web services.

The example links below assume you are using a web browser on the same computer you are running JMRI on and that JMRI is using the default port 12080.
To access the web server from another device on your network, determine the IP address of the JMRI computer and use it instead of "localhost". Example: "http://192.168.1.7: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. (More details)

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. The Roster page also includes an "Upload Roster Files" button. (More details)

Throttles

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

Operations

Operations services at http://localhost:12080/operations include Trains, Conductor and Manifest functions. (More details)

Tables

Tables services at http://localhost:12080/table include Turnouts, Sensors, Routes etc. See Tables Servlet for more information.

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 in the web directory of the JMRI distribution directory will override the default file used for that purpose. This provides the custom content.

Two files web/css/user.css and web/js/user.js are provided for convenience to make simple appearance and javascript additions and overrides. These files are automatically included in all JMRI web pages, and include instructions for usage.

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.

A technical description about the Web Server Package jmri.web.server can be found in the Web Server Javadoc.

An overview of how Web Server works between JMRI and the web browser, using web.servlet.panel as an example, can be found on PanelServlet Help page.

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.