EspTypes_PWM.h File Reference

ESP32 PWM type definitions for LEDC peripheral hardware abstraction. More...

#include "../../../base/BasePwm.h"
#include "../../../base/HardwareTypes.h"
#include "../../../utils/McuSelect.h"
#include "EspTypes_Base.h"
#include "EspTypes_GPIO.h"

Include dependency graph for EspTypes_PWM.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	hf_pwm_eviction_request_t
	Eviction request information passed to user callback. More...
struct	hf_pwm_unit_config_t
	ESP32 PWM unit configuration. More...
struct	hf_pwm_channel_status_t
	PWM channel status information. More...
struct	hf_pwm_timing_config_t
	ESP32 PWM timing configuration with optimization support. More...
struct	hf_pwm_channel_config_t
	ESP32 PWM channel configuration with comprehensive LEDC feature support. More...
struct	hf_pwm_fade_config_t
	ESP32 PWM fade configuration for smooth transitions. More...
struct	hf_pwm_capabilities_t
	PWM capabilities and limitations for ESP32. More...

Typedefs
using	hf_pwm_eviction_callback_t
	Callback function for eviction consent.

Enumerations
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 }
	ESP32 PWM clock source selection with frequency and constraint details. More...
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 }
	ESP32 PWM resolution options. More...
enum class	hf_pwm_mode_t : uint8_t { HF_PWM_MODE_BASIC = 0 , HF_PWM_MODE_FADE = 1 }
	ESP32 PWM mode configuration. More...
enum class	hf_pwm_fade_mode_t : uint8_t { HF_PWM_FADE_NO_WAIT = 0 , HF_PWM_FADE_WAIT_DONE = 1 }
	ESP32 PWM fade mode configuration. More...
enum class	hf_pwm_intr_type_t : uint8_t { HF_PWM_INTR_DISABLE = 0 , HF_PWM_INTR_FADE_END = 1 }
	ESP32 PWM interrupt type configuration. More...
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 }
	Timer eviction policy for resource management. More...
enum class	hf_pwm_channel_priority_t : uint8_t { PRIORITY_LOW = 0 , PRIORITY_NORMAL = 1 , PRIORITY_HIGH = 2 , PRIORITY_CRITICAL = 3 }
	Channel priority levels for eviction decisions. More...
enum class	hf_pwm_eviction_decision_t : uint8_t { DENY_EVICTION = 0 , ALLOW_EVICTION = 1 , SUGGEST_ALTERNATIVE = 2 }
	Eviction decision from user callback. More...

Variables
static constexpr uint8_t	HF_PWM_MAX_CHANNELS = 8
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
static constexpr uint32_t	HF_PWM_MAX_FREQUENCY = 20000000
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

Detailed Description

ESP32 PWM type definitions for LEDC peripheral hardware abstraction.

This header defines essential PWM-specific types and constants for the EspPwm implementation, providing a clean abstraction over ESP-IDF LEDC peripheral capabilities across different ESP32 variants.

LEDC Peripheral Overview:

The LED Controller (LEDC) peripheral is designed to control the intensity of LEDs, but is also perfectly suited for general-purpose PWM generation. Key features:

• High Resolution: Up to 20-bit resolution on ESP32 classic, 14-bit on newer variants
• Multiple Clock Sources: APB, XTAL, RC_FAST with different frequency ranges
• Hardware Fade: Smooth transitions without CPU intervention
• Timer Sharing: Multiple channels can share timers for efficiency
• Low Power: Optimized for battery-powered applications

ESP32 Variant Differences:

Different ESP32 variants have different LEDC capabilities:

• Channels: 16 (ESP32), 8 (S2/S3), 6 (C3/C6), 4 (H2)
• Timers: 8 (ESP32), 4 (S2/S3/C3/C6), 2 (H2)
• Clock Sources: Variant-specific availability and constraints

Author

Nebiyu Tadesse

Date

2025

Copyright

HardFOC

Typedef Documentation

hf_pwm_eviction_callback_t

using hf_pwm_eviction_callback_t

Initial value:

 
    hf_pwm_eviction_decision_t (*)(const hf_pwm_eviction_request_t& request, void* user_data)

Callback function for eviction consent.

Parameters

request	Information about the eviction request
user_data	User-provided data

Returns

Decision on whether to allow eviction

Enumeration Type Documentation

hf_pwm_channel_priority_t

enum class hf_pwm_channel_priority_t : uint8_t

strong

Channel priority levels for eviction decisions.

Enumerator
PRIORITY_LOW	Low priority - can be evicted first.
PRIORITY_NORMAL	Normal priority - default.
PRIORITY_HIGH	High priority - protect from eviction.
PRIORITY_CRITICAL	Critical priority - never evict.

hf_pwm_clock_source_t

enum class hf_pwm_clock_source_t : uint8_t

strong

ESP32 PWM clock source selection with frequency and constraint details.

Clock source selection is critical for PWM performance and determines the maximum achievable frequency for a given resolution. The formula is: Max Frequency = Clock Source Frequency / (2^resolution_bits)

Clock Source Specifications:

APB_CLK (80MHz) - Recommended for most applications

• Frequency: 80MHz (stable, derived from main crystal)
• Stability: High (crystal-locked)
• Max PWM Freq: ~78kHz @ 10-bit, ~19.5kHz @ 12-bit, ~4.9kHz @ 14-bit
• Use Cases: Motor control, servo control, LED dimming, audio PWM

XTAL_CLK (40MHz) - Power-efficient option

• Frequency: 40MHz (main crystal oscillator)
• Stability: High (primary crystal)
• Max PWM Freq: ~39kHz @ 10-bit, ~9.8kHz @ 12-bit, ~2.4kHz @ 14-bit
• Use Cases: Low-frequency PWM, power-sensitive applications

RC_FAST_CLK (~17.5MHz) - Lowest power consumption

• Frequency: ~17.5MHz (internal RC oscillator)
• Stability: Moderate (temperature dependent)
• Max PWM Freq: ~17kHz @ 10-bit, ~4.3kHz @ 12-bit, ~1.1kHz @ 14-bit
• Use Cases: Low-power applications, simple LED control

Warning

ESP32 Variant Constraints:

• ESP32 Classic: Each timer can use different clock sources independently
• ESP32-S2/S3/C3/C6/H2: All timers typically share the same clock source
• Always verify your target variant's clock source flexibility before design

Enumerator
HF_PWM_CLK_SRC_DEFAULT	Default clock source (typically APB_CLK)
HF_PWM_CLK_SRC_APB	APB clock (80MHz) - recommended for most uses.
HF_PWM_CLK_SRC_XTAL	Crystal oscillator (40MHz) - power efficient.
HF_PWM_CLK_SRC_RC_FAST	RC fast clock (~17.5MHz) - lowest power.

hf_pwm_eviction_decision_t

enum class hf_pwm_eviction_decision_t : uint8_t

strong

Eviction decision from user callback.

Enumerator
DENY_EVICTION	Deny the eviction request.
ALLOW_EVICTION	Allow the eviction to proceed.
SUGGEST_ALTERNATIVE	Suggest alternative (not implemented yet)

hf_pwm_eviction_policy_t

enum class hf_pwm_eviction_policy_t : uint8_t

strong

Timer eviction policy for resource management.

Controls how the PWM system handles timer resource conflicts.

Enumerator
STRICT_NO_EVICTION	Never evict existing channels (default, safest)
ALLOW_EVICTION_WITH_CONSENT	Require callback approval before eviction.
ALLOW_EVICTION_NON_CRITICAL	Only evict channels marked as non-critical.
FORCE_EVICTION	Aggressive eviction (advanced users only)

hf_pwm_fade_mode_t

enum class hf_pwm_fade_mode_t : uint8_t

strong

ESP32 PWM fade mode configuration.

Enumerator
HF_PWM_FADE_NO_WAIT	Non-blocking fade.
HF_PWM_FADE_WAIT_DONE	Blocking fade.

hf_pwm_intr_type_t

enum class hf_pwm_intr_type_t : uint8_t

strong

ESP32 PWM interrupt type configuration.

Enumerator
HF_PWM_INTR_DISABLE	Disable interrupts.
HF_PWM_INTR_FADE_END	Fade end interrupt.

hf_pwm_mode_t

enum class hf_pwm_mode_t : uint8_t

strong

ESP32 PWM mode configuration.

Enumerator
HF_PWM_MODE_BASIC	Basic PWM mode.
HF_PWM_MODE_FADE	Fade mode with hardware fade support.

hf_pwm_resolution_t

enum class hf_pwm_resolution_t : uint8_t

strong

ESP32 PWM resolution options.

Enumerator
HF_PWM_RES_8BIT	8-bit resolution
HF_PWM_RES_10BIT	10-bit resolution
HF_PWM_RES_12BIT	12-bit resolution
HF_PWM_RES_14BIT	14-bit resolution

Variable Documentation

HF_PWM_APB_CLOCK_HZ

constexpr uint32_t HF_PWM_APB_CLOCK_HZ = 80000000

staticconstexpr

HF_PWM_DEFAULT_FREQUENCY

constexpr uint32_t HF_PWM_DEFAULT_FREQUENCY = 1000

staticconstexpr

HF_PWM_DEFAULT_RESOLUTION

constexpr uint8_t HF_PWM_DEFAULT_RESOLUTION = 10

staticconstexpr

HF_PWM_MAX_CHANNELS

constexpr uint8_t HF_PWM_MAX_CHANNELS = 8

staticconstexpr

HF_PWM_MAX_FREQUENCY

constexpr uint32_t HF_PWM_MAX_FREQUENCY = 20000000

staticconstexpr

HF_PWM_MAX_RESOLUTION

constexpr uint8_t HF_PWM_MAX_RESOLUTION = 14

staticconstexpr

HF_PWM_MAX_TIMERS

constexpr uint8_t HF_PWM_MAX_TIMERS = 4

staticconstexpr

HF_PWM_MIN_FREQUENCY

constexpr uint32_t HF_PWM_MIN_FREQUENCY

staticconstexpr

Initial value:

=
    100