EspCan.h

Go to the documentation of this file.

 
#pragma once
 
#include "McuSelect.h"
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
// ESP-IDF v5.5 TWAI node-based API
#include "esp_twai.h"
#include "esp_twai_onchip.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
 
#ifdef __cplusplus
}
#endif
 
#include "BaseCan.h"
#include "HfSpscRing.h"
#include "PlatformMutex.h"
#include "utils/EspTypes_CAN.h"
 
#include <atomic>
#include <memory>
 
//==============================================================================
// ESP32 TWAI NODE CONFIGURATION (ESP-IDF v5.5)
//==============================================================================
 
enum class hf_esp_can_rx_mode_t : uint8_t {
  AUTO = 0,
  QUEUE_ALWAYS = 1,
};
 
struct hf_esp_can_config_t {
  // Core GPIO configuration
  hf_pin_num_t tx_pin; 
  hf_pin_num_t rx_pin; 
 
  // Timing configuration
  uint32_t baud_rate;              
  uint32_t sample_point_permill;   
  uint32_t secondary_sample_point; 
 
  // Queue configuration
  uint32_t tx_queue_depth;      
  uint32_t rx_queue_depth;      
  hf_esp_can_rx_mode_t rx_mode; 
 
  // Node behavior configuration
  hf_can_controller_id_t controller_id; 
  hf_can_mode_t mode;                   
  int8_t fail_retry_cnt;                
  uint8_t intr_priority;                
 
  // Advanced features
  bool enable_self_test;   
  bool enable_loopback;    
  bool enable_listen_only; 
  bool no_receive_rtr;     
  bool enable_alerts;      
 
  // Clock source configuration
  uint32_t clk_flags; 
 
  hf_esp_can_config_t() noexcept
      : tx_pin(4), rx_pin(5), baud_rate(500000), sample_point_permill(750),
        secondary_sample_point(0), tx_queue_depth(10), rx_queue_depth(32),
        rx_mode(hf_esp_can_rx_mode_t::AUTO),
        controller_id(hf_can_controller_id_t::HF_CAN_CONTROLLER_0),
        mode(hf_can_mode_t::HF_CAN_MODE_NORMAL), fail_retry_cnt(-1), intr_priority(1),
        enable_self_test(false), enable_loopback(false), enable_listen_only(false),
        no_receive_rtr(false), enable_alerts(true), clk_flags(0) {}
};
 
struct hf_esp_can_timing_config_t {
  uint32_t brp;        
  uint32_t prop_seg;   
  uint32_t tseg_1;     
  uint32_t tseg_2;     
  uint32_t sjw;        
  uint32_t ssp_offset; 
 
  hf_esp_can_timing_config_t() noexcept
      : brp(8), prop_seg(10), tseg_1(4), tseg_2(5), sjw(3), ssp_offset(0) {}
};
 
struct hf_esp_can_filter_config_t {
  uint32_t id;         
  uint32_t mask;       
  bool is_extended;    
  bool is_dual_filter; 
 
  // Dual filter configuration (when is_dual_filter = true)
  uint32_t id2;   
  uint32_t mask2; 
 
  hf_esp_can_filter_config_t() noexcept
      : id(0), mask(0), is_extended(false), is_dual_filter(false), id2(0), mask2(0) {}
};
 
//==============================================================================
// ENHANCED USER CALLBACK SYSTEM
//==============================================================================
 
struct hf_esp_can_error_info_t {
  uint32_t error_type;     
  uint32_t tx_error_count; 
  uint32_t rx_error_count; 
  bool bus_off_state;      
  bool error_warning;      
  bool error_passive;      
  uint64_t timestamp_us;   
};
 
struct hf_esp_can_state_info_t {
  uint32_t previous_state; 
  uint32_t current_state;  
  uint64_t timestamp_us;   
};
 
struct hf_esp_can_tx_info_t {
  hf_can_message_t message; 
  bool success;             
  uint64_t timestamp_us;    
};
 
using hf_esp_can_receive_callback_t = void (*)(const hf_can_message_t& message, void* user_data);
using hf_esp_can_error_callback_t = void (*)(const hf_esp_can_error_info_t& error_info,
                                             void* user_data);
using hf_esp_can_state_callback_t = void (*)(const hf_esp_can_state_info_t& state_info,
                                             void* user_data);
using hf_esp_can_tx_callback_t = void (*)(const hf_esp_can_tx_info_t& tx_info, void* user_data);
 
class EspCan : public BaseCan {
public:
  //==============================================//
  // CONSTRUCTOR AND DESTRUCTOR
  //==============================================//
 
  explicit EspCan(const hf_esp_can_config_t& config) noexcept;
 
  ~EspCan() noexcept override;
 
  //==============================================//
  // CORE CAN OPERATIONS (From BaseCan interface)
  //==============================================//
 
  hf_can_err_t Initialize() noexcept override;
 
  hf_can_err_t Deinitialize() noexcept override;
 
  hf_can_err_t SendMessage(const hf_can_message_t& message,
                           uint32_t timeout_ms = 1000) noexcept override;
 
  hf_can_err_t ReceiveMessage(hf_can_message_t& message, uint32_t timeout_ms = 0) noexcept override;
 
  hf_can_err_t SetReceiveCallback(hf_can_receive_callback_t callback) noexcept override;
 
  void ClearReceiveCallback() noexcept override;
 
  //==============================================//
  // SINGLE-CALLBACK PER EVENT MANAGEMENT
  //==============================================//
 
  // Receive (runs in ISR context: copy the frame, no blocking, no logging)
  hf_can_err_t SetReceiveCallbackEx(hf_esp_can_receive_callback_t cb,
                                    void* user_data = nullptr) noexcept;
  void ClearReceiveCallbackEx() noexcept;
 
  // Error
  hf_can_err_t SetErrorCallback(hf_esp_can_error_callback_t cb, void* user_data = nullptr) noexcept;
  void ClearErrorCallback() noexcept;
 
  // State change
  hf_can_err_t SetStateChangeCallback(hf_esp_can_state_callback_t cb,
                                      void* user_data = nullptr) noexcept;
  void ClearStateChangeCallback() noexcept;
 
  // TX complete
  hf_can_err_t SetTxCompleteCallback(hf_esp_can_tx_callback_t cb,
                                     void* user_data = nullptr) noexcept;
  void ClearTxCompleteCallback() noexcept;
 
  hf_can_err_t GetStatus(hf_can_status_t& status) noexcept override;
 
  hf_can_err_t Reset() noexcept override;
 
  hf_can_err_t SetAcceptanceFilter(uint32_t id, uint32_t mask,
                                   bool extended = false) noexcept override;
 
  hf_can_err_t ClearAcceptanceFilter() noexcept override;
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS (From BaseCan)
  //==============================================//
 
  hf_can_err_t GetStatistics(hf_can_statistics_t& stats) noexcept override;
 
  hf_can_err_t ResetStatistics() noexcept override;
 
  hf_can_err_t GetDiagnostics(hf_can_diagnostics_t& diagnostics) noexcept override;
 
  //==============================================//
  // ESP-IDF v5.5 SPECIFIC ADVANCED FEATURES
  //==============================================//
 
  hf_can_err_t ConfigureAdvancedTiming(const hf_esp_can_timing_config_t& timing_config) noexcept;
 
  hf_can_err_t ConfigureAdvancedFilter(const hf_esp_can_filter_config_t& filter_config) noexcept;
 
  hf_can_err_t InitiateBusRecovery() noexcept;
 
  hf_can_err_t GetBusStatus(hf_can_bus_status_t& status) noexcept override;
 
  hf_can_err_t RequestBusRecovery() noexcept override;
 
  hf_can_err_t GetNodeInfo(twai_node_record_t& node_info) noexcept;
 
  uint32_t SendMessageBatch(const hf_can_message_t* messages, uint32_t count,
                            uint32_t timeout_ms = 1000) noexcept;
 
private:
  //==============================================//
  // INTERNAL EVENT CALLBACKS (ESP-IDF v5.5)
  //==============================================//
 
  static bool InternalReceiveCallback(twai_node_handle_t handle,
                                      const twai_rx_done_event_data_t* event_data,
                                      void* user_ctx) noexcept;
 
  static bool InternalErrorCallback(twai_node_handle_t handle,
                                    const twai_error_event_data_t* event_data,
                                    void* user_ctx) noexcept;
 
  static bool InternalStateChangeCallback(twai_node_handle_t handle,
                                          const twai_state_change_event_data_t* event_data,
                                          void* user_ctx) noexcept;
 
  static bool InternalTxDoneCallback(twai_node_handle_t handle,
                                     const twai_tx_done_event_data_t* event_data,
                                     void* user_ctx) noexcept;
 
  //==============================================//
  // INTERNAL HELPER METHODS
  //==============================================//
 
  static hf_can_err_t ConvertToTwaiFrame(const hf_can_message_t& hf_message,
                                         twai_frame_t& twai_frame) noexcept;
 
  static hf_can_err_t ConvertFromTwaiFrame(const twai_frame_t& twai_frame,
                                           hf_can_message_t& hf_message) noexcept;
 
  hf_can_err_t ConvertEspError(esp_err_t esp_err) noexcept;
 
  void UpdateStatistics(hf_can_operation_type_t operation_type, bool success) noexcept;
 
  bool DeliverReceivedFromIsr(const hf_can_message_t& message) noexcept;
 
  hf_can_err_t AllocateQueues() noexcept;
 
  void ReleaseQueues() noexcept;
 
  void RefreshBusState() noexcept;
 
  void UpdateErrorStatistics(uint32_t error_type) noexcept;
 
  //==============================================//
  // CALLBACK DISPATCH HELPERS
  //==============================================//
 
  void DispatchErrorCallbacks(const hf_esp_can_error_info_t& error_info) noexcept;
 
  void DispatchStateChangeCallbacks(const hf_esp_can_state_info_t& state_info) noexcept;
 
  void DispatchTxCompleteCallbacks(const hf_esp_can_tx_info_t& tx_info) noexcept;
 
  // (no registry helpers in single-callback design)
 
  //==============================================//
  // MEMBER VARIABLES (ESP-IDF v5.5 Compatible)
  //==============================================//
 
  // Configuration (centralized)
  const hf_esp_can_config_t config_; 
 
  // State flags (atomic)
  std::atomic<bool> is_enabled_;    
  std::atomic<bool> is_recovering_; 
 
  // Thread safety (PlatformMutex)
  mutable PlatformMutex config_mutex_;   
  mutable PlatformMutex stats_mutex_;    
  mutable PlatformMutex callback_mutex_; 
 
  // ESP-IDF v5.5 TWAI node handle
  twai_node_handle_t twai_node_handle_; 
 
  // Single callbacks + user data per event type. The receive callbacks are read
  // from the RX ISR, so they are atomics (user data is stored before the callback).
  std::atomic<hf_esp_can_receive_callback_t> receive_cb_{nullptr};
  std::atomic<void*> receive_ud_{nullptr};
  std::atomic<hf_can_receive_callback_t> base_receive_cb_{nullptr};
 
  hf_esp_can_error_callback_t error_cb_{nullptr};
  void* error_ud_ = nullptr;
 
  hf_esp_can_state_callback_t state_cb_{nullptr};
  void* state_ud_ = nullptr;
 
  hf_esp_can_tx_callback_t tx_cb_{nullptr};
  void* tx_ud_ = nullptr;
 
  // Statistics and diagnostics
  hf_can_statistics_t statistics_;   
  hf_can_diagnostics_t diagnostics_; 
 
  // Advanced features
  hf_esp_can_timing_config_t advanced_timing_; 
  hf_esp_can_filter_config_t current_filter_;  
  bool filter_configured_;                     
 
  // RX path: ISR -> lock-free ring -> ReceiveMessage()
  HfSpscRing<hf_can_message_t> rx_ring_; 
  SemaphoreHandle_t rx_sem_{nullptr};    
  mutable PlatformMutex rx_mutex_;       
 
  // TX path: each queued frame lives in a slot until the TX-done ISR frees it.
  // The TWAI driver queues a pointer to the frame, not a copy, so the frame and
  // its buffer must stay valid until transmission completes.
  struct TxSlot {
    twai_frame_t frame;                     
    uint8_t buffer[HF_CAN_CLASSIC_MAX_LEN]; 
    std::atomic<bool> in_use;               
  };
  std::unique_ptr<TxSlot[]> tx_slots_;     
  uint32_t tx_slot_count_{0};              
  SemaphoreHandle_t tx_slot_sem_{nullptr}; 
 
  // Error-state counters (written from ISRs)
  std::atomic<uint32_t> tx_queue_full_{0}; 
  std::atomic<uint32_t> bus_off_count_{0}; 
  std::atomic<uint8_t> bus_state_{0};      
};
 
//==============================================//