CageNut Rails

DCC-EX serial command reference

The DCC-EX text commands worth knowing for setup and diagnosis, typed over USB serial or a TCP connection.

DCC-EX is driven by short text commands wrapped in angle brackets. You can send them over USB serial at 115200 baud, or over a TCP connection to the same port Rocrail uses.

Being able to type directly at the command station is the fastest way to establish whether a fault is in the command station, the track, or the software talking to it.

Check these against your own firmware

DCC-EX command syntax has changed across firmware generations, and some commands accept both an old and a new form. Send <s> first — it reports the version you are actually running — and check anything unexpected against the documentation for that version.

Getting connected

WhatHow
USB serial115200 baud, 8N1. Any terminal — screen, minicom, the Arduino IDE monitor.
Networknc <ip> 2560 — or any raw TCP client.

On Linux:

screen /dev/ttyACM0 115200      # exit with Ctrl-A then K

If /dev/ttyACM0 does not exist, check dmesg | tail after plugging in — it may enumerate as /dev/ttyUSB0 depending on the USB chip.

Status and power

CommandDoes
<s>Status. Reports firmware version and track power state. Start here.
<1>Track power on.
<0>Track power off.
<c>Report current draw on the main track.
<!>Emergency stop everything.

<s> is the single most useful command on this page. If it answers, the command station is alive and you have ruled out half the possible faults in one step.

Driving

CommandDoes
<t CAB SPEED DIR>Set speed and direction. DIR is 1 forward, 0 reverse.
<t CAB -1 DIR>Emergency stop that loco.

SPEED runs 0–126, where 0 is stop. That upper limit is not arbitrary — see 128 vs 28 speed steps for why it is 126 and not 128.

Example — loco 3, half speed, forwards:

<t 3 63 1>

Programming CVs

On the programming track, where you do not need to know the address:

CommandDoes
<R CV>Read a CV.
<W CV VALUE>Write a CV.
<W CAB>Write a locomotive address. Handles CV1 or CV17/18/29 as appropriate.

On the main track, by address:

CommandDoes
<w CAB CV VALUE>Write a CV to a specific loco in place.

Note the case: capital W is the programming track, lowercase w is the main track. It is an easy typo to make and a confusing one to debug, because the lowercase form will silently address a loco that may not be the one you meant.

Reading is only possible on the programming track. If reads fail there while writes succeed, the command station cannot detect the decoder’s acknowledgement pulse — see EX-MotorShield8874 vs the L298N.

Diagnostics

CommandDoes
<D ACK ON>Verbose logging of acknowledgement pulse detection.
<D CABS>List the locos the command station currently knows about.
<#>Report how many simultaneous locos this build supports.

<D ACK ON> is the one to reach for when CV reads are unreliable. It shows what the command station is measuring, which turns “reads don’t work” into an actual number you can reason about.

A diagnostic sequence

When something has stopped working, in order:

  1. <s> — is the command station alive, and what version is it?
  2. <1> — does track power come on?
  3. <c> — is it seeing sensible current, or a short?
  4. <t 3 30 1> — does a known-good loco respond?
  5. <R 8> — can the programming track read anything at all?

Each step rules out a layer. By the end you know whether the problem is the command station, the track, the decoder, or the software talking to it.