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:
- 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
- Click Actions and Start Web Server to ensure the web server is running
- 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
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
- Power Demonstration
- source /web/power.html