ILssMaster Interface¶
LSS master (CiA 305). Exactly one master may be active in a CANopen network (§6.1); this type does not police other processes. It sends on LssMasterMessage and receives on LssSlaveMessage. Commands run one at a time.
Implements IDisposable, IAsyncDisposable
Remarks¶
The master is responsible for having exactly one slave in LSS configuration before a service whose response carries a value (configure, store, inquire). Switch state global with Configuration puts every slave there; use it only when the network has a single LSS slave (§8.2.7).
A missing response of a confirmed service is LssTimeoutException. A missing response of switch state selective, identify, or the Fastscan reset step is a normal result: no slave matched.
Cancellation returns promptly, but later commands wait out an abandoned response window so its delayed replies cannot answer a new request. A cancelled Fastscan also preserves its probe's cycle gap. An abandoned ActivateBitTimingAsync(ushort, Nullable<int>, bool, CancellationToken) reserves both switch-delay periods, up to 2 × 65 535 ms, and the next command waits for them, including the release to waiting that LssCommissioning sends after a cancelled sequence. If transmission fails or is cancelled after entering the send service, delivery can remain indeterminate: the driver may still transmit arbitrarily later. The master then rejects every subsequent command with a CanOpenTransportException. Dispose it, reset the transport and re-establish a quiescent network before opening another master. Explicit driver rejection and cancellation checked before entering the service leave the master usable.
Properties¶
ILssMaster.Options Property¶
Options this master was opened with.
Property Value¶
Methods¶
ILssMaster.ActivateBitTimingAsync(ushort, Nullable<int>, bool, CancellationToken) Method¶
Tells every slave in LSS configuration to copy the pending bit rate to the active one after switchDelayMilliseconds, and to stay silent for a second period of the same length (§6.4.4, §7.5.3). Both periods are measured from the activation transmission; delayed confirmations do not restart them. This call waits out both periods. When bitsPerSecond and BitRateSwitch are both set, the switch runs after the first period, before slaves may transmit again. When returnToWaiting is true, switch state global (waiting) follows. With bitsPerSecond and the switch callback it is sent once both periods have elapsed, on the new rate: CiA 305 §6.4.4 and Figure 15 keep the master and every slave silent through both periods. A zero delay has already moved the slave, so it then requires both, and the frame is sent after the switch. Without a host switch the master would stay on the old rate, so a positive delay sends waiting before either period ends instead, while both ends still share a bitrate. That frame inside the first period is a deliberate departure from §6.4.4, kept for adapters that cannot change rate while open; 2.0 is planned to require a host switch for it. If its confirmation returns at or after the first deadline, the call fails with CanOpenTransportException after both periods have elapsed. The alternative that keeps to §6.4.4 without a host switch: omit returnToWaiting, dispose this master after the call returns, and send switch state global from a new master on the new bus. Cancellation or failure after a confirmed send returns to the caller promptly; subsequent commands still wait for the activation's two periods. With returnToWaiting, a positive delay and a host switch, the slaves switch whatever the caller does, so once the activation is confirmed the master follows through on its own: it switches after the first period and sends waiting after the second, even when the caller has stopped waiting, and subsequent commands also wait for that. Its failure reaches only a caller still waiting. Disposing the master ends it. An indeterminate send makes the master unusable as described in the interface remarks.
System.Threading.Tasks.Task ActivateBitTimingAsync(ushort switchDelayMilliseconds, System.Nullable<int> bitsPerSecond=null, bool returnToWaiting=false, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
switchDelayMilliseconds UInt16
returnToWaiting Boolean
cancellationToken CancellationToken
Returns¶
Exceptions¶
ArgumentException
A bit rate requires a switch callback. A zero delay with returnToWaiting requires both.
CanOpenTransportException
The old-rate waiting window was missed and no host bit-rate switch is available.
ILssMaster.ConfigureBitTimingAsync(byte, byte, CancellationToken) Method¶
Configures the pending bit timing of the single slave in LSS configuration (§6.4.3, §7.5.2). Table selector 0 is the CiA 301 table (LssBitTiming); selectors ManufacturerTableFirst..ManufacturerTableLast address a table the slave defines.
System.Threading.Tasks.Task<CanKit.Pro.CANopen.Lss.LssServiceResult> ConfigureBitTimingAsync(byte tableSelector, byte tableIndex, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
tableSelector Byte
tableIndex Byte
cancellationToken CancellationToken
Returns¶
ILssMaster.ConfigureNodeIdAsync(byte, CancellationToken) Method¶
Configures the pending node-id of the single slave in LSS configuration (§6.4.2, §7.5.1). nodeId is sent as given, including values the protocol reserves, so the slave's error code can be observed. UnconfiguredNodeId is a legal pending value.
System.Threading.Tasks.Task<CanKit.Pro.CANopen.Lss.LssServiceResult> ConfigureNodeIdAsync(byte nodeId, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
nodeId Byte
cancellationToken CancellationToken
Returns¶
ILssMaster.FastscanAsync(LssFastscanRequest, CancellationToken) Method¶
Runs LSS Fastscan for one unconfigured slave (§6.7, §8.2.3). A null request scans all four LSS numbers from bit 31. On success that slave is in LSS configuration and the service LSS switch state selective is not required.
System.Threading.Tasks.Task<CanKit.Pro.CANopen.Lss.LssFastscanResult> FastscanAsync(CanKit.Pro.CANopen.Lss.LssFastscanRequest? request=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
request LssFastscanRequest
cancellationToken CancellationToken
Returns¶
Exceptions¶
ArgumentException
The vendor-id is skipped, or more than two LSS numbers
are skipped. A partial scan must still select one slave (§6.7, annex A.3.4).
ArgumentOutOfRangeException
A field mode is undefined or its known-high-bit count is outside 0..32.
ILssMaster.IdentifyNonConfiguredSlavesAsync(CancellationToken) Method¶
Asks every non-configured slave (pending node-id UnconfiguredNodeId, no active node-id, NMT initialization) to identify itself (§6.6.4, §7.7.3). The call waits out IdentificationTimeout, as IdentifyRemoteSlavesAsync(LssIdentityRange, CancellationToken) does.
System.Threading.Tasks.Task<bool> IdentifyNonConfiguredSlavesAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.IdentifyRemoteSlavesAsync(LssIdentityRange, CancellationToken) Method¶
Asks every slave whose LSS address lies in range to identify itself (§6.6.2, §7.7.1). Returns true when at least one does. The call waits out IdentificationTimeout before it returns, so a later reply is not left for the next command.
System.Threading.Tasks.Task<bool> IdentifyRemoteSlavesAsync(CanKit.Pro.CANopen.Lss.LssIdentityRange range, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
range LssIdentityRange
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireAddressAsync(CancellationToken) Method¶
Reads the whole LSS address by the four inquire services (§6.5.2).
System.Threading.Tasks.Task<CanKit.Pro.CANopen.Lss.LssAddress> InquireAddressAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireNodeIdAsync(CancellationToken) Method¶
Reads the active node-id of the single slave in LSS configuration (§7.6.2). A slave that
is still in NMT initialization and has no active node-id reports its pending node-id,
which may be UnconfiguredNodeId. The LSS slave of a node opened
with CanOpen.OpenNode never holds such a pending value: it activates a node-id in
1..127 as soon as configure node-id writes one, so without an active node-id it reports
UnconfiguredNodeId.
System.Threading.Tasks.Task<byte> InquireNodeIdAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireProductCodeAsync(CancellationToken) Method¶
Reads 1018h:02 from the single slave in LSS configuration (§7.6.1.3).
System.Threading.Tasks.Task<uint> InquireProductCodeAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireRevisionNumberAsync(CancellationToken) Method¶
Reads 1018h:03 from the single slave in LSS configuration (§7.6.1.4).
System.Threading.Tasks.Task<uint> InquireRevisionNumberAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireSerialNumberAsync(CancellationToken) Method¶
Reads 1018h:04 from the single slave in LSS configuration (§7.6.1.5).
System.Threading.Tasks.Task<uint> InquireSerialNumberAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.InquireVendorIdAsync(CancellationToken) Method¶
Reads 1018h:01 from the single slave in LSS configuration (§7.6.1.2).
System.Threading.Tasks.Task<uint> InquireVendorIdAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.StoreConfigurationAsync(CancellationToken) Method¶
Asks the single slave in LSS configuration to copy pending node-id and bit timing to persistent storage (§6.4.5, §7.5.4).
System.Threading.Tasks.Task<CanKit.Pro.CANopen.Lss.LssServiceResult> StoreConfigurationAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
cancellationToken CancellationToken
Returns¶
ILssMaster.SwitchStateGlobalAsync(LssState, CancellationToken) Method¶
Switches every LSS slave to state (§6.3.2, §7.4.1). The service is unconfirmed: the call completes when the frame has been handed to the bus.
System.Threading.Tasks.Task SwitchStateGlobalAsync(CanKit.Pro.CANopen.Lss.LssState state, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
state LssState
cancellationToken CancellationToken
Returns¶
ILssMaster.SwitchStateSelectiveAsync(LssAddress, CancellationToken) Method¶
Switches the slave with address to LSS configuration (§6.3.3, §7.4.2). Returns false when no slave confirms within ResponseTimeout.
System.Threading.Tasks.Task<bool> SwitchStateSelectiveAsync(CanKit.Pro.CANopen.Lss.LssAddress address, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
address LssAddress
cancellationToken CancellationToken
Returns¶
ILssMaster.TransceiveManufacturerAsync(byte, ReadOnlyMemory<byte>, CancellationToken) Method¶
Sends a manufacturer-specific command (specifier 128..255, §7.3) and returns the first slave frame with the same specifier, or null when none arrives within ResponseTimeout. The returned buffer is 8 bytes.
System.Threading.Tasks.Task<byte[]?> TransceiveManufacturerAsync(byte commandSpecifier, System.ReadOnlyMemory<byte> parameters, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters¶
commandSpecifier Byte
parameters ReadOnlyMemory<Byte>
cancellationToken CancellationToken