CANOPEN_CLIENT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
canopen_client::Client< Port > Class Template Reference

A CANopen client on one CAN bus. More...

#include <canopen_client.hpp>

Public Member Functions

 Client (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 Client (const Client &)=delete
 One driver object per bus.
 
Client & operator= (const Client &)=delete
 One driver object per bus.
 
Result< void > EnsureInitialized () noexcept
 Start the client, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Mark the driver uninitialised and forget what it received. No bus traffic: nodes are left in the state they are in (send the NMT command you want first).
 
Result< void > SetConfig (const Config &config) noexcept
 Replace the configuration.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
 
Result< void > SendNmt (NmtCommand command, uint8_t node) noexcept
 Send an NMT command. Never refused for a state reason: Stop and every other command go out whatever the driver believes about the node or a transfer in flight. A reset command also restarts the guarding toggle of the node (or of every node).
 
Result< void > SendSync (uint8_t counter=0) noexcept
 Send one SYNC frame, with a counter byte when counter is not 0.
 
Result< void > SendRpdo (uint16_t cob_id, std::span< const uint8_t > data) noexcept
 Send a PDO the node consumes (an RPDO from the node's side).
 
Result< void > SdoDownloadUnconfirmed (uint8_t node, uint16_t index, uint8_t sub, std::span< const uint8_t > data) noexcept
 Write 1 to 4 bytes to an object with an expedited SDO download and do not wait for the reply: the transmit-only mode's write. The node's answer, including an abort, is not read, so a failed write is not noticed. Use SdoDownload() when the port can receive.
 
Result< void > SendRawFrame (const CanFrame &frame) noexcept
 Diagnostic: send one frame exactly as given. A single Send(): no retry, no routing, and none of the driver's state (node table, toggle bits, node states) is touched. It bypasses the safety and state guards: any frame goes out, an NMT command or a controlword included, and the node table does not learn of it. Stop and disable with SendNmt(), DriveDisable() and DriveQuickStop().
 
Result< CanFrame > ReadRawFrame (uint32_t timeout_us) noexcept
 Diagnostic: take the next frame from the port as it is. One Receive(): no retry, no routing, no validation beyond the port's framing; the node table, the EMCY queue and the TPDO samples do not see the frame. The frame is also kept for GetLastRawFrame().
 
Result< CanFrame > ReadRawSdo (uint8_t node, uint16_t index, uint8_t sub) noexcept
 Diagnostic: one SDO initiate-upload request and the first frame the node's SDO server (identifier 0x580 + node) answers with, returned as received. One request, no retry, no segment follow-up, no toggle, size or multiplexer check, no node-state gate and no abort on a timeout. The receive queue is drained first (routed as usual), so the frame returned arrived after the request. Other frames that arrive meanwhile are routed as usual. Use it to see what a node really sends; use SdoUpload() to read an object.
 
Result< CanFrame > WriteRawSdo (uint8_t node, uint16_t index, uint8_t sub, std::span< const uint8_t > data) noexcept
 Diagnostic: one expedited SDO download request of 1 to 4 bytes and the first frame the node's SDO server answers with, returned as received (a download response or an abort). The same rules as ReadRawSdo().
 
const CanFrame & GetLastRawFrame () const &noexcept
 
void GetLastRawFrame () const &&=delete
 Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
 
Result< FrameClass > Poll (uint32_t timeout_us) noexcept
 Wait up to timeout_us for one frame and route it: heartbeat to the node table, EMCY to the queue, a subscribed TPDO to its sample, SYNC counted. A frame nobody asked for (including an SDO reply with no request in flight) is dropped and counted.
 
Result< void > MonitorNode (uint8_t node, uint32_t timeout_us) noexcept
 Watch a node's heartbeat. Registering again changes the timeout and keeps what was received.
 
Result< void > UnmonitorNode (uint8_t node) noexcept
 Stop watching a node.
 
Result< NodeStatus > GetNodeStatus (uint8_t node) noexcept
 What the consumer knows about a watched node; alive is judged now. The age is a 32-bit microsecond difference, so a heartbeat older than 71.6 minutes can look fresh: call this or Poll() at least hourly.
 
Result< void > ClearBootUp (uint8_t node) noexcept
 Forget that a boot-up message was seen from a node (NodeStatus::bootup_seen), so the next one (the node reset on its own) can be told from the first. The flag is otherwise set once and cleared only by an NMT reset this driver sends.
 
Result< NmtState > GuardNode (uint8_t node) noexcept
 One node-guarding exchange: a remote frame on 0x700 + node, then the reply, whose toggle bit must alternate (the first reply after a reset has it clear). A reply with the wrong toggle fails and resynchronises the expected bit to the one after it.
 
bool PopEmcy (EmcyEvent &event) noexcept
 Take the oldest queued emergency message.
 
const Stats & GetStats () const &noexcept
 
void GetStats () const &&=delete
 Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
 
Result< void > SubscribeTpdo (uint16_t cob_id, uint8_t dlc) noexcept
 Hold the latest frame of a TPDO identifier for ReadTpdo().
 
Result< void > UnsubscribeTpdo (uint16_t cob_id) noexcept
 Stop holding a TPDO identifier.
 
Result< PdoSample > ReadTpdo (uint16_t cob_id) const noexcept
 The latest frame received on a subscribed identifier.
 
Result< std::size_t > SdoUpload (uint8_t node, uint16_t index, uint8_t sub, std::span< uint8_t > out) noexcept
 Read an object: expedited when the node answers so, otherwise segmented. A reply that is not the answer to this request (another object, another command, a wrong toggle bit, the wrong length) never counts; see the Contract page.
 
Result< void > SdoDownload (uint8_t node, uint16_t index, uint8_t sub, std::span< const uint8_t > data) noexcept
 Write an object: expedited for 1 to 4 bytes, segmented for more.
 
Result< uint8_t > SdoReadU8 (uint8_t node, uint16_t index, uint8_t sub) noexcept
 Read an unsigned 8-bit object.
 
Result< uint16_t > SdoReadU16 (uint8_t node, uint16_t index, uint8_t sub) noexcept
 Read an unsigned 16-bit object.
 
Result< uint32_t > SdoReadU32 (uint8_t node, uint16_t index, uint8_t sub) noexcept
 Read an unsigned 32-bit object.
 
Result< void > SdoWriteU8 (uint8_t node, uint16_t index, uint8_t sub, uint8_t value) noexcept
 Write an unsigned 8-bit object (expedited, one byte).
 
Result< void > SdoWriteU16 (uint8_t node, uint16_t index, uint8_t sub, uint16_t value) noexcept
 Write an unsigned 16-bit object (expedited, two bytes).
 
Result< void > SdoWriteU32 (uint8_t node, uint16_t index, uint8_t sub, uint32_t value) noexcept
 Write an unsigned 32-bit object (expedited, four bytes).
 
const SdoAbortInfo & GetLastAbort () const &noexcept
 The last SDO abort, sent by a node or by this driver. No I/O.
 
void GetLastAbort () const &&=delete
 Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
 
Result< uint32_t > ReadDeviceType (uint8_t node) noexcept
 Read the device type (object 0x1000).
 
Result< uint8_t > ReadErrorRegister (uint8_t node) noexcept
 Read the error register (object 0x1001).
 
Result< void > WriteHeartbeatProducerTime (uint8_t node, uint16_t period_ms) noexcept
 Set the node's heartbeat producer time (object 0x1017).
 
Result< void > StoreParameters (uint8_t node, uint8_t group) noexcept
 Store parameters to non-volatile memory (object 0x1010, signature "save").
 
Result< void > RestoreDefaults (uint8_t node, uint8_t group) noexcept
 Restore default parameters (object 0x1011, signature "load"); they apply after the next reset of the node.
 
Result< void > ConfigureSync (uint32_t period_us, uint8_t counter_overflow) noexcept
 Set the SYNC period ServiceSync() keeps.
 
Result< bool > ServiceSync () noexcept
 Send a SYNC when the period has elapsed since the last one (the first call after ConfigureSync() sends at once). Call it at least as often as the period; a late call sends one SYNC and starts the next period from now, it never sends a burst to catch up.
 
Result< void > ConfigurePdo (uint8_t node, PdoKind kind, uint16_t number, const PdoConfig &config) noexcept
 Configure a PDO of a node over SDO, in the order the profile prescribes: invalidate the COB-ID, write the transmission type (and for a TPDO the inhibit time and event timer when not 0), clear the mapping count, write each entry, write the count, then write the COB-ID valid (when config.enabled). A failure leaves the PDO invalid, never half-configured and valid.
 
Result< void > DisablePdo (uint8_t node, PdoKind kind, uint16_t number) noexcept
 Invalidate a PDO (set bit 31 of its COB-ID, keeping the identifier).
 
Result< PdoConfig > ReadPdoConfig (uint8_t node, PdoKind kind, uint16_t number) noexcept
 Read a PDO's identifier, validity, transmission type and mapping back.
 
Result< uint16_t > ReadStatusword (uint8_t node, const DriveObjects &objects={}) noexcept
 Read the statusword.
 
Result< DriveState > ReadDriveState (uint8_t node, const DriveObjects &objects={}) noexcept
 Read the statusword and decode the drive state.
 
Result< void > DriveEnable (uint8_t node, const DriveObjects &objects={}) noexcept
 Walk the drive to Operation enabled: shutdown, switch on, enable operation, reading the statusword after each controlword and pausing Config::drive_poll_interval_us. Each state gets one controlword, so a slow drive's transition is never restarted. From Quick stop active it first disables voltage. It does not clear a fault.
 
Result< void > DriveDisable (uint8_t node, const DriveObjects &objects={}) noexcept
 Disable voltage (controlword 0x0000), from any state. Never refused: it ignores the node's heartbeat state and any earlier failure, including a Receive() error (the receive queue is dropped and the request is sent anyway), and is attempted Config::safety_attempts times until the node acknowledges it. A port that cannot send, or a node that never answers, still ends in an error: the attempts are bounded.
 
Result< void > DriveQuickStop (uint8_t node, const DriveObjects &objects={}) noexcept
 Quick stop (controlword 0x0002). Never refused, retried like DriveDisable().
 
Result< void > DriveResetFault (uint8_t node, const DriveObjects &objects={}) noexcept
 Reset a fault: wait out Fault reaction active, then give controlword bit 7 a rising edge and wait for the drive to leave Fault. A drive that is not in a fault state is left as it is; one whose statusword is no state is DriveFault. Both waits together take at most Config::drive_timeout_us. On success the controlword is 0x0000 again (bit 7 low).
 
Result< void > SetDriveMode (uint8_t node, OperationMode mode, const DriveObjects &objects={}, Verify verify=Verify::None) noexcept
 Select the mode of operation.
 
Result< OperationMode > ReadDriveMode (uint8_t node, const DriveObjects &objects={}) noexcept
 Read the mode of operation display.
 

Detailed Description

template<CanPort Port>
class canopen_client::Client< Port >

A CANopen client on one CAN bus.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start, use, optionally Deinitialize(). Every call that touches the bus returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts it as a side effect.

Two kinds of port. A CanPort (hooks EnsureInitialized and Send) gives the transmit-only mode: SendNmt(), SendSync(), SendRpdo() and SdoDownloadUnconfirmed(). A CanRxPort adds Receive and NowUs and gives everything else; the calls that need a reply are constrained on it and do not exist on a transmit-only port.

One request is in flight at a time. The class is not thread-safe: call it from one task, or serialise the calls.

Optional hook: void Log(LogLevel, const char* message) noexcept.

Template Parameters
PortYour class derived from CanInterface<Port>.

Constructor & Destructor Documentation

◆ Client()

template<CanPort Port>
canopen_client::Client< Port >::Client ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configThe timeouts and options, checked by EnsureInitialized() before any I/O.

Member Function Documentation

◆ ClearBootUp()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::ClearBootUp ( uint8_t  node)
noexcept

Forget that a boot-up message was seen from a node (NodeStatus::bootup_seen), so the next one (the node reset on its own) can be told from the first. The flag is otherwise set once and cleared only by an NMT reset this driver sends.

Parameters
nodeA node registered with MonitorNode().
Returns
Ok, NotInitialized or InvalidArgument (not watched).

◆ ConfigurePdo()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::ConfigurePdo ( uint8_t  node,
PdoKind  kind,
uint16_t  number,
const PdoConfig &  config 
)
noexcept

Configure a PDO of a node over SDO, in the order the profile prescribes: invalidate the COB-ID, write the transmission type (and for a TPDO the inhibit time and event timer when not 0), clear the mapping count, write each entry, write the count, then write the COB-ID valid (when config.enabled). A failure leaves the PDO invalid, never half-configured and valid.

Parameters
nodeThe server, 1 to 127.
kindReceive (RPDO) or transmit (TPDO) from the node's side.
numberThe PDO number, 1 to 512.
configThe parameters; it must pass ValidatePdoConfig() and map at least one entry.
Returns
Ok, InvalidArgument (nothing is sent) or the errors of SdoWriteU32().

◆ ConfigureSync()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::ConfigureSync ( uint32_t  period_us,
uint8_t  counter_overflow 
)
noexcept

Set the SYNC period ServiceSync() keeps.

Parameters
period_usThe period, 100 us to 60 s, or 0 to stop.
counter_overflow0 for no counter byte, or 2 to 240: the counter counts 1 up to it, then wraps to 1.
Returns
Ok, NotInitialized or InvalidArgument.

◆ Deinitialize()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::Deinitialize ( )
noexcept

Mark the driver uninitialised and forget what it received. No bus traffic: nodes are left in the state they are in (send the NMT command you want first).

Returns
Ok.

◆ DisablePdo()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::DisablePdo ( uint8_t  node,
PdoKind  kind,
uint16_t  number 
)
noexcept

Invalidate a PDO (set bit 31 of its COB-ID, keeping the identifier).

Parameters
nodeThe server, 1 to 127.
kindReceive or transmit.
numberThe PDO number, 1 to 512.
Returns
Ok or the errors of SdoReadU32() and SdoWriteU32().

◆ DriveDisable()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::DriveDisable ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Disable voltage (controlword 0x0000), from any state. Never refused: it ignores the node's heartbeat state and any earlier failure, including a Receive() error (the receive queue is dropped and the request is sent anyway), and is attempted Config::safety_attempts times until the node acknowledges it. A port that cannot send, or a node that never answers, still ends in an error: the attempts are bounded.

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
Ok, NotInitialized, InvalidArgument, or the error of the last attempt (Bus when the port's Receive() failed, after the frame was sent).

◆ DriveEnable()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::DriveEnable ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Walk the drive to Operation enabled: shutdown, switch on, enable operation, reading the statusword after each controlword and pausing Config::drive_poll_interval_us. Each state gets one controlword, so a slow drive's transition is never restarted. From Quick stop active it first disables voltage. It does not clear a fault.

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
Ok, DriveFault (Fault, or a statusword that is no state), Timeout (Config::drive_timeout_us passed without reaching it: the last controlword written may still take effect, so follow a Timeout with DriveDisable() if the drive must not run) or the SDO errors.

◆ DriveQuickStop()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::DriveQuickStop ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Quick stop (controlword 0x0002). Never refused, retried like DriveDisable().

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
As DriveDisable().

◆ DriveResetFault()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::DriveResetFault ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Reset a fault: wait out Fault reaction active, then give controlword bit 7 a rising edge and wait for the drive to leave Fault. A drive that is not in a fault state is left as it is; one whose statusword is no state is DriveFault. Both waits together take at most Config::drive_timeout_us. On success the controlword is 0x0000 again (bit 7 low).

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
Ok, DriveFault (the fault persists), Timeout or the SDO errors.

◆ EnsureInitialized()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::EnsureInitialized ( )
noexcept

Start the client, once: the only way to initialise the driver.

The first call checks the configuration, starts the port and clears the node table, the PDO subscriptions, the EMCY queue and the counters. After it succeeds, later calls return Ok at once with no I/O. After it fails, the driver stays uninitialised.

Returns
Ok, InvalidArgument (the stored configuration fails Validate(); the port is not touched) or Bus (the port could not start).

◆ GetConfig()

template<CanPort Port>
const Config & canopen_client::Client< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration in use. No I/O.

◆ GetLastAbort()

template<CanPort Port>
const SdoAbortInfo & canopen_client::Client< Port >::GetLastAbort ( ) const &
inlinenoexcept

The last SDO abort, sent by a node or by this driver. No I/O.

Returns
The abort; code is 0 when no transfer has aborted since EnsureInitialized().

◆ GetLastRawFrame()

template<CanPort Port>
const CanFrame & canopen_client::Client< Port >::GetLastRawFrame ( ) const &
inlinenoexcept
Returns
The last frame ReadRawFrame(), ReadRawSdo() or WriteRawSdo() returned (no I/O); all zero before the first.

◆ GetNodeStatus()

template<CanPort Port>
Result< NodeStatus > canopen_client::Client< Port >::GetNodeStatus ( uint8_t  node)
noexcept

What the consumer knows about a watched node; alive is judged now. The age is a 32-bit microsecond difference, so a heartbeat older than 71.6 minutes can look fresh: call this or Poll() at least hourly.

Parameters
nodeThe node.
Returns
The status, NotInitialized or InvalidArgument (not watched).

◆ GetStats()

template<CanPort Port>
const Stats & canopen_client::Client< Port >::GetStats ( ) const &
inlinenoexcept
Returns
The receive counters. No I/O.

◆ GuardNode()

template<CanPort Port>
Result< NmtState > canopen_client::Client< Port >::GuardNode ( uint8_t  node)
noexcept

One node-guarding exchange: a remote frame on 0x700 + node, then the reply, whose toggle bit must alternate (the first reply after a reset has it clear). A reply with the wrong toggle fails and resynchronises the expected bit to the one after it.

Parameters
nodeA node registered with MonitorNode().
Returns
The reported state, NotInitialized, InvalidArgument, Timeout (no reply within Config::guard_timeout_us), Protocol (toggle not alternated) or Bus.

◆ IsInitialized()

template<CanPort Port>
bool canopen_client::Client< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized(). No I/O.

◆ MonitorNode()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::MonitorNode ( uint8_t  node,
uint32_t  timeout_us 
)
noexcept

Watch a node's heartbeat. Registering again changes the timeout and keeps what was received.

Parameters
nodeThe node, 1 to 127.
timeout_usHow old the last heartbeat may be for alive, 1 ms to 60 s.
Returns
Ok, NotInitialized, InvalidArgument, or BufferTooSmall (the table, of kMonitorCapacity nodes, is full).

◆ Poll()

template<CanPort Port>
Result< FrameClass > canopen_client::Client< Port >::Poll ( uint32_t  timeout_us)
noexcept

Wait up to timeout_us for one frame and route it: heartbeat to the node table, EMCY to the queue, a subscribed TPDO to its sample, SYNC counted. A frame nobody asked for (including an SDO reply with no request in flight) is dropped and counted.

Parameters
timeout_usHow long to wait; 0 polls once.
Returns
What the frame was (FrameClass::None when none arrived), NotInitialized or Bus.

◆ PopEmcy()

template<CanPort Port>
bool canopen_client::Client< Port >::PopEmcy ( EmcyEvent &  event)
noexcept

Take the oldest queued emergency message.

Parameters
[out]eventThe message; unchanged when the queue is empty.
Returns
true when one was returned.

◆ ReadDeviceType()

template<CanPort Port>
Result< uint32_t > canopen_client::Client< Port >::ReadDeviceType ( uint8_t  node)
noexcept

Read the device type (object 0x1000).

Parameters
nodeThe server, 1 to 127.
Returns
The value or the errors of SdoReadU32().

◆ ReadDriveMode()

template<CanPort Port>
Result< OperationMode > canopen_client::Client< Port >::ReadDriveMode ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Read the mode of operation display.

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
The mode, or the errors of SdoReadU8().

◆ ReadDriveState()

template<CanPort Port>
Result< DriveState > canopen_client::Client< Port >::ReadDriveState ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Read the statusword and decode the drive state.

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
The state (Unknown for a pattern that is none), or the errors of ReadStatusword().

◆ ReadErrorRegister()

template<CanPort Port>
Result< uint8_t > canopen_client::Client< Port >::ReadErrorRegister ( uint8_t  node)
noexcept

Read the error register (object 0x1001).

Parameters
nodeThe server, 1 to 127.
Returns
The value or the errors of SdoReadU8().

◆ ReadPdoConfig()

template<CanPort Port>
Result< PdoConfig > canopen_client::Client< Port >::ReadPdoConfig ( uint8_t  node,
PdoKind  kind,
uint16_t  number 
)
noexcept

Read a PDO's identifier, validity, transmission type and mapping back.

Parameters
nodeThe server, 1 to 127.
kindReceive or transmit.
numberThe PDO number, 1 to 512.
Returns
The configuration (the inhibit time and event timer are not read), Unsupported for a 29-bit identifier, BufferTooSmall for a mapping with more than kMaxPdoEntries entries, or the SDO errors.

◆ ReadRawFrame()

template<CanPort Port>
Result< CanFrame > canopen_client::Client< Port >::ReadRawFrame ( uint32_t  timeout_us)
noexcept

Diagnostic: take the next frame from the port as it is. One Receive(): no retry, no routing, no validation beyond the port's framing; the node table, the EMCY queue and the TPDO samples do not see the frame. The frame is also kept for GetLastRawFrame().

Parameters
timeout_usHow long to wait; 0 polls once.
Returns
The frame, NotInitialized, Timeout or Bus.

◆ ReadRawSdo()

template<CanPort Port>
Result< CanFrame > canopen_client::Client< Port >::ReadRawSdo ( uint8_t  node,
uint16_t  index,
uint8_t  sub 
)
noexcept

Diagnostic: one SDO initiate-upload request and the first frame the node's SDO server (identifier 0x580 + node) answers with, returned as received. One request, no retry, no segment follow-up, no toggle, size or multiplexer check, no node-state gate and no abort on a timeout. The receive queue is drained first (routed as usual), so the frame returned arrived after the request. Other frames that arrive meanwhile are routed as usual. Use it to see what a node really sends; use SdoUpload() to read an object.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
Returns
The reply frame, NotInitialized, InvalidArgument (nothing is sent), Timeout (Config::sdo_timeout_us) or Bus.

◆ ReadStatusword()

template<CanPort Port>
Result< uint16_t > canopen_client::Client< Port >::ReadStatusword ( uint8_t  node,
const DriveObjects &  objects = {} 
)
noexcept

Read the statusword.

Parameters
nodeThe server, 1 to 127.
objectsThe drive's object indices.
Returns
The value or the errors of SdoReadU16(); InvalidArgument for an index below 0x1000.

◆ ReadTpdo()

template<CanPort Port>
Result< PdoSample > canopen_client::Client< Port >::ReadTpdo ( uint16_t  cob_id) const
noexcept

The latest frame received on a subscribed identifier.

Parameters
cob_idThe identifier.
Returns
The sample (sequence 0 means no frame yet), NotInitialized or InvalidArgument.

◆ RestoreDefaults()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::RestoreDefaults ( uint8_t  node,
uint8_t  group 
)
noexcept

Restore default parameters (object 0x1011, signature "load"); they apply after the next reset of the node.

Parameters
nodeThe server, 1 to 127.
groupThe sub-index: 1 all, 2 communication, 3 application, 4 manufacturer.
Returns
Ok, InvalidArgument (group not 1 to 4) or the errors of SdoWriteU32().

◆ SdoDownload()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SdoDownload ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
std::span< const uint8_t >  data 
)
noexcept

Write an object: expedited for 1 to 4 bytes, segmented for more.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
data1 byte or more (at most 2^32 - 1), little-endian.
Returns
Ok, or the errors of SdoUpload() except BufferTooSmall.

◆ SdoDownloadUnconfirmed()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SdoDownloadUnconfirmed ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
std::span< const uint8_t >  data 
)
noexcept

Write 1 to 4 bytes to an object with an expedited SDO download and do not wait for the reply: the transmit-only mode's write. The node's answer, including an abort, is not read, so a failed write is not noticed. Use SdoDownload() when the port can receive.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
data1 to 4 bytes, little-endian.
Returns
Ok, NotInitialized, InvalidArgument or Bus.

◆ SdoReadU16()

template<CanPort Port>
Result< uint16_t > canopen_client::Client< Port >::SdoReadU16 ( uint8_t  node,
uint16_t  index,
uint8_t  sub 
)
noexcept

Read an unsigned 16-bit object.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
Returns
The value, or the errors of SdoUpload(); Protocol when the node returns another length than 2.

◆ SdoReadU32()

template<CanPort Port>
Result< uint32_t > canopen_client::Client< Port >::SdoReadU32 ( uint8_t  node,
uint16_t  index,
uint8_t  sub 
)
noexcept

Read an unsigned 32-bit object.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
Returns
The value, or the errors of SdoUpload(); Protocol when the node returns another length than 4.

◆ SdoReadU8()

template<CanPort Port>
Result< uint8_t > canopen_client::Client< Port >::SdoReadU8 ( uint8_t  node,
uint16_t  index,
uint8_t  sub 
)
noexcept

Read an unsigned 8-bit object.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
Returns
The value, or the errors of SdoUpload(); Protocol when the node returns another length than 1.

◆ SdoUpload()

template<CanPort Port>
Result< std::size_t > canopen_client::Client< Port >::SdoUpload ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
std::span< uint8_t >  out 
)
noexcept

Read an object: expedited when the node answers so, otherwise segmented. A reply that is not the answer to this request (another object, another command, a wrong toggle bit, the wrong length) never counts; see the Contract page.

The node is refused with NodeState without a frame when its heartbeat says it is Stopped.

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
outWhere the data goes.
Returns
The number of bytes read, or NotInitialized, InvalidArgument, NodeState, Bus, Timeout (the driver then sends an SDO abort when Config::abort_on_timeout), SdoAbort (the node aborted: GetLastAbort()), Protocol, or BufferTooSmall (the driver aborts the transfer with 0x05040005; no data is written past out).

◆ SdoWriteU16()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SdoWriteU16 ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
uint16_t  value 
)
noexcept

Write an unsigned 16-bit object (expedited, two bytes).

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
valueThe value.
Returns
Ok or the errors of SdoDownload().

◆ SdoWriteU32()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SdoWriteU32 ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
uint32_t  value 
)
noexcept

Write an unsigned 32-bit object (expedited, four bytes).

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
valueThe value.
Returns
Ok or the errors of SdoDownload().

◆ SdoWriteU8()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SdoWriteU8 ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
uint8_t  value 
)
noexcept

Write an unsigned 8-bit object (expedited, one byte).

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
valueThe value.
Returns
Ok or the errors of SdoDownload().

◆ SendNmt()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SendNmt ( NmtCommand  command,
uint8_t  node 
)
noexcept

Send an NMT command. Never refused for a state reason: Stop and every other command go out whatever the driver believes about the node or a transfer in flight. A reset command also restarts the guarding toggle of the node (or of every node).

Parameters
commandThe command.
nodeThe target, 1 to 127, or 0 for every node.
Returns
Ok, NotInitialized, InvalidArgument (node above 127 or a value that is not a command; nothing is sent) or Bus.

◆ SendRawFrame()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SendRawFrame ( const CanFrame &  frame)
noexcept

Diagnostic: send one frame exactly as given. A single Send(): no retry, no routing, and none of the driver's state (node table, toggle bits, node states) is touched. It bypasses the safety and state guards: any frame goes out, an NMT command or a controlword included, and the node table does not learn of it. Stop and disable with SendNmt(), DriveDisable() and DriveQuickStop().

Parameters
frameA frame of the port's classic kind: identifier up to 0x7FF, at most 8 bytes.
Returns
Ok, NotInitialized, InvalidArgument (the frame fails IsValid(); nothing is sent) or Bus.

◆ SendRpdo()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SendRpdo ( uint16_t  cob_id,
std::span< const uint8_t >  data 
)
noexcept

Send a PDO the node consumes (an RPDO from the node's side).

Parameters
cob_idThe identifier, kPdoCobIdMin to kPdoCobIdMax.
data0 to 8 bytes laid out as the node's RPDO mapping says.
Returns
Ok, NotInitialized, InvalidArgument or Bus.

◆ SendSync()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SendSync ( uint8_t  counter = 0)
noexcept

Send one SYNC frame, with a counter byte when counter is not 0.

Parameters
counter0 for a SYNC without data, or 1 to 240.
Returns
Ok, NotInitialized, InvalidArgument or Bus.

◆ ServiceSync()

template<CanPort Port>
Result< bool > canopen_client::Client< Port >::ServiceSync ( )
noexcept

Send a SYNC when the period has elapsed since the last one (the first call after ConfigureSync() sends at once). Call it at least as often as the period; a late call sends one SYNC and starts the next period from now, it never sends a burst to catch up.

Returns
true when a SYNC was sent, false when it is not due or stopped; NotInitialized or Bus.

◆ SetConfig()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SetConfig ( const Config &  config)
noexcept

Replace the configuration.

Parameters
configThe new configuration.
Returns
Ok, or InvalidArgument (it fails Validate(); the old one stays).

◆ SetDriveMode()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SetDriveMode ( uint8_t  node,
OperationMode  mode,
const DriveObjects &  objects = {},
Verify  verify = Verify::None 
)
noexcept

Select the mode of operation.

Parameters
nodeThe server, 1 to 127.
modeThe mode; a manufacturer-specific negative value is a cast of the number.
objectsThe drive's object indices.
verifyVerify::ReadBack reads the mode display until it shows mode, for at most Config::drive_timeout_us (one extra SDO exchange per poll); the default does not.
Returns
Ok, DeviceFault (the display never showed the mode) or the SDO errors.

◆ StoreParameters()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::StoreParameters ( uint8_t  node,
uint8_t  group 
)
noexcept

Store parameters to non-volatile memory (object 0x1010, signature "save").

Parameters
nodeThe server, 1 to 127.
groupThe sub-index: 1 all, 2 communication, 3 application, 4 manufacturer.
Returns
Ok, InvalidArgument (group not 1 to 4) or the errors of SdoWriteU32().

◆ SubscribeTpdo()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::SubscribeTpdo ( uint16_t  cob_id,
uint8_t  dlc 
)
noexcept

Hold the latest frame of a TPDO identifier for ReadTpdo().

Parameters
cob_idThe identifier, kPdoCobIdMin to kPdoCobIdMax.
dlcThe length every frame on it must have, 1 to 8; others are dropped and counted.
Returns
Ok, NotInitialized, InvalidArgument, or BufferTooSmall (the table, of kPdoSubscriptionCapacity identifiers, is full).

◆ UnmonitorNode()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::UnmonitorNode ( uint8_t  node)
noexcept

Stop watching a node.

Parameters
nodeThe node.
Returns
Ok, NotInitialized or InvalidArgument (not watched).

◆ UnsubscribeTpdo()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::UnsubscribeTpdo ( uint16_t  cob_id)
noexcept

Stop holding a TPDO identifier.

Parameters
cob_idThe identifier.
Returns
Ok, NotInitialized or InvalidArgument (not subscribed).

◆ WriteHeartbeatProducerTime()

template<CanPort Port>
Result< void > canopen_client::Client< Port >::WriteHeartbeatProducerTime ( uint8_t  node,
uint16_t  period_ms 
)
noexcept

Set the node's heartbeat producer time (object 0x1017).

Parameters
nodeThe server, 1 to 127.
period_msThe period in milliseconds; 0 stops the heartbeat.
Returns
Ok or the errors of SdoWriteU16().

◆ WriteRawSdo()

template<CanPort Port>
Result< CanFrame > canopen_client::Client< Port >::WriteRawSdo ( uint8_t  node,
uint16_t  index,
uint8_t  sub,
std::span< const uint8_t >  data 
)
noexcept

Diagnostic: one expedited SDO download request of 1 to 4 bytes and the first frame the node's SDO server answers with, returned as received (a download response or an abort). The same rules as ReadRawSdo().

Parameters
nodeThe server, 1 to 127.
indexThe object index.
subThe sub-index.
data1 to 4 bytes, little-endian.
Returns
The reply frame, NotInitialized, InvalidArgument, Timeout or Bus.

The documentation for this class was generated from the following file: