LPTimer (Low-Power Timer)

General Description

High level interface for interacting with the low-power timer (LPTimer).

LPTimer can operate in all possible low power modes. It can be used either to measure timing between events, or to perform some action after a specified interval of time.

Features

• Wake the device up from deepsleep
• Configurable to create a free-running timer or generate periodic interrupts.
• Configurable to update the match value of an already configured LPTimer set up to generate an interrupt on match.
• Used for measuring time between events in free-running mode.

Quick Start

cyhal_lptimer_init can be used for a LPTimer initialization which resets all the clocking and prescaler registers, along with disabling the compare interrupt.

See Snippet 2: LPTimer interrupts.

Code snippets

Snippet 1: LPTimer initialization with Default configuration

The following snippet initializes a LPTimer in free running mode.

    cy_rslt_t       rslt;
    cyhal_lptimer_t lptimer;
    uint32_t        lptimer_value;
 
    // Initialize the LPTIMER with default configuration
    rslt = cyhal_lptimer_init(&lptimer);
 
    // Read the LPTIMER count value
    lptimer_value = cyhal_lptimer_read(&lptimer);

Snippet 2: LPTimer interrupts

The following snippet initializes a LPTimer and uses cyhal_lptimer_set_match() to trigger an interrupt on match. Subsequent interrupts can be triggered at required times using cyhal_lptimer_set_delay() called from the ISR.

#define LPTIMER_MATCH_VALUE    (8192u)
#define LPTIMER_INTR_PRIORITY     (3u)
 
cyhal_lptimer_t lptimer_obj;
 
cy_rslt_t snippet_lptimer_init()
{
    cy_rslt_t rslt;
 
    // Initialize the LPTIMER
    rslt = cyhal_lptimer_init(&lptimer_obj);
 
    // Set a match value of 8192 counts (~0.25 seconds for a clock source of 32768 Hz)
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_lptimer_set_match(&lptimer_obj, LPTIMER_MATCH_VALUE);
    }
 
    if (CY_RSLT_SUCCESS == rslt)
    {
        // Register the callback handler which will be invoked when the interrupt triggers
        cyhal_lptimer_register_callback(&lptimer_obj, lptimer_interrupt_handler, NULL);
 
        // Configure and Enable the LPTIMER events
        cyhal_lptimer_enable_event(&lptimer_obj, CYHAL_LPTIMER_COMPARE_MATCH, LPTIMER_INTR_PRIORITY,
                                   true);
 
        // Reload/Reset the Low-Power timer to start counting from this instant
        rslt = cyhal_lptimer_reload(&lptimer_obj);
    }
 
    return rslt;
}
 
 
void lptimer_interrupt_handler(void* handler_arg, cyhal_lptimer_event_t event)
{
    CY_UNUSED_PARAMETER(handler_arg);
    CY_UNUSED_PARAMETER(event);
    // Reload/Reset the Low-Power timer to start counting from this instant
    cyhal_lptimer_set_delay(&lptimer_obj, LPTIMER_MATCH_VALUE);
}
 
 

API Reference
	LPTimer HAL Results
	LPTimer specific return codes.

Data Structures
struct	cyhal_lptimer_info_t
	LPTimer Information. More...

Macros
#define	cyhal_lptimer_set_time   cyhal_lptimer_set_match
	Deprecated. More...

Typedefs
typedef void(*	cyhal_lptimer_event_callback_t) (void *callback_arg, cyhal_lptimer_event_t event)
	Handler for LPTimer interrupts.

Enumerations
enum	cyhal_lptimer_event_t { CYHAL_LPTIMER_COMPARE_MATCH }
	LPTimer interrupt triggers.

Functions
cy_rslt_t	cyhal_lptimer_init (cyhal_lptimer_t *obj)
	Initialize the LPTimer. More...
void	cyhal_lptimer_free (cyhal_lptimer_t *obj)
	Deinitialize the LPTimer. More...
cy_rslt_t	cyhal_lptimer_reload (cyhal_lptimer_t *obj)
	Reload/Reset the Low-Power timer. More...
cy_rslt_t	cyhal_lptimer_set_match (cyhal_lptimer_t *obj, uint32_t ticks)
	Update the match/compare value. More...
cy_rslt_t	cyhal_lptimer_set_delay (cyhal_lptimer_t *obj, uint32_t delay)
	Update the match/compare value. More...
uint32_t	cyhal_lptimer_read (const cyhal_lptimer_t *obj)
	Read the current tick. More...
void	cyhal_lptimer_register_callback (cyhal_lptimer_t *obj, cyhal_lptimer_event_callback_t callback, void *callback_arg)
	Register a LPTimer match event handler. More...
void	cyhal_lptimer_enable_event (cyhal_lptimer_t *obj, cyhal_lptimer_event_t event, uint8_t intr_priority, bool enable)
	Configure and Enable/Disable the LPTimer events. More...
void	cyhal_lptimer_irq_trigger (cyhal_lptimer_t *obj)
	Manually trigger the LPTimer interrupt. More...
void	cyhal_lptimer_get_info (cyhal_lptimer_t *obj, cyhal_lptimer_info_t *info)
	Get information about the LPTimer. More...

---

Data Structure Documentation

cyhal_lptimer_info_t

struct cyhal_lptimer_info_t

Data Fields
uint32_t	frequency_hz	Operating clock frequency the LPTimer is running on.
uint8_t	min_set_delay	Minimum permitted value for the delay parameter in cyhal_lptimer_set_delay.
uint32_t	max_counter_value	Maximum value of the counter.

Macro Definition Documentation

cyhal_lptimer_set_time

#define cyhal_lptimer_set_time   cyhal_lptimer_set_match

Deprecated.

Call cyhal_lptimer_set_match instead.

Function Documentation

cyhal_lptimer_init()

cy_rslt_t cyhal_lptimer_init

(

cyhal_lptimer_t *

obj

)

Initialize the LPTimer.

Initialize or re-initialize the LPTimer. This resets all the clocking and prescaler registers, along with disabling the compare interrupt. Refer to the BSP for the clock source for the LPTimer.

Parameters

[out]

obj

Pointer to an LPTimer object. The caller must allocate the memory for this object but the init function will initialize its contents.

Returns

The status of the init request. On success it returns CY_RSLT_SUCCESS.

cyhal_lptimer_free()

void cyhal_lptimer_free

(

cyhal_lptimer_t *

obj

)

Deinitialize the LPTimer.

Powers down the LPTimer. After calling this function no other LPTimer functions should be called except cyhal_lptimer_init(). Calling any function other than init after freeing is undefined.

Parameters

[in,out]

obj

The LPTimer object

cyhal_lptimer_reload()

cy_rslt_t cyhal_lptimer_reload

(

cyhal_lptimer_t *

obj

)

Reload/Reset the Low-Power timer.

Parameters

[in]

obj

The LPTimer object

Returns

The status of the reload request. On success it returns CY_RSLT_SUCCESS.

cyhal_lptimer_set_match()

cy_rslt_t cyhal_lptimer_set_match	(	cyhal_lptimer_t *	obj,
		uint32_t	ticks
	)

Update the match/compare value.

Update the match value of an already configured LPTimer set up to generate an interrupt on match. Note that this function does not reinitialize the counter or the associated peripheral initialization sequence.

Note

This does not reset the counter.

Parameters

[in]	obj	The LPTimer object
[in]	ticks	The tick value to match

Returns

The status of the set_match request. On success it returns CY_RSLT_SUCCESS.

cyhal_lptimer_set_delay()

cy_rslt_t cyhal_lptimer_set_delay	(	cyhal_lptimer_t *	obj,
		uint32_t	delay
	)

Update the match/compare value.

Update the match value of an already configured LPTimer set up to generate an interrupt on match delay from the current counter value. Note that this function does not reinitialize the counter or the associated peripheral initialization sequence.

Note

This does not reset the counter.

Parameters

[in]	obj	The LPTimer object
[in]	delay	The ticks to wait. The minimum permitted delay value can be queried using cyhal_lptimer_get_info

Returns

The status of the set_match request. On success it returns CY_RSLT_SUCCESS.

cyhal_lptimer_read()

uint32_t cyhal_lptimer_read

(

const cyhal_lptimer_t *

obj

)

Read the current tick.

If no rollover has occurred, the seconds passed since cyhal_lptimer_init() or cyhal_lptimer_set_time() was called can be found by dividing the ticks returned by this function by the frequency of the source clock (Refer to BSP Settings section in the kit's BSP API Reference Manual for details on the clock source for LPTimer).

Parameters

[in]

obj

The LPTimer object

Returns

The timer's timer value in ticks

cyhal_lptimer_register_callback()

void cyhal_lptimer_register_callback	(	cyhal_lptimer_t *	obj,
		cyhal_lptimer_event_callback_t	callback,
		void *	callback_arg
	)

Register a LPTimer match event handler.

This function will be called when one of the events enabled by cyhal_lptimer_enable_event occurs.

Parameters

[in]	obj	The LPTimer object
[in]	callback	The callback handler which will be invoked when the interrupt triggers
[in]	callback_arg	Generic argument that will be provided to the handler when called

cyhal_lptimer_enable_event()

void cyhal_lptimer_enable_event	(	cyhal_lptimer_t *	obj,
		cyhal_lptimer_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure and Enable/Disable the LPTimer events.

When an enabled event occurs, the function specified by cyhal_lptimer_register_callback will be called.

Parameters

[in]	obj	The LPTimer object
[in]	event	The LPTimer event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on event, False to turn off

cyhal_lptimer_irq_trigger()

void cyhal_lptimer_irq_trigger

(

cyhal_lptimer_t *

obj

)

Manually trigger the LPTimer interrupt.

Parameters

[in]

obj

The LPTimer object

cyhal_lptimer_get_info()

void cyhal_lptimer_get_info	(	cyhal_lptimer_t *	obj,
		cyhal_lptimer_info_t *	info
	)

Get information about the LPTimer.

Provides information such as operating frequency, etc.

Parameters

[in]	obj	The LPTimer object.
[out]	info	Information about the LPtimer.