TimerOne & TimerThree Libraries

TimerOne and TimerThree let you use the built-in 16 bit timers.

Download: Included with the Teensyduino Installer
Latest TimerOne on Github
Latest TimerThree on Github

Hardware Requirements

These libraries use Timer1 and Timer3.

Each timer controls PWM pins. While uses these libraries, analogWrite() to those pins will not work normally, but you can use the library pwm() function.

BoardTimerOne
PWM Pins
TimerThree
PWM Pins
Teensy 4.1 & 4.07, 86, 9
Teensy 3.5 & 3.63, 429, 30
Teensy 3.2 & 3.13, 425, 32
Teensy 3.03, 4
Teensy 2.04, 14, 159
Teensy++ 2.025, 26, 2714, 15, 16
Arduino Uno9, 10
Arduino Leonardo9, 10, 115
Arduino Mega11, 12, 132, 3, 5
Wiring-S4, 5
Sanguino12, 13

Basic Usage

The timer is configured to repetitively measure a period of time, in microseconds. At the end of each period, an interrupt function can be run. The PWM pins can also be configured to switch during a portion of the period.

If using TimerThree, replace "Timer1" with "Timer3".

Configuration

Timer1.initialize(microseconds);

Begin using the timer. This function must be called first. "microseconds" is the period of time the timer takes.

Timer1.setPeriod(microseconds);

Set a new period after the library is already initialized.

Run Control

Timer1.start();

Start the timer, beginning a new period.

Timer1.stop();

Stop the timer.

Timer1.restart();

Restart the timer, from the beginning of a new period.

Timer1.resume();

Resume running a stopped timer. A new period is not begun.

PWM Signal Output

Timer1.pwm(pin, duty);

Configure one of the timer's PWM pins. "duty" is from 0 to 1023, where 0 makes the pin always LOW and 1023 makes the pin always HIGH.

Timer1.setPwmDuty(pin, duty);

Set a new PWM, without reconfiguring the pin. This is slightly faster than pwm(), but pwm() must be used at least once to configure the pin.

Timer1.disablePwm(pin);

Stop using PWM on a pin. The pin reverts to being controlled by digitalWrite().

Interrupt Function

Timer1.attachInterrupt(function);

Run a function each time the timer period finishes. The function is run as an interrupt, so special care is needed to share any variables beteen the interrupt function and your main program.

Timer1.detachInterrupt();

Disable the interrupt, so the function no longer runs.

Example Program

#include <TimerOne.h>

// This example uses the timer interrupt to blink an LED
// and also demonstrates how to share a variable between
// the interrupt and the main program.

const int led = LED_BUILTIN;  // the pin with a LED

void setup(void)
{
  pinMode(led, OUTPUT);
  Timer1.initialize(150000);
  Timer1.attachInterrupt(blinkLED); // blinkLED to run every 0.15 seconds
  Serial.begin(9600);
}


// The interrupt will blink the LED, and keep
// track of how many times it has blinked.
int ledState = LOW;
volatile unsigned long blinkCount = 0; // use volatile for shared variables

void blinkLED(void)
{
  if (ledState == LOW) {
    ledState = HIGH;
    blinkCount = blinkCount + 1;  // increase when LED turns on
  } else {
    ledState = LOW;
  }
  digitalWrite(led, ledState);
}


// The main program will print the blink count
// to the Arduino Serial Monitor
void loop(void)
{
  unsigned long blinkCopy;  // holds a copy of the blinkCount

  // to read a variable which the interrupt code writes, we
  // must temporarily disable interrupts, to be sure it will
  // not change while we are reading.  To minimize the time
  // with interrupts off, just quickly make a copy, and then
  // use the copy while allowing the interrupt to keep working.
  noInterrupts();
  blinkCopy = blinkCount;
  interrupts();

  Serial.print("blinkCount = ");
  Serial.println(blinkCopy);
  delay(100);
}

Interrupt Context Issues

Special design is necessary to share data between interrupt code and the rest of your program.

Variables usually need to be "volatile" types. Volatile tells the compiler to avoid optimizations that assume variable can not spontaneously change. Because your function may change variables while your program is using them, the compiler needs this hint. But volatile alone is often not enough.

When accessing shared variables, usually interrupts must be disabled. Even with volatile, if the interrupt changes a multi-byte variable between a sequence of instructions, it can be read incorrectly. If your data is multiple variables, such as an array and a count, usually interrupts need to be disabled for the entire sequence of your code which accesses the data.

Details

New development on TimerOne occurs on this Github page:

https://github.com/PaulStoffregen/TimerOne
https://github.com/PaulStoffregen/TimerThree

The original version of these libraries is at:

Timer1 page.