idfxx::pwm::output Class Reference

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
enum channel	channel () const noexcept
	Returns the channel slot used by this output.
idfxx::gpio	gpio () const noexcept
	Returns the GPIO pin used by this output.
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	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, 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 698 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 used by this output.

Definition at line 713 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 867 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 919 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 969 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 1022 of file pwm.hpp.

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

gpio()

idfxx::gpio idfxx::pwm::output::gpio ( ) const

inlinenoexcept

Returns the GPIO pin used by this output.

Definition at line 716 of file pwm.hpp.

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 1084 of file pwm.hpp.

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.

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 747 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 773 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 785 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 832 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 1119 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().

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 892 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 944 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 996 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_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 848 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

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.

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

---

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

• idfxx_pwm/include/idfxx/pwm.hpp