Arduino-style wrapper around an STM32 general purpose/advanced timer: PWM, output compare, input capture and update/compare interrupts. More...

#include <HardwareTimer.h>

Public Member Functions
	HardwareTimer ()
	HardwareTimer constructor: make uninitialized timer Before calling any methods, call setup to select and setup the timer to be used.

	HardwareTimer (TIM_TypeDef *instance)
	HardwareTimer constructor: set default configuration values The timer will be usable directly, there is no need to call setup().

	~HardwareTimer ()
	HardwareTimer destructor.

void	setup (TIM_TypeDef *instance)
	HardwareTimer setup: configuration values.

void	pause (void)
	Pause HardwareTimer: stop timer.

void	pauseChannel (uint32_t channel)
	Pause only one channel.

void	resume (void)
	Start or resume HardwareTimer: all channels are resumed, interrupts are enabled if necessary.

void	resumeChannel (uint32_t channel)
	Configure specified channel and resume/start timer.

void	setPrescaleFactor (uint32_t prescaler)
	Configure hardwareTimer prescaler.

uint32_t	getPrescaleFactor ()
	Retrieve prescaler from hardware register.

void	setOverflow (uint32_t overflow, TimerFormat_t format=TICK_FORMAT)
	Set overflow (rollover)

uint32_t	getOverflow (TimerFormat_t format=TICK_FORMAT)
	Retrieve overflow (rollover) value from hardware register.

void	setPWM (uint32_t channel, PinName pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback=nullptr, callback_function_t CompareCallback=nullptr)
	All in one function to configure PWM.

void	setPWM (uint32_t channel, pin_size_t pin, uint32_t frequency, uint32_t dutycycle, callback_function_t PeriodCallback=nullptr, callback_function_t CompareCallback=nullptr)
	All in one function to configure PWM, using an Arduino pin number.

void	setCount (uint32_t counter, TimerFormat_t format=TICK_FORMAT)
	Set timer counter value.

uint32_t	getCount (TimerFormat_t format=TICK_FORMAT)
	Retrieve timer counter value.

void	setMode (uint32_t channel, TimerModes_t mode, PinName pin=NC, ChannelInputFilter_t filter=FILTER_NONE)
	Set channel mode: configure timer channel with specified mode on specified pin if available.

void	setMode (uint32_t channel, TimerModes_t mode, pin_size_t pin, ChannelInputFilter_t filter=FILTER_NONE)
	Set channel mode: configure timer channel with specified mode on specified pin if available.

TimerModes_t	getMode (uint32_t channel)
	Retrieves channel mode configured.

void	setPreloadEnable (bool value)
	Enable or disable preloading for overflow value When disabled, changes to the overflow value take effect immediately.

uint32_t	getCaptureCompare (uint32_t channel, TimerCompareFormat_t format=TICK_COMPARE_FORMAT)
	Retrieve Capture/Compare value.

void	setCaptureCompare (uint32_t channel, uint32_t compare, TimerCompareFormat_t format=TICK_COMPARE_FORMAT)
	Set channel Capture/Compare register.

void	setInterruptPriority (uint32_t preemptPriority, uint32_t subPriority)
	Set the priority of the interrupt.

void	attachInterrupt (callback_function_t callback)
	Attach interrupt callback on update (rollover) event.

void	detachInterrupt ()
	Detach interrupt callback on update (rollover) event.

bool	hasInterrupt ()
	Checks if there's an interrupt callback attached on Rollover event.

void	attachInterrupt (uint32_t channel, callback_function_t callback)
	Attach interrupt callback on Capture/Compare event.

void	detachInterrupt (uint32_t channel)
	Detach interrupt callback on Capture/Compare event.

bool	hasInterrupt (uint32_t channel)
	Checks if there's an interrupt callback attached on Capture/Compare event.

void	timerHandleDeinit ()
	This function will reset the timer.

void	refresh (void)
	Generate an update event to force all registers (Autoreload, prescaler, compare) to be taken into account.

uint32_t	getTimerClkFreq ()
	This function return the timer clock frequency.

void	updateRegistersIfNotRunning (TIM_TypeDef *TIMx)
	Take into account registers update immediately if timer is not running, (independently from Preload setting)

bool	isRunning ()
	Check whether HardwareTimer is running (paused or resumed).

bool	isRunningChannel (uint32_t channel)
	Check whether channel is running (paused or resumed).

TIM_HandleTypeDef *	getHandle ()
	Return the timer object handle object for more advanced setup.

uint32_t	getChannel (uint32_t channel)
	Convert arduino channel into HAL channel.

uint32_t	getLLChannel (uint32_t channel)
	Convert arduino channel into LL channels used (regular and/or complementary)

bool	manageIT (uint32_t channel, ChannelITConfig_t config=DISABLE_IT)
	Handle itterupt based on arduino channel.

uint32_t	getAssociatedChannel (uint32_t channel)
	Get input associated channel Channel 1 and 2 are associated; channel 3 and 4 are associated.

Static Public Member Functions
static void	captureCompareCallback (TIM_HandleTypeDef *htim)
	Generic Capture and Compare callback which will call user callback.

static void	updateCallback (TIM_HandleTypeDef *htim)
	Generic Update (rollover) callback which will call user callback.

Detailed Description

Arduino-style wrapper around an STM32 general purpose/advanced timer: PWM, output compare, input capture and update/compare interrupts.

Constructor & Destructor Documentation

◆ HardwareTimer()

HardwareTimer::HardwareTimer ( TIM_TypeDef * instance )

HardwareTimer constructor: set default configuration values The timer will be usable directly, there is no need to call setup().

Using this constructor is not recommended for global variables that are automatically initialized at startup, since this will happen to early to report any errors. Better use the argumentless constructor and call the setup() method during initialization later.

Parameters

instance Timer instance ex: TIM1, ...

Member Function Documentation

◆ attachInterrupt() [1/2]

void HardwareTimer::attachInterrupt ( callback_function_t callback )

Attach interrupt callback on update (rollover) event.

Parameters

callback Interrupt callback

◆ attachInterrupt() [2/2]

void HardwareTimer::attachInterrupt	(	uint32_t	channel,
		callback_function_t	callback
	)

Attach interrupt callback on Capture/Compare event.

Parameters

channel	Arduino channel [1..4]
callback	Interrupt callback

◆ captureCompareCallback()

void HardwareTimer::captureCompareCallback ( TIM_HandleTypeDef * htim )

static

Generic Capture and Compare callback which will call user callback.

Parameters

htim	HAL timer handle

◆ detachInterrupt()

void HardwareTimer::detachInterrupt ( uint32_t channel )

Detach interrupt callback on Capture/Compare event.

Parameters

channel Arduino channel [1..4]

◆ getAssociatedChannel()

uint32_t HardwareTimer::getAssociatedChannel ( uint32_t channel )

Get input associated channel Channel 1 and 2 are associated; channel 3 and 4 are associated.

Parameters

channel Arduino channel [1..4]

Returns: associated channel [1..4]. Error handler called if arduino channel is invalid

◆ getCaptureCompare()

uint32_t HardwareTimer::getCaptureCompare	(	uint32_t	channel,
		TimerCompareFormat_t	format = `TICK_COMPARE_FORMAT`
	)

Retrieve Capture/Compare value.

Parameters

channel Arduino channel [1..4]

format Format of return value (see TimerCompareFormat_t). If omitted default format is Tick TICK_COMPARE_FORMAT: return value is the number of tick for Capture/Compare value MICROSEC_COMPARE_FORMAT: return value is the number of microsecondes for Capture/Compare value HERTZ_COMPARE_FORMAT: return value is the frequency in hertz for Capture/Compare value PERCENT_COMPARE_FORMAT: return value is the dutycycle in percentage RESOLUTION_nB_COMPARE_FORMAT: return value is the dutycycle scaled on n bits [0 .. 2^n - 1]

Returns: Capture/Compare value

◆ getChannel()

uint32_t HardwareTimer::getChannel ( uint32_t channel )

Convert arduino channel into HAL channel.

Parameters

channel Arduino channel [1..4]

Returns: HAL channel. Error handler called if arduino channel is invalid

◆ getCount()

uint32_t HardwareTimer::getCount ( TimerFormat_t format = TICK_FORMAT )

Retrieve timer counter value.

Parameters

format Format of returned value. If omitted default format is Tick

Returns: counter value depending on format value: TICK_FORMAT: return number of tick for counter MICROSEC_FORMAT: return number of microsecondes for counter HERTZ_FORMAT: return frequency in hertz for counter

◆ getHandle()

TIM_HandleTypeDef * HardwareTimer::getHandle ( )

Return the timer object handle object for more advanced setup.

Note: Using this function and editing the Timer handle is at own risk! No support will be provided whatsoever if the HardwareTimer does not work as expected when editing the handle using the HAL functionality or other custom coding.

Returns: TIM_HandleTypeDef address

◆ getLLChannel()

uint32_t HardwareTimer::getLLChannel ( uint32_t channel )

Convert arduino channel into LL channels used (regular and/or complementary)

Parameters

channel Arduino channel [1..4]

Returns: LL channel. Error handler called if arduino channel is invalid

◆ getMode()

TimerModes_t HardwareTimer::getMode ( uint32_t channel )

Retrieves channel mode configured.

Parameters

channel Arduino channel [1..4]

Returns: returns configured mode

◆ getOverflow()

uint32_t HardwareTimer::getOverflow ( TimerFormat_t format = TICK_FORMAT )

Retrieve overflow (rollover) value from hardware register.

Parameters

format Format of returned value. If omitted default format is Tick

Returns: overflow depending on format value: TICK_FORMAT: return number of tick for overflow MICROSEC_FORMAT: return number of microsecondes for overflow HERTZ_FORMAT: return frequency in hertz for overflow

◆ getPrescaleFactor()

uint32_t HardwareTimer::getPrescaleFactor ( )

Retrieve prescaler from hardware register.

Returns: prescaler factor

◆ getTimerClkFreq()

uint32_t HardwareTimer::getTimerClkFreq ( )

This function return the timer clock frequency.

Returns: frequency in Hz

◆ hasInterrupt() [1/2]

bool HardwareTimer::hasInterrupt ( )

Checks if there's an interrupt callback attached on Rollover event.

Returns: returns true if a timer rollover interrupt has already been set

◆ hasInterrupt() [2/2]

bool HardwareTimer::hasInterrupt ( uint32_t channel )

Checks if there's an interrupt callback attached on Capture/Compare event.

Parameters

channel Arduino channel [1..4]

Returns: returns true if a channel compare match interrupt has already been set

◆ isRunning()

bool HardwareTimer::isRunning ( )

Check whether HardwareTimer is running (paused or resumed).

Returns: return true if the HardwareTimer is running

◆ isRunningChannel()

bool HardwareTimer::isRunningChannel ( uint32_t channel )

Check whether channel is running (paused or resumed).

Parameters

channel Arduino channel [1..4]

Returns: return true if HardwareTimer is running and the channel is enabled

◆ manageIT()

bool HardwareTimer::manageIT	(	uint32_t	channel,
		ChannelITConfig_t	config = `DISABLE_IT`
	)

Handle itterupt based on arduino channel.

Parameters

channel	Arduino channel [1..4]
config	Configuration for the interrupt (enable, disable, clear, clear and disable)

Returns: true if interrupt is enabled, false otherwise

◆ pauseChannel()

void HardwareTimer::pauseChannel ( uint32_t channel )

Pause only one channel.

Timer is still running but channel is disabled (output and interrupt)

Parameters

channel Arduino channel [1..4]

◆ refresh()

void HardwareTimer::refresh ( void )

Generate an update event to force all registers (Autoreload, prescaler, compare) to be taken into account.

Note: Refresh() can only be called after timer has been initialized, either by calling setup() function or thanks to constructor with TIM instance parameter. It is useful while timer is running after some registers update

◆ resumeChannel()

void HardwareTimer::resumeChannel ( uint32_t channel )

Configure specified channel and resume/start timer.

Parameters

channel Arduino channel [1..4]

◆ setCaptureCompare()

void HardwareTimer::setCaptureCompare	(	uint32_t	channel,
		uint32_t	compare,
		TimerCompareFormat_t	format = `TICK_COMPARE_FORMAT`
	)

Set channel Capture/Compare register.

Parameters

channel	Arduino channel [1..4]
compare	Compare value depending on format
format	Format of compare parameter (see TimerCompareFormat_t). If omitted default format is Tick TICK_COMPARE_FORMAT: compare is the number of tick MICROSEC_COMPARE_FORMAT: compare is the number of microsecondes HERTZ_COMPARE_FORMAT: compare is the frequency in hertz PERCENT_COMPARE_FORMAT: compare is the dutycycle in percentage RESOLUTION_nB_COMPARE_FORMAT: compare is the dutycycle scaled on n bits [0 .. 2^n - 1]

◆ setCount()

void HardwareTimer::setCount	(	uint32_t	counter,
		TimerFormat_t	format = `TICK_FORMAT`
	)

Set timer counter value.

Parameters

counter	Counter value, depends on format parameter
format	Format of counter parameter. If omitted default format is Tick TICK_FORMAT: counter is the number of tick MICROSEC_FORMAT: counter is the number of microsecondes HERTZ_FORMAT: counter is the frequency in hertz

◆ setInterruptPriority()

void HardwareTimer::setInterruptPriority	(	uint32_t	preemptPriority,
		uint32_t	subPriority
	)

Set the priority of the interrupt.

Note: Must be call before resume()

Parameters

preemptPriority	The pre-emption priority for the IRQn channel
subPriority	The subpriority level for the IRQ channel.

◆ setMode() [1/2]

void HardwareTimer::setMode	(	uint32_t	channel,
		TimerModes_t	mode,
		pin_size_t	pin,
		ChannelInputFilter_t	filter = `FILTER_NONE`
	)

Set channel mode: configure timer channel with specified mode on specified pin if available.

Parameters

channel	Arduino channel [1..4]
mode	Mode configuration for the channel (see TimerModes_t)
pin	Arduino pin number, ex: D1, 1 or PA1
filter	Input capture filter (see ChannelInputFilter_t)

◆ setMode() [2/2]

void HardwareTimer::setMode	(	uint32_t	channel,
		TimerModes_t	mode,
		PinName	pin = `NC`,
		ChannelInputFilter_t	filter = `FILTER_NONE`
	)

Set channel mode: configure timer channel with specified mode on specified pin if available.

Parameters

channel	Arduino channel [1..4]
mode	Mode configuration for the channel (see TimerModes_t)
pin	Pin name, ex: PB_0
filter	Input capture filter (see ChannelInputFilter_t)

◆ setOverflow()

void HardwareTimer::setOverflow	(	uint32_t	overflow,
		TimerFormat_t	format = `TICK_FORMAT`
	)

Set overflow (rollover)

   Note that by default, the new value will not be applied
   immediately, but become effective at the next update event
   (usually the next timer overflow). See setPreloadEnable()
   for controlling this behaviour.

Parameters

overflow	Overflow value, depends on format parameter
format	Format of overflow parameter. If omitted default format is Tick TICK_FORMAT: overflow is the number of tick for overflow MICROSEC_FORMAT: overflow is the number of microsecondes for overflow HERTZ_FORMAT: overflow is the frequency in hertz for overflow

◆ setPreloadEnable()

void HardwareTimer::setPreloadEnable ( bool value )

Enable or disable preloading for overflow value When disabled, changes to the overflow value take effect immediately.

When enabled (the default), the value takes effect only at the next update event (typically the next overflow).

Note that the capture/compare register has its own preload enable bit, which is independent and enabled in PWM modes and disabled otherwise. If you need more control of that bit, you can use the HAL functions directly.

Parameters

value true to enable preloading, false to disable

◆ setPrescaleFactor()

void HardwareTimer::setPrescaleFactor ( uint32_t prescaler )

Configure hardwareTimer prescaler.

Parameters

prescaler Prescaler factor

◆ setPWM() [1/2]

void HardwareTimer::setPWM	(	uint32_t	channel,
		pin_size_t	pin,
		uint32_t	frequency,
		uint32_t	dutycycle,
		callback_function_t	PeriodCallback = `nullptr`,
		callback_function_t	CompareCallback = `nullptr`
	)

All in one function to configure PWM, using an Arduino pin number.

Parameters

channel	Arduino channel [1..4]
pin	Arduino pin number, ex D1, 1 or PA1
frequency	PWM frequency expressed in hertz
dutycycle	PWM dutycycle expressed in percentage
PeriodCallback	Timer period callback (timer rollover upon update event)
CompareCallback	Timer compare callback

◆ setPWM() [2/2]

void HardwareTimer::setPWM	(	uint32_t	channel,
		PinName	pin,
		uint32_t	frequency,
		uint32_t	dutycycle,
		callback_function_t	PeriodCallback = `nullptr`,
		callback_function_t	CompareCallback = `nullptr`
	)

All in one function to configure PWM.

Parameters

channel	Arduino channel [1..4]
pin	Pin name, ex PB_0
frequency	PWM frequency expressed in hertz
dutycycle	PWM dutycycle expressed in percentage
PeriodCallback	Timer period callback (timer rollover upon update event)
CompareCallback	Timer compare callback

◆ setup()

void HardwareTimer::setup ( TIM_TypeDef * instance )

HardwareTimer setup: configuration values.

Must be called exactly once before any other methods, except when an instance is passed to the constructor.

Parameters

instance Timer instance ex: TIM1, ...

◆ updateCallback()

void HardwareTimer::updateCallback ( TIM_HandleTypeDef * htim )

static

Generic Update (rollover) callback which will call user callback.

Parameters

htim	HAL timer handle

◆ updateRegistersIfNotRunning()

void HardwareTimer::updateRegistersIfNotRunning ( TIM_TypeDef * TIMx )

Take into account registers update immediately if timer is not running, (independently from Preload setting)

Parameters

TIMx	Timer instance

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

libraries/SrcWrapper/inc/HardwareTimer.h
libraries/SrcWrapper/src/HardwareTimer.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HardwareTimer()

Member Function Documentation

◆ attachInterrupt() [1/2]

◆ attachInterrupt() [2/2]

◆ captureCompareCallback()

◆ detachInterrupt()

◆ getAssociatedChannel()

◆ getCaptureCompare()

◆ getChannel()

◆ getCount()

◆ getHandle()

◆ getLLChannel()

◆ getMode()

◆ getOverflow()

◆ getPrescaleFactor()

◆ getTimerClkFreq()

◆ hasInterrupt() [1/2]

◆ hasInterrupt() [2/2]

◆ isRunning()

◆ isRunningChannel()

◆ manageIT()

◆ pauseChannel()

◆ refresh()

◆ resumeChannel()

◆ setCaptureCompare()

◆ setCount()

◆ setInterruptPriority()

◆ setMode() [1/2]

◆ setMode() [2/2]

◆ setOverflow()

◆ setPreloadEnable()

◆ setPrescaleFactor()

◆ setPWM() [1/2]

◆ setPWM() [2/2]

◆ setup()

◆ updateCallback()

◆ updateRegistersIfNotRunning()