TimerOne & TimerThree Libraries

Hardware Requirements

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.

Basic Usage

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

Configuration

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

Set a new period after the library is already initialized.

Run Control

Start the timer, beginning a new period.

Stop the timer.

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

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

PWM Signal Output

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.

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.

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

Interrupt 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.

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

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

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

The original version of these libraries is at:

Timer1 page.