JMRI can provide web access to your model railroad.
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 Tools ⇒ Servers ⇒ Start JMRI Web Server.
Test the connection:
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 are in two categories:
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.
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)
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)
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 services at http://localhost:12080/operations include Trains, Conductor and Manifest functions. (More details)
Tables services at http://localhost:12080/table include Turnouts, Sensors, Routes etc. See Tables Servlet for more information.
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.
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.
JMRI provides a JSON Protocol to access and manipulate for a number of JMRI-defined entities. See the JMRI JSON Protocol for more information.
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. JMRI, as of
version 5.5.4, allows the targeting of CSS to a specific panel by name. See user.css, located
in the current JMRI distribution, for details.
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.
Some requests are automatically redirected by one of the JMRI web services to ensure that old bookmarks or software can still be used:
/ since the static HTML root was replaced with a dynamic HTML
root./ 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./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.
/operations since this page was replaced with the operations servlet.
/operations since this page was replaced with the operations servlet.
/operations since this page was replaced with the operations servlet.
/panel.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.