2.27 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.
2.27.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: 2.27.5.1 Timer Use Case Code Snippet Instructions
- 2.27.5.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.
- 2.27.5.3 Timer Use Case 2: Timer Switch Frequency 100 ms / 500 ms: This use case sets up a project which changes the time-out period between 100 ms and 500 ms, when a switch is pressed.
2.27.2 Module Documentation
2.27.2.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.2.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.
Data structures
struct TIMER_INTERFACE
Structure containing the function pointers of TIMER driver.
Definitions
#define TIMER_PERIODCOUNTSET_API_SUPPORT false
Defines the deprecated SCCPx_Timer_PeriodCountSet or TMRx_PeriodCountSet API. Set it to true for backward compatibility.
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.
2.27.2.1.2 Definition Documentation
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.2.1.3 Function Documentation
TMR1_Counter16BitGet()
inline static uint16_t TMR1_Counter16BitGet (void )
This inline function gets the 16 bit TMR1 elapsed time value.
none. |
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.
none. |
Elapsed count value of the timer. |
TMR1_Deinitialize()
void TMR1_Deinitialize (void )
Deinitializes the TMR1 to POR values.
none. |
none. |
TMR1_Initialize()
void TMR1_Initialize (void )
Initializes the TMR1 module.
none. |
none. |
TMR1_InterruptPrioritySet()
void TMR1_InterruptPrioritySet (enum INTERRUPT_PRIORITY priority)
Sets the TMR1 interrupt priority value.
in | priority |
- value of interrupt priority. |
none. |
TMR1_PeriodGet()
inline static uint32_t TMR1_PeriodGet (void )
This inline function gets the TMR1 period count value.
none. |
Number of clock counts. |
TMR1_PeriodSet()
void TMR1_PeriodSet (uint32_t count)
Sets the TMR1 period count value.
in | count |
- number of clock counts. |
none. |
TMR1_Start()
void TMR1_Start (void )
Starts the timer.
TMR1_Initialize must be called. |
none. |
none. |
TMR1_Stop()
void TMR1_Stop (void )
Stops the timer.
TMR1_Initialize must be called. |
none. |
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.
none. |
none. |
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.
in | handler |
- Address of the callback function. |
none. |
2.27.2.1.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.
2.27.3 Class Documentation
2.27.3.1 TIMER_INTERFACE Struct Reference
Structure containing the function pointers of TIMER driver.
2.27.3.1.1 Detailed Description
Structure containing the function pointers of TIMER driver.
#include <timer_interface.h>
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.3.1.2 Member Data Documentation
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.
Deinitialize
void(* Deinitialize) (void)
Pointer to MCCPx_Timer_Deinitialize or SCCPx_Timer_Deinitialize or TMRx_Deinitialize e.g. SCCP1_Timer_Deinitialize or TMR1_Deinitialize.
Initialize
void(* Initialize) (void)
Pointer to MCCPx_Timer_Initialize or SCCPx_Timer_Initialize or TMRx_Initialize e.g. SCCP1_Timer_Initialize or TMR1_Initialize.
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.
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.
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.
Start
void(* Start) (void)
Pointer to MCCPx_Timer_Start or SCCPx_Timer_Start or TMRx_Start e.g. SCCP1_Timer_Start or TMR1_Start.
Stop
void(* Stop) (void)
Pointer to MCCPx_Timer_Stop or SCCPx_Timer_Stop or TMRx_Stop e.g. SCCP1_Timer_Stop or TMR1_Stop.
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)
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.4 File Documentation
2.27.4.1 source/timer_interface.h File Reference
#include <stddef.h> #include <stdint.h> #include <stdbool.h> #include "../system/interrupt_types.h"
2.27.4.1.1 Data structures
struct TIMER_INTERFACE
Structure containing the function pointers of TIMER driver.
2.27.4.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.4.1.3 Detailed Description
TIMER Generated Driver Interface Header File
2.27.4.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.4.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.4.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.4.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.5 Timer Use Cases
2.27.5.1 Timer Use Case Code Snippet Instructions
-
Add Timer(TMR1) to the project
-
Configure:
-
Timer as described in the example.
-
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.5.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 > Software Settings:
-
Requested Timer Period(ms): 100(ms).
-
-
Timer > Interrupt Settings:
-
Interrupt Driven: Yes.
-
-
System > Pins (for all pins check board schematics):
-
Pin Grid View: Select one GPIO Pin as LED Output (Check board schematic).
-
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.5.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 > Software Settings:
-
Requested Timer Period(ms): 500(ms).
-
-
Timer > Interrupt Settings:
-
TMR Interrupt: Yes.
-
-
System > Pins (for all pins check board schematics):
-
Pin Grid View: Select one GPIO Pin as LED Output
-
Pins: Rename Custom Name of selected GPIO Pin to "LED".
-
Pin Grid View: Select one GPIO Pin as Switch INPUT.
-
Pins: Rename Custom Name of selected GPIO Pin to "SW".
-
Pins: Enable Weak Pullup if needed
-
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; } } }