A lightweight identifier for a hardware PWM timer. More...

Classes
struct	config
	Timer configuration parameters. More...

Public Member Functions
	timer (const timer &)=default

timer &	operator= (const timer &)=default

	timer (timer &&)=default

timer &	operator= (timer &&)=default

constexpr bool	operator== (const timer &other) const =default

constexpr enum speed_mode	speed_mode () const noexcept
	Returns the speed mode.

void	configure (const struct config &cfg)
	Configures the timer with the given parameters.

void	configure (freq::hertz frequency, uint8_t resolution_bits=13)
	Configures the timer with frequency and resolution.

result< void >	try_configure (const struct config &cfg)
	Configures the timer with the given parameters.

result< void >	try_configure (freq::hertz frequency, uint8_t resolution_bits=13)
	Configures the timer with frequency and resolution.

bool	is_configured () const noexcept
	Returns true if the timer has been configured.

uint8_t	resolution_bits () const noexcept
	Returns the configured resolution in bits.

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

freq::hertz	frequency () const
	Returns the current timer frequency.

std::chrono::nanoseconds	period () const
	Returns the PWM period (1 / frequency) as a duration.

std::chrono::nanoseconds	tick_period () const
	Returns the duration of a single timer tick.

void	set_frequency (freq::hertz frequency)
	Changes the timer frequency.

result< void >	try_set_frequency (freq::hertz frequency)
	Changes the timer frequency.

template<typename Rep , typename Period >
void	set_period (const std::chrono::duration< Rep, Period > &period)
	Changes the timer period.

template<typename Rep , typename Period >
result< void >	try_set_period (const std::chrono::duration< Rep, Period > &period)
	Changes the timer period.

void	pause ()
	Pauses the timer counter.

result< void >	try_pause ()
	Pauses the timer counter.

void	resume ()
	Resumes the timer counter.

result< void >	try_resume ()
	Resumes the timer counter.

void	reset ()
	Resets the timer counter.

result< void >	try_reset ()
	Resets the timer counter.

Friends
template<int N, speed_mode M>
struct	timer_constant

std::optional< timer >	get_timer (enum channel, enum speed_mode)
	Returns the timer associated with an active channel, if any.

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

Detailed Description

A lightweight identifier for a hardware PWM timer.

Timers are fixed hardware resources, like GPIO pins. This class provides a copyable, lightweight handle for configuring and controlling a specific timer unit. Use the predefined constants (timer_0 through timer_3).

Call configure() to set up the timer's frequency and resolution before creating any output bound to it.

using namespace frequency_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 at 13-bit resolution

Definition at line 155 of file pwm.hpp.

Constructor & Destructor Documentation

◆ timer() [1/2]

idfxx::pwm::timer::timer ( const timer & )

default

◆ timer() [2/2]

idfxx::pwm::timer::timer ( timer && )

default

Member Function Documentation

◆ configure() [1/2]

void idfxx::pwm::timer::configure ( const struct config & cfg )

inline

Configures the timer with the given parameters.

Sets up the timer's frequency, resolution, and clock source. Must be called before creating any output bound to this timer.

Parameters

cfg	Timer configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

auto tmr = idfxx::pwm::timer_0;

tmr.configure({.frequency = 5_kHz, .resolution_bits = 13});

Definition at line 202 of file pwm.hpp.

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

◆ configure() [2/2]

void idfxx::pwm::timer::configure	(	freq::hertz	frequency,
		uint8_t	resolution_bits = `13`
	)

inline

Configures the timer with frequency and resolution.

Convenience overload using automatic clock source selection.

Parameters

frequency	PWM frequency.
resolution_bits	Duty resolution in bits (default: 13).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 214 of file pwm.hpp.

References frequency(), resolution_bits(), try_configure(), and idfxx::unwrap().

◆ frequency()

freq::hertz idfxx::pwm::timer::frequency ( ) const

Returns the current timer frequency.

The actual frequency may differ slightly from the requested value due to rounding.

Returns: Current frequency, or 0 Hz if the timer is not configured.

Referenced by configure(), set_frequency(), and try_configure().

◆ is_configured()

bool idfxx::pwm::timer::is_configured ( ) const

noexcept

Returns true if the timer has been configured.

This reflects global state — any copy of the same timer identifier will see the same configured status.

Returns: True if configure() has been called for this timer.

◆ operator=() [1/2]

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

default

◆ operator=() [2/2]

timer & idfxx::pwm::timer::operator= ( timer && )

default

◆ operator==()

constexpr bool idfxx::pwm::timer::operator== ( const timer & other ) const

constexprdefault

◆ pause()

void idfxx::pwm::timer::pause ( )

inline

Pauses the timer counter.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 381 of file pwm.hpp.

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

◆ period()

std::chrono::nanoseconds idfxx::pwm::timer::period ( ) const

Returns the PWM period (1 / frequency) as a duration.

Returns zero if the timer is not configured.

Returns: PWM period in nanoseconds, or 0 if not configured.

Referenced by set_period(), and try_set_period().

◆ reset()

void idfxx::pwm::timer::reset ( )

inline

Resets the timer counter.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 415 of file pwm.hpp.

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

◆ resolution_bits()

uint8_t idfxx::pwm::timer::resolution_bits ( ) const

noexcept

Returns the configured resolution in bits.

Returns 0 if the timer has not been configured via configure().

Returns: Duty resolution bits, or 0 if not configured.

Referenced by configure(), and try_configure().

◆ resume()

void idfxx::pwm::timer::resume ( )

inline

Resumes the timer counter.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 398 of file pwm.hpp.

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

◆ set_frequency()

void idfxx::pwm::timer::set_frequency ( freq::hertz frequency )

inline

Changes the timer frequency.

The timer must have been configured first via configure().

Parameters

frequency New PWM frequency.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 313 of file pwm.hpp.

References frequency(), try_set_frequency(), and idfxx::unwrap().

◆ set_period()

template<typename Rep , typename Period >

void idfxx::pwm::timer::set_period ( const std::chrono::duration< Rep, Period > & period )

inline

Changes the timer period.

The timer must have been configured first via configure().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

period New PWM period.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

using namespace std::chrono_literals;

tmr.set_period(20ms); // 50 Hz

Definition at line 347 of file pwm.hpp.

References period(), try_set_period(), and idfxx::unwrap().

◆ speed_mode()

constexpr enum speed_mode idfxx::pwm::timer::speed_mode ( ) const

inlineconstexprnoexcept

Returns the speed mode.

Definition at line 184 of file pwm.hpp.

◆ tick_period()

std::chrono::nanoseconds idfxx::pwm::timer::tick_period ( ) const

Returns the duration of a single timer tick.

Equal to period() / ticks_max(). Returns zero if the timer is not configured.

Returns: Tick duration in nanoseconds, or 0 if not configured.

◆ ticks_max()

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

noexcept

Returns the maximum duty ticks for the configured resolution.

Equal to 1 << resolution_bits(). Returns 1 if not configured.

Returns: Maximum duty ticks.

◆ try_configure() [1/2]

result< void > idfxx::pwm::timer::try_configure ( const struct config & cfg )

Configures the timer with the given parameters.

Sets up the timer's frequency, resolution, and clock source. Must be called before creating any output bound to this timer.

Parameters

cfg	Timer configuration.

Returns: Success, or an error.

Return values

invalid_arg	Invalid frequency (zero) or resolution.
fail	Requested frequency cannot be achieved.

Referenced by configure(), configure(), and try_configure().

◆ try_configure() [2/2]

result< void > idfxx::pwm::timer::try_configure	(	freq::hertz	frequency,
		uint8_t	resolution_bits = `13`
	)

inline

Configures the timer with frequency and resolution.

Convenience overload using automatic clock source selection.

Parameters

frequency	PWM frequency.
resolution_bits	Duty resolution in bits (default: 13).

Returns: Success, or an error.

Definition at line 242 of file pwm.hpp.

References frequency(), resolution_bits(), and try_configure().

◆ try_pause()

result< void > idfxx::pwm::timer::try_pause ( )

Pauses the timer counter.

Returns: Success, or an error.

Referenced by pause().

◆ try_reset()

result< void > idfxx::pwm::timer::try_reset ( )

Resets the timer counter.

Returns: Success, or an error.

Referenced by reset().

◆ try_resume()

result< void > idfxx::pwm::timer::try_resume ( )

Resumes the timer counter.

Returns: Success, or an error.

Referenced by resume().

◆ try_set_frequency()

result< void > idfxx::pwm::timer::try_set_frequency ( freq::hertz frequency )

Changes the timer frequency.

The timer must have been configured first via configure().

Parameters

frequency New PWM frequency.

Returns: Success, or an error.

Return values

invalid_arg	Invalid frequency or timer not configured.
fail	Requested frequency cannot be achieved.

Referenced by set_frequency(), and try_set_period().

◆ try_set_period()

template<typename Rep , typename Period >

result< void > idfxx::pwm::timer::try_set_period ( const std::chrono::duration< Rep, Period > & period )

inline

Changes the timer period.

The timer must have been configured first via configure().

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

period New PWM period.

Returns: Success, or an error.

Return values

invalid_arg	Invalid period (zero or negative).
fail	Requested period cannot be achieved.

Definition at line 366 of file pwm.hpp.

References idfxx::error(), idfxx::invalid_arg, period(), and try_set_frequency().

Referenced by set_period().

Friends And Related Symbol Documentation

◆ get_timer

std::optional< timer > get_timer	(	enum	channel,
		enum	speed_mode
	)

friend

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.

◆ timer_constant

template<int N, speed_mode M>

friend struct timer_constant

friend

Definition at line 157 of file pwm.hpp.

◆ try_start

result< output > try_start	(	idfxx::gpio	,
		const 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

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ timer() [1/2]

◆ timer() [2/2]

Member Function Documentation

◆ configure() [1/2]

◆ configure() [2/2]

◆ frequency()

◆ is_configured()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ pause()

◆ period()

◆ reset()

◆ resolution_bits()

◆ resume()

◆ set_frequency()

◆ set_period()

◆ speed_mode()

◆ tick_period()

◆ ticks_max()

◆ try_configure() [1/2]

◆ try_configure() [2/2]

◆ try_pause()

◆ try_reset()

◆ try_resume()

◆ try_set_frequency()

◆ try_set_period()

Friends And Related Symbol Documentation

◆ get_timer

◆ timer_constant

◆ try_start