Serge NOEL
2452 lines
72 KiB
Plaintext
2452 lines
72 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<!-- Copyright ($Author$) 2009 -->
|
|
|
|
<title>JMRI: WiThrottle Protocol</title><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
|
|
<style type="text/css">
|
|
table.data, pre.code {
|
|
margin: initial;
|
|
margin-left: 12px;
|
|
width: fit-content;
|
|
padding-right: 1em;
|
|
}
|
|
pre.code {
|
|
color: darkred;
|
|
border: solid 0.5px grey;
|
|
margin-left: 30px;
|
|
padding: .2em;
|
|
}
|
|
.delimiter1 {
|
|
color: red;
|
|
font-weight: bold;
|
|
}
|
|
.delimiter2 {
|
|
color: #91bc7a;
|
|
font-weight: bold;
|
|
}
|
|
a.to-top {
|
|
float: right;
|
|
font-size: 0.8em;
|
|
font-variant: small-caps;
|
|
}
|
|
h3 {
|
|
font-style: italic;
|
|
background-color: #f0f0f0;
|
|
}
|
|
code {
|
|
font-size: 1.5em;
|
|
color: darkred;
|
|
}
|
|
p.command, p.exampleInfo {
|
|
margin-left: 30px;
|
|
}
|
|
table.data, table.data th, table.data td {
|
|
border: 0.5px solid black;
|
|
font-size: 90%;
|
|
margin-left: 30px;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<div id="mainContent" class="no-sidebar">
|
|
<h1 id="top">JMRI: WiThrottle Protocol</h1>
|
|
|
|
<p>This page describes the protocol provided by the <a href=
|
|
"https://jmri.org/JavaDoc/doc/jmri/jmrit/withrottle/package-summary.html">jmri.jmrit.withrottle</a>
|
|
package for controlling trains, turnouts, and more through JMRI via a TCP/IP socket.</p>
|
|
|
|
<p>On This page:</p>
|
|
<p style="margin-left: 50px;"><a href="#StringParsing">String Parsing</a><br>
|
|
<a href="#InitialConnection">Initial Connection (Server to Client)</a><br>
|
|
<a href="#ThrottleChangeNotification">Throttle Change Notification</a><br>
|
|
<a href="#OtherServertoClientMessages">Other Server to Client Messages</a><br>
|
|
<a href="#Commands">Commands (Client to Server)</a><br>
|
|
<a href="#ThrottleCommands">Throttle Commands</a><br>
|
|
<a href="#ConsistCommands">Decoder Assisted (Advanced) Consist Commands</a><br>
|
|
<a href="#TurnoutCommands">Turnout/Point Commands</a><br>
|
|
<a href="#RouteCommands">Route Commands</a><br>
|
|
<a href="#UnknownCommands">Unknown Commands</a><br>
|
|
<a href="#Observations">Observations</a><br>
|
|
</p>
|
|
|
|
<p>JMRI uses a fairly simple text-based client-server protocol over TCP/IP sockets. Throttles
|
|
(or other applications) can locate JMRI by sending a multi-cast DNS request, using
|
|
ZeroConf/Bonjour, for the address "_withrottle._tcp.local". JMRI won't always reply (it
|
|
depends on your operating system, firewall settings, and network environment), so your
|
|
application should also allow entering an IP address and port.</p>
|
|
|
|
<p>When you first open the connection, JMRI responds with a number of lines of text that
|
|
provide information about the JMRI instance to which you've connected. Your application then
|
|
sends commands to JMRI. Each of these commands is plain text, with a system-specific newline
|
|
character at the end (typically 0A hex). Similarly, lines sent back from JMRI are terminated
|
|
by a system-specific newline. A newline can be a linefeed (0A hex), carriage return (0D hex),
|
|
or a carriage return followed by a newline. (0D 0A hex) Clients and servers should accept any
|
|
newline sequence as a command termination.</p>
|
|
|
|
<p>You can see these messages by enabling DEBUG for the Logging Category "jmri.jmrit.withrottle"
|
|
, see <a href="../../../../html/apps/Debug.shtml">Debugging and System Logging</a>.
|
|
All messages (both directions) will be added to your JMRI System Console and the session.log file.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="StringParsing">String Parsing <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>JMRI commands and results are very often arrays of values, and sometimes arrays of arrays.
|
|
The array elements are separated by three-character delimiters.</p>
|
|
|
|
<p class="exampleInfo">For example, the following
|
|
roster entry contains two engines, and each engine has three values:</p>
|
|
|
|
<pre class="code">
|
|
RL2<span class="delimiter1">]\[</span>RGS 41<span class="delimiter2">}|{</span>41<span class=
|
|
"delimiter2">}|{</span>L<span class="delimiter1">]\[</span>Test Loco<span class=
|
|
"delimiter2">}|{</span>1234<span class="delimiter2">}|{</span>L
|
|
</pre>
|
|
<p class="exampleInfo">Here the delimiters are color-coded to make it easier to see the two different delimiters.
|
|
The <code class="delimiter1"><strong>]\[</strong></code> delimiter is used to divide the
|
|
different roster entries (there are two), while the <code class="delimiter2">}|{</code>
|
|
delimiter is used to divide the parts of each roster entry. The details are described in
|
|
sections below for each command and response.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="InitialConnection">Initial Connection (Server to Client) <a class="to-top" href=
|
|
"#top">^Top</a></h2>
|
|
|
|
<p>When you first open a socket to JMRI, you may get a response that will look something like
|
|
the following:</p>
|
|
|
|
<pre class="code">
|
|
VN2.0
|
|
RL1]\[SP 2101}|{2102}|{L
|
|
PPA2
|
|
PTT]\[Turnouts}|{Turnout]\[Closed}|{2]\[Thrown}|{4
|
|
PRT]\[Routes}|{Route]\[Active}|{2]\[Inactive}|{4
|
|
RCC0
|
|
PW12080
|
|
*10
|
|
</pre>
|
|
<p class="note">Some implementations will not send these initial lines until a command has
|
|
been sent by the client, typically the N or HU commands identifying the client device.</p>
|
|
|
|
<p>Each line contains information for parts of the WiThrottle service, as described below, so your application
|
|
can show things like engines, turnouts/Points, etc.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>WiThrottle Protocol Version</h3>
|
|
|
|
<p class="command"><strong>VN</strong>«versionNumber»</p>
|
|
|
|
<p>The first string, <code>VN2.0</code>, provides the version number of the WiThrottle
|
|
protocol. In this case the version number is 2.0. Clients use this to determine WiThrottle
|
|
syntax. EngineDriver now requires at least 2.0 to connect.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>VN</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Version Number</td>
|
|
<td>2.0</td>
|
|
<td>The DCC address of the locomotive</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>Roster List</h3>
|
|
|
|
<p class="command"><strong>RL0</strong> - for zero entries<br/>
|
|
<strong>RL</strong>«numberOfEntries»<strong>]\[</strong>«entryList»</p>
|
|
|
|
<p>The roster string always begins with <code>RL</code> (Roster List) followed by the number
|
|
of entries in the roster.</p>
|
|
|
|
<p class="exampleInfo">Here are three different examples of roster strings that might be
|
|
returned by JMRI:</p>
|
|
|
|
<pre class="code">
|
|
RL0
|
|
RL2]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L
|
|
RL3]\[D&RGW 341}|{3}|{S]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L
|
|
</pre>
|
|
<p class="exampleInfo">with zero, two, and three roster entries, respectively. Each roster entry contains three
|
|
pieces of information, always in the same order:</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RL</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Number of Entries</td>
|
|
<td><strong>2</strong></td>
|
|
<td>Number of entries that will follow on the line</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="6">Repeated<br/>for each<br/>entry</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Name</td>
|
|
<td>RGS 41</td>
|
|
<td>The name to show in your application</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Address</td>
|
|
<td>41</td>
|
|
<td>The DCC address of the locomotive</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Length</td>
|
|
<td>L</td>
|
|
<td>S or L to indicate if this is a Short or Long DCC address</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>Track Power</h3>
|
|
|
|
<p class="command"><strong>PPA</strong>«powerState»</p>
|
|
|
|
<p>Returns information about the current state of track power. This takes the following form:</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PPA</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Power State</td>
|
|
<td>1</td>
|
|
<td>0 = Off<br/>
|
|
1 = On<br/>
|
|
2 = Unknown</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3 id="TurnoutList">Turnout/Points List</h3>
|
|
|
|
<p>JMRI returns either zero, one, or two strings for this section.
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4 >Turnout/Points Captions</h4>
|
|
|
|
The first string provides the labels for the different turnout/point states. For example:</p>
|
|
|
|
<p class="command"><strong>PTT[\[</strong>«turnoutsTitle»<strong>}\{</strong>«turnoutTitle»[\[</strong>«stateTitle»<strong>}\{</strong>«stateValue»...</p>
|
|
|
|
<pre class="code">
|
|
PTT]\[Turnouts}|{Turnout]\[Closed}|{2]\[Thrown}|{4]\[Unknown}|{1]\[Inconsistent}|{8
|
|
</pre>
|
|
<p>This string contains an array with two elements, which provide the labels to use for each
|
|
turnout/point state (except for Unknown):</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PTT</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnouts/Points Title</td>
|
|
<td>Turnouts</td>
|
|
<td>Title for all Turnouts/Points<br/>Ignored by Engine Driver</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnout/Points Title</td>
|
|
<td>Turnout</td>
|
|
<td>Title for a Turnout/Point<br/>Ignored by Engine Driver</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="4">Repeated<br/>for each<br/>entry</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Caption</td>
|
|
<td>Closed</td>
|
|
<td>The string to show for the possible state of a turnout/point</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Value</td>
|
|
<td>2</td>
|
|
<td>The corresponding value for that turnout/point state</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Defined Turnout/Points List</h4>
|
|
|
|
<p>The second string appears when you have turnouts/points defined in JMRI, and contains the array
|
|
of defined turnouts/points, and will look something like this:</p>
|
|
|
|
<p class="command"><strong>PTL</strong> - for zero entries<br/>
|
|
<strong>PTL</strong>«entryList»</p>
|
|
|
|
<pre class="code">
|
|
PTL]\[LT12}|{Rico Station N}|{1]\[LT324}|{Rico Station S}|{2
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PTL</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="6">Repeated<br/>for each<br/>entry<br/>(if any)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>System Name</td>
|
|
<td>LT12</td>
|
|
<td>The system name used to define this turnout/point</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>User Name</td>
|
|
<td>Rico Station N</td>
|
|
<td>The user name entered into JMRI for this turnout/point</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>State</td>
|
|
<td>1</td>
|
|
<td>The current state of the turnout/point (see above)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3 id="RouteList">Route List</h3>
|
|
|
|
<p>Similar to turnouts/points, JMRI will reply with zero, one or two strings.
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Route Captions</h4>
|
|
|
|
<p class="command"><strong>PRT]\[</strong>«stateTitle»<strong>}\{</strong>«stateValue»...</p>
|
|
|
|
<p>The first string is likewise a list of labels for the route values.</p>
|
|
|
|
<p class="exampleInfo">For example:</p>
|
|
|
|
<pre class="code">
|
|
PRT]\[Routes}|{Route]\[Active}|{2]\[Inactive}|{4]\[Unknown}|{0]\[Inconsistent}|{8
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PRT</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="4">Repeated<br/>for each<br/>entry</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Caption</td>
|
|
<td>Closed</td>
|
|
<td>The string to show for the state of turnout</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Value</td>
|
|
<td>2</td>
|
|
<td>The corresponding value for the turnout state</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Defined Route List</h4>
|
|
|
|
<p class="command"><strong>PRL</strong> - for zero entries<br/>
|
|
<strong>PRL</strong>«entryList»</p>
|
|
|
|
<p>The second string contains an array of defined routes. For example:</p>
|
|
|
|
<pre class="code">
|
|
PRL]\[IR:AUTO:0001}|{Rico Main}|{2
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PRT</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="6">Repeated<br/>for each<br/>entry<br/>(if any)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>System Name</td>
|
|
<td>IR:AUTO:0001</td>
|
|
<td>The system name defined for this route. The name in this example was
|
|
auto-generated</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>User Name</td>
|
|
<td>Rico Main</td>
|
|
<td>The name user entered into JMRI for this route</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>State</td>
|
|
<td>2</td>
|
|
<td>1=Unknown, 2=Active, 4=Inactive, 8=Inconsistent</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>Consist (Multiple Unit) List</h3>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Number of Consist (Multiple Unit)</h4>
|
|
|
|
<p class="command"><strong>RCC</strong>«numberOfEntries»<br/>
|
|
<strong>RCL</strong>«numberOfEntries»</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RCC</strong></td>
|
|
<td>'RCC' and 'RCL' should be treated the same</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Number of Consists</td>
|
|
<td>2</td>
|
|
<td>The number of Consists (Multiple Units) defined </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Defined Consists (Multiple Units) List</h4>
|
|
|
|
<p class="command"><strong>RCD}|{</strong>«contsistAddress»<strong>}|{</strong>«contsistId»<strong>]\[</strong>«EntryList»</p>
|
|
|
|
<p>The consist (Multiple Unit) list is similar in concept to the roster list. <em>However, there is a
|
|
separate line for each consist entry.</em> Here is an example of a consist list that contains two
|
|
entries:</p>
|
|
|
|
<pre class="code">
|
|
RCC2
|
|
RCD}|{74(S)}|{74(S)]\[3374(L)}|{true]\[346(L)}|{true
|
|
RCD}|{123(S)}|{123(S)]\[3374(L)}|{true
|
|
</pre>
|
|
<p>The first line marks the start of the consist list, with the number of entries after the
|
|
"RCC". Subsequent lines start with "RCD}|{" and are followed by information about a single
|
|
consist entry.</p>
|
|
|
|
<p><em>For whatever reason, consist entries don't follow the same pattern as roster entries.</em> Here
|
|
is a summary of the Format for each consist entry (with spaces added for readability):</p>
|
|
|
|
<pre class="code">
|
|
RCD }|{ consistAddress }|{ consistId
|
|
Array: ]\[ loco DCC Address }|{ locoDirection
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RCD</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
|
|
<tr>
|
|
<td>Consist Address</td>
|
|
<td>74(S)</td>
|
|
<td>Consist Address</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
|
|
<tr>
|
|
<td>Consist Id</td>
|
|
<td>74(S)</td>
|
|
<td>Consist Id</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td></td>
|
|
<td rowspan="6">Repeated<br/>for each<br/>entry</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>loco DCC Address</td>
|
|
<td>3374(L)</td>
|
|
<td>The loco address. followed by "(S)" for short addresses<br/>
|
|
or "(L)" for long addresses</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>}\{</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>facing </td>
|
|
<td>true</td>
|
|
<td>The direction the locomotive is facing in the consist.<br/>
|
|
'true' = facing forward<br/>'false' = facing backward/reverse</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>Addresses have the format <em>address</em>(S/L). For example, 3374(L) is a long address
|
|
and 74(S) is a short addresses.</p>
|
|
|
|
<p class="exampleInfo">In the first example above, here is the information about the first consist entry:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Data</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>74(S)</td>
|
|
<td>Consist has short DCC address 74</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>74(S)</td>
|
|
<td>The ID of the consist</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>3374(L)}|{true</td>
|
|
<td>Loco with long address 3374 in the forward direction</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>346(L)}|{true</td>
|
|
<td>Loco with long address 346 in the forward direction</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>JMRI Web Port</h3>
|
|
|
|
<p class="command"><strong>WP</strong>«port»</p>
|
|
|
|
<p>The final string from the initial reply provides the port set for the JMRI web server.</p>
|
|
|
|
<p class="exampleInfo">For example:</p>
|
|
|
|
<pre class="code">
|
|
PW12080
|
|
</pre>
|
|
<p class="exampleInfo">This example indicates that the web server port is set to 12080.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PW</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Port</td>
|
|
<td>12080</td>
|
|
<td>The web server port</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="ThrottleChangeNotification">Throttle Change Notification <a class="to-top" href=
|
|
"#top">^Top</a></h2>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»«notificationType»«locoId»<strong><;></strong>«propertyNotification»
|
|
</p>
|
|
|
|
<p>There are cases where throttle property changes in JMRI cause a message to be sent. These
|
|
messages are not a response to a command, but rather are sent at any time (from the
|
|
perspective of your WiThrottle protocol client).<p>
|
|
|
|
</p>For example, if you have a Throttle window
|
|
open in JMRI and you turn on the headlight (F0), a property change message will be sent with
|
|
the function information:</p>
|
|
|
|
<pre class="code">
|
|
M0AL341<;>F10
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>M</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Throttle Id</td>
|
|
<td>0</td>
|
|
<td>The ID of the throttle.<br/>
|
|
Valid Throttles:<br/>
|
|
"0"-"9" or <br/>
|
|
"T","S" or "G". T,S,G translate to 0,1,2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Notification Type</td>
|
|
<td>A</td>
|
|
<td>Valid notification types: <br/>
|
|
+ = Loco added to Throttle <br/>
|
|
- = Loco removed from Throttle<br/>
|
|
L = List of loco functions<br/>
|
|
A = Action. The following characters provide more details<br/>
|
|
S = loco in use, prompt for steal</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Loco Id</td>
|
|
<td>L341</td>
|
|
<td>The DCC address of the locomotive, with 'L' for long or 'S' for short address.<br>
|
|
or "*" for all locos (consist) currently on the throttle.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Property Notification</td>
|
|
<td>F10</td>
|
|
<td>The property change notification, using the format described below.<br/>
|
|
If the notificationType is "+" or "-" this will be empty.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>All property change messages begin with <strong>M0A</strong> (where '0' could be a different throttle
|
|
character) and then the DCC address of the locomotive. The part after the <;> separator
|
|
uses the format described below.</p>
|
|
|
|
<p>Here is a list of property notifications that can be sent:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Property Change Type</td>
|
|
<td>F</td>
|
|
<td>The property that changed.<br/>
|
|
Valid properties are:<br/>
|
|
'F' = Function state change<br/>
|
|
'S' = speed change<br/>
|
|
'R' = direction change<br/>
|
|
's' = Speed step mode<br/>
|
|
</td>
|
|
|
|
<tr>
|
|
<td>Property Change Value</td>
|
|
<td>10</td>
|
|
<td>The property that changed.<br/>
|
|
required parameters are:<br/>
|
|
For 'F' = «functionState»«functionNumber» <br/>
|
|
functionState - '0'=Off, '1'=On<br/>
|
|
functionNumber - '0'-'31'<br/>
|
|
For 'V' = «speed» - 0 and 126 inclusive<br/>
|
|
For 'R' = «direction» - '0'=Reverse and '1'=Forward<br/>
|
|
For 's' = «stepMode» - '1'=128step, '2'=28step, '4'=27step or '8'=14step<br/>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br/>
|
|
<pre class="code">
|
|
M0AL341<;>F10
|
|
M0AL341<;>V23
|
|
M0AL341<;>R1
|
|
M0AL341<;>s1
|
|
</pre>
|
|
<br/>
|
|
|
|
<p>Also see <a href="#MultiThrottleElements">MultiThrottle Elements</a> for more information.</p>
|
|
|
|
<p>The <strong>M</strong> notification is also used to send the list of functions
|
|
for a loco on a throttle from the server to the client.</p>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>L</strong>>«locoId»<strong><;></strong>«functionList»
|
|
</p>
|
|
|
|
<br/>
|
|
<pre class="code">
|
|
M0LL7407<;>]\[Lights]\[Bell]\[Whistle]\[Brake Squeal]\[Chuff On-Off]\[Firebox Open-Close]\[
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>M</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Throttle Id</td>
|
|
<td>0</td>
|
|
<td>The ID of the throttle.<br/>
|
|
Valid Throttles:<br/>
|
|
"0"-"9" or <br/>
|
|
"T","S" or "G". T,S,G translate to 0,1,2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Notification Type</td>
|
|
<td>L</td>
|
|
<td>Notification type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Loco Id</td>
|
|
<td>L341</td>
|
|
<td>The DCC address of the locomotive, with 'L' for long or 'S' for short address</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>]\[</strong></td>
|
|
<td colspan="2">Repeated<br/>for each<br/>function</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Function Label</td>
|
|
<td>Lights</td>
|
|
<td>Label for the function
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="OtherServertoClientMessages">Other Server to Client Messages <a class="to-top" href=
|
|
"#top">^Top</a></h2>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>Fast Clock Message</h3>
|
|
|
|
<p class="command">
|
|
<strong>PFT</strong>«seconds»<strong><;></strong>«fastTimeRatio»
|
|
</p>
|
|
|
|
<p>The 'PFT' command is used to synchronize the fast clock time. It is sent from the server
|
|
when time or rate change, indicating the "now" time and the current time ratio (or 0 when
|
|
clock stopped). Examples include:</p>
|
|
|
|
<pre class="code">
|
|
PFT65871<;>4
|
|
PFT1550686525<;>4.0
|
|
PFT1550681224<;>0.0
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PFT</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>seconds</td>
|
|
<td>37425</td>
|
|
<td>An integer number of seconds since 12:00 midnight, January 1st, 1970 fast clock time
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>fastTimeRatio</td>
|
|
<td>4.0</td>
|
|
<td>the current fast time ratio. It may be an integer value (4) or a floating point value (4.0).
|
|
If this value is 0 (or 0.0), the clock is stopped.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The first number is an integer number of seconds since 12:00 midnight, January 1st, 1970
|
|
fast clock time. This zero date is very close to the Unix time epoch, which is 12:00
|
|
midnight, January 1st, 1970 UTC, only differing in the time zone offset, where applicable. In
|
|
fact, this makes it easy to convert this value using the standard time libraries, as long as
|
|
any time zone conversions are omitted. JMRI sends a value based on the system date when the
|
|
fast clock was started, so it will return a value near the calendar date. </p>
|
|
|
|
<p>Since the JMRI fast
|
|
clock does not really support calendar dates, only the hour, minute and second are useful.
|
|
The Digitrax LNWI returns values within the range 0-86400, which translates to times on
|
|
January 1st, 1970, when the day, month and year are calculated.</p>
|
|
|
|
<p>To give an example: A JMRI instance started on Dec 13, 2020 with a fast clock time set to
|
|
10:23:45 am will return 1607855025, which can be converted back to hours, minutes and seconds
|
|
by "modulo dividing" by 86400 (number of seconds in a day) and calculating further as
|
|
follows:<br>
|
|
1607855025 mod 86400 = 37425 seconds since midnight.<br>
|
|
37425 seconds since midnight = 10 hours 1425 seconds since midnight = 10 hours 23 minutes 45
|
|
seconds since midnight = 10:23:45 am.</p>
|
|
|
|
<p>The second number is the current fast time ratio. It may be an integer value (4) or a
|
|
floating point value (4.0). If this value is 0 (or 0.0), the clock is stopped.<br>
|
|
</p>
|
|
|
|
<p>Updates are sent on each change in time or rate, and when clock stopped or started, so expect
|
|
one message every fast clock minute.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3 id="AlertandInfoMessage">Alert and Info Message</h3>
|
|
|
|
<p class="command">
|
|
<strong>HM</strong>«messageText»<br/>
|
|
<strong>Hm</strong>«messageText»
|
|
</p>
|
|
|
|
<p>The server can send a message string that the client can display. These cannot have
|
|
newlines in message. Two types:<br>
|
|
Alert message: 'HM' + message text. Normally used to return errors to be shown to user.<br>
|
|
Info message: 'Hm' + message text. Same as HM, but informational only.</p>
|
|
|
|
<p class="exampleInfo">Example returned after client requests invalid address (say
|
|
<code>M0+L23<;>L23</code>) the response is:</p>
|
|
|
|
<pre class="code">
|
|
HMJMRI: address 'L23' not allowed as Long
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>HM<br/>Hm</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Message</td>
|
|
<td>HMJMRI: address 'L23' not allowed as Long</td>
|
|
<td>Message</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>Server Type Message</h3>
|
|
|
|
<p class="command">
|
|
<strong>HT</strong>«serverType»<br/>
|
|
<strong>Ht</strong>«serverDescription»
|
|
</p>
|
|
|
|
<p>The server can send a "type" to identify itself to clients, useful to enable specific
|
|
behaviors. Two types:<br>
|
|
'HT' + type. Known types: 'Digitrax', 'MRC', 'JMRI'<br>
|
|
'Ht' + description. Longer informational text string, cannot contain newlines</p>
|
|
|
|
<pre class="code">
|
|
HTJMRI
|
|
HtJMRI v4.19.8 My JMRI Railroad
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>HT</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Server Type</td>
|
|
<td>JMRI</td>
|
|
<td>Server Type</td>
|
|
</tr>
|
|
</table>
|
|
<br/>
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>Ht</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Server Type</td>
|
|
<td>JMRI v4.19.8 My JMRI Railroad</td>
|
|
<td>Server Type</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="Commands">Commands (Client to Server) <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>Once you've established a connection as outlined above, you can start sending commands to
|
|
JMRI. The first letter of each command is interpreted by the <a href=
|
|
"https://github.com/JMRI/JMRI/blob/master/java/src/jmri/jmrit/withrottle/DeviceServer.java">DeviceServer</a>
|
|
class to determine where to send the rest of the command. Here are the letters currently
|
|
supported:</p>
|
|
|
|
<ul>
|
|
<li>'M' sends a command to a "multi" throttle</li>
|
|
|
|
<li>'D' sends a hex packet to the command station</li>
|
|
|
|
<li>'*' sends a heartbeat, or sets heartbeat on or off</li>
|
|
|
|
<li>'C' is not used anymore and forwards to the throttle controller.</li>
|
|
|
|
<li>'N' sets the device name</li>
|
|
|
|
<li>'H' sets the device ID.</li>
|
|
|
|
<li>'P' sends a panel command</li>
|
|
|
|
<li>'R' sends a roster command</li>
|
|
|
|
<li>'Q' indicates the device has quit, close its connection and release any resources.</li>
|
|
|
|
<li>'T' sends a throttle command, <em>deprecated, use 'M'</em></li>
|
|
|
|
<li>'S' sends a throttle command to a second throttle, <em>deprecated, use 'M'</em></li>
|
|
|
|
</ul>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'H' Hardware Information</h3>
|
|
|
|
<p class="command">
|
|
<strong>HU</strong>«clientDeviceId»
|
|
</p>
|
|
|
|
<p>Sets the device ID for the client. This could, for example, be the MAC address of the
|
|
caller, as a string. The syntax is <code>HU<em>identifier</em></code>, where
|
|
<em>identifier</em> is different for each connected device.</p>
|
|
|
|
<p><em>This needs to be unique for each device connected to the server.</em>
|
|
It is used to prevent duplicate connections from the same
|
|
client. Engine Driver and WiThrottle app use a generated unique identifier.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'N' Device Name</h3>
|
|
|
|
<p class="command">
|
|
<strong>N</strong>«clientDeviceName»
|
|
</p>
|
|
|
|
<p>Sets the name that will appear in the WiThrottle window. In Engine Driver, this is the
|
|
throttle name that you can set. The syntax is <code>N<em>name</em></code>, where
|
|
<em>name</em> can be any text, except for a newline, as the newline terminates the command.
|
|
For example:</p>
|
|
|
|
<pre class="code">
|
|
NJohn's Throttle
|
|
</pre>
|
|
|
|
<p class="command"><strong>Reply:</strong> <code>*</code><em>StopSeconds</em></p>
|
|
|
|
<pre class="code">
|
|
*10
|
|
</pre>
|
|
<p>The number after '*' indicates how often your throttle will need to send a command or
|
|
heartbeat (0 means a heartbeat is not required). JMRI will send an EStop to the locomotive if
|
|
it hasn't received a command or heartbeat within the number of seconds provided.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'*' Heartbeat</h3>
|
|
|
|
<p class="command">
|
|
<strong>*</strong><br/>
|
|
<strong>*+</strong><br/>
|
|
<strong>*-</strong><br/>
|
|
</p>
|
|
|
|
<p>There are three versions of this command:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<td>Command</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>*</td>
|
|
<td>Send heartbeat</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>*+</td>
|
|
<td>Turn heartbeat monitoring on</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>*-</td>
|
|
<td>Turn heartbeat monitoring off</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The idea of the heartbeat is that JMRI will issue an emergency stop if it has not received
|
|
any commands from your throttle within the heartbeat period. When you set your throttle name,
|
|
using the N command, JMRI returns the emergency stop delay, in seconds, but it doesn't turn
|
|
heartbeat monitoring on until you explicitly tell it to do so. Once you've turned it on, your
|
|
throttle will need to ensure it sends periodic heartbeat commands (or any other command) to
|
|
keep your engine(s) alive.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>M - MultiThrottle Controller</h3>
|
|
|
|
<p>The 'M' command is for a "multi" throttle, and is handled by the <a href=
|
|
"https://github.com/JMRI/JMRI/blob/master/java/src/jmri/jmrit/withrottle/ThrottleController.java">
|
|
ThrottleController</a> class.</p>
|
|
|
|
<p>The 'M' multithrottle can handle more than one locomotive. Engine Driver uses this
|
|
feature, for example, to make it super easy to create a consist on the fly with any set of
|
|
engines (without using DCC consisting). You can have one or more multithrottles, and each
|
|
multithrottle can have more than one locomotives attached to it. The first character after
|
|
the 'M' is used as a key for the instance of MultiThrottle to use. Engine Driver uses '0'
|
|
through '6' as its keys for multithrottle instances. However, you can use other characters
|
|
for the key, '0' is used in the examples below.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4 id="MultiThrottleElements">MultiThrottle Elements</h4>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»«command»«locoId»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
|
|
<p>The command string after the first two characters is passed to the MultiThrottle for
|
|
further processing. As in other cases, the commands are arrays, where the "<;>" string
|
|
is used as the delimiter. For example:</p>
|
|
|
|
<pre class="code">
|
|
M0+L341<;>ED&RGW 341
|
|
</pre>
|
|
|
|
<p class="exampleInfo">This example contains the array elements "+L341" and "ED&RGW 341".</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>M</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Throttle Id</td>
|
|
<td>0</td>
|
|
<td>The ID of the throttle.<br/>
|
|
Valid Throttles:<br/>
|
|
"0"-"9" or <br/>
|
|
"T","S" or "G". T,S,G translate to 0,1,2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Command</td>
|
|
<td>+</td>
|
|
<td>'A' = <a href="#locoAction">Action / Throttle Command</a>. The following characters provide more details<br/>
|
|
'+' = <a href="#addLoco">Add a locomotive</a> to the throttle<br/>
|
|
'-' = <a href="#removeLoco">Remove a locomotive</a> from the throttle<br/>
|
|
'S' = <a href="#stealLoco">Request steal locomotive</a> (see more below)
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Loco Id</td>
|
|
<td>L341</td>
|
|
<td>The DCC address of the locomotive, with 'L' for long or 'S' for short address.<br>
|
|
or "*" for all locos (consist) currently on the throttle.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Additional Info</td>
|
|
<td>ED&RGW 341</td>
|
|
<td>Additional Information for the command. See Below for each command</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>The first character of the first element describes the MultiThrottle command, and is one
|
|
of the following:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>3rd Char</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>A</td>
|
|
<td>Action / Throttle Command. The following characters provide more details</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>+</td>
|
|
<td>Add a locomotive to the throttle</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-</td>
|
|
<td>Remove a locomotive from the throttle</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>S</td>
|
|
<td>Request steal locomotive (see more below)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Each of these operations is described in sections below.</p>
|
|
|
|
<p>The second element will be passed onto the ThrottleController instance for further
|
|
processing, and the details are described below in the <a href=
|
|
"#ThrottleCommands">Actions / Throttle Commands</a> section.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h5 id="addloco">'+' -- Add Locomotive</h5>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>>«locoId»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>The following command is a request to add a new locomotive to the multithrottle:</p>
|
|
|
|
<pre class="code">
|
|
M0+S3<;>ED&RGW 341
|
|
</pre>
|
|
<p class="exampleInfo">In this example, the first element is "+S3" has the '+' to indicate that this is a request to add a
|
|
locomotive to the multithrottle. The rest of the string is another key, formatted like an
|
|
address (e.g., "S3" or "L341"), which will be used in future references by MultiThrottle
|
|
commands.</p>
|
|
|
|
<p class="exampleInfo">The second element is the actual address to select, using either the address directly
|
|
("S79" or "L3002") or by referencing a roster entry using the "E" command (such as
|
|
"ED&RGW 341").</p>
|
|
|
|
<p>The key address MUST match the address chosen via the third element of the string (after
|
|
the <;>). Any mismatch results in undefined behavior (and is known to vary between
|
|
implementations).</p>
|
|
|
|
<p>The reply from this command is quite verbose, and contains details about this locomotive
|
|
as known by JMRI. If the engine number is in JMRI's roster, it will return information like
|
|
the following:</p>
|
|
|
|
<pre class="code">
|
|
M0+L41<;>
|
|
M0LL41<;>]\[Headlight]\[Bell]\[Whistle]\[Short Whistle]\[Steam Release]\[FX5 Light]\[FX6 Light]\[Dimmer]\[Mute]\[Water Stop]\[Injectors]\[Brake Squeal]\[Coupler]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[]\[
|
|
M0AL41<;>F00
|
|
M0AL41<;>F01
|
|
M0AL41<;>F02
|
|
...
|
|
M0AL41<;>F027
|
|
M0AL41<;>F028
|
|
M0AL41<;>V0
|
|
M0AL41<;>R1
|
|
M0AL41<;>s1
|
|
</pre>
|
|
|
|
<p>If, on the other hand, JMRI does not have the engine number in it's roster, it returns
|
|
information like the following:</p>
|
|
|
|
<pre class="code">
|
|
M0+L341<;>
|
|
M0AL341<;>F00
|
|
M0AL341<;>F01
|
|
...
|
|
M0AL341<;>F027
|
|
M0AL341<;>F028
|
|
M0AL341<;>V0
|
|
M0AL341<;>R1
|
|
M0AL341<;>s1
|
|
</pre>
|
|
|
|
<p class="note">the examples above are all replies from the multithrottle.</p>
|
|
|
|
<p>The reply consists of the following sections:</p>
|
|
|
|
<ul>
|
|
<li>Function labels</li>
|
|
|
|
<li>Function states (pressed or released)</li>
|
|
|
|
<li>Current speed</li>
|
|
|
|
<li>Current direction</li>
|
|
|
|
<li>Current speed step mode</li>
|
|
</ul>
|
|
|
|
<p>For all except the function labels, see the appropriate throttle commands, such as 'V'
|
|
below, for details.</p>
|
|
|
|
<p>The function labels are an ordered array of strings, with ]\[ used as the array delimiter.
|
|
So in the example above, F0 is called Headlight, F1 Bell, etc. Note that, unlike with other
|
|
arrays, the array delimiter appears at the start and end of the array, as well as between
|
|
elements.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h5 id="removeLoco">'-' -- Remove Locomotive</h5>
|
|
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>-</strong>>«locoId»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>The '-' command removes an engine from a multithrottle. Engine Driver, for example, sends
|
|
the following command to release all locomotives from the 'T' throttle:</p>
|
|
|
|
<pre class="code">
|
|
M0-*<;>r
|
|
</pre>
|
|
<p>The first element after the '-' character is the key of the locomotive to remove, or '*'
|
|
to remove <em>all</em> locomotives from the multithrottle instance. The multithrottle
|
|
instance will loop through all of it's throttle instances and send the 'r' command to each
|
|
one. The 'r' command is a release command.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h5 id="locoAction">'A' -- Locomotive Action</h5>
|
|
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>>«locoId»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>This command passes the second element in the array to either a specific throttle (if you
|
|
specify a key), or to all of the throttles in the multithrottle instance if you provide '*'
|
|
as the key. For example:</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>qR
|
|
</pre>
|
|
<p class="exampleInfo">The characters after the 'A' in the first element are the key to a locomotive in the
|
|
multithrottle, or '*' to send the command to all of the locomotives. In the example above,
|
|
the client is sending a "qR" command to all of the locomotives on the '0' throttle.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="ThrottleCommands">Actions / Throttle Commands <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>This section describes throttle commands, which are the second element of 'Mx' commands
|
|
(as described above). After the command prefix, the next letter is one of the following:</p>
|
|
|
|
<ul>
|
|
<li>'C' consist</li>
|
|
<li>'c' consist lead from roster entry</li>
|
|
<li>'d' dispatch.</li>
|
|
<li>'E' sets an address from a roster entry. Format E<em>ID</em>.</li>
|
|
<li>'F' function key. Format F<em>{0|1}</em><em>Function</em>.</li>
|
|
<li>'f' force function. Format f<em>{0|1}</em><em>Function</em>.</li>
|
|
<li>'I' idle, which sets the speed to 0</li>
|
|
<li>'L' sets a long DCC address.</li>
|
|
<li>'m' momentary. Format m<em>{0|1}</em><em>Function</em>.</li>
|
|
<li>'q' ask for current settings, such as speed or direction</li>
|
|
<li>'Q' quit</li>
|
|
<li>'R' set direction. Format R<em>{0|1}</em>.</li>
|
|
<li>'r' release.</li>
|
|
<li>'S' sets a short DCC address.</li>
|
|
<li>'s' set speed step mode</li>
|
|
<li>'V' sets the speed (velocity). Format V<em>speed.</em></li>
|
|
<li>'X' emergency stop.</li>
|
|
</ul>
|
|
|
|
<p>Each of the commands is described in a section below when it takes additional information.
|
|
Some commands, such as 'X' require no additional information.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'C' and 'c' - Set lead loco for consist</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>C</strong>«leadLocoAddress»
|
|
</p>
|
|
|
|
<p>These two commands both allow you to set the lead loco to which function commands will be
|
|
sent. This is used in cases where you're not using CV21 and CV22 to determine how locos in an
|
|
advanced consist should respond to functions.</p>
|
|
|
|
<pre class="code">
|
|
M0AL341<;>CL346
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>C</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Lead Loco Address</td>
|
|
<td>L346</td>
|
|
<td>The DCC address of the lead loco, with 'L' for long or 'S' for short address</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3 id="dispatchLoco">'d' - Dispatch, and 'r' - Release</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>d</strong><br/>
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>r</strong>
|
|
</p>
|
|
|
|
<p>For most DCC systems, these are the same thing; if in doubt, use release. Device server
|
|
will then send a remove address command to the mobile device.</p>
|
|
|
|
<pre class="code">
|
|
M0-L341<;>r
|
|
M0-L341<;>d
|
|
</pre>
|
|
<p>You can also release or dispatch all of the locomotives under control of the current
|
|
throttle:</p>
|
|
|
|
<pre class="code">
|
|
M0-*<;>r
|
|
</pre>
|
|
<p>After sending this command, the WiThrottle Server will typically reply with a removed
|
|
message</p>
|
|
|
|
<pre class="code">
|
|
M0-L341<;>
|
|
</pre>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'F' - Function</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>F</strong>«functionState»«functionNumber»
|
|
</p>
|
|
|
|
<p>Function keys have two states. Either they're pushed down (when you're pushing with your
|
|
finger), or they're up (when you release them). <p>
|
|
|
|
</p>Therefore, when you send function commands,
|
|
you'll send a pair--first when the button is pushed down and second when the button is
|
|
released. Here is an example of a pair of messages (usually with some time in between
|
|
them):</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>F112
|
|
M0A*<;>F012
|
|
</pre>
|
|
|
|
<p>The first command is when you push F12, and the second is when you release the F12 button.
|
|
Although this example sends to all of the 'T' throttles, you can send a function to just one
|
|
by providing the key you used when you added an engine.</p>
|
|
|
|
<p class="note">Some functions, such as whistle, remain active only while you have the button
|
|
down, while others, like lights, are toggle. In both cases, your code should send both the
|
|
push (1) and release (0) and JMRI will map that into the correct DCC command or commands, as
|
|
appropriate.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>F</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Function State</td>
|
|
<td>0</td>
|
|
<td>'0'= Push,<br/>'1'= Release
|
|
</td>
|
|
|
|
<tr>
|
|
<td>Function Number</td>
|
|
<td>10</td>
|
|
<td>'0'-'31'<br/>
|
|
Do not use leading zeros for the function numbers
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'f' - Force Function</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>f</strong>«functionState»«functionNumber»
|
|
</p>
|
|
|
|
<p>This command will set the function state regardless of the state before this command. For
|
|
example:</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>f112
|
|
</pre>
|
|
<p class="command">Will activate Function 12 if it was off before and will keep F12 active if it was on
|
|
before. If Function 12 is a momentary function, it will still be activated by this command
|
|
and stay active.</p>
|
|
|
|
<p>The server will respond with a property change notification only if this command changes
|
|
the function state.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>f</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Function State</td>
|
|
<td>0</td>
|
|
<td>'0'=Off, '1'=On
|
|
</td>
|
|
|
|
<tr>
|
|
<td>Function Number</td>
|
|
<td>10</td>
|
|
<td>'0'-'31'<br/>
|
|
Do not use leading zeros for the function numbers
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'m' momentary: Set Function to momentary or locking</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>f</strong>«functionNumber»
|
|
</p>
|
|
|
|
<p>A function can either be momentary, i.e. active as long as the function key is pushed, or
|
|
locking, i.e. active until the function key is pushed a second time. By default, JMRI uses
|
|
the roster information to determine whether a function is momentary or locking for each
|
|
loco.</p>
|
|
|
|
<p>This command allows a wiThrottle client to override the setting from the roster. For
|
|
example:</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>m112
|
|
</pre>
|
|
<p>will set function <strong>12</strong> to be momentary from now on, and</p>
|
|
|
|
|
|
<pre class="code">
|
|
M0A*<;>m012
|
|
</pre>
|
|
<p>will set function 12 to be locking from now on. Actually, any value other than '1' will
|
|
set the function to locking. Although this example sets/resets the function to momentary on
|
|
all 'T' throttles, you can set this individually on a per-engine basis by providing the key
|
|
you used when you added an engine.</p>
|
|
|
|
<p class="note">The JMRI global wiThrottle preference "F2 always momentary" will override this
|
|
setting for F2.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>m</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Function State</td>
|
|
<td>0</td>
|
|
<td>'0'=latching, '1'=momentary
|
|
</td>
|
|
|
|
<tr>
|
|
<td>Function Number</td>
|
|
<td>10</td>
|
|
<td>'0'-'31'<br/>
|
|
Do not use leading zeros for the function numbers
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'R' - Set Direction</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong>R</strong>«direction»
|
|
</p>
|
|
|
|
<p>Used to change between forward and reverse.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>R</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Direction</td>
|
|
<td>0</td>
|
|
<td>'0'=Reverse, <br/>
|
|
'1'=Forward<br/>
|
|
Actually, any value other than '0' is considered forward
|
|
</td>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'V' - Set Speed</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>V</strong>«speed»
|
|
</p>
|
|
|
|
<p>Set the speed to a value between 0 and 126. The format looks something like this:</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>V30
|
|
</pre>
|
|
<p>If the value received from the WiThrottle Server is negative (e.g., during the
|
|
initialization information when an address is selected), that indicates the address is in
|
|
Emergency Stop mode.</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>V</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Speed</td>
|
|
<td>30</td>
|
|
<td>0 to 126 inclusive
|
|
</td>
|
|
</table>
|
|
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'S' - Steal Locomotive</h3>
|
|
|
|
<p>Requests stealing a locomotive. This is a feature that is of most interest when working
|
|
with Digitrax command stations and allows the WiThrottle protocol to support the same steal
|
|
scenario supported by Digitrax throttles.</p>
|
|
|
|
<p>Stealing a loco takes a few steps. Here is the sequence</p>
|
|
|
|
<ul>
|
|
<li>Send a normal (MT+) command to acquire a locomotive</li>
|
|
|
|
<li>WiThrottle Server sends back a steal (MTS) reply, indicating that a steal request is
|
|
required</li>
|
|
|
|
<li>Send a steal request (MTS) for the locomotive</li>
|
|
</ul>
|
|
|
|
<p class="exampleInfo">Here is an example</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>From WiThrottle Server (JMRI)</th>
|
|
<th>From Client</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
</td>
|
|
<td>MT+L341<;>L341</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>MTSL341<;>L341</td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
</td>
|
|
<td>MTSL341<;>L341</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> Steal requires JMRI 4.10 or later</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'q' - Query Speed or Direction</h3>
|
|
|
|
<p class="command">
|
|
<strong>M</strong>«throttleId»<strong>A</strong>«locoId»<strong><;>q</strong>«whatToQuery»
|
|
</p>
|
|
|
|
<p>Used to request the current values of speed (V) or direction (R)</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>q</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>What to Query</td>
|
|
<td>V</td>
|
|
<td>'V' = Query current speed<br/>
|
|
'R' = Query current direction
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p class="exampleInfo">Example requesting current speed and direction for all locos on throttle '0':</p>
|
|
|
|
<pre class="code">
|
|
M0A*<;>qV
|
|
M0A*<;>qR
|
|
</pre>
|
|
<p>The server responds with the Throttle Change Notification as described <a href=
|
|
"#ThrottleChangeNotification">[here]</a>. Example responses for address 3(S) on throttle
|
|
'0':</p>
|
|
|
|
<pre class="code">
|
|
M0AS3<;>V25
|
|
M0AS3<;>R1
|
|
</pre>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="ConsistCommands">Advanced Consist (Multiple Unit) Commands <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p class="command">
|
|
<strong>RC</strong>«command»<strong><;></strong>«consistAddress»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>The commands in this section are used to work with NMRA Decoder Assisted (Advanced) Consists (MUs). Consists that work by altering CV19 on the decoder. </p>
|
|
|
|
<p>All the advanced consist commands start with "RC", which stands for Roster Consist.</p>
|
|
|
|
<ul>
|
|
<li>'P' - Change order of locos in the consist (multiple unit)</li>
|
|
|
|
<li>'R' - Delete (remove) a consist (multiple unit)</li>
|
|
|
|
<li>'+' - Add loco to a consist (multiple unit) and/or set the relative direction</li>
|
|
|
|
<li>'-' - Remove a loco from the consist (multiple unit)</li>
|
|
|
|
<li>'F' - Program CV21 and CV22 function behavior</li>
|
|
</ul>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'+' Add to Consist</h3>
|
|
|
|
<p class="command">
|
|
<strong>RC+<;></strong>«consistAddress»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>Either creates a consist (multiple unit) or adds a locomotive to an existing consist (multiple unit). As an example, let's
|
|
say that consist (multiple unit) S74 does <strong>not</strong> exist. The following commands will create a
|
|
consist (multiple unit) with address "S74" and name "My consist" with two locos:</p>
|
|
|
|
<pre class="code">
|
|
RC+<;>S74<;>My consist<:>L341<;>true
|
|
RC+<;>S74<;>My consist<:>L342<;>true
|
|
</pre>
|
|
<p>The parts of this command are as follows:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RC+</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Consist Name</td>
|
|
<td>My Consist</td>
|
|
<td>The name for the consist (multiple unit)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><:></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Consist Address</td>
|
|
<td>S74</td>
|
|
<td>The DCC address of the consist (multiple unit)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Loco Address</td>
|
|
<td>L341</td>
|
|
<td>DCC address of the loco to add to the consist (multiple unit)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Direction</td>
|
|
<td>true</td>
|
|
<td>Direction is normal (false for reversed)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'-' - Remove Loco from Consist (multiple unit)</h3>
|
|
|
|
<p class="command">
|
|
<strong>RC-<;></strong>«consistAddress»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>Removes a single locomotive from the consist.</p>
|
|
|
|
|
|
<p class="exampleInfo">For example:</p>
|
|
|
|
<pre class="code">
|
|
RC-<;>S74<:>L341
|
|
</pre>
|
|
|
|
<p class="exampleInfo">This example removes DCC address L341 from the consist with the DCC address of S74.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RC-</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Consist Address</td>
|
|
<td>S74</td>
|
|
<td>The DCC address of the consist (multiple unit)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><:></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Loco Address</td>
|
|
<td>L341</td>
|
|
<td>DCC address of the loco to remove to the consist (multiple unit)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'P' Change Position in Consist</h3>
|
|
|
|
<p class="command">
|
|
<strong>RCP<;></strong>«consistAddress»<strong><;></strong>«additionalInfo»
|
|
</p>
|
|
|
|
<p>This command is used to change the order of locos in a consist. These commands have the
|
|
following format:</p>
|
|
|
|
<pre class="code">
|
|
RCP<;>consistAddress<:>leadLoco<;>nextLoco<;>...* ...<;>nextLoco<;>trailLoco
|
|
</pre>
|
|
<p class="exampleInfo">Notice that this has no direction information--it just has a list of locomotive DCC
|
|
addresses. For example:</p>
|
|
|
|
<pre class="code">
|
|
RCP<;>S74<:>L346<;>L3374
|
|
</pre>
|
|
<p class="exampleInfo">This example sets the position of the locos in the consist with the DCC address of S74 so
|
|
that DCC L346 is the lead and L3374 is the trailing loco.</p>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RCP</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Consist Address</td>
|
|
<td>S74</td>
|
|
<td>The DCC address of the consist (multiple unit)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
<td rowspan="2">Repeated<br/>for each<br/>loco</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Loco Address</td>
|
|
<td>L341</td>
|
|
<td>DCC address of the loco to place to the consist (multiple unit), in order starting with the lead loco</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h3>'R' Remove Consist</h3>
|
|
|
|
<p class="command">
|
|
<strong>RCR<;></strong>«consistAddress»
|
|
</p>
|
|
|
|
<p>Deletes a consist.</p>
|
|
|
|
|
|
<p class="exampleInfo">For example, the following command deletes the consist with DCC address
|
|
S74.</p>
|
|
|
|
<pre class="code">
|
|
RCR<;>S74
|
|
</pre>
|
|
|
|
<p>Command Segments:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>RCR</strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong><;></strong></td>
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Consist Address</td>
|
|
<td>S74</td>
|
|
<td>The DCC address of the consist (multiple unit) tp remove</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="TurnoutCommands">Turnout/Point Commands <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>There are three types of turnout/Point commands:</p>
|
|
|
|
<p><a href="#TurnoutList">Turnout List</a> sent when a client connects. This was described
|
|
<a href="#TurnoutList">[here]</a></p>
|
|
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Turnout/Point Request</h4>
|
|
|
|
<p class="command">
|
|
<strong>PTA</strong>«turnoutAction»«turnoutName»
|
|
</p>
|
|
|
|
<p>A <strong>Turnout/Point Request</strong> sent from client to server, requesting a new state for a
|
|
turnout. Can (optionally) create the turnout/point in JMRI if "Turnout Creation" is allowed in
|
|
WiThrottle Preferences. Will return <a href="#AlertandInfoMessage">HM alert message</a> if
|
|
error setting requested state.</p>
|
|
|
|
<pre class="code">
|
|
PTACLT92
|
|
</pre>
|
|
<p>The parts of this command are as follows:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PTA</strong></td>
|
|
<td>Prefix used for turnout/point commands</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnout/Point Action</td>
|
|
<td>C</td>
|
|
<td>Requested state, can be <br/>
|
|
'C'losed,<br/>
|
|
'T'hrown or <br/>
|
|
'2'Toggle current state</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnout/Pount Name</td>
|
|
<td>LT92</td>
|
|
<td>Name of turnout/point, can be a system name or a number. If number, server will use default
|
|
connection.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Turnout/Point Notification</h4>
|
|
|
|
<p>A <strong>Turnout/Point Notification</strong> sent from server to client, advising the new state
|
|
of a turnout/point. This is sent for all changes to known turnouts/points, whether requested by this
|
|
client or elsewhere.</p>
|
|
|
|
<pre class="code">
|
|
PTA2LT92
|
|
</pre>
|
|
<p>The parts of this response are:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PTA</strong></td>
|
|
<td>Prefix used for turnout/point commands</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnout/Point State</td>
|
|
<td>2</td>
|
|
<td>Current state, can be<br/>
|
|
'2' = Closed,<br/>
|
|
'4' = Thrown,<br/>
|
|
'1' = Unknown or<br/>
|
|
'8' = Inconsistent</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turnout/Point Name</td>
|
|
<td>LT92</td>
|
|
<td>Always returns system name of turnout/point.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="RouteCommands">Route Commands <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>There are three types of Route commands:</p>
|
|
|
|
<p><a href="#RouteList">Route List</a> sent when a client connects. This was described
|
|
<a href="#RouteList">[here]</a></p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Route Request</h4>
|
|
|
|
<p class="command">
|
|
<strong>PRA2</strong>«routeName»
|
|
</p>
|
|
|
|
<p><strong>Route Request</strong> sent from client to server, requesting the route be "set".
|
|
Will return <a href="#AlertandInfoMessage">HM alert message</a> if error setting route.</p>
|
|
|
|
<pre class="code">
|
|
PRA2IO_RESET_LAYOUT
|
|
</pre>
|
|
<p>The parts of this command are as follows:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>PRA</strong></td>
|
|
<td>Prefix used for route commands</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td><strong>2</strong></td>
|
|
<td>Always '2'= Set route</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Route Name</td>
|
|
<td>IO_RESET_LAYOUT</td>
|
|
<td>System name of route to set.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h4>Route Notification</h4>
|
|
|
|
<p class="command">
|
|
<strong>PRA</strong>«routeState»«routeName»
|
|
</p>
|
|
|
|
<p>A <strong>Route Notification</strong> sent from server to client, advising the new state of
|
|
a route. This is sent for all changes to known routes, whether requested by this client or
|
|
elsewhere.</p>
|
|
|
|
<pre class="code">
|
|
PRA2IO_RESET_LAYOUT
|
|
</pre>
|
|
<p>The parts of this response are:</p>
|
|
|
|
<table class="data">
|
|
<tr>
|
|
<th>Segment</th>
|
|
<th>Example</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
<td>PRA</td>
|
|
<td>Prefix used for route commands</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Route State</td>
|
|
<td>2</td>
|
|
<td>Current state, can be<br/>
|
|
'2'=Active,<br/>
|
|
'4'=Inactive or<br/>
|
|
'8'=Inconsistent</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Route Name</td>
|
|
<td>IO_RESET_LAYOUT</td>
|
|
<td>System name of route.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="UnknownCommands">Unknown Commands <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>Any command that is not recognized by a client should be ignored, with processing
|
|
continuing after the next newlines.</p>
|
|
|
|
<!-- -------------------------------------------------------- -->
|
|
|
|
<h2 id="Observations">Observations <a class="to-top" href="#top">^Top</a></h2>
|
|
|
|
<p>The LnWI sends a <code>PFC</code> command after connecting. Its purpose is unknown at this
|
|
time.</p>
|
|
|
|
<hr>
|
|
|
|
<p>This is the package/jmri/jmrit/withrottle/Protocol help page</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
</div>
|
|
<!-- close #mBody -->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|