BaseCan.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <atomic>
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC CAN Error Codes (Table)
//--------------------------------------
#define HF_CAN_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(CAN_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(CAN_ERR_FAILURE, 1, "General failure")                                                         \
  X(CAN_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(CAN_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(CAN_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(CAN_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(CAN_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Bus errors */                                                                                 \
  X(CAN_ERR_BUS_OFF, 7, "Bus off state")                                                           \
  X(CAN_ERR_BUS_ERROR, 8, "Bus error")                                                             \
  X(CAN_ERR_BUS_BUSY, 9, "Bus busy")                                                               \
  X(CAN_ERR_BUS_NOT_AVAILABLE, 10, "Bus not available")                                            \
  X(CAN_ERR_BUS_RECOVERY_FAILED, 11, "Bus recovery failed")                                        \
  X(CAN_ERR_BUS_ARBITRATION_LOST, 12, "Bus arbitration lost")                                      \
  /* Message errors */                                                                             \
  X(CAN_ERR_MESSAGE_TIMEOUT, 13, "Message timeout")                                                \
  X(CAN_ERR_MESSAGE_LOST, 14, "Message lost")                                                      \
  X(CAN_ERR_MESSAGE_INVALID, 15, "Invalid message")                                                \
  X(CAN_ERR_MESSAGE_TOO_LONG, 16, "Message too long")                                              \
  X(CAN_ERR_MESSAGE_INVALID_ID, 17, "Invalid message ID")                                          \
  X(CAN_ERR_MESSAGE_INVALID_DLC, 18, "Invalid data length code")                                   \
  X(CAN_ERR_QUEUE_FULL, 19, "Queue full")                                                          \
  X(CAN_ERR_QUEUE_EMPTY, 20, "Queue empty")                                                        \
  /* Transmission errors */                                                                        \
  X(CAN_ERR_TX_FAILED, 21, "Transmission failed")                                                  \
  X(CAN_ERR_TX_ABORTED, 22, "Transmission aborted")                                                \
  X(CAN_ERR_TX_ERROR_PASSIVE, 23, "Transmit error passive")                                        \
  X(CAN_ERR_TX_ERROR_WARNING, 24, "Transmit error warning")                                        \
  /* Reception errors */                                                                           \
  X(CAN_ERR_RX_OVERRUN, 25, "Receive overrun")                                                     \
  X(CAN_ERR_RX_ERROR_PASSIVE, 26, "Receive error passive")                                         \
  X(CAN_ERR_RX_ERROR_WARNING, 27, "Receive error warning")                                         \
  X(CAN_ERR_RX_FIFO_FULL, 28, "Receive FIFO full")                                                 \
  /* Hardware errors */                                                                            \
  X(CAN_ERR_HARDWARE_FAULT, 29, "Hardware fault")                                                  \
  X(CAN_ERR_COMMUNICATION_FAILURE, 30, "Communication failure")                                    \
  X(CAN_ERR_DEVICE_NOT_RESPONDING, 31, "Device not responding")                                    \
  X(CAN_ERR_VOLTAGE_OUT_OF_RANGE, 32, "Voltage out of range")                                      \
  X(CAN_ERR_CLOCK_ERROR, 33, "Clock error")                                                        \
  X(CAN_ERR_TRANSCEIVER_ERROR, 34, "Transceiver error")                                            \
  /* Configuration errors */                                                                       \
  X(CAN_ERR_INVALID_CONFIGURATION, 35, "Invalid configuration")                                    \
  X(CAN_ERR_UNSUPPORTED_OPERATION, 36, "Unsupported operation")                                    \
  X(CAN_ERR_INVALID_BAUD_RATE, 37, "Invalid baud rate")                                            \
  X(CAN_ERR_INVALID_CONTROLLER_ID, 38, "Invalid controller ID")                                    \
  X(CAN_ERR_FILTER_ERROR, 39, "Filter error")                                                      \
  X(CAN_ERR_FILTER_FULL, 40, "Filter table full")                                                  \
  /* Protocol errors */                                                                            \
  X(CAN_ERR_STUFF_ERROR, 41, "Bit stuffing error")                                                 \
  X(CAN_ERR_FORM_ERROR, 42, "Frame format error")                                                  \
  X(CAN_ERR_CRC_ERROR, 43, "CRC error")                                                            \
  X(CAN_ERR_ACK_ERROR, 44, "Acknowledgment error")                                                 \
  X(CAN_ERR_BIT_ERROR, 45, "Bit error")                                                            \
  /* System errors */                                                                              \
  X(CAN_ERR_SYSTEM_ERROR, 46, "System error")                                                      \
  X(CAN_ERR_PERMISSION_DENIED, 47, "Permission denied")                                            \
  X(CAN_ERR_OPERATION_ABORTED, 48, "Operation aborted")                                            \
                                                                                                   \
  /* Extended CAN errors (for ESP32 compatibility) */                                              \
  X(CAN_ERR_FAIL, 49, "Generic failure")                                                           \
  X(CAN_ERR_RESOURCE_BUSY, 50, "Resource busy")                                                    \
  X(CAN_ERR_INVALID_STATE, 51, "Invalid state")                                                    \
  X(CAN_ERR_NOT_SUPPORTED, 52, "Not supported")                                                    \
  X(CAN_ERR_TIMEOUT_ALT, 53, "Operation timeout")                                                  \
  X(CAN_ERR_UNKNOWN, 54, "Unknown error")
 
enum class hf_can_err_t : hf_u8_t {
#define X(NAME, VALUE, DESC) NAME = VALUE,
  HF_CAN_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfCanErrToString(hf_can_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_can_err_t::NAME:                                                                         \
    return DESC;
    HF_CAN_ERR_LIST(X)
#undef X
  default:
    return HfCanErrToString(hf_can_err_t::CAN_ERR_UNKNOWN);
  }
}
 
struct hf_can_config_t {
  hf_pin_num_t tx_pin;     
  hf_pin_num_t rx_pin;     
  hf_baud_rate_t baudrate; 
  bool loopback_mode;      
  bool silent_mode;        
  hf_u16_t tx_queue_size;  
  hf_u16_t rx_queue_size;  
 
  hf_can_config_t() noexcept
      : tx_pin(HF_INVALID_PIN), rx_pin(HF_INVALID_PIN), baudrate(500000), loopback_mode(false),
        silent_mode(false), tx_queue_size(10), rx_queue_size(10) {}
};
 
struct hf_can_message_t {
  // === Core CAN Message Fields ===
  hf_u32_t id;     
  hf_u8_t dlc;     
  hf_u8_t data[8]; 
 
  // === Standard CAN Flags ===
  bool is_extended;  
  bool is_rtr;       
  bool is_ss;        
  bool is_self;      
  bool dlc_non_comp; 
 
  // === Metadata and Diagnostics ===
  hf_u64_t timestamp_us;    
  hf_u32_t sequence_number; 
  hf_u8_t controller_id;    
  hf_u8_t retry_count;      
  hf_u8_t error_count;      
 
  // === CAN-FD Extended Fields (for future compatibility) ===
  bool is_canfd;     
  bool is_brs;       
  bool is_esi;       
  hf_u8_t canfd_dlc; 
 
  hf_can_message_t() noexcept
      : id(0), dlc(8), data{}, is_extended(false), is_rtr(false), is_ss(false), is_self(false),
        dlc_non_comp(false), timestamp_us(0), sequence_number(0), controller_id(0), retry_count(0),
        error_count(0), is_canfd(false), is_brs(false), is_esi(false), canfd_dlc(0) {}
 
  constexpr hf_u8_t GetMaxDataLength() const noexcept {
    return is_canfd ? 64 : 8;
  }
 
  bool IsValidDLC(hf_u8_t dlc) const noexcept {
    return is_canfd ? (dlc <= 64) : (dlc <= 8);
  }
 
  hf_u8_t GetEffectiveDLC() const noexcept {
    return is_canfd ? canfd_dlc : dlc;
  }
 
  bool SetDLC(hf_u8_t dlc) noexcept {
    if (!IsValidDLC(dlc)) {
      return false;
    }
    if (is_canfd) {
      canfd_dlc = dlc;
    } else {
      this->dlc = dlc;
    }
    return true;
  }
 
  void SetStandardFrame() noexcept {
    is_extended = false;
  }
 
  void SetExtendedFrame() noexcept {
    is_extended = true;
  }
 
  void SetDataFrame() noexcept {
    is_rtr = false;
  }
 
  void SetRemoteFrame() noexcept {
    is_rtr = true;
  }
 
  void SetSingleShot() noexcept {
    is_ss = true;
  }
 
  void SetSelfReception() noexcept {
    is_self = true;
  }
 
  bool IsValidId() const noexcept {
    if (is_extended) {
      return id <= 0x1FFFFFFF; // 29-bit max
    } else {
      return id <= 0x7FF; // 11-bit max
    }
  }
};
 
struct hf_can_status_t {
  hf_u32_t tx_error_count;  
  hf_u32_t rx_error_count;  
  hf_u32_t tx_failed_count; 
  hf_u32_t rx_missed_count; 
  bool bus_off;             
  bool error_warning;       
  bool error_passive;       
 
  // CAN-FD specific status
  bool canfd_enabled;        
  bool canfd_brs_enabled;    
  hf_u32_t nominal_baudrate; 
  hf_u32_t data_baudrate;    
  hf_u32_t canfd_tx_count;   
  hf_u32_t canfd_rx_count;   
  hf_u32_t brs_tx_count;     
  hf_u32_t brs_rx_count;     
  hf_u32_t form_errors;      
  hf_u32_t stuff_errors;     
  hf_u32_t crc_errors;       
  hf_u32_t bit_errors;       
  hf_u32_t ack_errors;       
 
  hf_can_status_t() noexcept
      : tx_error_count(0), rx_error_count(0), tx_failed_count(0), rx_missed_count(0),
        bus_off(false), error_warning(false), error_passive(false), canfd_enabled(false),
        canfd_brs_enabled(false), nominal_baudrate(0), data_baudrate(0), canfd_tx_count(0),
        canfd_rx_count(0), brs_tx_count(0), brs_rx_count(0), form_errors(0), stuff_errors(0),
        crc_errors(0), bit_errors(0), ack_errors(0) {}
};
 
using hf_can_receive_callback_t = void (*)(const hf_can_message_t& message);
 
struct hf_can_reception_info_t {
  hf_u32_t timestamp_us;      
  hf_u8_t rx_fifo_level;      
  bool data_phase_error;      
  bool arbitration_lost;      
  float bit_timing_tolerance; 
};
using hf_can_fd_receive_callback_t =
    void (*)(const hf_can_message_t& message, const hf_can_reception_info_t& info);
 
struct hf_can_statistics_t {
  // Message counters (atomic for ISR safety)
  std::atomic<hf_u64_t> messages_sent{0};     
  std::atomic<hf_u64_t> messages_received{0}; 
  std::atomic<hf_u64_t> bytes_transmitted{0}; 
  std::atomic<hf_u64_t> bytes_received{0};    
 
  // Error counters (atomic for ISR safety)
  std::atomic<hf_u32_t> send_failures{0};          
  std::atomic<hf_u32_t> receive_failures{0};       
  std::atomic<hf_u32_t> bus_error_count{0};        
  std::atomic<hf_u32_t> arbitration_lost_count{0}; 
  std::atomic<hf_u32_t> tx_failed_count{0};        
  std::atomic<hf_u32_t> bus_off_events{0};         
  std::atomic<hf_u32_t> error_warning_events{0};   
 
  // Performance metrics (atomic for ISR safety)
  std::atomic<hf_u64_t> uptime_seconds{0};                         
  std::atomic<hf_u32_t> last_activity_timestamp{0};                
  std::atomic<hf_can_err_t> last_error{hf_can_err_t::CAN_SUCCESS}; 
 
  // Queue statistics (atomic for ISR safety)
  std::atomic<hf_u32_t> tx_queue_peak{0};      
  std::atomic<hf_u32_t> rx_queue_peak{0};      
  std::atomic<hf_u32_t> tx_queue_overflows{0}; 
  std::atomic<hf_u32_t> rx_queue_overflows{0}; 
 
  // Default constructor - all fields are initialized with in-class initialization
  hf_can_statistics_t() noexcept = default;
};
 
struct hf_can_diagnostics_t {
  hf_u32_t tx_error_count;       
  hf_u32_t rx_error_count;       
  hf_u32_t tx_queue_peak;        
  hf_u32_t rx_queue_peak;        
  hf_u32_t last_error_timestamp; 
  hf_u32_t controller_resets;    
  hf_u32_t bus_load_percentage;  
  float bit_error_rate;          
 
  hf_can_diagnostics_t() noexcept
      : tx_error_count(0), rx_error_count(0), tx_queue_peak(0), rx_queue_peak(0),
        last_error_timestamp(0), controller_resets(0), bus_load_percentage(0),
        bit_error_rate(0.0f) {}
};
 
class BaseCan {
public:
  virtual ~BaseCan() noexcept = default;
 
  // Non-copyable, non-movable (can be changed in derived classes if needed)
  BaseCan(const BaseCan&) = delete;
  BaseCan& operator=(const BaseCan&) = delete;
  BaseCan(BaseCan&&) = delete;
  BaseCan& operator=(BaseCan&&) = delete;
 
  bool EnsureInitialized() noexcept {
    if (!initialized_) {
      initialized_ = (Initialize() == hf_can_err_t::CAN_SUCCESS);
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() noexcept {
    if (initialized_) {
      initialized_ = !(Deinitialize() == hf_can_err_t::CAN_SUCCESS);
    }
    return !initialized_;
  }
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS [MUST BE OVERRIDDEN]  //
  //==============================================//
 
  virtual hf_can_err_t Initialize() noexcept = 0;
 
  virtual hf_can_err_t Deinitialize() noexcept = 0;
 
  virtual hf_can_err_t SendMessage(const hf_can_message_t& message,
                                   hf_u32_t timeout_ms = 1000) noexcept = 0;
 
  virtual hf_can_err_t ReceiveMessage(hf_can_message_t& message,
                                      hf_u32_t timeout_ms = 0) noexcept = 0;
 
  virtual hf_can_err_t SetReceiveCallback(hf_can_receive_callback_t callback) noexcept = 0;
 
  virtual hf_can_err_t SetAcceptanceFilter(hf_u32_t id, hf_u32_t mask,
                                           bool extended = false) noexcept = 0;
 
  virtual hf_can_err_t GetStatus(hf_can_status_t& status) noexcept = 0;
 
  virtual hf_can_err_t Reset() noexcept = 0;
 
  //==============================================//
  // (OPTIONAL IMPLEMENTATIONS)                   //
  //==============================================//
 
  virtual void ClearReceiveCallback() noexcept {}
 
  virtual hf_can_err_t ClearAcceptanceFilter() noexcept {
    return SetAcceptanceFilter(0, 0, false);
  }
 
  virtual hf_can_err_t SetReceiveCallbackFD(hf_can_fd_receive_callback_t callback) noexcept {
    (void)callback; // Suppress unused parameter warning
    return hf_can_err_t::CAN_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual bool SupportsCanFD() const noexcept {
    return false;
  }
 
  virtual bool SetCanFDMode(bool enable, hf_u32_t data_baudrate = 2000000,
                            hf_u32_t timeout_ms = 1000) noexcept {
    (void)enable;
    (void)data_baudrate;
    (void)timeout_ms;
    return false;
  }
 
  virtual bool ConfigureCanFDTiming(hf_u16_t nominal_prescaler, hf_u8_t nominal_tseg1,
                                    hf_u8_t nominal_tseg2, hf_u16_t data_prescaler,
                                    hf_u8_t data_tseg1, hf_u8_t data_tseg2,
                                    hf_u8_t sjw = 1) noexcept {
    (void)nominal_prescaler;
    (void)nominal_tseg1;
    (void)nominal_tseg2;
    (void)data_prescaler;
    (void)data_tseg1;
    (void)data_tseg2;
    (void)sjw;
    return false;
  }
 
  virtual bool SetTransmitterDelayCompensation(hf_u8_t tdc_offset, hf_u8_t tdc_filter) noexcept {
    (void)tdc_offset;
    (void)tdc_filter;
    return false;
  }
 
  virtual hf_u32_t SendMessageBatch(const hf_can_message_t* messages, hf_u32_t count,
                                    hf_u32_t timeout_ms = 1000) noexcept {
    if (!messages || count == 0) {
      return 0;
    }
 
    hf_u32_t sent_count = 0;
    for (hf_u32_t i = 0; i < count; ++i) {
      if (SendMessage(messages[i], timeout_ms) == hf_can_err_t::CAN_SUCCESS) {
        sent_count++;
      }
    }
    return sent_count;
  }
 
  virtual hf_u32_t ReceiveMessageBatch(hf_can_message_t* messages, hf_u32_t max_count,
                                       hf_u32_t timeout_ms = 100) noexcept {
    if (!messages || max_count == 0) {
      return 0;
    }
 
    hf_u32_t received_count = 0;
    for (hf_u32_t i = 0; i < max_count; ++i) {
      if (ReceiveMessage(messages[i], timeout_ms) == hf_can_err_t::CAN_SUCCESS) {
        received_count++;
      } else {
        break; // No more messages available
      }
    }
    return received_count;
  }
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS STRUCTURES        //
  //==============================================//
 
  virtual hf_can_err_t ResetStatistics() noexcept {
    // Reset all atomic counters to zero (atomic operations are thread-safe)
    statistics_.messages_sent.store(0);
    statistics_.messages_received.store(0);
    statistics_.bytes_transmitted.store(0);
    statistics_.bytes_received.store(0);
    statistics_.send_failures.store(0);
    statistics_.receive_failures.store(0);
    statistics_.bus_error_count.store(0);
    statistics_.arbitration_lost_count.store(0);
    statistics_.tx_failed_count.store(0);
    statistics_.bus_off_events.store(0);
    statistics_.error_warning_events.store(0);
    statistics_.uptime_seconds.store(0);
    statistics_.last_activity_timestamp.store(0);
    statistics_.last_error.store(hf_can_err_t::CAN_SUCCESS);
    statistics_.tx_queue_peak.store(0);
    statistics_.rx_queue_peak.store(0);
    statistics_.tx_queue_overflows.store(0);
    statistics_.rx_queue_overflows.store(0);
    return hf_can_err_t::CAN_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_can_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_can_diagnostics_t{}; // Reset diagnostics to default values
    return hf_can_err_t::CAN_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_can_err_t GetStatistics(hf_can_statistics_t& statistics) noexcept {
    // Copy atomic values to non-atomic structure for return (atomic operations are thread-safe)
    statistics.messages_sent = statistics_.messages_sent.load();
    statistics.messages_received = statistics_.messages_received.load();
    statistics.bytes_transmitted = statistics_.bytes_transmitted.load();
    statistics.bytes_received = statistics_.bytes_received.load();
    statistics.send_failures = statistics_.send_failures.load();
    statistics.receive_failures = statistics_.receive_failures.load();
    statistics.bus_error_count = statistics_.bus_error_count.load();
    statistics.arbitration_lost_count = statistics_.arbitration_lost_count.load();
    statistics.tx_failed_count = statistics_.tx_failed_count.load();
    statistics.bus_off_events = statistics_.bus_off_events.load();
    statistics.error_warning_events = statistics_.error_warning_events.load();
    statistics.uptime_seconds = statistics_.uptime_seconds.load();
    statistics.last_activity_timestamp = statistics_.last_activity_timestamp.load();
    statistics.last_error = statistics_.last_error.load();
    statistics.tx_queue_peak = statistics_.tx_queue_peak.load();
    statistics.rx_queue_peak = statistics_.rx_queue_peak.load();
    statistics.tx_queue_overflows = statistics_.tx_queue_overflows.load();
    statistics.rx_queue_overflows = statistics_.rx_queue_overflows.load();
    return hf_can_err_t::CAN_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_can_err_t GetDiagnostics(hf_can_diagnostics_t& diagnostics) noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_can_err_t::CAN_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  BaseCan() noexcept : initialized_(false), statistics_{}, diagnostics_{} {}
 
  //==============================================//
  // VARIABLES                                    //
  //==============================================//
 
  bool initialized_;                 
  hf_can_statistics_t statistics_;   
  hf_can_diagnostics_t diagnostics_; 
};
 
//==============================================//
// END OF BASECAN - CLEAN AND MODERN API        //
//==============================================//