# SFBHWTimer Class Reference

The representation of a hardware timer. More...

`#include <SFBHWTimer.h>`

## Public Member Functions
void | begin (u32 usecsPerTick=1000, u32 ticksPerLap=1000, bool running=false)
| Power up and configure the timer.
void | end ()
| Disable and power down the timer.
void | setTickTime (u32 usecsPerTick)
| Specify how long a single tick of the timer will take.
void | setRunning (bool isRunning)
| Start or stop the ticking of the timer.
void | start ()
| Start the timer ticking.
void | stop ()
| Stop the timer ticking.
void | reset (bool alsoStop=false)
| Reset the timer, setting the tick counter to 0.
void | setLap (u32 ticksPerLap)
| Set the number of ticks per lap.
u32 | getLap ()
| Access the number of ticks per lap.
void | setLapHandler (HWTimerHandler handler)
| Specify that handler shall be called each time the timer laps.
void | setSplitHandler (u32 splitIndex, u32 ticks, HWTimerHandler handler)
| Specify that handler shall be called whenever the clock reaches ticks within a given lap.
void | setSplit (u32 splitIndex, u32 ticks)
| Set the ticks of the splitIndex split time, without affecting any existing split time handelr.
u32 | getSplit (u32 splitIndex)
| Access the number of ticks in a given split.
HWTimerHandler | getSplitHandler (u32 splitIndex)
| Access the handler associated with a given split, if any.
HWTimerHandler | getLapHandler ()
| Access the lap handler, if any.
u32 | getLaps ()
| Access the total number of laps recorded by this timer since begin().
u32 | getTicks ()
| Access the number of ticks within the current lap of this timer.
| SFBHWTimer (u8 index)
## Static Public Member Functions
static u32 | getSplitIndex ()
| Access the index number of the currently running split handler (see setSplitHandler).

## Detailed Description

The representation of a hardware timer.

Primarily accessed through the global variables Timer1 through Timer4.

## Member Function Documentation

void SFBHWTimer::begin | ( | u32 | usecsPerTick = `1000`,
|  | u32 | ticksPerLap = `1000`,
|  | bool | running = `false` |
| ) |  |  |

Power up and configure the timer.

The timer will be configured to tick every usecsPerTick microseconds (defaulting to 1000 and later modifiable by calling setTickTime), and will lap after every ticksPerLap ticks (defaulting to 1000 and later modifiable by calling setLap), and will be ticking if running is set (defaulting to `false`, and later modifiable by calling setRunning).

So, by default the timer will tick one thousand times a second, and will lap after each one thousand ticks, and so will lap once a second.

Parameters:

  | usecsPerTick | Number of microseconds per tick of the timer. Must be nonzero. Default value 1000.
  | ticksPerLap | Number of ticks per lap of the timer. Must be nonzero.
  | running | `true` if the timer should be started immediately, `false` if not (requiring a later call to start() or setRunning() to start the timer).

Blinks:
  E_API_NONZERO if usecsPerTick is zero

Blinks:
  E_API_NONZERO if ticksPerLap is zero

Side Effects:
  The associated hardware timer block is powered up, configured as indicated, and perhaps started.

Example:

         void setup() {
           Timer1.begin();    // Configure timer 1 using the default values
           Timer1.start();    // Start it running
         }
         void loop() {
           pprintf("t %d\n",seconds()-Timer1.getLaps());  // Printed number will (usually!) never change
           delay(1000);
         }

Example:

         void chime() { println("bong"); }
         void setup() {
           Timer2.begin(1,60*1000000U,true);  // Timer 2 ticks at 1MHz, laps each minute, starting now
           Timer2.setLapHandler(chime);       // Call chime once per minute
         }
         void loop() {
           pprintf("t %d\n",micros()-Timer2.getTicks());  // Number stays (nearly) constant in each minute
           delay(1000);
         }

Examples:
  timer1.cpp, timer2.cpp, timer3.cpp, and timer4.cpp.

u32 SFBHWTimer::getLap | ( |  | ) |

Access the number of ticks per lap.

Example:

         void setup() {
           Timer1.begin(123,456,true); // Tick each 123usecs, laps each 456 ticks, running
         }
         void loop() {
           println(Timer1.getLap());   // Prints 456
           delay(1000);
         }

HWTimerHandler SFBHWTimer::getLapHandler | ( |  | ) |

Access the lap handler, if any.

Returns:
  the last handler value supplied to setLapHandler on this splitIndex, or zero if setLapHandler has not been called

u32 SFBHWTimer::getSplit | ( | u32 | splitIndex | ) |

Access the number of ticks in a given split.

Example:

         void doNothing() { }
         void setup() {
           Timer1.begin();          // Tick each 123usecs, laps each 456 ticks, running
           Timer1.setSplitHandler(3,246,doNothing); // Set up split 3
         }
         void loop() {
           println(Timer1.getSplit(3));   // Prints 246
           delay(1000);
         }

HWTimerHandler SFBHWTimer::getSplitHandler | ( | u32 | splitIndex | ) |

Access the handler associated with a given split, if any.

Parameters:

  | splitIndex | The split to access, one of 1, 2, or 3.

Returns:
  the last handler value supplied to setSplitHandler on this splitIndex, or zero if setSplitHandler has never been called on this splitIndex

Blinks:
  E_API_NONZERO if splitIndex is zero

Blinks:
  E_API_MAX_RANGE if splitIndex is greater than 3

static u32 SFBHWTimer::getSplitIndex | ( |  | ) | `[inline, static]`

Access the index number of the currently running split handler (see setSplitHandler).

The returned is valid only during a callback to a split handler. Can be used to share a single handler function over multiple splits:

Example:

         void setLed() {
           ledSet(BODY_RGB_RED_PIN, Timer2.getSplitIndex()==1); // On on split 1, off on split 2
         }
         void setup() {
           Timer2.begin();                       // Configure 1ms per tick, 1 second per lap
           Timer2.setSplitHandler(1,300,setLed); // At 300ms per lap, call setLed
           Timer2.setSplitHandler(2,400,setLed); // At 400ms per lap, call setLed again
           Timer2.start();                       // Set the timer running
         }
         void loop() { }

Examples:
  timer4.cpp.

void SFBHWTimer::reset | ( | bool | alsoStop = `false` | ) |

Reset the timer, setting the tick counter to 0.

Optionally, also stop() it. Note this does not also reset the lap counter (as returned by getLaps); if that is desired begin() must be called again.

void SFBHWTimer::setLap | ( | u32 | ticksPerLap | ) |

Set the number of ticks per lap.

The minimum value of ticks is 1. The timer will reset to zero (and its getLaps() will increment) whenever the timer's counter equals ticks. Consequently, the period of the clock will be ticks times the tick rate.

In addition, note that whenever the number of ticks per lap is decreased relative to its previous value, the timer tick counter is automatically reset() to zero, without calling the lap handler or incrementing getLaps(). This avoids the risk of a 'runaway' timer, at the cost of an extra-long lap.

Parameters:

  | ticksPerLap | the number of ticks per lap. Must be at least one

Blinks:
  E_API_NONZERO if ticksPerLap is zero

Example:

         void flip() { ledToggle(BODY_RGB_BLUE_PIN); }
         void setup() {
           Timer1.begin();              // Timer 1 ticks at 1 KHz, laps each second
           Timer1.setLapHandler(flip);  // Toggle led each lap
           Timer1.start();              // Start it up
         }
         void loop() {
           if (buttonDown()) {
             u32 lap = Timer1.getLap(); // Get current ticks per lap
             if (lap > 1000) lap = 25;  // If too big, speed it up
             else lap++;                // else slow down the blinking
             Timer1.setLap(lap);        // Adjust lap length
           }
           delay(10);
         }

void SFBHWTimer::setLapHandler | ( | HWTimerHandler | handler | ) |

Specify that handler shall be called each time the timer laps.

If handler is zero, clears any end-of-period handler function. Note that handler will called with interrupts disabled! Keep its execution as short as possible, to minimize the disruption to other time-critical services (such as serial I/O, the master clock, etc).

Parameters:

  | handler | Function to call when the timer laps, or 0 to specify that no function should be called at end of lap.

Examples:
  timer1.cpp, timer2.cpp, timer3.cpp, and timer4.cpp.

void SFBHWTimer::setSplit | ( | u32 | splitIndex,
|  | u32 | ticks |
| ) |  |  |

Set the ticks of the splitIndex split time, without affecting any existing split time handelr.

setSplit can be called at any time without affecting the value of the timer tick counter (unlike setLap), but note that when a split's ticks value is being changed, the associated handler may or may not be called in the given lap, depending on the current value of the timer tick counter.

Parameters:

  | splitIndex | The split index to affect. Must be 1, 2, or 3.
  | ticks | The tick number within the lap to set this split to. Note that if ticks is greater than or equal to the number of ticks per lap (set by setLap() or begin()), that is not an error, but the split handler (if any) will never be called.

Blinks:
  E_API_NONZERO if splitIndex is zero

Blinks:
  E_API_MAX_RANGE if splitIndex is greater than 3

void SFBHWTimer::setSplitHandler | ( | u32 | splitIndex,
|  | u32 | ticks,
|  | HWTimerHandler | handler |
| ) |  |  |

Specify that handler shall be called whenever the clock reaches ticks within a given lap.

In addition to the overall lap time, a timer can have up to three split times, denoted by the splitIndex values of 1, 2, or 3 (Note: Not zero-based!). If handler is zero, specifies the given splitIndex is not in use. Note that the handler function will called at interrupt level, with interrupts disabled! Keep it very brief, to minimize disruptions to other time-sensitive services (such as I/O, the master clock, etc).

setSplitHandler can be called at any time without affecting the value of the timer tick counter (unlike setLap), but note that when a split's ticks value is being changed, the associated handler may or may not be called in the given lap, depending on the current value of the timer tick counter.

Parameters:

  | splitIndex | The split index to affect. Must be 1, 2, or 3.
  | ticks | The tick number within the lap to set this split to. Note that if ticks is greater than or equal to the number of ticks per lap (set by setLap() or begin()), that is not an error, but the handler will never be called.
  | handler | The function to call whenever the split time arrives, or 0 to disable the splitIndex split.

Blinks:
  E_API_NONZERO if splitIndex is zero

Blinks:
  E_API_MAX_RANGE if splitIndex is greater than 3

Examples:
  timer3.cpp, and timer4.cpp.

void SFBHWTimer::setTickTime | ( | u32 | usecsPerTick | ) |

Specify how long a single tick of the timer will take.

Minimum value is one microsecond, producing a timer that ticks at 1MHz. Maximum value `0xffffffff` produces a timer that ticks about once every 72 minutes.

Parameters:

  | usecsPerTick | Timer for one tick in microseconds. Must be at least one.

Blinks:
  E_API_NONZERO if usecsPerTick is zero

Side Effects:
  The 'prescaler' of associated hardware timer block, used to determine how fast the timer ticks, is configured as indicated.

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

- src/include/SFBHWTimer.h
- src/components/board/SFBHWTimer.cpp