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 JSON Servlet

The JMRI JSON Servlet provides a RESTful API and a WebSocket API for accessing and editing user defined objects in JMRI. This document describes how to enable the JMRI JSON servlet and provides some examples of use.

Note the JMRI JSON protocol is documented in JMRI API Documentation.

JMRI JSON Servlet

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

Setting up the JSON Servlet

The JMRI JSON Servlet is a feature that is part of the Web Server. To use this service:

  1. Ensure the web server's port is unique:
    • Open the Preferences dialog
    • Click Web Server on the left side
    • Ensure the port number is unique (for example 12080). Other ports are used by WiThrottle, JSON Server, etc.
    • Click Save
  2. Click Actions and Start Web Server to ensure the web server is running (Tools ⇒ Servers ⇒ Start JRMI Web Server in PanelPro).
  3. If you want the Web Server to run each time you start JMRI:
    • Open the JMRI Preferences dialog
    • Select Start Up in the left column
    • Click Add ▾
    • Select Perform action...
    • Select Start Web Server
    • Click OK

Paths

The servlet responds to the following paths:

/json
Depending on protocol:
HTTP
Open a JSON WebSocket console that allows experimentation with JSON sockets.
WS
Open a JSON WebSocekt.
/json/type
Using the HTTP protocol:
GET
request a list of objects of type
PUT
add an object of type
A JSON array of valid types for your JMRI installation is available by using the type "type" (with JMRI Web Server running). See the protocol documentation for more details.
/json/type/name
Using the HTTP protocol:
GET
request the object of type with name name
POST
modify the object of type with name name
DELETE
remove the object of type with name name

JMRI JSON Server

The JMRI JSON server is functionally identical to the JSON WebSocket interface, but running over a standard network socket.

jquery.jmri.js

jquery.jmri.js is a jQuery library that ships with JMRI and makes the JSON protocol support "just work" on most current browsers.

Examples of use of the jquery.jmri.js JavaScript library that ships with JMRI include:

Operations Conductor
source /js/operations.js
Panel
source /js/panel.js
JSON Console
source /js/json-console.js

Note: The source code for the above is found in the web/ts directory, which contains the JavaScript and Typescript source code. This is compiled to the web/js directory for actual execution.

Power Demonstration (with JMRI Web Server running).
source /web/power.html