CANOPEN_CLIENT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, frames, protocol vocabulary and configuration. More...

Classes

struct  canopen_client::Result< T >
 The value of a call, or why there is none. More...
 
struct  canopen_client::Result< void >
 The result of a call that returns no value. More...
 
struct  canopen_client::CanFrame
 One classic CAN frame with an 11-bit identifier. More...
 
struct  canopen_client::SdoAbortInfo
 The last SDO abort, from the node or from this driver. More...
 
struct  canopen_client::SdoReply
 A decoded SDO server reply. More...
 
struct  canopen_client::HeartbeatInfo
 A decoded heartbeat or node-guarding reply. More...
 
struct  canopen_client::NodeStatus
 What the heartbeat consumer knows about one node. More...
 
struct  canopen_client::EmcyEvent
 One emergency message (EMCY). More...
 
struct  canopen_client::PdoSample
 The latest frame received on a subscribed TPDO identifier. More...
 
struct  canopen_client::Stats
 Counters of the receive path, for diagnostics. More...
 
struct  canopen_client::PdoMapEntry
 One mapped object of a PDO. More...
 
struct  canopen_client::PdoConfig
 The communication and mapping parameters of one PDO. More...
 
struct  canopen_client::DriveObjects
 The object indices of a drive; the defaults are the profile's, a remapped drive overrides them. More...
 
struct  canopen_client::Config
 Everything the client uses; the defaults suit a node on a 500 kbit/s bus. More...
 

Enumerations

enum class  canopen_client::Error : uint8_t {
  canopen_client::Error::Ok = 0 , canopen_client::Error::NotInitialized = 1 , canopen_client::Error::InvalidArgument = 2 , canopen_client::Error::Bus = 3 ,
  canopen_client::Error::Timeout = 4 , canopen_client::Error::DeviceIdMismatch = 5 , canopen_client::Error::Crc = 6 , canopen_client::Error::Busy = 7 ,
  canopen_client::Error::DeviceFault = 8 , canopen_client::Error::Unsupported = 9 , canopen_client::Error::SdoAbort = 16 , canopen_client::Error::Protocol = 17 ,
  canopen_client::Error::BufferTooSmall = 18 , canopen_client::Error::InvalidFrame = 19 , canopen_client::Error::NodeState = 20 , canopen_client::Error::DriveFault = 21
}
 Why a call failed. Values 0 to 9 are the shared base set; client-specific values start at 16. More...
 
enum class  canopen_client::LogLevel : uint8_t { canopen_client::LogLevel::Error = 0 , canopen_client::LogLevel::Warning , canopen_client::LogLevel::Info , canopen_client::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  canopen_client::Verify : uint8_t { canopen_client::Verify::None = 0 , canopen_client::Verify::ReadBack }
 Whether a setter or a transfer reads back what it wrote (extra bus traffic). More...
 
enum class  canopen_client::RxStatus : uint8_t { canopen_client::RxStatus::Frame = 0 , canopen_client::RxStatus::Timeout , canopen_client::RxStatus::Error }
 What a port's Receive() hook reports. More...
 
enum class  canopen_client::NmtCommand : uint8_t {
  canopen_client::NmtCommand::Start = 0x01 , canopen_client::NmtCommand::Stop = 0x02 , canopen_client::NmtCommand::PreOperational = 0x80 , canopen_client::NmtCommand::ResetNode = 0x81 ,
  canopen_client::NmtCommand::ResetCommunication = 0x82
}
 NMT master command (the first data byte of the frame on identifier 0x000). More...
 
enum class  canopen_client::NmtState : uint8_t { canopen_client::NmtState::BootUp = 0x00 , canopen_client::NmtState::Stopped = 0x04 , canopen_client::NmtState::Operational = 0x05 , canopen_client::NmtState::PreOperational = 0x7F }
 NMT state a node reports in its heartbeat or guarding reply (bit 7 masked off). More...
 
enum class  canopen_client::SdoAbortCode : uint32_t {
  canopen_client::SdoAbortCode::ToggleNotAlternated = 0x05030000 , canopen_client::SdoAbortCode::Timeout = 0x05040000 , canopen_client::SdoAbortCode::InvalidCommandSpecifier , canopen_client::SdoAbortCode::InvalidBlockSize = 0x05040002 ,
  canopen_client::SdoAbortCode::InvalidSequenceNumber = 0x05040003 , canopen_client::SdoAbortCode::CrcError = 0x05040004 , canopen_client::SdoAbortCode::OutOfMemory = 0x05040005 , canopen_client::SdoAbortCode::UnsupportedAccess = 0x06010000 ,
  canopen_client::SdoAbortCode::WriteOnly = 0x06010001 , canopen_client::SdoAbortCode::ReadOnly = 0x06010002 , canopen_client::SdoAbortCode::ObjectNotFound = 0x06020000 , canopen_client::SdoAbortCode::NotMappable = 0x06040041 ,
  canopen_client::SdoAbortCode::PdoLengthExceeded = 0x06040042 , canopen_client::SdoAbortCode::ParameterIncompatible = 0x06040043 , canopen_client::SdoAbortCode::InternalIncompatibility = 0x06040047 , canopen_client::SdoAbortCode::HardwareError = 0x06060000 ,
  canopen_client::SdoAbortCode::LengthMismatch , canopen_client::SdoAbortCode::LengthTooHigh = 0x06070012 , canopen_client::SdoAbortCode::LengthTooLow = 0x06070013 , canopen_client::SdoAbortCode::SubIndexNotFound = 0x06090011 ,
  canopen_client::SdoAbortCode::InvalidValue = 0x06090030 , canopen_client::SdoAbortCode::ValueTooHigh = 0x06090031 , canopen_client::SdoAbortCode::ValueTooLow = 0x06090032 , canopen_client::SdoAbortCode::MaxLessThanMin = 0x06090036 ,
  canopen_client::SdoAbortCode::SdoResourceUnavailable = 0x060A0023 , canopen_client::SdoAbortCode::GeneralError = 0x08000000 , canopen_client::SdoAbortCode::StoreFailed = 0x08000020 , canopen_client::SdoAbortCode::LocalControl = 0x08000021 ,
  canopen_client::SdoAbortCode::DeviceState = 0x08000022 , canopen_client::SdoAbortCode::NoDictionary = 0x08000023 , canopen_client::SdoAbortCode::NoData = 0x08000024
}
 SDO abort codes the driver names. Any 32-bit value can arrive; SdoAbortInfo::code keeps the raw value and AbortCodeName() names it. More...
 
enum class  canopen_client::SdoReplyKind : uint8_t {
  canopen_client::SdoReplyKind::InitiateDownload = 0 , canopen_client::SdoReplyKind::SegmentDownload , canopen_client::SdoReplyKind::InitiateUpload , canopen_client::SdoReplyKind::SegmentUpload ,
  canopen_client::SdoReplyKind::Abort
}
 The kind of an SDO server reply. More...
 
enum class  canopen_client::FrameClass : uint8_t {
  canopen_client::FrameClass::None = 0 , canopen_client::FrameClass::Heartbeat , canopen_client::FrameClass::Emcy , canopen_client::FrameClass::Pdo ,
  canopen_client::FrameClass::Sync , canopen_client::FrameClass::Ignored , canopen_client::FrameClass::Invalid
}
 What Poll() did with the frame it received. More...
 
enum class  canopen_client::PdoKind : uint8_t { canopen_client::PdoKind::Receive = 0 , canopen_client::PdoKind::Transmit = 1 }
 Whether a PDO is a receive PDO (client to node) or a transmit PDO (node to client). More...
 
enum class  canopen_client::DriveState : uint8_t {
  NotReadyToSwitchOn = 0 , SwitchOnDisabled , ReadyToSwitchOn , SwitchedOn ,
  OperationEnabled , QuickStopActive , FaultReactionActive , Fault ,
  canopen_client::DriveState::Unknown
}
 The drive state machine states, decoded from the statusword. More...
 
enum class  canopen_client::OperationMode : int8_t {
  NoMode = 0 , ProfilePosition = 1 , Velocity = 2 , ProfileVelocity = 3 ,
  ProfileTorque = 4 , Homing = 6 , InterpolatedPosition = 7 , CyclicSynchronousPosition = 8 ,
  CyclicSynchronousVelocity = 9 , CyclicSynchronousTorque = 10
}
 Modes of operation (object 0x6060), as the profile numbers them.
 

Functions

constexpr const char * canopen_client::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr bool canopen_client::IsValid (const CanFrame &frame) noexcept
 Whether a frame is representable on the bus: identifier at most 0x7FF, length at most 8.
 
constexpr const char * canopen_client::AbortCodeName (uint32_t code) noexcept
 The name of an abort code, for logs.
 
constexpr const char * canopen_client::ToString (DriveState state) noexcept
 The name of a drive state, for logs.
 
constexpr Error canopen_client::Validate (const Config &config) noexcept
 Check a configuration without touching the bus.
 
constexpr Config canopen_client::FastBusPreset () noexcept
 Short timeouts for a fast, lightly loaded bus.
 
constexpr Config canopen_client::SlowBusPreset () noexcept
 Long timeouts for a slow or busy bus (for example 125 kbit/s with many nodes).
 
constexpr const char * canopen_client::GetDriverVersion () noexcept
 
constexpr uint32_t canopen_client::GetDriverVersionMajor () noexcept
 
constexpr uint32_t canopen_client::GetDriverVersionMinor () noexcept
 
constexpr uint32_t canopen_client::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint16_t canopen_client::kMaxCanId = 0x7FF
 Largest 11-bit CAN identifier.
 
constexpr uint8_t canopen_client::kMaxDlc = 8
 Longest classic CAN payload in bytes.
 
constexpr uint8_t canopen_client::kBroadcastNode = 0
 Node identifier of "every node" in an NMT command.
 
constexpr uint8_t canopen_client::kMinNodeId = 1
 Lowest valid node identifier.
 
constexpr uint8_t canopen_client::kMaxNodeId = 127
 Highest valid node identifier.
 
constexpr uint16_t canopen_client::kCobIdNmt = 0x000
 NMT command identifier (pre-defined connection set).
 
constexpr uint16_t canopen_client::kCobIdSync = 0x080
 SYNC identifier.
 
constexpr uint16_t canopen_client::kCobIdEmcyBase = 0x080
 EMCY identifiers are this plus the node identifier.
 
constexpr uint16_t canopen_client::kCobIdSdoResponseBase = 0x580
 SDO response (server to client) identifiers are this plus the node identifier.
 
constexpr uint16_t canopen_client::kCobIdSdoRequestBase = 0x600
 SDO request (client to server) identifiers are this plus the node identifier.
 
constexpr uint16_t canopen_client::kCobIdHeartbeatBase = 0x700
 Heartbeat and node-guarding identifiers are this plus the node identifier.
 
constexpr uint16_t canopen_client::kPdoCobIdMin = 0x181
 Lowest identifier the driver accepts for a PDO (the first pre-defined TPDO1 of node 1).
 
constexpr uint16_t canopen_client::kPdoCobIdMax = 0x57F
 Highest identifier the driver accepts for a PDO (the last pre-defined RPDO4 identifier).
 
constexpr std::size_t canopen_client::kMonitorCapacity = 16
 Nodes the heartbeat and guarding consumer can watch at once.
 
constexpr std::size_t canopen_client::kPdoSubscriptionCapacity = 16
 TPDO identifiers the receive path can hold the latest frame of.
 
constexpr std::size_t canopen_client::kEmcyQueueCapacity = 8
 EMCY events queued between two PopEmcy() calls.
 
constexpr std::size_t canopen_client::kMaxPdoEntries = 16
 Entries of one PDO mapping the helpers handle.
 
constexpr uint32_t canopen_client::kMaxFramesPerWait = 256
 Frames one blocking wait looks at before it gives up (a flooded bus must not stall a call).
 
constexpr uint32_t canopen_client::kMaxDrainFrames = 64
 Frames drained and routed before a request is sent.
 
constexpr uint32_t canopen_client::kMaxSdoSegments = 65536
 Segments of one segmented SDO transfer (7 bytes each).
 
constexpr uint32_t canopen_client::kMaxReceivesPerWait = 65536
 
constexpr uint16_t canopen_client::kControlShutdown = 0x0006
 Controlword: shutdown (to Ready to switch on).
 
constexpr uint16_t canopen_client::kControlSwitchOn = 0x0007
 Controlword: switch on (to Switched on).
 
constexpr uint16_t canopen_client::kControlDisableVoltage = 0x0000
 Controlword: disable voltage (to Switch on disabled).
 
constexpr uint16_t canopen_client::kControlQuickStop = 0x0002
 Controlword: quick stop.
 
constexpr uint16_t canopen_client::kControlEnableOperation = 0x000F
 Controlword: enable operation (to Operation enabled).
 
constexpr uint16_t canopen_client::kControlFaultReset = 0x0080
 Controlword: fault reset (bit 7, acts on the rising edge).
 
constexpr uint32_t canopen_client::kMaxSdoTimeoutUs = 60'000'000
 Longest SDO timeout in microseconds.
 

Detailed Description

Errors, results, frames, protocol vocabulary and configuration.

Enumeration Type Documentation

◆ DriveState

enum class canopen_client::DriveState : uint8_t
strong

The drive state machine states, decoded from the statusword.

Enumerator
Unknown 

The statusword matches no state.

◆ Error

enum class canopen_client::Error : uint8_t
strong

Why a call failed. Values 0 to 9 are the shared base set; client-specific values start at 16.

DeviceIdMismatch, Crc and Busy are never returned: the CAN controller checks the frame CRC, and every call blocks until it finishes.

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

The port failed to send or to receive a frame.

Timeout 

No valid reply arrived in time (SDO, node guarding, drive state).

DeviceIdMismatch 

Not returned by this driver.

Crc 

Not returned by this driver.

Busy 

Not returned by this driver.

DeviceFault 

A read-back showed a value other than the one written.

Unsupported 

The call needs a port hook the port lacks, or a transfer type the driver does not implement.

SdoAbort 

The node aborted the SDO transfer; see GetLastAbort().

Protocol 

A reply broke the protocol (command specifier, toggle bit, size).

BufferTooSmall 

An upload is larger than the caller's buffer.

InvalidFrame 

A frame fails validation (identifier, length or content).

NodeState 

The node is known to be in an NMT state that ignores the request.

DriveFault 

The drive is in the Fault state or reports a state no transition leaves.

◆ FrameClass

enum class canopen_client::FrameClass : uint8_t
strong

What Poll() did with the frame it received.

Enumerator
None 

No frame arrived within the timeout.

Heartbeat 

A heartbeat or boot-up message; the node table is updated.

Emcy 

An emergency message; queued for PopEmcy().

Pdo 

A subscribed TPDO; its sample is updated.

Sync 

A SYNC frame from another producer.

Ignored 

A valid frame nobody here asked for (including a stale SDO reply).

Invalid 

A frame that fails validation; counted and dropped.

◆ LogLevel

enum class canopen_client::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events.

Debug 

Detail for bring-up.

◆ NmtCommand

enum class canopen_client::NmtCommand : uint8_t
strong

NMT master command (the first data byte of the frame on identifier 0x000).

Enumerator
Start 

Go to Operational.

Stop 

Go to Stopped.

PreOperational 

Go to Pre-operational.

ResetNode 

Reset the whole application and communication.

ResetCommunication 

Reset the communication parameters only.

◆ NmtState

enum class canopen_client::NmtState : uint8_t
strong

NMT state a node reports in its heartbeat or guarding reply (bit 7 masked off).

Enumerator
BootUp 

The boot-up message; the node continues to Pre-operational.

Stopped 

Only NMT and heartbeat; SDO and PDO are off.

Operational 

SDO and PDO are on.

PreOperational 

SDO is on, PDO is off.

◆ PdoKind

enum class canopen_client::PdoKind : uint8_t
strong

Whether a PDO is a receive PDO (client to node) or a transmit PDO (node to client).

Enumerator
Receive 

RPDO: the node consumes it.

Transmit 

TPDO: the node produces it.

◆ RxStatus

enum class canopen_client::RxStatus : uint8_t
strong

What a port's Receive() hook reports.

Enumerator
Frame 

A frame was received into the argument.

Timeout 

No frame arrived within the timeout (not an error).

Error 

The controller failed (bus off, driver not running).

◆ SdoAbortCode

enum class canopen_client::SdoAbortCode : uint32_t
strong

SDO abort codes the driver names. Any 32-bit value can arrive; SdoAbortInfo::code keeps the raw value and AbortCodeName() names it.

Enumerator
ToggleNotAlternated 

Toggle bit not alternated.

Timeout 

SDO protocol timed out.

InvalidCommandSpecifier 

Client or server command specifier not valid or unknown.

InvalidBlockSize 

Invalid block size (block mode only).

InvalidSequenceNumber 

Invalid sequence number (block mode only).

CrcError 

CRC error (block mode only).

OutOfMemory 

Out of memory.

UnsupportedAccess 

Unsupported access to an object.

WriteOnly 

Attempt to read a write-only object.

ReadOnly 

Attempt to write a read-only object.

ObjectNotFound 

Object does not exist in the object dictionary.

NotMappable 

Object cannot be mapped to the PDO.

PdoLengthExceeded 

The mapped objects would exceed the PDO length.

ParameterIncompatible 

General parameter incompatibility.

InternalIncompatibility 

General internal incompatibility in the device.

HardwareError 

Access failed due to a hardware error.

LengthMismatch 

Data type does not match, length of service parameter does not match.

LengthTooHigh 

Data type does not match, length of service parameter too high.

LengthTooLow 

Data type does not match, length of service parameter too low.

SubIndexNotFound 

Sub-index does not exist.

InvalidValue 

Invalid value for parameter (download only).

ValueTooHigh 

Value of parameter written too high (download only).

ValueTooLow 

Value of parameter written too low (download only).

MaxLessThanMin 

Maximum value is less than minimum value.

SdoResourceUnavailable 

Resource not available: SDO connection.

GeneralError 

General error.

StoreFailed 

Data cannot be transferred or stored to the application.

LocalControl 

... because of local control.

DeviceState 

... because of the present device state.

NoDictionary 

Object dictionary dynamic generation fails or none present.

NoData 

No data available.

◆ SdoReplyKind

enum class canopen_client::SdoReplyKind : uint8_t
strong

The kind of an SDO server reply.

Enumerator
InitiateDownload 

Response to an initiate download request (scs 3).

SegmentDownload 

Response to a download segment (scs 1).

InitiateUpload 

Response to an initiate upload request (scs 2).

SegmentUpload 

A segment of upload data (scs 0).

Abort 

Abort transfer (scs 4).

◆ Verify

enum class canopen_client::Verify : uint8_t
strong

Whether a setter or a transfer reads back what it wrote (extra bus traffic).

Enumerator
None 

No read-back: the node's acknowledgement is the only check.

ReadBack 

Read the object again and compare; costs one more SDO exchange.

Function Documentation

◆ AbortCodeName()

constexpr const char * canopen_client::AbortCodeName ( uint32_t  code)
constexprnoexcept

The name of an abort code, for logs.

Parameters
codeThe raw 32-bit abort code.
Returns
A static string; "Unknown" for a code the driver does not name.

◆ FastBusPreset()

constexpr Config canopen_client::FastBusPreset ( )
constexprnoexcept

Short timeouts for a fast, lightly loaded bus.

Returns
The preset.

◆ GetDriverVersion()

constexpr const char * canopen_client::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0". No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t canopen_client::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t canopen_client::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t canopen_client::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ IsValid()

constexpr bool canopen_client::IsValid ( const CanFrame &  frame)
constexprnoexcept

Whether a frame is representable on the bus: identifier at most 0x7FF, length at most 8.

Parameters
frameThe frame.
Returns
true when valid.

◆ SlowBusPreset()

constexpr Config canopen_client::SlowBusPreset ( )
constexprnoexcept

Long timeouts for a slow or busy bus (for example 125 kbit/s with many nodes).

Returns
The preset.

◆ ToString() [1/2]

constexpr const char * canopen_client::ToString ( DriveState  state)
constexprnoexcept

The name of a drive state, for logs.

Parameters
stateThe state.
Returns
A static string; "Unknown" for a value that is not an enumerator.

◆ ToString() [2/2]

constexpr const char * canopen_client::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error canopen_client::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the bus.

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument.

Variable Documentation

◆ kMaxReceivesPerWait

constexpr uint32_t canopen_client::kMaxReceivesPerWait = 65536
inlineconstexpr

Receive() calls one blocking wait makes at most, whatever they return, before it gives up. Only frames count against kMaxFramesPerWait; this bounds a port that returns early with no frame.