HF Interface Wrapper 0.1.0-dev
Embedded C++ hardware abstraction layer
Loading...
Searching...
No Matches
EspCan Class Reference

ESP32 CAN (TWAI) implementation using ESP-IDF v5.5+ node-based API. More...

#include <EspCan.h>

Inheritance diagram for EspCan:
[legend]
Collaboration diagram for EspCan:
[legend]

Public Member Functions

 EspCan (const hf_esp_can_config_t &config) noexcept
 Constructor with TWAI node configuration.
 
 ~EspCan () noexcept override
 Destructor - ensures proper cleanup and resource deallocation.
 
hf_can_err_t Initialize () noexcept override
 Initialize the TWAI node and allocate resources.
 
hf_can_err_t Deinitialize () noexcept override
 Deinitialize the TWAI node and free resources.
 
hf_can_err_t SendMessage (const hf_can_message_t &message, uint32_t timeout_ms=1000) noexcept override
 Send a CAN message.
 
hf_can_err_t ReceiveMessage (hf_can_message_t &message, uint32_t timeout_ms=0) noexcept override
 Receive a CAN message (legacy polling interface).
 
hf_can_err_t SetReceiveCallback (hf_can_receive_callback_t callback) noexcept override
 Set callback for received messages (legacy support removed - use RegisterReceiveCallback).
 
void ClearReceiveCallback () noexcept override
 Clear the receive callback (legacy support removed - use UnregisterCallback).
 
hf_can_err_t SetReceiveCallbackEx (hf_esp_can_receive_callback_t cb, void *user_data=nullptr) noexcept
 
void ClearReceiveCallbackEx () noexcept
 
hf_can_err_t SetErrorCallback (hf_esp_can_error_callback_t cb, void *user_data=nullptr) noexcept
 
void ClearErrorCallback () noexcept
 
hf_can_err_t SetStateChangeCallback (hf_esp_can_state_callback_t cb, void *user_data=nullptr) noexcept
 
void ClearStateChangeCallback () noexcept
 
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
 Get current CAN bus status.
 
hf_can_err_t Reset () noexcept override
 Reset the CAN controller.
 
hf_can_err_t SetAcceptanceFilter (uint32_t id, uint32_t mask, bool extended=false) noexcept override
 Set acceptance filter for incoming messages.
 
hf_can_err_t ClearAcceptanceFilter () noexcept override
 Clear all acceptance filters (accept all messages).
 
hf_can_err_t GetStatistics (hf_can_statistics_t &stats) noexcept override
 Get detailed statistics.
 
hf_can_err_t ResetStatistics () noexcept override
 Reset statistics counters.
 
hf_can_err_t GetDiagnostics (hf_can_diagnostics_t &diagnostics) noexcept override
 Get diagnostic information.
 
hf_can_err_t ConfigureAdvancedTiming (const hf_esp_can_timing_config_t &timing_config) noexcept
 Configure advanced bit timing parameters.
 
hf_can_err_t ConfigureAdvancedFilter (const hf_esp_can_filter_config_t &filter_config) noexcept
 Configure hardware acceptance filter with advanced options.
 
hf_can_err_t InitiateBusRecovery () noexcept
 Initiate bus recovery from bus-off state.
 
hf_can_err_t GetNodeInfo (twai_node_record_t &node_info) noexcept
 Get detailed node information including error states.
 
uint32_t SendMessageBatch (const hf_can_message_t *messages, uint32_t count, uint32_t timeout_ms=1000) noexcept
 Send multiple messages in a batch for improved performance.
 
- Public Member Functions inherited from BaseCan
virtual ~BaseCan () noexcept=default
 Virtual destructor ensures proper cleanup in derived classes.
 
 BaseCan (const BaseCan &)=delete
 
BaseCanoperator= (const BaseCan &)=delete
 
 BaseCan (BaseCan &&)=delete
 
BaseCanoperator= (BaseCan &&)=delete
 
bool EnsureInitialized () noexcept
 Ensures that the CAN bus is initialized (lazy initialization).
 
bool EnsureDeinitialized () noexcept
 Ensures that the CAN bus is deinitialized.
 
bool IsInitialized () const noexcept
 Checks if the class is initialized.
 
virtual hf_can_err_t SetReceiveCallbackFD (hf_can_fd_receive_callback_t callback) noexcept
 Set CAN-FD receive callback with enhanced information.
 
virtual bool SupportsCanFD () const noexcept
 Check if CAN-FD is supported by this controller.
 
virtual bool SetCanFDMode (bool enable, hf_u32_t data_baudrate=2000000, hf_u32_t timeout_ms=1000) noexcept
 Enable or disable CAN-FD mode.
 
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
 Configure CAN-FD timing parameters.
 
virtual bool SetTransmitterDelayCompensation (hf_u8_t tdc_offset, hf_u8_t tdc_filter) noexcept
 Set transmitter delay compensation (CAN-FD feature).
 
virtual hf_u32_t ReceiveMessageBatch (hf_can_message_t *messages, hf_u32_t max_count, hf_u32_t timeout_ms=100) noexcept
 Receive multiple messages in a batch.
 
virtual hf_can_err_t ResetDiagnostics () noexcept
 Reset CAN diagnostic information.
 

Private Member Functions

hf_can_err_t ConvertToTwaiFrame (const hf_can_message_t &hf_message, twai_frame_t &twai_frame) noexcept
 Convert HF CAN message to ESP-IDF v5.5 TWAI frame.
 
hf_can_err_t ConvertFromTwaiFrame (const twai_frame_t &twai_frame, hf_can_message_t &hf_message) noexcept
 Convert ESP-IDF v5.5 TWAI frame to HF CAN message.
 
hf_can_err_t ConvertEspError (esp_err_t esp_err) noexcept
 Convert ESP-IDF error to HF error code.
 
void UpdateStatistics (hf_can_operation_type_t operation_type, bool success) noexcept
 Update statistics after an operation.
 
void ProcessReceivedMessage (const twai_frame_t &frame) noexcept
 Process received message through callback system.
 
void UpdateErrorStatistics (uint32_t error_type) noexcept
 Update error statistics from error event.
 
void DispatchReceiveCallbacks (const twai_frame_t &frame) noexcept
 Dispatch message to all registered receive callbacks.
 
void DispatchErrorCallbacks (const hf_esp_can_error_info_t &error_info) noexcept
 Dispatch error event to all registered error callbacks.
 
void DispatchStateChangeCallbacks (const hf_esp_can_state_info_t &state_info) noexcept
 Dispatch state change to all registered state callbacks.
 
void DispatchTxCompleteCallbacks (const hf_esp_can_tx_info_t &tx_info) noexcept
 Dispatch transmission complete to all registered TX callbacks.
 

Static Private Member Functions

static bool InternalReceiveCallback (twai_node_handle_t handle, const twai_rx_done_event_data_t *event_data, void *user_ctx) noexcept
 Internal receive event callback for ESP-IDF v5.5 event system.
 
static bool InternalErrorCallback (twai_node_handle_t handle, const twai_error_event_data_t *event_data, void *user_ctx) noexcept
 Internal error event callback for comprehensive error handling.
 
static bool InternalStateChangeCallback (twai_node_handle_t handle, const twai_state_change_event_data_t *event_data, void *user_ctx) noexcept
 Internal state change callback for bus recovery monitoring.
 

Private Attributes

const hf_esp_can_config_t config_
 TWAI node configuration.
 
std::atomic< bool > is_enabled_
 Node enabled state.
 
std::atomic< bool > is_recovering_
 Bus recovery state.
 
PlatformMutex config_mutex_
 Configuration mutex.
 
PlatformMutex stats_mutex_
 Statistics mutex.
 
PlatformMutex callback_mutex_
 Callback registry mutex.
 
twai_node_handle_t twai_node_handle_
 Native TWAI node handle.
 
hf_esp_can_receive_callback_t receive_cb_ {nullptr}
 
void * receive_ud_ = 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
 
hf_can_statistics_t statistics_
 Performance statistics.
 
hf_can_diagnostics_t diagnostics_
 Diagnostic information.
 
hf_esp_can_timing_config_t advanced_timing_
 Advanced timing configuration.
 
hf_esp_can_filter_config_t current_filter_
 Current filter configuration.
 
bool filter_configured_
 Filter configuration state.
 

Additional Inherited Members

- Protected Member Functions inherited from BaseCan
 BaseCan () noexcept
 Protected constructor.
 
- Protected Attributes inherited from BaseCan
bool initialized_
 Initialization status.
 
hf_can_statistics_t statistics_
 CAN operation statistics.
 
hf_can_diagnostics_t diagnostics_
 CAN diagnostic information.
 

Detailed Description

ESP32 CAN (TWAI) implementation using ESP-IDF v5.5+ node-based API.

This class provides clean, comprehensive CAN communication using the ESP32's TWAI (Two-Wire Automotive Interface) controllers with modern ESP-IDF v5.5+ node-based APIs. The implementation supports ESP32-C6 and external SN65 CAN transceivers.

Key Features:

  • ESP-IDF v5.5+ handle-based TWAI node API
  • ESP32-C6 compatible TWAI controller support
  • Event-driven callback-based message reception
  • Advanced acceptance filtering (single/dual mask modes)
  • Comprehensive error detection and bus recovery
  • Advanced bit timing configuration for various baud rates
  • Thread-safe operations with proper resource management
  • Support for external SN65 CAN transceivers
  • Comprehensive diagnostics and performance monitoring
Note
This implementation requires ESP-IDF v5.5 or later
Each EspCan instance represents a single TWAI node

Constructor & Destructor Documentation

◆ EspCan()

EspCan::EspCan ( const hf_esp_can_config_t & config)
explicitnoexcept

Constructor with TWAI node configuration.

Parameters
configTWAI node configuration parameters

LAZY INITIALIZATION: The TWAI node is NOT physically configured until Initialize() is called. This follows the same pattern as EspAdc.

◆ ~EspCan()

EspCan::~EspCan ( )
overridenoexcept

Destructor - ensures proper cleanup and resource deallocation.

Member Function Documentation

◆ ClearAcceptanceFilter()

hf_can_err_t EspCan::ClearAcceptanceFilter ( )
overridevirtualnoexcept

Clear all acceptance filters (accept all messages).

Returns
hf_can_err_t error code

Reimplemented from BaseCan.

◆ ClearErrorCallback()

void EspCan::ClearErrorCallback ( )
noexcept

◆ ClearReceiveCallback()

void EspCan::ClearReceiveCallback ( )
overridevirtualnoexcept

Clear the receive callback (legacy support removed - use UnregisterCallback).

Reimplemented from BaseCan.

◆ ClearReceiveCallbackEx()

void EspCan::ClearReceiveCallbackEx ( )
noexcept

◆ ClearStateChangeCallback()

void EspCan::ClearStateChangeCallback ( )
noexcept

◆ ClearTxCompleteCallback()

void EspCan::ClearTxCompleteCallback ( )
noexcept

◆ ConfigureAdvancedFilter()

hf_can_err_t EspCan::ConfigureAdvancedFilter ( const hf_esp_can_filter_config_t & filter_config)
noexcept

Configure hardware acceptance filter with advanced options.

Parameters
filter_configFilter configuration including dual filter support
Returns
hf_can_err_t error code

◆ ConfigureAdvancedTiming()

hf_can_err_t EspCan::ConfigureAdvancedTiming ( const hf_esp_can_timing_config_t & timing_config)
noexcept

Configure advanced bit timing parameters.

Parameters
timing_configAdvanced timing configuration
Returns
hf_can_err_t error code

◆ ConvertEspError()

hf_can_err_t EspCan::ConvertEspError ( esp_err_t esp_err)
privatenoexcept

Convert ESP-IDF error to HF error code.

Parameters
esp_errESP-IDF error code
Returns
hf_can_err_t error code

◆ ConvertFromTwaiFrame()

hf_can_err_t EspCan::ConvertFromTwaiFrame ( const twai_frame_t & twai_frame,
hf_can_message_t & hf_message )
privatenoexcept

Convert ESP-IDF v5.5 TWAI frame to HF CAN message.

Parameters
twai_frameSource TWAI frame
hf_messageDestination HF message
Returns
hf_can_err_t error code

◆ ConvertToTwaiFrame()

hf_can_err_t EspCan::ConvertToTwaiFrame ( const hf_can_message_t & hf_message,
twai_frame_t & twai_frame )
privatenoexcept

Convert HF CAN message to ESP-IDF v5.5 TWAI frame.

Parameters
hf_messageSource HF message
twai_frameDestination TWAI frame
Returns
hf_can_err_t error code

◆ Deinitialize()

hf_can_err_t EspCan::Deinitialize ( )
overridevirtualnoexcept

Deinitialize the TWAI node and free resources.

Returns
hf_can_err_t error code
Note
This method stops the TWAI node and releases all resources

Implements BaseCan.

◆ DispatchErrorCallbacks()

void EspCan::DispatchErrorCallbacks ( const hf_esp_can_error_info_t & error_info)
privatenoexcept

Dispatch error event to all registered error callbacks.

Parameters
error_infoError information

◆ DispatchReceiveCallbacks()

void EspCan::DispatchReceiveCallbacks ( const twai_frame_t & frame)
privatenoexcept

Dispatch message to all registered receive callbacks.

Parameters
frameReceived TWAI frame

◆ DispatchStateChangeCallbacks()

void EspCan::DispatchStateChangeCallbacks ( const hf_esp_can_state_info_t & state_info)
privatenoexcept

Dispatch state change to all registered state callbacks.

Parameters
state_infoState change information

◆ DispatchTxCompleteCallbacks()

void EspCan::DispatchTxCompleteCallbacks ( const hf_esp_can_tx_info_t & tx_info)
privatenoexcept

Dispatch transmission complete to all registered TX callbacks.

Parameters
tx_infoTransmission information

◆ GetDiagnostics()

hf_can_err_t EspCan::GetDiagnostics ( hf_can_diagnostics_t & diagnostics)
overridevirtualnoexcept

Get diagnostic information.

Parameters
diagnosticsReference to store diagnostic data
Returns
hf_can_err_t error code

Reimplemented from BaseCan.

◆ GetNodeInfo()

hf_can_err_t EspCan::GetNodeInfo ( twai_node_record_t & node_info)
noexcept

Get detailed node information including error states.

Parameters
node_infoReference to store node information
Returns
hf_can_err_t error code

◆ GetStatistics()

hf_can_err_t EspCan::GetStatistics ( hf_can_statistics_t & stats)
overridevirtualnoexcept

Get detailed statistics.

Parameters
statsReference to store statistics
Returns
hf_can_err_t error code

Reimplemented from BaseCan.

◆ GetStatus()

hf_can_err_t EspCan::GetStatus ( hf_can_status_t & status)
overridevirtualnoexcept

Get current CAN bus status.

Parameters
statusReference to store status information
Returns
hf_can_err_t error code

Implements BaseCan.

◆ Initialize()

hf_can_err_t EspCan::Initialize ( )
overridevirtualnoexcept

Initialize the TWAI node and allocate resources.

Returns
hf_can_err_t error code
Note
This method configures the TWAI hardware and starts the node

Implements BaseCan.

◆ InitiateBusRecovery()

hf_can_err_t EspCan::InitiateBusRecovery ( )
noexcept

Initiate bus recovery from bus-off state.

Returns
hf_can_err_t error code

◆ InternalErrorCallback()

bool EspCan::InternalErrorCallback ( twai_node_handle_t handle,
const twai_error_event_data_t * event_data,
void * user_ctx )
staticprivatenoexcept

Internal error event callback for comprehensive error handling.

Parameters
handleTWAI node handle
event_dataError event data
user_ctxUser context
Returns
true to yield to higher priority task

◆ InternalReceiveCallback()

bool EspCan::InternalReceiveCallback ( twai_node_handle_t handle,
const twai_rx_done_event_data_t * event_data,
void * user_ctx )
staticprivatenoexcept

Internal receive event callback for ESP-IDF v5.5 event system.

Parameters
handleTWAI node handle
event_dataEvent data
user_ctxUser context
Returns
true to yield to higher priority task

◆ InternalStateChangeCallback()

bool EspCan::InternalStateChangeCallback ( twai_node_handle_t handle,
const twai_state_change_event_data_t * event_data,
void * user_ctx )
staticprivatenoexcept

Internal state change callback for bus recovery monitoring.

Parameters
handleTWAI node handle
event_dataState change event data
user_ctxUser context
Returns
true to yield to higher priority task

◆ ProcessReceivedMessage()

void EspCan::ProcessReceivedMessage ( const twai_frame_t & frame)
privatenoexcept

Process received message through callback system.

Parameters
frameReceived TWAI frame

◆ ReceiveMessage()

hf_can_err_t EspCan::ReceiveMessage ( hf_can_message_t & message,
uint32_t timeout_ms = 0 )
overridevirtualnoexcept

Receive a CAN message (legacy polling interface).

Parameters
messageReference to store received message
timeout_msTimeout in milliseconds (0 = non-blocking)
Returns
hf_can_err_t error code
Note
Callback-based reception is preferred for ESP-IDF v5.5+

Implements BaseCan.

◆ Reset()

hf_can_err_t EspCan::Reset ( )
overridevirtualnoexcept

Reset the CAN controller.

Returns
hf_can_err_t error code

Implements BaseCan.

◆ ResetStatistics()

hf_can_err_t EspCan::ResetStatistics ( )
overridevirtualnoexcept

Reset statistics counters.

Returns
hf_can_err_t error code

Reimplemented from BaseCan.

◆ SendMessage()

hf_can_err_t EspCan::SendMessage ( const hf_can_message_t & message,
uint32_t timeout_ms = 1000 )
overridevirtualnoexcept

Send a CAN message.

Parameters
messageCAN message to send
timeout_msTimeout in milliseconds (0 = non-blocking)
Returns
hf_can_err_t error code

Implements BaseCan.

◆ SendMessageBatch()

uint32_t EspCan::SendMessageBatch ( const hf_can_message_t * messages,
uint32_t count,
uint32_t timeout_ms = 1000 )
virtualnoexcept

Send multiple messages in a batch for improved performance.

Parameters
messagesArray of messages to send
countNumber of messages
timeout_msTimeout for each message
Returns
Number of messages successfully sent

Reimplemented from BaseCan.

◆ SetAcceptanceFilter()

hf_can_err_t EspCan::SetAcceptanceFilter ( uint32_t id,
uint32_t mask,
bool extended = false )
overridevirtualnoexcept

Set acceptance filter for incoming messages.

Parameters
idCAN ID to accept
maskAcceptance mask (0 = don't care bits)
extendedtrue for extended frames, false for standard
Returns
hf_can_err_t error code

Implements BaseCan.

◆ SetErrorCallback()

hf_can_err_t EspCan::SetErrorCallback ( hf_esp_can_error_callback_t cb,
void * user_data = nullptr )
noexcept

◆ SetReceiveCallback()

hf_can_err_t EspCan::SetReceiveCallback ( hf_can_receive_callback_t callback)
overridevirtualnoexcept

Set callback for received messages (legacy support removed - use RegisterReceiveCallback).

Parameters
callbackCallback function to handle received messages
Returns
hf_can_err_t error code

Implements BaseCan.

◆ SetReceiveCallbackEx()

hf_can_err_t EspCan::SetReceiveCallbackEx ( hf_esp_can_receive_callback_t cb,
void * user_data = nullptr )
noexcept

◆ SetStateChangeCallback()

hf_can_err_t EspCan::SetStateChangeCallback ( hf_esp_can_state_callback_t cb,
void * user_data = nullptr )
noexcept

◆ SetTxCompleteCallback()

hf_can_err_t EspCan::SetTxCompleteCallback ( hf_esp_can_tx_callback_t cb,
void * user_data = nullptr )
noexcept

◆ UpdateErrorStatistics()

void EspCan::UpdateErrorStatistics ( uint32_t error_type)
privatenoexcept

Update error statistics from error event.

Parameters
error_typeError type from ESP-IDF

◆ UpdateStatistics()

void EspCan::UpdateStatistics ( hf_can_operation_type_t operation_type,
bool success )
privatenoexcept

Update statistics after an operation.

Parameters
operation_typeType of operation
successWhether operation was successful

Member Data Documentation

◆ advanced_timing_

hf_esp_can_timing_config_t EspCan::advanced_timing_
private

Advanced timing configuration.

◆ callback_mutex_

PlatformMutex EspCan::callback_mutex_
mutableprivate

Callback registry mutex.

◆ config_

const hf_esp_can_config_t EspCan::config_
private

TWAI node configuration.

◆ config_mutex_

PlatformMutex EspCan::config_mutex_
mutableprivate

Configuration mutex.

◆ current_filter_

hf_esp_can_filter_config_t EspCan::current_filter_
private

Current filter configuration.

◆ diagnostics_

hf_can_diagnostics_t EspCan::diagnostics_
private

Diagnostic information.

◆ error_cb_

hf_esp_can_error_callback_t EspCan::error_cb_ {nullptr}
private

◆ error_ud_

void* EspCan::error_ud_ = nullptr
private

◆ filter_configured_

bool EspCan::filter_configured_
private

Filter configuration state.

◆ is_enabled_

std::atomic<bool> EspCan::is_enabled_
private

Node enabled state.

◆ is_recovering_

std::atomic<bool> EspCan::is_recovering_
private

Bus recovery state.

◆ receive_cb_

hf_esp_can_receive_callback_t EspCan::receive_cb_ {nullptr}
private

◆ receive_ud_

void* EspCan::receive_ud_ = nullptr
private

◆ state_cb_

hf_esp_can_state_callback_t EspCan::state_cb_ {nullptr}
private

◆ state_ud_

void* EspCan::state_ud_ = nullptr
private

◆ statistics_

hf_can_statistics_t EspCan::statistics_
private

Performance statistics.

◆ stats_mutex_

PlatformMutex EspCan::stats_mutex_
mutableprivate

Statistics mutex.

◆ twai_node_handle_

twai_node_handle_t EspCan::twai_node_handle_
private

Native TWAI node handle.

◆ tx_cb_

hf_esp_can_tx_callback_t EspCan::tx_cb_ {nullptr}
private

◆ tx_ud_

void* EspCan::tx_ud_ = nullptr
private

The documentation for this class was generated from the following files: