TIMER

Overview

ESP32 chip contains two hardware timer groups, each containing two general-purpose hardware timers.

They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.

Application Example

64-bit hardware timer example: peripherals/timer_group.

API Reference

Macros

TIMER_BASE_CLK (APB_CLK_FREQ)

Type Definitions

Enumerations

enum timer_group_t

Selects a Timer-Group out of 2 available groups.

Values:

TIMER_GROUP_0 = 0

Hw timer group 0

TIMER_GROUP_1 = 1

Hw timer group 1

TIMER_GROUP_MAX
enum timer_idx_t

Select a hardware timer from timer groups.

Values:

TIMER_0 = 0

Select timer0 of GROUPx

TIMER_1 = 1

Select timer1 of GROUPx

TIMER_MAX
enum timer_count_dir_t

Decides the direction of counter.

Values:

TIMER_COUNT_DOWN = 0

Descending Count from cnt.high|cnt.low

TIMER_COUNT_UP = 1

Ascending Count from Zero

TIMER_COUNT_MAX
enum timer_start_t

Decides whether timer is on or paused.

Values:

TIMER_PAUSE = 0

Pause timer counter

TIMER_START = 1

Start timer counter

enum timer_alarm_t

Decides whether to enable alarm mode.

Values:

TIMER_ALARM_DIS = 0

Disable timer alarm

TIMER_ALARM_EN = 1

Enable timer alarm

TIMER_ALARM_MAX
enum timer_intr_mode_t

Select interrupt type if running in alarm mode.

Values:

TIMER_INTR_LEVEL = 0

Interrupt mode: level mode

TIMER_INTR_MAX
enum timer_autoreload_t

Select if Alarm needs to be loaded by software or automatically reload by hardware.

Values:

TIMER_AUTORELOAD_DIS = 0

Disable auto-reload: hardware will not load counter value after an alarm event

TIMER_AUTORELOAD_EN = 1

Enable auto-reload: hardware will load counter value after an alarm event

TIMER_AUTORELOAD_MAX

Structures

struct timer_config_t

timer configure struct

Public Members

bool alarm_en

Timer alarm enable

bool counter_en

Counter enable

timer_intr_mode_t intr_type

Interrupt mode

timer_count_dir_t counter_dir

Counter direction

bool auto_reload

Timer auto-reload

uint16_t divider

Counter clock divider

Functions

esp_err_t timer_get_counter_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t *timer_val)

Read the counter value of hardware timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • timer_val: Pointer to accept timer counter value.

esp_err_t timer_get_counter_time_sec(timer_group_t group_num, timer_idx_t timer_num, double *time)

Read the counter value of hardware timer, in unit of a given scale.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • time: Pointer, type of double*, to accept timer counter value, in seconds.

esp_err_t timer_set_counter_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t load_val)

Set counter value to hardware timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • load_val: Counter value to write to the hardware timer.

esp_err_t timer_start(timer_group_t group_num, timer_idx_t timer_num)

Start the counter of hardware timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]

esp_err_t timer_pause(timer_group_t group_num, timer_idx_t timer_num)

Pause the counter of hardware timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]

esp_err_t timer_set_counter_mode(timer_group_t group_num, timer_idx_t timer_num, timer_count_dir_t counter_dir)

Set counting mode for hardware timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • counter_dir: Counting direction of timer, count-up or count-down

esp_err_t timer_set_auto_reload(timer_group_t group_num, timer_idx_t timer_num, timer_autoreload_t reload)

Enable or disable counter reload function when alarm event occurs.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • reload: Counter reload mode.

esp_err_t timer_set_divider(timer_group_t group_num, timer_idx_t timer_num, uint16_t divider)

Set hardware timer source clock divider. Timer groups clock are divider from APB clock.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • divider: Timer clock divider value.

esp_err_t timer_set_alarm_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t alarm_value)

Set timer alarm value.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • alarm_value: A 64-bit value to set the alarm value.

esp_err_t timer_get_alarm_value(timer_group_t group_num, timer_idx_t timer_num, uint64_t *alarm_value)

Get timer alarm value.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • alarm_value: Pointer of A 64-bit value to accept the alarm value.

esp_err_t timer_set_alarm(timer_group_t group_num, timer_idx_t timer_num, timer_alarm_t alarm_en)

Get timer alarm value.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • alarm_en: To enable or disable timer alarm function.

esp_err_t timer_isr_register(timer_group_t group_num, timer_idx_t timer_num, void (*fn)(void *), void *arg, int intr_alloc_flags, timer_isr_handle_t *handle, )

register Timer interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

Note
In case the this is called with the INIRAM flag, code inside the handler function can only call functions in IRAM, so it cannot call other timer APIs. Use direct register access to access timers from inside the ISR in this case.
Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Function pointer error.
Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number
  • timer_num: Timer index of timer group
  • fn: Interrupt handler function.
Parameters
  • arg: Parameter for handler function
  • intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
  • handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

esp_err_t timer_init(timer_group_t group_num, timer_idx_t timer_num, timer_config_t *config)

Initializes and configure the timer.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • config: Pointer to timer initialization parameters.

esp_err_t timer_get_config(timer_group_t group_num, timer_idx_t timer_num, timer_config_t *config)

Get timer configure value.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index, 0 for hw_timer[0] & 1 for hw_timer[1]
  • config: Pointer of struct to accept timer parameters.

esp_err_t timer_group_intr_enable(timer_group_t group_num, uint32_t en_mask)

Enable timer group interrupt, by enable mask.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • en_mask: Timer interrupt enable mask. Use TIMG_T0_INT_ENA_M to enable t0 interrupt Use TIMG_T1_INT_ENA_M to enable t1 interrupt

esp_err_t timer_group_intr_disable(timer_group_t group_num, uint32_t disable_mask)

Disable timer group interrupt, by disable mask.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • disable_mask: Timer interrupt disable mask. Use TIMG_T0_INT_ENA_M to disable t0 interrupt Use TIMG_T1_INT_ENA_M to disable t1 interrupt

esp_err_t timer_enable_intr(timer_group_t group_num, timer_idx_t timer_num)

Enable timer interrupt.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index.

esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num)

Disable timer interrupt.

Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • group_num: Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  • timer_num: Timer index.