13#ifndef CANOPEN_CLIENT_HPP
14#define CANOPEN_CLIENT_HPP
26#include "canopen_client_version.h"
37template <
typename Port>
38concept DeclaresLog =
requires(Port& port) { port.Log(
LogLevel::Info,
""); };
41template <
typename Port>
43 requires { ExactHook<Port, void(
LogLevel,
const char*)
noexcept>::Take(&Port::Log); };
46template <
typename Port>
47concept DeclaresReceive =
requires(Port& port,
CanFrame& frame) { port.Receive(frame, 0_u32); };
50template <
typename Port>
51concept DeclaresNowUs =
requires(Port& port) { port.NowUs(); };
54template <
typename Port>
55void Log(Port& port, [[maybe_unused]]
LogLevel level,
56 [[maybe_unused]]
const char* message)
noexcept {
57 if constexpr (HasLog<Port>) {
58 port.Log(level, message);
60 static_cast<void>(port);
69 uint32_t timeout_us{0};
81enum class PendingKind : uint8_t {
90 PendingKind kind{PendingKind::None};
98 uint32_t abort_code{0};
131template <CanPort Port>
133 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
134 "canopen_client: the optional Log hook must be `void Log(LogLevel, const char* "
135 "message) noexcept`");
136 static_assert(detail::DeclaresReceive<Port> == detail::DeclaresNowUs<Port>,
137 "canopen_client: a port implements both `Receive` and `NowUs`, or neither");
139 "canopen_client: the hooks must be `RxStatus Receive(CanFrame&, uint32_t "
140 "timeout_us) noexcept` and `uint32_t NowUs() noexcept`");
148 explicit Client(Port& port,
const Config& config = {})
noexcept : port_(port), config_(config) {}
235 std::span<const uint8_t> data) noexcept;
288 std::span<const uint8_t> data) noexcept
421 std::span<uint8_t> out) noexcept
433 std::span<const uint8_t> data) noexcept
711 void resetState() noexcept;
712 void noteNmt(
NmtCommand command, uint8_t node) noexcept;
722 void onSdoReply(const
CanFrame& frame) noexcept
724 void onGuardReply(const
CanFrame& frame) noexcept
726 void finish(
Error error, uint32_t abort_code) noexcept;
727 void clearPending() noexcept;
728 Result<
void> awaitPending(uint32_t timeout_us) noexcept
730 Result<
void> drainRx() noexcept
732 Result<
void> idleFor(uint32_t us) noexcept
734 [[nodiscard]] detail::MonitorSlot* findSlot(uint8_t node) noexcept;
736 Result<
void> sdoBegin(uint8_t node, uint16_t index, uint8_t sub,
bool gated) noexcept
740 void abortLocal(uint32_t code) noexcept;
741 Result<std::
size_t> uploadSegments(std::span<uint8_t> out) noexcept
743 Result<
bool> uploadSegment(std::span<uint8_t> out, std::
size_t& got,
bool toggle) noexcept
745 Result<
void> downloadSegments(std::span<const uint8_t> data) noexcept
747 Result<uint32_t> readUnsigned(uint8_t node, uint16_t index, uint8_t sub,
748 std::
size_t size) noexcept
750 Result<
void> writeUnsigned(uint8_t node, uint16_t index, uint8_t sub, uint32_t value,
751 std::
size_t size,
bool gated) noexcept
753 Result<
void> storeOrRestore(uint8_t node, uint16_t index, uint8_t group,
754 uint32_t signature) noexcept
757 Result<
void> writePdoMapping(uint8_t node, uint16_t map_index, const
PdoConfig& config) noexcept
759 Result<
void> writePdoCommunication(uint8_t node,
PdoKind kind, uint16_t comm_index,
763 uint16_t word) noexcept
765 Result<
void> waitFaultCleared(uint8_t node, const
DriveObjects& objects, uint32_t start) noexcept
767 [[nodiscard]]
bool driveTimedOut(uint32_t start_us) noexcept
769 [[nodiscard]] uint32_t driveStepLimit() const noexcept;
775 bool initialized_{
false};
779 CanFrame last_raw_{};
781 detail::Pending pending_{};
782 SdoAbortInfo last_abort_{};
784 std::array<detail::MonitorSlot, kMonitorCapacity> monitors_{};
785 std::array<detail::PdoSlot, kPdoSubscriptionCapacity> pdos_{};
786 std::array<EmcyEvent, kEmcyQueueCapacity> emcy_{};
787 std::size_t emcy_head_{0};
788 std::size_t emcy_count_{0};
789 uint32_t sync_period_us_{0};
790 uint8_t sync_overflow_{0};
791 uint8_t sync_counter_{0};
792 bool sync_started_{
false};
793 uint32_t sync_last_us_{0};
801#include "../src/canopen_client.ipp"
The CAN port of the CANopen client driver: the CRTP base and the CanPort and CanRxPort concepts.
Compile-time helpers of the CANOPEN_CLIENT driver: typed integer literals, exact hook matching,...
The CANopen frame codecs: pure functions that build and decode NMT, SYNC, SDO, heartbeat,...
Public types of the CANopen client driver: errors, Result<T>, the CAN frame, the protocol vocabulary ...
A CANopen client on one CAN bus.
Definition canopen_client.hpp:132
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
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,...
Result< NmtState > GuardNode(uint8_t node) noexcept
One node-guarding exchange: a remote frame on 0x700 + node, then the reply, whose toggle bit must alt...
Result< uint32_t > ReadDeviceType(uint8_t node) noexcept
Read the device type (object 0x1000).
Result< void > SetDriveMode(uint8_t node, OperationMode mode, const DriveObjects &objects={}, Verify verify=Verify::None) noexcept
Select the mode of operation.
Result< void > SetConfig(const Config &config) noexcept
Replace the configuration.
const CanFrame & GetLastRawFrame() const &noexcept
Definition canopen_client.hpp:293
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 ...
Result< void > DriveEnable(uint8_t node, const DriveObjects &objects={}) noexcept
Walk the drive to Operation enabled: shutdown, switch on, enable operation, reading the statusword af...
Result< void > SubscribeTpdo(uint16_t cob_id, uint8_t dlc) noexcept
Hold the latest frame of a TPDO identifier for ReadTpdo().
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< DriveState > ReadDriveState(uint8_t node, const DriveObjects &objects={}) noexcept
Read the statusword and decode the drive state.
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).
void GetLastAbort() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
Result< void > UnmonitorNode(uint8_t node) noexcept
Stop watching a node.
bool PopEmcy(EmcyEvent &event) noexcept
Take the oldest queued emergency message.
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 di...
Result< OperationMode > ReadDriveMode(uint8_t node, const DriveObjects &objects={}) noexcept
Read the mode of operation display.
Result< void > SendRawFrame(const CanFrame &frame) noexcept
Diagnostic: send one frame exactly as given. A single Send(): no retry, no routing,...
Client(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Definition canopen_client.hpp:148
Result< void > UnsubscribeTpdo(uint16_t cob_id) noexcept
Stop holding a TPDO identifier.
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< 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 no...
const Config & GetConfig() const &noexcept
Definition canopen_client.hpp:187
Result< PdoSample > ReadTpdo(uint16_t cob_id) const noexcept
The latest frame received on a subscribed identifier.
Result< void > Deinitialize() noexcept
Mark the driver uninitialised and forget what it received. No bus traffic: nodes are left in the stat...
Result< bool > ServiceSync() noexcept
Send a SYNC when the period has elapsed since the last one (the first call after ConfigureSync() send...
Result< uint16_t > SdoReadU16(uint8_t node, uint16_t index, uint8_t sub) noexcept
Read an unsigned 16-bit object.
const SdoAbortInfo & GetLastAbort() const &noexcept
The last SDO abort, sent by a node or by this driver. No I/O.
Definition canopen_client.hpp:501
Result< void > ConfigureSync(uint32_t period_us, uint8_t counter_overflow) noexcept
Set the SYNC period ServiceSync() keeps.
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...
Result< uint32_t > SdoReadU32(uint8_t node, uint16_t index, uint8_t sub) noexcept
Read an unsigned 32-bit object.
const Stats & GetStats() const &noexcept
Definition canopen_client.hpp:370
Result< uint8_t > SdoReadU8(uint8_t node, uint16_t index, uint8_t sub) noexcept
Read an unsigned 8-bit object.
Client(const Client &)=delete
One driver object per bus.
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 tra...
Result< uint16_t > ReadStatusword(uint8_t node, const DriveObjects &objects={}) noexcept
Read the statusword.
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 answ...
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 ...
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,...
Result< uint8_t > ReadErrorRegister(uint8_t node) noexcept
Read the error register (object 0x1001).
void GetStats() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
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.
bool IsInitialized() const noexcept
Definition canopen_client.hpp:168
void GetLastRawFrame() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
Result< void > StoreParameters(uint8_t node, uint8_t group) noexcept
Store parameters to non-volatile memory (object 0x1010, signature "save").
Client & operator=(const Client &)=delete
One driver object per bus.
Result< void > WriteHeartbeatProducerTime(uint8_t node, uint16_t period_ms) noexcept
Set the node's heartbeat producer time (object 0x1017).
Result< void > SendSync(uint8_t counter=0) noexcept
Send one SYNC frame, with a counter byte when counter is not 0.
Result< void > EnsureInitialized() noexcept
Start the client, once: the only way to initialise the driver.
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 0x5...
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 ser...
Result< PdoConfig > ReadPdoConfig(uint8_t node, PdoKind kind, uint16_t number) noexcept
Read a PDO's identifier, validity, transmission type and mapping back.
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 > 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 > 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 > 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 t...
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,...
Result< void > DriveQuickStop(uint8_t node, const DriveObjects &objects={}) noexcept
Quick stop (controlword 0x0002). Never refused, retried like DriveDisable().
Satisfied by a CanPort that also receives frames and keeps time: the full client port.
Definition canopen_client_can_interface.hpp:83
OperationMode
Modes of operation (object 0x6060), as the profile numbers them.
Definition canopen_client_types.hpp:542
NmtCommand
NMT master command (the first data byte of the frame on identifier 0x000).
Definition canopen_client_types.hpp:263
FrameClass
What Poll() did with the frame it received.
Definition canopen_client_types.hpp:451
NmtState
NMT state a node reports in its heartbeat or guarding reply (bit 7 masked off).
Definition canopen_client_types.hpp:272
Verify
Whether a setter or a transfer reads back what it wrote (extra bus traffic).
Definition canopen_client_types.hpp:172
SdoReplyKind
The kind of an SDO server reply.
Definition canopen_client_types.hpp:390
LogLevel
Severity passed to the optional Log() hook.
Definition canopen_client_types.hpp:164
PdoKind
Whether a PDO is a receive PDO (client to node) or a transmit PDO (node to client).
Definition canopen_client_types.hpp:471
Error
Why a call failed. Values 0 to 9 are the shared base set; client-specific values start at 16.
Definition canopen_client_types.hpp:36
@ BootUp
The boot-up message; the node continues to Pre-operational.
@ None
No read-back: the node's acknowledgement is the only check.
@ InitiateUpload
Response to an initiate upload request (scs 2).
The CANopen client driver: everything it declares lives here; internals in detail.
Definition canopen_client.hpp:28
One classic CAN frame with an 11-bit identifier.
Definition canopen_client_types.hpp:190
Everything the client uses; the defaults suit a node on a 500 kbit/s bus.
Definition canopen_client_types.hpp:580
The object indices of a drive; the defaults are the profile's, a remapped drive overrides them.
Definition canopen_client_types.hpp:557
One emergency message (EMCY).
Definition canopen_client_types.hpp:433
What the heartbeat consumer knows about one node.
Definition canopen_client_types.hpp:423
The communication and mapping parameters of one PDO.
Definition canopen_client_types.hpp:484
The latest frame received on a subscribed TPDO identifier.
Definition canopen_client_types.hpp:442
The value of a call, or why there is none.
Definition canopen_client_types.hpp:106
The last SDO abort, from the node or from this driver.
Definition canopen_client_types.hpp:381
A decoded SDO server reply.
Definition canopen_client_types.hpp:399
Counters of the receive path, for diagnostics.
Definition canopen_client_types.hpp:462