Technical Reference for Throttle Developers

This page is intended to capture relevant information to assist those who develop throttles compatible with EX‑CommandStation using the DCC-EX Native Protocol, not the wiThrottle Protocol.

This page should be read in conjunction with the DCC-EX Native API Reference in order to understand how to send and parse DCC-EX API commands correctly, and ignore any irrelevant commands.

Considerations for throttle developers 

For anyone developing a throttle or controller application, these considerations should be taken into account:

Refer to the DCC-EX Native API Reference
Refer to the DCC-EX Native Commands Summary Reference
A throttle/controller MUST accept and ignore anything it does not understand
Track power state has three possible states: On, Off, and Unknown
There is no concept of a throttle ‘acquiring’ a loco.
Simply, commands for a loco are sent to the Command Station, and the Command Station ‘broadcasts’ the status of any/every loco to every throttle any time a change is made to a loco.
There is no concept of the throttle disconnecting from the Command Station.

DCC-EX Native command library - DCCEXProtocol 

For throttle developers that want to focus on throttle features and functionality, the DCC-EX team have now released an Arduino library that communicates with EX‑CommandStation via the native DCC-EX commands.

This library exposes numerous methods to interact with the EX‑CommandStation and the various objects including locos, turnouts/points, routes, and turntables.

For further information, refer to the DCC-EX Native command library - DCCEXProtocol documentation.

Responding to appropriate information 

In addition to understanding the specific throttle commands details on this page, throttles/controllers also must understand and respond appropriately to broadcasts sent from the DCC-EX API.

These are the key broadcast responses that should be understood:

<p X [MAIN|PROG|JOIN]> - When a throttle issues a track power command, this response is sent as a broadcast (see Power Management)
<r address> - When a loco address is read on the programming track, the address is sent as a broadcast (see Reading/Writing Configuration Variables (CVs) - Programming track)
<l cabid slot speed/dir func> - When throttles send loco commands, this is sent as a broadcast (see Cab (Loco) Commands)

These broadcast responses should be understood if your controller deals with turnouts/points and sensors:

<H id [DCC|SERVO|VPIN|LCN] ... [0|1]> - When turnouts are closed/thrown, this response is broadcast (see Turnouts/Points)
<[q|Q] id> - When sensors are deactivated/activated, this response is broadcast (see Sensors)
<m "text"> - New in 5.4.0 - A message can be sent to all throttles using EXRAIL (see MESSAGE( “msg” ) - Writes a message to all clients)
<i id position moving> - New in 5.4.0 - Broadcasts if the new turntable/traverser objects are implemented (see Turntables/Traversers).

Working with track power states 

Track power can be On, Off, or Unknown. There is no broadcast of an Unknown power state though, meaning a throttle/controller must start with track power flagged as Unknown.

The throttle should only flag the power state as On or Off when either:

A power broadcast is received from the EX‑CommandStation <p...>
The throttle user selects to turn track power on or off

Key Throttle commands 

Key throttle specific commands are summarised here, refer below for elaboration on the details with examples. Refer to the DCC-EX Native Commands Summary Reference for detailed information.

Command	Response	Description
`<t cabid speed dir>`	`<l cabid slot speedbyte functionMap>` (Broadcast)	Sets a cab (loco) speed and direction. (See below for the response)
`<t cabid>`	`<l cabid slot speedbyte functionMap>` (Broadcast)	Requests a deliberate update of cab (loco) speed/functions
`<F cabid funct state>`	`<l cabid slot speedbyte functionMap>` (Broadcast)	Turns cab (loco) decoder functions ON and OFF (See below for the response.)
`<JT>`	`<jT id1 id2 id3 ...>`	Returns the defined turnout IDs
`<JT id>`	`<jT id state "[description]">`	Returns the ID, state, and description of the specified turnout ID
`<JA>`	`<jA id1 id2 id3 ...>`	Returns the defined automation and route IDs
`<JA id>`	`<jA id type "[description]">`	Returns the ID, type (A=automation or R=route), and description of the specified automation/route ID
`<JR>`	`<jR id1 id2 id3 ...>`	Returns the defined roster entry IDs
`<JR id>`	`<jR id "description" "function1/function2/function3/...">`	Returns the ID, description, and function map of the specified roster entry ID
`<JO>`	`<jO id1 id2 id3 ...>`	Returns the defined turntable IDs
`<JO id>`	`<jO id type position position_count "[description]">`	Returns the ID, type (0=DCC or 1=EXTT), current position, position count, and description of the specified turntable ID
`<JP id>`	`<jP id index angle "[description]">`	Returns the turntable ID, position index, angle, and description of each defined position for the specified turntable ID

Additional Details 

Refer to the DCC-EX Native Commands Summary Reference for detailed information on these commands.

Setting cab (loco) status 

<t cabid speed dir> - Sets a cab (loco) speed and direction. (See below for the response.)

<F cab funct state> - Turns cab (loco) decoder functions ON and OFF. (See below for the response.)

Obtaining loco (cab) status 

<t cabid> - Requests a deliberate update on the cab speed/functions in the same format as the cab broadcast.

Example response:

<l cabid slot speedbyte functionMap> - Note that a slot of -1 indicates that the cab is not in the reminders table and this command will not reserve a slot until such time as the cab is throttled.

Where:

cabid = Loco’s DCC address

slot = Position in the reminders table (for the convenience of slot managers later)

speedbyte = The DCC packet speed bye including the direction bit (NOT the same as the DCC-EX speed)

reverse - 2-127 = speed 1-126, 0 = stop

forward - 130-255 = speed 1-126, 128 = stop

functionMap = Binary map of which functions are ON ( 1=F0, 2=F1, 3=F0&F1 etc.)

The above is not a direct response, but rather as a broadcast that will be triggered as a result of any throttle command being issued by any device for the cab(loc) in question.

Turnouts/Points 

The conventional turnout definition commands and the <H> responses do not contain information about the turnout description which may have been provided in an EXRAIL script. A turnout description is much more user friendly than the identifier (e.g. T123), and having a list helps the throttle UI build a suitable set of buttons.

<JT> - Returns a list of turnout IDs. The throttle should be uninterested in the turnout technology used but needs to know the IDs it can throw/close and monitor the current state.

Example response:

<jT 1 17 22 19> - Turnout IDS 1, 17, 22, and 19 are defined.

<JT 17> - Returns the description for turnout ID 17, and the status of T=thrown or C=closed.

Example responses:

<jT 17 T "Coal yard exit"> - Description “Coal yard exit” plus state is thrown.

<jT 17 C "Coal yard exit"> - Description “Coal yard exit” plus state is closed.

<jT 17 C ""> - Indicates turnout description not defined, and state is closed.

<jT 17 X> - Indicates turnout unknown (or possibly hidden.)

Note

It is still the throttles responsibility to monitor the status broadcasts. Also note that turnouts marked in EXRAIL with the HIDDEN keyword instead of a “description” will NOT show up in these commands.

Note

Note from the author: The existing broadcast is messy and needs cleaning up, however, I’m not keen on dynamically created/deleted turnouts so I have no intention of providing a command that indicates the turnout list has been updated since the throttle started. - Chris Harlow

Automations/Routes 

A throttle needs to know which EXRAIL Automations and Routes it can show the user.

<JA> - Returns a list of Automations/Routes.

Example response:

<jA 13 16 23> - Indicates route/automation ids 13, 16, and 23 are defined.

<JA 13> - Returns information for route/automation ID 13 including the description, and if it is a route (R) or automation (A).

Example responses:

<jA 13 R "description"> - Returns the description for ID 13, and that it is a route.

<jA 13 A "description"> - Returns the description for ID 13, and that it is an automation.

<jA 13 X> - Indicates ID 13 is not found.

New in version 5.4

Route states can now also be broadcast via EXRAIL, allowing throttles to respond when they are active/inactive or hidden. Throttle developers should now respond to (or ignore if not implemented) the <jB ...> broadcasts.

This broadcast is in the format:

<jB id param> where:

id is the ID of the route or automation (obtained via the <JA> commands above)
param is one of the following:
- 0 - indicates the route/automation is currently inactive
- 1 - indicates the route/automation is currently active
- 2 - indicates the route/automation should be hidden/unavailable
- “text” - some text that should be display to the user
Example broadcasts:
- <jB 13 0> - indicates route/automation ID 13 is inactive
- <jB 13 1> - indicates route/automation ID 13 is active
- <jB 13 2> - indicates route/automation ID 13 should be hidden
- <jB 13 "Route 13"> - indicates route/automation ID 13’s label/description should be set to “Route 13”

To see how these are implemented in EXRAIL, refer to Flow Control.

What’s the difference?

A ROUTE is just a call to an EXRAIL ROUTE, traditionally to set some turnouts or signals but can be used to perform any kind of EXRAIL function, but is not expecting to know the loco ID.

A route can be triggered by sending, for example, </START 13>.

An AUTOMATION is a handoff of the last accessed loco ID to an EXRAIL AUTOMATION which would typically drive the loco away.

An automation expects a start command with a cab ID, for example </START 13 3>.

Roster Information 

<JR> - Requests a list of cab IDs from the roster.

Example responses:

<jR 3 200 6336> - Returns the roster entry IDs 3, 200, and 6336 are defined.

<jR> - Indicates no roster entries are defined.

<JR 200> - Returns the roster name function map for roster ID 200.

Example response:

<jR 200 "Thomas" "whistle/*bell/squeal/panic"> - Returns the defined description “Thomas” with each defined function’s name. Refer to the EXRAIL ROSTER command for function map format.

Turntables/Traversers 

A new feature has been added to support control of turntables/traversers from throttles, including the ability for throttles to “draw” turntable positions as defined to support graphical operation. If EXRAIL commands are used to define turntables and their associated positions, a description for the turntable as well as each position is able to be defined.

Note that to obtain a complete definition for a turntable/traverser, the turntable object needs to be queried first (<JO id>) followed by the position query (<JP id>) to obtain all defined positions for the object.

<JO> - Returns a list of turntable IDs.

Example response:

<jT 1 2> - Turntable IDs 1 and 2 are defined.

<JO 1> - Returns details of turntable ID 1.

Example responses:

<jO 1 0 1 5 "DCC Turntable"> - DCC turntable type currently at position 1, with 5 defined positions and a description “DCC Turntable”.

<jO 1 1 0 11 "EX-Turntable"> - EX-Turntable type currently at the home position (0), with 11 defined positions and a description “EX-Turntable”

<JP 1> - Returns all positions for turntable ID 1.

Example responses (will return all positions):

<jP 1 0 0 ""> - Position 0, unused for DCC turntables, “home” for EX-Turntable

<jP 1 1 100 "Turntable position 1"> - Position 1, 10 degrees from home

<jP 1 2 1800 "Turntable position 2"> - Position 2, 180 degrees from home

Commands to avoid 

<f cab func1 func2> - Use <F cab function 1/0> instead
<t slot cab speed dir> - Just drop the slot number
<T commands> - other than <T id 0/1>
<D> - If the throttle developer sees the need to obtain info which is <D> only please contact us to get a better way to do it