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)
void reinitForPCLK ()

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, 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 value 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 be 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:
Generated on Fri Apr 22 06:57:19 2011 for SFB by doxygen 1.5.9