This page describes the protocol provided by the jmri.jmrit.withrottle package for controlling trains, turnouts, and more through JMRI via a TCP/IP socket.
On This page:
String Parsing
Initial Connection (Server to Client)
Throttle Change Notification
Other Server to Client Messages
Commands (Client to Server)
Throttle Commands
Consist Commands
Turnout/Point Commands
Route Commands
Unknown Commands
Observations
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.
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.
You can see these messages by enabling DEBUG for the Logging Category "jmri.jmrit.withrottle" , see Debugging and System Logging. All messages (both directions) will be added to your JMRI System Console and the session.log file.
JMRI commands and results are very often arrays of values, and sometimes arrays of arrays. The array elements are separated by three-character delimiters.
For example, the following roster entry contains two engines, and each engine has three values:
RL2]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L
Here the delimiters are color-coded to make it easier to see the two different delimiters.
The ]\[
delimiter is used to divide the
different roster entries (there are two), while the }|{
delimiter is used to divide the parts of each roster entry. The details are described in
sections below for each command and response.
When you first open a socket to JMRI, you may get a response that will look something like the following:
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
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.
Each line contains information for parts of the WiThrottle service, as described below, so your application can show things like engines, turnouts/Points, etc.
VN«versionNumber»
The first string, VN2.0
, 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.
Command Segments:
Segment | Example | Description |
---|---|---|
VN | ||
Version Number | 2.0 | The DCC address of the locomotive |
RL0 - for zero entries
RL«numberOfEntries»]\[«entryList»
The roster string always begins with RL
(Roster List) followed by the number
of entries in the roster.
Here are three different examples of roster strings that might be returned by JMRI:
RL0 RL2]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L RL3]\[D&RGW 341}|{3}|{S]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L
with zero, two, and three roster entries, respectively. Each roster entry contains three pieces of information, always in the same order:
Command Segments:
Segment | Example | Description | |
---|---|---|---|
RL | |||
Number of Entries | 2 | Number of entries that will follow on the line | |
]\[ | Repeated for each entry |
||
Name | RGS 41 | The name to show in your application | |
}\{ | |||
Address | 41 | The DCC address of the locomotive | |
}\{ | |||
Length | L | S or L to indicate if this is a Short or Long DCC address |
PPA«powerState»
Returns information about the current state of track power. This takes the following form:
Command Segments:
Segment | Example | Description |
---|---|---|
PPA | ||
Power State | 1 | 0 = Off 1 = On 2 = Unknown |
JMRI returns either zero, one, or two strings for this section.
PTT[\[«turnoutsTitle»}\{«turnoutTitle»[\[«stateTitle»}\{«stateValue»...
PTT]\[Turnouts}|{Turnout]\[Closed}|{2]\[Thrown}|{4]\[Unknown}|{1]\[Inconsistent}|{8
This string contains an array with two elements, which provide the labels to use for each turnout/point state (except for Unknown):
Command Segments:
Segment | Example | Description | |
---|---|---|---|
PTT | |||
]\[ | |||
Turnouts/Points Title | Turnouts | Title for all Turnouts/Points Ignored by Engine Driver |
|
}\{ | |||
Turnout/Points Title | Turnout | Title for a Turnout/Point Ignored by Engine Driver |
|
]\[ | Repeated for each entry |
||
Caption | Closed | The string to show for the possible state of a turnout/point | |
}\{ | |||
Value | 2 | The corresponding value for that turnout/point state |
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:
PTL - for zero entries
PTL«entryList»
PTL]\[LT12}|{Rico Station N}|{1]\[LT324}|{Rico Station S}|{2
Command Segments:
Segment | Example | Description | |
---|---|---|---|
PTL | |||
]\[ | Repeated for each entry (if any) |
||
System Name | LT12 | The system name used to define this turnout/point | |
}\{ | |||
User Name | Rico Station N | The user name entered into JMRI for this turnout/point | |
}\{ | |||
State | 1 | The current state of the turnout/point (see above) |
Similar to turnouts/points, JMRI will reply with zero, one or two strings.
PRT]\[«stateTitle»}\{«stateValue»...
The first string is likewise a list of labels for the route values.
For example:
PRT]\[Routes}|{Route]\[Active}|{2]\[Inactive}|{4]\[Unknown}|{0]\[Inconsistent}|{8
Command Segments:
Segment | Example | Description | |
---|---|---|---|
PRT | |||
]\[ | Repeated for each entry |
||
Caption | Closed | The string to show for the state of turnout | |
}\{ | |||
Value | 2 | The corresponding value for the turnout state |
PRL - for zero entries
PRL«entryList»
The second string contains an array of defined routes. For example:
PRL]\[IR:AUTO:0001}|{Rico Main}|{2
Command Segments:
Segment | Example | Description | |
---|---|---|---|
PRT | |||
]\[ | Repeated for each entry (if any) |
||
System Name | IR:AUTO:0001 | The system name defined for this route. The name in this example was auto-generated | |
}\{ | |||
User Name | Rico Main | The name user entered into JMRI for this route | |
}\{ | |||
State | 2 | 1=Unknown, 2=Active, 4=Inactive, 8=Inconsistent |
RCC«numberOfEntries»
RCL«numberOfEntries»
Command Segments:
Segment | Example | Description |
---|---|---|
RCC | 'RCC' and 'RCL' should be treated the same | |
Number of Consists | 2 | The number of Consists (Multiple Units) defined |
RCD}|{«contsistAddress»}|{«contsistId»]\[«EntryList»
The consist (Multiple Unit) list is similar in concept to the roster list. However, there is a separate line for each consist entry. Here is an example of a consist list that contains two entries:
RCC2 RCD}|{74(S)}|{74(S)]\[3374(L)}|{true]\[346(L)}|{true RCD}|{123(S)}|{123(S)]\[3374(L)}|{true
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.
For whatever reason, consist entries don't follow the same pattern as roster entries. Here is a summary of the Format for each consist entry (with spaces added for readability):
RCD }|{ consistAddress }|{ consistId Array: ]\[ loco DCC Address }|{ locoDirection
Command Segments:
Segment | Example | Description | |
---|---|---|---|
RCD | |||
}\{ | |||
Consist Address | 74(S) | Consist Address | |
}\{ | |||
Consist Id | 74(S) | Consist Id | |
]\[ | Repeated for each entry |
||
loco DCC Address | 3374(L) | The loco address. followed by "(S)" for short addresses or "(L)" for long addresses |
|
}\{ | |||
facing | true | The direction the locomotive is facing in the consist. 'true' = facing forward 'false' = facing backward/reverse |
Addresses have the format address(S/L). For example, 3374(L) is a long address and 74(S) is a short addresses.
In the first example above, here is the information about the first consist entry:
Data | Description |
---|---|
74(S) | Consist has short DCC address 74 |
74(S) | The ID of the consist |
3374(L)}|{true | Loco with long address 3374 in the forward direction |
346(L)}|{true | Loco with long address 346 in the forward direction |
WP«port»
The final string from the initial reply provides the port set for the JMRI web server.
For example:
PW12080
This example indicates that the web server port is set to 12080.
Command Segments:
Segment | Example | Description |
---|---|---|
PW | ||
Port | 12080 | The web server port |
M«throttleId»«notificationType»«locoId»<;>«propertyNotification»
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).
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:
M0AL341<;>F10
Command Segments:
Segment | Example | Description |
---|---|---|
M | ||
Throttle Id | 0 | The ID of the throttle. Valid Throttles: "0"-"9" or "T","S" or "G". T,S,G translate to 0,1,2. |
Notification Type | A | Valid notification types: + = Loco added to Throttle - = Loco removed from Throttle L = List of loco functions A = Action. The following characters provide more details S = loco in use, prompt for steal |
Loco Id | L341 | The DCC address of the locomotive, with 'L' for long or 'S' for short address. or "*" for all locos (consist) currently on the throttle. |
<;> | ||
Property Notification | F10 | The property change notification, using the format described below. If the notificationType is "+" or "-" this will be empty. |
All property change messages begin with M0A (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.
Here is a list of property notifications that can be sent:
Segment | Example | Description |
---|---|---|
Property Change Type | F | The property that changed. Valid properties are: 'F' = Function state change 'S' = speed change 'R' = direction change 's' = Speed step mode |
Property Change Value | 10 | The property that changed. required parameters are: For 'F' = «functionState»«functionNumber» functionState - '0'=Off, '1'=On functionNumber - '0'-'31' For 'V' = «speed» - 0 and 126 inclusive For 'R' = «direction» - '0'=Reverse and '1'=Forward For 's' = «stepMode» - '1'=128step, '2'=28step, '4'=27step or '8'=14step |
M0AL341<;>F10 M0AL341<;>V23 M0AL341<;>R1 M0AL341<;>s1
Also see MultiThrottle Elements for more information.
The M notification is also used to send the list of functions for a loco on a throttle from the server to the client.
M«throttleId»L>«locoId»<;>«functionList»
M0LL7407<;>]\[Lights]\[Bell]\[Whistle]\[Brake Squeal]\[Chuff On-Off]\[Firebox Open-Close]\[
Command Segments:
Segment | Example | Description | |
---|---|---|---|
M | |||
Throttle Id | 0 | The ID of the throttle. Valid Throttles: "0"-"9" or "T","S" or "G". T,S,G translate to 0,1,2. |
|
Notification Type | L | Notification type | |
Loco Id | L341 | The DCC address of the locomotive, with 'L' for long or 'S' for short address | |
]\[ | Repeated for each function |
||
Function Label | Lights | Label for the function |
PFT«seconds»<;>«fastTimeRatio»
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:
PFT65871<;>4 PFT1550686525<;>4.0 PFT1550681224<;>0.0
Command Segments:
Segment | Example | Description |
---|---|---|
PFT | ||
seconds | 37425 | An integer number of seconds since 12:00 midnight, January 1st, 1970 fast clock time |
<;> | ||
fastTimeRatio | 4.0 | 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. |
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.
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.
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:
1607855025 mod 86400 = 37425 seconds since midnight.
37425 seconds since midnight = 10 hours 1425 seconds since midnight = 10 hours 23 minutes 45
seconds since midnight = 10:23:45 am.
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.
Updates are sent on each change in time or rate, and when clock stopped or started, so expect one message every fast clock minute.
HM«messageText»
Hm«messageText»
The server can send a message string that the client can display. These cannot have
newlines in message. Two types:
Alert message: 'HM' + message text. Normally used to return errors to be shown to user.
Info message: 'Hm' + message text. Same as HM, but informational only.
Example returned after client requests invalid address (say
M0+L23<;>L23
) the response is:
HMJMRI: address 'L23' not allowed as Long
Command Segments:
Segment | Example | Description |
---|---|---|
HM Hm |
||
Message | HMJMRI: address 'L23' not allowed as Long | Message |
HT«serverType»
Ht«serverDescription»
The server can send a "type" to identify itself to clients, useful to enable specific
behaviors. Two types:
'HT' + type. Known types: 'Digitrax', 'MRC', 'JMRI'
'Ht' + description. Longer informational text string, cannot contain newlines
HTJMRI HtJMRI v4.19.8 My JMRI Railroad
Command Segments:
Segment | Example | Description |
---|---|---|
HT | ||
Server Type | JMRI | Server Type |
Segment | Example | Description |
---|---|---|
Ht | ||
Server Type | JMRI v4.19.8 My JMRI Railroad | Server Type |
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 DeviceServer class to determine where to send the rest of the command. Here are the letters currently supported:
HU«clientDeviceId»
Sets the device ID for the client. This could, for example, be the MAC address of the
caller, as a string. The syntax is HUidentifier
, where
identifier is different for each connected device.
This needs to be unique for each device connected to the server. It is used to prevent duplicate connections from the same client. Engine Driver and WiThrottle app use a generated unique identifier.
N«clientDeviceName»
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 Nname
, where
name can be any text, except for a newline, as the newline terminates the command.
For example:
NJohn's Throttle
Reply: *
StopSeconds
*10
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.
*
*+
*-
There are three versions of this command:
Command | Description |
* | Send heartbeat |
*+ | Turn heartbeat monitoring on |
*- | Turn heartbeat monitoring off |
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.
The 'M' command is for a "multi" throttle, and is handled by the ThrottleController class.
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.
M«throttleId»«command»«locoId»<;>«additionalInfo»
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:
M0+L341<;>ED&RGW 341
This example contains the array elements "+L341" and "ED&RGW 341".
Command Segments:
Segment | Example | Description |
---|---|---|
M | ||
Throttle Id | 0 | The ID of the throttle. Valid Throttles: "0"-"9" or "T","S" or "G". T,S,G translate to 0,1,2. |
Command | + | 'A' = Action / Throttle Command. The following characters provide more details '+' = Add a locomotive to the throttle '-' = Remove a locomotive from the throttle 'S' = Request steal locomotive (see more below) |
Loco Id | L341 | The DCC address of the locomotive, with 'L' for long or 'S' for short address. or "*" for all locos (consist) currently on the throttle. |
<;> | ||
Additional Info | ED&RGW 341 | Additional Information for the command. See Below for each command |
The first character of the first element describes the MultiThrottle command, and is one of the following:
3rd Char | Description |
---|---|
A | Action / Throttle Command. The following characters provide more details |
+ | Add a locomotive to the throttle |
- | Remove a locomotive from the throttle |
S | Request steal locomotive (see more below) |
Each of these operations is described in sections below.
The second element will be passed onto the ThrottleController instance for further processing, and the details are described below in the Actions / Throttle Commands section.
M«throttleId»A>«locoId»<;>«additionalInfo»
The following command is a request to add a new locomotive to the multithrottle:
M0+S3<;>ED&RGW 341
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.
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").
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).
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:
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
If, on the other hand, JMRI does not have the engine number in it's roster, it returns information like the following:
M0+L341<;> M0AL341<;>F00 M0AL341<;>F01 ... M0AL341<;>F027 M0AL341<;>F028 M0AL341<;>V0 M0AL341<;>R1 M0AL341<;>s1
the examples above are all replies from the multithrottle.
The reply consists of the following sections:
For all except the function labels, see the appropriate throttle commands, such as 'V' below, for details.
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.
M«throttleId»->«locoId»<;>«additionalInfo»
The '-' command removes an engine from a multithrottle. Engine Driver, for example, sends the following command to release all locomotives from the 'T' throttle:
M0-*<;>r
The first element after the '-' character is the key of the locomotive to remove, or '*' to remove all 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.
M«throttleId»A>«locoId»<;>«additionalInfo»
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:
M0A*<;>qR
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.
M«throttleId»A«locoId»<;>«additionalInfo»
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:
Each of the commands is described in a section below when it takes additional information. Some commands, such as 'X' require no additional information.
M«throttleId»A«locoId»<;>C«leadLocoAddress»
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.
M0AL341<;>CL346
Command Segments:
Segment | Example | Description |
---|---|---|
C | ||
Lead Loco Address | L346 | The DCC address of the lead loco, with 'L' for long or 'S' for short address |
M«throttleId»A«locoId»<;>d
M«throttleId»A«locoId»<;>r
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.
M0-L341<;>r M0-L341<;>d
You can also release or dispatch all of the locomotives under control of the current throttle:
M0-*<;>r
After sending this command, the WiThrottle Server will typically reply with a removed message
M0-L341<;>
M«throttleId»A«locoId»<;>F«functionState»«functionNumber»
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).
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):
M0A*<;>F112 M0A*<;>F012
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.
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.
Command Segments:
Segment | Example | Description |
---|---|---|
F | ||
Function State | 0 | '0'= Push, '1'= Release |
Function Number | 10 | '0'-'31' Do not use leading zeros for the function numbers |
M«throttleId»A«locoId»<;>f«functionState»«functionNumber»
This command will set the function state regardless of the state before this command. For example:
M0A*<;>f112
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.
The server will respond with a property change notification only if this command changes the function state.
Command Segments:
Segment | Example | Description |
---|---|---|
f | ||
Function State | 0 | '0'=Off, '1'=On |
Function Number | 10 | '0'-'31' Do not use leading zeros for the function numbers |
M«throttleId»A«locoId»<;>f«functionNumber»
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.
This command allows a wiThrottle client to override the setting from the roster. For example:
M0A*<;>m112
will set function 12 to be momentary from now on, and
M0A*<;>m012
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.
The JMRI global wiThrottle preference "F2 always momentary" will override this setting for F2.
Command Segments:
Segment | Example | Description |
---|---|---|
m | ||
Function State | 0 | '0'=latching, '1'=momentary |
Function Number | 10 | '0'-'31' Do not use leading zeros for the function numbers |
M«throttleId»A«locoId»R«direction»
Used to change between forward and reverse.
Command Segments:
Segment | Example | Description |
---|---|---|
R | ||
Direction | 0 | '0'=Reverse, '1'=Forward Actually, any value other than '0' is considered forward |
M«throttleId»A«locoId»<;>V«speed»
Set the speed to a value between 0 and 126. The format looks something like this:
M0A*<;>V30
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.
Segment | Example | Description |
---|---|---|
V | ||
Speed | 30 | 0 to 126 inclusive |
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.
Stealing a loco takes a few steps. Here is the sequence
Here is an example
From WiThrottle Server (JMRI) | From Client |
---|---|
MT+L341<;>L341 | |
MTSL341<;>L341 | |
MTSL341<;>L341 |
Note: Steal requires JMRI 4.10 or later
M«throttleId»A«locoId»<;>q«whatToQuery»
Used to request the current values of speed (V) or direction (R)
Command Segments:
Segment | Example | Description |
---|---|---|
q | ||
What to Query | V | 'V' = Query current speed 'R' = Query current direction |
Example requesting current speed and direction for all locos on throttle '0':
M0A*<;>qV M0A*<;>qR
The server responds with the Throttle Change Notification as described [here]. Example responses for address 3(S) on throttle '0':
M0AS3<;>V25 M0AS3<;>R1
RC«command»<;>«consistAddress»<;>«additionalInfo»
The commands in this section are used to work with consists. All the consist commands start with "RC", which stands for Roster Consist.
RC+<;>«consistAddress»<;>«additionalInfo»
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 not exist. The following commands will create a consist (multiple unit) with address "S74" and name "My consist" with two locos:
RC+<;>S74<;>My consist<:>L341<;>true RC+<;>S74<;>My consist<:>L342<;>true
The parts of this command are as follows:
Segment | Example | Description |
---|---|---|
RC+ | ||
<;> | ||
Consist Address | S74 | The DCC address of the consist (multiple unit) |
<;> | ||
Loco Address | L341 | DCC address of the loco to add to the consist (multiple unit) |
<;> | ||
Direction | true | Direction is normal (false for reversed) |
RC-<;>«consistAddress»<;>«additionalInfo»
Removes a single locomotive from the consist.
For example:
RC-<;>S74<:>L341
This example removes DCC address L341 from the consist with the DCC address of S74.
Command Segments:
Segment | Example | Description |
---|---|---|
RC- | ||
<;> | ||
Consist Address | S74 | The DCC address of the consist (multiple unit) |
<;> | ||
Loco Address | L341 | DCC address of the loco to remove to the consist (multiple unit) |
RCP<;>«consistAddress»<;>«additionalInfo»
This command is used to change the order of locos in a consist. These commands have the following format:
RCP<;>consistAddress<:>leadLoco<;>nextLoco<;>...* ...<;>nextLoco<;>trailLoco
Notice that this has no direction information--it just has a list of locomotive DCC addresses. For example:
RCP<;>S74<:>L346<;>L3374
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.
Command Segments:
Segment | Example | Description | |
---|---|---|---|
RCP | |||
<;> | |||
Consist Address | S74 | The DCC address of the consist (multiple unit) | |
<;> | Repeated for each loco |
||
Loco Address | L341 | DCC address of the loco to place to the consist (multiple unit), in order starting with the lead loco |
RCR<;>«consistAddress»
Deletes a consist.
For example, the following command deletes the consist with DCC address S74.
RCR<;>S74
Command Segments:
Segment | Example | Description |
---|---|---|
RCR | ||
<;> | ||
Consist Address | S74 | The DCC address of the consist (multiple unit) tp remove |
There are three types of turnout/Point commands:
Turnout List sent when a client connects. This was described [here]
PTA«turnoutAction»«turnoutName»
A Turnout/Point Request 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 HM alert message if error setting requested state.
PTACLT92
The parts of this command are as follows:
Segment | Example | Description |
---|---|---|
PTA | Prefix used for turnout/point commands | |
Turnout/Point Action | C | Requested state, can be 'C'losed, 'T'hrown or '2'Toggle current state |
Turnout/Pount Name | LT92 | Name of turnout/point, can be a system name or a number. If number, server will use default connection. |
A Turnout/Point Notification 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.
PTA2LT92
The parts of this response are:
Segment | Example | Description |
---|---|---|
PTA | Prefix used for turnout/point commands | |
Turnout/Point State | 2 | Current state, can be '2' = Closed, '4' = Thrown, '1' = Unknown or '8' = Inconsistent |
Turnout/Point Name | LT92 | Always returns system name of turnout/point. |
There are three types of Route commands:
Route List sent when a client connects. This was described [here]
PRA2«routeName»
Route Request sent from client to server, requesting the route be "set". Will return HM alert message if error setting route.
PRA2IO_RESET_LAYOUT
The parts of this command are as follows:
Segment | Example | Description |
---|---|---|
PRA | Prefix used for route commands | |
2 | Always '2'= Set route | |
Route Name | IO_RESET_LAYOUT | System name of route to set. |
PRA«routeState»«routeName»
A Route Notification 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.
PRA2IO_RESET_LAYOUT
The parts of this response are:
Segment | Example | Description |
---|---|---|
PRA | Prefix used for route commands | |
Route State | 2 | Current state, can be '2'=Active, '4'=Inactive or '8'=Inconsistent |
Route Name | IO_RESET_LAYOUT | System name of route. |
Any command that is not recognized by a client should be ignored, with processing continuing after the next newlines.
The LnWI sends a PFC
command after connecting. Its purpose is unknown at this
time.
This is the package/jmri/jmrit/withrottle/Protocol help page
Thanks and congratulations to all who contributed! Contact us via the JMRI users Groups.io group.
Copyright © 1997 - 2024 JMRI Community. JMRI®, DecoderPro®, PanelPro™, DispatcherPro™, OperationsPro™, SignalPro™, SoundPro™, LccPro™, TrainPro™, Logix™, LogixNG™ and associated logos are our trademarks. Additional information on copyright, trademarks and licenses is linked here.
View the