LPTimer HAL Results

group group_hal_lptimer

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;

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);
}

Defines

cyhal_lptimer_set_time

Deprecated.

Call cyhal_lptimer_set_match instead.

Typedefs

typedef void (*cyhal_lptimer_event_callback_t)(void *callback_arg, cyhal_lptimer_event_t event)

Handler for LPTimer interrupts.

Enums

enum cyhal_lptimer_event_t

cyhal_lptimer_event_t: LPTimer interrupt triggers.

Values:

enumerator CYHAL_LPTIMER_COMPARE_MATCH

Functions

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.

Return

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

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.

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
  • [inout] obj: The LPTimer object

cy_rslt_t cyhal_lptimer_reload(cyhal_lptimer_t *obj)

Reload/Reset the Low-Power timer.

Return

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

Parameters
  • [in] obj: The LPTimer object

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.

Return

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

Parameters
  • [in] obj: The LPTimer object

  • [in] value: The tick value to match

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.

Return

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

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

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

Return

The timer’s timer value in ticks

Parameters
  • [in] obj: The LPTimer object

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

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

void cyhal_lptimer_irq_trigger(cyhal_lptimer_t *obj)

Manually trigger the LPTimer interrupt.

Parameters
  • [in] obj: The LPTimer object

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.

struct cyhal_lptimer_info_t
#include <cyhal_lptimer.h>

LPTimer Information.

Public Members

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.