3.24.3.1 TMR2

Timer2

3.24.3.1.1 Introduction

The Timer2 (TMR2) module is a 8-bit timer that operates by a matching the value written to a configurable 8-bit period register. It has adjustable prescaler, postscaler, and the added feature of interrupt triggers.

3.24.3.1.2 Supported Device Families

PIC12/16F150xPIC12/16F157xPIC12/16F184x
PIC12/16LF155xPIC16F145xPIC16F151x
PIC16F152xPIC16F170xPIC16F171x
PIC16F178xPIC16F183xxPIC16F194x
PIC16LF156xPIC18F-K20PIC18F-K22
PIC18F-K50PIC18F-K80PIC18F-K90

3.24.3.1.3 Required header files:

#include "mcc_generated_files/timer/tmr2.h"

3.24.3.1.4 How to use the Timer 2 PLIB

Click the links to view the code snippets associated with each example:

3.24.3.1.5 Specific MISRA C:2012 Deviations

Global TMR2_MAX_COUNT

Advisory: misra-c2012-2.5  

Justification: MCC Melody drivers provide macros that can be added to an application. It depends on the application whether a macro is used or not.

Advisory: misra-c2012-2.5  

Justification: MCC Melody drivers provide macros that can be added to an application. It depends on the application whether a macro is used or not.

Global TMR2_Read

Advisory: misra-c2012-2.5  

Justification: MCC Melody drivers provide macros that can be added to an application. It depends on the application whether a macro is used or not.

3.24.3.1.6 Module Documentation

TMR2

This file contains the API prototypes and other data types for the Timer2 (TMR2) driver.

Module description

This file contains the API prototypes and other data types for the Timer2 (TMR2) driver.

This file contains the API prototypes and other data types for the TMR2 driver.

Version: Driver Version 2.0.0 Package Version 2.0.0 TMR2 Driver Version 2.0.0 Package Version 2.0.0
Definitions
Functions

Definition Documentation

TIMER2_CLOCK_FREQ

#define TIMER2_CLOCK_FREQ TMR2_CLOCK_FREQ

Defines the Custom Name for the TMR2_CLOCK_FREQ.

Timer2_CounterGet

#define Timer2_CounterGet TMR2_CounterGet

Defines the Custom Name for the TMR2_CounterGet API.

Timer2_CounterSet

#define Timer2_CounterSet TMR2_CounterSet

Defines the Custom Name for the TMR2_CounterSet API.

Timer2_Deinitialize

#define Timer2_Deinitialize TMR2_Deinitialize

Defines the Custom Name for the TMR2_Deinitialize API.

Timer2_Initialize

#define Timer2_Initialize TMR2_Initialize

Defines the Custom Name for the TMR2_Initialize API.

Timer2_ISR

#define Timer2_ISR TMR2_ISR

Defines the Custom Name for the TMR2_ISR API.

TIMER2_MAX_COUNT

#define TIMER2_MAX_COUNT TMR2_MAX_COUNT

Defines the Custom Name for the TMR2_MAX_COUNT.

Timer2_MaxCountGet

#define Timer2_MaxCountGet TMR2_MaxCountGet

Defines the Custom Name for the TMR2_MaxCountGet API.

Timer2_OverflowCallbackRegister

#define Timer2_OverflowCallbackRegister TMR2_PeriodMatchCallbackRegister

Defines the Custom Name for the TMR2_PeriodMatchCallbackRegister API. The Timer2_OverflowCallbackRegister will be deprecated in the future release. Use Timer2_PeriodMatchCallbackRegister instead.

Timer2_PeriodCountSet

#define Timer2_PeriodCountSet TMR2_PeriodSet

Defines the Custom Name for the TMR2_PeriodSet API. The Timer2_PeriodCountSet will be deprecated in the future release. Use Timer2_PeriodSet instead.

Timer2_PeriodGet

#define Timer2_PeriodGet TMR2_PeriodGet

Defines the Custom Name for the TMR2_PeriodGet API.

Timer2_PeriodMatchCallbackRegister

#define Timer2_PeriodMatchCallbackRegister TMR2_PeriodMatchCallbackRegister

Defines the Custom Name for the TMR2_PeriodMatchCallbackRegister API.

Timer2_PeriodMatchStatusClear

#define Timer2_PeriodMatchStatusClear TMR2_PeriodMatchStatusClear

Defines the Custom Name for the TMR2_PeriodMatchStatusClear API.

Timer2_PeriodMatchStatusGet

#define Timer2_PeriodMatchStatusGet TMR2_PeriodMatchStatusGet

Defines the Custom Name for the TMR2_PeriodMatchStatusGet API.

Timer2_PeriodSet

#define Timer2_PeriodSet TMR2_PeriodSet

Defines the Custom Name for the TMR2_PeriodSet API.

Timer2_Read

#define Timer2_Read TMR2_CounterGet

Defines the Custom Name for the TMR2_CounterGet API. The Timer2_Read will be deprecated in the future release. Use Timer2_CounterGet instead.

Timer2_Start

#define Timer2_Start TMR2_Start

Defines the Custom Name for the TMR2_Start API.

Timer2_Stop

#define Timer2_Stop TMR2_Stop

Defines the Custom Name for the TMR2_Stop API.

Timer2_Tasks

#define Timer2_Tasks TMR2_Tasks

Defines the Custom Name for the TMR2_Tasks API.

Timer2_Write

#define Timer2_Write TMR2_CounterSet

Defines the Custom Name for the TMR2_CounterSet API. The Timer2_Write will be deprecated in the future release. Use Timer2_CounterSet instead.

TMR2_CLOCK_FREQ

#define TMR2_CLOCK_FREQ (250000UL)

Defines the timer prescaled clock frequency in hertz.

TMR2_MAX_COUNT

#define TMR2_MAX_COUNT (255U)

Defines the maximum count value of the timer.

MISRA C:2012 Deviation Advisory: misra-c2012-2.5  

Justification: MCC Melody drivers provide macros that can be added to an application. It depends on the application whether a macro is used or not.

TMR2_OverflowCallbackRegister

#define TMR2_OverflowCallbackRegister TMR2_PeriodMatchCallbackRegister

Defines the Custom Name for the TMR2_PeriodMatchCallbackRegister API. The TMR2_OverflowCallbackRegister will be deprecated in the future release. Use TMR2_PeriodMatchCallbackRegister instead.

TMR2_PeriodCountSet

#define TMR2_PeriodCountSet TMR2_PeriodSet

Defines the Custom Name for the TMR2_PeriodSet API. The TMR2_PeriodCountSet will be deprecated in the future release. Use TMR2_PeriodSet instead.

TMR2_Read

#define TMR2_Read TMR2_CounterGet

Defines the Custom Name for the TMR2_CounterGet API. The TMR2_Read will be deprecated in the future release. Use TMR2_CounterGet instead.

MISRA C:2012 Deviation Advisory: misra-c2012-2.5  

Justification: MCC Melody drivers provide macros that can be added to an application. It depends on the application whether a macro is used or not.

TMR2_Write

#define TMR2_Write TMR2_CounterSet

Defines the Custom Name for the TMR2_CounterSet API. The TMR2_Write will be deprecated in the future release. Use TMR2_CounterSet instead.

Function Documentation

TMR2_CounterGet()

uint8_t TMR2_CounterGet (void )

Returns the current counter value.

Precondition:

Initialize TMR2 with TMR2_Initialize() before calling this API.

Parameters:
None.
Returns:

Counter value from the TMR2 register

TMR2_CounterSet()

void TMR2_CounterSet (uint8_t counterValue)

Sets the counter value.

Precondition:

Initialize TMR2 with TMR2_Initialize before calling this API.

Parameters:
counterValue

- Counter value to be written to the TMR2 register

Returns:

None.

TMR2_Deinitialize()

void TMR2_Deinitialize (void )

Deinitializes the TMR2 module.

Parameters:
None.
Returns:

None.

TMR2_Initialize()

void TMR2_Initialize (void )

Initializes the TMR2 module. This routine must be called before any other TMR2 routines.

Parameters:
None.
Returns:

None.

Section: TMR2 APIs

TMR2_ISR()

void TMR2_ISR (void )

Interrupt Service Routine (ISR) for the TMR2 Period Match Interrupt.

Parameters:
None.
Returns:

None.

TMR2_MaxCountGet()

uint8_t TMR2_MaxCountGet (void )

Returns the maximum count value.

Parameters:
None.
Returns:

Maximum count value

TMR2_PeriodGet()

uint8_t TMR2_PeriodGet (void )

Returns the current period value.

Precondition:

Initialize TMR2 with TMR2_Initialize before calling this API.

Parameters:
None.
Returns:

Period count value from the PR2 register

TMR2_PeriodMatchCallbackRegister()

void TMR2_PeriodMatchCallbackRegister (void(*)(void) CallbackHandler)

Setter function for the TMR2 period match callback.

Parameters:
CallbackHandler

- Address of the custom callback function

Returns:

None.

TMR2_PeriodMatchStatusClear()

void TMR2_PeriodMatchStatusClear (void )

Clears the TMR2 Period Match Interrupt flag.

Parameters:
None.
Returns:

None.

TMR2_PeriodMatchStatusGet()

bool TMR2_PeriodMatchStatusGet (void )

Returns the status of the TMR2 Period Match Interrupt flag.

Parameters:
None.
Returns:

Interrupt flag status

TMR2_PeriodSet()

void TMR2_PeriodSet (uint8_t periodCount)

Sets the period value.

Precondition:

Initialize TMR2 with TMR2_Initialize before calling this API.

Parameters:
periodCount

- Period count value written to the PR2 register

Returns:

None.

TMR2_Start()

void TMR2_Start (void )

Starts the TMR2 timer.

Precondition:

Initialize TMR2 with TMR2_Initialize before calling this API.

Parameters:
None.
Returns:

None.

TMR2_Stop()

void TMR2_Stop (void )

Stops the TMR2 timer.

Precondition:

Initialize TMR2 with TMR2_Initialize before calling this API.

Parameters:
None.
Returns:

None.

TMR2_Tasks()

void TMR2_Tasks (void )

Performs tasks to be executed during the Period Match Interrupt event.

Parameters:
None.
Returns:

None.

3.24.3.1.7 Tmr2_example

This section explains various use case examples of the Timer module within an MPLAB® Code Configurator (MCC) Melody Project.

TMR2 PLIB Examples

4 ms/8 ms Timer Period Change in Non-Interrupt Mode

This use case configures the TMR2 PLIB to generate the timer period. The period of a timer is changed at run time during each overflow event. The callback function is used to change the timer period.

System Configuration
  • System>Clock Control:

    • Clock Source: FOSC

    • HF Internal Clock: 1MHz_HFINTOSC/16 (1 MHz)

  • System>Pins:

    • Pin Grid View: Select LED pin as output (Check the schematic for your board)

    • Pins: Rename Custom Name to "LED"

Timer Configuration
  • Drivers>TMR2:

    • Timer Enable: False

    • Prescaler: 1:4

    • Postscaler: 1:2

    • TMR Interrupt Enable: False

After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:

#include "mcc_generated_files/system/system.h"

/*
 * Development Board: Explorer 8 Development Board
 * MCC Configuration:
 *     System module: 1MHz_HFINTOSC/16 (1 MHz)
 *     TMR2 module: Timer Enable - False, Prescaler - 1:4, Postscaler - 1:2, TMR Interrupt Enable - False
 *     Pins module: RD1 - GPIO Output, CustomName - LED 
 */
 
#define USE_TASKS_API 1
#define POSTSCALER 2UL
#define MS_TO_TICKS(ms) (((TMR2_CLOCK_FREQ * (ms)) / 1000UL) - 1UL)
#define LED_4_MS (MS_TO_TICKS(4UL))
#define LED_8_MS (MS_TO_TICKS(8UL))

static void Timer_PeriodChange(void)
{ 
    static volatile bool changePeriod = false;
    LED_Toggle();
    
    uint8_t maxCount = TMR2_MaxCountGet();
    uint8_t newPeriod = changePeriod ? LED_4_MS:LED_8_MS;
    
    if(maxCount > newPeriod)
    {      
        TMR2_PeriodSet(newPeriod);
    }
    else
    {
        // Invalid period
    }
    changePeriod = !changePeriod;
}

int main(void)
{
    SYSTEM_Initialize();

    TMR2_PeriodSet(LED_4_MS);   
    TMR2_PeriodMatchStatusClear();
    
#if USE_TASKS_API    
    TMR2_PeriodMatchCallbackRegister(Timer_PeriodChange);
#endif
    TMR2_Start();
    
    while(1)
    {
#if   USE_TASKS_API
        TMR2_Tasks();
#else
        if(1U == TMR2_PeriodMatchStatusGet())
        {
            Timer_PeriodChange();
            TMR2_PeriodMatchStatusClear();
        }
#endif
    }    
}

4 ms Timer Period in Interrupt Mode

This use case configures the TMR2 PLIB to generate the overflow interrupt at a period of 4 ms while toggling an LED. This use case uses the generated APIs to set the timer period.

System Configuration
  • System>Clock Control:

    • Clock Source: FOSC

    • HF Internal Clock: 1MHz_HFINTOSC/16 (1 MHz)

  • System>Pins:

    • Pin Grid View: Select LED pin as output (Check the schematic for your board)

    • Pins: Rename Custom Name to "LED"

Timer Configuration
  • Drivers>TMR2:

    • Timer Enable: True

    • Prescaler: 1:4

    • Postscaler: 1:2

    • TMR Interrupt Enable: True

After configuring the components as described above, click 'Generate' to generate the code. Then add the following code snippets to your application:

#include "mcc_generated_files/system/system.h"

/*
 * Development Board: Explorer 8 Development Board
 * MCC Configuration:
 *     System module: 1MHz_HFINTOSC/16 (1 MHz)
 *     TMR2 module: Timer Enable - True, Prescaler - 1:4, Postscaler - 1:2, TMR Interrupt Enable - True
 *     Pins module: RD1 - GPIO Output, CustomName - LED 
 */
 
#define POSTSCALER 2UL
#define MS_TO_TICKS(ms) (((TMR2_CLOCK_FREQ * (ms)) / 1000UL) - 1UL)
#define LED_4_MS  (MS_TO_TICKS(4UL))

void Custom_Callback(void)
{
    LED_Toggle();
}

int main(void)
{
    SYSTEM_Initialize();

    const uint8_t maxCount = TMR2_MaxCountGet();
    TMR2_CounterSet(0);
    
    if(maxCount > LED_4_MS)
    {
        TMR2_PeriodSet(LED_4_MS);
    }
    else 
    {
        //Invalid period        
    }
    
    TMR2_PeriodMatchCallbackRegister(Custom_Callback);
    TMR2_Start();
    
    INTERRUPT_GlobalInterruptEnable();
    INTERRUPT_PeripheralInterruptEnable();
    
    while(1)
    {
    }    
}

3.24.3.1.8 File Documentation

source/tmr2.c File Reference

This file contains the API implementation for the TMR2 module. 

#include <xc.h>
#include "../tmr2.h"

Functions

Detailed Description

This file contains the API implementation for the TMR2 module.

This file contains the Timer driver implementation for the TMR2 driver.

TMR2 Generated Driver File

Version: Driver Version 2.0.0 Package Version 2.0.0

TMR2 Generated Timer Driver File

Version: TMR2 Timer Driver Version 2.0.0 Package Version 2.0.0

Function Documentation

TMR2_DefaultPeriodMatchCallback()

static void TMR2_DefaultPeriodMatchCallback (void )[static]

Variable Documentation

TMR2_PeriodMatchCallback

void(* TMR2_PeriodMatchCallback) (void)[static]

source/tmr2.h File Reference

This file contains the API prototypes and other data types for the Timer2 (TMR2) driver. 

#include <stdint.h>
#include <stdbool.h>
#include "tmr2_deprecated.h"

Functions

Macros

Detailed Description

This file contains the API prototypes and other data types for the Timer2 (TMR2) driver.

TMR2 Generated Driver API Header File

TMR2 Generated Driver API Header File

Version: TMR2 Driver Version 2.0.0 Package Version 2.0.0

source/tmr2_deprecated.h File Reference

Macros

source/tmr2_drv.c File Reference

#include <xc.h>
#include "../tmr2.h"

Functions

Function Documentation

TMR2_DefaultPeriodMatchCallback()

static void TMR2_DefaultPeriodMatchCallback (void )[static]

Variable Documentation

TMR2_PeriodMatchCallback

void(* TMR2_PeriodMatchCallback) (void)[static]

source/tmr2_drv.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include "timer_interface.h"

Functions

Macros

Variable Documentation

Timer2

const struct TIMER_INTERFACE Timer2

Section: Included Files

source/tmr2_example.dox File Reference