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_obj;
    uint32_t lptimer_value;
    /* Initialize the LPTIMER with default configuration */
    rslt = cyhal_lptimer_init(&lptimer_obj);
    /* Read the LPTIMER count value */
    lptimer_value = cyhal_lptimer_read(&lptimer_obj);

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;
void snippet_lptimer_init()
{
    cy_rslt_t rslt;
    /* Initialize the LPTIMER */
    rslt = cyhal_lptimer_init(&lptimer_obj);
    CY_ASSERT(rslt == CY_RSLT_SUCCESS);
    /* Set a match value of 8192 counts (~0.25 seconds for a clock source of 32768 Hz) */
    cyhal_lptimer_set_match(&lptimer_obj, LPTIMER_MATCH_VALUE);
    /* 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 */
    cyhal_lptimer_reload(&lptimer_obj);
}
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 value)
	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	value
	)

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]	value	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.

General Description

Features

Quick Start

Code snippets

Snippet 1: LPTimer initialization with Default configuration

Snippet 2: LPTimer interrupts

API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ cyhal_lptimer_info_t

Macro Definition Documentation

◆ cyhal_lptimer_set_time

Function Documentation

◆ cyhal_lptimer_init()

◆ cyhal_lptimer_free()

◆ cyhal_lptimer_reload()

◆ cyhal_lptimer_set_match()

◆ cyhal_lptimer_set_delay()

◆ cyhal_lptimer_read()

◆ cyhal_lptimer_register_callback()

◆ cyhal_lptimer_enable_event()

◆ cyhal_lptimer_irq_trigger()

◆ cyhal_lptimer_get_info()