ESP32-IDF 通用定时器 GPTimer

最新推荐文章于 2025-05-28 08:24:34 发布

Projectsauron

最新推荐文章于 2025-05-28 08:24:34 发布

阅读量4.9k

点赞数 23

CC 4.0 BY-SA版权

分类专栏： # ESP32 文章标签： esp32-idf

本文链接：https://blog.csdn.net/Teminator_/article/details/143039363

一、基本介绍

1、配置结构体

1.1 gptimer_config_t

typedef struct {
   
   
    gptimer_clock_source_t clk_src;      /*!< GPTimer clock source */
    gptimer_count_direction_t direction; /*!< Count direction */
    uint32_t resolution_hz;              /*!< Counter resolution (working frequency) in Hz,
                                              hence, the step size of each count tick equals to (1 / resolution_hz) seconds */
    int intr_priority;                   /*!< GPTimer interrupt priority,
                                              if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
    struct {
   
   
        uint32_t intr_shared: 1;         /*!< Set true, the timer interrupt number can be shared with other peripherals */
        uint32_t backup_before_sleep: 1; /*!< If set, the driver will backup/restore the GPTimer registers before/after entering/exist sleep mode.
                                              By this approach, the system can power off GPTimer's power domain.
                                              This can save power, but at the expense of more RAM being consumed */
    } flags;                             /*!< GPTimer config flags*/
} gptimer_config_t;

clk_src：时钟源
direction：计数方向（如递增、递减）
resolution_hz：计数器分辨率（工作频率），以 Hz 为单位，因此，每个计数滴答的步长等于（1 / resolution_hz）秒
intr_priority：GPTimer 中断优先级，如果设置为 0，驱动程序将尝试分配优先级相对较低的中断（1,2,3）
flags
- intr_shared：设置为 1，定时器中断号可以与其他外设共享
- backup_before_sleep：设置为 1，驱动程序会在进入睡眠模式前备份并在恢复时恢复 GPTimer 的寄存器。这可以节省电力，但会增加 RAM 的使用。

1.2 gptimer_event_callbacks_t

一组支持 GPTimer 的回调函数。

这些回调都在 ISR 环境下运行

typedef bool (*gptimer_alarm_cb_t)(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx);

...

typedef struct {
   
   
    gptimer_alarm_cb_t on_alarm; /*!< Timer alarm callback */
} gptimer_event_callbacks_t;

on_alarm：alarm 回调函数

补充

这个结构体保存的是 gptimer alarm 的数据：

typedef struct {
   
   
    uint64_t count_value; /* 定时器自启动以来的累积计数 */
    uint64_t alarm_value; /* 触发警报所需达到的计数阈值 */
} gptimer_alarm_event_data_t;

1.3 gptimer_alarm_config_t

配置 GPTimer 的 alarm

typedef struct {
   
   
    uint64_t alarm_count;  /*!< Alarm target count value */
    uint64_t reload_count; /*!< Alarm reload count value, effect only when `auto_reload_on_alarm` is set to true */
    struct {
   
   
        uint32_t auto_reload_on_alarm: 1; /*!< Reload the count value by hardware, immediately at the alarm event */
    } flags;                              /*!< Alarm config flags*/
} gptimer_alarm_config_t;

alarm_count：报警触发的目标计数值。当定时器的计数器达到这个值时，将触发报警事件。
reload_count：报警触发后重新加载的计数值。这个值只有在 auto_reload_on_alarm 被设置为 true 时才会生效，定时器会在触发报警后重新加载这个值作为新的计数值。
auto_reload_on_alarm：标志位，表示是否在报警事件发生时自动重载计数值。如果设置为 true，则在触发报警后，定时器将自动将计数器的值重置为 reload_count。

2、常用 API

需要包含头文件 #include "driver/gptimer.h"

2.1 gptimer_new_timer

esp_err_t gptimer_new_timer(const gptimer_config_t *config, gptimer_handle_t *ret_timer)

参数
- config：GPTimer 配置结构体
- ret_timer：返回的 timer 句柄
作用
- 创建一个新的 GPTimer，并返回 handle。
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_ERR_NO_MEM：内存不足
- ESP_ERR_NOT_FOUND：所有硬件计时器都已用完，没有更多空闲计时器
- ESP_FAIL：由于其他错误

2.2 gptimer_del_timer

esp_err_t gptimer_del_timer(gptimer_handle_t timer)

参数
- timer：timer 句柄
作用
- 删除 GPTimer 句柄。
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_ERR_INVALID_STATE：计时器未处于 init 状态
- ESP_FAIL：由于其他错误

计时器必须处于 “init” 状态，然后才能删除。

2.3 gptimer_set_raw_count

esp_err_t gptimer_set_raw_count(gptimer_handle_t timer, uint64_t value)

参数
- timer：timer 句柄
- value：要设置的 Count 值
作用
- 设置 GPTimer 原始计数值。
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_FAIL：由于其他错误

当更新活动计时器的原始计数时，计时器将立即开始从新值开始计数。

允许此函数在 ISR 上下文中运行

2.4 gptimer_get_raw_count

esp_err_t gptimer_get_raw_count(gptimer_handle_t timer, uint64_t *value)

参数
- timer：timer 句柄
- value：保存获取的 Count 值
作用
- 获取 GPTimer 原始计数值。
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_FAIL：由于其他错误

使用原始计数值和从 gptimer_get_resolution 返回的分辨率，您可以将计数值转换为秒。

此函数将触发软件捕获事件，然后返回捕获的计数值。

允许此函数在 ISR 上下文中运行

2.5 gptimer_get_resolution

esp_err_t gptimer_get_resolution(gptimer_handle_t timer, uint32_t *out_resolution)

参数
- timer：timer 句柄
- out_resolution：返回的计时器分辨率，以 Hz 为单位
作用
- 返回计时器的实际分辨率。
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_FAIL：由于其他错误

通常 timer 分辨率与您在 gptimer_config_t::resolution_hz 配置的相同，但一些不稳定的 clock source （例如 RC_FAST）会进行校准，实际分辨率可能与配置的分辨率不同。

2.6 gptimer_get_captured_count

esp_err_t gptimer_get_captured_count(gptimer_handle_t timer, uint64_t *value)

参数
- timer：timer 句柄
- value：保存捕获到的 count 值
作用
- 获取 GPTimer 捕获到的 count 值
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_FAIL：由于其他错误

2.7 gptimer_register_event_callbacks

esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer_event_callbacks_t *cbs, void *user_data)

参数
- timer：timer 句柄
- cbs：回调函数组
- user_data：用户数据，将直接传递给回调函数
作用
- 设置 GPTimer 回调函数
返回值
- ESP_OK：成功
- ESP_ERR_INVALID_ARG：参数无效
- ESP_ERR_INVALID_STATE：设置事件回调失败，因为计时器未处于 init 状态
- ESP_FAIL：由于其他错误