WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

timer.h

Provides low level help with timers and compare channels.
If you are trying to measure time delays or get a current 'timer clock' value then you should be looking at clock.h. The functions here are for much lower-level use!
Timers, in general, are probably the most complex subject when dealing with microprocessors and trying to create code which can port from one device to another especially with the added complexity of different cpu speeds. Timers have different modes: but each timer may only support some of those modes, and each timer may have several channels/pins that are linked to it.
This library attempts to de-mystify some of the above by providing a more intelligent API than other libraries.
The library is aware of the AVR device you are using as well as the clock speed. The library also knows which timers are available for your selected device as well as the modes and channels that it supports.
At the end of the day the 'beginner' doesn't need to worry about this file. There are higher level functions elsewhere to achieve given tasks. So if all of this is going 'over the top of your head' then don't worry - read on...

 

Function

 


timerOverflowAttach(const Timer* timer, TimerCallback callback, void* user_data )

Register an overflow callback.
This registers a function that is called every time this timer overflows from TOP to BOTTOM. The final parameter is an optional pointer to some user defined data. The library doesn't chage this data, it is purely there for your own use and may be 'null' if there is none.
Each timer can only have one registered overflow callback routine at a time. If you need to change the callback (unlikely?) then you should use timerOverflowDetach(const Timer* timer) to remove any existing callback prior to calling this routine.

timerOverflowDetach(const Timer* timer)

Remove any overflow callback for the given timer.

timerOverflowClearInterruptPending(const Timer* timer)

Clears the timers 'overflow interrupt pending' flag.
Normally only required when reconfiguring a timer so don't use it unless you understand what this means!

boolean timerOverflowIsInterruptPending(const Timer* timer)

Test if an overflow interrupt is pending for the given timer.
It only makes sense to call this when interrupts are disabled or in an interrupt service routine as, if we are in the foreground, then the interrupt will trigger and we will never be able to test for it. This routine will return TRUE if an overflow interrupt is pending and will be triggered when interrupts are re-enabled.

boolean timerIsCaptureSupported(const Timer* timer)

Returns TRUE if this timer supports Input Capture.

timerCaptureAttach(const Timer* timer, TimerCallback callback, void* user_data, boolean risingEdge )

Register a capture callback.
This registers a function that is called every time the capture input pin for this timer goes low->high (if last parameter is TRUE) or high->low (if last parameter is FALSE) . The third parameter is an optional pointer to some user defined data. The library doesn't chage this data, it is purely there for your own use and may be 'null' if there is none.
Each timer can only have one registered capture callback routine at a time. If you need to change the callback (unlikely?) then you should use timerCaptureDetach(const Timer* timer) to remove any existing callback prior to calling this routine.

timerCaptureDetach(const Timer* timer)

Remove any capture callback for the given timer.

timerCaptureClearInterruptPending(const Timer* timer)

Clears the timers 'capture interrupt pending' flag.
Normally only required when reconfiguring a timer so don't use it unless you understand what this means!

boolean timerCaptureIsInterruptPending(const Timer* timer)

Test if a capture interrupt is pending for the given timer.
It only makes sense to call this when interrupts are disabled or in an interrupt service routine as, if we are in the foreground, then the interrupt will trigger and we will never be able to test for it. This routine will return TRUE if a capture interrupt is pending and will be triggered when interrupts are re-enabled.

const IOPin* timerGetCapturePin(const Timer* timer)

Returns the IOPin used for input capture.
If the timer does not support input capture mode, or the IOPin is not available on your system, then this will return null.

boolean timerSupportsCompare(const Timer* timer)

Does the timer have any compare units?
Return TRUE if the timer has at least one compare unit.

uint8_t timerNumberOfCompareUnits(const Timer* timer)

Returns the number of compare units provided by this timer.
Typically this will return a number between 0 and 3.

const TimerCompare* timerGetCompare(const Timer* timer, uint8_t channel)

Find the compare unit for a given timer.
Each timer typically has between 0 and 3 compare units.
The first parameter specifies the timer (eg TIMER0, TIMER1 etc) and the second parameter is the compare unit number from 0 up to 'timerNumberOfCompareUnits(const Timer* timer) - 1'.

TIMER_MODE timerGetMode(const Timer*timer)

Returns the current mode for a timer.
The modes are:
TIMER_MODE_NORMAL,
TIMER_MODE_PWM8_PHASE_CORRECT,
TIMER_MODE_PWM9_PHASE_CORRECT,
TIMER_MODE_PWM10_PHASE_CORRECT,
TIMER_MODE_CTC_OCR,
TIMER_MODE_PWM8_FAST,
TIMER_MODE_PWM9_FAST,
TIMER_MODE_PWM10_FAST,
TIMER_MODE_PWM_PHASE_FREQ_ICR,
TIMER_MODE_PWM_PHASE_FREQ_OCR,
TIMER_MODE_PWM_PHASE_CORRECT_ICR,
TIMER_MODE_PWM_PHASE_CORRECT_OCR,
TIMER_MODE_CTC_ICR,
TIMER_MODE_13_RESVD,
TIMER_MODE_PWM_FAST_ICR,
TIMER_MODE_PWM_FAST_OCR

timerSetMode(const Timer* timer, TIMER_MODE mode)

Set the operating mode for the given timer.
Only use this if you know that the timer is not currently in use ie 'timerIsInUse' returns FALSE. For a list of possible modes see timerGetMode(const Timer*timer)

boolean  timerIsModeSupported(const Timer* timer, TIMER_MODE mode)

Test if a timer supports a given mode of operation.
Some timers support all modes whilst others only support a subset of the possible modes.

uint16_t timerGetBestPrescaler(const Timer* timer, uint16_t repeat_ms)

Find the optimum prescaler value for the given timer in order to measure the given number of ms.
This function takes into account the different prescale options for the given timer and whether it is a 16 bit or 8 bit timer and will return the smallest prescale value capable of measuring the given delay taking into account the clock speed of the microprocessor.
This will return a value such as 1, 16, 64, 128 etc.

boolean  timerSupportsPrescaler(const Timer* timer, uint16_t prescaler)

Does the timer support the given prescaler value?

uint16_t timerGetCounter(const Timer* timer)

Returns the current counter value for the timer.
This always returns a 16 bit value but for an 8 bit timer the top byte will always be 0x00. This function should not be used to calculate durations as the actual timings will vary according to clock speeds, prescalers etc and there are other more friendly methods to this. It's main use is in other library functions when setting compare thresholds - see uartsw.c for an example.

uint16_t timerGetPrescaler(const Timer* timer)

Returns the current clock prescaler value for this timer.

timerSetPrescaler(const Timer* timer, uint16_t prescaler)

Set the clock prescaler value for the given timer.

uint16_t timerGetTOP(const Timer* timer)

Returns the current value of TOP for the given timer.
This is used by library routines such as the motor drivers in order to calculate the required compare unit value for a given duty cycle.

boolean timerIsInUse(const Timer* timer)

Test if a given timer is currently in use.

timerOff(const Timer* timer)

Tuen off the specified timer.
Use this with extreme caution! If you have used 'timerIsInUse' to locate an unused timer, and then return it to the timer pool via this call then all is ok. But don't suddenly turn off another timer at random since it may be used for motor control or for the clock.

boolean timerIs16bit(const Timer* timer)

Is the given timer a 16 bit timer?
Return TRUE if it is a 16 bit timer, or FALSE if it is an 8 bit timer.

compareAttach(const TimerCompare* channel, TimerCompareCallback callback, uint16_t threshold, void* data )

Attach a callback function to a compare unit.
Only one callback function can be registered per compare unit at a time - see compateDetach.
The callback function is called once the timer value reaches the threshold value. Note that if this value is greater than the value of TOP (as returned by timerGetTOP(const Timer* timer) ) then this will never happen and the callback will never be called.
The first parameter specifies which compare unit.
The second parameter is the address of your function that will be called. This function should have the following signature:
void myCallBack(const TimerCompare *timer_compare, void* data);
If you don't want a function to be called then use: &nullTimerCompareCallback
The third parameter specifies the value used to trigger the compare match.
The last parameter is for your own use and is often used to pass a reference to some data that needs to be passed into your callback function.

compareDetach(const TimerCompare* compare)

Removes any callback function from the given compare unit.

compareClearInterruptPending(const TimerCompare* channel)

Clears the 'interrupt pending' flag for the compare unit.
This is normally only used when interrupts are switched off for example when initialising the timer.

boolean compareIsInterruptPending(const TimerCompare* channel)

Test if the compare unit has set the 'interrupt pending' flag.
This is only of use when interrupts are turned off - otherwise the interrupt happens and the flag is cleared. So if this function returns TRUE then it means that as soon as interrupts are re-enabled then the callback routine will be called.

const TimerCompare* compareFromIOPin(const IOPin* pin)

Find the compare unit that can be used to toggle the specified IOPin.
Compare units can be used purely for timing purposes but more often they are used to output waveforms (such as PWM) on a given pin. Each compare unit is therefore associated with a given IO pin. This function allows you to locate the compare unit for a given IOPin. It will return 'null' if there is no compare unit associated.
Note that on some devices the same pin is used by more than one timer. In this case priority is given to the 16 bit timer.
For example on an Axon then calling: compareFromIOPin(H4) will return Timer 4 Channel B. However calling: compareFromIOPin(B7) should return Timer 0 Channel A but since this has no header pin on the Axon then it will return 'null'.

const IOPin* compareGetPin(const TimerCompare* channel)

Returns the IOPin associated with a given compare unit or null if there isn't one or it has no header pin on this board.
Also see:compareFromIOPin(const IOPin* pin) for the reverse action

uint16_t compareGetThreshold(const TimerCompare* channel)

Returns the threshold value for the given compare unit.

compareSetThreshold(const TimerCompare* channel, uint16_t threshold)

Changes the threshold value for the compare unit.

const Timer* compareGetTimer(const TimerCompare* compare)

Returns the Timer that this compare unit is associated with.

boolean compareIsInUse(const TimerCompare* channel)

Tests if a given compare unit is currently in use.
This is useful if you want to use a compare unit for timing purposes rather than generating a waveform on an IOPin. You can iterate through all the timers and compare units to locate one that is not currently in use.

CHANNEL_MODE compareGetOutputMode(const TimerCompare* channel)

Find the mode used for toggling the PWM output pin of a compare channel when the compare threshold is met.
This will return one of the following values:
CHANNEL_MODE_DISCONNECT - if the output pin is left unchanged
CHANNEL_MODE_TOGGLE - if the output pin is toggled
CHANNEL_MODE_NON_INVERTING - if the output pin is set low
CHANNEL_MODE_INVERTING - if the output pin is set high

compareSetOutputMode(const TimerCompare* channel, CHANNEL_MODE mode)

Sets the output mode of the compare unit.
The following modes are supported:
CHANNEL_MODE_DISCONNECT,
CHANNEL_MODE_TOGGLE,
CHANNEL_MODE_NON_INVERTING,
CHANNEL_MODE_INVERTING

uint8_t NUMBER_OF_TIMERS

A constant value representing the number of Timers in the microprocessor.
This can be used to iterate through the list of timers as follows:-
for(int8_t t=0; t<NUMBER_OF_TIMERS-1; t++){
const Timer * timer = &pgm_Timers[t];
}

Valid XHTML 1.0 Transitional