BasePwm.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC PWM Error Codes (Table)
//--------------------------------------
 
#define HF_PWM_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(PWM_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(PWM_ERR_FAILURE, 1, "General failure")                                                         \
  X(PWM_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(PWM_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(PWM_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(PWM_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(PWM_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Channel errors */                                                                             \
  X(PWM_ERR_INVALID_CHANNEL, 7, "Invalid PWM channel")                                             \
  X(PWM_ERR_CHANNEL_BUSY, 8, "Channel already in use")                                             \
  X(PWM_ERR_CHANNEL_NOT_AVAILABLE, 9, "Channel not available")                                     \
  X(PWM_ERR_INSUFFICIENT_CHANNELS, 10, "Insufficient channels available")                          \
  /* Frequency/timing errors */                                                                    \
  X(PWM_ERR_INVALID_FREQUENCY, 11, "Invalid frequency")                                            \
  X(PWM_ERR_FREQUENCY_TOO_HIGH, 12, "Frequency too high")                                          \
  X(PWM_ERR_FREQUENCY_TOO_LOW, 13, "Frequency too low")                                            \
  X(PWM_ERR_RESOLUTION_NOT_SUPPORTED, 14, "Resolution not supported")                              \
  /* Duty cycle errors */                                                                          \
  X(PWM_ERR_INVALID_DUTY_CYCLE, 15, "Invalid duty cycle")                                          \
  X(PWM_ERR_DUTY_OUT_OF_RANGE, 16, "Duty cycle out of range")                                      \
  /* Hardware errors */                                                                            \
  X(PWM_ERR_HARDWARE_FAULT, 17, "Hardware fault")                                                  \
  X(PWM_ERR_TIMER_CONFLICT, 18, "Timer resource conflict")                                         \
  X(PWM_ERR_PIN_CONFLICT, 19, "Pin already in use")                                                \
  /* Communication errors (for external PWM ICs) */                                                \
  X(PWM_ERR_COMMUNICATION_TIMEOUT, 20, "Communication timeout")                                    \
  X(PWM_ERR_COMMUNICATION_FAILURE, 21, "Communication failure")                                    \
  X(PWM_ERR_DEVICE_NOT_RESPONDING, 22, "Device not responding")                                    \
  X(PWM_ERR_INVALID_DEVICE_ID, 23, "Invalid device ID")                                            \
  X(PWM_ERR_UNSUPPORTED_OPERATION, 24, "Unsupported operation")                                    \
  X(PWM_ERR_UNKNOWN, 25, "Unknown error")
 
// Generate enum class
enum class hf_pwm_err_t : hf_u32_t {
#define X(name, value, description) name = value,
  HF_PWM_ERR_LIST(X)
#undef X
      PWM_ERR_COUNT // Total number of error codes
};
 
constexpr std::string_view HfPwmErrToString(hf_pwm_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_pwm_err_t::NAME:                                                                         \
    return DESC;
    HF_PWM_ERR_LIST(X)
#undef X
  default:
    return HfPwmErrToString(hf_pwm_err_t::PWM_ERR_UNKNOWN);
  }
}
 
//--------------------------------------
//  PWM Configuration Structures
//--------------------------------------
 
struct hf_pwm_statistics_t {
  hf_u32_t duty_updates_count;       
  hf_u32_t frequency_changes_count;  
  hf_u32_t fade_operations_count;    
  hf_u32_t error_count;              
  hf_u32_t channel_enables_count;    
  hf_u32_t channel_disables_count;   
  hf_u64_t last_activity_timestamp;  
  hf_u64_t initialization_timestamp; 
 
  hf_pwm_statistics_t() noexcept
      : duty_updates_count(0), frequency_changes_count(0), fade_operations_count(0), error_count(0),
        channel_enables_count(0), channel_disables_count(0), last_activity_timestamp(0),
        initialization_timestamp(0) {}
};
 
struct hf_pwm_diagnostics_t {
  bool hardware_initialized;      
  bool fade_functionality_ready;  
  hf_u8_t active_channels;        
  hf_u8_t active_timers;          
  hf_u32_t system_uptime_ms;      
  hf_pwm_err_t last_global_error; 
 
  hf_pwm_diagnostics_t() noexcept
      : hardware_initialized(false), fade_functionality_ready(false), active_channels(0),
        active_timers(0), system_uptime_ms(0), last_global_error(hf_pwm_err_t::PWM_SUCCESS) {}
};
 
//--------------------------------------
//  Callback Types
//--------------------------------------
 
using hf_pwm_period_callback_t = void (*)(hf_channel_id_t channel_id, void* user_data);
 
using hf_pwm_fault_callback_t =
    void (*)(hf_channel_id_t channel_id, hf_pwm_err_t error, void* user_data);
 
//--------------------------------------
//  Abstract Base Class
//--------------------------------------
 
class BasePwm {
public:
  //==============================================================================
  // LIFECYCLE
  //==============================================================================
 
  virtual ~BasePwm() noexcept = default;
 
  virtual hf_pwm_err_t Initialize() noexcept = 0;
 
  virtual hf_pwm_err_t Deinitialize() noexcept = 0;
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  bool EnsureInitialized() noexcept {
    if (!initialized_) {
      initialized_ = (Initialize() == hf_pwm_err_t::PWM_SUCCESS);
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() noexcept {
    if (initialized_) {
      initialized_ = !(Deinitialize() == hf_pwm_err_t::PWM_SUCCESS);
      return !initialized_;
    }
    return true;
  }
  //==============================================================================
  // CHANNEL MANAGEMENT
  //==============================================================================
 
  virtual hf_pwm_err_t EnableChannel(hf_channel_id_t channel_id) noexcept = 0;
 
  virtual hf_pwm_err_t DisableChannel(hf_channel_id_t channel_id) noexcept = 0;
 
  virtual bool IsChannelEnabled(hf_channel_id_t channel_id) const noexcept = 0;
 
  //==============================================================================
  // PWM CONTROL
  //==============================================================================
 
  virtual hf_pwm_err_t SetDutyCycle(hf_channel_id_t channel_id, float duty_cycle) noexcept = 0;
 
  virtual hf_pwm_err_t SetDutyCycleRaw(hf_channel_id_t channel_id, hf_u32_t raw_value) noexcept = 0;
 
  virtual hf_pwm_err_t SetFrequency(hf_channel_id_t channel_id,
                                    hf_frequency_hz_t frequency_hz) noexcept = 0;
 
  virtual hf_pwm_err_t SetPhaseShift(hf_channel_id_t channel_id,
                                     float phase_shift_degrees) noexcept = 0;
 
  //==============================================================================
  // ADVANCED FEATURES
  //==============================================================================
 
  virtual hf_pwm_err_t StartAll() noexcept = 0;
 
  virtual hf_pwm_err_t StopAll() noexcept = 0;
 
  virtual hf_pwm_err_t UpdateAll() noexcept = 0;
 
  virtual hf_pwm_err_t SetComplementaryOutput(hf_channel_id_t primary_channel,
                                              hf_channel_id_t complementary_channel,
                                              hf_u32_t deadtime_ns) noexcept = 0;
 
  //==============================================================================
  // STATUS AND INFORMATION
  //==============================================================================
 
  virtual float GetDutyCycle(hf_channel_id_t channel_id) const noexcept = 0;
 
  virtual hf_frequency_hz_t GetFrequency(hf_channel_id_t channel_id) const noexcept = 0;
 
  virtual hf_pwm_err_t GetStatistics(hf_pwm_statistics_t& statistics) const noexcept {
    statistics = statistics_; // Return statistics by default
    return hf_pwm_err_t::PWM_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pwm_err_t GetDiagnostics(hf_pwm_diagnostics_t& diagnostics) const noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_pwm_err_t::PWM_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pwm_err_t ResetStatistics() noexcept {
    statistics_ = hf_pwm_statistics_t{}; // Reset statistics to default values
    return hf_pwm_err_t::PWM_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pwm_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_pwm_diagnostics_t{}; // Reset diagnostics to default values
    return hf_pwm_err_t::PWM_ERR_UNSUPPORTED_OPERATION;
  }
 
  //==============================================================================
  // UTILITY FUNCTIONS
  //==============================================================================
 
  static constexpr hf_u32_t DutyCycleToRaw(float duty_cycle, hf_u8_t resolution_bits) noexcept {
    if (duty_cycle < 0.0f)
      duty_cycle = 0.0f;
    if (duty_cycle > 1.0f)
      duty_cycle = 1.0f;
    return static_cast<hf_u32_t>(duty_cycle * ((1U << resolution_bits) - 1));
  }
 
  static constexpr float RawToDutyCycle(hf_u32_t raw_value, hf_u8_t resolution_bits) noexcept {
    hf_u32_t max_value = (1U << resolution_bits) - 1;
    if (raw_value > max_value)
      raw_value = max_value;
    return static_cast<float>(raw_value) / static_cast<float>(max_value);
  }
 
  static constexpr bool IsValidDutyCycle(float duty_cycle) noexcept {
    return (duty_cycle >= 0.0f && duty_cycle <= 1.0f);
  }
 
  static constexpr bool IsValidFrequency(hf_u32_t frequency_hz, hf_u32_t min_freq_hz,
                                         hf_u32_t max_freq_hz) noexcept {
    return (frequency_hz >= min_freq_hz && frequency_hz <= max_freq_hz);
  }
 
  static constexpr bool IsValidRawDuty(hf_u32_t raw_value, hf_u8_t resolution_bits) noexcept {
    if (resolution_bits == 0 || resolution_bits > 16)
      return false;
    hf_u32_t max_value = (1U << resolution_bits) - 1;
    return (raw_value <= max_value);
  }
 
  static constexpr float CalculateFrequencyAccuracy(hf_u32_t target_freq,
                                                    hf_u32_t actual_freq) noexcept {
    if (target_freq == 0)
      return 0.0f;
    float diff = static_cast<float>(target_freq > actual_freq ? target_freq - actual_freq
                                                              : actual_freq - target_freq);
    return 1.0f - (diff / static_cast<float>(target_freq));
  }
 
  static constexpr float ClampDutyCycle(float duty_cycle) noexcept {
    if (duty_cycle < 0.0f)
      return 0.0f;
    if (duty_cycle > 1.0f)
      return 1.0f;
    return duty_cycle;
  }
 
protected:
  BasePwm() noexcept : initialized_(false), statistics_{}, diagnostics_{} {}
  BasePwm(const BasePwm&) = delete;
  BasePwm& operator=(const BasePwm&) = delete;
  BasePwm(BasePwm&&) = delete;
  BasePwm& operator=(BasePwm&&) = delete;
 
  bool initialized_;                 
  hf_pwm_statistics_t statistics_;   
  hf_pwm_diagnostics_t diagnostics_; 
};