PWM Component

Type-safe PWM controller for ESP32. More...

Modules
	Timer Constants
	Predefined timer identifiers.

Namespaces
namespace	idfxx
namespace	idfxx::pwm

Classes
class	idfxx::pwm::timer
	A lightweight identifier for a hardware PWM timer. More...
struct	idfxx::pwm::output_config
	Output configuration parameters. More...
class	idfxx::pwm::output
	An active PWM output binding a timer, channel, and GPIO pin. More...

Enumerations
enum class	idfxx::pwm::speed_mode : int { idfxx::pwm::speed_mode::low_speed = 0 }
	PWM speed mode selection. More...
enum class	idfxx::pwm::channel : int {   idfxx::pwm::channel::ch_0 = 0 ,   idfxx::pwm::channel::ch_1 ,   idfxx::pwm::channel::ch_2 ,   idfxx::pwm::channel::ch_3 ,   idfxx::pwm::channel::ch_4 ,   idfxx::pwm::channel::ch_5 }
	PWM channel slot identifiers. More...
enum class	idfxx::pwm::clk_source : int { idfxx::pwm::clk_source::auto_select = 0 }
	PWM timer clock source. More...
enum class	idfxx::pwm::fade_mode : int {   idfxx::pwm::fade_mode::no_wait = 0 ,   idfxx::pwm::fade_mode::wait_done }
	Fade operation blocking mode. More...
enum class	idfxx::pwm::sleep_mode : int {   idfxx::pwm::sleep_mode::no_alive_no_pd = 0 ,   idfxx::pwm::sleep_mode::no_alive_allow_pd ,   idfxx::pwm::sleep_mode::keep_alive }
	Channel behavior during light sleep. More...

Functions
output	idfxx::pwm::start (idfxx::gpio gpio, const timer &tmr, enum channel ch)
	Starts PWM output on a GPIO pin.
output	idfxx::pwm::start (idfxx::gpio gpio, const timer &tmr, enum channel ch, const output_config &cfg)
	Starts PWM output on a GPIO pin with custom configuration.
output	idfxx::pwm::start (idfxx::gpio gpio, const timer::config &cfg)
	Starts PWM output with automatic timer and channel allocation.
output	idfxx::pwm::start (idfxx::gpio gpio, const timer::config &cfg, const output_config &out_cfg)
	Starts PWM output with automatic allocation and custom output configuration.
void	idfxx::pwm::stop (enum channel ch, enum speed_mode mode=speed_mode::low_speed, idfxx::gpio::level idle_level=idfxx::gpio::level::low)
	Stops PWM output on a channel and sets it to an idle level.
result< output >	idfxx::pwm::try_start (idfxx::gpio gpio, const timer &tmr, enum channel ch)
	Starts PWM output on a GPIO pin.
result< output >	idfxx::pwm::try_start (idfxx::gpio gpio, const timer &tmr, enum channel ch, const output_config &cfg)
	Starts PWM output on a GPIO pin with custom configuration.
result< output >	idfxx::pwm::try_start (idfxx::gpio gpio, const timer::config &cfg)
	Starts PWM output with automatic timer and channel allocation.
result< output >	idfxx::pwm::try_start (idfxx::gpio gpio, const timer::config &cfg, const output_config &out_cfg)
	Starts PWM output with automatic allocation and custom output configuration.
bool	idfxx::pwm::is_active (enum channel ch, enum speed_mode mode=speed_mode::low_speed)
	Returns true if the specified channel currently has an active output.
std::optional< timer >	idfxx::pwm::get_timer (enum channel ch, enum speed_mode mode=speed_mode::low_speed)
	Returns the timer associated with an active channel, if any.
result< void >	idfxx::pwm::try_stop (enum channel ch, enum speed_mode mode=speed_mode::low_speed, idfxx::gpio::level idle_level=idfxx::gpio::level::low)
	Stops PWM output on a channel and sets it to an idle level.

Detailed Description

Type-safe PWM controller for ESP32.

Provides PWM output management with lightweight timer identifiers and RAII-managed output bindings. Timers are fixed hardware resources configured via methods; outputs bind a timer, channel, and GPIO pin into an active PWM signal with automatic cleanup on destruction.

Depends on Core Utilities for error handling, GPIO Component for pin identifiers, and Hardware Support Component for interrupt allocation types.

Enumeration Type Documentation

channel

enum class idfxx::pwm::channel : int

strong

PWM channel slot identifiers.

Selects the channel slot for PWM output. The number of available channels is target-dependent.

Enumerator
ch_0	Channel 0.
ch_1	Channel 1.
ch_2	Channel 2.
ch_3	Channel 3.
ch_4	Channel 4.
ch_5	Channel 5.

Definition at line 62 of file pwm.hpp.

clk_source

enum class idfxx::pwm::clk_source : int

strong

PWM timer clock source.

Selects the clock source for the timer. The default auto_select lets the driver choose the best source for the requested frequency.

Enumerator
auto_select	Automatic clock source selection.

Definition at line 84 of file pwm.hpp.

fade_mode

enum class idfxx::pwm::fade_mode : int

strong

Fade operation blocking mode.

Enumerator
no_wait	Return immediately, fade runs in background.
wait_done	Block until the fade completes.

Definition at line 104 of file pwm.hpp.

sleep_mode

enum class idfxx::pwm::sleep_mode : int

strong

Channel behavior during light sleep.

Enumerator
no_alive_no_pd	No output, keep power domain on (default)
no_alive_allow_pd	No output, allow power domain off (saves power)
keep_alive	Maintain PWM output during light sleep.

Definition at line 113 of file pwm.hpp.

speed_mode

enum class idfxx::pwm::speed_mode : int

strong

PWM speed mode selection.

Most targets only support low-speed mode. The original ESP32 also provides a high-speed mode with hardware-driven duty updates.

Enumerator
low_speed	Low-speed mode (available on all targets)

Definition at line 48 of file pwm.hpp.

Function Documentation

get_timer()

std::optional< timer > idfxx::pwm::get_timer	(	enum channel	ch,
		enum speed_mode	mode = speed_mode::low_speed
	)

Returns the timer associated with an active channel, if any.

Parameters

ch	Channel to check.
mode	Speed mode group (defaults to low_speed).

Returns

The timer bound to the channel, or std::nullopt if the channel is not active.

is_active()

bool idfxx::pwm::is_active	(	enum channel	ch,
		enum speed_mode	mode = speed_mode::low_speed
	)

Returns true if the specified channel currently has an active output.

Parameters

ch	Channel to check.
mode	Speed mode group (defaults to low_speed).

Returns

True if the channel has an active output.

start() [1/4]

output idfxx::pwm::start ( idfxx::gpio  gpio, const timer &  tmr, enum channel  ch  )

inline

Starts PWM output on a GPIO pin.

Configures the specified channel to output PWM on the given GPIO pin using the provided timer's frequency and resolution.

Parameters

gpio	GPIO pin for the output.
tmr	Configured timer to use. Must have been configured via timer::configure().
ch	Channel slot to use.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

using namespace frequency_literals;
using namespace std::chrono_literals;
 
auto tmr = idfxx::pwm::timer_0;
tmr.configure({.frequency = 5_kHz, .resolution_bits = 13});
 
auto pwm = idfxx::pwm::start(idfxx::gpio_18, tmr, idfxx::pwm::channel::ch_0);
pwm.set_duty(0.5f);  // 50% duty
 
// Fade to off over 1 second (requires fade service)
idfxx::pwm::output::install_fade_service();
pwm.fade_to(0.0f, 1s);

Definition at line 1176 of file pwm.hpp.

References idfxx::pwm::output::try_start, and idfxx::unwrap().

start() [2/4]

output idfxx::pwm::start ( idfxx::gpio  gpio, const timer &  tmr, enum channel  ch, const output_config &  cfg  )

inline

Starts PWM output on a GPIO pin with custom configuration.

Exceptions

std::system_error

on failure.

Definition at line 1179 of file pwm.hpp.

References idfxx::pwm::output::try_start, and idfxx::unwrap().

start() [3/4]

output idfxx::pwm::start ( idfxx::gpio  gpio, const timer::config &  cfg  )

inline

Starts PWM output with automatic timer and channel allocation.

Finds a timer already configured with matching parameters, or allocates and configures a new one. Then finds a free channel and starts PWM output. Only low-speed mode timers and channels are considered.

Parameters

gpio	GPIO pin for the output.
cfg	Timer configuration (frequency, resolution, clock source).

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

using namespace frequency_literals;
 
auto pwm = idfxx::pwm::start(idfxx::gpio_18, {.frequency = 5_kHz});
pwm.set_duty(0.5f);

Definition at line 1182 of file pwm.hpp.

References idfxx::pwm::output::try_start, and idfxx::unwrap().

start() [4/4]

output idfxx::pwm::start ( idfxx::gpio  gpio, const timer::config &  cfg, const output_config &  out_cfg  )

inline

Starts PWM output with automatic allocation and custom output configuration.

Exceptions

std::system_error

on failure.

Definition at line 1185 of file pwm.hpp.

References idfxx::pwm::output::try_start, and idfxx::unwrap().

stop()

void idfxx::pwm::stop ( enum channel  ch, enum speed_mode  mode = speed_mode::low_speed, idfxx::gpio::level  idle_level = idfxx::gpio::level::low  )

inline

Stops PWM output on a channel and sets it to an idle level.

Exceptions

std::system_error

on failure.

Definition at line 1188 of file pwm.hpp.

References idfxx::pwm::output::try_stop(), and idfxx::unwrap().

try_start() [1/4]

result< output > idfxx::pwm::try_start	(	idfxx::gpio	gpio,
		const timer &	tmr,
		enum channel	ch
	)

Starts PWM output on a GPIO pin.

Configures the specified channel to output PWM on the given GPIO pin using the provided timer's frequency and resolution.

Parameters

gpio	GPIO pin for the output.
tmr	Configured timer to use. Must have been configured via timer::configure().
ch	Channel slot to use.

Returns

The active output, or an error.

Return values

invalid_state	Timer not configured.
invalid_arg	GPIO not connected or invalid channel.

using namespace frequency_literals;
 
auto tmr = idfxx::pwm::timer_0;
tmr.configure({.frequency = 5_kHz, .resolution_bits = 13});
 
auto pwm = idfxx::pwm::try_start(idfxx::gpio_18, tmr, idfxx::pwm::channel::ch_0);
if (pwm) {
    pwm->try_set_duty(0.5f);
}

try_start() [2/4]

result< output > idfxx::pwm::try_start	(	idfxx::gpio	gpio,
		const timer &	tmr,
		enum channel	ch,
		const output_config &	cfg
	)

Starts PWM output on a GPIO pin with custom configuration.

Parameters

gpio	GPIO pin for the output.
tmr	Configured timer to use. Must have been configured via timer::configure().
ch	Channel slot to use.
cfg	Output configuration.

Returns

The active output, or an error.

Return values

invalid_state	Timer not configured.
invalid_arg	GPIO not connected or invalid channel.

try_start() [3/4]

result< output > idfxx::pwm::try_start	(	idfxx::gpio	gpio,
		const timer::config &	cfg
	)

Starts PWM output with automatic timer and channel allocation.

Finds a timer already configured with matching parameters, or allocates and configures a new one. Then finds a free channel and starts PWM output. Only low-speed mode timers and channels are considered.

Parameters

gpio	GPIO pin for the output.
cfg	Timer configuration (frequency, resolution, clock source).

Returns

The active output, or an error.

Return values

not_found	No free timer or channel available.
invalid_arg	GPIO not connected or invalid configuration.

using namespace frequency_literals;
 
auto pwm = idfxx::pwm::try_start(idfxx::gpio_18, {.frequency = 5_kHz});
if (pwm) {
    pwm->try_set_duty(0.5f);
}

try_start() [4/4]

result< output > idfxx::pwm::try_start	(	idfxx::gpio	gpio,
		const timer::config &	cfg,
		const output_config &	out_cfg
	)

Starts PWM output with automatic allocation and custom output configuration.

Parameters

gpio	GPIO pin for the output.
cfg	Timer configuration (frequency, resolution, clock source).
out_cfg	Output configuration (initial duty, hpoint, inversion, sleep mode).

Returns

The active output, or an error.

Return values

not_found	No free timer or channel available.
invalid_arg	GPIO not connected or invalid configuration.

try_stop()

result< void > idfxx::pwm::try_stop	(	enum channel	ch,
		enum speed_mode	mode = speed_mode::low_speed,
		idfxx::gpio::level	idle_level = idfxx::gpio::level::low
	)

Stops PWM output on a channel and sets it to an idle level.

Stops the channel regardless of whether an output object owns it. Any existing output for this channel will become inactive.

Parameters

ch	Channel to stop.
mode	Speed mode group (defaults to low_speed).
idle_level	Output level after stopping.

Returns

Success, or an error.