EspI2c.h

Go to the documentation of this file.

#ifndef ESP_I2C_H_
#define ESP_I2C_H_
 
#pragma once
 
#include "BaseI2c.h"
#include "utils/EspTypes.h"
#include "utils/PlatformMutex.h"
#include <memory>
#include <vector>
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
#include "driver/i2c_master.h"
#include "esp_log.h"
#ifdef __cplusplus
}
#endif
 
// Forward declarations
class EspI2cBus;
class EspI2cDevice;
 
enum class hf_i2c_operation_t : uint8_t {
  HF_I2C_OP_WRITE = 0,           
  HF_I2C_OP_READ = 1,            
  HF_I2C_OP_WRITE_READ = 2,      
  HF_I2C_OP_WRITE_ASYNC = 3,     
  HF_I2C_OP_READ_ASYNC = 4,      
  HF_I2C_OP_WRITE_READ_ASYNC = 5 
};
 
const char* HfI2COperationToString(hf_i2c_operation_t op) noexcept;
 
class EspI2cDevice : public BaseI2c {
public:
  EspI2cDevice(EspI2cBus* parent, const hf_i2c_device_config_t& config);
 
  ~EspI2cDevice() noexcept override;
 
  bool Initialize() noexcept override;
 
  bool MarkAsDeinitialized() noexcept;
 
  bool Deinitialize() noexcept override;
 
  hf_i2c_err_t Write(const hf_u8_t* data, hf_u16_t length,
                     hf_u32_t timeout_ms = 0) noexcept override;
 
  hf_i2c_err_t Read(hf_u8_t* data, hf_u16_t length, hf_u32_t timeout_ms = 0) noexcept override;
 
  hf_i2c_err_t WriteRead(const hf_u8_t* tx_data, hf_u16_t tx_length, hf_u8_t* rx_data,
                         hf_u16_t rx_length, hf_u32_t timeout_ms = 0) noexcept override;
 
  //==============================================//
  // ASYNC OPERATIONS - ESP-IDF v5.5+ FEATURES   //
  //==============================================//
 
  hf_i2c_err_t WriteAsync(const hf_u8_t* data, hf_u16_t length, hf_i2c_async_callback_t callback,
                          void* user_data = nullptr, hf_u32_t timeout_ms = 1000) noexcept;
 
  hf_i2c_err_t ReadAsync(hf_u8_t* data, hf_u16_t length, hf_i2c_async_callback_t callback,
                         void* user_data = nullptr, hf_u32_t timeout_ms = 1000) noexcept;
 
  hf_i2c_err_t WriteReadAsync(const hf_u8_t* tx_data, hf_u16_t tx_length, hf_u8_t* rx_data,
                              hf_u16_t rx_length, hf_i2c_async_callback_t callback,
                              void* user_data = nullptr, hf_u32_t timeout_ms = 1000) noexcept;
 
  bool IsAsyncModeSupported() const noexcept;
 
  bool IsAsyncOperationInProgress() const noexcept;
 
  bool IsSyncOperationInProgress() const noexcept;
 
  bool WaitAsyncOperationComplete(hf_u32_t timeout_ms = 0) noexcept;
 
  hf_i2c_err_t GetStatistics(hf_i2c_statistics_t& statistics) const noexcept override;
 
  hf_i2c_err_t GetDiagnostics(hf_i2c_diagnostics_t& diagnostics) const noexcept override;
 
  hf_i2c_err_t ResetStatistics() noexcept override;
 
  i2c_master_dev_handle_t GetHandle() const noexcept;
 
  const hf_i2c_device_config_t& GetConfig() const noexcept;
 
  hf_u16_t GetDeviceAddress() const noexcept;
 
  hf_i2c_err_t GetActualClockFrequency(hf_u32_t& actual_freq_hz) const noexcept;
 
  bool ProbeDevice() noexcept;
 
  i2c_master_dev_handle_t GetDeviceHandle() const noexcept {
    return handle_;
  }
 
  hf_i2c_async_callback_t GetCurrentCallback() const noexcept {
    return current_callback_;
  }
 
  void* GetCurrentUserData() const noexcept {
    return current_user_data_;
  }
 
  void UpdateErrorRecoveryAttempt() noexcept;
 
  //==============================================//
  // MODE-AWARE OPERATION METHODS                //
  //==============================================//
 
  hf_i2c_mode_t GetMode() const noexcept;
 
  bool IsAsyncMode() const noexcept;
 
  bool IsSyncMode() const noexcept;
 
private:
  //==============================================//
  // ESP-IDF v5.5 ASYNC CALLBACK BRIDGE          //
  //==============================================//
 
  static bool InternalAsyncCallback(i2c_master_dev_handle_t i2c_dev,
                                    const i2c_master_event_data_t* evt_data, void* arg);
 
  bool RegisterTemporaryCallback(hf_i2c_async_callback_t callback, void* user_data,
                                 hf_u32_t timeout_ms) noexcept;
 
  void UnregisterTemporaryCallback() noexcept;
 
  inline void StartAsyncOperationTracking() noexcept;
 
  void UpdateStatistics(bool success, size_t bytes_transferred,
                        hf_u64_t operation_time_us) noexcept;
 
  void UpdateErrorStatistics(hf_i2c_err_t error_code) noexcept;
 
  hf_i2c_err_t ConvertEspError(esp_err_t esp_error) const noexcept;
 
  bool ValidateOperation(const void* data, hf_u16_t length,
                         hf_i2c_operation_t operation_type) noexcept;
 
  bool SetupSyncOperation(hf_i2c_operation_t operation_type) noexcept;
 
  void CleanupSyncOperation() noexcept;
 
  void CleanupAsyncOperation() noexcept;
 
  bool SetupAsyncOperation(hf_i2c_async_callback_t callback, void* user_data,
                           hf_u32_t timeout_ms) noexcept;
 
  //==============================================//
  // MEMBER VARIABLES                            //
  //==============================================//
 
  EspI2cBus* parent_bus_;                    
  i2c_master_dev_handle_t handle_;           
  hf_i2c_device_config_t config_;            
  bool initialized_;                         
  mutable hf_i2c_statistics_t statistics_;   
  mutable hf_i2c_diagnostics_t diagnostics_; 
  mutable PlatformMutex mutex_;                  
  hf_i2c_mode_t device_mode_;                
 
  //==============================================//
  // ASYNC OPERATION SUPPORT                     //
  //==============================================//
  bool async_operation_in_progress_;          
  bool sync_operation_in_progress_;           
  hf_i2c_async_callback_t current_callback_;  
  void* current_user_data_;                   
  hf_u64_t async_start_time_;                 
  hf_i2c_transaction_type_t current_op_type_; 
  hf_u16_t last_write_length_;                
  hf_u16_t last_read_length_;                 
};
 
class EspI2cBus {
public:
  explicit EspI2cBus(const hf_i2c_master_bus_config_t& config) noexcept;
 
  ~EspI2cBus() noexcept;
 
  // Non-copyable, non-movable
  EspI2cBus(const EspI2cBus&) = delete;
  EspI2cBus& operator=(const EspI2cBus&) = delete;
  EspI2cBus(EspI2cBus&&) = delete;
  EspI2cBus& operator=(EspI2cBus&&) = delete;
 
  bool Initialize() noexcept;
 
  bool Deinitialize() noexcept;
 
  int CreateDevice(const hf_i2c_device_config_t& device_config) noexcept;
 
  BaseI2c* GetDevice(int device_index) noexcept;
 
  const BaseI2c* GetDevice(int device_index) const noexcept;
 
  EspI2cDevice* GetEspDevice(int device_index) noexcept;
 
  const EspI2cDevice* GetEspDevice(int device_index) const noexcept;
 
  BaseI2c* GetDeviceByAddress(hf_u16_t device_address) noexcept;
 
  std::size_t GetDeviceCount() const noexcept;
 
  bool RemoveDevice(int device_index) noexcept;
 
  bool RemoveDeviceByAddress(hf_u16_t device_address) noexcept;
 
  //==============================================//
  // INDEX-BASED ACCESS AND ITERATION METHODS    //
  //==============================================//
 
  BaseI2c* operator[](int device_index) noexcept;
 
  const BaseI2c* operator[](int device_index) const noexcept;
 
  EspI2cDevice* At(int device_index) noexcept;
 
  const EspI2cDevice* At(int device_index) const noexcept;
 
  bool IsValidIndex(int device_index) const noexcept;
 
  BaseI2c* GetFirstDevice() noexcept;
 
  const BaseI2c* GetFirstDevice() const noexcept;
 
  BaseI2c* GetLastDevice() noexcept;
 
  const BaseI2c* GetLastDevice() const noexcept;
 
  std::vector<BaseI2c*> GetAllDevices() noexcept;
 
  std::vector<const BaseI2c*> GetAllDevices() const noexcept;
 
  std::vector<EspI2cDevice*> GetAllEspDevices() noexcept;
 
  std::vector<const EspI2cDevice*> GetAllEspDevices() const noexcept;
 
  int FindDeviceIndex(hf_u16_t device_address) const noexcept;
 
  std::vector<hf_u16_t> GetDeviceAddresses() const noexcept;
 
  bool HasDevices() const noexcept;
 
  bool IsEmpty() const noexcept;
 
  bool ClearAllDevices() noexcept;
 
  const hf_i2c_master_bus_config_t& GetConfig() const noexcept;
 
  i2c_master_bus_handle_t GetHandle() const noexcept;
 
  int GetPort() const noexcept;
 
  bool IsInitialized() const noexcept;
 
  size_t ScanDevices(std::vector<hf_u16_t>& found_devices, hf_u16_t start_addr = 0x08,
                     hf_u16_t end_addr = 0x77, hf_u32_t scan_timeout_ms = 0) noexcept;
 
  bool ProbeDevice(hf_u16_t device_addr, hf_u32_t timeout_ms = 10) noexcept;
 
  bool ResetBus() noexcept;
 
  //==============================================//
  // MODE MANAGEMENT METHODS                      //
  //==============================================//
 
  hf_i2c_mode_t GetMode() const noexcept;
 
  bool IsAsyncMode() const noexcept;
 
  bool IsSyncMode() const noexcept;
 
  bool SwitchMode(hf_i2c_mode_t new_mode, uint8_t queue_depth = 10) noexcept;
 
private:
  //==============================================//
  // PRIVATE METHODS                              //
  //==============================================//
 
  int FindDeviceIndexByAddress(hf_u16_t device_address) const noexcept;
 
  hf_i2c_err_t ConvertEspError(esp_err_t esp_error) const noexcept;
 
  bool CustomFastProbe(hf_u16_t device_addr, hf_u32_t timeout_ms) noexcept;
 
  //==============================================//
  // MEMBER VARIABLES                            //
  //==============================================//
 
  hf_i2c_master_bus_config_t config_;                  
  i2c_master_bus_handle_t bus_handle_;                 
  bool initialized_;                                   
  mutable PlatformMutex mutex_;                            
  std::vector<std::unique_ptr<EspI2cDevice>> devices_; 
  hf_i2c_mode_t current_mode_;                         
 
  // Bus-level statistics and diagnostics
  mutable hf_i2c_statistics_t statistics_;   
  mutable hf_i2c_diagnostics_t diagnostics_; 
};
 
#endif // ESP_I2C_H_