3.23 Timer Driver

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.

3.23.1 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: 3.23.5.1.1 Timer Use Case Code Snippet Instructions

3.23.2 Module Documentation

3.23.2.1 DELAY BLOCKING DRIVER

This file contains the API to generate delays in the range of milliseconds and microseconds.

3.23.2.1.1 Module description

This file contains the API to generate delays in the range of milliseconds and microseconds.

Version: DELAY Driver Version 1.1.0
Functions

  • void DELAY_milliseconds (uint16_t milliseconds)

    Delays the execution of the program for a certain number of milliseconds.

  • void DELAY_microseconds (uint16_t microseconds)

    Delays the execution of the program for a certain number of microseconds.

3.23.2.1.2 Function Documentation

DELAY_microseconds()

void DELAY_microseconds (uint16_t microseconds)

Delays the execution of the program for a certain number of microseconds.

Parameters:
in microseconds

- Number of microseconds to delay

Returns:

None.

DELAY_milliseconds()

void DELAY_milliseconds (uint16_t milliseconds)

Delays the execution of the program for a certain number of milliseconds.

Parameters:
in milliseconds

- Number of milliseconds to delay

Returns:

None.

3.23.2.2 Timer Driver

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

3.23.2.2.1 Module description

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

Data structures

  • struct TIMER_INTERFACE

    Structure containing the function pointers of TIMER driver.

Definitions
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.

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.

3.23.2.2.2 Definition Documentation

Timer1_Counter16BitGet

#define Timer1_Counter16BitGet TMR1_Counter16BitGet

This macro defines the Custom Name for TMR1_Counter16BitGet API.

Timer1_CounterGet

#define Timer1_CounterGet TMR1_CounterGet

This macro defines the Custom Name for TMR1_CounterGet API.

Timer1_Deinitialize

#define Timer1_Deinitialize TMR1_Deinitialize

This macro defines the Custom Name for TMR1_Deinitialize API.

Timer1_Initialize

#define Timer1_Initialize TMR1_Initialize

This macro defines the Custom Name for TMR1_Initialize API.

Timer1_InterruptPrioritySet

#define Timer1_InterruptPrioritySet TMR1_InterruptPrioritySet

This macro defines the Custom Name for TMR1_InterruptPrioritySet API.

Timer1_PeriodGet

#define Timer1_PeriodGet TMR1_PeriodGet

This macro defines the Custom Name for TMR1_PeriodGet API.

Timer1_PeriodSet

#define Timer1_PeriodSet TMR1_PeriodSet

This macro defines the Custom Name for TMR1_PeriodSet API.

Timer1_Start

#define Timer1_Start TMR1_Start

This macro defines the Custom Name for TMR1_Start API.

Timer1_Stop

#define Timer1_Stop TMR1_Stop

This macro defines the Custom Name for TMR1_Stop API.

Timer1_TimeoutCallbackRegister

#define Timer1_TimeoutCallbackRegister TMR1_TimeoutCallbackRegister

This macro defines the Custom Name for TMR1_TimeoutCallbackRegister API.

3.23.2.2.3 Function Documentation

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

TMR1_CounterGet()

inline static uint32_t TMR1_CounterGet (void )

This inline function gets the TMR1 elapsed time value.

Returns:
TMR1_Deinitialize()

void TMR1_Deinitialize (void )

Deinitializes the TMR1 to POR values.

Returns:
TMR1_Initialize()

void TMR1_Initialize (void )

Initializes the TMR1 module.

Returns:
TMR1_InterruptPrioritySet()

void TMR1_InterruptPrioritySet (enum INTERRUPT_PRIORITY priority)

Sets the TMR1 interrupt priority value.

Parameters:
in priority

- value of interrupt priority

Returns:

none

TMR1_PeriodGet()

inline static uint32_t TMR1_PeriodGet (void )

This inline function gets the TMR1 period count value.

Returns:
TMR1_PeriodSet()

void TMR1_PeriodSet (uint32_t count)

Sets the TMR1 period count value.

Parameters:
in count

- number of clock counts

Returns:

none

TMR1_Start()

void TMR1_Start (void )

Starts the timer.

Precondition:

TMR1_Initialize must be called

Returns:

none

TMR1_Stop()

void TMR1_Stop (void )

Stops the timer.

Precondition:

TMR1_Initialize must be called

Returns:

none

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.

Returns:
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

3.23.2.2.4 Variable Documentation

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.

3.23.3 Data Structure Documentation

3.23.3.1 TIMER_INTERFACE Struct Reference

Structure containing the function pointers of TIMER driver.

3.23.3.1.1 Detailed Description

Structure containing the function pointers of TIMER driver.

#include <timer_interface.h>

Data Fields

  • void(* Initialize )(void)

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

  • void(* Deinitialize )(void)

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

  • void(* Start )(void)

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

  • void(* Stop )(void)

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

  • void(* PeriodSet )(uint32_t count)

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

  • uint32_t(* PeriodGet )(void)

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

  • uint32_t(* CounterGet )(void)

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

  • void(* InterruptPrioritySet )(enum INTERRUPT_PRIORITY priority)

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

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

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

  • void(* Tasks )(void)

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

3.23.3.1.2 Field Documentation

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

source/

timer_interface.h

CounterGet

uint32_t(* CounterGet) (void)

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

Deinitialize

void(* Deinitialize) (void)

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

Initialize

void(* Initialize) (void)

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

InterruptPrioritySet

void(* InterruptPrioritySet) (enum INTERRUPT_PRIORITY priority)

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

PeriodGet

uint32_t(* PeriodGet) (void)

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

PeriodSet

void(* PeriodSet) (uint32_t count)

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

Start

void(* Start) (void)

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

Stop

void(* Stop) (void)

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

Tasks

void(* Tasks) (void)

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

TimeoutCallbackRegister

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

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

3.23.4 File Documentation

3.23.4.1 source/delay.h File Reference

#include <stdint.h>

3.23.4.1.1 Functions

  • void DELAY_milliseconds (uint16_t milliseconds)

    Delays the execution of the program for a certain number of milliseconds.

  • void DELAY_microseconds (uint16_t microseconds)

    Delays the execution of the program for a certain number of microseconds.

3.23.4.1.2 Detailed Description

DELAY Generated Driver API Header File

3.23.4.2 source/timer_interface.h File Reference

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

3.23.4.2.1 Data structures

  • struct TIMER_INTERFACE

    Structure containing the function pointers of TIMER driver.

3.23.4.2.2 Detailed Description

TIMER Generated Driver Interface Header File

3.23.4.3 source/tmr1.h File Reference

This is the generated driver header file for the TMR1 driver. 

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

3.23.4.3.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.

3.23.4.3.2 Macros

3.23.4.3.3 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.

3.23.4.3.4 Detailed Description

This is the generated driver header file for the TMR1 driver.

TMR1 Generated Driver Header File

Version:

PLIB Version 1.0.0-rc.2

3.23.5 Module Documentation

    
    

3.23.5.1 Timer Use Cases







3.23.5.1.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).
    





3.23.5.1.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)
    {
        
    }
}

 


3.23.5.1.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_StandardPeripheralFrequencyGet()
#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;
        }
    }
}