An active PWM output binding a timer, channel, and GPIO pin. More...

Public Member Functions
	~output ()
	Destroys the output, stopping PWM on the bound GPIO.

	output (const output &)=delete

output &	operator= (const output &)=delete

	output (output &&other) noexcept

output &	operator= (output &&other) noexcept

class timer	timer () const noexcept
	Returns the timer that was bound to this output.

enum channel	channel () const noexcept
	Returns the channel slot that was bound to this output.

bool	is_active () const noexcept
	Returns true if the output is still actively driving the channel.

uint32_t	ticks_max () const noexcept
	Returns the maximum duty ticks for the configured resolution.

float	duty () const
	Returns the current duty cycle as a ratio.

uint32_t	duty_ticks () const
	Returns the current duty cycle in ticks.

void	set_duty (float duty)
	Sets the PWM duty cycle as a ratio.

result< void >	try_set_duty (float duty)
	Sets the PWM duty cycle as a ratio.

void	set_duty_ticks (uint32_t duty)
	Sets the PWM duty cycle in ticks.

void	set_duty_ticks (uint32_t duty, uint32_t hpoint)
	Sets the PWM duty cycle in ticks with high point.

result< void >	try_set_duty_ticks (uint32_t duty)
	Sets the PWM duty cycle in ticks.

result< void >	try_set_duty_ticks (uint32_t duty, uint32_t hpoint)
	Sets the PWM duty cycle in ticks with high point.

std::chrono::nanoseconds	pulse_width () const
	Returns the current pulse width as a duration.

template<typename Rep , typename Period >
void	set_pulse_width (const std::chrono::duration< Rep, Period > &width)
	Sets the PWM duty cycle as a pulse width duration.

template<typename Rep , typename Period >
result< void >	try_set_pulse_width (const std::chrono::duration< Rep, Period > &width)
	Sets the PWM duty cycle as a pulse width duration.

template<typename Rep , typename Period >
void	fade_to (float target, const std::chrono::duration< Rep, Period > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target duty ratio over the specified duration.

template<typename Rep , typename Period >
result< void >	try_fade_to (float target, const std::chrono::duration< Rep, Period > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target duty ratio over the specified duration.

template<typename Rep , typename Period >
void	fade_to_duty_ticks (uint32_t target_duty, const std::chrono::duration< Rep, Period > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target duty in ticks over the specified duration.

template<typename Rep , typename Period >
result< void >	try_fade_to_duty_ticks (uint32_t target_duty, const std::chrono::duration< Rep, Period > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target duty in ticks over the specified duration.

template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >
void	fade_to_pulse_width (const std::chrono::duration< Rep1, Period1 > &target_width, const std::chrono::duration< Rep2, Period2 > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target pulse width over the specified duration.

template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >
result< void >	try_fade_to_pulse_width (const std::chrono::duration< Rep1, Period1 > &target_width, const std::chrono::duration< Rep2, Period2 > &duration, enum fade_mode mode=fade_mode::no_wait)
	Fades to a target pulse width over the specified duration.

void	fade_with_step (uint32_t target_duty, uint32_t scale, uint32_t cycle_num, enum fade_mode mode=fade_mode::no_wait)
	Starts a fade to a target duty in ticks with step control.

result< void >	try_fade_with_step (uint32_t target_duty, uint32_t scale, uint32_t cycle_num, enum fade_mode mode=fade_mode::no_wait)
	Starts a fade to the target duty with step control.

void	register_fade_end_callback (std::move_only_function< bool() const > callback)
	Registers a callback for fade-end events.

result< void >	try_register_fade_end_callback (std::move_only_function< bool() const > callback)
	Registers a callback for fade-end events.

void	stop (idfxx::gpio::level idle_level=idfxx::gpio::level::low)
	Stops PWM output and sets the GPIO to an idle level.

result< void >	try_stop (idfxx::gpio::level idle_level=idfxx::gpio::level::low)
	Stops PWM output and sets the GPIO to an idle level.

enum channel	release () noexcept
	Releases ownership of the channel without stopping the PWM output.

Static Public Member Functions
static void	install_fade_service (idfxx::intr_levels levels=intr_level_lowmed, idfxx::flags< intr_flag > flags={})
	Installs the PWM fade service.

static result< void >	try_install_fade_service (idfxx::intr_levels levels=intr_level_lowmed, idfxx::flags< intr_flag > flags={})
	Installs the PWM fade service.

static void	uninstall_fade_service ()
	Uninstalls the PWM fade service.

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

result< output >	try_start (idfxx::gpio, const timer::config &, const output_config &)
	Starts PWM output with automatic allocation and custom output configuration.

Detailed Description

An active PWM output binding a timer, channel, and GPIO pin.

Represents a configured PWM output that is actively driving a GPIO pin with a PWM signal. This type is non-copyable and move-only. The destructor automatically stops the PWM output.

Create via start() or try_start(), which accept either a timer::config (for automatic timer and channel allocation) or an explicit timer and channel.

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

Definition at line 710 of file pwm.hpp.

Constructor & Destructor Documentation

◆ ~output()

idfxx::pwm::output::~output ( )

Destroys the output, stopping PWM on the bound GPIO.

Sets the output to idle low level.

◆ output() [1/2]

idfxx::pwm::output::output ( const output & )

delete

◆ output() [2/2]

idfxx::pwm::output::output ( output && other )

noexcept

Member Function Documentation

◆ channel()

enum channel idfxx::pwm::output::channel ( ) const

inlinenoexcept

Returns the channel slot that was bound to this output.

Note: This output may no longer be driving the channel.

Definition at line 736 of file pwm.hpp.

◆ duty()

float idfxx::pwm::output::duty ( ) const

Returns the current duty cycle as a ratio.

Returns: Duty ratio in range [0.0, 1.0].

Referenced by set_duty(), set_duty_ticks(), and set_duty_ticks().

◆ duty_ticks()

uint32_t idfxx::pwm::output::duty_ticks ( ) const

Returns the current duty cycle in ticks.

Returns the duty at the current point in the PWM cycle.

Returns: Current duty ticks.

◆ fade_to()

template<typename Rep , typename Period >

void idfxx::pwm::output::fade_to	(	float	target,
		const std::chrono::duration< Rep, Period > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target duty ratio over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

target	Duty ratio in range [0.0, 1.0].
duration	Fade duration.
mode	Whether to block until the fade completes.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 890 of file pwm.hpp.

References try_fade_to(), and idfxx::unwrap().

◆ fade_to_duty_ticks()

template<typename Rep , typename Period >

void idfxx::pwm::output::fade_to_duty_ticks	(	uint32_t	target_duty,
		const std::chrono::duration< Rep, Period > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target duty in ticks over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

target_duty	Duty in ticks, in range [0, ticks_max()].
duration	Fade duration.
mode	Whether to block until the fade completes.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 942 of file pwm.hpp.

References try_fade_to_duty_ticks(), and idfxx::unwrap().

◆ fade_to_pulse_width()

template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >

void idfxx::pwm::output::fade_to_pulse_width	(	const std::chrono::duration< Rep1, Period1 > &	target_width,
		const std::chrono::duration< Rep2, Period2 > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target pulse width over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep1	Target width representation type.
Period1	Target width period type.
Rep2	Duration representation type.
Period2	Duration period type.

Parameters

target_width	Target pulse width.
duration	Fade duration.
mode	Whether to block until the fade completes.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 992 of file pwm.hpp.

References try_fade_to_pulse_width(), and idfxx::unwrap().

◆ fade_with_step()

void idfxx::pwm::output::fade_with_step	(	uint32_t	target_duty,
		uint32_t	scale,
		uint32_t	cycle_num,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Starts a fade to a target duty in ticks with step control.

Requires the fade service to be installed via install_fade_service().

Parameters

target_duty	Duty in ticks, in range [0, ticks_max()].
scale	Duty change per step.
cycle_num	Number of PWM cycles per step.
mode	Whether to block until the fade completes.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 1045 of file pwm.hpp.

References try_fade_with_step(), and idfxx::unwrap().

◆ install_fade_service()

static void idfxx::pwm::output::install_fade_service	(	idfxx::intr_levels	levels = `intr_level_lowmed`,
		idfxx::flags< intr_flag >	flags = `{}`
	)

inlinestatic

Installs the PWM fade service.

Must be called before using any fade operations. This is a global service shared by all PWM channels.

Parameters

levels	Interrupt priority levels to accept.
flags	Behavioral flags.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 1257 of file pwm.hpp.

◆ is_active()

bool idfxx::pwm::output::is_active ( ) const

noexcept

Returns true if the output is still actively driving the channel.

◆ operator=() [1/2]

output & idfxx::pwm::output::operator= ( const output & )

delete

◆ operator=() [2/2]

output & idfxx::pwm::output::operator= ( output && other )

noexcept

◆ pulse_width()

std::chrono::nanoseconds idfxx::pwm::output::pulse_width ( ) const

Returns the current pulse width as a duration.

Returns: Current pulse width in nanoseconds.

◆ register_fade_end_callback()

void idfxx::pwm::output::register_fade_end_callback ( std::move_only_function< bool() const > callback )

inline

Registers a callback for fade-end events.

The callback runs in ISR context and should return true if a higher-priority task was woken. Any previously registered callback on this output is replaced. The callback is automatically unregistered when the output is destroyed.

Parameters

callback Fade-end callback.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 1202 of file pwm.hpp.

References try_register_fade_end_callback(), and idfxx::unwrap().

◆ release()

enum channel idfxx::pwm::output::release ( )

noexcept

Releases ownership of the channel without stopping the PWM output.

After calling release(), the PWM signal continues running and the destructor will not stop it. Use the free function stop() to later stop the channel.

Returns: The channel that was released.

◆ set_duty()

void idfxx::pwm::output::set_duty ( float duty )

inline

Sets the PWM duty cycle as a ratio.

Thread-safe. The new duty takes effect on the next PWM cycle.

Parameters

duty	Duty ratio in range [0.0, 1.0].

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 770 of file pwm.hpp.

References duty(), try_set_duty(), and idfxx::unwrap().

◆ set_duty_ticks() [1/2]

void idfxx::pwm::output::set_duty_ticks ( uint32_t duty )

inline

Sets the PWM duty cycle in ticks.

Thread-safe.

Parameters

duty	Duty in ticks, in range [0, ticks_max()].

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 796 of file pwm.hpp.

References duty(), try_set_duty_ticks(), and idfxx::unwrap().

◆ set_duty_ticks() [2/2]

void idfxx::pwm::output::set_duty_ticks	(	uint32_t	duty,
		uint32_t	hpoint
	)

inline

Sets the PWM duty cycle in ticks with high point.

Thread-safe.

Parameters

duty	Duty in ticks, in range [0, ticks_max()].
hpoint	High point in the PWM cycle.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 808 of file pwm.hpp.

References duty(), try_set_duty_ticks(), and idfxx::unwrap().

◆ set_pulse_width()

template<typename Rep , typename Period >

void idfxx::pwm::output::set_pulse_width ( const std::chrono::duration< Rep, Period > & width )

inline

Sets the PWM duty cycle as a pulse width duration.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

width Pulse width duration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

using namespace std::chrono_literals;

pwm.set_pulse_width(1500us); // 1.5 ms pulse width

Definition at line 855 of file pwm.hpp.

References try_set_pulse_width(), and idfxx::unwrap().

◆ stop()

void idfxx::pwm::output::stop ( idfxx::gpio::level idle_level = idfxx::gpio::level::low )

inline

Stops PWM output and sets the GPIO to an idle level.

Parameters

idle_level Output level after stopping.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 1292 of file pwm.hpp.

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

◆ ticks_max()

uint32_t idfxx::pwm::output::ticks_max ( ) const

noexcept

Returns the maximum duty ticks for the configured resolution.

Referenced by try_fade_to().

◆ timer()

class timer idfxx::pwm::output::timer ( ) const

inlinenoexcept

Returns the timer that was bound to this output.

Note: This output may no longer be driving the channel.

Definition at line 729 of file pwm.hpp.

◆ try_fade_to()

template<typename Rep , typename Period >

result< void > idfxx::pwm::output::try_fade_to	(	float	target,
		const std::chrono::duration< Rep, Period > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target duty ratio over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

target	Duty ratio in range [0.0, 1.0].
duration	Fade duration.
mode	Whether to block until the fade completes.

Returns: Success, or an error.

Return values

invalid_state	Output moved from or fade service not installed.
invalid_arg	Invalid parameters.

Definition at line 915 of file pwm.hpp.

References ticks_max().

Referenced by fade_to().

◆ try_fade_to_duty_ticks()

template<typename Rep , typename Period >

result< void > idfxx::pwm::output::try_fade_to_duty_ticks	(	uint32_t	target_duty,
		const std::chrono::duration< Rep, Period > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target duty in ticks over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

target_duty	Duty in ticks, in range [0, ticks_max()].
duration	Fade duration.
mode	Whether to block until the fade completes.

Returns: Success, or an error.

Return values

invalid_state	Output moved from or fade service not installed.
invalid_arg	Invalid parameters.

Definition at line 967 of file pwm.hpp.

Referenced by fade_to_duty_ticks().

◆ try_fade_to_pulse_width()

template<typename Rep1 , typename Period1 , typename Rep2 , typename Period2 >

result< void > idfxx::pwm::output::try_fade_to_pulse_width	(	const std::chrono::duration< Rep1, Period1 > &	target_width,
		const std::chrono::duration< Rep2, Period2 > &	duration,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

inline

Fades to a target pulse width over the specified duration.

Requires the fade service to be installed via install_fade_service().

Template Parameters

Rep1	Target width representation type.
Period1	Target width period type.
Rep2	Duration representation type.
Period2	Duration period type.

Parameters

target_width	Target pulse width.
duration	Fade duration.
mode	Whether to block until the fade completes.

Returns: Success, or an error.

Return values

invalid_state	Output moved from or fade service not installed.
invalid_arg	Invalid parameters.

Definition at line 1019 of file pwm.hpp.

Referenced by fade_to_pulse_width().

◆ try_fade_with_step()

result< void > idfxx::pwm::output::try_fade_with_step	(	uint32_t	target_duty,
		uint32_t	scale,
		uint32_t	cycle_num,
		enum fade_mode	mode = `fade_mode::no_wait`
	)

Starts a fade to the target duty with step control.

Requires the fade service to be installed via install_fade_service().

Parameters

target_duty	Target duty in ticks, in range [0, ticks_max()].
scale	Duty change per step.
cycle_num	Number of PWM cycles per step.
mode	Whether to block until the fade completes.

Returns: Success, or an error.

Return values

invalid_state	Output moved from or fade service not installed.
invalid_arg	Invalid parameters.

Referenced by fade_with_step().

◆ try_install_fade_service()

static result< void > idfxx::pwm::output::try_install_fade_service	(	idfxx::intr_levels	levels = `intr_level_lowmed`,
		idfxx::flags< intr_flag >	flags = `{}`
	)

static

Installs the PWM fade service.

Must be called before using any fade operations. This is a global service shared by all PWM channels.

Parameters

levels	Interrupt priority levels to accept.
flags	Behavioral flags.

Returns: Success, or an error.

Return values

invalid_state Fade service already installed.

◆ try_register_fade_end_callback()

result< void > idfxx::pwm::output::try_register_fade_end_callback ( std::move_only_function< bool() const > callback )

Registers a callback for fade-end events.

The callback runs in ISR context and should return true if a higher-priority task was woken. Any previously registered callback on this output is replaced. The callback is automatically unregistered when the output is destroyed.

Parameters

callback Fade-end callback.

Returns: Success, or an error.

Return values

invalid_state Output moved from or fade service not installed.

Referenced by register_fade_end_callback().

◆ try_set_duty()

result< void > idfxx::pwm::output::try_set_duty ( float duty )

Sets the PWM duty cycle as a ratio.

Thread-safe. The new duty takes effect on the next PWM cycle.

Parameters

duty	Duty ratio in range [0.0, 1.0].

Returns: Success, or an error.

Return values

invalid_state	Output has been moved from.
invalid_arg	Invalid duty ratio.

Referenced by set_duty().

◆ try_set_duty_ticks() [1/2]

result< void > idfxx::pwm::output::try_set_duty_ticks ( uint32_t duty )

Sets the PWM duty cycle in ticks.

Thread-safe.

Parameters

duty	Duty in ticks, in range [0, ticks_max()].

Returns: Success, or an error.

Referenced by set_duty_ticks(), and set_duty_ticks().

◆ try_set_duty_ticks() [2/2]

result< void > idfxx::pwm::output::try_set_duty_ticks	(	uint32_t	duty,
		uint32_t	hpoint
	)

Sets the PWM duty cycle in ticks with high point.

Thread-safe.

Parameters

duty	Duty in ticks, in range [0, ticks_max()].
hpoint	High point in the PWM cycle.

Returns: Success, or an error.

◆ try_set_pulse_width()

template<typename Rep , typename Period >

result< void > idfxx::pwm::output::try_set_pulse_width ( const std::chrono::duration< Rep, Period > & width )

inline

Sets the PWM duty cycle as a pulse width duration.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

width Pulse width duration.

Returns: Success, or an error.

Return values

invalid_state Output has been moved from.

Definition at line 871 of file pwm.hpp.

Referenced by set_pulse_width().

◆ try_stop()

result< void > idfxx::pwm::output::try_stop ( idfxx::gpio::level idle_level = idfxx::gpio::level::low )

Stops PWM output and sets the GPIO to an idle level.

Parameters

idle_level Output level after stopping.

Returns: Success, or an error.

Referenced by idfxx::pwm::stop(), and stop().

◆ uninstall_fade_service()

static void idfxx::pwm::output::uninstall_fade_service ( )

static

Uninstalls the PWM fade service.

All fade operations must be stopped before calling this.

Friends And Related Symbol Documentation

◆ try_start [1/2]

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

friend

Referenced by idfxx::pwm::start(), idfxx::pwm::start(), idfxx::pwm::start(), and idfxx::pwm::start().

◆ try_start [2/2]

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

friend

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.

The documentation for this class was generated from the following file:

idfxx_pwm/include/idfxx/pwm.hpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~output()

◆ output() [1/2]

◆ output() [2/2]

Member Function Documentation

◆ channel()

◆ duty()

◆ duty_ticks()

◆ fade_to()

◆ fade_to_duty_ticks()

◆ fade_to_pulse_width()

◆ fade_with_step()

◆ install_fade_service()

◆ is_active()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pulse_width()

◆ register_fade_end_callback()

◆ release()

◆ set_duty()

◆ set_duty_ticks() [1/2]

◆ set_duty_ticks() [2/2]

◆ set_pulse_width()

◆ stop()

◆ ticks_max()

◆ timer()

◆ try_fade_to()

◆ try_fade_to_duty_ticks()

◆ try_fade_to_pulse_width()

◆ try_fade_with_step()

◆ try_install_fade_service()

◆ try_register_fade_end_callback()

◆ try_set_duty()

◆ try_set_duty_ticks() [1/2]

◆ try_set_duty_ticks() [2/2]

◆ try_set_pulse_width()

◆ try_stop()

◆ uninstall_fade_service()

Friends And Related Symbol Documentation

◆ try_start [1/2]

◆ try_start [2/2]