Porting¶
Run the driver on a new MCU by writing one class: the port.
Datasheet sections this page relies on
From Texas Instruments SN65HVD230, SN65HVD231, SN65HVD232 (SLOS346) O:
- Supply voltage and mode select (RS): 8.3 Recommended Operating Conditions; 5 Description (continued), p. 6
- CAN node: transceiver and controller wiring: 11.2 Typical Application, p. 26
All of them, with the driver API for each: Datasheet map.
The driver calls hooks on a class you derive from canopen_client::CanInterface<Self> (in
inc/canopen_client_can_interface.hpp). The base declares no hook; the
driver template is constrained by the canopen_client::CanPort concept (and CanRxPort for the calls that need a
reply), so a missing or misdeclared hook is a compile error.
What you implement¶
| Method | Required | Contract |
|---|---|---|
bool EnsureInitialized() noexcept |
yes | Bring the controller up at the bus bit rate on the first call; true at once afterwards |
bool Send(const CanFrame&) noexcept |
yes | Queue one 11-bit frame; false when the controller refused it |
RxStatus Receive(CanFrame&, uint32_t timeout_us) noexcept |
for replies | Wait up to timeout_us for one frame (0 only looks): Frame, Timeout or Error |
uint32_t NowUs() noexcept |
with Receive |
A free-running microsecond clock; every timeout is measured with it |
void Log(LogLevel, const char* message) noexcept |
no | Print one line; message is plain text, never a format string |
Receive and NowUs come as a pair. The port drops extended-identifier, CAN FD and error frames itself: the driver
only ever sees a classic frame. Report a bus-off or stopped controller as RxStatus::Error, and a quiet bus as
Timeout; they are different failures (Bus and Timeout).
The port¶
class MyPort : public canopen_client::CanInterface<MyPort> {
public:
// Bring the CAN controller up at 500 kbit/s, once; later calls return true at once.
bool EnsureInitialized() noexcept {
if (!ready_) {
ready_ = platform_can_start(500'000U);
}
return ready_;
}
// Queue one frame: false when the controller refused it.
bool Send(const canopen_client::CanFrame& frame) noexcept {
return platform_can_send(frame.id, frame.rtr, frame.dlc, frame.data.data());
}
// Wait up to `timeout_us` for one 11-bit frame; 0 only looks.
canopen_client::RxStatus Receive(canopen_client::CanFrame& frame, uint32_t timeout_us) noexcept {
frame = canopen_client::CanFrame{};
const int status =
platform_can_receive(timeout_us, frame.id, frame.rtr, frame.dlc, frame.data.data());
if (status == 0) {
return canopen_client::RxStatus::Frame;
}
return (status == 1) ? canopen_client::RxStatus::Timeout : canopen_client::RxStatus::Error;
}
// A clock that never stops: every timeout in the driver is measured with it.
uint32_t NowUs() noexcept {
return platform_micros();
}
private:
bool ready_ = false;
};
A port with every hook:
class FullPort : public canopen_client::CanInterface<FullPort> {
public:
bool EnsureInitialized() noexcept {
return platform_can_start();
}
bool Send(const canopen_client::CanFrame& frame) noexcept {
return platform_can_send(frame);
}
canopen_client::RxStatus Receive(canopen_client::CanFrame& frame, uint32_t timeout_us) noexcept {
switch (platform_can_receive(frame, timeout_us)) {
case 0:
return canopen_client::RxStatus::Frame;
case 1:
return canopen_client::RxStatus::Timeout; // nothing arrived: not an error
default:
return canopen_client::RxStatus::Error; // bus off, controller stopped
}
}
uint32_t NowUs() noexcept {
return platform_micros();
}
// Optional: one line per failure. The driver never formats; the port does.
void Log(canopen_client::LogLevel level, const char* message) noexcept {
(void)level;
platform_log(message); // plain text: never use it as a format string
}
};
A node that only commands needs two hooks, and the calls that need a reply do not compile:
// A node that only commands (a controller that cannot read the bus): two hooks, and the calls that
// need a reply do not compile.
class TxPort : public canopen_client::CanInterface<TxPort> {
public:
bool EnsureInitialized() noexcept {
return platform_can_start();
}
bool Send(const canopen_client::CanFrame& frame) noexcept {
return platform_can_send(frame);
}
};
The ESP32 example uses esp32_canopen_client_port.hpp (the
TWAI driver at 500 kbit/s).
Bit rate and filters¶
The driver does not set the bit rate: EnsureInitialized() of the port does. Accept all 11-bit identifiers in the
controller's filter (or at least 0x080 to 0x7FF); heartbeats, EMCY and the SDO replies all arrive on different
identifiers, and a filter that drops one makes the matching call time out.
Threads¶
The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex.