CANOPEN_CLIENT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Concepts | Enumerations | Functions | Variables
canopen_client Namespace Reference

The CANopen client driver: everything it declares lives here; internals in detail. More...

Classes

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

Concepts

concept  CanPort
 Satisfied by a class that derives from CanInterface<Port> and implements the required hooks with exactly the types above, noexcept (handbook KB-CPP20-006).
 
concept  CanRxPort
 Satisfied by a CanPort that also receives frames and keeps time: the full client port.
 

Enumerations

enum class  Error : uint8_t {
  Error::Ok = 0 , Error::NotInitialized = 1 , Error::InvalidArgument = 2 , Error::Bus = 3 ,
  Error::Timeout = 4 , Error::DeviceIdMismatch = 5 , Error::Crc = 6 , Error::Busy = 7 ,
  Error::DeviceFault = 8 , Error::Unsupported = 9 , Error::SdoAbort = 16 , Error::Protocol = 17 ,
  Error::BufferTooSmall = 18 , Error::InvalidFrame = 19 , Error::NodeState = 20 , 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  LogLevel : uint8_t { LogLevel::Error = 0 , LogLevel::Warning , LogLevel::Info , LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  Verify : uint8_t { Verify::None = 0 , Verify::ReadBack }
 Whether a setter or a transfer reads back what it wrote (extra bus traffic). More...
 
enum class  RxStatus : uint8_t { RxStatus::Frame = 0 , RxStatus::Timeout , RxStatus::Error }
 What a port's Receive() hook reports. More...
 
enum class  NmtCommand : uint8_t {
  NmtCommand::Start = 0x01 , NmtCommand::Stop = 0x02 , NmtCommand::PreOperational = 0x80 , NmtCommand::ResetNode = 0x81 ,
  NmtCommand::ResetCommunication = 0x82
}
 NMT master command (the first data byte of the frame on identifier 0x000). More...
 
enum class  NmtState : uint8_t { NmtState::BootUp = 0x00 , NmtState::Stopped = 0x04 , NmtState::Operational = 0x05 , NmtState::PreOperational = 0x7F }
 NMT state a node reports in its heartbeat or guarding reply (bit 7 masked off). More...
 
enum class  SdoAbortCode : uint32_t {
  SdoAbortCode::ToggleNotAlternated = 0x05030000 , SdoAbortCode::Timeout = 0x05040000 , SdoAbortCode::InvalidCommandSpecifier , SdoAbortCode::InvalidBlockSize = 0x05040002 ,
  SdoAbortCode::InvalidSequenceNumber = 0x05040003 , SdoAbortCode::CrcError = 0x05040004 , SdoAbortCode::OutOfMemory = 0x05040005 , SdoAbortCode::UnsupportedAccess = 0x06010000 ,
  SdoAbortCode::WriteOnly = 0x06010001 , SdoAbortCode::ReadOnly = 0x06010002 , SdoAbortCode::ObjectNotFound = 0x06020000 , SdoAbortCode::NotMappable = 0x06040041 ,
  SdoAbortCode::PdoLengthExceeded = 0x06040042 , SdoAbortCode::ParameterIncompatible = 0x06040043 , SdoAbortCode::InternalIncompatibility = 0x06040047 , SdoAbortCode::HardwareError = 0x06060000 ,
  SdoAbortCode::LengthMismatch , SdoAbortCode::LengthTooHigh = 0x06070012 , SdoAbortCode::LengthTooLow = 0x06070013 , SdoAbortCode::SubIndexNotFound = 0x06090011 ,
  SdoAbortCode::InvalidValue = 0x06090030 , SdoAbortCode::ValueTooHigh = 0x06090031 , SdoAbortCode::ValueTooLow = 0x06090032 , SdoAbortCode::MaxLessThanMin = 0x06090036 ,
  SdoAbortCode::SdoResourceUnavailable = 0x060A0023 , SdoAbortCode::GeneralError = 0x08000000 , SdoAbortCode::StoreFailed = 0x08000020 , SdoAbortCode::LocalControl = 0x08000021 ,
  SdoAbortCode::DeviceState = 0x08000022 , SdoAbortCode::NoDictionary = 0x08000023 , 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  SdoReplyKind : uint8_t {
  SdoReplyKind::InitiateDownload = 0 , SdoReplyKind::SegmentDownload , SdoReplyKind::InitiateUpload , SdoReplyKind::SegmentUpload ,
  SdoReplyKind::Abort
}
 The kind of an SDO server reply. More...
 
enum class  FrameClass : uint8_t {
  FrameClass::None = 0 , FrameClass::Heartbeat , FrameClass::Emcy , FrameClass::Pdo ,
  FrameClass::Sync , FrameClass::Ignored , FrameClass::Invalid
}
 What Poll() did with the frame it received. More...
 
enum class  PdoKind : uint8_t { PdoKind::Receive = 0 , PdoKind::Transmit = 1 }
 Whether a PDO is a receive PDO (client to node) or a transmit PDO (node to client). More...
 
enum class  DriveState : uint8_t {
  NotReadyToSwitchOn = 0 , SwitchOnDisabled , ReadyToSwitchOn , SwitchedOn ,
  OperationEnabled , QuickStopActive , FaultReactionActive , Fault ,
  DriveState::Unknown
}
 The drive state machine states, decoded from the statusword. More...
 
enum class  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 Config KconfigDefaults () noexcept
 The configuration menuconfig selected, on top of the defaults.
 
constexpr bool IsNodeId (uint8_t node) noexcept
 Whether a node identifier is in 1 to 127.
 
constexpr uint16_t SdoRequestId (uint8_t node) noexcept
 The identifier of the SDO request frames to node.
 
constexpr uint16_t SdoResponseId (uint8_t node) noexcept
 The identifier of the SDO reply frames from node.
 
constexpr uint16_t HeartbeatId (uint8_t node) noexcept
 The identifier of the heartbeat and node-guarding frames of node.
 
constexpr uint16_t EmcyId (uint8_t node) noexcept
 The identifier of the emergency frames of node.
 
constexpr bool IsNmtCommand (uint8_t command) noexcept
 Whether a command byte is one of the five NMT commands.
 
constexpr bool DecodeNmtState (uint8_t raw, NmtState &state) noexcept
 Decode the state byte of a heartbeat (bit 7 already cleared).
 
constexpr Result< CanFrame > MakeNmtFrame (NmtCommand command, uint8_t node) noexcept
 The NMT command frame: identifier 0x000, two data bytes.
 
constexpr Result< CanFrame > MakeSyncFrame (uint8_t counter) noexcept
 The SYNC frame: identifier 0x080, no data, or one counter byte.
 
constexpr Result< CanFrame > MakeGuardRequest (uint8_t node) noexcept
 The node-guarding request: a remote frame on 0x700 + node.
 
constexpr Result< CanFrame > MakePdoFrame (uint16_t cob_id, std::span< const uint8_t > data) noexcept
 A PDO frame: a valid identifier and 0 to 8 data bytes.
 
constexpr Result< CanFrame > MakeSdoUploadRequest (uint8_t node, uint16_t index, uint8_t sub) noexcept
 The initiate-upload request (read an object): command byte 0x40.
 
constexpr Result< CanFrame > MakeSdoExpeditedDownload (uint8_t node, uint16_t index, uint8_t sub, std::span< const uint8_t > data) noexcept
 The expedited initiate-download request (write 1 to 4 bytes): command byte 0x23 | (4 - size) << 2.
 
constexpr Result< CanFrame > MakeSdoSegmentedDownload (uint8_t node, uint16_t index, uint8_t sub, uint32_t size) noexcept
 The segmented initiate-download request announcing size bytes: command byte 0x21.
 
constexpr Result< CanFrame > MakeSdoDownloadSegment (uint8_t node, bool toggle, std::span< const uint8_t > data, bool last) noexcept
 One download segment: command byte toggle << 4 | (7 - length) << 1 | last.
 
constexpr Result< CanFrame > MakeSdoUploadSegmentRequest (uint8_t node, bool toggle) noexcept
 The request for the next upload segment: command byte 0x60 | toggle << 4.
 
constexpr Result< CanFrame > MakeSdoAbort (uint8_t node, uint16_t index, uint8_t sub, uint32_t code) noexcept
 The abort frame the client sends to end a transfer: command byte 0x80.
 
constexpr Result< SdoReply > ParseSdoReply (const CanFrame &frame, bool strict) noexcept
 Decode a frame from an SDO server (identifier 0x580 + node).
 
constexpr Result< HeartbeatInfo > ParseHeartbeat (const CanFrame &frame) noexcept
 Decode a heartbeat, boot-up or node-guarding reply: identifier 0x701 to 0x77F, one byte.
 
constexpr Result< EmcyEvent > ParseEmcy (const CanFrame &frame) noexcept
 Decode an emergency message: identifier 0x081 to 0x0FF, eight bytes (error code, error register, five manufacturer bytes). The timestamp is left 0 for the caller.
 
constexpr Result< uint16_t > PdoCommunicationIndex (PdoKind kind, uint16_t number) noexcept
 The index of the communication parameter record of a PDO.
 
constexpr Result< uint16_t > PdoMappingIndex (PdoKind kind, uint16_t number) noexcept
 The index of the mapping parameter record of a PDO.
 
constexpr uint32_t EncodePdoMapEntry (const PdoMapEntry &entry) noexcept
 The 32-bit mapping record: index << 16 | sub-index << 8 | length in bits.
 
constexpr PdoMapEntry DecodePdoMapEntry (uint32_t record) noexcept
 Split a 32-bit mapping record into its object and length.
 
constexpr Error ValidatePdoConfig (const PdoConfig &config) noexcept
 Check a PDO configuration: identifier range, a transmission type that is not reserved (241 to 251), 0 to kMaxPdoEntries entries, each of 1 to 64 bits at a non-zero index, and at most 64 bits in all.
 
constexpr uint32_t PdoBitLength (const PdoConfig &config) noexcept
 The bits the entries of a PDO occupy in all.
 
constexpr Result< uint64_t > ExtractBits (std::span< const uint8_t > data, uint32_t offset, uint32_t bits) noexcept
 Read bits bits starting at bit offset of a PDO payload (Intel bit order: bit 0 is the least significant bit of byte 0).
 
constexpr Result< void > InsertBits (std::span< uint8_t > data, uint32_t offset, uint32_t bits, uint64_t value) noexcept
 Write the low bits bits of value at bit offset of a PDO payload; the other bits are unchanged.
 
constexpr DriveState DecodeStatusword (uint16_t statusword) noexcept
 Decode the drive state from a statusword (object 0x6041): the masks 0x4F and 0x6F of the state machine, matched exactly.
 
constexpr bool EnableStepControlword (DriveState state, uint16_t &word) noexcept
 The controlword that moves a drive one step toward Operation enabled.
 
constexpr const char * ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr bool IsValid (const CanFrame &frame) noexcept
 Whether a frame is representable on the bus: identifier at most 0x7FF, length at most 8.
 
constexpr const char * AbortCodeName (uint32_t code) noexcept
 The name of an abort code, for logs.
 
constexpr const char * ToString (DriveState state) noexcept
 The name of a drive state, for logs.
 
constexpr Error Validate (const Config &config) noexcept
 Check a configuration without touching the bus.
 
constexpr Config FastBusPreset () noexcept
 Short timeouts for a fast, lightly loaded bus.
 
constexpr Config SlowBusPreset () noexcept
 Long timeouts for a slow or busy bus (for example 125 kbit/s with many nodes).
 
constexpr const char * GetDriverVersion () noexcept
 
constexpr uint32_t GetDriverVersionMajor () noexcept
 
constexpr uint32_t GetDriverVersionMinor () noexcept
 
constexpr uint32_t GetDriverVersionPatch () noexcept
 

Variables

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

Detailed Description

The CANopen client driver: everything it declares lives here; internals in detail.

Function Documentation

◆ KconfigDefaults()

constexpr Config canopen_client::KconfigDefaults ( )
constexprnoexcept

The configuration menuconfig selected, on top of the defaults.

A Kconfig bool is defined when it is y and absent when it is n, so the booleans follow Kconfig only when this component's Kconfig is active (CONFIG_CANOPEN_CLIENT is defined); otherwise they keep the Config{} defaults.

Returns
Config{} with the timeouts and options from Kconfig.