HardwareTimer

This class defines the public API for interfacing with the STM32’s built-in timer peripherals. More information on these peripherals (including code examples) is available in the timers reference.

Library Documentation

HardwareTimer Class Reference

To interact with a particular timer, call one of the methods documented below on one of the predefined HardwareTimer instances. For example, to set the prescale factor on timer 1 to 5, call Timer1.setPrescaleFactor(5).

class HardwareTimer

Class for interacting with a timer. There are four predefined instances available on the Maple: Timer1, Timer2, Timer3, and Timer4.

void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler)

Attach an interrupt handler to the given channel. This interrupt handler will be called when the timer’s counter reaches the given channel compare value.

handler should be a function which takes no arguments and has void value; i.e. it should have signature

void handler(void);

You can later detach the interrupt using detachInterrupt().

Note

The function (often called an interrupt service routine, or ISR) should attempt to return as quickly as possible. Blinking the LED, some logic, PWM updates, and Serial writes are fine; writing to SerialUSB or waiting for user input can take a long time and prevent other interrupts from firing on time.

Tip: if you have a delay() in your ISR, you’re probably doing it wrong.

void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler)

Equivalent to attachInterrupt(1, handler).

void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler)

Equivalent to attachInterrupt(2, handler).

void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler)

Equivalent to attachInterrupt(3, handler).

void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler)

Equivalent to attachInterrupt(4, handler).

void HardwareTimer::setChannelMode(int channel, TimerMode mode)

Set the given channel of this timer to the given mode. The parameter channel is one of 1, 2, 3, and 4, and corresponds to the compare channel you would like to set. Refer to the full pin mapping table to match up timer channels and pin numbers.

void HardwareTimer::setChannel1Mode(TimerMode mode)

Equivalent to setChannelMode(1, mode).

void HardwareTimer::setChannel2Mode(TimerMode mode)

Equivalent to setChannelMode(2, mode).

void HardwareTimer::setChannel3Mode(TimerMode mode)

Equivalent to setChannelMode(3, mode).

void HardwareTimer::setChannel4Mode(TimerMode mode)

Equivalent to setChannelMode(4, mode).

uint16 HardwareTimer::getCompare(int channel)

Gets the compare value for the given channel, from 1 to 4. See setCompare().

uint16 HardwareTimer::getCompare1()

Equivalent to getCompare(1, mode).

uint16 HardwareTimer::getCompare2()

Equivalent to getCompare(2, mode).

uint16 HardwareTimer::getCompare3()

Equivalent to getCompare(3, mode).

uint16 HardwareTimer::getCompare4()

Equivalent to getCompare(4, mode).

void HardwareTimer::setCompare(int channel, uint16 compare)

Sets the compare value for the given channel to compare. If compare is greater than this timer’s overflow value, it will be truncated to the overflow value. The default compare value is 65,535 (the largest unsigned 16-bit integer value).

When the counter reaches this value the interrupt for this channel will fire if the given channel mode is TIMER_OUTPUTCOMPARE and an interrupt is attached.

By default, this only changes the relative offsets between events on a single timer (“phase”); they don’t control the frequency with which they occur. However, a common trick is to increment the compare value manually in the interrupt handler so that the event will fire again after the increment period. There can be a different increment value for each channel, so this trick allows events to be programmed at 4 different rates on a single timer. Note that function call overheads mean that the smallest increment rate is at least a few microseconds.

void HardwareTimer::setCompare1(uint16 compare)

Equivalent to setCompare(1, compare).

void HardwareTimer::setCompare2(uint16 compare)

Equivalent to setCompare(2, compare).

void HardwareTimer::setCompare3(uint16 compare)

Equivalent to setCompare(3, compare).

void HardwareTimer::setCompare4(uint16 compare)

Equivalent to setCompare(4, compare).

uint16 HardwareTimer::getCount()

Gets the current timer count. Due to function call overhead, the return value will be increasingly accurate with smaller prescale values. Also see setCount().

void HardwareTimer::setCount(uint16 val)

Set the timer’s current count to val.

Note that there is some function call overhead associated with calling this method, so using it is not a robust way to get multiple timers to share a count value.

If val exceeds the timer’s overflow value, it is truncated to the overflow value.

void HardwareTimer::detachInterrupt(int channel)

Remove the interrupt handler attached to the given channel, if any. The handler will no longer be called by this timer.

void HardwareTimer::detachCompare1Interrupt()

Equivalent to detachInterrupt(1).

void HardwareTimer::detachCompare2Interrupt()

Equivalent to detachInterrupt(2).

void HardwareTimer::detachCompare3Interrupt()

Equivalent to detachInterrupt(3).

void HardwareTimer::detachCompare4Interrupt()

Equivalent to detachInterrupt(4).

void HardwareTimer::generateUpdate()

Re-initializes the counter (to 0 in upcounting mode, which is the default), and generates an update of the prescale and overflow registers.

uint16 HardwareTimer::getOverflow()

Gets the timer’s overflow value. See setOverflow().

void HardwareTimer::setOverflow(uint16 val)

Sets the timer overflow (or “reload”) value to val.

When the timer’s counter reaches this, value it resets to zero. Its default value is 65535 (the largest unsigned 16-bit integer); setting the overflow to anything lower will cause interrupts to be called more frequently (see setPeriod() function for a shortcut).

After the next timer update, this number will be the maximum value for the timer’s channel compare values.

void HardwareTimer::pause()

Stop the timer’s counter, without affecting its configuration.

The timer will no longer count or fire interrupts after this function is called, until it is resumed. This function is useful during timer setup periods, in order to prevent interrupts from firing before the timer is fully configured.

Note that there is some function call overhead associated with this method, so using it in concert with resume() is not a robust way to align multiple timers to the same count value.

uint16 HardwareTimer::setPeriod(uint32 microseconds)

Configure the prescaler and overflow values to generate a timer reload with a period as close to the given number of microseconds as possible.

The return value is the new overflow value, which may be used to set channel compare values. However, if a clock that fires an interrupt every given number of microseconds is all that is desired, and the relative “phases” are unimportant, channel compare values may all be set to 1.

uint16 HardwareTimer::getPrescaleFactor()

Returns the timer’s prescale factor. See setPrescaleFactor().

void HardwareTimer::setPrescaleFactor(uint16 factor)

Set the timer’s prescale factor to factor.

The prescaler acts as a clock divider to slow down the rate at which the counter increments.

For example, the system clock rate is 72MHz, so the counter will reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22 microseconds), or about a thousand times a second. If the prescaler equals 1098, then the clock rate is effectively 72MHz / 1098 = 65.56KHz, and the counter will reach 65536 in (15.25 microseconds) × (65536 counts) = (0.999 seconds), or about once per second.

The setPeriod() method may also be used as a convenient alternative.

void HardwareTimer::resume()

Resume a paused timer, without affecting its configuration.

The timer will resume counting and firing interrupts as appropriate.

Note that there is some function call overhead associated with using this method, so using it in concert with pause() is not a robust way to align multiple timers to the same count value.

timer_dev_num HardwareTimer::getTimerNum()

Returns the timer device number associated with the timer. For example, Timer1.getTimerNum() would return TIMER1.

In most cases, you should not need to use this function. If you do use it, be careful; the constant TIMER1 is not equal to the number 1; similarly, TIMER2 is not the number 2, etc. Be sure to refer to the timer device number by name.

Timer Modes

TimerMode enum

Used to configure the behavior of a timer.

Values:

• TIMER_DISABLED -

  In this mode, the timer stops counting, interrupts are not called, and no state changes are output.

• TIMER_PWM -

  This is the default mode for pins after initialization.

• TIMER_OUTPUTCOMPARE -

  In this mode, the timer counts from 0 to its reload value repeatedly; every time the counter value reaches one of the channel compare values, the corresponding interrupt is fired.

Timer Device Numbers

These provide a lower-level interface for interacting with timers. They are mostly useful in context with the getTimer() function. Be careful when using these not to confuse e.g. TIMER1 with the number 1; they are different.

timer_dev_num enum

Timer device numbers.

See STM32 reference manual, chapters 13-15.

Values:

• TIMER1 -
• TIMER2 -
• TIMER3 -
• TIMER4 -
• TIMER_INVALID -

Other Functions

HardwareTimer * getTimer(timer_dev_num timerNum)

Get one of the pre-instantiated HardwareTimer instances, given a timer device number.

Be careful not to pass an actual number to this function. For example, getTimer(1) will not return Timer1. Use a real timer_dev_num, e.g. TIMER1, TIMER2, etc.

Parameters

• timerNum -

  the timer device number, e.g. TIMER1.

Return

Pointer to the HardwareTimer instance corresponding to the given timer device number. If timerNum is TIMER_INVALID, returns a null pointer.

See

timer_dev_num