HardwareTimer — Maple v0.0.9 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Docs Home |
- Index »
- Complete Language Index »

# 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

### Navigation

- next
- previous |
- LeafLabs |
- Docs Home |
- Index »
- Complete Language Index »