Initialisation depot

This commit is contained in:
Serge NOEL committed 2026-06-17 14:00:51 +02:00
commit efdf1683af
33190 files changed
+5907629

No files matched your search

+81
View File
@@ -0,0 +1,81 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2008 -->
<title>JMRI: Frame Servlet</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Frame Servlet</h1>
<p>The JMRI Frame Servlet provides web access to JMRI windows. Its base url is "/frame/",
which by itself will return a page listing available frames.</p>
<p>It uses the facilities of the <code>jmri.util.JmriJFrame</code> class to locate windows
and create an image of their current appearance. The window does not have to be maximized,
but it does have to be open; it's OK for the window to have been minimized.</p>
<p>The <a href="index.shtml#Configure">Web Server Preferences</a> can be used to adjust the
default delay after a click and adjust the periodic refresh between clicks. You can also
enter a list of frames which are not to be allowed, and enable ajax refresh (recommended) or
use the older meta-refresh.</p>
<p>You can override the defaults for individual pages by adding the following yes/no
parameters to your URL:</p>
<ul>
<li><strong>plain</strong> (hide the footer links)</li>
<li><strong>protect</strong> (protect the frame from user clicks, i.e. read-only image, but
with refresh)</li>
<li><strong>ajax</strong> (use ajax for updates)</li>
</ul>
To display any <em>already open</em> JMRI window as a <strong>clickable</strong> image that
periodically refreshes, use a URL like: <code><a href=
"http://127.0.0.1:12080/frame/Monitor%20Slots.html">http://127.0.0.1:12080/frame/Monitor%20Slots.html</a></code><br>
<code><a href=
"http://127.0.0.1:12080/frame/Analog%20Clock.html">http://127.0.0.1:12080/frame/Analog%20Clock.html</a></code><br>
<code><a href=
"http://127.0.0.1:12080/frame/Turnout%20Table.html">http://127.0.0.1:12080/frame/Turnout%20Table.html</a></code>
<p>Note the frame title in the URL, followed by ".html". Replace any spaces in the title with
"%20".</p>
For current, dynamically-generated list of available windows, use this URL: <code><a href=
"http://127.0.0.1:12080/frame">http://127.0.0.1:12080/frame</a></code>
<p><em>Note:</em> Adjust defaults such as refresh timing, disallowed frames and ajax usage in
Web Server Preferences.</p>
You can override the defaults for individual pages by using the following parameters in your
URL:
<ul>
<li><strong>plain</strong> (hide the footer links)</li>
<li><strong>protect</strong> (protect the frame from user clicks, i.e. read-only image, but
with refresh)</li>
<li><strong>ajax</strong> (use ajax for updates)</li>
</ul>
Example, showing no links, protected, using ajax to refresh every 12 seconds:<br>
<code><a href=
"http://127.0.0.1:12080/frame/Power%20Control.html?ajax=true&amp;plain=true&amp;protect=true&amp;retry=12">
http://127.0.0.1:12080/frame/Power%20Control.html?ajax=true&amp;plain=true&amp;protect=true&amp;retry=12</a></code>
<p>The <code>jmri/web/servlet/frameimage/JmriJFrameServlet.properties</code> <a href=
"https://github.com/JMRI/JMRI/blob/master/java/src/jmri/web/servlet/frameimage/JmriJFrameServlet.properties">
properties file</a> can be used to configure the HTML that's returned when a frame is
requested.</p>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+395
View File
@@ -0,0 +1,395 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator"
content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<title>JMRI JSON Servlet</title>
<!--#include virtual="/help/en/parts/Style.shtml" -->
<style type="text/css">
table#jsonResponses {
border-collapse: collapse;
}
table#jsonResponses td {
border: 1px solid gray;
width: 33%;
}
table.data {
margin: initial;
margin-left: 2em;
}
code {
white-space: normal;
}
</style>
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI JSON Servlet</h1>
<p>
The JMRI <a href="https://en.wikipedia.org/wiki/JSON">JSON</a>
Servlet provides a RESTful API and a <a
href="https://en.wikipedia.org/wiki/WebSocket">WebSocket</a> 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.
</p>
<p>
<strong>Note</strong> the JMRI JSON protocol is documented in <a
href="https://www.jmri.org/JavaDoc/doc/jmri/server/json/package-summary.html">JMRI
API Documentation</a>.
</p>
<h2 id="jmri_json_servlet">JMRI JSON Servlet</h2>
<p>
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 <a href="PanelServlet.shtml#example">PanelServlet Help page</a>.
</p>
<h2>Setting up the JSON Servlet</h2>
<p>The JMRI JSON Servlet is a feature that is part of the Web
Server. To use this service:</p>
<ol>
<li>Ensure the web server's port is unique:
<ul>
<li>Open the Preferences dialog</li>
<li>Click <strong>Web Server</strong> on the left side
</li>
<li>Ensure the port number is unique (for example 12080).
Other ports are used by WiThrottle, JSON Server, etc.</li>
<li>Click Save</li>
</ul>
</li>
<li>Click <strong>Actions</strong> and <strong>Start
Web Server</strong> to ensure the web server is running (<strong>Tools
&rArr; Servers &rArr; Start JRMI Web Server</strong> in PanelPro).
</li>
<li>If you want the Web Server to run each time you start JMRI:
<ul>
<li>Open the JMRI <strong>Preferences</strong> dialog
</li>
<li>Select <strong>Start Up</strong> in the left column
</li>
<li>Click <strong>Add &#9662;</strong></li>
<li>Select <strong>Perform action...</strong></li>
<li>Select <strong>Start Web Server</strong></li>
<li>Click <strong>OK</strong></li>
</ul>
</li>
</ol>
<h2>Paths</h2>
<p>The servlet responds to the following paths:</p>
<dl>
<dt>/json</dt>
<dd>
Depending on protocol:
<dl>
<dt>HTTP</dt>
<dd>Open a JSON WebSocket console that allows experimentation
with JSON sockets.</dd>
<dt>WS</dt>
<dd>Open a JSON WebSocket.</dd>
</dl>
</dd>
<dt>
/json/<em>type</em>
</dt>
<dd>
Using the HTTP protocol:
<dl>
<dt>GET</dt>
<dd>
request a list of objects of <em>type</em>
</dd>
<dt>PUT</dt>
<dd>
add an object of <em>type</em>
</dd>
</dl>
A JSON array of valid types for your JMRI installation is available
by using the <em>type</em> "
<code>
<a href="/json/type">type</a>
</code>
" (with JMRI Web Server running). You can also see the list using
the Tables menu on the JMRI Web Server Home page. "
<code>
<a href="/tables/type">/tables/type</a>
</code>
" See the <a
href="https://www.jmri.org/JavaDoc/doc/jmri/server/json/package-summary.html">protocol
documentation</a> for more details.
</dd>
<dt>
/json/<em>type</em>/<em>name</em>
</dt>
<dd>
Using the HTTP protocol:
<dl>
<dt>GET</dt>
<dd>
request the object of <em>type</em> with name <em>name</em>
</dd>
<dt>POST</dt>
<dd>
modify the object of <em>type</em> with name <em>name</em>
</dd>
<dt>DELETE</dt>
<dd>
remove the object of <em>type</em> with name <em>name</em>
</dd>
</dl>
</dd>
</dl>
<h2 id="jmri_json_server">JMRI JSON Server</h2>
<p>The JMRI JSON server is functionally identical to the JSON
WebSocket interface, but running over a standard network socket.</p>
<h2 id="jquery_jmri">jquery.jmri.js</h2>
<p>
<a
href="https://github.com/JMRI/JMRI/blob/master/web/js/jquery.jmri.js"><em>jquery.jmri.js</em></a>
is a <a href="https://jquery.com">jQuery</a> library that ships with
JMRI and makes the JSON protocol support "just work" on most current
browsers.
</p>
<p>Examples of use of the jquery.jmri.js JavaScript library that
ships with JMRI include:</p>
<dl>
<dt>Operations Conductor</dt>
<dd>
source <a
href="https://github.com/JMRI/JMRI/blob/master/web/js/operations.js">/js/operations.js</a>
</dd>
<dt>Panel</dt>
<dd>
source <a
href="https://github.com/JMRI/JMRI/blob/master/web/js/panel.js">/js/panel.js</a>
</dd>
<dt>JSON Console</dt>
<dd>
source <a
href="https://github.com/JMRI/JMRI/blob/master/web/js/json-console.js">/js/json-console.js</a>
</dd>
<p>
Note: The source code for the above is found in the web/ts
directory, which contains the JavaScript and Typescript source
code. This is <a href="../doc/Technical/Patterns.shtml#typescript">compiled
to the web/js directory</a> for actual execution.
<dt>
<a href="/web/power.html">Power
Demonstration</a> (with JMRI Web Server running).
</dt>
<dd>
source <a
href="https://github.com/JMRI/JMRI/blob/master/web/power.html">/web/power.html</a>
</dd>
</dl>
<h2 id="websocket_examples">WebSocket Examples</h2>
<p>
The <b>WebSocket</b> feature of the servlet can be seen by browsing
to the <b>/json/</b> url, where a <b>JSON console</b> is provided
for testing.<br>
Notes: Method "get" is default. "get"ting an item sets up a listener which sends all subsequent changes as well.<br>
</p>
<table id="jsonResponses">
<caption><b>Example commands and responses</b></caption>
<tr>
<th>command</th>
<th>response</th>
<th>notes</th>
</tr>
<tr>
<td><code>{"type":"sensor","data":{"name":"IS2"}}</code></td>
<td><code>{"type":"sensor","data":{"name":"IS2","state":2,"userName":null,"comment":null,"properties":[],"inverted":false}}</code></td>
<td>request current state of sensor IS2</td>
</tr>
<tr>
<td><code>{"type":"sensor","method":"post","data":{"name":"IS2","state":4}}</code></td>
<td><code>{"type":"sensor","data":{"name":"IS2","state":4,"userName":null,"comment":null,"properties":[],"inverted":false}}</code></td>
<td>set sensor IS2 to InActive (4)</td>
</tr>
<tr>
<td><code>{"type":"turnout","data":{"name":"IT99"}}</code></td>
<td><code>{"type":"turnout","data":{"name":"IT99","state":4,"userName":null,"comment":null,"properties":[],"inverted":false,"feedbackMode":1,"feedbackModes":[16,32,128,1],"sensor":[null,null]}}</code></td>
<td>request current state of turnout IT99</td>
</tr>
<tr>
<td><code>{"type":"turnout","method":"put","data":{"name":"IT98","userName":"Test Turnout 98"}}</code></td>
<td><code>{"type":"turnout","data":{"name":"IT98","userName":"Test Turnout 98","comment":null,"properties":[],"inverted":false,"state":0,"feedbackMode":1,"feedbackModes":[16,32,128,1],"sensor":[null,null]}}</code></td>
<td>creaate turnout IT98 using "put" method</td>
</tr>
<tr>
<td><code>{"type":"power","method":"get"}</code></td>
<td><code>{"type":"power","data":{"name":"LocoNet","state":2,"default":true,"prefix":"L"}}</code></td>
<td>get power state of the default connection; state 2=ON, 4=OFF, 8=IDLE, 0=UNKNOWN</td>
</tr>
<tr>
<td><code>{"type":"power","method":"get","data":{"prefix":"L2"}}</code></td>
<td><code>{"type":"power","data":{"name":"LocoNet Prog","state":4,"default":false,"prefix":"L2"}}</code></td>
<td>get power state of a specific connection by system prefix</td>
</tr>
<tr>
<td><code>{"type":"power","method":"post","data":{"prefix":"L","state":2}}</code></td>
<td><code>{"type":"power","data":{"name":"LocoNet","state":2,"default":true,"prefix":"L"}}</code></td>
<td>set power state on a specific connection; use state 2 for ON, 4 for OFF; omit "prefix" to target the default connection</td>
</tr>
<tr>
<td><code>{"list":"power"}</code></td>
<td><code>[{"type":"power","data":{"name":"LocoNet","state":2,"default":true,"prefix":"L"}},{"type":"power","data":{"name":"LocoNet Prog","state":4,"default":false,"prefix":"L2"}}]</code></td>
<td>list all configured power connections, one entry per connection</td>
</tr>
<tr>
<td><code>{"type":"memory","data":{"name":"IMCURRENTTIME"}}</code></td>
<td><code>{"type":"memory","data":{"name":"IMCURRENTTIME","userName":null,"comment":null,"value":"2:53
PM"}}</code></td>
<td>get builtin memory (fast)clock time.</td>
</tr>
<tr>
<td><code>{"type":"ping"}</code></td>
<td><code>{"type":"pong"}</code></td>
<td>ping request and response</td>
</tr>
<tr>
<td><code>{"list":"panels"}</code></td>
<td><code>[{"type":"panel","data":{"name":"ControlPanel/R&amp;R","URL":"/panel/ControlPanel/R&amp;R?format=xml","userName":"R&amp;R","type":"Control
Panel"}},{"type":"panel","data":{"name":"Layout/Waccamaw%20Coast%20Line","URL":"/panel/Layout/Waccamaw%20Coast%20Line?format=xml","userName":"Waccamaw
Coast Line","type":"Layout"}}]</code></td>
<td>request a list of panels, respond with array, example
shows two panels</td>
</tr>
<tr>
<td><code>{"type":"throttle","data":{"name":"CSX754","address":754}}</code></td>
<td><code>{"type":"throttle","data":{"name":"CSX754","address":754,"speed":0.0,"forward":true,
"F0":false,"F1":false,"F2":false,"F3":false,"F4":false,"F5":false,"F6":false,"F7":false,
"F8":false,"F9":false,"F10":false,"F11":false,"F12":false,"F13":false,"F14":false,
"F15":false,"F16":false,"F17":false,"F18":false,"F19":false,"F20":false,"F21":false,
"F22":false,"F23":false,"F24":false,"F25":false,"F26":false,"F27":false,"F28":false,
"throttle":"CSX754"}}</code></td>
<td>request throttle for address 754 on the default connection, referred to as "CSX754"; add "prefix" to target a specific connection instead</td>
</tr>
<tr>
<td><code>{"type":"throttle","data":{"name":"CSX754","address":754,"prefix":"L"}}</code></td>
<td><code>{"type":"throttle","data":{"name":"CSX754","address":754,"prefix":"L","speed":0.0,"forward":true,"throttle":"CSX754"}}</code></td>
<td>request throttle for address 754 on a specific connection by system prefix &mdash; useful when multiple command stations are configured; subsequent speed/function commands use the name "CSX754" as normal</td>
</tr>
<tr>
<td><code>{"type":"throttle","data":{"name":"CSX754","speed":0.25}}</code></td>
<td><code>{"type":"throttle","data":{"name":"CSX754","speed":0.25,"throttle":"CSX754"}}</code></td>
<td>request speed of throttle "CSX754" to 25%</td>
</tr>
<tr>
<td><code>{"type":"throttle","data":{"name":"CSX754","release":null}}</code></td>
<td><code>{"type":"throttle","data":{"name":"CSX754","release":null,"throttle":"CSX754"}}</code></td>
<td>release the throttle "CSX754"</td>
</tr>
<tr>
<td><code>{"type":"light","data":{"name":"IL1"}}</code></td>
<td><code>{"type":"light","data":{"name":"IL1","userName":"Yard Light","comment":null,"state":4,"properties":[]}}</code></td>
<td>get current state of light IL1; state 2=ON, 4=OFF, 0=UNKNOWN</td>
</tr>
<tr>
<td><code>{"type":"light","method":"post","data":{"name":"IL1","state":2}}</code></td>
<td><code>{"type":"light","data":{"name":"IL1","userName":"Yard Light","comment":null,"state":2,"properties":[]}}</code></td>
<td>turn light IL1 on (state 2); use state 4 to turn off</td>
</tr>
<tr>
<td><code>{"list":"lights"}</code></td>
<td><code>[{"type":"light","data":{"name":"IL1","userName":"Yard Light","comment":null,"state":2,"properties":[]}},{"type":"light","data":{"name":"IL2","userName":null,"comment":null,"state":4,"properties":[]}}]</code></td>
<td>list all configured lights; returns an empty array <code>[]</code> if none are configured</td>
</tr>
<tr>
<td><code>{"type":"block","data":{"name":"IB1"}}</code></td>
<td><code>{"type":"block","data":{"name":"IB1","userName":"AUTOBLK:1","comment":null,"value":"ns2608"}}</code></td>
<td>request current value for block IB1</td>
</tr>
<tr>
<td><code>{"type":"train","data":{"name":"3"}}</code></td>
<td><code>{"type":"train","data":{"name":"3","userName":"BB","iconName":"BB 1017",
"departureTime":"07:50","description":"Bakersfield - Sweeper","route":"Bksfld-turn",
"routeId":"4","locations":[</code>...<code>],"engines":[</code>...<code>],
"cars": [</code>...<code>],"trainDepartsName":"Bakersfield",
"trainTerminatesName":"Bakersfield","location":"Bakersfield",
"locationId":"4r1","status":"Partial 4/8 cars","statusCode":20,
"length":87,"weight":144,"leadEngine":"SP 1017",
"caboose":"NH 681"}}</code></td>
<td>request train by name<br />
NOTE: locations, engines and cars arrays not shown here for clarity</td>
</tr>
<tr>
<td><code>{"type":"car","method":"post","data":{"name":"ATSF10407",
"trainId":null,"locationUnknown":true,"location":null}}</code></td>
<td><code>
{"type":"car","data":{"name":"ATSF10407","number":"10407","road":"ATSF","rfid":"","carType":"Boxcar","carSubType":"",
"length":50,"weight":4.4,"weightTons":88.0,"color":"Tuscan","owner":"AT","built":"1943","comment":"",
"outOfService":false,"locationUnknown":true,"location":null,"trainId":null,"trainName":null,"destination":null,
"load":"L","hazardous":false,"caboose":false,"passenger":false,"fred":false,"removeComment":"","addComment":"",
"kernel":"","utility":false,"isLocal":false,"finalDestination":null,"returnWhenEmpty":null,"returnWhenLoaded":null,
"division":"","status":"&lt;&quest;&gt;"}} </code></td>
<td>use post method to remove car from train and mark it as
LocationUnknown.</td>
</tr>
</table>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+42
View File
@@ -0,0 +1,42 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2015 -->
<title>JMRI: Operations web functions</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Operations web functions</h1>
<p>JMRI OperationsPro&trade; provides many features to support operating sessions. You can learn
more about <a href="../apps/OperationsPro/index.shtml">JMRI OperationsPro here</a>.</p>
<p>With JMRI running on your network and the <a href="index.shtml#Start">Web Server</a> active,
the current functionality can be accessed by visiting the <a href=
"http://localhost:12080/operations">http://localhost:12080/operations</a> URL.</p>
<p>You can view a list of available <b>Trains</b> under <b>Operations</b>, <b>Trains</b>. For each train, there are two options,
<b>Manifest</b> and <b>Conductor</b>. These provide a browser-friendly experience very similar to their respective
windows in JMRI: (<a href="../../package/jmri/jmrit/operations/Operations.shtml#Trains">Trains</a>,
<a href="../../package/jmri/jmrit/operations/Operations.shtml#PrintingManifests">Manifest</a>,
<a href="../../package/jmri/jmrit/operations/Operations.shtml#TrainConductor">Conductor</a>)
<h3>Screenshots:</h3>
<h4>Example Trains page:</h4><img src="images/WebServerOperationsTrainsExample.jpg">
<h4>Example Manifest page:</h4><img src="images/WebServerOperationsTrainsManifestExample.jpg">
<h4>Example Conductor page:</h4><img src="images/WebServerOperationsTrainsConductorExample.jpg">
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+373
View File
@@ -0,0 +1,373 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2012, 2014, 2020 -->
<title>JMRI Remote Panels</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI Remote Panels</h1>
<p>JMRI displays panels via a web browser at the <strong>/panel</strong> relative URL.</p>
<a href="images/webServerPanelView.png"><img src="images/webServerPanelView.png" alt=
"Web Server Panel screenshot" width="553" height="363"></a>
<p>Remote Panel URLs are:</p>
<dl>
<dt>/panel</dt>
<dd>Without any additional parameters, <em>/panel</em> lists the open JMRI panels, as shown
in the screen shot above (panels may be hidden in PanelPro, but they must be loaded to show
up).<br>
Clicking or tapping on one of the listed panel names will open a functioning panel.</dd>
<dt>/panel?name=&lt;type&gt;/&lt;name&gt;</dt>
<dd>Displays an open, operable panel. <em>&lt;type&gt;</em> is one of: <em>Panel</em>,
<em>ControlPanel</em>, <em>Switchboard</em> or <em>Layout</em>.</dd>
<dt>/panel/&lt;type&gt;/&lt;name&gt;?format=xml</dt>
<dd>Retrieves a portable XML representation of the panel. <em>&lt;type&gt;</em> is one of:
<em>Panel</em>, <em>ControlPanel</em>, <em>Switchboard</em> or <em>Layout</em>.</dd>
<dt>/panel/&lt;type&gt;/&lt;name&gt;?protect=yes</dt>
<dd>Displays a read-only representation of the specified panel.</dd>
</dl>
<p>Panel display requires a modern browser with HTML5 support including WebSocket.
The JMRI web server's About page includes a test for this.</p>
<h2 id="example">Technical Example: Behind the scenes of Web Server Panels</h2>
<a href="images/WebServerFlow.png"><img src="images/WebServerFlow.png" alt=
"Web Server Data Flow Diagram" width="341" height="640" class="floatRight" title=
"Simplified Web Server Flow (by EB)"></a>
<p>This chapter shows an overview of how JMRI Web Server operates between the JMRI
application and the Web Browser to demonstrate what code is involved, using Panels as an
example.</p>
<p>In <a href="#exampleA">part A</a> we show at how a panel initially shows up in the browser
of a (remote) user logged on to JMRI Web Server.</p>
<p><a href="#exampleB">Part B</a> focuses on the opposing flow of information. You will
discover how user action in the browser is picked up all the way back to JMRI and even to the
layout.</p>
Some definitions
<ul>
<li>Web Server displays panels, roster engines, tables and Operations in the web browser,
using a mix of XML, Javascript, jdom, json, jQuery and CSS.</li>
<li>Each of these categories is displayed in a separate frame, accessible in the browser
via tabs at the top edge of the browser window: Panels, Throttle, Operations, Tables:<br>
<a href="images/webServerMenubar.png"><img src="images/webServerMenubar.png" alt=
"Web Server Panel screenshot" width="250" height="90"></a>
</li>
<li>Each category has its own JavaScript code file, e.g., <code>/web/js/Panel.js</code>,
plus supporting "Servlets" to connect to JMRI, as documented in the <a href=
"https://www.jmri.org/JavaDoc/doc/jmri/web/server/package-summary.html">Web Server
Javadoc</a>. (Note: The code is run from <code>/web/js/</code>, but the real
source code is stored in <code>/web/ts/</code> to allow the use of
<a href="../doc/Technical/Patterns.shtml#typescript">compiled TypeScript</a>)
</li>
</ul>
<h3 id="exampleA">A. From JMRI to the browser</h3>
<p>We assume JMRI and Web Server are running and the user has a browser pointing to
<code>http://localhost:12080</code> as set in JMRI Web Server preferences.<br>
Configuration and current state of panel items is handled by the
<code>jmri/jmrit/display/xPanelEditor.java</code> code. This means that creating a panel and
items like Turnouts connected to the layout, and listening for changes has been completed
first in the JMRI application. A graphical control panel needs to be loaded in JMRI for it to
show up in the JMRI web browser drop down (it is OK if a panel is hidden in JMRI UI).</p>
<a href="images/webservletsexample_A.png"><img src="images/webservletsexample_A.png" alt=
"Web Server Sequence Diagram A (draft)" width="471" height="231"></a>
<ol>
<li>To open a panel the User uses the mouse to click the "Panel" combo on the menu
bar.</li>
<li>The web browser responds by asking Web Server to produce the panel by sending a GET
request together with a <code>/panel/"name"</code> URL.</li>
<li>This starts the <code>/web/js/panel.js</code> JavaScript code.</li>
<li>The main method in <code>panel.js</code> is <code>$(document).ready(function() {</code>
(around line 2000).<br>
It ends with a call to the <code>requestPanelXML(panelName);</code> method:<br>
<code><br>
141 var requestPanelXML = function(panelName) {<br>
142 &nbsp;&nbsp;&nbsp;$.ajax({<br>
143 &nbsp;&nbsp;&nbsp;type: "GET",<br>
144 &nbsp;&nbsp;&nbsp;url: "/panel/" + panelName + "?format=xml", [...]<br>
145 &nbsp;&nbsp;&nbsp;success: function(data, textStatus, jqXHR) {<br>
146 &nbsp;&nbsp;&nbsp;processPanelXML(data, textStatus, jqXHR);<br>
147 &nbsp;&nbsp;&nbsp;setTitle($gPanel["name"]); } [...]<br></code><br>
Here, line 142 sends an <a href="https://www.w3schools.com/xml/ajax_intro.asp">AJAX</a>
(Asynchronous JavaScript And XML) <code>GET XMLHttpRequest</code>code&gt; for the panel
to be retrieved by its name to the JMRI PanelServlet.
</li>
<li>The connection between web server and JMRI categories is handled by
<strong>servlets</strong> in <code>JMRI/java/src/jmri/web/servlet/</code>, pieces of Java
code interacting with the web server. The extended HttpServlet
<code>jmri/web/servlet/panel/AbstractPanelServlet.java</code> links the web server requests
to the information kept in Java. The <code>doGet()</code> HttpServer message calls in
<code>panel.js</code> to answer the request.</li>
<li>In the case of Switchboards the
<code>/jmri/web/servlet/panel/SwitchboardServlet.java</code> contains methods such as:
<ul>
<li><code>String getPanelType()</code>
</li>
<li><code>String getXmlPanel(String name)</code>
</li>
</ul>
When you want to develop new features on web panels, that second method needs to be
expanded to include them when pulling new information from SwitchboardEditor and
individual BeanSwitches placed on that panel:<br>
<code><br>
40 protected String getXmlPanel(String name) {<br>
41 &nbsp;&nbsp;&nbsp;SwitchboardEditor editor = (SwitchboardEditor) getEditor(name);<br>
42 &nbsp;&nbsp;&nbsp;&nbsp;Element panel = new Element("panel");<br>
43 &nbsp;&nbsp;&nbsp;&nbsp;panel.setAttribute("shape", editor.getSwitchShape());<br>
44 &nbsp;&nbsp;&nbsp;&nbsp;Element color = new Element("backgroundColor");<br>
45 &nbsp;&nbsp;&nbsp;&nbsp;color.setAttribute("red",
Integer.toString(editor.getBackgroundColor().getRed()));<br>
46 &nbsp;&nbsp;&nbsp;&nbsp;[...] 47
&nbsp;&nbsp;&nbsp;&nbsp;panel.addContent(color);<br></code><br>
Line 45 allows us to later from <code>panel.js</code> call e.g.,<br>
<code>979 $("#panel-area").css({"background-color": "rgb(" + $widget.red + "," +
$widget.green + "," + $widget.blue + ")"});</code>
</li>
<li>From the Java code running JMRI, specific information is written out to an xml
"snapshot" for both the panel (JFrame) and the individual objects placed on that panel, so
called 'Positionables':
<ul>
<li>The complete panel is "stored" by the <code>store(object)</code> method in
<code>jmri/jmrit/display/switchboardEditor/configurexml/SwitchboardEditorXml.java</code>:<br>
<code><br>
41 public Element store(Object o) {<br>
42&nbsp;&nbsp;SwitchboardEditor p = (SwitchboardEditor) o;<br>
43&nbsp;&nbsp;Element panel = new Element("switchboardeditor");<br>
44&nbsp;&nbsp;JFrame frame = p.getTargetFrame();<br>
45&nbsp;&nbsp;panel.setAttribute("name", "" + frame.getTitle());<br>
46&nbsp;&nbsp;panel.setAttribute("class",
"jmri.jmrit.display.switchboardEditor.configurexml.SwitchboardEditorXml");<br>
[...]<br></code><br>
followed by a for-each loop:<br>
<code><br>
for (BeanSwitch sub : _switches) {<br>
&nbsp;&nbsp;try {<br>
&nbsp;&nbsp;&nbsp;&nbsp;Element e = ConfigXmlManager.elementFromObject(sub);<br>
&nbsp;&nbsp;&nbsp;&nbsp;e.setAttribute("label",
sub.getNameString());<br></code><br></li>
<li>Additional properties of all BeanSwitches on the Switchboard panel are exported in
a for-each loop in
<code>jmri/jmrit/display/switchboardEditor/configurexml/BeanSwitchXml.java</code>:<br>
<code><br>
public Element store(Object o) {<br>
&nbsp;&nbsp;BeanSwitch bs = (BeanSwitch) o;<br>
&nbsp;&nbsp;Element element = new Element("beanswitch");<br>
&nbsp;&nbsp;element.setAttribute("label", bs.getNameString());<br>
&nbsp;&nbsp;[...]<br>
}<br></code><br></li>
</ul>
The result is an xml <code>out.outputString(doc)</code> in reply to the web server
request.
</li>
<li>To process the xml response returned for the <code>requestPanelXML</code> command, the
JavaScript code in <code>/web/js/panel.js</code> contains the function<br>
<code>processPanelXML($returnedData, $success, $xhr)</code> (around line 160)<br>
that renders from the xml data in <code>$xml</code> an object-based web panel html, ready
to forward to the browser and display client-side using CSS and HTML5.<br>
Among a lot of other properties, the background color is set from the <code>panel</code>
attribute:<br>
<code><br>
$("#panel-area").css({backgroundColor: $gPanel.backgroundcolor});<br></code><br>
where <code>$()</code> invokes jQuery as a selector (a function that returns a set of
elements found in the DOM of the web page).<br>
After the attributes of the main panel such as color, size and position are copied from the
xml, all individual elements in the panel xml are processed in a for-each loop, building a
persistent array of <code>$widget</code> arrays:<br>
<code><br>
236 $panel.contents().each(<br>
237 &nbsp;&nbsp;function() {<br>
238 &nbsp;&nbsp;&nbsp;&nbsp;var $widget = new Array();<br></code><br>
In such an array the attributes of each (positionable) item are copied in 1-on-1 from the
xml, filling the basic widget web object:<br>
<code>244 $(this.attributes).each(function() {<br>
245 &nbsp;&nbsp;$widget[this.name] = this.value;<br>
246 });<br></code></li>
<li>Next, every <code>$widget</code> array if enriched by extra fields, either using
attributes shared on the panel, like<br>
<code>666 var $cr = $gPanel.turnoutcirclesize * SIZE;</code><br>
with attributes of one of the elements: <code>1039 $widget['text8'] =
$(this).find('inconsistentText').attr('text');</code><br>
or with copies of other elements already present in the $widget array, for example:<br>
<code><br>
case "beanswitch" :<br>
&nbsp;&nbsp;$widget['name'] = $widget.label;</code><br>
which creates a 'name' item in the array and copies in the <code>label</code> item.</li>
<li>Next, the HTML is written:<br>
<code><br>
$("#panel-area").append("&lt;div id=" + $widget.id + "r class='" +<br>
$widget.classes + "' " + $hoverText + "&gt;&lt;/div&gt;");<br></code><br></li>
<li>The complete HTML "page" is sent out to user's screen as a structured but basically
static visual, composed of graphical "objects" that will be updated via the server as
needed at a later point in time when the status of one such item changes inside JMRI.</li>
<li>Next, <code>panel.js</code> starts up a process to send and listens for changes to each
panel element (called "nodes" in xml speak).<br>
The nodes in our example panel are called <strong>BeanSwitches</strong>. SensorIcons and
LayoutTracks are similar nodes. Each element is assigned a <code>$widget</code> variable in
<code>/web/js/panel.js</code>, to interact with the browser document object model (DOM)
HTML5+ entities via jdom (Java-based document object model for XML), jQuery and JavaScript
Object Notation (JSON).<br>
To be able to keep a link to every graphical element displayed on the browser we mainly use
<code>&lt;div/&gt;</code>s that the server will feed to the user's browser and using jQuery
can be contacted by their unique ID.</li>
<li>From that moment, <code>panel.js</code> follows interaction in
<code>java.src.jmrit.display.xPanelEditor</code> and the separate PositionableItems like
LayoutTurnout, CPE SensorIcon and Switchboard Beanswitch.</li>
<li>Now that the <code>$(document).ready(function()</code> main method is running, it will
listen for changes, and depending on the type (object) will start <code>updateWidgets(name,
state, data)</code>, which in turn calls <code>setWidgetState(widgetId, state, data)</code>
to update the shape displayed on screen, e.g., when a sensor on the layout changes
state.</li>
</ol>
<p><strong>What to Code:</strong>
</p>
<ol>
<li>Describe how to get your specific stuff out of JMRI and into the web server:
<ul>
<li>Shared: create the <code>store(panel)</code> method</li>
<li>Per item: add code in a <code>for-each</code> element loop in the same method</li>
</ul>
</li>
<li>Describe how to fill the <code>$widgets</code> for your items in the
<code>processPanelXML()</code> function.</li>
</ol>
<p><strong>Where to Code:</strong>
</p>
<ol>
<li>In <code>/jmri/jmrit/display/xEditor/configureXml/xEditorXml.java</code> + similar
files for any special classes your panel type relies on.</li>
<li>In <code>/web/js/panel.js</code></li>
</ol>
<h3 id="exampleB">B. From the browser to JMRI</h3>
<a href="images/webservletsexample_B.png"><img src="images/webservletsexample_B.png" alt=
"Web Server Sequence Diagram A (draft)" width="471" height="201"></a>
<p>Note: Web click events are only enabled if a panel is configured (in JMRI xPanelEditor) to
allow control.</p>
<ol>
<li>To perform regular click-handling, a <code>mouseup()</code> function is hooked up to
widgets in <code>/web/js/panel.js</code> (around line 1120):
<ul>
<li>a state toggle function for all non-momentary clickable widgets:<br>
<code>$('.clickable:not(.momentary)').bind(UPEVENT, $handleClick);<br></code></li>
<li>Momentary widgets go active on <code>mousedown</code>, and inactive on
<code>mouseup</code></li>
</ul>
</li>
<li>Sending commands to the JMRI items under control, and listening for changes to those
items in JMRI, is handled by the JSON WebSocket Server.
<ul>
<li>User interaction in the browser is picked up via <code>UserClicked(object)</code>
and GET/POST HTTP messages.</li>
<li>When a <code>mouseClickEvent</code> is heard, the <code>$handleClick(e)</code>
function in <code>panel.js</code> calls <code>sendElementChange($widget.jsonType,
$widget.systemName, $newState)</code>, resulting in <code>jmri.setObject(type, name,
state)</code> forwarding to the JMRI system.</li>
</ul>
</li>
<li>The <code>$handleClick(e)</code> function in <code>panel.js</code> (around line 1160)
updates the widgets involved:
<ul>
<li>Text based widgets are told how to change the &lt;div&gt; item that's already
displayed on screen: fetch them by their ID, update their contents e.g., show an ON
label instead of OFF.</li>
<li>Icon-based widget are redrawn to reflect changes to state or occupancy by drawing
on the graphical "canvas"</li>
<li>It is also possible to swap styles on a div using CSS, for example to change the
style of a widget from "css2" to a new style called "css4" (where 4 represents the
<code>int</code> value for Inactive and Thrown):<br>
<br>
<code>var $reDrawIcon = function($widget) {<br>
&nbsp;&nbsp;$('div#' + $id).css($widget['css' + $newState]);<br></code><br></li>
</ul>
The actual CSS styling code for the element is taken from <code>web/css/panel.css</code>
file by he user's browser.
</li>
<li>Via <code>sendElementChange</code> (around line 1750) a call is made to
<code>jmri.setObject(type, name, state);</code>, where <code>jmri</code> represents the
JMRI WebSocket on this server</li>
<li>
<code>setObject()</code> in <code>/web/js/jquery.jmri.js</code> <a href=
"https://jquery.com">jQuery JavaScript Library</a> instructs JMRI to set for example a
Light to "On" via a Post message:<br>
<code><br>
jmri.setLight = function (name, state) {<br>
&nbsp;&nbsp;jmri.socket.send("light", { name: name, state: state }, 'post');<br>
}<br></code>
</li>
<li>If properly connected, on the layout a light will start to light.</li>
</ol>
<p><strong>What to Code:</strong> Specify the response to user action by adding an
<code>if(...)</code> block to the <code>$setWidgetState(id, newState, data)</code> function
(near line 1570).</p>
<p><strong>Where to Code:</strong> <code>$handleClick()</code> function in
<code>jmri/web/js/panel.js</code></p>
<h3>Conclusion</h3>
<p>We hope the above example will help new developers understand which parts are required to
create and maintain web display for a panel type, and how each part is connected to display
stuff from JMRI in the web browser, and back.<br>
As always, start small and check often!</p>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+43
View File
@@ -0,0 +1,43 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2015 -->
<title>JMRI: Roster Servlet</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Roster Servlet</h1>
<p>The JMRI Roster Servlet provides web access to information about JMRI roster entries. This
servlet responds to the following URL patterns:</p>
<ul>
<li>/roster/</li>
<li>/roster/list</li>
<li>/roster/list?filter=filter[&amp;filter=filter]</li>
<li>/roster/&lt;ID&gt;</li>
<li>/roster/entry/&lt;ID&gt;</li>
<li>/roster/&lt;ID&gt;/image</li>
<li>/roster/&lt;ID&gt;/icon</li>
</ul>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+37
View File
@@ -0,0 +1,37 @@
<!-- Sidebar.shtml -->
<!-- This is the common sidebar definition for html/web pages -->
<hr class="hide">
<div id="side"> <!-- Block of text on left side of page -->
<div style="text-align: center">JMRI Web Access</div>
<dl>
<dt><a href="index.shtml">Basic Use</a></dt>
<dd>JMRI supports working with your layout from a web browser.
<ul>
<li><a href="index.shtml#Start">Getting Started</a></li>
<li><a href="index.shtml#Configure">Configure</a></li>
<li><a href="index.shtml#files">URLs</a></li>
</ul>
</dd>
<dt class="dtheader">Services</dt>
<dd>Details of the JMRI web services.
<ul>
<li><a href="FrameServlet.shtml">Frames</a></li>
<li><a href="JsonServlet.shtml">JSON</a></li>
<li><a href="PanelServlet.shtml">Panels</a></li>
<li><a href="RosterServlet.shtml">Roster</a></li>
<li><a href="TablesServlet.shtml">Tables</a></li>
</ul>
</dd>
<!--#include virtual="../../parts/SidebarApplications.shtml" -->
</dl>
<!--#include virtual="../../parts/SidebarTail.shtml" -->
</div> <!-- closes #side -->
<!-- button is in /Header -->
<script src="/js/side.js"></script>
<!-- /Sidebar.shtml -->
+53
View File
@@ -0,0 +1,53 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<title>JMRI: Tables Servlet</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: Tables Servlet</h1>
<p>The JMRI Tables Servlet provides web access to information about JMRI objects such as
Turnouts and Sensors.</p>
<p>This servlet responds to the following URL patterns:</p>
<dl>
<dt>/tables/</dt>
<dt>/tables/type</dt>
<dd>Lists all potentially supported data types (in a table).</dd>
<dt>/tables/&lt;type&gt;</dt>
<dd>Displays an operating list of objects of that type (or "No data for this table." in
case of an empty list).<br>
The table updates dynamically to reflect changes in JMRI. Click the State column entry to
toggle the state of that item in JMRI.<br>
<em>&lt;type&gt;</em> is one of: <em>turnout</em>, <em>sensor</em>, <em>route</em>,
<em>reporter</em> etc.</dd>
<dt>/tables/&lt;type&gt;?&lt;key1&gt;=&lt;value1&gt;&amp;&lt;key2&gt;=&lt;value2&gt;...</dt>
<dd>Query string of key=value pairs, where the specified column (key) value must match the
specified value. For example, <code>/tables/car?trainId=12&location=Lakeview</code> will only
show cars which have trainID of 12 and location of Lakeview. Use <code>?</code> to start the query
string and separate multiple parameters with <code>&amp;</code>. Any columns in the table
can be used as a filter. Note: Both key and value are case-sensitive.</dd>
</dl>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
+13
View File
@@ -0,0 +1,13 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2015 -->
<title>JMRI Web Server</title><!--#include virtual="/help/en/parts/Style.shtml" -->
<meta http-equiv="refresh" content="0; url=index.shtml">
</head>
<body>
<p>This content has been superseded by <a href="index.shtml">JMRI Web Access</a>.</p>
</body>
</html>
+270
View File
@@ -0,0 +1,270 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<!-- Copyright 2015 -->
<title>JMRI: XML I/O Servlet - no longer supported</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI: XML I/O Servlet - no longer supported</h1>
<strong>The XML I/O protocol was removed from JMRI in the 3.11 development
cycle.</strong><br>
Affected applications should be ported to using the <a href="JsonServlet.shtml">JSON
protocol</a>.<br>
This page is only for reference of older versions.
<p>The JMRI XML I/O Servlet provides bidirectional web access to JMRI services.</p>
<p>The servlet lives in the <a href=
"https://jmri.org/JavaDoc/doc/jmri/web/servlet/xmlio/package-summary.html">jmri.web.servlet.xmlio</a>
package, and provides web access to the <a href=
"https://jmri.org/JavaDoc/doc/jmri/web/xmlio/package-summary.html">JMRI XML I/O package</a>.
By default, the JMRI Web Server will send any URL that starts with <code>/xmlio</code> to
this servlet. It will list all known elements of a specified type, accept changes to the
value/state of elements, and respond with current value/state of elements. If sent a list of
elements with current values, it will "monitor" for changes to any of those elements,
returning the new values.</p>
Element types fully supported:
<ul>
<li>power</li>
<li>turnout</li>
<li>sensor</li>
<li>signalhead</li>
<li>signalmast</li>
<li>memory</li>
<li>route</li>
</ul>
Element types list-only:
<ul>
<li>roster</li>
<li>frame</li>
<li>panel</li>
<li>metadata</li>
<li>railroad</li>
</ul>
Throttle is a unique case, with a slightly different syntax, supporting read and change, but
not list or monitoring:
<ul>
<li>throttle</li>
</ul>
There are several sample pages that (used to) show how this can be used:
<dl>
<dt>
<a href="http://localhost:12080/web/request.html">web/request.html</a>
</dt>
<dd>Makes a single XML request for all available sensors, and shows their status in a
table.</dd>
<dt>
<a href="http://localhost:12080/web/monitor.html">web/monitor.html</a>
</dt>
<dd>Uses delayed requests to monitor the status of all sensors, updating a table when any
change.</dd>
<dt>
<a href="http://localhost:12080/web/throttle.html">web/throttle.html</a>
</dt>
<dd>Sends a speed command to a DCC locomotive on the layout when a button is pressed.</dd>
<dt>
<a href="http://localhost:12080/web/turnoutPanel.html">web/turnoutPanel.html</a>
</dt>
<dd>Example of a control panel on a web page.</dd>
<dt>
<a href="http://localhost:12080/web/turnoutMonitor.html">web/turnoutMonitor.html</a>
</dt>
<dd>More complex turnout table, with buttons to throw and close turnouts.</dd>
<dt>
<a href="http://localhost:12080/web/JMRI_XMLIO_test.html">web/JMRI_XMLIO_test.html</a>
</dt>
<dd>Useful for sending various commands to xmlio server and viewing the responses.</dd>
<dt>
<a href="http://localhost:12080/web/JMRIMobile.html">web/JMRIMobile.html</a>
</dt>
<dd>This tool uses the xmlio server for retrieving data from JMRI, sending changes and
monitoring for changes to elements.</dd>
</dl>
<p>Please note that the XML I/O servlet was only supported with the <a href=
"index.shtml">JMRI Web Server</a>, and may not work with other servlet containers.</p>
<h2>Request Format</h2>
<p>The XML schema is defined in the <a href="https://jmri.org/xml/schema/xmlio.xsd">xmlio.xsd
schema document</a>.</p>
<p>There is also an attribute-based syntax available (see status examples below). The xmlio
server responds with the same syntax used in the request.</p>
<p>Below are some example requests and responses.</p>
<h3>Get the status of individual objects</h3>
Request:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;item&gt;
&lt;type&gt;turnout&lt;/type&gt;
&lt;name&gt;IT12&lt;/name&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;name&gt;West sensor&lt;/name&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;power&lt;/type&gt;
&lt;name&gt;power&lt;/name&gt;
&lt;/item&gt;
&lt;/xmlio&gt;
</pre>Reply:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;item&gt;
&lt;type&gt;turnout&lt;/type&gt;
&lt;name&gt;IT12&lt;/name&gt;
&lt;value&gt;2&lt;/value&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;name&gt;West sensor&lt;/name&gt;
&lt;value&gt;4&lt;/value&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;power&lt;/type&gt;
&lt;name&gt;power&lt;/name&gt;
&lt;value&gt;2&lt;/value&gt;
&lt;/item&gt;
&lt;/xmlio&gt;
</pre>The "value" element is inserted in the request, and then it's returned as the reply. You can
just turn the reply around and use it as another request. If "value" elements are present for all
items, the response will only be returned when one or more of the included item's state has changed
to something different.
<h3>Get all objects of a type</h3>
Request:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;list&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;/list&gt;
&lt;/xmlio&gt;
</pre>Reply:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;item&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;name&gt;IS1&lt;/name&gt;
&lt;value&gt;2&lt;/value&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;name&gt;IS2&lt;/name&gt;
&lt;value&gt;4&lt;/value&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;type&gt;sensor&lt;/type&gt;
&lt;name&gt;West sensor&lt;/name&gt;
&lt;value&gt;2&lt;/value&gt;
&lt;/item&gt;
&lt;/xmlio&gt;
</pre>The response can be turned around and used as the next request.
<h3>Set the status of an object</h3>
Request:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;item&gt;
&lt;type&gt;turnout&lt;/type&gt;
&lt;name&gt;IT12&lt;/name&gt;
&lt;set&gt;2&lt;/set&gt;
&lt;/item&gt;
&lt;/xmlio&gt;
</pre>Reply:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;item&gt;
&lt;type&gt;turnout&lt;/type&gt;
&lt;name&gt;IT12&lt;/name&gt;
&lt;value&gt;2&lt;/value&gt;
&lt;/item&gt;
&lt;/xmlio&gt;
</pre>The "set" element in the request results in the state being set to the given value, and then
it's returned in the reply as a value element with the proper value at that point.
<p>All writes are done before the values are collected for any reads, but there is no
guarantee that the consequences of the writes have propagated completely.</p>
<h3>Set the status of an object (attribute-based syntax)</h3>
Request:
<pre style="font-family: monospace;">
&lt;turnout name="IT12" set="2" /&gt;
</pre>Reply:
<pre style="font-family: monospace;">
&lt;turnout name="IT12" value="2" /&gt;
</pre>
<h3>Control a Throttle</h3>
A &lt;throttle&gt; element can be used to control a DCC Throttle via the default
ThrottleManager. The first use allocates the throttle, and all later ones set any attributes
present:
<pre style="font-family: monospace;">
&lt;xmlio&gt;
&lt;throttle&gt;
&lt;address&gt;1234&lt;/address&gt;
&lt;speed&gt;0.75&lt;/speed&gt;
&lt;forward&gt;true&lt;/forward&gt;
&lt;F3&gt;false&lt;/F3&gt;
&lt;/throttle&gt;
&lt;/xmlio&gt;
</pre>A throttle element is returned unchanged.
<h2>Related Documentation</h2>
<ul>
<li>C.F. K. H. Wolf, K. Froitzheim, M. Weber, Department of Distributed Systems, University
of Ulm, "Interactive Video and Remote Control via the World Wide Web", in "<em>Lecture
Notes in Computer Science</em>", Springer, Berlin, 1996.</li>
<li>Previously in Volume 7, Number 5 of "<em>M&auml;rklin Digital Newsletter</em>", Dr. T.
Catherall Ed, September/October 1995 (<a href=
"http://rr.informatik.tu-freiberg.de/index.php?con=home&amp;sel=&amp;lang=eng&amp;js=1&amp;">project
website no longer online</a>).
</li>
</ul>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>
Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 130 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 175 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

@@ -0,0 +1,96 @@
@startuml
box /jmri/
participant Sensor
end box
box /jmri/jmrit/display/panels/xEditor/ #LightYellow
participant Switchboard
participant BeanSwitch
participant SwitchboardXml
participant BeanSwitchXml
end box
box /jmri/web/servlet/panel/
participant xPanelServlet.java
end box
box "Web Server /web/" #LightBlue
participant panel.js
participant JSONSocketSrv
participant jQuery
participant panel.css
end box
box "Browser" #White
participant browser
participant div
participant Mouse
end box
actor User
activate Sensor
activate Switchboard
activate BeanSwitch
activate panel.js
activate JSONSocketSrv
activate browser
== A. Initial Web Panel Display ==
User -> Mouse: click
Mouse -> browser: mouseUp()
browser -> JSONSocketSrv: "Show Panel"
JSONSocketSrv -> panel.js: getPanel()
panel.js -> xPanelServlet.java: requestPanelXML
activate xPanelServlet.java
xPanelServlet.java -> SwitchboardXml: xEditor#store()
activate SwitchboardXml
SwitchboardXml -> Switchboard: editor.getBgColor()
Switchboard -> SwitchboardXml: BgColor="Red"
SwitchboardXml -> panel.js: XmlDataStream
deactivate SwitchboardXml
xPanelServlet.java -> BeanSwitchXml: BeanSwitch#store()
deactivate xPanelServlet.java
activate BeanSwitchXml
BeanSwitchXml -> BeanSwitch: bs.getLabel()
BeanSwitch -> BeanSwitchXml: label="IS4+"
BeanSwitchXml -> panel.js: XmlDataStream
deactivate BeanSwitchXml
panel.js -> panel.js: processPanelXml
panel.js -> jQuery: $("#activity-alert")...
activate jQuery
jQuery -> browser: <div class=hide>
deactivate jQuery
panel.js -> browser: HTML5 <panel>
browser -> panel.css: css4?
activate panel.css
panel.css -> browser: css4
deactivate panel.css
browser -> div: ID#4,Green
activate div #00bb00
div -> User: Hi, I'm here
== B. Handling User Feedback ==
User -> Mouse: click
Mouse -> browser: mousUp(x,y)
browser -> jQuery: clicked(divID4)
activate jQuery
jQuery -> panel.js: handleClick()
deactivate jQuery
panel.js -> panel.js: sendElementChange($4)
panel.js -> JSONSocketSrv: jmri.setObject($4)
JSONSocketSrv -> Sensor: setState($4, 8)
Sensor -> BeanSwitch: newState=Inactive
BeanSwitch -> JSONSocketSrv: IS4=Inactive
JSONSocketSrv -> panel.js: handleChange(IS4)
panel.js -> panel.js: updateWidgets($4, 8)
panel.js -> jQuery: div$4=8
activate jQuery
jQuery -> browser: div$4:Red
deactivate jQuery
browser -> panel.css: css8?
activate panel.css
panel.css -> browser: css8
deactivate panel.css
deactivate div
browser -> div: ID#4,Green
activate div #dd0000
div -> user: I'm Red
@enduml
this file is input for PlantUML to produce PNG images for help/en/html/web Help
Copyright JMRI Egbert Broerse 09-2020
Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

+314
View File
@@ -0,0 +1,314 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
<title>JMRI Web Access</title><!--#include virtual="/help/en/parts/Style.shtml" -->
</head>
<body>
<!--#include virtual="/help/en/parts/Header.shtml" -->
<div id="mBody">
<!--#include virtual="Sidebar.shtml" -->
<div id="mainContent">
<h1>JMRI Web Access</h1>
<p>JMRI can provide web access to your model railroad.</p>
<h2 id="Start">Starting Web Access</h2>
<p>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.</p>
<p>Start web access by selecting <strong>Tools &rArr; Servers &rArr; Start JMRI Web
Server</strong>.</p>
<p>Test the connection:</p>
<ul>
<li>If you're using a Bonjour/Zeroconf-enabled web browser like Safari you should see a "My
JMRI Railroad" website in the "Bonjour" tab.</li>
<li>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,
<a href="http://localhost:12080">click here</a>. 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.
</li>
</ul>
<h2 id="Configure">Configure Web Access</h2>
<h3>Automatically start</h3>
<p>JMRI can automatically start the web server when launched.</p>
<p>Open the <a href="../../package/apps/TabbedPreferences.shtml">Preferences Window</a> to
configure JMRI to start the server each time you start the program.</p>
<p>Select the "Start Up" tab, click "Add &#9662;", and select "Perform action...". In the new
selection box that appears, select "Start JMRI Web Server". Don't forget to save your
changes!</p>
<h2>Web Server Preferences</h2>
<p>Web Server Preferences are in two categories:</p>
<dl>
<dt>Web Server</dt>
<dd>
<dl>
<dt>Port#</dt>
<dd>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.</dd>
<dt>Disable power control in menus</dt>
<dd>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 website can see the power status, but
cannot turn off or turn on layout power.</dd>
<dt>Start automatically with application</dt>
<dd>This will add the action "Start JMRI Web Server" to your Start Up Preferences.</dd>
</dl>
</dd>
<dt>
<a href="FrameServlet.shtml">Frame Server</a>
</dt>
<dd>
<dl>
<dt>Disable Frames</dt>
<dd>Disable the frame server. Disabling the frame server disables most other
preferences. The frame server is disabled by default.</dd>
<dt>Use Panels Instead</dt>
<dd>
If the frame server is disabled, requests for frames can be redirected to <a href=
"PanelServlet.shtml">panels</a>. Redirection to panels is enabled by default.
</dd>
<dt>Click Delay</dt>
<dd>Wait the specified number of seconds after a click on the window (frame) image
before refreshing the image.</dd>
<dt>Refresh Delay</dt>
<dd>The number of seconds before the window image is automatically refreshed.</dd>
<dt>Use Ajax?</dt>
<dd>Use features that improve performance on modern browsers. Turn off to support
obsolete browsers.</dd>
<dt>Disallowed Frames</dt>
<dd>A list of windows that will NOT be allowed in the browser.</dd>
</dl>
</dd>
</dl>
<h2 id="services">Services</h2>
<p>JMRI Web Access provides a number of web services.</p>
<p>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.<br>
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"</p>
<p>JMRI Web Access home page at <a href="http://localhost:12080">http://localhost:12080</a>
provides direct access to all of the web services. Most JMRI web access pages provide direct
access to the <a href="#panels">panels</a>, <a href="#roster">roster</a>, and <a href=
"#operations">operations</a> services.</p>
<!-- don't mention the servlets at all, just mention the services provided by the servlets -->
<h3><a id="panels" href="PanelServlet.shtml">Panels</a>
</h3>
<!-- panelServlet intro -->
<p>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 <a href=
"http://localhost:12080/panel">http://localhost:12080/panel</a>. <a href=
"PanelServlet.shtml">(More details)</a></p>
<h3 id="roster">Roster</h3>
<!-- rosterServlet intro -->
<p>The web roster at <a href=
"http://localhost:12080/roster">http://localhost:12080/roster</a> 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. <a href=
"RosterServlet.shtml">(More details)</a></p>
<h3 id="throttle">Throttles</h3>
<!-- webThrottle intro -->
<p>JMRI supports using a modern browser on a smart phone, tablet, or other computer as a
throttle device at <a href=
"http://localhost:12080/web/webThrottle.html">http://localhost:12080/web/webThrottle.html</a>
(see <a href="../../package/jmri/jmrit/webThrottle/webThrottle.shtml">Web Throttle
Help</a>).</p>
<h3><a id="operations" href="Operations.shtml">Operations</a>
</h3>
<!-- operationsServlet intro -->
<p>Operations services at <a href=
"http://localhost:12080/operations">http://localhost:12080/operations</a> include Trains,
Conductor and Manifest functions. <a href="Operations.shtml">(More
details)</a></p>
<h3 id="tables">Tables</h3>
<!-- operationsServlet intro -->
<p>Tables services at <a href="http://localhost:12080/panel">http://localhost:12080/table</a>
include Turnouts, Sensors, Routes etc. See <a href="TablesServlet.shtml">Tables Servlet</a>
for more information.</p>
<h3><a id="frames" href="FrameServlet.shtml">Windows</a>
</h3>
<!-- frameServlet intro -->
<p>JMRI can display most <em>already open</em> windows as a somewhat usable image to allow
partial remote control of JMRI.</p>
<p>The list of viewable windows is at <a href=
"http://localhost:12080/frame">http://localhost:12080/frame</a>. Please note that not all
open windows are viewable. See <a href="FrameServlet.shtml">Window Services</a> for more
information.</p>
<h3 id="files">File System</h3>
<!-- fileServlet intro -->
<p>A local web page (HTML file), graphic or text file, or directory listing can be displayed
using the appropriate URL.</p>
<p>Files in your JMRI preferences directory can be accessed via a URL path that starts with
"<code>/prefs/</code>": <a href=
"http://localhost:12080/prefs/">http://localhost:12080/prefs/</a></p>
<p>Files in certain directories in the JMRI program directory can be accessed via a URL path
that starts with "<code>/dist/</code>": <a href=
"http://localhost:12080/dist/help/en/webindex.shtml">http://localhost:12080/dist/help/en/webindex.shtml</a>
will reference the index to the help system, while <a href=
"http://localhost:12080/dist/resources/logo.gif">http://localhost:12080/dist/resources/logo.gif</a>
will load a JMRI logo graphic from the resources directory. "<code>/dist/web/</code>" and
"<code>/dist/xml/</code>" also work as prefixes.</p>
<p>Note that if a directory contains a file named <code>index.html</code> it will display the
contents of the index.html file instead of listing the directory contents.</p>
<h3><a id="json" href="JsonServlet.shtml">JSON Protocol</a>
</h3>
<!-- JsonServlet intro -->
<p>JMRI provides a JSON Protocol to access and manipulate for a number of JMRI-defined
entities. See the <a href="JsonServlet.shtml">JMRI JSON Protocol</a> for more
information.</p>
<h2 id="custom">Customizing Web Access</h2>
<p>If you create a directory <code>web</code> 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 <code>web</code> directory of the JMRI
distribution directory will override the default file used for that purpose. This provides
the custom content.</p>
<p>Two files <code>web/css/user.css</code> and <code>web/js/user.js</code> 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.</p>
<p>The standard web services use templates in the <code>web/servlet</code> 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.</p>
<p>A technical description about the Web Server Package <code>jmri.web.server</code> can be
found in the <a href=
"https://www.jmri.org/JavaDoc/doc/jmri/web/server/package-summary.html">Web Server
Javadoc</a>.</p>
<p>An overview of how Web Server works between JMRI and the web browser, using
web.servlet.panel as an example, can be found on <a href=
"PanelServlet.shtml#example">PanelServlet Help page</a>.</p>
<h2 id="redirection">Request Redirection</h2>
<p>Some requests are automatically redirected by one of the JMRI web services to ensure that
old bookmarks or software can still be used:</p>
<dl>
<dt>/index.html</dt>
<dd>Redirects to <code>/</code> since the static HTML root was replaced with a dynamic HTML
root.</dd>
<dt>/prefs/index.html</dt>
<dd>Redirects to <code>/</code> 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
<code>/prefs/index.html</code> returns an error.</dd>
<dt>/prefs/roster.xml</dt>
<dd>
Redirects to <code>/roster?format=xml</code> since users can opt to have the roster
outside the normal preferences file location, and the <a href=
"RosterServlet.shtml">roster servlet</a> can load the roster from any location.
</dd>
<dt>/web/operationsConductor.html</dt>
<dd>
Redirects to <code>/operations</code> since this page was replaced with the <a href=
"Operations.shtml">operations servlet</a>.
</dd>
<dt>/web/operationsManifest.html</dt>
<dd>
Redirects to <code>/operations</code> since this page was replaced with the <a href=
"Operations.shtml">operations servlet</a>.
</dd>
<dt>/web/operationsTrains.html</dt>
<dd>
Redirects to <code>/operations</code> since this page was replaced with the <a href=
"Operations.shtml">operations servlet</a>.
</dd>
<dt>/web/showPanel.html</dt>
<dd>Redirects to <code>/panel</code>.</dd>
</dl>
<h2 id="security">Security</h2>
<p>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.</p>
<!--#include virtual="/help/en/parts/Footer.shtml" -->
</div>
<!-- closes #mainContent-->
</div>
<!-- closes #mBody-->
<script src="/js/help.js"></script>
</body>
</html>