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