tle92466ed.hpp

Go to the documentation of this file.

 
#pragma once
#include <array>
#include <span>
 
#include "tle92466ed_expected.hpp"
#include "tle92466ed_spi_interface.hpp"
#include "tle92466ed_registers.hpp"
#include "tle92466ed_version.h"
 
namespace tle92466ed {
 
enum class DriverError : uint8_t {
  None = 0,            
  NotInitialized,      
  HardwareError,       
  InvalidChannel,      
  InvalidParameter,    
  DeviceNotResponding, 
  WrongDeviceID,       
  RegisterError,       
  CRCError,            
  FaultDetected,       
  ConfigurationError,  
  TimeoutError,        
  WrongMode,           
  SPIFrameError,       
  WriteToReadOnly,     
  FeedbackNotReady     
};
 
template <typename T>
using DriverResult = tle::expected<T, DriverError>;
 
struct ChannelConfig {
  ChannelMode mode{ChannelMode::ICC};            
  uint16_t current_setpoint_ma{0};               
  SlewRate slew_rate{SlewRate::MEDIUM_2V5_US};   
  DiagCurrent diag_current{DiagCurrent::I_80UA}; 
  uint8_t open_load_threshold{3};                
  uint16_t pwm_period_mantissa{0};               
  uint8_t pwm_period_exponent{0};                
  bool auto_limit_disabled{false};               
  bool olsg_warning_enabled{false};              
  uint8_t min_int_thresh{CH_CTRL_REG::MIN_INT_THRESH_FLOOR};
  bool pwm_period_calc_mode{false};
  bool deep_dither_enabled{false};               
  uint16_t dither_step_size{0};                  
  uint8_t dither_steps{0};                       
  uint8_t dither_flat{0};                        
};
 
struct DeviceStatus {
  bool config_mode{true}; 
  bool init_done{false};  
  bool any_fault{false};  
 
  // Supply voltage faults
  bool vbat_uv{false}; 
  bool vbat_ov{false}; 
  bool vio_uv{false};  
  bool vio_ov{false};  
  bool vdd_uv{false};  
  bool vdd_ov{false};  
 
  // Temperature
  bool ot_warning{false}; 
  bool ot_error{false};   
 
  // Other faults
  bool clock_fault{false};  
  bool spi_wd_error{false}; 
  bool por_event{false};    
  bool reset_event{false};  
 
  // Internal diagnostics
  bool supply_nok_internal{false}; 
  bool supply_nok_external{false}; 
 
  // Voltage readings
  uint16_t vbat_voltage{0}; 
  uint16_t vio_voltage{0};  
};
 
struct ChannelDiagnostics {
  // Error flags (DIAG_ERR_CHGRx, \u00a75.3.2.12)
  bool overcurrent{false};            
  bool short_to_ground{false};        
  bool open_load{false};              
  bool over_temperature{false};       
  bool open_load_short_ground{false}; 
 
  // Warning flags (DIAG_WARN_CHGRx, \u00a75.3.2.13)
  bool ot_warning{false};                 
  bool current_regulation_warning{false}; 
  bool pwm_regulation_warning{false};     
  bool olsg_warning{false};               
  bool olsg_check_not_performed{false};   
 
  // Measurements (raw 22-bit reply low halves unless noted)
  uint16_t average_current{0}; 
  uint16_t duty_cycle{0};      
  int16_t  min_current_mA{0};  
  int16_t  max_current_mA{0};  
  uint16_t vbat_feedback{0};   
};
 
struct ChannelErrorFlags {
  bool open_load_short_ground{false}; 
  bool open_load{false};              
  bool overcurrent{false};            
  bool short_to_ground{false};        
  bool over_temperature{false};       
};
 
struct ChannelCurrentSample {
  int32_t iavg_ma{0};        
  uint16_t tp_mant{0};       
  uint16_t to_mant{0};       
  bool window_valid{false};  
};
 
struct CurrentFeedbackBatch {
  uint8_t requested_mask{0}; 
  uint8_t update_mask{0};    
  uint8_t valid_mask{0};     
  uint8_t rejected_chains{0};
  std::array<ChannelCurrentSample, 6> channels{};
};
 
struct FaultReport {
  bool any_fault{false}; 
 
  // External Supply Faults (GLOBAL_DIAG0)
  bool vbat_uv{false}; 
  bool vbat_ov{false}; 
  bool vio_uv{false};  
  bool vio_ov{false};  
  bool vdd_uv{false};  
  bool vdd_ov{false};  
 
  // Internal Supply Faults (GLOBAL_DIAG1)
  bool vr_iref_uv{false}; 
  bool vr_iref_ov{false}; 
  bool vdd2v5_uv{false};  
  bool vdd2v5_ov{false};  
  bool ref_uv{false};     
  bool ref_ov{false};     
  bool vpre_ov{false};    
  bool hvadc_err{false};  
 
  // System Faults (GLOBAL_DIAG0)
  bool clock_fault{false};  
  bool spi_wd_error{false}; 
 
  // Temperature Faults (GLOBAL_DIAG0)
  bool ot_error{false};   
  bool ot_warning{false}; 
 
  // Reset Events (GLOBAL_DIAG0)
  bool por_event{false};   
  bool reset_event{false}; 
 
  // Memory/ECC Faults (GLOBAL_DIAG2)
  bool reg_ecc_err{false}; 
  bool otp_ecc_err{false}; 
  bool otp_virgin{false};  
 
  // Channel-specific faults (per channel)
  struct ChannelFaults {
    bool has_fault{false};                  
    bool overcurrent{false};                
    bool short_to_ground{false};            
    bool open_load{false};                  
    bool over_temperature{false};           
    bool open_load_short_ground{false};     
    bool ot_warning{false};                 
    bool current_regulation_warning{false}; 
    bool pwm_regulation_warning{false};     
    bool olsg_warning{false};               
  };
 
  std::array<ChannelFaults, 6> channels{}; 
 
  // Summary flags from FB_STAT
  bool supply_nok_internal{false}; 
  bool supply_nok_external{false}; 
};
 
struct GlobalConfig {
  bool crc_enabled{false};            
  bool spi_watchdog_enabled{false};   
  bool clock_watchdog_enabled{true};  
  bool vio_5v{false};                 
  float vbat_uv_voltage{7.0F};        
  float vbat_ov_voltage{40.0F};       
  uint16_t spi_watchdog_reload{1000}; 
};
 
template <typename CommType>
class Driver {
public:
  explicit Driver(CommType& comm) noexcept
      : comm_(comm) {}
 
  ~Driver() noexcept {
    if (initialized_) {
      // Best effort shutdown - ignore errors
      (void)DisableAllChannels();
    }
  }
 
  // Prevent copying
  Driver(const Driver&) = delete;
  Driver& operator=(const Driver&) = delete;
 
  // Delete move operations (contains reference member)
  Driver(Driver&&) noexcept = delete;
  Driver& operator=(Driver&&) noexcept = delete;
 
  //==========================================================================
  // INITIALIZATION AND MODE CONTROL
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> Init(bool perform_hardware_reset = true) noexcept;
 
  [[nodiscard]] DriverResult<void> EnterMissionMode() noexcept;
 
  [[nodiscard]] DriverResult<void> EnterConfigMode() noexcept;
 
  [[nodiscard]] bool IsMissionMode() const noexcept {
    return mission_mode_;
  }
 
  [[nodiscard]] bool IsConfigMode() const noexcept {
    return !mission_mode_;
  }
 
  //==========================================================================
  // GLOBAL CONFIGURATION
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> ConfigureGlobal(const GlobalConfig& config) noexcept;
 
  [[nodiscard]] DriverResult<void> SetCrcEnabled(bool enabled) noexcept;
 
  [[nodiscard]] DriverResult<void> SetVbatThresholds(float uv_voltage, float ov_voltage) noexcept;
 
  [[nodiscard]] DriverResult<void> SetVbatThresholdsRaw(uint8_t uv_threshold,
                                                        uint8_t ov_threshold) noexcept;
 
  //==========================================================================
  // CHANNEL CONTROL
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> EnableChannel(Channel channel, bool enabled) noexcept;
 
  [[nodiscard]] DriverResult<void> EnableChannels(uint8_t channel_mask) noexcept;
 
  [[nodiscard]] DriverResult<void> EnableAllChannels() noexcept;
 
  [[nodiscard]] DriverResult<void> DisableAllChannels() noexcept;
 
  [[nodiscard]] DriverResult<void> SetChannelMode(Channel channel, ChannelMode mode) noexcept;
 
  [[nodiscard]] DriverResult<void> SetParallelOperation(ParallelPair pair, bool enabled) noexcept;
 
  //==========================================================================
  // CURRENT CONTROL (ICC MODE)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> SetCurrentSetpoint(Channel channel, uint16_t current_ma,
                                                      bool parallel_mode = false) noexcept;
 
  [[nodiscard]] DriverResult<void> SetCurrentSetpointUa(Channel channel, uint32_t current_ua,
                                                        bool parallel_mode = false) noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetCurrentSetpoint(Channel channel,
                                                          bool parallel_mode = false) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigurePwmPeriod(Channel channel, float period_us) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigurePwmPeriodRaw(Channel channel, uint8_t period_mantissa,
                                                         uint8_t period_exponent,
                                                         bool low_freq_range = false) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigureDither(Channel channel, float amplitude_ma,
                                                   float frequency_hz,
                                                   bool parallel_mode = false) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigureDitherRaw(Channel channel, uint16_t step_size,
                                                      uint8_t num_steps,
                                                      uint8_t flat_steps) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigureDitherClock(
      Channel channel,
      float t_ref_clk_us,
      bool dither_pwm_sync = false,
      bool dither_setpoint_sync = false) noexcept;
 
  [[nodiscard]] DriverResult<void> ConfigureChannel(Channel channel,
                                                    const ChannelConfig& config) noexcept;
 
  //==========================================================================
  // STATUS AND DIAGNOSTICS
  //==========================================================================
 
  [[nodiscard]] DriverResult<DeviceStatus> GetDeviceStatus() noexcept;
 
  [[nodiscard]] DriverResult<ChannelDiagnostics> GetChannelDiagnostics(Channel channel) noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetAverageCurrent(Channel channel,
                                                         bool parallel_mode = false) noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetDutyCycle(Channel channel) noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetVbatVoltage() noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetVioVoltage() noexcept;
 
  [[nodiscard]] DriverResult<uint16_t> GetVddVoltage() noexcept;
 
  [[nodiscard]] DriverResult<void> GetVbatThresholds(uint16_t& uv_threshold,
                                                     uint16_t& ov_threshold) noexcept;
 
  //==========================================================================
  // FAULT MANAGEMENT
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> ClearFaults() noexcept;
 
  [[nodiscard]] DriverResult<bool> HasAnyFault() noexcept;
 
  [[nodiscard]] DriverResult<FaultReport> GetAllFaults() noexcept;
 
  [[nodiscard]] DriverResult<void> PrintAllFaults() noexcept;
 
  [[nodiscard]] DriverResult<void> SoftwareReset() noexcept;
 
  //==========================================================================
  // WATCHDOG MANAGEMENT
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> ReloadSpiWatchdog(uint16_t reload_value) noexcept;
 
  //==========================================================================
  // DEVICE INFORMATION
  //==========================================================================
 
  [[nodiscard]] DriverResult<uint16_t> GetIcVersion() noexcept;
 
  [[nodiscard]] DriverResult<std::array<uint16_t, 3>> GetChipId() noexcept;
 
  [[nodiscard]] DriverResult<bool> VerifyDevice() noexcept;
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  //==========================================================================
  // GPIO CONTROL (Reset, Enable, Fault Status)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> SetReset(bool reset) noexcept;
 
  [[nodiscard]] DriverResult<void> HoldReset() noexcept {
    return SetReset(true);
  }
 
  [[nodiscard]] DriverResult<void> ReleaseReset() noexcept {
    return SetReset(false);
  }
 
  [[nodiscard]] DriverResult<void> SetEnable(bool enable) noexcept;
 
  [[nodiscard]] DriverResult<void> Enable() noexcept {
    return SetEnable(true);
  }
 
  [[nodiscard]] DriverResult<void> Disable() noexcept {
    return SetEnable(false);
  }
 
  [[nodiscard]] DriverResult<bool> IsFault(bool print_faults = false) noexcept;
 
  //==========================================================================
  // PHASE 2 - CLOCK, POWER, STATE (D10, D29)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> ConfigureClockSource(ClockSource source,
                                                         uint32_t f_clk_Hz = 0) noexcept;
 
  [[nodiscard]] static constexpr uint32_t GetSystemClockHz() noexcept {
    return CLK_DIV::F_SYS_TARGET_HZ;
  }
 
  [[nodiscard]] DriverResult<SupplyVoltages> ReadAllSupplyVoltages() noexcept;
 
  [[nodiscard]] DriverResult<float> GetCentralTemperatureCelsius() noexcept;
 
  [[nodiscard]] DriverResult<void> SetVioLevel(VioLevel level) noexcept;
 
  [[nodiscard]] DriverResult<OperationState> GetOperationState() noexcept;
 
  [[nodiscard]] DriverResult<void> EnterMissionModeChecked(uint32_t timeout_ms = 10U) noexcept;
 
  [[nodiscard]] DriverResult<SupplyMonitorSelfTestResult>
  RunSupplyMonitorSelfTest() noexcept;
 
  //==========================================================================
  // PHASE 3 - ICC INTEGRATOR & THRESHOLD API (D11, D12, D13, D14, D16)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> SetIntegratorLimits(Channel channel,
                                                       uint16_t lim_value_abs,
                                                       uint8_t  auto_lim_value_abs) noexcept;
 
  [[nodiscard]] DriverResult<void> SetPwmControllerKi(Channel channel, uint8_t ki) noexcept;
 
  [[nodiscard]] DriverResult<void> SetMinIntegratorThreshold(Channel channel,
                                                             int8_t min_int_thresh) noexcept;
 
  [[nodiscard]] DriverResult<void> SetManualOnTimeMode(Channel channel,
                                                       float on_time_us) noexcept;
 
  [[nodiscard]] DriverResult<void> SeedIntegratorThresholdFromFeedback(Channel channel) noexcept;
 
  //==========================================================================
  // PHASE 4 - DITHER COMPLETENESS (D15, D18)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> SetDitherAdvanced(Channel channel,
                                                     const DitherSetup& setup,
                                                     bool parallel_mode = false) noexcept;
 
  //==========================================================================
  // PHASE 5 - DIAGNOSTICS COMPLETENESS (D17, D19, D20, D21, D22, D23)
  //==========================================================================
 
  [[nodiscard]] DriverResult<void> SetOlsgTimeout(Channel channel,
                                                  uint8_t olsg_timeout_code) noexcept;
 
  [[nodiscard]] DriverResult<void> SetOffStateDiagnostics(Channel channel,
                                                          bool oc_diag_enabled,
                                                          uint8_t ol_th_fixed) noexcept;
 
  [[nodiscard]] DriverResult<BistResult> RunSffBist(uint32_t timeout_ms = 10U) noexcept;
 
  [[nodiscard]] DriverResult<PinStatus> ReadPinStatus() noexcept;
 
  [[nodiscard]] DriverResult<void> SetFaultMask(MaskableFault fault, bool enable) noexcept;
 
  //==========================================================================
  // PHASE 6 - ATOMIC FEEDBACK READOUT (D24, D27, D28)
  //==========================================================================
 
  [[nodiscard]] DriverResult<ChannelFeedback> ReadChannelFeedback(Channel channel,
                                                                  uint32_t timeout_ms = 10U) noexcept;
 
  [[nodiscard]] DriverResult<std::array<ChannelFeedback, 6>>
  ReadAllChannelFeedback(uint32_t timeout_ms = 20U) noexcept;
 
  [[nodiscard]] DriverResult<int32_t>
  GetCalibrationAvgCurrent_mA(Channel channel) noexcept;
 
  //==========================================================================
  // BATCHED NON-BLOCKING FEEDBACK (real-time control path)
  //==========================================================================
 
  [[nodiscard]] DriverResult<uint8_t> GetFeedbackUpdateMask() noexcept;
 
  [[nodiscard]] DriverResult<void> FreezeFeedback(uint8_t channel_mask) noexcept;
 
  [[nodiscard]] DriverResult<void> ReleaseFeedbackFreeze() noexcept;
 
  [[nodiscard]] DriverResult<CurrentFeedbackBatch>
  SampleChannelCurrents(uint8_t channel_mask) noexcept;
 
  [[nodiscard]] DriverResult<void>
  ReadAllChannelErrorFlags(std::array<ChannelErrorFlags, 6>& out) noexcept;
 
  [[nodiscard]] DriverResult<bool> IsMeasurementClockRunning(Channel channel) noexcept;
 
  [[nodiscard]] DriverResult<bool> EnsureDitherRunning(Channel channel,
                                                       float amplitude_ma,
                                                       float frequency_hz,
                                                       uint8_t max_attempts = 3U) noexcept;
 
  [[nodiscard]] uint16_t GetChannelControlShadow() const noexcept { return ch_ctrl_cache_; }
 
  [[nodiscard]] DriverResult<void> SetFaultContributionMask(uint8_t channel_mask) noexcept;
 
  //==========================================================================
  // REGISTER ACCESS (Advanced)
  //==========================================================================
 
  [[nodiscard]] DriverResult<uint32_t> ReadRegister(uint16_t address,
                                                    bool verify_crc = false) noexcept;
 
  [[nodiscard]] DriverResult<void> ReadRegisterMulti(std::span<const uint16_t> addresses,
                                                     std::span<uint32_t> values,
                                                     uint16_t& valid_mask) noexcept;
 
  [[nodiscard]] DriverResult<void> WriteRegister(uint16_t address, uint16_t value,
                                                 bool verify_crc = false,
                                                 bool verify_write = true) noexcept;
 
  [[nodiscard]] DriverResult<void> ModifyRegister(uint16_t address, uint16_t mask,
                                                  uint16_t value) noexcept;
 
  // ===========================================================================
  // Driver Version
  // ===========================================================================
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_TLE92466ED_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_TLE92466ED_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_TLE92466ED_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_TLE92466ED_VERSION_PATCH;
  }
 
private:
  //==========================================================================
  // PRIVATE METHODS
  //==========================================================================
 
  [[nodiscard]] DriverResult<SPIFrame> transferFrame(const SPIFrame& tx_frame,
                                                     bool verify_crc = true) noexcept;
 
  [[nodiscard]] constexpr bool isValidChannelInternal(Channel channel) const noexcept {
    return IsValidChannel(channel);
  }
 
  [[nodiscard]] DriverResult<void> checkInitialized() const noexcept {
    if (!initialized_) {
      return tle::unexpected(DriverError::NotInitialized);
    }
    return {};
  }
 
  [[nodiscard]] DriverResult<void> checkMissionMode() const noexcept {
    if (!mission_mode_) {
      return tle::unexpected(DriverError::WrongMode);
    }
    return {};
  }
 
  [[nodiscard]] DriverResult<void> checkConfigMode() const noexcept {
    if (mission_mode_) {
      return tle::unexpected(DriverError::WrongMode);
    }
    return {};
  }
 
  [[nodiscard]] DriverResult<void> applyDefaultConfig() noexcept;
 
  [[nodiscard]] DriverResult<void> clearFaultsInternal() noexcept;
 
  [[nodiscard]] DriverResult<void> setVbatThresholdsInternal(float uv_voltage,
                                                             float ov_voltage) noexcept;
 
  [[nodiscard]] DriverResult<void> checkSpiStatus(const SPIFrame& rx_frame) noexcept;
 
  [[nodiscard]] DriverResult<bool> isChannelParallel(Channel channel) noexcept;
 
  [[nodiscard]] DriverResult<bool> isSlaveChannel(Channel channel) noexcept;
 
  void diagnoseClockConfiguration() noexcept;
 
  //==========================================================================
  // MEMBER VARIABLES
  //==========================================================================
 
  CommType& comm_;         
  bool initialized_{false};       
  bool mission_mode_{false};      
  bool crc_enabled_{false};       
  bool vio_5v_mode_{false};       
  uint16_t ch_ctrl_cache_{0U}; 
  uint16_t channel_enable_cache_{0U};             
  uint16_t cached_icvid_{0U}; 
  std::array<uint16_t, 6> channel_setpoints_; 
};
 
// Include template implementation (must be inside namespace before it closes)
#define TLE92466ED_HEADER_INCLUDED
// NOLINTNEXTLINE(bugprone-suspicious-include) - Intentional: template implementation file
#include "../src/tle92466ed.ipp"
#undef TLE92466ED_HEADER_INCLUDED
 
// Public API: Get driver version string
inline const char* GetDriverVersion() noexcept {
  return HF_TLE92466ED_VERSION_STRING;
}
 
} // namespace tle92466ed