Z21 LAN Protocol Specification

Markdown transcription of the Z21 LAN protocol specification. Source: Z21 LAN Protocol Specification, Modelleisenbahn GmbH (Roco/Fleischmann), Document Version 1.13 en, 06.11.2023 (original: docs/z21.html).

Conventions: - All multi-byte values are little-endian unless stated otherwise. - Bytes are written in hexadecimal notation (0x..). - In bit field tables, letters denote individual bits (e.g. RVVVVVVV).

Basics

System, Status, Versions

Settings

Driving

Switching

Reading and writing Decoder CVs

Feedback – R-BUS

RailCom

LocoNet

CAN

zLink

Fast Clock

Appendix A – Command overview

1 Basics

1.1 Communication

Communication with the Z21 command station uses UDP on port 21105 or 21106. Client applications (PC, app, …) should primarily use port 21105.

Communication is always asynchronous, i.e. broadcast messages may appear between a request and the corresponding response.

Each client should communicate with the Z21 at least once per minute; otherwise it will be removed from the list of active participants. If possible, the client should log off using LAN_LOGOFF.

1.2 Z21 Dataset

1.2.1 Structure

A single Z21 data record (request or response) has the following structure:

• DataLen (little-endian): total length of the entire record including DataLen, Header, and Data, i.e. DataLen = 2 + 2 + n.
• Header (little-endian): describes the command and protocol group.
• Data: structure and byte count depend on the command.

Unless stated otherwise, byte order is little-endian (low byte first, then high byte).

1.2.2 X-BUS Protocol tunneling

Requests and responses based on the X-BUS protocol are sent with the Z21-LAN header 0x40 (LAN_X_xxx). This applies only to the protocol — these commands have nothing in common with the physical X-BUS of the Z21; they are addressed exclusively to LAN clients or to the Z21.

The actual X-BUS command is in the Data field. The last byte is a checksum calculated as XOR over the entire X-BUS command. Example:

1.2.3 LocoNet tunneling

From Z21 FW 1.20.

With Z21-LAN headers 0xA0 and 0xA1 (LAN_LOCONET_Z21_RX, LAN_LOCONET_Z21_TX), messages received or sent by the Z21 on the LocoNet bus are forwarded to the LAN client. The client subscribes via LAN_SET_BROADCASTFLAGS.

The LAN client can write messages to the LocoNet bus via header 0xA2 (LAN_LOCONET_FROM_LAN).

In this way the Z21 can act as an Ethernet/LocoNet gateway, while the Z21 is also the LocoNet master managing refresh slots and generating DCC packets.

Example — LocoNet message OPC_MOVE_SLOTS <0><0> (“DISPATCH_GET”) sent by the Z21:

1.3 Combining datasets in one UDP packet

Several independent Z21 data records can be sent in one UDP packet to one recipient. Each recipient must be able to interpret these combined packets.

The UDP packet must fit within the Ethernet MTU; considering the IPv4 header and UDP header, at most 1500 - 20 - 8 = 1472 bytes of payload data are available.

2 System, Status, Versions

2.1 LAN_GET_SERIAL_NUMBER

Read the Z21 serial number.

Request to Z21:

Reply from Z21:

2.2 LAN_LOGOFF

Log off the client from the Z21.

Request to Z21:

Reply from Z21: none.

Use the same port number when logging out as when logging in.

Note: login is implicit with the client’s first command (e.g. LAN_SYSTEMSTATE_GETDATA, …).

2.3 LAN_X_GET_VERSION

Read the Z21 X-Bus version.

Request to Z21:

Reply from Z21:

• XBUS_VER: X-Bus protocol version (0x30 = V3.0, 0x36 = V3.6, 0x40 = V4.0, …)
• CMDST_ID: command station ID (0x12 = Z21 device family)

2.4 LAN_X_GET_STATUS

Request the Z21 status.

Request to Z21:

Reply from Z21: see 2.12 LAN_X_STATUS_CHANGED.

The command station status is identical to CentralState in 2.18 LAN_SYSTEMSTATE_DATACHANGED.

2.5 LAN_X_SET_TRACK_POWER_OFF

Switch off track voltage.

Request to Z21:

Reply from Z21: see 2.7 LAN_X_BC_TRACK_POWER_OFF.

2.6 LAN_X_SET_TRACK_POWER_ON

Switch on track voltage, or end emergency stop / programming mode.

Request to Z21:

Reply from Z21: see 2.8 LAN_X_BC_TRACK_POWER_ON.

2.7 LAN_X_BC_TRACK_POWER_OFF

Packet sent by the Z21 to registered clients when: - a client sent 2.5 LAN_X_SET_TRACK_POWER_OFF, - or track voltage was switched off by an input device (multiMaus), - and the client has activated the corresponding broadcast (2.16, flag 0x00000001).

Z21 to Client:

2.8 LAN_X_BC_TRACK_POWER_ON

Analogous to 2.7, when track voltage was switched on.

Z21 to Client:

2.9 LAN_X_BC_PROGRAMMING_MODE

Packet sent when the Z21 enters CV programming mode via 6.1 LAN_X_CV_READ or 6.2 LAN_X_CV_WRITE (broadcast flag 0x00000001).

Z21 to Client:

2.10 LAN_X_BC_TRACK_SHORT_CIRCUIT

Packet sent in case of a short circuit (broadcast flag 0x00000001).

Z21 to Client:

2.11 LAN_X_UNKNOWN_COMMAND

Z21 response to an invalid request.

Z21 to Client:

2.12 LAN_X_STATUS_CHANGED

Sent when the client explicitly requests status via 2.4 LAN_X_GET_STATUS.

Z21 to Client:

DB1 = command station status. Bitmask:

#define csEmergencyStop          0x01  // The emergency stop is switched on
#define csTrackVoltageOff        0x02  // The track voltage is switched off
#define csShortCircuit           0x04  // Short-circuit
#define csProgrammingModeActive  0x20  // The programming mode is active

Status is identical to SystemState.CentralState (see 2.18).

2.13 LAN_X_SET_STOP

Activate emergency stop — locomotives are stopped, but track voltage remains on.

Request to Z21:

Reply from Z21: see 2.14 LAN_X_BC_STOPPED.

2.14 LAN_X_BC_STOPPED

Packet sent after 2.13 LAN_X_SET_STOP or after emergency stop triggered by an input device (broadcast flag 0x00000001).

Z21 to Client:

2.15 LAN_X_GET_FIRMWARE_VERSION

Read the Z21 firmware version.

Request to Z21:

Reply from Z21:

• DB1 = MSB of firmware version, DB2 = LSB of firmware version. BCD format.
• Example: 0x09 0x00 0x40 0x00 0xF3 0x0A 0x01 0x23 0xDB → “Firmware Version 1.23”.

2.16 LAN_SET_BROADCASTFLAGS

Set broadcast flags in the Z21. Flags are set per client (per IP + port) and must be set again on each subsequent login.

Request to Z21:

Broadcast flags are an OR combination of the following values:

Reply from Z21: none.

Note: when configuring broadcast flags always consider the impact on network load. This applies especially to flags 0x00010000, 0x00040000, 0x02000000 and 0x04000000. IP packets may be dropped by the router under overload, and UDP offers no detection mechanisms.

2.17 LAN_GET_BROADCASTFLAGS

Read broadcast flags.

Request to Z21:

Reply from Z21:

2.18 LAN_SYSTEMSTATE_DATACHANGED

System status change notification from Z21 to client. Sent asynchronously when the client has activated broadcast (flag 0x00000100) or explicitly requested status (2.19).

Z21 to Client:

SystemState structure (16-bit values, little-endian):

CentralState bitmask:

#define csEmergencyStop          0x01  // The emergency stop is switched on
#define csTrackVoltageOff        0x02  // The track voltage is switched off
#define csShortCircuit           0x04  // Short-circuit
#define csProgrammingModeActive  0x20  // The programming mode is active

CentralStateEx bitmask:

#define cseHighTemperature       0x01  // temperature too high
#define csePowerLost             0x02  // Input voltage too low
#define cseShortCircuitExternal  0x04  // S.C. at the external booster output
#define cseShortCircuitInternal  0x08  // S.C. at the main track or programming track
#define cseRCN213                0x20  // (from FW 1.42) turnout addresses according to RCN-213

Capabilities bitmask (from FW 1.42):

#define capDCC            0x01  // capable of DCC
#define capMM             0x02  // capable of MM
//#define capReserved     0x04  // reserved for future development
#define capRailCom        0x08  // RailCom is activated
#define capLocoCmds       0x10  // accepts LAN commands for locomotive decoders
#define capAccessoryCmds  0x20  // accepts LAN commands for accessory decoders
#define capDetectorCmds   0x40  // accepts LAN commands for detectors
#define capNeedsUnlockCode 0x80 // device needs activate code (z21start)

If Capabilities == 0, the device likely has an older firmware version — Capabilities should not be interpreted in that case.

2.19 LAN_SYSTEMSTATE_GETDATA

Request current system status.

Request to Z21:

Reply from Z21: see 2.18 LAN_SYSTEMSTATE_DATACHANGED.

2.20 LAN_GET_HWINFO

From Z21 FW 1.20 and SmartRail FW V1.13.

Read hardware type and Z21 firmware version.

Request to Z21:

Reply from Z21:

HwType:

#define D_HWT_Z21_OLD             0x00000200  // „black Z21” (variant from 2012)
#define D_HWT_Z21_NEW             0x00000201  // „black Z21” (variant from 2013)
#define D_HWT_SMARTRAIL           0x00000202  // SmartRail (from 2012)
#define D_HWT_z21_SMALL           0x00000203  // „white z21” starter set (from 2013)
#define D_HWT_z21_START           0x00000204  // „z21 start” starter set (from 2016)
#define D_HWT_SINGLE_BOOSTER      0x00000205  // 10806 „Z21 Single Booster” (zLink)
#define D_HWT_DUAL_BOOSTER        0x00000206  // 10807 „Z21 Dual Booster” (zLink)
#define D_HWT_Z21_XL              0x00000211  // 10870 „Z21 XL Series” (from 2020)
#define D_HWT_XL_BOOSTER          0x00000212  // 10869 „Z21 XL Booster” (from 2021, zLink)
#define D_HWT_Z21_SWITCH_DECODER  0x00000301  // 10836 „Z21 SwitchDecoder” (zLink)
#define D_HWT_Z21_SIGNAL_DECODER  0x00000302  // 10837 „Z21 SignalDecoder” (zLink)

FW version is in BCD format. Example: 0x0C 0x00 0x1A 0x00 0x00 0x02 0x00 0x00 0x20 0x01 0x00 0x00 → „Hardware Type 0x200, Firmware Version 1.20”.

For older firmware versions use 2.15 LAN_X_GET_FIRMWARE_VERSION: - V1.10 / V1.11 … Z21 (variant from 2012) - V1.12 … SmartRail (from 2012)

2.21 LAN_GET_CODE

Read Z21 software feature scope (especially relevant for the “z21 start” variant to check whether driving and switching over LAN are blocked or allowed).

Request to Z21:

Reply from Z21:

Code:

#define Z21_NO_LOCK         0x00  // all features permitted
#define z21_START_LOCKED    0x01  // „z21 start”: driving and switching is blocked
#define z21_START_UNLOCKED  0x02  // „z21 start”: driving and switching is permitted

3 Settings

The following settings are stored permanently in the Z21. They can be reset to factory defaults by holding the STOP button on the Z21 until the LEDs start flashing purple.

3.1 LAN_GET_LOCOMODE

Read output format (DCC, MM) for a given locomotive address. In the Z21 the format is stored permanently for each loco address (max 256 addresses). Any address ≥ 256 is automatically DCC.

Request to Z21:

Reply from Z21:

• Loco address: 2 bytes, big-endian (high byte first, then low byte).
• Mode: 0 = format DCC, 1 = format MM.

3.2 LAN_SET_LOCOMODE

Set output format for a given locomotive address (persistent write).

Request to Z21:

Reply from Z21: none.

Notes: any address ≥ 256 is and remains DCC format. The number of speed steps (14, 28, 128) is also stored permanently — this happens automatically with the drive command (4.2 LAN_X_SET_LOCO_DRIVE).

3.3 LAN_GET_TURNOUTMODE

Read settings (DCC, MM format) for a given accessory decoder address (“Accessory Decoder” RP-9.2.1). Max 256 addresses; any ≥ 256 is automatically DCC.

Request to Z21:

Reply from Z21:

• Mode: 0 = format DCC, 1 = format MM.

On the LAN interface and in the Z21, accessory decoder addresses are numbered from 0, but in applications or on multiMaus visualization — from 1. Example: turnout #3 on multiMaus corresponds to address 2 on LAN and in the Z21.

3.4 LAN_SET_TURNOUTMODE

Set output format for a given accessory decoder address (persistent write).

Request to Z21:

Reply from Z21: none.

MM accessory decoders are supported from Z21 FW 1.20. They are not supported by SmartRail. Any decoder ≥ 256 is and remains DCC.

4 Driving

The client can subscribe to locomotive information via 4.1 LAN_X_GET_LOCO_INFO to be automatically notified of changes to that locomotive address (including those triggered by other clients or controllers). Additionally the appropriate broadcast must be active (2.16, flag 0x00000001).

To keep network traffic within reasonable limits, a client can subscribe to at most 16 locomotive addresses (FIFO).

4.1 LAN_X_GET_LOCO_INFO

Query locomotive status. At the same time the client “subscribes” to information for this loco address (only in combination with broadcast flag 0x00000001).

Request to Z21:

Loco addressing: loco address = (Adr_MSB & 0x3F) << 8 + Adr_LSB. For addresses ≥ 128 the two highest bits in DB1 must be set to 1: DB1 = (0xC0 | Adr_MSB). For addresses < 128 these two bits are irrelevant.

Reply from Z21: see 4.4 LAN_X_LOCO_INFO.

4.2 LAN_X_SET_LOCO_DRIVE

Change locomotive speed and direction.

Request to Z21:

Loco addressing as in 4.1.

DB0 = 0x1S — number of speed steps depends on the configured format: - S=0: DCC 14 steps, or MMI with 14 steps and F0 - S=2: DCC 28 steps, or MMII with 14 actual steps and F0-F4 - S=3: DCC 128 steps (“126 steps” excluding stop steps), or MMII with 28 actual steps (light-trit) and F0-F4

DB3 = RVVVVVVV: - R — direction: 1 = forward - V — speed, encoding depends on speed steps S (see below)

If MM format is configured for the loco, conversion of the given DCC step to the actual MM step is performed automatically in the Z21.

Encoding per NMRA S 9.2 and S 9.2.1. “Stop” = “normal stop” / “step 0”. “E-Stop” = “immediate emergency stop”.

“DCC 14” speed encoding (R000 VVVV):

“DCC 28” speed encoding (R00V5 VVVV — like DCC 14, but with an additional intermediate bit V5):

¹ Use not recommended.

“DCC 128” speed encoding (RVVV VVVV):

Reply from Z21: no standard reply; 4.4 LAN_X_LOCO_INFO to subscribed clients.

Note: the number of speed steps (14/28/128) is automatically stored permanently for that loco address in the command station.

4.3 Functions for locomotive decoder

Function commands from F0 through F12 are sent periodically to the main track (depending on priority), similar to speed and direction.

Function commands F13 and above are sent three times after a change, then — per RCN-212 and available bandwidth — are no longer sent until the next function state change.

4.3.1 LAN_X_SET_LOCO_FUNCTION

Change a single locomotive function.

Request to Z21:

Loco addressing as in 4.1.

DB3 = TTNN NNNN: - TT — switch type: 00 = off, 01 = on, 10 = toggle, 11 = not allowed - NNNNNN — function index: 0x00 = F0 (light), 0x01 = F1, etc.

With Motorola MMI only F0 can be switched. With MMII: F0–F4. With DCC: F0–F28. From FW 1.42 extended range F0–F31.

Reply from Z21: no standard reply; 4.4 LAN_X_LOCO_INFO to subscribed clients.

4.3.2 LAN_X_SET_LOCO_FUNCTION_GROUP

Switch an entire loco function group (up to 8 functions in one command). From FW 1.42 DCC functions up to F31, and with certain limitations up to F68.

The client should continuously monitor all functions of the controlled loco to avoid accidentally turning off a function enabled earlier by another client. The command is more suitable for PC automation software.

Request to Z21:

Loco addressing as in 4.1.

Groups and functions:

Notes: - (A) Motorola MMI: only F0; MMII: F0–F4. - (B) DCC F13–F28 with this command only from FW V1.24. - (C) DCC F29–F31 from FW V1.42, including feedback to LAN clients. - (D) DCC F32–F68 from FW V1.42, but without feedback to LAN clients (commands sent to track only). - (E) It is not guaranteed that DCC function commands from F29 upward will be understood by all decoders.

Reply from Z21: no standard reply; for functions F0–F31, 4.4 LAN_X_LOCO_INFO to subscribed clients.

4.3.3 LAN_X_SET_LOCO_BINARY_STATE

From FW 1.42. Send a DCC “Binary State” command to the locomotive decoder.

Request to Z21:

Loco addressing: loco address = (AH & 0x3F) << 8 + AL; for addresses ≥ 128 DB1 = (0xC0 | Adr_MSB).

• F (highest bit of DB3) — specifies whether the binary state is on/off.
• LLLLLLL — lower seven bits of the binary state address.
• HHHHHHHH (DB4) — upper eight bits of the binary state address.

15-bit binary state address = (HHHHHHHH << 7) + (LLLLLLL & 0x7F). Allowed address range 29–32767. Addresses 1–28 reserved for special applications, address 0 as broadcast. Addresses < 128 (HHHHHHHH == 0) are sent as DCC “binary state control command short form” (RCN-212), ≥ 128 as “long form”. Commands sent three times to the main track, then not repeated.

Reply from Z21: none (no reply to caller and no notification to other clients).

4.4 LAN_X_LOCO_INFO

Sent from Z21 to clients in response to 4.1 LAN_X_GET_LOCO_INFO, and also without a request when another client/controller changed loco status, the client activated broadcast (flag 0x00000001) and subscribed to that address.

Z21 to Client:

Packet length n variable: 7 ≤ n ≤ 14. From FW 1.42 DataLen ≥ 15 (n ≥ 8) to carry F29, F30 and F31 status.

Locomotive information structure:

¹ In the original, DB2 is described as 0000 BKKK; the MM bit (M) was introduced from FW 1.43.

4.5 LAN_X_SET_LOCO_E_STOP

From FW 1.43. Stop locomotive. For a DCC loco the “E-STOP” speed step is sent (emergency stop per RCN-212); for an MM loco step 0 (“Stop”).

Request to Z21:

Loco addressing as in 4.1.

Reply from Z21: no standard reply; 4.4 LAN_X_LOCO_INFO to subscribed clients.

4.6 LAN_X_PURGE_LOCO

From FW 1.43. Remove locomotive from Z21 — stops sending loco commands to the track. Sending resumes after a new drive/function command is sent to the same address.

Request to Z21:

Loco addressing as in 4.1.

Reply from Z21: none (no reply to caller and no notification to other clients).

5 Switching

This chapter covers messages required for switching accessory decoders (“Accessory Decoder” per RP-9.2.1, e.g. turnout decoders).

Turnout number visualization differs across DCC systems. Per DCC there are four ports with two outputs each per accessory decoder address. Conversion of input parameters (FAdr_MSB, FAdr_LSB, A, P) na polecenie DCC:

DCC basic accessory decoder packet: {preamble} 0 10AAAAAA 0 1aaaCDDd 0 EEEEEEEE 1

UINT16 FAdr     = (FAdr_MSB << 8) + FAdr_LSB;
UINT16 Dcc_Addr = FAdr >> 2;

aaaAAAAAA = (~Dcc_Addr & 0x1C0) | (Dcc_Addr & 0x003F);  // DCC Address
C  = A;            // Activate or deactivate output
DD = FAdr & 0x03;  // Port
d  = P;            // Switch to the left or to the right

Example: FAdr=0 → DCC-Addr=0 Port=0; FAdr=3 → DCC-Addr=0 Port=3; FAdr=4 → DCC-Addr=1 Port=0. For MM format: FAdr=0 → MM-Addr=1; FAdr=1 → MM-Addr=2; …

The client can subscribe to accessory info (broadcast flag 0x00000001). The description uses the terms “output 1” and “output 2” instead of “straight”/“branching”.

5.1 LAN_X_GET_TURNOUT_INFO

Query turnout status (or any accessory function).

Request to Z21:

Function address = (FAdr_MSB << 8) + FAdr_LSB.

Reply from Z21: see 5.3 LAN_X_TURNOUT_INFO.

5.2 LAN_X_SET_TURNOUT

Switch turnout (or any accessory function).

Request to Z21:

Function address = (FAdr_MSB << 8) + FAdr_LSB.

DB2 = 1000A00P / 10Q0A00P: - A=0 — deactivate turnout output; A=1 — activate - P=0 — select output 1; P=1 — select output 2 - Q=0 — execute command immediately - Q=1 — (from FW V1.24) queue command in Z21 and deliver to track as soon as possible

Reply from Z21: no standard reply; 5.3 LAN_X_TURNOUT_INFO to subscribed clients.

5.2.1 LAN_X_SET_TURNOUT with Q=0

With Q=0 the Z21 behaves compatibly with previous versions: the switch command is sent to the track immediately (mixed with current drive commands). Activate (A=1) is sent until the LAN client sends the corresponding Deactivate. Only one switch command can be active at a time. The LAN client is responsible for correct serialization and switching-time timing.

Wrong:

Activate #5/A2 (4,0x89); Activate #6/A2 (5,0x89);
Activate #3/A1 (2,0x88); Deactivate #3/A1 (2,0x80);
Deactivate #5/A2 (4,0x81); Deactivate #6/A2 (5,0x81);

Correct:

Activate #5/A2 (4,0x89); wait 100ms; Deactivate #5/A2 (4,0x81); wait 50ms;
Activate #6/A2 (5,0x89); wait 100ms; Deactivate #6/A2 (5,0x81); wait 50ms;
Activate #3/A1 (2,0x88); wait 100ms; Deactivate #3/A1 (2,0x80); wait 50ms;

5.2.2 LAN_X_SET_TURNOUT with Q=1

With Q=1 the command first enters the Z21 internal queue (FIFO), then is written to the track four times. The LAN client does not need to strictly serialize commands — it can send them mixed (useful for routes). The client is only responsible for Deactivate timing (for MM, Deactivate must not be skipped).

Activate #25/A2 (24,0xA9); Activate #5/A2 (4,0xA9);
Wait 150ms;
Deactivate #25/A2 (24,0xA1)

Never mix Q=0 and Q=1 commands in one application.

5.3 LAN_X_TURNOUT_INFO

Sent in response to 5.1, and also without a request when status was changed by another client/controller (broadcast flag 0x00000001).

Z21 to Client:

Function address = (FAdr_MSB << 8) + FAdr_LSB.

DB2 = 000000ZZ: - ZZ=00 — turnout not yet switched - ZZ=01 — turnout in position per “P=0” (see 5.2) - ZZ=10 — turnout in position per “P=1” - ZZ=11 — invalid combination

5.4 LAN_X_SET_EXT_ACCESSORY

From FW V1.40. Send a DCC command in “extended accessory decoder package format” (DCCext) to an extended accessory decoder. Allows sending turnout switching times or complex signal aspects in one command. See RCN-213 (section 2.3).

Request to Z21:

RawAddress = (Adr_MSB << 8) + Adr_LSB. RawAddress of the first extended decoder = 4 per RCN-213 (usually displayed as “Address 1”).

• DDDDDDDD — up to 256 states transmitted via bits 0–7 in DB2, in extended accessory decoder package format per RCN-213.

Note (10836 Z21 switch DECODER): interprets DDDDDDDD as RZZZZZZZ: - ZZZZZZZ — on-time with 100 ms resolution. Value 0 = output off; 127 = output on permanently (until next command). - Bit 7 (R) — output selection in pair: R=1 “green” (straight), R=0 “red” (branched).

Note (10837 Z21 signal DECODER): interprets DDDDDDDD as one of 256 possible signal aspects. Example values: - 0 … Stop - 4 … Clear with max speed limit 40 km/h - 16 … Clear - 65 (0x41) … shunting allowed - 66 (0x42) … turn off all lights (e.g. for distant signals) - 69 (0x45) … substitution (permission to pass defective signal)

Reply from Z21: no standard reply or 5.6 LAN_X_EXT_ACCESSORY_INFO.

Examples:

0x0A 0x00 0x40 0x00 0x54 0x00 0x04 0x05 0x00 0x55
  → RawAddress=4 (displayed as address 1), DDDDDDDD value=5

0x0A 0x00 0x40 0x00 0x54 0x07 0xFF 0x00 0x00 0xAC
  → emergency stop for extended accessory decoders (RCN-213 2.4), RawAddress=2047, value 0

5.5 LAN_X_GET_EXT_ACCESSORY_INFO

From FW V1.40. Query the last command forwarded to an extended accessory decoder.

Request to Z21:

RawAddress = (Adr_MSB << 8) + Adr_LSB (wg RCN-213). DB2 zarezerwowane, init 0.

Reply from Z21: see 5.6 LAN_X_EXT_ACCESSORY_INFO.

5.6 LAN_X_EXT_ACCESSORY_INFO

Sent in response to 5.5, and also without a request (broadcast flag 0x00000001).

Z21 to Client:

RawAddress = (Adr_MSB << 8) + Adr_LSB. - DDDDDDDD — up to 256 states in extended accessory decoder package format (RCN-213, see 5.4). - Status: 0x00 = Data Valid, 0xFF = Data Unknown.

6 Reading and writing Decoder CVs

This chapter covers reading/writing decoder CVs (Configuration Variable, RP-9.2.2, RP-9.2.3). Whether access is bit-wise or byte-wise depends on Z21 settings.

6.1 LAN_X_CV_READ

Read CV in direct mode.

Request to Z21:

CV Address = (CVAdr_MSB << 8) + CVAdr_LSB, where 0=CV1, 1=CV2, 255=CV256, etc.

Reply from Z21: 2.9 LAN_X_BC_PROGRAMMING_MODE to subscribed clients and result: 6.3 LAN_X_CV_NACK_SC, 6.4 LAN_X_CV_NACK lub 6.5 LAN_X_CV_RESULT.

6.2 LAN_X_CV_WRITE

Write CV in direct mode.

Request to Z21:

CV Address = (CVAdr_MSB << 8) + CVAdr_LSB (0=CV1, …).

Reply from Z21: as in 6.1.

6.3 LAN_X_CV_NACK_SC

If programming failed due to a short circuit, this message is sent to the client that initiated programming (6.1 / 6.2).

Z21 to Client:

6.4 LAN_X_CV_NACK

If ACK is missing from the decoder. For byte read, time until LAN_X_CV_NACK can be long.

Z21 to Client:

6.5 LAN_X_CV_RESULT

“Positive ACK” — sent to the client that initiated programming. For byte read, time until LAN_X_CV_RESULT can be long.

Z21 to Client:

CV Address = (CVAdr_MSB << 8) + CVAdr_LSB (0=CV1, …).

6.6 LAN_X_CV_POM_WRITE_BYTE

Write locomotive decoder CV on the main track (POM, “Programming on the Main”). In normal operating mode (track voltage on, service mode inactive). No feedback.

Request to Z21:

POM parameters:

Reply from Z21: none.

6.7 LAN_X_CV_POM_WRITE_BIT

Write a single CV bit of a locomotive decoder on the main track (POM). No feedback.

Request to Z21:

POM parameters:

Reply from Z21: none.

6.8 LAN_X_CV_POM_READ_BYTE

From FW 1.22. Read locomotive decoder CV on the main track (POM). RailCom must be active in the Z21, and the decoder must support RailCom (CV28 bits 0 and 1 and CV29 bit 3 = 1).

Request to Z21:

POM parameters:

Reply from Z21: 6.4 LAN_X_CV_NACK or 6.5 LAN_X_CV_RESULT.

6.9 LAN_X_CV_POM_ACCESSORY_WRITE_BYTE

From FW 1.22. Write accessory decoder CV on the main track (POM). No feedback.

Request to Z21:

POM parameters:

Reply from Z21: none.

6.10 LAN_X_CV_POM_ACCESSORY_WRITE_BIT

From FW 1.22. Write a single CV bit of an accessory decoder on the main track (POM). No feedback.

Request to Z21:

POM parameters:

Reply from Z21: none.

6.11 LAN_X_CV_POM_ACCESSORY_READ_BYTE

From FW 1.22. Read accessory decoder CV on the main track (POM). RailCom must be active; decoder must support RailCom.

Request to Z21:

POM parameters:

Reply from Z21: 6.4 LAN_X_CV_NACK or 6.5 LAN_X_CV_RESULT.

6.12 LAN_X_MM_WRITE_BYTE

From FW 1.23. Write Motorola decoder register on the programming track.

Request to Z21:

• RegAdr: 0=Register1, 1=Register2, …, 78=Register79.
• 0 ≤ Value ≤ 255 (some decoders accept only 0–80).

Reply from Z21: 2.9 LAN_X_BC_PROGRAMMING_MODE to subscribed clients and result 6.3 LAN_X_CV_NACK_SC or 6.5 LAN_X_CV_RESULT.

Note: there is no read for Motorola. LAN_X_CV_RESULT only means “MM programming process finished”, not “MM programming process successful”.

Example: 0x0A 0x00 0x40 0x00 0x24 0xFF 0x00 0x00 0x05 0xDE → “Change loco decoder address (register 1) to 5”.

6.13 LAN_X_DCC_READ_REGISTER

From FW 1.25. Read DCC decoder register in register mode (S-9.2.3) on the programming track.

Request to Z21:

• REG: 0x01=Register1, …, 0x08=Register8. 0 ≤ Value ≤ 255.

Reply from Z21: 2.9 LAN_X_BC_PROGRAMMING_MODE + 6.3 LAN_X_CV_NACK_SC lub 6.5 LAN_X_CV_RESULT.

Register mode is only needed for very old DCC decoders. Direct CV is preferred.

6.14 LAN_X_DCC_WRITE_REGISTER

From FW 1.25. Write DCC decoder register in register mode on the programming track.

Request to Z21:

• REG: 0x01=Register1, …, 0x08=Register8. 0 ≤ Value ≤ 255.

Reply from Z21: as in 6.13.

7 Feedback – R-BUS

Feedback modules (Roco 10787, 10808, 10819) on R-BUS.

7.1 LAN_RMBUS_DATACHANGED

Report changes on the feedback bus. Sent asynchronously when the client activated broadcast (flag 0x00000002) or explicitly requested status (7.2).

Z21 to Client:

• Group index: 0 … modules at addresses 1–10; 1 … modules at addresses 11–20.
• Feedback status: 1 byte per module, 1 bit per input. Address and byte position order ascending.

Example: Group Index = 1, Feedback Status = 0x01 0x00 0xC5 0x00 … → “module #11, contact on input 1; module #13, contacts on inputs 8, 7, 3 and 1”.

7.2 LAN_RMBUS_GETDATA

Query current status of feedback modules.

Request to Z21:

Reply from Z21: see 7.1 LAN_RMBUS_DATACHANGED.

7.3 LAN_RMBUS_PROGRAMMODULE

Change address of one feedback module.

Request to Z21:

• Address: new module address. Range: 0 and 1…20.

Reply from Z21: none.

The programming sequence is broadcast on R-BUS until this command is sent again with address=0. During programming only one module should be connected to R-BUS.

8 RailCom

The Z21 supports RailCom: - Generating RailCom cutout in the track signal. - Global RailCom receiver in the Z21. - Local RailCom receivers (e.g. in 10808 detectors or 10806/10807 boosters) — data from channel 2 forwarded via CAN to Z21 (from FW V1.29). - Reading POM results (see 6.8, from FW V1.22). - Loco address recognition for occupancy detectors (CAN, LocoNet, X-BUS). - Decoder speed (from FW V1.29). - Decoder QoS (from FW V1.29).

Requires a RailCom-capable decoder, correct CV28/CV29 configuration, and active “RailCom” option in Z21 settings.

8.1 LAN_RAILCOM_DATACHANGED

From FW 1.29. Sent in response to 8.2, and also without a request when RailCom data actually changed and the client: activated broadcast 0x00000004 + subscribed to loco address (4.1), or subscribed to broadcast 0x00040000 (all locomotives, PC software only).

Z21 to Client:

RailComData structure (16/32-bit values, little-endian):

Options bitmask:

#define rcoSpeed1  0x01  // CH7 subindex 0
#define rcoSpeed2  0x02  // CH7 subindex 1
#define rcoQoS     0x04  // CH7 subindex 7

Structure may be extended — consider DataLen when evaluating.

8.2 LAN_RAILCOM_GETDATA

From FW V1.29. Query RailCom data from Z21.

Request to Z21:

• Type: 0x01 = query RailCom data for the given loco address.
• LocoAddress: 0 = query RailCom data for the next loco (circular buffer).

Reply from Z21: see 8.1 LAN_RAILCOM_DATACHANGED.

9 LocoNet

From FW 1.20. The Z21 can act as an Ethernet/LocoNet gateway, while also being LocoNet master (refreshing slots, generating DCC packets).

• Messages received by Z21 from LocoNet → to LAN client with header LAN_LOCONET_Z21_RX.
• Messages sent by Z21 on LocoNet → to LAN client with header LAN_LOCONET_Z21_TX.
• The client can write messages to LocoNet via LAN_LOCONET_FROM_LAN. Other clients with LocoNet subscription are also notified; the sender itself is not.

Subscription via 2.16 LAN_SET_BROADCASTFLAGS. Consider carefully whether flags 0x02000000 (locos) and 0x04000000 (turnouts) are needed — for conventional driving and switching, commands from chapters 4, 5 and 6 are preferable. The LocoNet protocol itself is not described here.

9.1 LAN_LOCONET_Z21_RX

From FW 1.20. Message received by Z21 from LocoNet bus (broadcasts 0x01000000, 0x02000000 or 0x04000000).

Z21 to Client:

9.2 LAN_LOCONET_Z21_TX

From FW 1.20. Message written by Z21 to LocoNet bus.

Z21 to Client:

9.3 LAN_LOCONET_FROM_LAN

From FW 1.20. Allows the LAN client to write a message to LocoNet. Also sent asynchronously by Z21 when another LAN client wrote a message to LocoNet.

LAN client → Z21, or Z21 → LAN client:

9.3.1 DCC Binary State Control Instruction via LocoNet OPC_IMM_PACKET

From FW 1.42 4.3.3 LAN_X_SET_LOCO_BINARY_STATE is recommended instead of the method below.

From FW V1.25 arbitrary DCC packets can be generated on track output using LAN_LOCONET_FROM_LAN and LocoNet command OPC_IMM_PACKET, including Binary State Control Instruction (“F29…F32767”). Also applies to white z21 (virtual LocoNet stack). For OPC_IMM_PACKET structure see LocoNet Spec; for Binary State Control Instruction — NMRA S-9.2.1 “Feature Expansion Instruction”.

9.4 LAN_LOCONET_DISPATCH_ADDR

From FW 1.20. Prepare loco address for LocoNet dispatch (“DISPATCH_PUT”).

Request to Z21:

Reply from Z21: - FW < 1.22: none. - FW ≥ 1.22:

• Result = 0: “DISPATCH_PUT” failed (e.g. when Z21 is LocoNet slave and master rejected the request — address assigned to another controller).
• Result > 0: “DISPATCH_PUT” successful. Loco address can be passed to a controller (e.g. FRED). Result value = current LocoNet slot number for that address.

9.5 LAN_LOCONET_DETECTOR

From FW 1.22. Allows querying occupancy state and being asynchronously notified of changes without dealing with LocoNet protocol details.

Difference between 10787 module on R-BUS and LocoNet occupancy detectors: 10787 typically uses mechanical contacts (per axle), whereas LocoNet detectors rely on current measurement or advanced technologies (transponder, infrared, RailCom) and usually generate a message only on occupancy state change.

Request to Z21:

Type: - 0x80 — request via “Stationary Interrogate Request” (SIC) per Digitrax procedure (also Blücher-Elektronik). “Report address” parameter = 0 (irrelevant). - 0x81 — request via so-called report address for Uhlenbrock detector (user-configurable, e.g. UB63320 via LNCV 17, default 1017). Report address ≠ feedback address. On LocoNet bus implemented via turnout switch commands, so the LocoNet value is decremented by 1. Example: 0x07 0x00 0xA4 0x00 0x81 0xF8 0x03 → “detector status with report address 1017” (1017 = 0x03F8 + 1). - 0x82 — (from FW 1.23) request status for LISSY. For Uhlenbrock LISSY report address equals feedback address; message type depends on LISSY receiver operating mode.

A single request may be answered by several detectors, so expect multiple replies.

Reply from Z21:

Sent asynchronously when the client activated broadcast 0x08000000 and Z21 received a message from a detector (input state change or explicit query).

• Feedback address — each detector input has its own address describing the monitored block.
• Info[n] — byte array; content and length n depend on Type:

Type may be extended with additional IDs in the future.

10 CAN

10.1 LAN_CAN_DETECTOR

From FW 1.30. Roco CAN occupancy detector 10808. Can be used in four ways:

1. R-BUS emulation — CAN detector forwarded as R-BUS detector (chapter 7).
2. LocoNet emulation — forwarded as LocoNet detector (chapter 9.5, types 0x01, 0x02, 0x03).
3. LISSY emulation — emulated via LISSY/Marco messages (chapter 9.5, types 0x10, 0x11).
4. Direct access via LAN_CAN_DETECTOR command (fastest, most bandwidth-efficient method).

Emulation type configurable via Z21 Maintenance Tool. Factory default: R-BUS emulation = on, LocoNet emulation = on, LISSY emulation = off.

Request to Z21:

• Type 0x00: request detector with given CAN network ID. NetworkID 0xD000 = “all CAN detectors”.
• Example: 0x07 0x00 0xC4 0x00 0x00 0x00 0xD0 → “query status of all CAN detectors”.

Reply from Z21:

Sent asynchronously with broadcast 0x00080000. All 16-bit values are little-endian.

• NId — immutable CAN network ID of the detector.
• Addr — configurable detector module address.
• Port — CAN detector input number (0–7).
• Type:
• 0x01 — input occupancy status (free, busy, overload)
• 0x11 — 1st and 2nd recognized loco address on input
• 0x12 — 3rd and 4th recognized loco address
• … up to 0x1F — 29th and 30th recognized loco address

If Type = 0x01 (occupancy status):

If Type = 0x11..0x1F (RailCom Loco address): Type 0x11..0x1F form a list of loco addresses terminated by address 0. - Value1 — first detected loco address in section with direction. 0 = none / end of list. - Value2 — second detected loco address. 0 = none / end of list.

Direction encoded in the two highest bits of Value1/Value2: - 0 x — direction not detected - 1 0 — vehicle facing forward - 1 1 — vehicle facing reverse

Lower 14 bits contain the loco address.

10.2 CAN Booster

From FW 1.41. Manage Roco CAN boosters (10806, 10807, 10869) — works only when boosters are connected to Z21 via CAN-Bus (not B-BUS).

10.2.1 LAN_CAN_DEVICE_GET_DESCRIPTION

Read booster name (free text stored by user).

Request to Z21:

NId — CAN-NetworkID adresowanego boostera (16-bit LE, 0xC101–0xC1FF).

Z21 to Client:

• Name — null-terminated string, kodowanie ISO 8859-1 (Latin-1).

Tips: do not send two GET_DESCRIPTION requests back-to-back — wait for the reply. NetworkIDs of all CAN boosters available via 10.2.3.

10.2.2 LAN_CAN_DEVICE_SET_DESCRIPTION

Overwrite booster name.

Request to Z21:

• Name — null-terminated string, ISO 8859-1, pad remainder with 0x00.
• Disallowed characters: double quote " (0x22) and backslash \ (0x5C).

Reply from Z21: none.

10.2.3 LAN_CAN_BOOSTER_SYSTEMSTATE_CHGD

Report CAN booster status to client. Message appears approx. once per second per booster and output. Sent with broadcast 0x00020000 and at least one booster connected via CAN.

Z21 to Client:

Struktura CANBoosterSystemState (16-bit little-endian):

Booster_State bitmask:

#define bsBgActive         0x0001  // brake generator active (ZCAN SSP)
#define bsShortCircuit     0x0020  // short circuit on track (ZCAN UES)
#define bsTrackVoltageOff  0x0080  // track is switched off (OFF)
#define bsRailComActive    0x0800  // RailCom-Cutout active
// From Booster FW V1.11 (Booster Management):
#define bsOutputDisabled   0x0100  // track is deactivated (by user)

10.2.4 LAN_CAN_BOOSTER_SET_TRACKPOWER

Manage booster: deactivate and reactivate CAN booster track outputs.

Request to Z21:

• NId — CAN-NetworkID boostera (0xC101–0xC1FF).
• Power:
• 0x00 — deactivate all track outputs
• 0xFF — reactivate all track outputs
• (from Z21 FW V1.42 and Booster FW V1.11):
• 0x10 — deactivate 1st output; 0x11 — reactivate 1st output
• 0x20 — deactivate 2nd output (Z21 dual BOOSTER); 0x22 — reactivate 2nd output

Outputs can be turned on again only when the Z21 is on and sending a valid track signal. Booster management settings are not stored permanently.

Reply from Z21: on change 10.2.3 LAN_CAN_BOOSTER_SYSTEMSTATE_CHGD to subscribed clients.

11 zLink

The zLink interface allows integrating devices with smaller microcontrollers into the network (without their own LAN/Wi-Fi). zLink devices (01/2021): - 10806 Z21 single BOOSTER - 10807 Z21 dual BOOSTER - 10869 Z21 XL BOOSTER - 10836 Z21 switch DECODER - 10837 Z21 signal DECODER

11.1 Adapter

11.1.1 10838 Z21 pro LINK

10838 Z21 pro LINK connects the zLink interface to Wi-Fi as a gateway: 1. Configuration of the end device (buttons/display, Z21 App, Z21 Maintenance Tool). 2. Firmware update of the end device. 3. Control of the device by Wi-Fi clients using the Z21 LAN protocol.

A reduced Z21 protocol stack is implemented in the end device (see tables in Appendix A). Tips: - Limited bandwidth: effective transfer < 1024 bytes/s per device. - Pause ≥ 50 ms between two requests. - Use Z21 pro LINK preferably in client mode. - Preferably only one Wi-Fi client per Z21 pro LINK, max 4.

11.1.1.1 LAN_ZLINK_GET_HWINFO

Query Z21 pro LINK properties. Sent as UDP broadcast to discover devices on the network. This command is handled by Z21 pro LINK itself (not forwarded to the end device).

Request to Z21 pro LINK:

• Data[0] = 0x06 = ZLINK_MSG_TYPE_HW_INFO

Reply from Z21 pro LINK:

Struktura Z_Hw_Info (16-bit little-endian):

• HwID: 401 = 0x191 … adapter 10838 Z21 pro LINK.
• MAC_Address: MAC adaptera jako null-terminated string, 8-bit ASCII.
• Name: configurable name, null-terminated string, max 32 characters + 0x00, ISO 8859-1.

11.2 Booster 10806, 10807 und 10869

Commands available for boosters — see Appendix A. Additionally, new commands were introduced that apply only to boosters.

11.2.1 LAN_BOOSTER_GET_DESCRIPTION

Request to BOOSTER:

Reply from BOOSTER:

• Name — null-terminated string, ISO 8859-1, ≤ 16 characters (CAN compatibility).
• Special case: Name[0] == 0xFF if name was never written → treat as empty string.

11.2.2 LAN_BOOSTER_SET_DESCRIPTION

Request to BOOSTER:

• Name — ISO 8859-1, pad remainder with 0x00. Disallowed: " (0x22), \ (0x5C).

Reply from BOOSTER: none.

11.2.3 LAN_BOOSTER_SYSTEMSTATE_GETDATA

Request to BOOSTER:

Reply from BOOSTER: see 11.2.4.

11.2.4 LAN_BOOSTER_SYSTEMSTATE_DATACHANGED

Reported asynchronously with broadcast 0x00000100 or after explicit request 11.2.3.

BOOSTER to Client:

BoosterSystemState structure (16-bit little-endian):

CentralState bitmask:

#define csTrackVoltageOff  0x02  // track is switched off
#define csConfigMode       0x10  // configuration mode is active
#define csCanConnected     0x20  // CAN connection with Z21 is Ok

CentralStateEx bitmask:

#define cseHighTemperature         0x01  // over temperature
#define csePowerLost               0x02  // supply voltage too low
#define cseBooster_1_ShortCircuit  0x04  // short circuit on 1st track output
#define cseBooster_2_ShortCircuit  0x08  // short circuit on 2nd output
#define cseRevPol                  0x10  // supply voltage error
#define cseNoDCCInput              0x80  // no DCC input signal

CentralStateEx2 bitmask:

#define cse2Booster_1_RailComActive   0x01  // RailCom active 1st track output
#define cse2Booster_2_RailComActive   0x02  // RailCom active 2nd track output
#define cse2Booster_1_MasterSettings  0x04  // CAN autosettings Ok 1st track output
#define cse2Booster_2_MasterSettings  0x08  // CAN autosettings Ok 2nd track output
#define cse2Booster_1_BgActive        0x10  // brake generator active 1st track output
#define cse2Booster_2_BgActive        0x20  // brake generator active 2nd track output
#define cse2Booster_1_RailComFwd      0x40  // RailCom forwarding active 1st track output
#define cse2Booster_2_RailComFwd      0x80  // RailCom forwarding active 2nd track output

CentralStateEx3 bitmask:

#define cse3Booster_1_OutputInverted  0x01  // 1st track output inverted (autoinvert)
#define cse3Booster_2_OutputInverted  0x02  // 2nd track output inverted (autoinvert)
// From Booster FW V1.11:
#define cse3Booster_1_OutputDisabled  0x10  // Track output 1 deactivated (by user)
#define cse3Booster_2_OutputDisabled  0x20  // Track output 2 deactivated (by user)

11.2.5 LAN_BOOSTER_SET_POWER

From Booster FW V1.11. User booster management. Allows turning off/on dedicated track output on 10807 Z21 dual BOOSTER.

Request to BOOSTER:

• BoosterPort: 0x01 = 1st output, 0x02 = 2nd output (dual only), 0x03 = all.
• BoosterPortState: 0x00 = deactivate, 0x01 = reactivate.

Reply from BOOSTER: on change 11.2.4 to subscribed clients.

11.3 Decoder 10836 und 10837

Commands available for decoders — see Appendix A.

11.3.1 LAN_DECODER_GET_DESCRIPTION

Request to DECODER:

Reply from DECODER:

Name encoding as in 11.2.1.

11.3.2 LAN_DECODER_SET_DESCRIPTION

Request to DECODER:

Name encoding as in 11.2.2. Reply: none.

11.3.3 LAN_DECODER_SYSTEMSTATE_GETDATA

Request to DECODER:

Reply from DECODER: see 11.3.4.

11.3.4 LAN_DECODER_SYSTEMSTATE_DATACHANGED

Reported asynchronously with broadcast 0x00000100 or after explicit request 11.3.3. If signal decoder does not report within 4 s despite subscription, it can be queried. Replies from 10836 and 10837 differ in structure and content — distinguished by DataLen.

11.3.4.1 SwitchDecoderSystemState

10836 Z21 switch DECODER to client:

SwitchDecoderSystemState structure (16-bit little-endian):

CentralState bitmask:

#define csEmergencyStop    0x01  // The emergency stop for decoder
#define csTrackVoltageOff  0x02  // The track voltage is switched off
#define csShortCircuit     0x04  // Short-circuit
#define csConfigMode       0x10  // configuration mode is active

CentralStateEx bitmask:

#define csePowerLost   0x02  // Input voltage too low
#define cseRCN213      0x20  // addressing conform with RCN213
#define cseNoDCCInput  0x80  // no DCC input signal

OutputState (enumeration):

#define oUnknown        0x00
#define oRedActive      0x11
#define oRedInactive    0x01
#define oGreenActive    0x12
#define oGreenInactive  0x02

OutputConfig (enumeration, output operating mode):

#define ocfgNormal   0  // impulse operation (default)
#define ocfgBlinker  1  // alternating flasher
#define ocfgBlinkSm  2  // alternating flasher with fade in/out
#define ocfg10775    3  // momentary operation like 10775
#define ocfgK84      4  // continuous operation (e.g. for lighting)
#define ocfgK84Sm    5  // continuous operation with fade in/out

• OutputDimm — 0 = dimming off (full power); 1–100 = min..max power.
• Address — decoder address corresponds to 4 turnout numbers: address 1 → turnouts 1–4; address 2 → 5–8; etc.
• Address2 — if 0, 2nd decoder address automatically = “1st address + 1”.
• Dimmed — 1 bit per output pair: 0 not dimmed, 1 dimmed / smooth dimming. LSB = pair 1, MSB = pair 8.

11.3.4.2 SignalDecoderSystemState

10837 Z21 signal DECODER to client:

SignalDecoderSystemState structure (16-bit little-endian):

CentralState bitmask:

#define csEmergencyStop    0x01  // The emergency stop for decoder
#define csTrackVoltageOff  0x02  // The track voltage is switched off
#define csShortCircuit     0x04  // Short-circuit
#define csConfigMode       0x10  // configuration mode is active

CentralStateEx bitmask:

#define csePowerLost   0x02  // Input voltage too low
#define cseEEPromError 0x10  // EEPROM write / read error
#define cseRCN213      0x20  // addressing conform with RCN213
#define cseNoDCCInput  0x80  // no DCC input signal

• OutputStates — [0]: LSB = A1, MSB = A8; [1]: LSB = B1, MSB = B8.
• BlinkStates — analogous to OutputStates.
• SignalDccExt and SignalConfig — SignalConfig defines signal type (Signal-ID); SignalDccExt defines the currently visible signal aspect (DCCext value).
• Address — decoder address corresponds to 4 signal addresses; decoder occupies 4 consecutive decoder addresses = 4×4 = 16 signal addresses. Address 1 → signals 1–16; etc.

12 Fast Clock

From FW 1.43. Accelerated Z21 fast clock time is available for devices on the main track, X-BUS and LAN. Rate can be accelerated up to ≤ 63.

The Z21 has no real-time clock — fast clock always starts from the same default start time (configurable). Behavior on emergency stop/short circuit and output to track, LocoNet, X-BUS and IP Multicast can be configured.

• DCC model time on the main track — see RCN-211.
• LocoNet — devices can poll clock slot (0x7B) every 70–100 s.
• X-BUS — time once per model minute (XpressNet™ V4.0).
• LAN — optionally via “MRclock” multicast on 239.50.50.20, port 2000 (once per model minute, min. 3× per real minute).

12.1 LAN_FAST_CLOCK_CONTROL

12.1.1 Get Fast Clock Time

Request to Z21:

Reply from Z21: see 12.2 LAN_FAST_CLOCK_DATA.

12.1.2 Set Fast Clock Time

Sets current rate and fast clock time.

Request to Z21:

• DDD — day of week in 3 bits (0 = Monday … 6 = Sunday).
• hhhhh — hour in 5 bits (0–23).
• mmmmmm — minute in 6 bits (0–59).
• rrrrrr — rate (acceleration factor) in 6 bits (0–63): 0 = stopped (not recommended, use 12.1.4); 1 = real time; 2 = 2× faster; etc.
• XOR-Byte — XOR sum over Data.

Rate is stored permanently in the Z21.

Reply from Z21: 12.2 LAN_FAST_CLOCK_DATA to subscribed clients.

12.1.3 Start Fast Clock Time

Request to Z21:

Reply from Z21: 12.2 LAN_FAST_CLOCK_DATA. Stan “fcFastClockEnabled” stored permanently.

12.1.4 Stop Fast Clock Time

Request to Z21:

Reply from Z21: 12.2 LAN_FAST_CLOCK_DATA. Stan “fcFastClockEnabled” stored permanently.

12.2 LAN_FAST_CLOCK_DATA

Reports current fast clock time. Sent asynchronously with broadcast 0x00000010 or after explicit request 12.1.1. When fast clock is running, message appears approx. once per model minute, and on start/pause/change. Z21 may skip messages — clients must tolerate this and optionally compute time themselves.

Z21 to Client:

Struktura FastClockTime:

• DDD — day of week in 3 bits (0 = Monday … 6 = Sunday).
• hhhhh — hour (0–23); mmmmmm — minute (0–59); ssssss — second (0–59).
• S — STOP flag: fast clock not running (e.g. not enabled or rate = 0).
• H — HALT flag: fast clock temporarily paused (emergency stop or short circuit on main track).
• rrrrrr — rate (0–63).
• FcSettings — persistent settings flags, see 12.3.

12.3 LAN_FAST_CLOCK_SETTINGS_GET

Read persistent fast clock settings.

Request to Z21:

Reply from Z21:

Each field in Data is 8 bits. - FcSettings — settings flags (see below). - Rate — rate (0–63). - StartDDDhhhhh — default start time: DDD day (0=Mon..6=Sun), hhhhh hour (0–23). - StartMMMMMM — default start minute (0–59).

FcSettings bitmask:

#define fcFastClockLocoNetEn       0x01  // activate output on LocoNet (polled)
#define fcFastClockXBUSEn          0x02  // activate broadcast on XBUS
//                                 0x04  // reserved
#define fcFastClockDCCEn           0x08  // activate DCC broadcast on main track
#define fcFastClockMRclockEn       0x10  // enable sending MRclock multicasts
//                                 0x20  // reserved
#define fcFastClockEmergenyHaltEn  0x40  // halt fast clock on emergency stop automatically
#define fcFastClockEnabled         0x80  // activate fast clock

• fcFastClockEmergenyHaltEn — automatic fast clock pause on emergency stop / short circuit.
• fcFastClockEnabled — enable flag; also changed indirectly via LAN_FAST_CLOCK_CONTROL (start/stop).
• Factory defaults: FcSettings=0x4F, Rate=1, StartDDDhhhhh=0, StartMMMMMM=0.

12.4 LAN_FAST_CLOCK_SETTINGS_SET

Overwrite persistent fast clock settings. Each field in Data is 8 bits. Three variants available depending on number of fields:

Variant 1 — FcSettings only:

Variant 2 — FcSettings + Rate:

Variant 3 — FcSettings + Rate + default start time:

Field description — see 12.3 LAN_FAST_CLOCK_SETTINGS_GET.

Reply from Z21: none.

Appendix A – Command overview

Client to Z21

Messages sent from client to Z21 or zLink device.

Table 1: Messages from Client to Z21.

Z21 to Client

Messages sent from Z21 or zLink device to client.

Table 2: Messages from Z21 to Clients.

Table footnotes:

1. z21start: fully functional only with activation code (catalog no. 10814 or 10818).
2. z21, z21start: virtual LocoNet stack (e.g. GBM16XN with XPN interface).
3. From decoder FW V1.11.
4. Z21 → Client: short circuit reported in the appropriate booster/decoder system state. Client → Z21: decoder shows stop aspect if the second bit (0x02) is set in CV38 (10837 only).
5. Answered by 10838 Z21 pro LINK, not its end device (booster or decoder).
6. Decoder (LAN_X_SET_TRACK_POWER_ON): turn signal lamps back on (10837 only).