BaseI2c.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC I2C Error Codes (Table)
//--------------------------------------
#define HF_I2C_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(I2C_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(I2C_ERR_FAILURE, 1, "General failure")                                                         \
  X(I2C_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(I2C_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(I2C_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(I2C_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(I2C_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Bus errors */                                                                                 \
  X(I2C_ERR_BUS_BUSY, 7, "Bus busy")                                                               \
  X(I2C_ERR_BUS_ERROR, 8, "Bus error")                                                             \
  X(I2C_ERR_BUS_ARBITRATION_LOST, 9, "Arbitration lost")                                           \
  X(I2C_ERR_BUS_NOT_AVAILABLE, 10, "Bus not available")                                            \
  X(I2C_ERR_BUS_TIMEOUT, 11, "Bus timeout")                                                        \
  /* Device errors */                                                                              \
  X(I2C_ERR_DEVICE_NOT_FOUND, 12, "Device not found")                                              \
  X(I2C_ERR_DEVICE_NACK, 13, "Device NACK")                                                        \
  X(I2C_ERR_DEVICE_NOT_RESPONDING, 14, "Device not responding")                                    \
  X(I2C_ERR_INVALID_ADDRESS, 15, "Invalid device address")                                         \
  /* Data errors */                                                                                \
  X(I2C_ERR_DATA_TOO_LONG, 16, "Data too long")                                                    \
  X(I2C_ERR_READ_FAILURE, 17, "Read failure")                                                      \
  X(I2C_ERR_WRITE_FAILURE, 18, "Write failure")                                                    \
  X(I2C_ERR_TIMEOUT, 19, "Operation timeout")                                                      \
  /* Hardware errors */                                                                            \
  X(I2C_ERR_HARDWARE_FAULT, 20, "Hardware fault")                                                  \
  X(I2C_ERR_COMMUNICATION_FAILURE, 21, "Communication failure")                                    \
  X(I2C_ERR_VOLTAGE_OUT_OF_RANGE, 22, "Voltage out of range")                                      \
  X(I2C_ERR_CLOCK_STRETCH_TIMEOUT, 23, "Clock stretch timeout")                                    \
  /* Configuration errors */                                                                       \
  X(I2C_ERR_INVALID_CONFIGURATION, 24, "Invalid configuration")                                    \
  X(I2C_ERR_UNSUPPORTED_OPERATION, 25, "Unsupported operation")                                    \
  X(I2C_ERR_INVALID_CLOCK_SPEED, 26, "Invalid clock speed")                                        \
  X(I2C_ERR_PIN_CONFIGURATION_ERROR, 27, "Pin configuration error")                                \
  /* System errors */                                                                              \
  X(I2C_ERR_SYSTEM_ERROR, 28, "System error")                                                      \
  X(I2C_ERR_PERMISSION_DENIED, 29, "Permission denied")                                            \
  X(I2C_ERR_OPERATION_ABORTED, 30, "Operation aborted")                                            \
  X(I2C_ERR_INVALID_STATE, 31, "Invalid state")                                                    \
  X(I2C_ERR_UNKNOWN, 32, "Unknown error")
 
enum class hf_i2c_err_t : hf_u8_t {
#define X(NAME, VALUE, DESC) NAME = VALUE,
  HF_I2C_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfI2CErrToString(hf_i2c_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_i2c_err_t::NAME:                                                                         \
    return DESC;
    HF_I2C_ERR_LIST(X)
#undef X
  default:
    return HfI2CErrToString(hf_i2c_err_t::I2C_ERR_UNKNOWN);
  }
}
 
struct hf_i2c_statistics_t {
  hf_u64_t total_transactions;        
  hf_u64_t successful_transactions;   
  hf_u64_t failed_transactions;       
  hf_u64_t timeout_count;             
  hf_u64_t bytes_written;             
  hf_u64_t bytes_read;                
  hf_u64_t total_transaction_time_us; 
  hf_u32_t max_transaction_time_us;   
  hf_u32_t min_transaction_time_us;   
  hf_u32_t nack_errors;               
  hf_u32_t bus_errors;                
  hf_u32_t arbitration_lost_count;    
  hf_u32_t clock_stretch_timeouts;    
  hf_u32_t devices_added;             
  hf_u32_t devices_removed;           
 
  hf_i2c_statistics_t() noexcept
      : total_transactions(0), successful_transactions(0), failed_transactions(0), timeout_count(0),
        bytes_written(0), bytes_read(0), total_transaction_time_us(0), max_transaction_time_us(0),
        min_transaction_time_us(UINT32_MAX), nack_errors(0), bus_errors(0),
        arbitration_lost_count(0), clock_stretch_timeouts(0), devices_added(0), devices_removed(0) {
  }
};
 
struct hf_i2c_diagnostics_t {
  bool bus_healthy;                  
  bool sda_line_state;               
  bool scl_line_state;               
  bool bus_locked;                   
  hf_i2c_err_t last_error_code;      
  hf_u64_t last_error_timestamp_us;  
  hf_u32_t consecutive_errors;       
  hf_u32_t error_recovery_attempts;  
  float bus_utilization_percent;     
  hf_u32_t average_response_time_us; 
  hf_u32_t clock_stretching_events;  
  hf_u32_t active_device_count;      
  hf_u32_t total_device_scans;       
  hf_u32_t devices_found_last_scan;  
 
  hf_i2c_diagnostics_t() noexcept
      : bus_healthy(true), sda_line_state(true), scl_line_state(true), bus_locked(false),
        last_error_code(hf_i2c_err_t::I2C_SUCCESS), last_error_timestamp_us(0),
        consecutive_errors(0), error_recovery_attempts(0), bus_utilization_percent(0.0f),
        average_response_time_us(0), clock_stretching_events(0), active_device_count(0),
        total_device_scans(0), devices_found_last_scan(0) {}
};
 
//--------------------------------------
//  Abstract Base Class
//--------------------------------------
 
class BaseI2c {
public:
  virtual ~BaseI2c() noexcept = default;
 
  // Non-copyable, non-movable (can be changed in derived classes if needed)
  BaseI2c(const BaseI2c&) = delete;
  BaseI2c& operator=(const BaseI2c&) = delete;
  BaseI2c(BaseI2c&&) = delete;
  BaseI2c& operator=(BaseI2c&&) = delete;
 
  bool EnsureInitialized() noexcept {
    if (!initialized_) {
      initialized_ = Initialize();
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() noexcept {
    if (initialized_) {
      initialized_ = !Deinitialize();
      return !initialized_;
    }
    return true;
  }
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS - MUST BE OVERRIDDEN  //
  //==============================================//
 
  virtual bool Initialize() noexcept = 0;
 
  virtual bool Deinitialize() noexcept = 0;
 
  virtual hf_i2c_err_t Write(const hf_u8_t* data, hf_u16_t length,
                             hf_u32_t timeout_ms = 0) noexcept = 0;
 
  virtual hf_i2c_err_t Read(hf_u8_t* data, hf_u16_t length, hf_u32_t timeout_ms = 0) noexcept = 0;
 
  virtual 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 = 0;
 
  virtual hf_u16_t GetDeviceAddress() const noexcept = 0;
 
  //==============================================//
  // CONVENIENCE METHODS WITH DEFAULT IMPLEMENTATIONS
  //==============================================//
 
  virtual bool Open() noexcept {
    return Initialize();
  }
 
  virtual bool Close() noexcept {
    return Deinitialize();
  }
 
  // Removed duplicate Write method to avoid overload conflicts
 
  // Removed duplicate Read method to avoid overload conflicts
 
  // Removed duplicate WriteRead method to avoid overload conflicts
 
  virtual bool IsDevicePresent() noexcept {
    // Try to read 1 byte from the device
    hf_u8_t dummy;
    return Read(&dummy, 1, 100) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  virtual bool ProbeDevice() noexcept {
    return IsDevicePresent();
  }
 
  virtual bool WriteByte(hf_u8_t data) noexcept {
    return Write(&data, 1) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  virtual bool ReadByte(hf_u8_t& data) noexcept {
    return Read(&data, 1) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  virtual bool WriteRegister(hf_u8_t reg_addr, hf_u8_t data) noexcept {
    hf_u8_t buffer[2] = {reg_addr, data};
    return Write(buffer, 2) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  virtual bool ReadRegister(hf_u8_t reg_addr, hf_u8_t& data) noexcept {
    return WriteRead(&reg_addr, 1, &data, 1) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  virtual bool ReadRegisters(hf_u8_t reg_addr, hf_u8_t* data, hf_u16_t length) noexcept {
    return WriteRead(&reg_addr, 1, data, length) == hf_i2c_err_t::I2C_SUCCESS;
  }
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS
  //==============================================//
 
  virtual hf_i2c_err_t ResetStatistics() noexcept {
    statistics_ = hf_i2c_statistics_t{}; // Reset statistics to default values
    return hf_i2c_err_t::I2C_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_i2c_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_i2c_diagnostics_t{}; // Reset diagnostics to default values
    return hf_i2c_err_t::I2C_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_i2c_err_t GetStatistics(hf_i2c_statistics_t& statistics) const noexcept {
    statistics = statistics_; // Return statistics by default
    return hf_i2c_err_t::I2C_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_i2c_err_t GetDiagnostics(hf_i2c_diagnostics_t& diagnostics) const noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_i2c_err_t::I2C_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  explicit BaseI2c() noexcept : initialized_(false), statistics_{}, diagnostics_{} {}
 
  bool initialized_;                 
  hf_i2c_statistics_t statistics_;   
  hf_i2c_diagnostics_t diagnostics_; 
};