DCC-EX Native Commands Summary Reference

This page describes all the DCC-EX Native Commands that the EX‑CommandStation supports.

Conventions used on this page 

< and > - All DCC-EX commands are surrounded by these characters to indicate the beginning and end, these must always be included
First letter or number - These are called OPCODES, are case sensitive, and must be specified as directed, e.g. 1, c, or -
CAPITALISED words - These are parameters referred to as keywords, and should be specified as directed, e.g. MAIN (note these are not case sensitive, however capitalising makes them easier to distinguish from other parameters)
lowercase words - These are parameters that must be provided or are returned, with multiple parameters separated by a space “ “, e.g. cab
Square brackets [] - Parameters within square brackets [] are optional and may be omitted, and if specifying these parameters, do not include the square brackets themselves
| - Use of the | character means you need to provide one of the provided options only, for example <0|1 MAIN|PROG|JOIN> becomes either <0 MAIN> or <1 MAIN>
0|1 DIRECTION: 1=forward, 0=reverse.

Controlling the EX-CommandStation 

Power Management 

Also see System Information for retrieve command station power information.

`<onOff [track]>` - Turn power on or off to the MAIN and PROG tracks 

Also allows joining the MAIN and PROG tracks together.

Parameters:
> onOff: one of
 • 1 = on
 • 0 = off
> track: one of
 • blank = Both Main and Programming Tracks
 • MAIN = Main track
 • PROG = Programming Track
 • JOIN = Join the Main and Programming tracks temporarily
Note: While <1 JOIN> is valid, <0 JOIN> is not.

Response:

The following is not a direct response, but rather a broadcast that will be triggered as a result of any power state changes.

<pOnOFF [track]>

Notes:

The use of the JOIN function allows the DCC signal for the MAIN track to also be sent to the PROG track. This allows the prog track to act as a siding (or similar) in the main layout even though it is isolated electrically and connected to the programming track output.

However, it is important that the prog track wiring be in the same phase as the main track i.e. when the left rail is high on MAIN, it is also high on PROG. You may have to swap the wires to your prog track to make this work.

If you drive onto a programming track that is “joined” and enter a programming command, the track will automatically switch to a programming track. If you use a compatible Throttle, you can then send the join command again and drive off the track onto the rest of your layout!

In some split Motor Shield hardware configurations JOIN will not be able to work.

While <1 JOIN> is valid, <0 JOIN> is not.

Examples:
all tracks off: <0>
all tracks on <1>
join: <1 JOIN>
Example Responses:
all tracks off: <p0>
all tracks on <p1>
join: <p1 JOIN>

`<D RESET>` - Re-boot the command Station 

Response: N/A

`<J I> <JI>` - Request current values list 

Response: <jI [cA cB cC ...]>
> c: Raw current value for each defined Track, in milliAmps

`<J G> <JG>` - Request max current list 

Response: <jG [mA mB mC ...]>
> m: Raw current trip value for each defined Track, in milliAmps

Track Manager 

Note: Previously referred to as ‘DC-District’.

`<= trackletter mode [cab]>` - Configure Track Manager 

Important

Whenever the track mode is changed, track power is automatically turned off.

Parameters:
> trackletter: ‘A’ through ‘H’ represent one of the outputs of the/a Motor Shield.
> mode: one of
    • MAIN
    • MAIN_INV
    • MAIN_AUTO [1]
    • PROG
    • DC
    • DC_INV = DC reversed polarity
    • DCX [2] = DC reversed polarity (same as DC_INV)
    • NONE
> id: the cab ID. Required when specifying DC or DC_INV / DCX

Response:
(for each track/channel that has changed) <= trackletter state cab>

> trackletter: A-H
> state: ‘PROG’, ‘MAIN’, ‘MAIN_INV’, ‘MAIN A’, ‘DC’, ‘DCX’, ‘NONE’
> cab: cab(loco) equivalent to a fake DCC Address for DC and DCX only

Notes:

Since only one channel can be PROG, changing a second channel to PROG, will force the other to NONE
The response to DC_INV is DCX
The response to DCC_MAIN is MAIN A

`<=>` - Request the current Track Manager configuration 

Response:
for each track/channel supported by the Motor Shield <= trackletter state cab>

> trackletter: A-H
> state: ‘PROG’, ‘MAIN’, ‘MAIN_INV’, ‘MAIN A’, ‘DC’, ‘DCX’, ‘NONE’
> cab: cab(loco) equivalent to a fake DCC Address for DC and DCX only

Notes:

A track set to DC_INV (DC inverted) will respond with DCX

A track set to MAIN_AUTO (DCC Auto reverser) will respond with MAIN A

`<onOff [track]>` - Turn power on or off to the requested TrackManager track 

Parameters:
> onOff: one of
• 1 = on
• 0 = off
> track: one of tracks A - H

Response:
The following is not a direct response, but rather a broadcast that will be triggered as a result of any power state changes.
<pOnOFF [track]>

Change Frequency on DC or DC_INV/DCX TrackManager track 

When running in DC mode certain locomotives can be unresponsive at certain DC frequencies, a situation that is not found when running in DCC mode. When in DC or DC_INV / DCX mode it is now possible to set different frequencies using Functions F29, F30 & F31.

The settings achievable vary slightly depending upon the processor running the Command Station but broadly follow the following:

> No Functions: Default - low frequency 131Hz
> F29: Mid frequency - 490Hz
> F30: High frequency - 3400Hz
> F31: Supersonic - 62500Hz

Notes:

These functions are not cumulative - setting F30 overrides F29 and setting F31 overrides F29 & F30.
You need to activate the functions above once you have acquired the loco address that have assigned to the output.
Specifically:
1. Set the output/track to DC mode with a specified loco address
2. Acquire that loco address in your throttle app
3. Make sure the loco is stopped
4. Set the frequency by activating one of the functions above
You need to stop the loco (throttle to zero) before changing the frequency using the function buttons.

For details on setting F keys see “Turn Loco decoder functions ON or OFF” in Cab (Loco) Commands below.

For ease of changing these functions within EXRAIL an EXRAIL command SET_FREQ is available to select the frequency within automations/routes.

Cab (Loco) Commands 

`<t cab>` - Request a deliberate update on the cab (loco) speed/functions 

Parameters:
> cab: DCC Address of the decoder/loco

Response:
The following 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.

<l cab reg speedByte functMap>
> cab: DCC Address of the decoder/loco. The short (1-127) or long (128-10293) address of the engine decoder (this has to be already programmed in the decoder)
> reg: not used. We no longer use this but need something here for compatibility with legacy systems. Enter any single digit. > speedbyte: Speed in DCC speedstep format
• reverse - 2-127 = speed 1-126, 0 = stop, 1 = Emergency Stop
• forward - 130-255 = speed 1-126, 128 = stop, 129 = Emergency Stop
> FunctiMap: individual function states represented by the bits in a byte

Notes:

The speedbyte value is different to the speed sent, as it is an encoded (1,7 bits) byte.
This starts a reminder process for any external updates to the cab’s (loco’s) status.

`<t cab speed dir>` - Set Cab (Loco) Speed 

Parameters:
> cab: DCC Address of the decoder/loco
> speed: 0-127 or -1 for Emergency Stop
> dir: one of
 • 1=forward
 • 0=reverse

Response:
The following 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.

<l cab reg speedByte functMap>
> cab: DCC Address of the decoder/loco
> speedbyte: Speed in DCC speedstep format
 • reverse - 2-127 = speed 1-126, 0 = stop, 1 = Emergency Stop
 • forward - 130-255 = speed 1-126, 128 = stop, 129 = Emergency Stop
> FunctiMap: individual function states represented by the the bits in a byte

Notes:

The speedbyte value is different to the speed sent, as it is an encoded (1,7 bits) byte.
This starts a reminder process for any external updates to the cab’s (loco’s) status.

`<!>` - Emergency Stop 

Response:
Repeated for each loco in the reminders list <l cab reg speedByte functMap>
Refer to the <t ..> command for details on this response.

`<F cab funct state>` - Turn loco decoder functions ON or OFF 

Parameters:
> cab: DCC Address of the decoder/loco (short (1-127) or long (128-10293))
> funct: 0-68 (Support for the RCN-212 Functions))
> state:
• 1=on
• 0=off

Response:
The following 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.
<l cab reg speedByte functMap>
refer to the <t > command above for details

Notes:

Setting requests are transmitted directly to mobile loco decoder.
Current state of loco functions (as known by commands issued since power on) is stored by the CommandStation - All functions within a group get set all at once per NMRA DCC standards.
The command station knows about the previous settings in the same group and will not, for example, unset F2 because you change F1. If, however, you have never set F2, then changing F1 WILL unset F2.

Examples: (click to show)

<F 3 0 1> Turns the headlight ON for CAB (loco address) 3

<F 126 0 0> Turns the headlight OFF for CAB 126

<F 1330 1 1> Turns the horn ON for CAB 1330

`<f cab byte1 [byte2]>` - Decoder Functions - Legacy command Deprecated 

Parameters:
> cab: DCC Address of the decoder/loco
> byte1 byte2: DCC function bytes as sent to decoders (up to F28)

Response:
Success: nothing
Fail: <X>

Notes:

Used by the sniffer

Additional Information for byte1: (click to show)
To make “byte1” add the values of what you want ON together, the ones that you want OFF do not get added to the base value of 128.

F0 (Light)=16, F1 (Bell)=1, F2 (Horn)=2, F3=4, F4=8

All off = 128

Light on 128 + 16 = 144

Light and bell on 128 + 16 + 1 = 145

Light and horn on 128 + 16 + 2 = 146

Just horn 128 + 2 = 130

If light is on (144), Then you turn on bell with light (145), Bell back off but light on (144)

Examples: (click to show)
Breakdown for this example: <f 3265 144>

f = (lower case f) This command is for a CAB,s function i.e.: Lights, horn, bell

3265 = CAB: the short (1-127) or long (128-10293) address of the engine decoder

144 = Turn on headlight

To set functions F5-F8 on=(1) or off=(0): <f cab byte1 [byte2]>

f = (lower case f) This command is for a CAB,s function.

byte1 = 176 + F5*1 + F6*2 + F7*4 + F8*8

ADD 176 + the ones you want ON together

Add 1 for F5 ON

Add 2 for F6 ON

Add 4 for F7 ON

Add 8 for F8 ON

176 Alone Turns OFF F5-F8

byte2 = omitted

To set functions F9-F12 on=(1) or off=(0): <f cab byte1 [byte2]>`

f = (lower case f) This command is for a CAB,s function.

byte1 = 160 + F9*1 +F10*2 + F11*4 + F12*8

ADD 160 + the ones you want ON together Add 1 for F9 ON Add 2 for F10 ON Add 4 for F11 ON Add 8 for F12 ON 160 Alone Turns OFF F9-F12

byte2 = omitted

To set functions F13-F20 on=(1) or off=(0): <f cab byte1 [byte2]>

f = (lower case f) This command is for a CAB,s function.

byte1 = 222

byte2 = F13*1 + F14*2 + F15*4 + F16*8 + F17*16 + F18*32 + F19*64 + F20*128

ADD the ones you want ON together

Add 1 for F13 ON

Add 2 for F14 ON

Add 4 for F15 ON

Add 8 for F16 ON

Add 16 for F17 ON

Add 32 for F18 ON

Add 64 for F19 ON

Add 128 for F20 ON

0 Alone Turns OFF F13-F20

To set functions F21-F28 on=(1) or off=(0): <f cab byte1 [byte2]>

f = (lower case f) This command is for a CAB function.

byte1 = 223

byte2 = F21*1 + F22*2 + F23*4 + F24*8 + F25*16 + F26*32 + F27*64 + F28*128

ADD the ones you want ON together

Add 1 for F21 ON

Add 2 for F22 ON

Add 4 for F23 ON

Add 8 for F24 ON

Add 16 for F25 ON

Add 32 for F26 ON

Add 64 for F27 ON

Add 128 for F28 ON

0 Alone Turns OFF F21-F28

`<t reg cab speed dir>` - Set Cab (Loco) Speed - Legacy command Deprecated 

Parameters:
> reg: not used
> cab: DCC Address of the decoder/loco
> speed: 0-127
> dir: one of
• 1=forward
• 0=reverse

Response:
The following 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.
<l cab reg speedByte functMap>
refer to the <t > command above for details
Legacy response: Deprecated
<T reg speed dir> - do not rely on this response

Version Deprecated: 4.1.1

Notes:

The speedbyte value is different to the speed sent, as it is an encoded (1,7 bits) byte.
This starts a reminder process for any external updates to the cab’s (loco’s) status.

`<- [cab]>` - Remove one or all locos from reminders 

Parameters:
> cab: one of
• blank = all locos
• No. = Cab (loco) to forget

Response: N/A

Notes:

Forgets one or all locos. The “cab” parameter is optional.

Once you send a throttle command to any loco, throttle commands to that loco will continue to be sent to the track. If you remove the loco, or for testing purposes need to clear the loco from repeating messages to the track, you can use this command. Sending <- cab> will forget/clear that loco. Sending <-> will clear all the locos. This doesn’t do anything destructive or erase any loco settings, it just clears the speed reminders from being sent to the track. As soon as a controller sends another throttle command, it will go back to repeating those commands.

Examples:

<- 74> - Forgets loco at address 74
<-> - Forgets all locos

`<D speedsteps>` - Switch between 28 and 128 speed steps 

Parameters:
> speedsteps:
    • SPEED28 = use 28 speed steps
    • SPEED128 = use 128 speed steps

Response:
Response sent to the Serial Monitor only (not wifi clients).
One of:
    • 28 Speedsteps
    • 128 Speedsteps

Roster Commands 

`<J R>` `<JR>` - Request the list defined Roster Entry IDs 

Parameters: N/A

Response:
<jR [id1 id2 id3 ...]>
> id?: unique id of the Cab/s (Loco/s) in the roster

Example Responses:
Response (roster exists): <jR id1 id2 id3 ...>
Response (no roster exists): <jR>

`<J R id>` `<JR id>` - Request details of a specific Roster Entry 

Parameters:
> id: unique id of the Cab/s (Loco/s) in the roster

Response:
<jR id ""|"desc" ""|"funct1/funct2/funct3/...">
 > id: unique id of the Cab/s (Loco/s) in the roster
 > desc: description of the Loco
 > funct?: Label for each function 0-28

Example Responses:
Response (id is in Roster): <jR id "desc" "funct1/funct2/funct3/...">
Response (id is not in Roster): <jR id "" "">

Turnouts/Points 

For details on how to configure turnouts/points see: Turnouts/Points (Configuring the EX-CommandStation)

`<T>` - Request a list all defined turnouts/Points 

Response:
Repeated for each defined Turnout/Point
 Response: <H id state>
Response (fail): N/A
Response (no defined turnouts/points): X

> id - The numeric ID (0-32767) of the turnout to control.
> state: one of
 • 1 = Thrown,
 • 0 = Closed

`<T id state>` - Throw or Close a defined turnout/point 

Parameters:
> id: identifier of the Turnout/Point
> state: one of
 • 1 = Throw,
 • T = Throw,
 • 0 = Close,
 • C = Close,
 • X = eXamine

Response:
<H id state>
> id: one of
 • identifier of the Turnout/Point, or
 • X if the command fails
> state: one of
 • 1 = Thrown,
 • 0 = Closed
 • blank = command failed

Example Responses:
Response on throw/close:
 Response (successful): <H id state>
 Response (fail): <X>
Response on eXamine:
 Response (DCC Accessories): <H id DCC address subaddress state>
 Response (Servos): <H id SERVO vpin thrown_position closed_position profile state>
 Response (VPIN): <H id VPIN vpin state>
 Response (LCN): <H id LCN state>
 Response (fail/no such turnout): <X>

Response - Additional Details: (click to show)

id : The numeric ID (0-32767) of the turnout to control.
(NOTE: IDs are shared between Turnouts/Points, Sensors and Outputs)

address : the primary address of a DCC accessory decoder controlling a turnout/point (0-511)

subaddress : the subaddress of a DCC accessory decoder controlling a turnout/point (0-3)

vpin : the pin number of the output to be controlled by the turnout/point object. For Arduino output pins, this is the same as the digital pin number. For servo outputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 100-115 for servos attached to the first PCA9685 Servo Controller module, 116-131 for the second PCA9685 module, 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module.

state : 0 = closed. 1 = thrown.

thrown_position : the PWM value corresponding to the servo position for THROWN state, normally in the range 102 to 490.

closed_position : the PWM value corresponding to the servo position for CLOSED state, normally in the range 102 to 490.

profile : the profile for the transition between states. 0=Immediate, 1=Fast (0.5 sec), 2=Medium (1 sec), 3=Slow (2 sec), 3=Bounce (for semaphore signals).

`<J T id>` `<JT id>` - Request details of a specific Turnout/Point 

Parameters:
> id: unique id of the Turnout/Point

Response:
<jT id X|state |"[desc]">
> id: unique id of the Turnout/Point
> state: one of
 • C = Closed
 • T = Thrown
 • X = unknown id
> desc: one of
 • “desc” = description of the Turnout(Point) (including surrounding quotes)
 • blank = unknown id

Example Responses:
Response (id is defined): <jT id state "[desc]">
Response (id not defined): <jT id X>

`<J T>` `<JT>` - Request the list of defined turnout/Point IDs 

Response: <jT [id1 id2 id3 ...]>
> id: unique id of the Turnout/s(Point/s)

Example Responses:
Response (has defined Turnouts/Points): <jT id1 id2 id3 ...>
Response (no defined Turnouts/Points): <jT>

Turntables/Traversers 

For details on how to configure turntables/traversers see: Turntables/Traversers (Configuring the EX-CommandStation)

`` - Request a list all defined turntables/traversers 

Response:
Repeated for each defined Turtable/traverser
Response: 
Response (fail): N/A
Response (no defined turntables/traversers): X

> id - The numeric ID (1-32767) of the turntable to control
> position - The current position of the turntable

`` - Request position of the specified turntable/traverser 

Response:
Response: 
Response (fail): N/A
Response (no defined turntables/traversers): X

> id - The numeric ID (1-32767) of the turntable to control
> position - The current position of the turntable

`` - Rotate a DCC turntable 

Parameters:
> id: - Identifier of the Turntable/traverser
> position: - Position to rotate to

Response:

> id: one of
 • identifier of the Turntable/traverser, or
 • X if the command fails
> position: one of
 • position rotating to, or
 • blank = command failed
> moving: one of
 • 0 (no feedback can be returned from a DCC turntable), or
 • blank = command failed

Example Responses:
Response on rotate:
 Response (successful): 
 Response (fail): <X>

Further information:
When a DCC accessory turntable is rotated or moved, no feedback is sent to EX‑CommandStation, and therefore the moving variable will always be ‘0’, and a second response will therefore never be sent to indicate the completion of a rotation or move, unlike how EX‑Turntable operates.

`` - Rotate EX-Turntable 

Parameters:
> id: - Identifier of the Turntable/traverser
> position: - Position to rotate to
> activity: - The activity for EX-Turntable to perform (refer EX-Turntable activity reference)

Response:

> id: one of
 • identifier of the Turntable/traverser, or
 • X if the command fails, or a rotation/move is in progress
> position: one of
 • position rotating to, or
 • blank = command failed
> moving: one of
 • 1 - turntable is moving, or
 • 0 - turntable is not moving, or
 • blank = command failed

Example Responses:
Response on rotate:
 Response (successful): 
 Response (fail): <X>

Further information:
When EX-Turntable commences rotating/moving, the device driver flags this using the moving variable above in the response (1 indicates moving, 0 indicates stationary), and when a rotation or move is complete, it will generate an additional response broadcast to indicate that the rotation or move has completed. Further to this, a new rotate/move command will error when a rotation or move is currently in progress.

`<J O>` `<JO>` - Request the list of defined turntables/traversers 

Response: <jO [id1 id2 id3 ...]>
> id: unique id of the turntable(s)/traverser(s)

Example Responses:
Response (has defined Turnouts/Points): <jO id1 id2 id3 ...>
Response (no defined Turnouts/Points): <jO>

`<J O id>` `<JO id>` - Request details of the specific turntable/traverser 

Parameters:
> id: unique id of the turntable/traverser

Response:
<jO id type position position_count "[desc]">
> id: unique id of the turntable/traverser
> type: one of
 • 0 = DCC
 • 1 = EX-Turntable
 • X = unknown id or hidden
> position: one of
 • index of the current position (0 - 48)
 • blank = unknown or hidden id
> position_count: one of
 • 0 = number of defined positions, including home (0)
 • blank = unknown or hidden id
> desc: one of
 • “desc” = description of the turntable or traverser (including surrounding quotes)
 • blank = unknown or hidden id

Example Responses:
Response (id is defined): <jO id type position position_count "[desc]">
Response (id not defined): <jO id X>

Further information:
The turntable or traverser information does not include the list of defined positions, and this must be requested separated as outlined in the following section.

`<J P id> <JP id>` - Request all position details of the specified turntable/traverser 

Parameters:
> id: unique id of the Turnout/Point

Response:
<jP id index angle "[desc]">
> id: unique id of the turntable/traverser
> index: one of
 • the position index (0 - 48)
 • X = unknown or hidden id
> angle: one of
 • the angle from home for the position (0 - 3600 to allow for partial angles)
 • blank = unknown or hidden id
> desc: one of
 • “desc” = description of the position (including surrounding quotes)
 • blank = unknown or hidden id

Example Responses:
Response (id is defined): <jO id index angle "[desc]">
Response (id not defined): <jO id X>

Routes/Automations 

For details on how to configure routes/automations see: EXRAIL Command Reference

Also see the EXRAIL section below for activating routes.

`<J A>` - Request a list of Automations/Routes 

Response:
<jA [id0 id1 id2 ..]>
> id?: identifier of the Route/Automation(s)

Example Responses:
Response (successful turnouts/point exist): <jA id0 id1 id2 ..>
Response (successful turnouts/point don’t exist): <jA.>
Response (fail): ???

`<J A id> <JA id>` - Request information for a route/automation 

Parameters:
> id: identifier of the Route/Automation

Response:
<jA id X|type |"desc">
> id: identifier of the Route/Automation
> type: one of
• ‘R’= Route
• ‘A’=Automation
> “desc”: Textual description of the route/automation always surrounded in quotes (”)

Example Responses:
Response (successful): <jA id type "desc">
Response (fail - is not defined): <jA id X>

System Information 

`<c>`- Request Current on the Track(s)

Response:
<c "CurrentMAIN" current C "Milli" "0" max_ma "1" trip_ma>
> “CurrentMAIN”: Static text for software like JMRI
> current: Current in MilliAmps
> C: Designator to signify this is a current meter (V would be for voltage)
> “Milli”: Unit of measure for external software with a meter like JMRI (Milli, Kilo, etc.)
> “0”: numbered parameter for external software (1,2,3, etc.)
> max_ma: The maximum current handling of the Motor Driver in MilliAmps
> “1”: number parameter for external software (we use 2 parameters here, 0 and 1)
> trip_ma - The overcurrent limit that will trip the software circuit breaker in mA

`<s>` - Request the DCC-EX version and hardware info, along with listing defined turnouts 

Response:
<iDCCEX version / microprocessorType / MotorControllerType / buildNumber>
(repeated for each defined Turnout/Point): <H id state>

> version: Command Station version
> microprocessorType: microprocessor type (e.g. MEGA)
> MotorControllerType: Motor Driver type (e.g. STANDARD_MOTOR_SHIELD)
> buildNumber: Command Station build number
> id: unique identifier for the Turnout/Point
> state: one of
• 1=thrown
• 0=Closed

`<#>` - Request the number of supported cabs(locos)

Response:
<# noCabs>
> noCabs: maximum number of Cabs(Locos) supported by the command station

Notes:

This will display the number of available cab slots. This will typically be <# 20>, <# 30>, or <# 50> depending on how much memory your EX‑CommandStation has available.

This is a design limit based on the memory limitations of the particular hardware and a compromise with other features that require memory such as WiFI. If you need more slots and are comfortable with code changes you can adjust this by changing MAX_LOCOS in “DCC.h”, knowing that each new slot will take approximately 8 bytes of memory. The <D RAM> command will display the amount of free memory. If you fill the available slots, the “Forget Locos” command (<- [CAB]>) will free up unused locos. Currently there is no automatic purging of unused locos.

DCC Accessories 

EX‑CommandStation can keep track of the direction of any turnout that is controlled by a DCC stationary accessory decoder once its Defined (Set Up).

All decoders that are not in an engine are accessory decoders including turnouts.

Any DCC Accessory Decoder based turnouts, as well as any other DCC accessories connected in this fashion, can always be operated using the DCC COMMAND STATION Accessory command:

There are two interchangeable commands for controlling Accessory Decoders, the Address/Subaddress method (aka “Dual-Coil” method) and linear addressing method. You can either specify an address and its subaddress (Addresses 0-511 with Subaddresses from 0-3) or the straight linear address (Addresses from 1-2044).

In the mapping used by EX-CS|, linear addresses range from linear address 1, which is address 1 subaddress 0, up to linear address 2040 which is address 510 subaddress 3. Decoder address 511 (linear addresses 2041-2044) is reserved for use as a broadcast address and should not be used for decoders. Decoder address 0 does not have a corresponding linear address. This seems strange, but it is the mapping used by many, but not all, commercial manufacturers. If your decoder does not respond on the expected linear address, try adding and subtracting 4 to see if it works. Or use the address/subaddress versions of the commands.

Here is a spreadsheet in .XLSX format to help you: Stationary Decoder Address Table (xlsx Spreadsheet).

NOTE: Both the following commands do the same thing. Pick the one that works for your needs.

`<a addr subaddr activate>` - Control an Accessory Decoder with Address and Subaddress 

Parameters:
> addr: the primary address of the decoder controlling the turnout (0-511)
> subaddr: the subaddress of the decoder controlling this turnout (0-3)
> activate: one of
• 0=off, deactivate, straight or Closed
• 1=on, activate, turn or thrown

Response: ???

`<a linear_addr activate>` - Control an Accessory Decoder with linear address 

Parameters:
> linear_addr: linear address of the decoder controlling this turnout (1-2044)
> activate: one of
• 0=off, deactivate, straight or Closed
• 1=on, activate, turn or thrown

Response: ???

`<A address aspect>` - Command for DCC Extended Accessories.

New in version 5.4

This command sends an extended accessory packet to the track, normally used to set a signal aspect. Aspect numbers are undefined as sdtandards except for 0 which is always considered a stop.

Note

These general commands simply send the appropriate DCC instruction packet to the main tracks to operate connected accessories. It does not store or retain any information regarding the current status of that accessory.

Sensors 

`<Q>` - Lists Status of all sensors 

Response:
Repeat for each defined sensor: <q id>

e.g.
Response (successful) Repeat for each defined sensor: <q id>
Response (fail): N/A

`<S>` - Request a list of all defined sensors 

Response:
Repeated for each defined sensor: <Q id vpin pullup>
> id: identifier of the Sensor. (0-32767)
> vpin: pin number of the input to be controlled by the sensor object
> pullup: one of
• 1=Use pull-up resistor ACTIVE=LOW
• 0=don’t use pull-up resistor ACTIVE=HIGH

e.g.
Response (successful) Repeated for each defined sensor: <Q id vpin pullup>
Response (fail): <X>

Signals 

`</ RED signalId>` </ AMBER signalId> </ GREEN signalId> - Control a signal 

Parameters:
> signalId: defined red Vpin of the signal to control

Response: N/A

WiFi Control 

`<+X>` - Force the Command Station into “WiFi Connected” mode 

A special command to force the “connected” flag (WiFi Connected Mode) to on inside the Command Station so that our loop will start seeing network traffic. If your code creates a connection outside of our normal WiFi code, this provides a way for you to notify the Command Station that it needs to process commands on a connection you created and so you can send your own AT commands.

Response: ???

Examples:

<+GMR> - Sends the “AT+GMR” command that prints version information from the WiFi device.
<+CIFSR> - Gets the local IP Address.

Notes:

DCC-EX WiFi Configuration

Espressif AT Command Set PDF File (Exressif makes the ESP8266)

`<+command>` - Sends AT+ commands to the WiFi board (ESP8266, ESP32, etc.)

Parameters:
> command: what you want to append after AT+ and send to the AT processor.

Response: ???

Example: <+X> would send AT+X to the ESP

Notes:

Users familiar with the AT Command Set of WiFi board may enter commands directly into the Serial Monitor in real-time or as setup commands in the mySetup.h file. This allows users to override the default WiFi connect sequence or to send any command to change a WiFi device setting.

`<+>` - Switch to direct communication with WiFi AT processor 

Response:
All input and output from this point is the direct communication with the WiFi AT software this mode is ended by typing ! (exclamation mark).

`<C WIFI "ssid" "password">` - Connects to an existing WIFI network in STA mode 

Parameters:
> ssid: network to connect to
> password: password to use

Response: ???

Example: ???

Notes:

Valid only for ESP32 microcontrollers only (including the EX‑CSB1)

EXRAIL 

Refer to the EXRAIL Command Reference for these.

EX-FastClock 

These commands require the optional EX‑FastClock hardware to the installed along with the EX‑CommandStation to function.

`<JC minutes speed>` - Start the fast clock with a specified time 

Parameters:
minutes: = time in minutes since midnight. i.e. (hours * 60) + mins
speed: = the perceived speed factor

Response: <jC minutes>
where
minutes: = time in minutes since midnight. i.e. (hours * 60) + mins

Example:

<JC 375 4> Will set the fast clock time as 6:15am with the percieved speed factor of 1 minute every 15 seconds (4 times actual).

`<JC>` - Request the fast clock current time 

Response: <jC minutes>
where
minutes: = time in minutes since midnight. i.e. (hours * 60) + mins

Writing Configuration Variable (CVs)

Writing CVs - Program on the main 

`` - Write Configuration Variable (CV) bit on main track 

Parameters:
> cab: DCC Address of the decoder/loco. The short (1-127) or long (128-10293) address of the engine decoder
> cv: The number of the Configuration Variable memory location in the decoder to write to (1-1024)
> bit: ???
> value: The value to be written to the Configuration Variable memory location (0-255)

Response: N/A

`<w cab cv value>` - Write Configuration Variable (CV) on main track 

Parameters:
> cab: DCC Address of the decoder/loco. The short (1-127) or long (128-10293) address of the engine decoder
> cv: The number of the Configuration Variable memory location in the decoder to write to (1-1024)
> value: The value to be written to the Configuration Variable memory location (0-255)

Response: N/A

Reading/Writing Configuration Variables (CVs) - Programming track 

Note

By design, for safety reasons, the NMRA specification prevents locos from responding to throttle or function commands while on the service track. A loco WILL NOT MOVE on the service track! Don’t let the little ‘jumps’ you may see when you are programming a CV confuse you. The loco pulses the motor to give a jump in current that we read as an ‘ACK’ (acknowledgment), that causes some locos to stutter ahead slightly every time you read or write a CV.

`<R cv>` - Read Configuration Variables (CVs)

Parameters:
> cv: CV number

Response:
<v cv value>
> cv: The number of the Configuration Variable memory location in the decoder (1-1024)
> value: one of
• value of the CV
• -1: if the write failed

Example: <v 1 3> shows that the value 3 is stored in CV 1.
Example: <v 1 -1> shows that reading the value stored in CV 1 failed.

`<R>` - Read DCC decoder (cab) address 

Response:
<r -cab>
> cab:
• DCC Address of the decoder/loco. The short (1-127) or long (128-10293) address of the engine decoder
• -1 = failed read

Example Responses:
Response (successful): <r cab>
Response (fail): <r -1>

Notes:

IMPORTANT: If the loco is on a consist, the address returned will be the consist address

When combined with the <D ACK ON> Command, the <R> Command (with or without parameters) can be used for diagnostics, for example when you get a “-1” response. (See Diagnosing Issues** for more help)

`<V cv bit onOff>` - Verify/Read bit of Configuration Variable (CV) with guessed value 

Parameters:
> cv: CV number
> bit: bit to verify in the CV
> onOff: one of
 • 1=on
 • 0=off

Response:
<v cv bit onOff>
> cv: CV number
> bit: bit to verify in the CV
> onOff: one of
 • 1=on
 • 0=off
 • -1=error

Example: <v 1 3 1> shows that the value 1 is stored in bit 3 of CV 1.
Example: <v 1 3 -1> shows verifying the value stored in bit 3 of CV 1 failed.

Notes:

This command is designed to offer faster verification of the value held in a CV and can be used instead of the <R> commands. Instead of reading a bit value, it compares the bit to an expected value. It will attempt to verify the value first, an if it is successful, will return the value as if it was simply “read”. If the verify fails, it will perform a read bit command (see above) and return the value read.

`<V cv value>` - Verify/Read of Configuration Variable (CV) with guessed value 

Parameters:
> cv: CV number
> value: value to verify

Response:
<v cv value>
> cv: CV number
> value: one of
• actual value of the CV
• -1: if the verify failed

Example: <v 1 3> shows that the value 3 is stored in CV 1.
Example: <v 1 -1> shows verifying the value stored in CV 1 failed.

Notes:

This command is designed to offer faster verification of the value held in a CV and can be used instead of the <R> commands. Instead of reading a byte value or looking at each bit, it compares the byte to an expected value. It will attempt to verify the value first, and if it is successful, will return the value as if it was simply “read”. If the verify fails, it will perform a read byte command (see above) and return the value read.

`` - Write bit to Configuration Variable (CV)

Parameters:
> cv: CV number
> bit: bit to change in the CV
> onOff: one of
 • 1=on
 • 0=off

Response:
<r0|0|cv bit onOff>
> cv: CV number
> bit: bit changed
> onOff: one of
 • 0|1
 • -1: if the write failed

Example: <r0|0|1 3 1> shows that the value 1 was written to bit 3 of CV 1.
Example: <r0|0|1 3 -1> shows that writing to bit 3 of CV 1 failed.

Notes:

The response is a legacy DCC++ formatted response that is hard to parse, and it is recommended to write full CVs where possible.

`<W cv value>` - Write Configuration Variable (CV)

Parameters:
> cv: CV number
> value: value to change the CV to

Response:
<r cv value>
> cv: CV number
> value: one of
• value CV was changed to
• -1: if the write failed

Example: <r 1 3> shows that the value 3 was written to CV 1.
Example: <r 1 -1> shows writing a value to CV 1 failed.

`<W address>` - Write DCC address to cab (loco)

Parameters:
> address: DCC Address of the decoder/loco

Response:
<w address>
> address: one of
• DCC Address of the decoder/loco
• -1 = failed read

Response (successful): <w cab>
Response (fail): <w -1>

Notes:

Writes, and then verifies, the address to decoder of an engine on the programming track. This involves clearing any consist and automatically setting a long or short address. This is an easy way to put a loco in a known state to test for issues like not responding to throttle commands when it is on the main track.

`` - Writes a DCC packet to the PROG track 

Writes a DCC packet of two, three, four, or five hexadecimal bytes to a register driving the selected track.

Parameters:
> register: ignored
> byte1: first hexadecimal byte in the packet
> byte2: second hexadecimal byte in the packet
> byte3: optional third hexadecimal byte in the packet
> byte4: optional fourth hexadecimal byte in the packet
> byte5: optional fifth hexadecimal byte in the packet

Response:
N/A

Notes:

register for backwards compat (can not be removed because number of arguments is unknown)

`` - Deprecated, please use <W cv value> instead 

Parameters:
> cv: The number of the Configuration Variable memory location in the decoder to write to (1-1024 ).
> bit: The bit number of the Configuration Variable memory location to write (0-7)
> value: The value to be written to the Configuration Variable memory location (0-255)
> callbacknum: An arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs that call this function.
> callbacksub: a second arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs (e.g. DCC-EX Interface) that call this function.

Response: <r callbacknum|callbacksub|cv value>

`<W cv value callbacknum callbacksub>` - Deprecated, please use <w cv value> instead 

Parameters:
> cv: The number of the Configuration Variable memory location in the decoder to write to (1-1024 ).
> value: The value to be written to the Configuration Variable memory location (0-255)
> callbacknum: An arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs that call this function.
> callbacksub: a second arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs (e.g. DCC-EX Interface) that call this function.

Response: <r callbacknum|callbacksub|cv value>

`<R cv callbacknum callbacksub>` - Read Configuration variable byte 

Parameters:
> cv: The number of the Configuration Variable memory location in the decoder to write to (1-1024 ).
> callbacknum: An arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs that call this function.
> callbacksub: a second arbitrary integer (0-32767) that is ignored by the Command Station and is simply echoed back in the output - useful for external programs (e.g. DCC-EX Interface) that call this function.

Response: <r callbacknum|callbacksub|cv value>

Notes:

If specified with parameters, reads a Configuration Variable from the decoder of an engine on the programming track. If no parameters are specified, it returns the Address of the loco on the programming track.

Write direct DCC packet 

Warning

THESE ARE FOR DEBUGGING AND TESTING PURPOSES ONLY. DO NOT USE UNLESS YOU KNOW HOW TO CONSTRUCT NMRA DCC PACKETS - YOU CAN INADVERTENTLY RE-PROGRAM YOUR ENGINE DECODER

`<M register hex1 hex2 [hex3 [hex4 [hex5]]]>` - Write a DCC packet the MAIN track 

Writes a DCC packet of two, three, four, or five hexadecimal bytes to a register driving the selected track.

Parameters:
> register: ignored
> byte1: first hexadecimal byte in the packet
> byte2: second hexadecimal byte in the packet
> byte3: optional third hexadecimal byte in the packet
> byte4: optional fourth hexadecimal byte in the packet
> byte5: optional fifth hexadecimal byte in the packet

Response:
N/A

Notes:

register for backwards compat (can not be removed because number of arguments is unknown)

Programming track - Tuning 

`<D ACK LIMIT mA>` - Sets the ACK limit 

Use this command to override the minimum milliamps (mA) required to detect the ACK pulse, e.g. <D ACK LIMIT 30> means a minimum 30mA pulse would be accepted.

Parameters:
> mA: currently limit in milliamps

Response: N/A

Notes:

The Ack current limit is set according to the DCC standard(s) of 60mA. Most decoders send a quick back and forth current pulse to the motor to generate this ACK. However, some modern motors (N and Z scales) may not be able to draw that amount of current. You can adjust down this limit. Or, if for some reasons your acks seem to be too “trigger happy” you can make it less sensitive by raising this limit.

`<D ACK MIN µS>` - Sets the ACK pulse minimum 

As above, however overriding the maximum amount of time for a pulse, e.g. <D ACK MAX 20000> means a pulse up to 20ms would be accepted.

Parameters:
> µS: ACK pulsedureation in milliseconds lower bound

Response: N/A

Notes:

The NMRA specifies that the ACK pulse duration should be 6 milliseconds, which is 6000 microseconds (µS), give or take 1000 µS. That means the minimum pulse duration is 5000 µS and the maximum is 7000 µS. There are many poorly designed decoders in existence so DCC-EX extends this range from 4000 to 8500 µS. If you have any decoders that still do not function within this range, you can adjust the ACK MIN and ACK MAX parameters.

`<D ACK MAX µS>` - Sets the ACK pulse maximum 

Use this command to override the minimum amount of time in microseconds (uS) the pulse needs to be active for, e.g. <D ACK MIN 2000> means a pulse of 2ms or more would be accepted.

Parameters:
> µS: ACK pulse duration in milliseconds upper bound

Response:
N/A

Notes:
see MIN

`<D ACK RETRY num>` - Adjust ACK retries 

When reading/writing CVs, the program will try again upon failure. The default is <D ACK RETRY 2>, which means 3 attempts before a failure is reported. Each of the unsuccessful attempts is reported in the Serial Monitor or JMRI monitor log. The last unsuccessful attempt remains on the display if in use. To reset the running total, send the command manually: <D ACK RETRY 2>.

Parameters:
> num: Number of times to retry

Response: N/A

Notes:

When combined with the <D ACK ON> Command, the <R> Command (with or without parameters) can be used for diagnostics, for example when you get a “-1” response. (See Diagnosing Issues** for more help)

`<D PROGBOOST>` - Override prog track limit while idle 

By default, the programming track has a current limit enabled of 250mA, so any programming activities requiring more than this value will cause power to the programming track to be cut for 100ms. Run this command to override this if programming decoders trigger current limiting on the programming track.

Response: N/A

Notes:

When the programming track is switched on with <1> or <1 PROG> it will normally be restricted to 250mA according to NMRA standards. Some loco decoders require more than this, especially sound versions. <D PROGBOOST> temporarily removes this limit to allow the decoder to use more power. The normal limit will be re-imposed when the programming track is switched off with <0> or <0 PROG> or the Command Station is reset.

Configuring the EX-CommandStation 

Turnouts/Points (Configuring the EX-CommandStation)

The Turnout/Point commands provide a more flexible and more functional way of operating turnouts/points. It requires that the turnout/point be pre-defined through the <T ...> commands, described below.

Turnouts may be in either of two states: Closed or Thrown. The turnout/point commands below use the values 1 for Throw or Thrown and 0 for Close or Closed.

General notes:

vpin is the pin number of the output to be controlled by the turnout/point object. For Arduino output pins, this is the same as the digital pin number. For servo outputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 100-115 for servos attached to the first PCA9685 Servo Controller module, 116-131 for the second PCA9685 module, 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module.

`<T id DCC addr subaddr>` - Define turnout/point on a DCC Accessory Decoder with the specified address and subaddress 

Parameters:
> id: identifier of the Turnout/Point
> addr: ranges from 0 to 511
> subaddr: ranges from 0 to 3

Response: ???

Examples: (click to show)
Example: <T 23 DCC 5 0>

Example: You have a turnout on your main line going to warehouse industry. The turnout is controlled by an accessory decoder with a address of 123 and is wired to output 3. You want it to have the ID of 10. You would send the following command to the CommandStation: <T 10 DCC 123 3>

This Command means:

T = (Upper case T) Define a Turnout

DCC = The turnout is DCC Accessory Decoder based

10 = ID number I am setting to use this turnout

123 = The accessory decoders address

3 = The turnout is wired to output 3

Next you would send the following command to the EX-CS: <E>

This Command means:

E : (Upper case E) Store (save) this definition to EEPROM

`<T id DCC linearAddr>` - Define turnout/point on a DCC Accessory Decoder with the specified linear address 

Parameters:
> id: identifier of the Turnout/Point
> linearAddr: ranges from 1 (address 1/subaddress 0) to 2044 (address 511/subaddress 3).

Response: ???

Example: <T 23 DCC 44> (corresponds to address 11 subaddress 3)

`<T id VPIN vpin>` - Define turnout/point output on specified vpin 

Parameters:
> id: unique Id for the servo
> vpin: vpin to which the servo is attached

Response:
Successful: <O>
Fail: <X>

Example: <T 25 VPIN 30> defines a turnout/point that operates Arduino digital output pin D30.
Example: <T 26 VPIN 164> defines a turnout/point that operates the first pin on the first MCP23017 GPIO expander (if present).

Notes:

See vpin notes above.

This may be used for controlling Arduino digital output pins or pins on an I/O Extender.

`<T id SERVO vpin thrownPos closedPos profile>` - Define turnout/point servo (PWM) on specified vpin 

Parameters:
> id: unique Id for the servo
> vpin: vpin to which the servo is attached
> thrownPos: the PWM value corresponding to the servo position for THROWN state, normally in the range 102 to 490
> closedPos: the PWM value corresponding to the servo position for CLOSED state, normally in the range 102 to 490
> profile: one of
 • 0=Instant,
 • 1=Fast (0.5 sec),
 • 2=Medium (1 sec),
 • 3=Slow (2 sec) and
 • 4=Bounce (subject to revision)

Response:
Successful: <O>
Fail: <X>

Example: <T 24 SERVO 100 410 205 2> defines a servo turnout/point on the first PCA9685 pin, moving at medium speed between positions 205 and 410.

Notes:

Servos are not supported on the minimal HAL (Uno or Nano target).

See vpin notes above.

The active and inactive positions are defined in terms of the PWM parameter (0-4095 corresponds to 0-100% PWM). The limits for an SG90 servo are about 102 to 490. The standard range of 1ms to 2ms pulses correspond to values 205 to 409.
Profile defines the speed and style of movement: 0=Instant, 1=Fast (0.5 sec), 2=Medium (1 sec), 3=Slow (2 sec) and 4=Bounce (subject to revision).

`<T id> - Deletes a turnout by Id`

Parameters:
> id: unique Id for the servod

Response:
Successful: <O>
Fail: <X> (Id does not exist)

`<D SERVO vpin value [profile]>` - Set servo position to value on pin vpin 

Parameters:
> vpin: vpin to which the servo is attached
> value: position to mve the servo to
> profile: one of
    • 0 = instant
    • 1 = fast
    • 2 = medium
    • 3 = slow
    • 4 = bounce

Response: N/A

Notes:

See vpin notes above.

`<T id addr subaddr>` - Define a turnout on a DCC Accessory Decoder with the specified address and subaddress - Legacy command Deprecated 

Parameters:
> id: identifier of the Turnout/Point
> addr: ???
> subaddr: ???

Response: ???

Version Deprecated: ???

`<T id vpin activePos inactivePos>` - Define a turnout/point servo on specified vpin - Legacy command Deprecated 

Parameters:
> id: identifier of the Turnout/Point
> vpin: vpin of the input to be controlled by the sensor object
> activePos: ???
> inactivePos: ???

Response: ???

Version Deprecated: ???

Notes:

See vpin notes above.

The positions are the same as for the turnout/point servo command above. Note: Servos are not supported on the minimal HAL (Uno or Nano target).

Once all turnouts have been properly defined, Use the <E> command to store their definitions to EEPROM. If you later make edits/additions/deletions to the turnout definitions, you must invoke the <E> command if you want those new definitions updated in the EEPROM. You can also ERASE everything; (turnouts, sensors, and outputs) stored in the EEPROM by invoking the <e> (lower case e) command. WARNING: (There is no Un-Delete)

If turnout definitions are stored in EEPROM, the turnout thrown/closed state is also written to EEPROM whenever the turnout is switched. Consequently, when the EX‑CommandStation is restarted the turnout outputs may be set to their last known state (applicable for Servo and VPIN turnouts). This is intended so that the servos don’t perform a sweep on power-on when their physical position does not match initial position in the CommandStation.

Turntables/Traversers (Configuring the EX-CommandStation)

The Turntable/Traverser commands provide a more flexible and functional way of operating turntables/traversers. These require that the turntable/traverser be pre-defined through the  commands, described below.

Note that a turntable/traverser object must be created using the appropriate  command, and then each desired position must be added using the  command.

Turntables/traversers may be located at positions from 0 (also known as home) through 48. A common angle of separation for tracks radiating out from the turntable is 7.5 degrees, hence the need for allowing up to 48 positions to be defined.

It is anticipated that throttle developers will be able to “draw” turntables with a visual representation of the location of the home and various defined positions, hence the reason for including an angle or home variable when defining turntables and positions below. Valid angles are from 0 to 3600, where 3600 = the full 360 degrees, allowing for a single decimal place to be used if partial angles are required. Throttle developers simply need to divide by 10 to obtain the appropriate angle.

General notes:

If there is no desire for throttles to know or understand a position’s angle from home, simple set any instance of the angle or home variable to 0 (zero).

`` - Define a DCC accessory turntable/traverser 

Parameters:
> id: unique Id for the turntable/traverser (1 - 32767)
> home: angle of the home position (0 - 3600)

Response:
Successful: 
Fail: <X>

Example:  defines a DCC accessory turntable/traverser with a 0 degree home angle.
Example:  defines a DCC accessory turntable/traverser with a 5 degree home angle.

`` - Define an EX-Turntable turntable/traverser 

Parameters:
> id: unique Id for the turntable/traverser (1 - 32767)
> vpin: the Vpin of the EX-Turntable device (must exist and be operational)
> home: angle of the home position (0 - 3600)

Response:
Successful: 
Fail: <X>

Example:  defines an EX-Turntable turntable/traverser at Vpin 600 with a 0 degree home angle.
Example:  defines an EX-Turntable turntable/traverser at Vpin 600 with a 5 degree home angle.

`` - Add a position to a turntable/traverser 

Parameters:
> id: id of the turntable/traverser the position is being added to
> position: position index (1 - 48)
> value: either the number of steps from home for EX-Turntable (1 - 32767), or the linear DCC address for a DCC accessory turntable/traverser
> angle: angle from home for the position (0 - 3600)

Response:
Successful: 
Fail: <X>

Example: This example defines a DCC accessory device, with 3 positions:
 // defines a DCC accessory turntable/traverser with a 0 degree home angle.
 // adds position 1, which is at linear DCC address 201, and 10 degrees from home.
 // adds position 2, which is at linear DCC address 202, and 45 degrees from home.
 // adds position 3, which is at linear DCC address 203, and 190 degrees from home.
Example: This example defines an EX-Turntable device, with 3 positions:
 // defines an EX-Turntable turntable/traverser with a 5 degree home angle.
 // adds position 1, which is 200 steps from home, and 10 degrees from home.
 // adds position 2, which is 1500 steps from home, and 45 degrees from home.
 // adds position 3, which is 8000 steps from home, and 190 degrees from home.

Sensors (Configuring the EX-CommandStation)

EX‑CommandStation supports Sensor inputs that can be connected to any Arduino Pin not in use by this program, as well as pins on external I/O expanders and other devices. Physical sensors can be of any type (infrared, magnetic, mechanical…). They may be configured to pull-up or not. When configured for pull-up, the input is connected (within the CS) to +5V via a resistor. This sort of input is suited to sensors that have two wires (a switch or relay contacts, or a device with an ‘open collector’ or ‘open drain’ output. Some sensors may be sensitive to the pull-up resistor and not operate as expected - in this case you can turn off the pull-up.

The sensor is considered INACTIVE when at +5V potential, and ACTIVE when the pin is pulled down to 0V.

To ensure proper voltage levels, some part of the Sensor circuitry MUST be tied back to the same ground as used by the Arduino.

The Sensor code utilises debouncing logic to eliminate contact ‘bounce’ generated by mechanical switches on transitions. This avoids the need to create smoothing circuitry for each sensor. You may need to change the parameters in Sensor.cpp through trial and error for your specific sensors, but the default parameters protect against contact bounces for up to 20 milliseconds, which should be adequate for almost all mechanical switches and all electronic sensors.

To monitor one or more Arduino pins for sensor triggers, first define/edit/delete sensor definitions using the following variation of the <S> command:

`<S id vpin pullup>` - Create a new sensor ID 

Parameters:
> id: identifier of the Sensor (0-32767) (You pick the ID & they are shared between Turnouts, Sensors and Outputs)
> vpin: vpin of the input to be controlled by the sensor object For Arduino input pins, this is the same as the digital pin number. For servo inputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module.
> pullup: one of
• 1=Use pull-up resistor ACTIVE=LOW
• 0=don’t use pull-up resistor ACTIVE=HIGH

Response:
Successful: <O>
Fail: <X> (e.g. out of memory)

Notes:

Once defined, the EX-CS will send a <Q id> response anytime the sensor is activated, and a <q id> response when deactivated.

It is worthwhile creating new IDs to define sensors, for JMRI, using vpin=id. It will simplify your life.

`<S id>` - Delete defined sensor 

Parameters:
> id: identifier of the Sensor (0-32767)

Response:
Successful: <O>
Fail: <X> (e.g. ID does not exist)

Once all sensors have been properly defined, use the <E> (upper case E) command to store their definitions to EEPROM. If you later make edits/additions/deletions to the sensor definitions, you must invoke the <E> (upper case E) command if you want those new definitions updated in the EEPROM. You can also clear everything (turnouts, sensors, and outputs) stored in the EEPROM by invoking the <e> (lower case e) command. (There is NO UN-Delete)

All sensors defined as per above are repeatedly and sequentially checked within the main loop of this sketch. If a Sensor Pin is found to have transitioned from one state to another, one of the following serial messages are generated:

<Q id> - for transition of Sensor ID from INACTIVE state to ACTIVE state (i.e. the sensor is triggered)
<q id> - for transition of Sensor ID from ACTIVE state to INACTIVE state (i.e. the sensor is no longer triggered)

Depending on whether the physical sensor is acting as an “event-trigger” or a “detection-sensor”, you may decide to ignore the <q id> return and only react to <Q id> triggers.

`</ LATCH vpin>` - Lock sensor ON, preventing external influence 

Lock sensor ON, preventing external influence, valid IDs are in the range 0 - 255.

Parameters:
> vpin: identifier of the Sensor (0-255)

Response:
Successful: ?
Fail: ?

`</ UNLATCH vpin>` - Unlock sensor, returning to current external state 

Unlock sensor, returning to current external state, valid IDs are in the range 0 - 255.

Parameters:
> vpin: identifier of the Sensor (0-255)

Response:
Successful: ?
Fail: ?

Refer to the LATCH/UNLATCH commands in the Sensors/Inputs - Reading and Responding section below for further details.

Outputs (Configuring the EX-CommandStation)

EX‑CommandStation supports optional OUTPUT control of any unused Arduino Pins for custom purposes. Pins can be activated or de-activated. The default is to set ACTIVE pins HIGH and INACTIVE pins LOW. However, this default behaviour can be inverted for any pin in which case ACTIVE=LOW and INACTIVE=HIGH.

Definitions and state (ACTIVE/INACTIVE) for pins are retained in EEPROM and restored on power-up. The default is to set each defined pin to active or inactive according to its restored state. However, the default behaviour can be modified so that any pin can be forced to be either active or inactive upon power-up regardless of its previous state before power-down.

To have EX‑CommandStation utilise one or more Arduino pins as custom outputs, first define/edit/delete output definitions using the following variation of the <Z> command, or the lowercase <z> command can be used with no pre-definition required.

`<z vpin> or <z -vpin>` - Control an output pin; no setup required 

Parameters for the lowercase z command:
> vpin: the pin or vpin number of the output
• positive vpin = ACTIVE/HIGH
• negative vpin = INACTIVE/LOW

Response: N/A

`<Z id vpin iflag>` - Creates a new output ID, with specified PIN and IFLAG values 

Parameters:
> id: identifier of the output
> vpin: the pin number of the output to be controlled by the output object. For Arduino output pins, this is the same as the digital pin number. For servo outputs and I/O expanders, it is the pin number defined for the HAL device (if present), for example 100-115 for servos attached to the first PCA9685 Servo Controller module, 116-131 for the second PCA9685 module, 164-179 for pins on the first MCP23017 GPIO expander module, and 180-195 for the second MCP23017 module.
> iflag: see below

iflag, bit 0:
 • 0 = forward operation (ACTIVE=HIGH / INACTIVE=LOW)
 • 1 = inverted operation (ACTIVE=LOW / INACTIVE=HIGH)
iflag, bit 1:
 • 0 = state of pin restored on power-up to either ACTIVE or INACTIVE depending on state before power-down.
 • 1 = state of pin set on power-up, or when first created, to either ACTIVE of INACTIVE depending on IFLAG, bit 2
iflag, bit 2:
 • 0 = state of pin set to INACTIVE upon power-up or when first created
 • 1 = state of pin set to ACTIVE upon power-up or when first created

Response:
Successful: <O>
Fail: <X> (e.g. out of memory).

Notes:

if output ID already exists, it is updated with specified vpin and iflag.

Output state will be immediately set to ACTIVE/INACTIVE and pin will be set to HIGH/LOW according to iflag value specified (see below).

`<Z id>` - Deletes definition of output ID 

Parameters:
> id: identifier of the output to delete

Response:
Successful: <O>
Fail: <X> (e.g. ID does not exist)

`<Z>` -Lists all defined output pins 

Response:
Successful: <Y id vpin iflag state> repeated for each defined output pin
Fail: <X> (e.g. ID does not exist)

`<Z id state>` - Sets output ID to either INACTIVE or ACTIVE state 

Parameters:
> id: identifier of the output
> state: one of
• 0= INACTIVE
• 1= INACTIVE

Response:
Successful: <Y id state>
Fail: <X> if output ID does not exist

Notes:

When controlled as such, the Arduino updates and stores the direction of each output in EEPROM so that it is retained even without power. A list of the current states of each output in the form <Y id state> is generated by EX‑CommandStation whenever the <s> status command is invoked. This provides an efficient way of initializing the state of any outputs being monitored or controlled by a separate interface or GUI program.

Once all outputs have been properly defined, use the <E> Upper Case “E” command to store their definitions to EEPROM. If you later make edits/additions/deletions to the output definitions, you must invoke the <E> command if you want those new definitions updated in the EEPROM. You can also ERASE everything (turnouts, sensors, and outputs) stored in the EEPROM by invoking the <e> (lower case e) command. (There is no Un-Delete)

EEPROM Management (Configuring the EX-CommandStation)

`<D EEPROM>` - Diagnostic dump EEPROM contents 

Response: ???

`<e>` - Erase ALL (turnouts, sensors, and outputs) from EEPROM 

Response:
<O>

`<E>` - Store definitions to EEPROM 

Response:
<O>

Diagnostic Programming Commands (Configuring the EX-CommandStation)

`<D ACK state>` - Enables ACK diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response:
“Ack diag on” or “Ack diag off”
Displayed on the serial monitor only.

Notes:

This will turn ACK diagnostics ON and then try to read the appropriate CVs to determine your loco address.

`<D CMD state>` - Enables Command Parser diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response: N/A

Notes:

When enabled, diagnostic messages will be shown on the the Serial Monitor.

`<D ETHERNET state>` - Enables Ethernet diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response: N/A

Notes:

When enabled, diagnostic messages will be shown on the the Serial Monitor.

`<D LCN state>` - Enables LCN interface diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response: N/A

`<D WIFI state>` - Enables WiFi diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response: N/A

Notes:

When enabled, diagnostic messages will be shown on the the Serial Monitor.

`<D WIT state>` - Enables WiThrottle diagnostics 

Parameters:
> state: one of
• ON
• OFF

Response: N/A

Notes:

When enabled, diagnostic messages will be shown on the the Serial Monitor.

`<D CABS>` - Shows cab numbers and speed in reminder tables 

Response:
“Used=xxx, max=yyy”
Displayed on the serial monitor only.

`<D HAL SHOW>` - Shows configured servo board and GPIO extender board config and used pins 

Response:
List the configured I/O drivers in the Hardware Abstraction Layer (HAL). This command is available from Version 3.2.0.

Examples

Example output showing a connected PCA9685 Servo controller and an MCP23017 I/O expander:
<* PARSING:D HAL SHOW * >
<* Arduino Vpins:2-69 * >
<* PCA9685 I2C:x40 Configured on Vpins:100-115 * >
<* PCA9685 I2C:x41 Configured on Vpins:116-131 OFFLINE * >
<* MCP23017 I2C:x20 Configured on Vpins:164-179 * >
<* MCP23017 I2C:x21 Configured on Vpins:180-195 * >

`<D RAM>` - Shows remaining RAM (Free Memory)

Response:
“Free memory=xxxx”
Displayed on the Serial Monitor only.

I/O (HAL) Diagnostics 

`<D ANIN vpin>` - Read and display pin vpin’s analogue value 

Parameters:
> vpin: ??

Response: ???

`<D ANOUT vpin value [param2]>` - Write value to analogue vpin 

Write value to analogue pin vpin, supplying param2 to the driver.

Parameters:
> vpin: ??
> value: ??
> param2: ??

Response: ???

Parameters:
> cmd: user defined command

Response: N/A