Class Z21CommandStation

Namespace

Z21.Core

Assembly

Z21.Client.dll

public class Z21CommandStation : IZ21CommandStation, ICommandStation, ILocoControl, IAccessoryControl, ITrackPowerControl, ISystemInfoProvider, IProgrammingControl, IFeedbackControl, IFastClockControl, IDisposable

Inheritance

object

Z21CommandStation

Implements

IZ21CommandStation

ICommandStation

ILocoControl

IAccessoryControl

ITrackPowerControl

ISystemInfoProvider

IProgrammingControl

IFeedbackControl

IFastClockControl

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

Z21CommandStation(ITransport, Z21ResponseHandler, IZ21CommandFactory, Z21Options, ILocoInfoResponseHandler, ITurnoutInfoResponseHandler, IExtAccessoryInfoResponseHandler, ISystemStateDataChangedResponseHandler, IFirmwareVersionResponseHandler, IStatusChangedResponseHandler, ITrackPowerOnResponseHandler, ITrackPowerOffResponseHandler, ICvResultResponseHandler, ICvNackResponseHandler, ICvNackShortCircuitResponseHandler, IRmBusDataChangedResponseHandler, IFastClockDataResponseHandler, ILogger<Z21CommandStation>?)

public Z21CommandStation(ITransport transport, Z21ResponseHandler dispatcher, IZ21CommandFactory commands, Z21Options options, ILocoInfoResponseHandler locoInfoResponseHandler, ITurnoutInfoResponseHandler turnoutInfoResponseHandler, IExtAccessoryInfoResponseHandler extAccessoryInfoResponseHandler, ISystemStateDataChangedResponseHandler systemStateResponseHandler, IFirmwareVersionResponseHandler firmwareVersionResponseHandler, IStatusChangedResponseHandler statusChangedResponseHandler, ITrackPowerOnResponseHandler trackPowerOnResponseHandler, ITrackPowerOffResponseHandler trackPowerOffResponseHandler, ICvResultResponseHandler cvResultResponseHandler, ICvNackResponseHandler cvNackResponseHandler, ICvNackShortCircuitResponseHandler cvNackShortCircuitResponseHandler, IRmBusDataChangedResponseHandler rmBusDataChangedResponseHandler, IFastClockDataResponseHandler fastClockDataResponseHandler, ILogger<Z21CommandStation>? logger = null)

Parameters

transport ITransport

dispatcher Z21ResponseHandler

commands IZ21CommandFactory

options Z21Options

locoInfoResponseHandler ILocoInfoResponseHandler

turnoutInfoResponseHandler ITurnoutInfoResponseHandler

extAccessoryInfoResponseHandler IExtAccessoryInfoResponseHandler

systemStateResponseHandler ISystemStateDataChangedResponseHandler

firmwareVersionResponseHandler IFirmwareVersionResponseHandler

statusChangedResponseHandler IStatusChangedResponseHandler

trackPowerOnResponseHandler ITrackPowerOnResponseHandler

trackPowerOffResponseHandler ITrackPowerOffResponseHandler

cvResultResponseHandler ICvResultResponseHandler

cvNackResponseHandler ICvNackResponseHandler

cvNackShortCircuitResponseHandler ICvNackShortCircuitResponseHandler

rmBusDataChangedResponseHandler IRmBusDataChangedResponseHandler

fastClockDataResponseHandler IFastClockDataResponseHandler

logger ILogger<Z21CommandStation>

Exceptions

PlatformNotSupportedException

Thrown when system architecture is not little-endian.

Fields

MaxUdpPayload

IPv4 safe MTU for payload according to specification.

public const int MaxUdpPayload = 1472

Field Value

int

Properties

Commands

Factory for building raw Z21 commands to pass to SendCommandsAsync(params IZ21Command[]).

public IZ21CommandFactory Commands { get; }

Property Value

IZ21CommandFactory

IsConnected

public bool IsConnected { get; }

Property Value

bool

Methods

ConnectAsync()

public Task ConnectAsync()

Returns

Task

DisconnectAsync()

public Task DisconnectAsync()

Returns

Task

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DriveAsync(ushort, DccSpeedMode, DrivingDirection, ushort)

public Task DriveAsync(ushort locoAddress, DccSpeedMode speedMode, DrivingDirection direction, ushort speed)

Parameters

locoAddress ushort

speedMode DccSpeedMode

direction DrivingDirection

speed ushort

Returns

Task

EmergencyStopAllAsync()

Stops all locomotives while leaving the track voltage on.

public Task EmergencyStopAllAsync()

Returns

Task

EmergencyStopAsync(ushort)

public Task EmergencyStopAsync(ushort locoAddress)

Parameters

locoAddress ushort

Returns

Task

LogOnAsync()

protected virtual Task LogOnAsync()

Returns

Task

PurgeAsync(ushort)

public Task PurgeAsync(ushort locoAddress)

Parameters

locoAddress ushort

Returns

Task

ReadCvAsync(ushort)

public Task ReadCvAsync(ushort cvAddress)

Parameters

cvAddress ushort

Returns

Task

ReadCvAsync(ushort, TimeSpan)

Reads a CV on the programming track, retrying while the decoder does not acknowledge, and returns the value. A missing acknowledgement that never clears (for example an absent or unreadable decoder) is reported as a timeout rather than a distinct error. Do not call the fire-and-forget CV methods concurrently with this one on the same station.

public Task<byte> ReadCvAsync(ushort cvAddress, TimeSpan timeout)

Parameters

cvAddress ushort

timeout TimeSpan

Returns

Task<byte>

Exceptions

CvOperationTimeoutException

No result arrived within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

timeout is not a positive, in-range duration.

ReadPomCvAsync(ushort, ushort, TimeSpan)

Reads a CV of a locomotive decoder on the main track (POM), retrying while the decoder does not acknowledge, and returns the value. Requires RailCom; without it (or for an absent decoder) the read can only ever time out. The result is correlated by CV address only — the protocol's POM result carries no loco address — so do not run other CV operations on this station concurrently.

public Task<byte> ReadPomCvAsync(ushort locoAddress, ushort cvAddress, TimeSpan timeout)

Parameters

locoAddress ushort

cvAddress ushort

timeout TimeSpan

Returns

Task<byte>

Exceptions

CvOperationTimeoutException

No result arrived within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

timeout is not a positive, in-range duration.

ReadPomCvBitAsync(ushort, ushort, byte, TimeSpan)

Reads a single bit of a CV of a locomotive decoder on the main track (POM) by reading the CV byte back (so it requires RailCom) and returning the value of the target bit.

public Task<bool> ReadPomCvBitAsync(ushort locoAddress, ushort cvAddress, byte bitPosition, TimeSpan timeout)

Parameters

locoAddress ushort

cvAddress ushort

bitPosition byte

The 0-based bit position within the CV (0–7).

timeout TimeSpan

Returns

Task<bool>

Exceptions

CvOperationTimeoutException

No result arrived within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

bitPosition exceeds 7, or timeout is not a positive, in-range duration.

RequestExtAccessoryInfoAsync(ushort)

public Task RequestExtAccessoryInfoAsync(ushort accessoryAddress)

Parameters

accessoryAddress ushort

Returns

Task

RequestFeedbackAsync(byte)

public Task RequestFeedbackAsync(byte groupIndex)

Parameters

groupIndex byte

Returns

Task

RequestFirmwareVersionAsync()

public Task RequestFirmwareVersionAsync()

Returns

Task

RequestLocoInfoAsync(ushort)

public Task RequestLocoInfoAsync(ushort locoAddress)

Parameters

locoAddress ushort

Returns

Task

RequestModelTimeAsync()

public Task RequestModelTimeAsync()

Returns

Task

RequestStatusAsync()

public Task RequestStatusAsync()

Returns

Task

RequestSystemStateAsync()

public Task RequestSystemStateAsync()

Returns

Task

RequestTurnoutInfoAsync(ushort)

public Task RequestTurnoutInfoAsync(ushort accessoryAddress)

Parameters

accessoryAddress ushort

Returns

Task

SendCommandsAsync(params IZ21Command[])

Sends one or more raw commands in a single UDP packet.

public Task SendCommandsAsync(params IZ21Command[] commands)

Parameters

commands IZ21Command[]

Returns

Task

SetExtAccessoryAsync(ushort, byte)

public Task SetExtAccessoryAsync(ushort accessoryAddress, byte payload)

Parameters

accessoryAddress ushort

payload byte

Returns

Task

SetFunctionAsync(ushort, ushort, FunctionToggleType)

public Task SetFunctionAsync(ushort locoAddress, ushort functionIndex, FunctionToggleType toggleType)

Parameters

locoAddress ushort

functionIndex ushort

toggleType FunctionToggleType

Returns

Task

SetModelTimeAsync(ModelTime)

public Task SetModelTimeAsync(ModelTime time)

Parameters

time ModelTime

Returns

Task

SetTurnoutAsync(ushort, AccessoryOutput, AccessoryState, bool)

public Task SetTurnoutAsync(ushort accessoryAddress, AccessoryOutput output, AccessoryState state, bool executeImmediately)

Parameters

accessoryAddress ushort

output AccessoryOutput

state AccessoryState

executeImmediately bool

Returns

Task

StartModelTimeAsync()

public Task StartModelTimeAsync()

Returns

Task

StopModelTimeAsync()

public Task StopModelTimeAsync()

Returns

Task

TrackPowerOffAsync()

public Task TrackPowerOffAsync()

Returns

Task

TrackPowerOnAsync()

public Task TrackPowerOnAsync()

Returns

Task

WriteCvAsync(ushort, byte)

public Task WriteCvAsync(ushort cvAddress, byte value)

Parameters

cvAddress ushort

value byte

Returns

Task

WriteCvAsync(ushort, byte, TimeSpan)

Writes a CV on the programming track, retrying while the decoder does not acknowledge, and completes once the command station acknowledges the write (LAN_X_CV_RESULT). A missing acknowledgement that never clears is reported as a timeout. Do not call the fire-and-forget CV methods concurrently with this one on the same station.

public Task WriteCvAsync(ushort cvAddress, byte value, TimeSpan timeout)

Parameters

cvAddress ushort

value byte

timeout TimeSpan

Returns

Task

Exceptions

CvOperationTimeoutException

The write was not acknowledged within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

timeout is not a positive, in-range duration.

WritePomCvAsync(ushort, ushort, byte, TimeSpan)

Writes a CV of a locomotive decoder on the main track (POM). Because a POM write returns no acknowledgement, this verifies by reading the CV back and retrying until the read-back matches the written value (so it requires RailCom). A decoder that never reads back the written value is reported as a timeout. Do not run other CV operations on this station concurrently.

public Task WritePomCvAsync(ushort locoAddress, ushort cvAddress, byte value, TimeSpan timeout)

Parameters

locoAddress ushort

cvAddress ushort

value byte

timeout TimeSpan

Returns

Task

Exceptions

CvOperationTimeoutException

The write could not be confirmed within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

timeout is not a positive, in-range duration.

WritePomCvBitAsync(ushort, ushort, byte, bool, TimeSpan)

Writes a single bit of a CV of a locomotive decoder on the main track (POM). Because a POM write returns no acknowledgement, this verifies by reading the CV byte back and retrying until the target bit matches the written value (so it requires RailCom). A bit that never reads back is reported as a timeout. Do not run other CV operations on this station concurrently.

public Task WritePomCvBitAsync(ushort locoAddress, ushort cvAddress, byte bitPosition, bool bitValue, TimeSpan timeout)

Parameters

locoAddress ushort

cvAddress ushort

bitPosition byte

The 0-based bit position within the CV (0–7).

bitValue bool

timeout TimeSpan

Returns

Task

Exceptions

CvOperationTimeoutException

The write could not be confirmed within timeout.

CvShortCircuitException

The command station reported a short circuit.

ArgumentOutOfRangeException

bitPosition exceeds 7, or timeout is not a positive, in-range duration.

Events

ConnectionChanged

public event EventHandler<ConnectionChangedEventArgs>? ConnectionChanged

Event Type

EventHandler<ConnectionChangedEventArgs>

CvProgrammingFailed

public event EventHandler<CvProgrammingError>? CvProgrammingFailed

Event Type

EventHandler<CvProgrammingError>

CvReadCompleted

public event EventHandler<CvValue>? CvReadCompleted

Event Type

EventHandler<CvValue>

ExtAccessoryInfoReceived

public event EventHandler<ExtAccessoryInfo>? ExtAccessoryInfoReceived

Event Type

EventHandler<ExtAccessoryInfo>

FeedbackChanged

public event EventHandler<FeedbackData>? FeedbackChanged

Event Type

EventHandler<FeedbackData>

FirmwareVersionReceived

public event EventHandler<FirmwareVersion>? FirmwareVersionReceived

Event Type

EventHandler<FirmwareVersion>

LocoInfoReceived

public event EventHandler<LocoInfoData>? LocoInfoReceived

Event Type

EventHandler<LocoInfoData>

ModelTimeChanged

public event EventHandler<ModelTime>? ModelTimeChanged

Event Type

EventHandler<ModelTime>

StatusChanged

public event EventHandler<CentralState>? StatusChanged

Event Type

EventHandler<CentralState>

SystemStateReceived

public event EventHandler<SystemState>? SystemStateReceived

Event Type

EventHandler<SystemState>

TrackPowerChanged

Raised when track power is switched on (true) or off (false).

public event EventHandler<bool>? TrackPowerChanged

Event Type

EventHandler<bool>

TurnoutInfoReceived

public event EventHandler<TurnoutInfo>? TurnoutInfoReceived

Event Type

EventHandler<TurnoutInfo>