WiThrottle Protocol Specification

Technical reference for the WiThrottle™ network protocol as used by mobile throttle apps (Engine Driver, WiThrottle for iOS, …) and JMRI-class servers.

Sources: - JMRI WiThrottle Protocol — Protocol.shtml. Normative description of commands, delimiters, and the MultiThrottle model implemented by JMRI's jmri.jmrit.withrottle package. - flash62au/WiThrottleProtocol (Arduino/ESP32 client library) — github.com/flash62au/WiThrottleProtocol, library docs. De-facto reference for client behaviour: heartbeat handling, command pacing, MultiThrottle command builders, and parsing edge cases on real hardware (JMRI, Digitrax LNWI, RailBOX RB1110).

Conventions: - Commands and responses are plain ASCII text, one logical message per line. - Examples show the payload only; each line is terminated by a newline (see §2.2). - Loco addresses are written Snnn (short, 1–127) or Lnnn (long, 128–10239). - WiThrottle™ is a trademark; message formats reproduced here are for interoperability.

Overview & design philosophy

Transport & discovery

Framing & delimiters

Connection lifecycle

Initial server messages

Client registration & heartbeat

MultiThrottle model

Locomotive acquisition & release

Throttle actions

Server property notifications

Track power

Turnouts / points

Routes

Consists (roster & advanced)

Fast clock

Alerts, server identity & misc

Deprecated & auxiliary commands

Client implementation notes

BigFred mapping

Appendix A – Command quick reference

Appendix B – Worked examples

1 Overview & design philosophy

WiThrottle is a client–server, line-oriented text protocol over TCP/IP. A server (JMRI, Digitrax LNWI, RailBOX RB1110, …) owns the connection to the DCC command station; clients (mobile throttles, hardware panels, automation scripts) send terse single-line commands and receive asynchronous updates.

Design properties:

Unlike LocoNet (§ peer bus) or Z21 LAN (§ binary UDP), WiThrottle is intentionally simple for mobile apps: no checksums, no slot numbers — the server maps loco addresses to command-station resources internally.

2 Transport & discovery

2.1 TCP connection

JMRI and most servers accept a single long-lived connection per client. The client should send Q before closing so the server can release throttles promptly.

2.2 Line termination

Each command or response is one line. A line ends with:

Both peers must accept any of the above as end-of-line. JMRI commonly emits two consecutive newlines after some responses; robust clients trigger on the first terminator and discard the second empty line (WiThrottleProtocol.cpp check()).

There is no escape mechanism — command text must not contain raw newline characters.

2.3 Service discovery (mDNS / Bonjour)

Clients may locate servers with a multicast DNS browse for:

_withrottle._tcp.local

Discovery is best-effort (depends on OS, firewall, and VLAN isolation). Production clients should always allow manual host + port entry. Engine Driver and WiThrottle for iOS both support mDNS and static configuration.

2.4 Known server deployments

3 Framing & delimiters

WiThrottle packs structured data into flat strings using fixed three-character delimiters (defined in WiThrottleProtocol.h):

3.1 Roster example

Two roster entries:

RL2]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L

Parsed as:

The count after RL (2) must match the number of ]\[-delimited entries. S vs L in the third field indicates short vs long DCC address format for that roster entry.

3.2 MultiThrottle example

Add long-address loco 341 to throttle 0, referencing roster entry D&RGW 341:

M0+L341<;>ED&RGW 341

The part before <;> is the acquisition key (+L341); the part after is the address selector passed to the server's throttle controller (ED&RGW 341).

4 Connection lifecycle

Typical client sequence:

Ordering notes:

• Some servers (including JMRI) defer the §5 initial burst until the client sends HU and/or N.
• HU must be unique per simultaneous connection — duplicate IDs may be rejected. Mobile apps typically use a random UUID string.
• N sets the human-readable name shown in the server's WiThrottle window.
• The server replies to N with *«seconds» — the emergency-stop timeout if no further commands arrive (§6).

5 Initial server messages

After connect (and often after HU / N), the server may send one line per topic. Lines can arrive in any order; clients should parse by two- or three-letter prefix.

5.1 Protocol version — VN

VN2.0

Engine Driver requires ≥ 2.0. Syntax before 2.0 used deprecated single-throttle T / S / MT prefixes (§17).

5.2 Roster list — RL

RL0
RL2]\[RGS 41}|{41}|{L]\[Test Loco}|{1234}|{L

5.3 Track power — PPA

PPA1

Also used as a client → server command (§11).

5.4 Turnout captions — PTT

PTT]\[Turnouts}|{Turnout]\[Closed}|{2]\[Thrown}|{4]\[Unknown}|{1]\[Inconsistent}|{8

Provides human-readable labels and numeric state codes for turnout feedback (§12). The outer ]\[ pair wraps the global title and per-state entries.

5.5 Turnout list — PTL

PTL]\[LT12}|{Rico Station N}|{1]\[LT324}|{Rico Station S}|{2

PTL alone (no entries) means zero turnouts.

5.6 Route captions — PRT and list — PRL

Same pattern as turnouts:

PRT]\[Routes}|{Route]\[Active}|{2]\[Inactive}|{4]\[Unknown}|{0]\[Inconsistent}|{8
PRL]\[IR:AUTO:0001}|{Rico Main}|{2

Route state codes: 2 = Active, 4 = Inactive, 8 = Inconsistent, 0 / 1 = Unknown (server-dependent).

5.7 Consist list — RCC / RCL / RCD

Header (treat RCC and RCL identically):

RCC2

Per-consist lines (one line each — not the same ]\[ roster pattern):

RCD}|{74(S)}|{74(S)]\[3374(L)}|{true]\[346(L)}|{true

5.8 Web server port — PW

PW12080

JMRI embedded web UI port (informational for clients that deep-link into JMRI).

6 Client registration & heartbeat

6.1 Device ID — HU

HUa1b2c3d4-e5f6-7890-abcd-ef1234567890

6.2 Device name — N

NJohn's Throttle

Any text except newline. Server reply:

*10

6.3 Heartbeat — *

Heartbeat monitoring is off until the client sends *+. While enabled, any valid client command (including *) resets the watchdog. The flash62au client alternates * with re-sending N«name» to force a server response when half the period has elapsed.

6.4 Quit — Q

Q

Client announces disconnect; server should release throttles tied to this session.

7 MultiThrottle model

Protocol 2.0 routes all throttle traffic through M (MultiThrottle) commands. The character immediately after M selects the throttle instance:

Each MultiThrottle instance holds zero or more loco addresses (an on-the-fly "consist" from the protocol's point of view — distinct from NMRA advanced consists in §14). Engine Driver uses 0–6; the flash62au library supports 6 instances (0–5 plus T).

Important: do not mix legacy T-prefixed APIs with 0-prefixed MultiThrottle APIs in one program — legacy code uses defunct throttle id T, modern code uses 0 (library README).

7.1 MultiThrottle command shape

M«throttleId»«operation»«locoKey»<;>«payload»

locoKey is normally Snnn, Lnnn, or * (all locos on this MultiThrottle).

8 Locomotive acquisition & release

8.1 Add locomotive — M…+

M0+S3<;>S3
M0+L341<;>ED&RGW 341

The key address must match the address chosen in the selector; mismatch is undefined (behaviour varies by server).

Server reply (verbose — multiple lines), when successful:

M0+S3<;>
M0LS3<;>]\[Headlight]\[Bell]\[…     (only if loco is in roster)
M0AS3<;>F00
M0AS3<;>F01
…
M0AS3<;>F028
M0AS3<;>V0
M0AS3<;>R1
M0AS3<;>s1

Roster entries include a function-name array (M…L…, §10.2). Ad-hoc addresses skip the label list but still receive F / V / R / s states.

8.2 Remove locomotive — M…−

M0-S3<;>r
M0-*<;>r

Server typically confirms:

M0-S3<;>

8.3 Steal — M…S

Used with Digitrax systems when a loco is already controlled elsewhere.

Requires JMRI ≥ 4.10 for JMRI-backed servers.

9 Throttle actions

Actions are sent as the second part of an M…A command:

M0A*<;>V30
M0AS3<;>F112
M0AL341<;>R0

locoKey before <;> may be * (all locos on throttle) or a specific S/L key. The payload after <;> is a letter + value throttle sub-command.

9.1 Sub-command summary

Function numbers are 0–31 without leading zeros (F10, not F010).

9.2 Speed — V

M0A*<;>V30

During initialization the server may send negative speed values to indicate E-stop state (JMRI); clients should treat that as stopped / E-stop.

9.3 Function press/release — F

Momentary UI buttons send pairs:

M0A*<;>F112
M0A*<;>F012

The server maps press/release to the correct DCC behaviour (momentary whistle vs toggling headlight).

9.4 Force function — f

M0A*<;>f112

Sets absolute on (1) / off (0) regardless of prior state. Server emits M…A notification only when the state actually changes.

9.5 Momentary vs latching — m

M0A*<;>m112
M0A*<;>m012

Overrides roster defaults: m1«fn» = momentary, m0«fn» (or any non-1) = latching. JMRI global preference "F2 always momentary" overrides for F2.

9.6 Speed-step mode — s

M0AS3<;>s1

9.7 Query — q

M0A*<;>qV
M0A*<;>qR

Server answers with M…A notifications (V…, R…) per loco.

9.8 Release & dispatch — r / d

Usually sent as part of M…− (§8.2). On many systems release and dispatch are equivalent; prefer r when unsure.

9.9 Consist lead routing — C / c

M0AL341<;>CL346

Directs function commands to the lead loco L346 when not using CV21/CV22 advanced consist mapping.

10 Server property notifications

Asynchronous M lines inform clients about changes (from other throttles, panels, or automation):

M0AL341<;>F10
M0AL341<;>V23
M0AL341<;>R1
M0AL341<;>s1

10.1 Notification shape — M…A

M«id»A«locoKey»<;>«property»

10.2 Function labels — M…L

M0LL7407<;>]\[Lights]\[Bell]\[Whistle]\[…

Returned after roster acquire. Delimiters: leading ]\[, between labels ]\[, trailing ]\[. Index n in the array maps to Fn (F0 = first label).

10.3 Add/remove notifications — M…+ / M…−

M0+S3<;>
M0-S3<;>

Empty payload after <;> confirms add/remove events.

10.4 Steal prompt — M…S

See §8.3.

11 Track power

11.1 Server → client

Announced in the initial PPA line (§5.3) and on changes.

11.2 Client → server

PPA1
PPA0

Sets track power on/off where the server supports it. Not all command stations expose power control through WiThrottle.

12 Turnouts / points

12.1 Client request — PTA

PTACLT92
PTATLT92
PTA2LT92

JMRI may create unknown turnouts when preference allows; errors return HM… (§16.1).

12.2 Server notification — PTA

PTA2LT92

Broadcast for all turnout changes on the layout, not only those requested by this client.

13 Routes

13.1 Client request — PRA

PRA2IO_RESET_LAYOUT

13.2 Server notification — PRA

PRA2IO_RESET_LAYOUT

14 Consists (roster & advanced)

Two layers:

1. MultiThrottle multi-loco (§7) — protocol-level list on one TCP throttle; no CV programming.
2. NMRA advanced consists — RC commands manipulating decoder CV19 and CV21/22.

14.1 Advanced consist commands — RC

All start with RC:

RC+ fields (JMRI):

RC+<;>S74<;>My consist<:>L341<;>true

Initial RCC / RCD lines (§5.7) describe existing consists.

15 Fast clock

15.1 Server → client — PFT

PFT65871<;>4
PFT1550686525<;>4.0
PFT1550681224<;>0.0

Sent when rate or time changes, and roughly once per fast-clock minute while running. Digitrax LNWI may use the range 0…86400 for time-of-day only.

Extracting HH:MM:SS (JMRI style):

seconds mod 86400 → seconds since midnight

Example: 1607855025 mod 86400 = 37425 → 10:23:45.

16 Alerts, server identity & misc

16.1 Alerts & info — HM / Hm

HMJMRI: address 'L23' not allowed as Long
HmTrain 42 approaching station

No embedded newlines.

16.2 Server type — HT / Ht

HTJMRI
HtJMRI v4.19.8 My JMRI Railroad

Known HT types include JMRI, Digitrax, MRC. Clients may branch on these.

16.3 Unknown commands

Clients must ignore unrecognized lines and continue reading. Servers likewise ignore unknown client commands.

16.4 PFC (LNWI)

Digitrax LNWI may send a PFC line after connect; purpose undocumented in JMRI help. Treat as ignorable.

16.5 AT+CIPSENDBUF= (LNWI artefact)

The flash62au parser strips leading AT+CIPSENDBUF= noise occasionally prepended by LNWI firmware before the real WiThrottle payload.

17 Deprecated & auxiliary commands

17.1 Legacy single-throttle prefixes

Steal examples in older docs use MT+ / MTS; modern clients use M0+ / M0S.

17.2 Raw DCC packet — D

D«hex bytes…»

Sends a hex-encoded packet to the command station (implementation-defined). Rare in mobile clients; useful for scripting through JMRI.

17.3 Panel — P

Prefix for panel operations (handled by JMRI DeviceServer); not used by standard mobile throttles.

17.4 Roster — R

Prefix for roster operations beyond the initial RL list (server-specific).

17.5 C forward

Legacy no-op forwarding to throttle controller — not used in new clients.

18 Client implementation notes

Practices distilled from flash62au/WiThrottleProtocol and field experience:

18.1 Suggested parser structure

1. Read bytes until CR or LF; ignore duplicate empty lines.
2. Match longest prefix first (PFT, PTL, M0A, VN, …) — the flash62au processCommand() ordering is a useful reference.
3. For M messages, branch on character index 2 (+, −, S, A, L).
4. Split remaining fields on <;> then parse action letter (V, F, …).

19 BigFred mapping

BigFred implements an optional inbound WiThrottle TCP server inside the dcc-bus daemon, symmetric to the Z21 inbound UDP server, so Engine Driver and physical WiThrottle handsets drive through the same cmd.Router as the browser throttle. The implementation plan is ../plans/withrottle-server.md. Layout control otherwise uses:

The RB1110 also exposes WiThrottle on TCP 12090 — see RB1110 §6.3. When BigFred owns the command station it binds its own WiThrottle port; BigFred and a vendor WiThrottle server are separate consumers of the same command station and do not share sessions.

19.0 Pairing

Authorization uses a 6-digit numeric code shown in the BigFred UI. The code is entered on the handset through one of two equivalent paths:

1. Function keys — BigFred advertises a sentinel "Pair with BigFred" roster entry to unpaired clients; the user acquires it and presses F1…F9 (one digit each) or F10…F32 (two digits each) in sequence. This mirrors the Z21 function-key pairing flow.
2. Device name — the user sets the Engine Driver Device Name to the code (N122145); BigFred matches it on connect.

The HU device id is the paired client key (withrottle:<deviceId>); sessions survive TCP reconnect without re-pairing. One pilot per user per command station is shared across the Z21 and WiThrottle inbound servers.

19.1 Conceptual mapping

The realized mapping from WiThrottle commands to dcc-bus intents:

19.2 Capability snapshot

Appendix A – Command quick reference

Client → server

Server → client

Appendix B – Worked examples

B.1 Minimal session (short address 3)

→ HU550e8400-e29b-41d4-a716-446655440000
→ NBigFred Test
← *10
← VN2.0
← PPA1
→ *+
→ M0+S3<;>S3
← M0+S3<;>
← M0AS3<;>F00
← M0AS3<;>V0
← M0AS3<;>R1
← M0AS3<;>s1
→ M0A*<;>V20
→ M0A*<;>R1
→ M0A*<;>F11
→ M0A*<;>F01
→ M0-*<;>r
← M0-S3<;>
→ Q

B.2 Long address with roster entry

→ M0+L341<;>ED&RGW 341
← M0+L341<;>
← M0LL341<;>]\[Headlight]\[Bell]\[Whistle]\[…
← M0AL341<;>F00
…
→ M0AL341<;>V45

B.3 Turnout throw

← PTT]\[Turnouts}|{Turnout]\[Closed}|{2]\[Thrown}|{4
← PTL]\[LT92}|{Station North}|{2
→ PTATLT92
← PTA4LT92

B.4 Fast-clock time extraction

← PFT1607855025<;>4.0

1607855025 mod 86400 = 37425 seconds after midnight
37425 s = 10 h 23 min 45 s

B.5 Steal sequence (Digitrax)

Related: z21.md (Z21 LAN), loconet.md (LocoNet), RailBOX RB1110 (WiThrottle port 12090), JMRI WiThrottle Protocol.