2.27 Timer Driver

2.27.1 Introduction

Overview

Timer is used to generate the timeout in a regular interval to do some specific task like LED blink, ADC read etc.Timer is used to generate the timeout in a regular interval to do some specific task like LED blink, ADC read etc.

Features

  • User configurable time out period.
  • Supports both polling and interrupt mode, default it gets configured in interrupt mode.
  • Timeout period value range varies based on the clock frequency of the timer clock source which can be selected from the PLIB.

2.27.2 How to Use the Timer Driver

The links below provide examples for different use cases of the Timer Driver, which can run on a number of different timer hardware instances.

For general instructions common to all examples, refer to this section: 2.27.6.1 Timer Use Case Code Snippet Instructions

2.27.3 Module Documentation

2.27.3.1 Timer Driver

Timer Driver is a 16-bit timer or 32-bit timer that can operate as a free-running interval timer using dsPIC MCUs.

2.27.3.1.1 Module description

Timer Driver is a 16-bit timer or 32-bit timer that can operate as a free-running interval timer using dsPIC MCUs.

2.27.3.1.1.1 Data structures

  • struct TIMER_INTERFACE

    Structure containing the function pointers of TIMER driver.

2.27.3.1.1.2 Definitions

  • #define TIMER_PERIODCOUNTSET_API_SUPPORT false

    Defines the deprecated SCCPx_Timer_PeriodCountSet or TMRx_PeriodCountSet API. Set it to true for backward compatibility.

2.27.3.1.1.3 Functions

  • void TMR1_Initialize (void)

    Initializes the TMR1 module.

  • void TMR1_Deinitialize (void)

    Deinitializes the TMR1 to POR values.

  • void TMR1_Start (void)

    Starts the timer.

  • void TMR1_Stop (void)

    Stops the timer.

  • void TMR1_PeriodSet (uint32_t count)

    Sets the TMR1 period count value.

  • static uint32_t TMR1_PeriodGet (void)

    This inline function gets the TMR1 period count value.

  • static uint32_t TMR1_CounterGet (void)

    This inline function gets the TMR1 elapsed time value.

  • static uint16_t TMR1_Counter16BitGet (void)

    This inline function gets the 16 bit TMR1 elapsed time value.

  • void TMR1_InterruptPrioritySet (enum INTERRUPT_PRIORITY priority)

    Sets the TMR1 interrupt priority value.

  • void TMR1_TimeoutCallbackRegister (void(*handler)(void))

    This function can be used to override default callback and to define custom callback for TMR1 Timeout event.

  • void TMR1_TimeoutCallback (void)

    This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using TMR1_TimeoutCallbackRegister.

2.27.3.1.1.4 Variables

  • const struct TIMER_INTERFACE Timer1

    Structure object of type TIMER_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. Timer1 can be changed by the user in the TIMER user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

2.27.3.1.2 Definition Documentation

2.27.3.1.2.1 TIMER_PERIODCOUNTSET_API_SUPPORT

#define TIMER_PERIODCOUNTSET_API_SUPPORT false

Defines the deprecated SCCPx_Timer_PeriodCountSet or TMRx_PeriodCountSet API. Set it to true for backward compatibility.

2.27.3.1.3 Function Documentation

2.27.3.1.3.1 TMR1_Counter16BitGet()

inline static uint16_t TMR1_Counter16BitGet (void )

This inline function gets the 16 bit TMR1 elapsed time value.

Parameters:
none.
Returns:

16 bit elapsed count value of the timer.

2.27.3.1.3.2 TMR1_CounterGet()

inline static uint32_t TMR1_CounterGet (void )

This inline function gets the TMR1 elapsed time value.

Parameters:
none.
Returns:

Elapsed count value of the timer.

2.27.3.1.3.3 TMR1_Deinitialize()

void TMR1_Deinitialize (void )

Deinitializes the TMR1 to POR values.

Parameters:
none.
Returns:

none.

2.27.3.1.3.4 TMR1_Initialize()

void TMR1_Initialize (void )

Initializes the TMR1 module.

Parameters:
none.
Returns:

none.

2.27.3.1.3.5 TMR1_InterruptPrioritySet()

void TMR1_InterruptPrioritySet (enum INTERRUPT_PRIORITY priority)

Sets the TMR1 interrupt priority value.

Parameters:
in priority

- value of interrupt priority.

Returns:

none.

2.27.3.1.3.6 TMR1_PeriodGet()

inline static uint32_t TMR1_PeriodGet (void )

This inline function gets the TMR1 period count value.

Parameters:
none.
Returns:

Number of clock counts.

2.27.3.1.3.7 TMR1_PeriodSet()

void TMR1_PeriodSet (uint32_t count)

Sets the TMR1 period count value.

Parameters:
in count

- number of clock counts.

Returns:

none.

2.27.3.1.3.8 TMR1_Start()

void TMR1_Start (void )

Starts the timer.

Precondition:

TMR1_Initialize must be called.

Parameters:
none.
Returns:

none.

2.27.3.1.3.9 TMR1_Stop()

void TMR1_Stop (void )

Stops the timer.

Precondition:

TMR1_Initialize must be called.

Parameters:
none.
Returns:

none.

2.27.3.1.3.10 TMR1_TimeoutCallback()

void TMR1_TimeoutCallback (void )

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using TMR1_TimeoutCallbackRegister.

Parameters:
none.
Returns:

none.

2.27.3.1.3.11 TMR1_TimeoutCallbackRegister()

void TMR1_TimeoutCallbackRegister (void(*)(void) handler)

This function can be used to override default callback and to define custom callback for TMR1 Timeout event.

Parameters:
in handler

- Address of the callback function.

Returns:

none.

2.27.3.1.4 Variable Documentation

2.27.3.1.4.1 Timer1

const struct TIMER_INTERFACE Timer1

Structure object of type TIMER_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. Timer1 can be changed by the user in the TIMER user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

2.27.4 Class Documentation

2.27.4.1 TIMER_INTERFACE Struct Reference

Structure containing the function pointers of TIMER driver.

2.27.4.1.1 Detailed Description

Structure containing the function pointers of TIMER driver.

#include <timer_interface.h>

2.27.4.1.1.1 Public Attributes

  • void(* Initialize )(void)

    Pointer to MCCPx_Timer_Initialize or SCCPx_Timer_Initialize or TMRx_Initialize e.g. SCCP1_Timer_Initialize or TMR1_Initialize.

  • void(* Deinitialize )(void)

    Pointer to MCCPx_Timer_Deinitialize or SCCPx_Timer_Deinitialize or TMRx_Deinitialize e.g. SCCP1_Timer_Deinitialize or TMR1_Deinitialize.

  • void(* Start )(void)

    Pointer to MCCPx_Timer_Start or SCCPx_Timer_Start or TMRx_Start e.g. SCCP1_Timer_Start or TMR1_Start.

  • void(* Stop )(void)

    Pointer to MCCPx_Timer_Stop or SCCPx_Timer_Stop or TMRx_Stop e.g. SCCP1_Timer_Stop or TMR1_Stop.

  • void(* PeriodSet )(uint32_t count)

    Pointer to MCCPx_Timer_PeriodSet or SCCPx_Timer_PeriodSet or TMRx_PeriodSet e.g. SCCP1_Timer_PeriodSet or TMR1_PeriodSet.

  • uint32_t(* PeriodGet )(void)

    Pointer to MCCPx_Timer_PeriodGet or SCCPx_Timer_PeriodGet or TMRx_PeriodGet e.g. SCCP1_Timer_PeriodGet or TMR1_PeriodGet.

  • uint32_t(* CounterGet )(void)

    Pointer to MCCPx_Timer_CounterGet or SCCPx_Timer_CounterGet or TMRx_CounterGet e.g. SCCP1_Timer_CounterGet or TMR1_CounterGet.

  • void(* InterruptPrioritySet )(enum INTERRUPT_PRIORITY priority)

    Pointer to MCCPx_Timer_InterruptPrioritySet or SCCPx_Timer_InterruptPrioritySet or TMRx_InterruptPrioritySet e.g. SCCP1_Timer_InterruptPrioritySet or TMR1_InterruptPrioritySet.

  • void(* TimeoutCallbackRegister )(void(*CallbackHandler)(void))

    Pointer to MCCPx_TimeoutCallbackRegister or SCCPx_TimeoutCallbackRegister or TMRx_TimeoutCallbackRegister e.g. SCCP1_TimeoutCallbackRegister or TMR1_TimeoutCallbackRegister.

  • void(* Tasks )(void)

    Pointer to MCCPx_Timer_Tasks or SCCPx_Timer_Tasks or TMRx_Tasks e.g. SCCP1_Timer_Tasks or TMR1_Tasks (Supported only in polling mode)

2.27.4.1.2 Member Data Documentation

The documentation for this struct was generated from the following file:

source/

timer_interface.h

2.27.4.1.2.1 CounterGet

uint32_t(* CounterGet) (void)

Pointer to MCCPx_Timer_CounterGet or SCCPx_Timer_CounterGet or TMRx_CounterGet e.g. SCCP1_Timer_CounterGet or TMR1_CounterGet.

2.27.4.1.2.2 Deinitialize

void(* Deinitialize) (void)

Pointer to MCCPx_Timer_Deinitialize or SCCPx_Timer_Deinitialize or TMRx_Deinitialize e.g. SCCP1_Timer_Deinitialize or TMR1_Deinitialize.

2.27.4.1.2.3 Initialize

void(* Initialize) (void)

Pointer to MCCPx_Timer_Initialize or SCCPx_Timer_Initialize or TMRx_Initialize e.g. SCCP1_Timer_Initialize or TMR1_Initialize.

2.27.4.1.2.4 InterruptPrioritySet

void(* InterruptPrioritySet) (enum INTERRUPT_PRIORITY priority)

Pointer to MCCPx_Timer_InterruptPrioritySet or SCCPx_Timer_InterruptPrioritySet or TMRx_InterruptPrioritySet e.g. SCCP1_Timer_InterruptPrioritySet or TMR1_InterruptPrioritySet.

2.27.4.1.2.5 PeriodGet

uint32_t(* PeriodGet) (void)

Pointer to MCCPx_Timer_PeriodGet or SCCPx_Timer_PeriodGet or TMRx_PeriodGet e.g. SCCP1_Timer_PeriodGet or TMR1_PeriodGet.

2.27.4.1.2.6 PeriodSet

void(* PeriodSet) (uint32_t count)

Pointer to MCCPx_Timer_PeriodSet or SCCPx_Timer_PeriodSet or TMRx_PeriodSet e.g. SCCP1_Timer_PeriodSet or TMR1_PeriodSet.

2.27.4.1.2.7 Start

void(* Start) (void)

Pointer to MCCPx_Timer_Start or SCCPx_Timer_Start or TMRx_Start e.g. SCCP1_Timer_Start or TMR1_Start.

2.27.4.1.2.8 Stop

void(* Stop) (void)

Pointer to MCCPx_Timer_Stop or SCCPx_Timer_Stop or TMRx_Stop e.g. SCCP1_Timer_Stop or TMR1_Stop.

2.27.4.1.2.9 Tasks

void(* Tasks) (void)

Pointer to MCCPx_Timer_Tasks or SCCPx_Timer_Tasks or TMRx_Tasks e.g. SCCP1_Timer_Tasks or TMR1_Tasks (Supported only in polling mode)

2.27.4.1.2.10 TimeoutCallbackRegister

void(* TimeoutCallbackRegister) (void(*CallbackHandler)(void))

Pointer to MCCPx_TimeoutCallbackRegister or SCCPx_TimeoutCallbackRegister or TMRx_TimeoutCallbackRegister e.g. SCCP1_TimeoutCallbackRegister or TMR1_TimeoutCallbackRegister.

2.27.5 File Documentation

2.27.5.1 source/timer_interface.h File Reference

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "../system/interrupt_types.h"

2.27.5.1.1 Data structures

  • struct TIMER_INTERFACE

    Structure containing the function pointers of TIMER driver.

2.27.5.1.2 Macros

  • #define TIMER_PERIODCOUNTSET_API_SUPPORT false

    Defines the deprecated SCCPx_Timer_PeriodCountSet or TMRx_PeriodCountSet API. Set it to true for backward compatibility.

2.27.5.1.3 Detailed Description

TIMER Generated Driver Interface Header File

2.27.5.2 source/tmr1.h File Reference

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

#include <stddef.h>
#include <stdint.h>
#include <xc.h>
#include "timer_interface.h"

2.27.5.2.1 Functions

  • void TMR1_Initialize (void)

    Initializes the TMR1 module.

  • void TMR1_Deinitialize (void)

    Deinitializes the TMR1 to POR values.

  • void TMR1_Start (void)

    Starts the timer.

  • void TMR1_Stop (void)

    Stops the timer.

  • void TMR1_PeriodSet (uint32_t count)

    Sets the TMR1 period count value.

  • static uint32_t TMR1_PeriodGet (void)

    This inline function gets the TMR1 period count value.

  • static uint32_t TMR1_CounterGet (void)

    This inline function gets the TMR1 elapsed time value.

  • static uint16_t TMR1_Counter16BitGet (void)

    This inline function gets the 16 bit TMR1 elapsed time value.

  • void TMR1_InterruptPrioritySet (enum INTERRUPT_PRIORITY priority)

    Sets the TMR1 interrupt priority value.

  • void TMR1_TimeoutCallbackRegister (void(*handler)(void))

    This function can be used to override default callback and to define custom callback for TMR1 Timeout event.

  • void TMR1_TimeoutCallback (void)

    This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using TMR1_TimeoutCallbackRegister.

2.27.5.2.2 Variables

  • const struct TIMER_INTERFACE Timer1

    Structure object of type TIMER_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. Timer1 can be changed by the user in the TIMER user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

2.27.5.2.3 Detailed Description

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

TMR1 Generated Driver Header File

2.27.6 Timer Use Cases

2.27.6.1 Timer Use Case Code Snippet Instructions

The use cases show example uses of the Timer Driver, within a MCC Melody project:

  • Add Timer(TMR1) to the project

  • Configure:

    1. Timer as described in the example.

    2. Any other peripherals or pins needed for the use case.

  • Generate the code

  • Add the code snippet(s) to the application code

  • Program the board

  • Note: The main clock is asumed to use the FRC Oscillator as a clock source. In these use cases the Timer is configured to run asynchronously from the main clock, using the FOSC/2 (Peripheral Frequency).

2.27.6.2 Timer Use Case 1: 100 ms Timer

This use-case configures Timer (TMR1) to generate an overflow interrupt at a period of 100ms, toggling a LED at this period.

Timer Settings
  • Timer > Software Settings:

    1. Requested Timer Period(ms): 100(ms).

  • Timer > Interrupt Settings:

    1. Interrupt Driven: Yes.

System Settings
  • System > Pins (for all pins check board schematics):

    1. Pin Grid View: Select one GPIO Pin as LED Output (Check board schematic).

    2. Pins: Rename Custom Name of selected GPIO Pin to "LED" respectively.  

#include "mcc_generated_files/system/system.h"
#include "mcc_generated_files/timer/tmr1.h"
#include "mcc_generated_files/system/pins.h"

/* Create a pointer of type TMR_INTERFACE and assign it to the address of the Timer1 TIMER_INTERFACE struct.
This enables us to get access the portable API interface, which ensures that it's easy to change the peripheral instance the timer runs on. */
const struct TIMER_INTERFACE *Timer = &Timer1;

void Timer_Callback_100ms(void)
{
    LED_Toggle();
}

int main(void)
{
    SYSTEM_Initialize();
    Timer->TimeoutCallbackRegister(Timer_Callback_100ms);
    while(1)
    {
        
    }
}

2.27.6.3 Timer Use Case 2: Timer Switch Frequency 100 ms / 500 ms

This use case toggles the time-out period between 100 ms and 500 ms, when the switch is pressed.

Timer Settings
  • Timer > Software Settings:

    1. Requested Timer Period(ms): 500(ms).  

  • Timer > Interrupt Settings:

    1. TMR Interrupt: Yes.

System Settings
  • System > Pins (for all pins check board schematics):

    1. Pin Grid View: Select one GPIO Pin as LED Output  

    2. Pins: Rename Custom Name of selected GPIO Pin to "LED".  

    3. Pin Grid View: Select one GPIO Pin as Switch INPUT.

    4. Pins: Rename Custom Name of selected GPIO Pin to "SW".

    5. Pins: Enable Weak Pullup if needed  

    6. Pins: Switch Input Pin -> Interrupt on Change: Sense negative/positive on switch press

#define     FCY         CLOCK_PeripheralFrequencyGet()
#include <libpic30.h>
#include "mcc_generated_files/system/clock.h"
#include "mcc_generated_files/system/system.h"
#include "mcc_generated_files/timer/tmr1.h"
#include "mcc_generated_files/system/pins.h"

/* Create a pointer of type TMR_INTERFACE and assign it to the address of the Timer1 TIMER_INTERFACE struct.
This enables us to get access the portable API interface, which ensures that it's easy to change the peripheral instance the timer runs on. */
const struct TIMER_INTERFACE *Timer = &Timer1;

#define LED_500ms (0x7A11)
#define LED_100ms (0x1869)
volatile bool CHANGE_PERIOD = false;
volatile bool PERIOD_500ms = true;  /*Global variable to check the current period value*/

void Timer_Callback(void)
{
    LED_Toggle();
}

void SW_CallBack(void)
{
    CHANGE_PERIOD = true;
}

void Timer_Change_Frequency(void){
    Timer->Stop();
    if(PERIOD_500ms)
    {
        TMR1 = 0x0;   //Restart the timer
        Timer->PeriodSet(LED_100ms);
        PERIOD_500ms = false;
    }
    else
    {
        TMR1 = 0x0;   //Restart the timer
        Timer->PeriodSet(LED_500ms);
        PERIOD_500ms = true;
    }
    Timer->Start();
}

int main(void)
{
    SYSTEM_Initialize();
    Timer->TimeoutCallbackRegister(Timer_Callback);
    
    SW_SetInterruptHandler(SW_CallBack);   /* Select for SW pin you are using */
    
    while(1)
    {
        if(CHANGE_PERIOD)
        {
            Timer_Change_Frequency();
            __delay_ms(100);    //De-bounce delay
            CHANGE_PERIOD = false;
        }
    }
}