EspTypes_PWM.h

Go to the documentation of this file.

 
#pragma once
 
#include "../../../base/BasePwm.h"       // For hf_pwm_err_t
#include "../../../base/HardwareTypes.h" // For basic hardware types
#include "../../../utils/McuSelect.h"    // Central MCU platform selection (includes all ESP-IDF)
#include "EspTypes_Base.h"
#include "EspTypes_GPIO.h" // For hf_gpio_num_t
 
//==============================================================================
// ESP32 PWM TYPE MAPPINGS
//==============================================================================
 
// Direct ESP-IDF type usage - no unnecessary aliases
// These types are used internally by EspPwm implementation
 
//==============================================================================
// ESP32 PWM CONSTANTS
//==============================================================================
 
// Number of LEDC channels depends on the MCU variant. For ESP32-C6, there are 6.
// Use centralized selection from McuSelect.h when available.
#ifdef HF_MCU_PWM_MAX_CHANNELS
static constexpr uint8_t HF_PWM_MAX_CHANNELS = HF_MCU_PWM_MAX_CHANNELS;
#else
static constexpr uint8_t HF_PWM_MAX_CHANNELS = 8;
#endif
static constexpr uint8_t HF_PWM_MAX_TIMERS = 4;
static constexpr uint8_t HF_PWM_MAX_RESOLUTION = 14;
static constexpr uint32_t HF_PWM_MIN_FREQUENCY =
    100; // ESP32-C6 LEDC practical minimum with 10-bit resolution
static constexpr uint32_t HF_PWM_MAX_FREQUENCY = 20000000; // ESP32-C6 LEDC practical maximum
static constexpr uint32_t HF_PWM_DEFAULT_FREQUENCY = 1000;
static constexpr uint8_t HF_PWM_DEFAULT_RESOLUTION = 10;
static constexpr uint32_t HF_PWM_APB_CLOCK_HZ = 80000000;
 
//==============================================================================
// ESP32 PWM ENUMS
//==============================================================================
 
enum class hf_pwm_clock_source_t : uint8_t {
  HF_PWM_CLK_SRC_DEFAULT = 0, 
  HF_PWM_CLK_SRC_APB = 1,     
  HF_PWM_CLK_SRC_XTAL = 2,    
  HF_PWM_CLK_SRC_RC_FAST = 3  
};
 
enum class hf_pwm_resolution_t : uint8_t {
  HF_PWM_RES_8BIT = 8,   
  HF_PWM_RES_10BIT = 10, 
  HF_PWM_RES_12BIT = 12, 
  HF_PWM_RES_14BIT = 14  
};
 
enum class hf_pwm_mode_t : uint8_t {
  HF_PWM_MODE_BASIC = 0, 
  HF_PWM_MODE_FADE = 1   
};
 
enum class hf_pwm_fade_mode_t : uint8_t {
  HF_PWM_FADE_NO_WAIT = 0,  
  HF_PWM_FADE_WAIT_DONE = 1 
};
 
enum class hf_pwm_intr_type_t : uint8_t {
  HF_PWM_INTR_DISABLE = 0, 
  HF_PWM_INTR_FADE_END = 1 
};
 
enum class hf_pwm_eviction_policy_t : uint8_t {
  STRICT_NO_EVICTION = 0,          
  ALLOW_EVICTION_WITH_CONSENT = 1, 
  ALLOW_EVICTION_NON_CRITICAL = 2, 
  FORCE_EVICTION = 3               
};
 
enum class hf_pwm_channel_priority_t : uint8_t {
  PRIORITY_LOW = 0,     
  PRIORITY_NORMAL = 1,  
  PRIORITY_HIGH = 2,    
  PRIORITY_CRITICAL = 3 
};
 
struct hf_pwm_eviction_request_t {
  hf_channel_id_t affected_channel;   
  hf_u8_t current_timer;              
  hf_u32_t current_frequency;         
  hf_u8_t current_resolution;         
  hf_u32_t requested_frequency;       
  hf_u8_t requested_resolution;       
  hf_channel_id_t requesting_channel; 
 
  hf_pwm_eviction_request_t() noexcept
      : affected_channel(0), current_timer(0), current_frequency(0), current_resolution(0),
        requested_frequency(0), requested_resolution(0), requesting_channel(0) {}
};
 
enum class hf_pwm_eviction_decision_t : uint8_t {
  DENY_EVICTION = 0,      
  ALLOW_EVICTION = 1,     
  SUGGEST_ALTERNATIVE = 2 
};
 
// Forward declarations for callback types
using hf_pwm_eviction_callback_t =
    hf_pwm_eviction_decision_t (*)(const hf_pwm_eviction_request_t& request, void* user_data);
 
struct hf_pwm_unit_config_t {
  uint8_t unit_id;                    
  hf_pwm_mode_t mode;                 
  uint32_t base_clock_hz;             
  hf_pwm_clock_source_t clock_source; 
  bool enable_fade;                   
  bool enable_interrupts;             
 
  hf_pwm_unit_config_t() noexcept
      : unit_id(0), mode(hf_pwm_mode_t::HF_PWM_MODE_BASIC), base_clock_hz(HF_PWM_APB_CLOCK_HZ),
        clock_source(hf_pwm_clock_source_t::HF_PWM_CLK_SRC_DEFAULT), enable_fade(true),
        enable_interrupts(false) {}
};
 
struct hf_pwm_channel_status_t {
  bool enabled;                        
  bool configured;                     
  float current_duty_cycle;            
  hf_frequency_hz_t current_frequency; 
  uint8_t resolution_bits;             
  uint32_t raw_duty_value;             
  bool fade_active;                    
  hf_pwm_err_t last_error;             
 
  hf_pwm_channel_status_t() noexcept
      : enabled(false), configured(false), current_duty_cycle(0.0f), current_frequency(0),
        resolution_bits(0), raw_duty_value(0), fade_active(false),
        last_error(hf_pwm_err_t::PWM_SUCCESS) {}
};
 
//==============================================================================
// ESP32 PWM CONFIGURATION STRUCTURES
//==============================================================================
 
struct hf_pwm_timing_config_t {
  uint32_t frequency_hz;         
  uint8_t resolution_bits;       
  hf_pwm_clock_source_t clk_src; 
  uint32_t clk_divider;          
 
  // Calculated timing parameters
  uint32_t actual_frequency_hz; 
  float frequency_accuracy;     
  uint32_t period_ticks;        
  uint32_t max_duty_ticks;      
 
  hf_pwm_timing_config_t() noexcept
      : frequency_hz(HF_PWM_DEFAULT_FREQUENCY), resolution_bits(HF_PWM_DEFAULT_RESOLUTION),
        clk_src(hf_pwm_clock_source_t::HF_PWM_CLK_SRC_DEFAULT), clk_divider(0),
        actual_frequency_hz(0), frequency_accuracy(0.0f), period_ticks(0), max_duty_ticks(0) {}
};
 
struct hf_pwm_channel_config_t {
  hf_gpio_num_t gpio_pin;   
  uint8_t channel_id;       
  uint8_t timer_id;         
  hf_pwm_mode_t speed_mode; 
 
  // Explicit frequency and resolution control
  uint32_t frequency_hz;              
  uint8_t resolution_bits;            
  hf_pwm_clock_source_t clock_source; 
 
  uint32_t duty_initial;        
  hf_pwm_intr_type_t intr_type; 
  bool invert_output;           
 
  // Advanced LEDC features
  uint32_t hpoint;    
  uint8_t idle_level; 
  bool output_invert; 
 
  // Resource protection and management
  hf_pwm_channel_priority_t priority; 
  bool is_critical;                   
  const char* description;            
 
  hf_pwm_channel_config_t() noexcept
      : gpio_pin(static_cast<hf_gpio_num_t>(HF_INVALID_PIN)), channel_id(0), timer_id(0),
        speed_mode(hf_pwm_mode_t::HF_PWM_MODE_BASIC), frequency_hz(HF_PWM_DEFAULT_FREQUENCY),
        resolution_bits(HF_PWM_DEFAULT_RESOLUTION),
        clock_source(hf_pwm_clock_source_t::HF_PWM_CLK_SRC_APB), duty_initial(0),
        intr_type(hf_pwm_intr_type_t::HF_PWM_INTR_DISABLE), invert_output(false), hpoint(0),
        idle_level(0), output_invert(false), priority(hf_pwm_channel_priority_t::PRIORITY_NORMAL),
        is_critical(false), description(nullptr) {}
};
 
struct hf_pwm_fade_config_t {
  uint32_t target_duty;         
  uint32_t fade_time_ms;        
  hf_pwm_fade_mode_t fade_mode; 
  uint32_t scale;               
  uint32_t cycle_num;           
 
  hf_pwm_fade_config_t() noexcept
      : target_duty(0), fade_time_ms(1000), fade_mode(hf_pwm_fade_mode_t::HF_PWM_FADE_NO_WAIT),
        scale(0), cycle_num(0) {}
};
 
struct hf_pwm_capabilities_t {
  uint8_t num_channels;            
  uint8_t num_timers;              
  uint8_t max_resolution_bits;     
  uint32_t max_frequency_hz;       
  uint32_t min_frequency_hz;       
  bool supports_fade;              
  bool supports_sleep_retention;   
  bool supports_complementary;     
  bool supports_deadtime;          
  bool supports_phase_shift;       
  uint8_t available_clock_sources; 
 
  // Constructor with ESP32 defaults
  hf_pwm_capabilities_t() noexcept
      : num_channels(HF_PWM_MAX_CHANNELS), num_timers(HF_PWM_MAX_TIMERS),
        max_resolution_bits(HF_PWM_MAX_RESOLUTION), max_frequency_hz(HF_PWM_MAX_FREQUENCY),
        min_frequency_hz(HF_PWM_MIN_FREQUENCY), supports_fade(true), supports_sleep_retention(true),
        supports_complementary(true), supports_deadtime(true), supports_phase_shift(false),
        available_clock_sources(4) {}
};
 
//==============================================================================
// END OF ESPPWM TYPES - MINIMAL AND ESSENTIAL ONLY
//==============================================================================