Skip to content

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

my_port.hpp
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.