LocoNet Protocol Specification

Technical reference for the LocoNet® bus as used by BigFred's loconet_serial and loconet_tcp command-station drivers (pkgs/loco/commandstation/loconet.go).

Sources: - Digitrax LocoNet Personal Use Edition 1.0 (Digitrax Inc., 16 Oct 1997) — PDF. The normative source for the wire protocol, opcodes, and slot model. - SV Programming Message Formats v13 (Digitrax PE 1.0 extension, 2002–2006) — PDF. Defines device (System Variable) programming over OPC_PEER_XFER. - JMRI LnConstants / LocoNetSlot — LnConstants, LocoNetSlot. The de-facto reference for F9–F28 handling, expanded slots (LocoNet 2), and vendor (Intellibox/Uhlenbrock) function opcodes not in PE 1.0. - OpenLCB LocoNet Connections note — old.openlcb.org. How LocoNet messages map onto OpenLCB events/datagrams. - LoconetOverTcp protocol — loconetovertcp.sourceforge.net. The ASCII framing BigFred's loconet_tcp driver speaks. - mrrwa/LocoNet (Arduino embedded library) — github.com/mrrwa/LocoNet. - tanner87661/LocoNetESP32HB (ESP32 hybrid library) — github.com/tanner87661/LocoNetESP32HB.

Conventions: - Bytes are written in hexadecimal (0x.. or bare BF); LocoNet documents classically wrap opcodes in angle brackets, e.g. <BF>. - Bit fields are numbered D7 (MSB) … D0 (LSB). - LocoNet trademarks belong to Digitrax Inc.; message formats reproduced here for interoperability are Copyright Digitrax / Uhlenbrock (see source notes).

Overview & design philosophy

Physical layer

Electrical layer

Network timing & access (CSMA/CD)

Message format

Checksum

Opcode summary

The refresh slot model

Slot data block (OPC_SL_RD_DATA / OPC_WR_SL_DATA)

Loco control messages

Functions above F8 (F9–F28 and beyond)

Expanded slots & LocoNet 2

Address selection & slot lifecycle

Dispatching

Switch & sensor messages

Programming track

Device programming (SV) over OPC_PEER_XFER

Fast clock

Peer-to-peer & immediate packets

LoconetOverTcp framing

Embedded implementations (mrrwa, ESP32HB)

LocoNet ↔ OpenLCB gateways

BigFred mapping

Appendix A – Opcode quick reference

Appendix B – Worked byte examples

1 Overview & design philosophy

LocoNet is a peer-to-peer, event-driven distributed network: every device can monitor all traffic, and there is no central poller in normal operation. Access is arbitrated with CSMA/CD (Carrier Sense Multiple Access with Collision Detection), the same family used by classic Ethernet.

One device — the MASTER (command station) — is privileged only in that it:

• maintains the refresh stack (slots) for DCC packet generation, and
• actively generates the DCC track signal.

All other transactions (throttle ↔ throttle, sensor reports, computer interfaces) flow on the same wire without involving the master, as long as they obey the message format and timing. Devices may join or leave a live bus; the protocol is tolerant of transients and requires no unique device IDs.

This decentralisation is why BigFred sees other throttles' traffic for free: the loconet_serial / loconet_tcp driver observes every speed/direction/function packet on the shared bus, not only those it authored (§23, 16-dcc-bus/09-external-state-observation.md).

2 Physical layer

2.1 RJ12 pinout

BigFred relevance: a throttle-class interface such as the Uhlenbrock 63120 needs only pins 2/5 (ground) and 3/4 (data). Never wire RAIL_SYNC (pins 1 & 6) into the interface's logic — see devices/uhlenbrock-63120.md and hardware/02-loconet-electrical.md.

The two RAIL_SYNC lines carry a low-power copy of the DCC waveform (for boosters); the two LocoNet data lines are paralleled in the single-ended implementation, making the cable polarity-insensitive.

3 Electrical layer

LocoNet is a wired-OR, multiple-access linear network. Single-ended levels:

The idle bus sits at MARK and is RFI-quiet (no traffic unless a device sends). Transmission is half-duplex; transmitters monitor their own transmit echo for collision detection.

4 Network timing & access (CSMA/CD)

4.1 Byte framing

LocoNet bytes are standard asynchronous serial: 1 start bit, 8 data bits, 1 stop bit, LSB first.

A serial-bridge interface (Uhlenbrock 63120, LocoBuffer) handles this 16.66 kBaud wire timing internally; the host sees a conventional UART rate (BigFred: 57600 8N1, §23).

4.2 Carrier detect & collisions

A device seizes the bus only after the CD backoff elapses; the master may seize immediately when CD releases. All transmitters detect collisions via bad transmit echo and emit a 15-bit BREAK, which makes every receiver reset its message parser. Malformed or fragmentary messages are silently ignored; receivers resync on the next opcode byte.

4.3 Disconnect / reconnect & purge

BigFred relevance: to avoid a slot being purged mid-session the driver must re-touch active slots periodically. The <81> (OPC_BUSY) "time burner" NOP sent by some masters should simply be stripped and ignored.

4.4 PC fast access

A PC interface may infer that the bus is free when the last decoded message implies no follow-on response, and seize before the CD backoff elapses, pre-empting other devices. Multiple PCs share access by subdividing the 20-bit CD backoff into priority windows and checking transmit echo + carrier detect.

5 Message format

Every LocoNet message is multi-byte:

<OPCODE> <ARG…> <CHECKSUM>

• The opcode is the first byte and the only byte with D7 = 1.
• All argument bytes and the checksum have D7 = 0 (7-bit payload each).
• Opcode bits D6, D5 encode the message length; D3 flags a follow-on reply:

D3 = 1 implies a follow-on message/reply is expected. The A,B,C,D,F bits encode up to 32 opcodes per length class.

BigFred parser: loconet_proto.go lnMsgLen() decodes (opcode >> 5) & 0x03 to {2,4,6,variable}, and lnStreamParser.PushByte() reconstructs frames from the serial byte stream, resyncing on the next byte with D7 = 1.

6 Checksum

The checksum is the 1's complement of the byte-wise XOR of all message bytes except the checksum itself.

Validation: XOR all bytes including the checksum — a correct message yields 0xFF.

chk      = 0xFF XOR (b0 XOR b1 XOR … XOR b[n-1])
valid?   : (b0 XOR b1 XOR … XOR b[n-1] XOR chk) == 0xFF

BigFred implementation (loconet_proto.go):

func lnChecksumOK(pkt []byte) bool {
    var x byte
    for _, b := range pkt { x ^= b }
    return x == 0xFF
}
// lnAppendChecksum appends chk = x ^ 0xFF

Example: idle frame 83 7C → 0x83 ^ 0x7C = 0xFF. ✓

7 Opcode summary

From the LocoNet PE 1.0 opcode list (opcodes in italics in the source are informational/non-final). Length is implied by the opcode's D6/D5 bits (§5).

7.1 2-byte messages <OPC> <CKSUM>

7.2 4-byte messages <OPC> <ARG1> <ARG2> <CKSUM>

7.3 Variable-length messages <OPC> <COUNT> … <CKSUM>

Opcodes 0xB8–0xBF and 0xA8–0xAF are defined to carry responses. OPC_LONG_ACK (0xB4) <LOPC> is a copy of the opcode being answered (MSB stripped); LOPC = 0 is also a valid "fail" code.

7.4 Extended & vendor opcodes (post-PE 1.0)

These are not in PE 1.0; they come from later Digitrax masters (LocoNet 2, §12) or were reverse-engineered from Uhlenbrock/Intellibox hardware (JMRI LnConstants). An observer on a shared bus must length-decode (§5) and tolerate them.

8 The refresh slot model

The master keeps an array of up to 120 read/write refresh slots. A slot holds up to 10 data bytes describing a locomotive and controls a task in the DCC refresh stack. The slot number is the usual 2nd byte (1st argument) of slot-addressed messages and works like a "file handle".

Slot numbers do not imply a fixed loco address — the master allocates them via address-selection (§13). Up-consisted slots use indirection (the speed byte becomes a pointer to the consist-top slot).

9 Slot data block (OPC_SL_RD_DATA / OPC_WR_SL_DATA)

14-byte message carrying 10 slot data bytes, in transmission order:

<E7|EF> <0E> <SLOT> <STAT1> <ADR> <SPD> <DIRF> <TRK> <SS2> <ADR2> <SND> <ID1> <ID2> <CHK>

BigFred parses this in parseLnSlotData(): addr = (adrLo & 0x7F) | ((adrHi & 0x7F) << 7), reading Speed=pkt[5], DirF=pkt[6], Snd=pkt[10].

9.1 Byte 1 — STAT1 (slot status)

BUSY/ACTIVE (D5,D4):

Consist (D6,D3): 11 = mid-consist (linked up & down), 10 = consist top, 01 = consist sub-member, 00 = free (no consist).

Speed-step / decoder type (D2,D1,D0):

9.2 Byte 2 — ADR (loco address low 7 bits)

Also the ARG2 of OPC_LOCO_ADR <BF>.

9.3 Byte 3 — SPD (speed)

9.4 Byte 4 — DIRF (direction + F0–F4)

BigFred bit helpers (loconet.go getFnFromDirf / setFnInDirf): F0 = 0x10, F1 = 0x01, F2 = 0x02, F3 = 0x04, F4 = 0x08; direction = 0x20.

9.5 Byte 5 — TRK (global track status)

9.6 Byte 6 — SS2 (status 2)

9.7 Byte 7 — ADR2 (loco address high 7 bits)

0 ⇒ low byte is a short 7-bit NMRA address. Non-zero ⇒ long 14-bit address (maps to CV17/CV18). A DT200 master always treats this as 0.

9.8 Byte 8 — SND (sound / F5–F8)

BigFred bit helpers (getFnFromSnd / setFnInSnd): F5 = 0x01, F6 = 0x02, F7 = 0x04, F8 = 0x08.

9.9 Bytes 9–10 — ID1 / ID2

Two 7-bit values forming a 14-bit device-usage ID:

10 Loco control messages

Once a slot is allocated (§13), real-time control uses three 4-byte messages keyed by slot number:

These do not elicit a response. Because they are slot-keyed, an observer must map slot → address (via a prior slot read) to attribute the change — BigFred keeps a reverse slotAddr map for exactly this (loconet.go slotToAddr).

BigFred builders (loconet_proto.go): lnBuildSetSpeed, lnBuildSetDirF, lnBuildSetSnd each append the checksum. Direction is folded into the DIRF byte (0x20), so SetSpeed sends both an A0 speed and an A1 DIRF message to preserve function bits.

10.1 Speed scaling

LocoNet slot speed is a 7-bit value (0x00 stop, 0x01 e-stop, 0x02…0x7F). BigFred maps user steps (14/28/128) into 2…127 linearly in scaleToLnSpeed(); the decoder type in STAT1.D2–D0 (§9.1) selects the DCC packet mode the master emits.

11 Functions above F8 (F9–F28 and beyond)

The 10-byte slot (§9) only has room for F0–F4 (DIRF) and F5–F8 (SND). Functions F9 and up are not stored in the slot at all and therefore cannot be set with OPC_LOCO_DIRF / OPC_LOCO_SND. PE 1.0 throttles/PC interfaces drive them by a different mechanism. Several approaches exist in the field:

Because F9–F28 live outside the slot, a client must remember their state itself. JMRI keeps a "virtual extended slot" (LocoNetSlot.localF9 … localF28) precisely because the command station gives it no place to store them (LocoNetSlot).

BigFred does exactly this: the LocoNet driver keeps a per-loco extFnByA bitmask (loconet.go) updated both when it sends F9–F28 and when it observes such a packet on the shared bus, so a group send preserves the other functions and ListFunctions can report them.

11.1 F9–F28 via OPC_IMM_PACKET (0xED)

This is the portable method (works on any master that implements LocoNet 1.1 / the immediate-packet buffer). The throttle composes a raw NMRA DCC function packet and asks the master to put it on the track via OPC_IMM_PACKET (frame layout in §19.2). LocoNet practice is to send a whole function group (a bitmask of all functions in the group) and to repeat the packet on the track ~4×.

DCC function-group instruction bytes (NMRA S-9.2.1 / RCN-212), placed after the 1- or 2-byte loco address:

Address bytes (precede the instruction byte(s)):

• Short (1–127): one byte <ADR>.
• Long (128–10239): two bytes <0xC0 | (ADR>>8)> <ADR & 0xFF>.

The DCC packet's trailing XOR error byte is not carried in the LocoNet message — the master regenerates it. LocoNet can only carry DCC packets up to 5 payload bytes (IM1…IM5), which covers all standard function groups.

NMRA-packet builders (reference, JMRI): function9Through12Packet emits [ADR, 0xA0|mask]; function13Through20Packet emits […, 0xDE, mask]; function21Through28Packet → 0xDF; function29Through36Packet → 0xD8 (source).

11.2 F0–F28 via the expanded command 0xD5 (LocoNet 2)

Newer Digitrax masters (DCS210, DCS240 — "LocoNet 2", §12) accept a compact 6-byte slot-addressed function/speed command, OPC_EXP_SEND_FUNCTION_OR_SPEED_AND_DIR (0xD5):

D5 <SUB|SLOTHI> <SLOTLO> <THROTTLE_ID> <DATA> <CHK>
  SUB|SLOTHI : (slot >> 7) | subcode      (slot high bits + group selector)
  SLOTLO     : slot & 0x7F
  THROTTLE_ID: slot.id() & 0x7F
  DATA       : function bitmask (or speed for the speed/dir sub-codes)

This addresses the loco by slot, so no DCC-packet wrapping is needed, and it covers F9–F28 on LocoNet 2 masters only. F29+ still uses §11.4.

11.3 Vendor (Intellibox / Uhlenbrock) function opcodes

Uhlenbrock command stations (and traffic seen from IB-I / IB-II) carry extra functions on reverse-engineered opcodes that are not in PE 1.0:

0xD4 tokens (from JMRI LnConstants): 0x08 = F13–F19, 0x05/0x06/0x07 = IB-I special F0–F4 / F5–F11 ranges. These appear on the bus from Uhlenbrock hardware even though BigFred does not generate them; an observer should tolerate/skip them.

Z21 relevance: the Z21's virtual LocoNet stack forwards loco-specific traffic including OPC_LOCO_F912 (the F9–F12 message) and OPC_EXP_CMD when the 0x02000000 broadcast flag is set — see z21.md §2.16 and §9.3.1.

11.4 F29 and above

• F29–F68 use the 0xD8–0xDC DCC group bytes (§11.1 table) wrapped in OPC_IMM_PACKET. These come from RCN-212, not PE 1.0, and not every decoder implements them.
• F29–F32767 ("binary states") use the NMRA DCC Binary State Control Instruction (S-9.2.1), again wrapped in OPC_IMM_PACKET. The Z21 documents this exact LocoNet path (LAN_LOCONET_FROM_LAN + OPC_IMM_PACKET); from Z21 FW 1.42 the dedicated LAN_X_SET_LOCO_BINARY_STATE is preferred — see z21.md §9.3.1.

11.5 Observing F9–F28 from the bus

A receiver recognises an extended-function command by decoding the embedded DCC packet from an OPC_IMM_PACKET and checking the instruction byte: mask … == 0xA0 ⇒ F9–F12, … == 0xDE00 ⇒ F13–F20, etc. (JMRI SlotManager.isExtFunctionMessage). The loco address is taken from the embedded DCC address bytes — not from a slot — so an observer needs no prior slot read to attribute the change.

12 Expanded slots & LocoNet 2

Original LocoNet (PE 1.0, "LocoNet 1.1") has 120 usable refresh slots and the F0–F8 slot model above. Later Digitrax masters (DCS210, DCS240) added a second protocol level — informally "LocoNet 2" — with expanded slots (hundreds of slots, ~0x000…0x77F) and the compact 0xD5 function/speed command (§11.2).

Protocol detection. Slot STAT1.D2 (GTRK_MLOK1, §9.5) tells you the master implements LocoNet 1.1 (0 = DT200). JMRI further distinguishes LocoNet 1 vs 2 with the LOCONETPROTOCOL_ONE / LOCONETPROTOCOL_TWO levels, probing whether 0xBE/0xE6 expanded-slot traffic is honoured.

BigFred scope: BigFred targets the LocoNet 1.1 surface (120 slots, F0–F8). Expanded slots and the 0xD5 command are not generated; the parser tolerates them on a shared bus by length-decoding (§5) and ignoring unknown opcodes.

13 Address selection & slot lifecycle

Throttle ──► OPC_LOCO_ADR  BF 00 <ADR> <CHK>     (request address)
Master   ──► OPC_SL_RD_DATA E7 0E … <CHK>          (slot containing that address)
                                                    │
              ┌─────────────────────────────────────┘
              ▼
Throttle ──► OPC_MOVE_SLOTS BA <slot> <slot> <CHK> (NULL move → mark IN_USE)
Master   ──► OPC_SL_RD_DATA E7 …                    (confirm slot now IN_USE)

1. Request address with OPC_LOCO_ADR <BF> <0> <ADR> <CHK>.
2. Short 7-bit address: high byte = 0; analog/zero-stretch: both bytes 0; long 14-bit: high byte non-zero (most-significant bits).
3. Master replies with OPC_SL_RD_DATA <E7> for the slot containing the address. If the address is new, the master loads it into a FREE slot (speed 0, forward, functions off, 128-step) and returns that slot. If no free slot, it returns OPC_LONG_ACK <B4> <3F> <00> (fail code 0).
4. If the returned STAT1 shows COMMON / IDLE / NEW, the throttle promotes it to IN_USE via a NULL MOVE (OPC_MOVE_SLOTS with SRC == DEST).
5. If the loco is already IN_USE or up-consisted, do not use it (unlink first if consisted).

After this the throttle owns the slot and updates Speed/Dir/Functions (§10). On reconnect, a throttle re-reads the slot and continues only if the state matches its remembered value; otherwise it re-runs the logon.

BigFred: ensureSlotLocked() issues OPC_LOCO_ADR, waits for the matching E7 slot read, and caches addr↔slot. querySlotLocked() issues OPC_RQ_SL_DATA <BB> <slot> <0> to refresh current state before toggling a single function bit. BigFred currently relies on the master's allocation and does not issue the NULL MOVE itself; it caches slot state and serialises request/response sequences under a mutex (reqMu) with a sync channel.

14 Dispatching

A "one-deep" mechanism to hand a prepared slot to a simple throttle:

It is illegal to move to/from slots 120–127.

15 Switch & sensor messages

LocoNet accessory/feedback uses DS54-style 11-bit addressing (A0…A10), where the two LS bits of SW1 select one of four output/input pairs.

15.1 OPC_SW_REQ 0xB0 — request switch (turnout)

B0 <SW1> <SW2> <CHK>
SW1 = 0 A6 A5 A4 - A3 A2 A1 A0     (7 LS address bits)
SW2 = 0 0 DIR ON - A10 A9 A8 A7    (control + 4 MS address bits)
  DIR = 1 Closed/GREEN, 0 Thrown/RED
  ON  = 1 output ON, 0 output OFF

OPC_SW_ACK 0xBD is the acknowledged variant (returns LACK; not on DT200). OPC_SW_STATE 0xBC requests current state.

15.2 OPC_INPUT_REP 0xB2 — general sensor input

B2 <IN1> <IN2> <CHK>
IN1 = 0 A6 A5 A4 - A3 A2 A1 A0
IN2 = 0 X I L - A10 A9 A8 A7
  I = 0 DS54 "aux" inputs, 1 "switch" inputs (4K sensor space)
  L = 0 input LOW (0 V), 1 input HIGH (≥ +6 V)
  X = 1 (control bit; 0 reserved)

15.3 OPC_SW_REP 0xB1 — turnout sensor / output report

Two encodings selected by the second control bit: input levels (I,L) for turnout feedback, or current output levels (C = closed line on, T = thrown line on).

BigFred scope: the current driver focuses on mobile decoder control (speed/dir/F0–F8) and observation. Accessory switching and sensor decoding are not implemented in loconet.go; on the Z21 path accessory/feedback ride other messages (see z21.md §5, §7).

16 Programming track

The programming track is special slot 124 (0x7C), a shared asynchronous resource. Writing to it starts a task; an immediate LACK indicates acceptance, and an OPC_SL_RD_DATA <E7> from slot 124 carries the final result.

16.1 Task start

EF 0E 7C <PCMD> <00> <HOPSA> <LOPSA> <TRK> <CVH> <CVL> <DATA7> <00> <00> <CHK>

Immediate LACK codes:

16.2 PCMD — programmer command byte

Type codes:

16.3 CV addressing & data

CVH = 0 0 CV9 CV8 - 0 0 D7 CV7    (high 3 bits of CV# + MS data bit)
CVL = 0 CV6 CV5 CV4 - CV3 CV2 CV1 CV0
DATA7 = 0 D6 D5 D4 - D3 D2 D1 D0   (MS data bit lives in CVH.D1)

16.4 Final reply PSTAT

E7 0E 7C <PCMD> <PSTAT> <HOPSA> <LOPSA> <TRK> <CVH> <CVL> <DATA7> <00> <00> <CHK>

BigFred: ReadCV / WriteCV are implemented for the programming track (ProgrammingTrackMode) using service-mode direct byte access (loconet.go readCVLocked / writeCVLocked; builders lnBuildProgTask / parseLnProgReply with PCMD 0x2B read, 0x6B write — the values observed from real command stations). The driver sends the 0xEF slot-0x7C task, then resolves the LACK and the final 0xE7 reply (PSTAT + value). POM (main-track) CV access is rejected because it needs RailCom; for that, use the Z21 path (z21.md §6).

17 Device programming (SV) over OPC_PEER_XFER

Beyond programming decoders on the programming track (§16), LocoNet programs the configuration of LocoNet devices themselves (feedback modules, signal drivers, the Uhlenbrock 63120, etc.) through System Variables (SVs). This is a PE 1.0 extension carried in the 16-byte OPC_PEER_XFER (0xE5 0x10) message (SV Programming v13).

An 0xE5 message is recognised as SV programming by its 4th byte and the upper nibbles of the 6th and 11th bytes. Two layouts exist; format 2 is recommended for new designs:

E5 10 <SRC> <SV_CMD> <SV_TYPE> <SVX1> <DST_L> <DST_H>
      <SV_ADRL> <SV_ADRH> <SVX2> <D1> <D2> <D3> <D4> <CHK>

(Format 1 — legacy — is E5 10 <SRC> <DST> 01 <PXCT1> D1 D2 D3 D4 <PXCT2> D5 D6 D7 D8 <CHK>.)

17.1 Field usage (format 2)

17.2 SV_CMD commands

Identity replies return MANUFACTURER_ID in SV_ADRL, DEVELOPER_ID in SV_ADRH, PRODUCT_ID in D1/D2, and the serial number in D3/D4 (each 16-bit value LSB first). The Discover→Identify→Change-Address sequence resolves devices that ship with the same default address.

17.3 Standard SV locations

MANUFACTURER_ID uses the NMRA DCC manufacturer number; DIY developers use NMRA manufacturer 13 and manage their own DEVELOPER_IDs.

BigFred scope: SV programming is not implemented in the LocoNet driver. It is documented here because the Uhlenbrock 63120 interface and many LocoNet feedback/accessory boards are configured this way (LNCV is a related Uhlenbrock variant) — see devices/uhlenbrock-63120.md.

18 Fast clock

The system fast clock lives in slot 123 (0x7B). Write with OPC_WR_SL_DATA, read/sync via slot read of 0x7B. Devices keep a local clock and only re-sync on the SYNC read (~every 70–100 s); they must not continuously poll the slot.

EF 0E 7B <CLK_RATE> <FRAC_MINSL> <FRAC_MINSH> <256-MINS_60> <TRK>
         <256-HRS_24> <DAYS> <CLK_CNTRL> <ID1> <ID2> <CHK>

BigFred scope: fast clock is not implemented in the LocoNet driver.

19 Peer-to-peer & immediate packets

19.1 OPC_PEER_XFER 0xE5

Moves 8 data bytes SRC→DST (16-byte message). DSTL/DSTH = 0 is broadcast; SRC = 0 is master; SRC = 7F is a throttle message transfer. The PXCT1/PXCT2 bytes carry the MS bit of each data byte plus address/data type codes (e.g. ANSI text). Used for throttle text, LNCV-style transfers, and vendor extensions. The SV device-programming protocol (§17) rides this opcode.

19.2 OPC_IMM_PACKET 0xED

Sends an n-byte DCC packet immediately (not entered into the refresh stack). This is the carrier for F9–F28+ functions (§11.1) and DCC binary states:

ED 0B 7F <REPS> <DHI> <IM1> <IM2> <IM3> <IM4> <IM5> <CHK>
  DHI  = 0 0 1 IM5.7 - IM4.7 IM3.7 IM2.7 IM1.7   (MS bits of IM1..5)
  REPS = 0 <#IM bytes:D6..D4> 0 <repeat count:D2..D0>

LACK B4 7D 7F = command OK; B4 7D 00 = buffer busy. Not implemented on DT200.

The DHI byte's top three bits are the fixed pattern 0 0 1 per the Digitrax spec (so DHI is always ≥ 0x20); bits D4…D0 are the D7 (MSB) of IM5…IM1 respectively.

Note — JMRI deviation: JMRI's SlotManager.sendPacket builds DHI from the payload MSBs without the fixed 0x20 bit. Real command stations accept both; this doc follows the normative Digitrax bit layout.

Example — F9 ON, short address 3 (DCC packet 03 A1, 2 bytes, 4 repeats):

ED 0B 7F 23 20 03 21 00 00 00 00 <CHK>
         │  │  │  └─ IM2 = 0xA1 & 0x7F = 0x21  (0xA0 | F9)
         │  │  └──── IM1 = 0x03         (address 3)
         │  └─────── DHI = 0x20         (fixed 001 high bits; no IMx has D7 set)
         └────────── REPS = 0x23        (#bytes=2 → bits6-4=010, repeats=3+1)

(The decoder sees the regenerated full packet 03 A1 A2.)

BigFred: the LocoNet driver emits OPC_IMM_PACKET for F9–F28 (lnBuildImmPacket + dccFnGroupPacket, repeated lnImmRepeats×) and decodes it on receive (decodeImmDccPacket → dccPacketFunctions) to observe external F9–F28 changes. F29+ and DCC binary states are still out of scope (§23.3).

20 LoconetOverTcp framing

BigFred's loconet_tcp kind supports two TCP wire formats. The default (tcp://) is raw binary LocoNet over TCP (§20.4). The ASCII LoconetOverTcp protocol described in this section — spoken by LbServer-style gateways and the Digikeijs DR5000 LBServer LAN mode — is the lnTCPASCIITransport driver, selected with the lbserver:// scheme.

20.1 Line syntax

• One TCP connection per session; human-readable ASCII, line-oriented.
• A line ends with CR (0x0D) and/or LF (0x0A); empty lines are discarded.
• Each line starts with an uppercase token, optionally followed by a space-separated parameter.
• LocoNet bytes are carried as space-separated hex (e.g. 83 7C).

20.2 Tokens

Version history: v0 (Jun 2002, receive-only), v1 (Sep 2002, full duplex), v2 (Apr 2015, error reporting + timestamps).

20.3 Echo semantics

A SEND is echoed back as a RECEIVE (the bus echo), and then a SENT token confirms success/failure. Clients expecting a command-station reply see it right after the SENT token (skipping any OPC_BUSY / BREAK). This mirrors the half-duplex echo model of the raw bus (§4.1).

BigFred implementation: lnTCPASCIITransport.WritePacket() emits SEND <hex…>\r\n (refusing bad checksums); readLoop() parses RECEIVE lines into packets (validating checksum), logs VERSION / SENT, and ignores other tokens. Parsing is shared with the serial path through lnParseHexBytes(). The reader is a plain blocking line reader (it never arms a per-read deadline that could drop a half-received RECEIVE line), it locates the RECEIVE token anywhere in the line (tolerating a leading TIMESTAMP), and it trims the payload to the opcode's length code before checksumming — matching RocRail's lbserver.c behaviour.

20.4 Raw binary variant (no ASCII framing)

Not every LocoNet-over-TCP peer speaks the ASCII LbServer protocol: some bridges stream raw LocoNet bytes straight over the socket (opcode … checksum inclusive), with no SEND/RECEIVE lines. This is the protocol of RocRail's lbtcp client (rocdigs/impl/loconet/lbtcp.c), as opposed to its ASCII lbserver.c. Pointing the ASCII transport at such a peer connects fine but every request times out, because no RECEIVE line ever arrives.

BigFred handles this with a second transport, lnTCPBinaryTransport (NewLocoNetTCPBinary): it Writes the raw message bytes and reassembles inbound frames with the same lnStreamParser (§5) the serial transport uses. Raw binary is the default and the more common case, so it is selected by the bare tcp://host:port scheme; the ASCII LbServer protocol (lnTCPASCIITransport) is selected with lbserver://host:port (see 05-domain-model/01-entities.md).

21 Embedded implementations (mrrwa, ESP32HB)

These libraries are not part of BigFred but document real-world bit-level behaviour useful when reasoning about a physical bus or building a custom interface.

21.1 mrrwa/LocoNet (Arduino)

github.com/mrrwa/LocoNet — the reference embedded library:

• Interrupt-driven Rx into a circular FIFO; LocoNet.receive() returns the head packet or NULL.
• Successfully sent packets are (by default) appended to the receive buffer, so the app handles them like any other bus traffic — the echo model again.
• Maintains Tx/Rx statistics; invalid packets are discarded and an RxErrors counter is incremented.
• Uses a 16-bit timer + Input Capture (ICP) for wire timing (UNO TIMER1/ICP, MEGA TIMER5/ICP5, STM32 TIM2+EXTI, ESP8266 TIMER1).
• Signal polarity is configurable (LN_SW_UART_RX_INVERTED / LN_SW_UART_TX_INVERTED) — most interface circuits invert the LocoNet line.

21.2 tanner87661/LocoNetESP32HB (ESP32 hybrid)

github.com/tanner87661/LocoNetESP32HB — hardware UART receiver + timer-interrupt transmitter. Hardware UART Rx keeps valid reception even with WiFi active (which jitters timers); Tx errors are easy to detect and the library auto-resends.

Receive buffer (lnReceiveBuffer) carries timing useful for request/response logic:

Error flags:

A valid message must always have a correct opcode, data bytes, and XOR check byte before sending (mirrors §5–§6). Inverted logic is typical (InverseLogic).

22 LocoNet ↔ OpenLCB gateways

For interoperability with OpenLCB / LCC layouts, LocoNet traffic can be bridged to OpenLCB events and datagrams (OpenLCB note). This is not part of BigFred, but it informs how a shared bus is observed and how a neutral "every device sees every packet" model maps to a publish/subscribe network.

• LocoNet layout-control messages are already producer/consumer events — they are broadcast to unknown listeners, exactly like OpenLCB P/C events. Mapping each to a unique EventID makes the bridge straightforward.
• EventID layout used by the gateway:

• Transparent (raw) mapping. Short LocoNet messages (≤ 4 bytes) fit a single OpenLCB event; longer ones (slot reads, transponding, LISSY) span multiple event messages and are reassembled using the §5 length code. This survives protocol additions because the gateway never parses message semantics.
• LocoNet ID (a 7-bit value separating co-located radio LocoNets) is carried so multiple LocoNets do not collide at large modular meets.
• Flow control: OpenLCB is much faster than LocoNet, so the OpenLCB→LocoNet direction needs buffering; LocoNet→OpenLCB needs almost none.
• Synchronisation caveat: LocoNet has no general response/ack, and programs model state by watching the echoed stream (§4.1, §20.3). OpenLCB events are not echoed the same way, so a bridge must decide whether to re-emit events it places on the bus (an "echo" flag is proposed).

BigFred relevance: the same shared-bus, echo-driven property that OpenLCB gateways exploit is why BigFred observes other throttles' speed/function changes for free (§1, §23.3). BigFred does not implement an OpenLCB bridge.

23 BigFred mapping

How this spec maps to BigFred's drivers (pkgs/loco/commandstation/):

23.1 Transports

The serial transport reconstructs packets with lnStreamParser (§5); the TCP transport parses RECEIVE lines (§20). Both push validated packets onto a shared rxCh, demultiplexed by a single dispatch() goroutine.

23.2 Opcodes BigFred uses

23.3 Capability & limits

F9–F28 and service-mode CV access were added to the LocoNet driver. The remaining gaps vs Z21 are F29+, POM CV access (RailCom) and accessory/sensor control, so BigFred docs still prefer Z21 for the RailBOX RB1110 and use DR5000 over LocoNet when this surface suffices — see commandstations/dr5000.md §8 and commandstations/rb1110.md §8.

23.4 Concurrency & slot safety

• reqMu serialises request/response sequences (one in flight at a time).
• beginSync()/endSync() gate the syncCh so unsolicited bus traffic is not consumed while no one is waiting; dispatch() always feeds observe().
• slotByAd / slotAddr cache the address↔slot mapping; dirfByA / sndByA cache function bytes so a single function toggle does not clobber the others.
• Checksum is enforced on send (sendLocked) and receive (transport layer).

Appendix A – Opcode quick reference

† Post-PE-1.0 (LocoNet 2 / vendor); see §7.4, §11, §12.

LACK fail codes seen in the spec: B4 3F 00 (no free slot), B4 3A 00 (illegal move / no dispatch), B4 39 00 (invalid link), B4 30 00 (switch command failed), B4 7F xx (programmer status), B4 7D xx (immediate packet status).

Appendix B – Worked byte examples

Idle / NOP & checksum

83 7C        OPC_GPON  → XOR 0x83^0x7C = 0xFF ✓
81 7E        OPC_BUSY "time burner" NOP (strip & ignore)

Request loco address 3 (short)

BF 00 03 ??  OPC_LOCO_ADR, adrHi=0, adrLo=3
chk = 0xFF ^ (0xBF ^ 0x00 ^ 0x03) = 0xFF ^ 0xBC = 0x43
→ BF 00 03 43

Set speed on slot 5 to 0x10

A0 05 10 ??  OPC_LOCO_SPD
chk = 0xFF ^ (0xA0 ^ 0x05 ^ 0x10) = 0xFF ^ 0xB5 = 0x4A
→ A0 05 10 4A

Set DIRF on slot 5: forward (0x20) + F0 (0x10)

A1 05 30 ??  OPC_LOCO_DIRF, DIRF = 0x20|0x10 = 0x30
chk = 0xFF ^ (0xA1 ^ 0x05 ^ 0x30) = 0xFF ^ 0x94 = 0x6B
→ A1 05 30 6B

Request slot 5 data

BB 05 00 ??  OPC_RQ_SL_DATA
chk = 0xFF ^ (0xBB ^ 0x05 ^ 0x00) = 0xFF ^ 0xBE = 0x41
→ BB 05 00 41

Set F9 on short address 3 via OPC_IMM_PACKET (§11.1, §19.2)

DCC packet (no error byte): 03 A1        (0xA0 | F9-mask 0x01)
REPS = 0x23   (#bytes=2 → 010 in bits6-4; 4 repeats → 011 in bits2-0)
DHI  = 0x20   (fixed 001 high bits; neither 0x03 nor 0x21 has D7 set)
IM1  = 0x03,  IM2 = 0xA1 & 0x7F = 0x21
ED 0B 7F 23 20 03 21 00 00 00 00 ??

Set F13 on long address 1234 via OPC_IMM_PACKET (§11.1)

1234 = 0x04D2 → addr bytes: C0|0x04 = 0xC4, 0xD2
DCC packet: C4 D2 DE 01   (0xDE group byte + F13-mask 0x01)  → 4 bytes
REPS = 0x43   (#bytes=4 → 100; 4 repeats → 011)
DHI: fixed 0x20 | 0xC4(D7=1)→b0 | 0xD2(D7=1)→b1 | 0xDE(D7=1)→b2 = 0x27
IM1=0x44, IM2=0x52, IM3=0x5E, IM4=0x01
ED 0B 7F 43 27 44 52 5E 01 00 00 ??

LoconetOverTcp wire (§20)

→ SEND A0 05 10 4A         (client requests speed)
← RECEIVE A0 05 10 4A      (bus echo)
← SENT OK                  (server confirms)

Related: z21.md (Z21 LAN), command-station docs commandstations/dr5000.md, commandstations/rb1110.md, device devices/uhlenbrock-63120.md, and the LocoNet bring-up set hardware/.