esp32s3 库函数功能解析

定时器

esp_restart

函数的主要功能是触发整个系统的重新启动。调用此函数后，ESP32 芯片会执行以下操作：

保存当前状态（如果需要）：在一些应用场景中，可能需要在重启前保存当前系统状态，比如日志数据或关键变量。这通常需要开发者在调用 esp_restart() 之前自行处理。

执行系统重启：此函数会关闭所有的硬件资源，复位所有的寄存器，并最终重新加载程序，从而实现系统的完全重启。

重新初始化：系统重新启动后，会重新运行从上电开始的初始化过程，包括启动引导加载程序，加载应用程序，并重新初始化所有的硬件和软件组件

---

esp_timer_create

esp_timer_create 是 ESP-IDF 中用于创建定时器的函数。定时器是嵌入式系统中非常重要的工具，用于在指定的时间间隔后执行某些操作或反复执行某些任务。

详细说明

功能

esp_timer_create 函数用于创建一个软件定时器（软件定时器是在软件层面实现的定时器，而非硬件定时器）。创建定时器后，可以启动它以在指定时间后调用一个回调函数。

函数原型

esp_err_t esp_timer_create(const esp_timer_create_args_t* create_args, esp_timer_handle_t* out_handle);

参数说明

• create_args: 一个指向 esp_timer_create_args_t 结构体的指针，用于指定定时器的参数。
• out_handle: 一个指向 esp_timer_handle_t 类型的指针，用于接收创建的定时器句柄。

esp_timer_create_args_t 结构体

这个结构体包含了创建定时器所需的参数：

typedef struct {
    esp_timer_cb_t callback; // 定时器到期时调用的回调函数
    void* arg;               // 传递给回调函数的参数
    const char* name;        // 定时器的名称（可选）
    bool dispatch_method;    // 调度方法（ESP_TIMER_TASK or ESP_TIMER_ISR）
} esp_timer_create_args_t;

• callback: 定时器到期时将被调用的回调函数。
• arg: 传递给回调函数的参数，可以是 NULL。
• name: 定时器的名称，用于调试（可选）。
• dispatch_method: 指定回调函数的调用方式（可选）。

返回值

该函数返回 esp_err_t 类型的值，表示函数执行的结果：

• ESP_OK 表示成功。
• 其他错误代码表示失败。

使用示例

下面是一个创建并启动定时器的简单示例，该定时器会在1秒后触发：

#include "esp_timer.h"

void timer_callback(void* arg) {
    printf("Timer expired!\n");
}

void app_main() {
    esp_timer_handle_t timer_handle;
    esp_timer_create_args_t timer_args = {
        .callback = &timer_callback,
        .arg = NULL,
        .name = "example_timer"
    };

    // 创建定时器
    esp_err_t ret = esp_timer_create(&timer_args, &timer_handle);
    if (ret != ESP_OK) {
        printf("Failed to create timer: %s\n", esp_err_to_name(ret));
        return;
    }

    // 启动定时器，设置1秒（1000000微秒）后到期
    ret = esp_timer_start_once(timer_handle, 1000000);
    if (ret != ESP_OK) {
        printf("Failed to start timer: %s\n", esp_err_to_name(ret));
        return;
    }

    printf("Timer started\n");
}

在这个示例中：

1. 定义了一个名为 timer_callback 的回调函数，该函数在定时器到期时被调用。
2. 创建了一个 esp_timer_create_args_t 结构体，设置回调函数和其他参数。
3. 使用 esp_timer_create 函数创建了一个定时器，并获得定时器句柄。
4. 使用 esp_timer_start_once 函数启动定时器，设定定时器在1秒后触发。

这就是 esp_timer_create 函数的基本使用方法。

---

esp_timer_start_periodic

城哥，下面我分别详细介绍 esp_timer_create 和 esp_timer_start_periodic 函数的功能及其使用方法。

esp_timer_create

功能

esp_timer_create 函数用于创建一个定时器（timer），这个定时器可以是一次性的（one-shot）或周期性的（periodic）。创建定时器时，需要指定定时器触发时要调用的回调函数及其参数。

函数原型

esp_err_t esp_timer_create(const esp_timer_create_args_t* create_args, esp_timer_handle_t* out_handle);

参数

• create_args: 一个指向 esp_timer_create_args_t 结构体的指针，该结构体包含定时器的初始化参数，包括回调函数和回调函数的参数。
• out_handle: 一个指向 esp_timer_handle_t 变量的指针，用于接收创建的定时器句柄。

esp_timer_create_args_t 结构体

typedef struct {
    void (*callback)(void* arg);   // 定时器触发时的回调函数
    void* arg;                     // 传递给回调函数的参数
    const char* name;              // 定时器的名称（可选）
    bool skip_unhandled_events;    // 是否跳过未处理的定时器事件
} esp_timer_create_args_t;

示例代码

#include "esp_timer.h"

void timer_callback(void* arg) {
    // 定时器触发时执行的代码
    printf("Timer triggered!\n");
}

void app_main() {
    esp_timer_handle_t timer_handle;
    esp_timer_create_args_t timer_args = {
        .callback = &timer_callback,
        .arg = NULL,
        .name = "my_timer"
    };

    esp_err_t err = esp_timer_create(&timer_args, &timer_handle);
    if (err == ESP_OK) {
        printf("Timer created successfully!\n");
    } else {
        printf("Failed to create timer!\n");
    }
}

esp_timer_start_periodic

功能

esp_timer_start_periodic 函数用于启动一个周期性定时器。定时器在指定的周期时间间隔内不断触发，并调用之前设置的回调函数。

###函数原型

esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period);

参数

• timer: 之前通过 esp_timer_create 创建的定时器句柄。
• period: 定时器触发的时间间隔，单位为微秒（us）。

示例代码

#include "esp_timer.h"

void periodic_timer_callback(void* arg) {
    // 周期性定时器触发时执行的代码
    printf("Periodic timer triggered!\n");
}

void app_main() {
    esp_timer_handle_t periodic_timer_handle;
    esp_timer_create_args_t periodic_timer_args = {
        .callback = &periodic_timer_callback,
        .arg = NULL,
        .name = "my_periodic_timer"
    };

    esp_err_t err = esp_timer_create(&periodic_timer_args, &periodic_timer_handle);
    if (err == ESP_OK) {
        printf("Periodic timer created successfully!\n");
        err = esp_timer_start_periodic(periodic_timer_handle, 1000000); // 1秒周期
        if (err == ESP_OK) {
            printf("Periodic timer started successfully!\n");
        } else {
            printf("Failed to start periodic timer!\n");
        }
    } else {
        printf("Failed to create periodic timer!\n");
    }
}

在这个示例中，创建了一个名为 “my_periodic_timer” 的周期性定时器，触发间隔为 1 秒。每次定时器触发时，都会调用 periodic_timer_callback 函数。

城哥，以下是关于 esp_timer_create、esp_timer_start_periodic 和 esp_timer_start 函数的详细说明：

esp_timer_create

esp_timer_create 函数用于创建一个新的计时器（timer）。这个计时器可以是一次性（one-shot）计时器或者周期性（periodic）计时器。

函数原型

esp_err_t esp_timer_create(const esp_timer_create_args_t *create_args, esp_timer_handle_t *out_handle);

参数

• create_args：一个指向 esp_timer_create_args_t 结构体的指针，包含计时器的创建参数。

  • callback：计时器超时时调用的回调函数。
  • arg：传递给回调函数的参数。
  • name：计时器的名称（可选，用于调试）。

• out_handle：一个指向 esp_timer_handle_t 的指针，用于存储创建的计时器句柄。

返回值

• ESP_OK：表示计时器创建成功。
• 其他错误代码：表示创建失败。

示例

#include "esp_timer.h"

void timer_callback(void* arg) {
    printf("Timer expired\n");
}

void app_main() {
    esp_timer_handle_t timer;
    esp_timer_create_args_t timer_args = {
        .callback = &timer_callback,
        .name = "my_timer"
    };
    esp_timer_create(&timer_args, &timer);
}

esp_timer_start_periodic

esp_timer_start_periodic 函数用于启动一个周期性计时器，该计时器会以固定的间隔时间重复触发。

函数原型

esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period);

参数

• timer：之前通过 esp_timer_create 创建的计时器句柄。
• period：计时器周期，以微秒为单位。

返回值

• ESP_OK：表示计时器启动成功。
• 其他错误代码：表示启动失败。

示例

#include "esp_timer.h"

void periodic_timer_callback(void* arg) {
    printf("Periodic timer expired\n");
}

void app_main() {
    esp_timer_handle_t periodic_timer;
    esp_timer_create_args_t periodic_timer_args = {
        .callback = &periodic_timer_callback,
        .name = "periodic_timer"
    };
    esp_timer_create(&periodic_timer_args, &periodic_timer);
    esp_timer_start_periodic(periodic_timer, 1000000); // 每1秒触发一次
}

esp_timer_restart

函数原型

esp_err_t esp_timer_restart(esp_timer_handle_t timer, uint64_t timeout_us);

参数

• timer：之前通过 esp_timer_create 创建的计时器句柄。
• timeout_us：新的计时器超时时间，以微秒为单位。 ·（所谓的超时时间，就是新的定时器的定时周期）

返回值

• ESP_OK：表示计时器重启成功。
• 其他错误代码：表示重启失败。

详细说明

• 当调用 esp_timer_restart 时，计时器将使用新的超时时间重新开始计时。
• 该函数适用于需要在运行时重新调整计时器超时时间的场景。例如，如果在某些事件发生时需要延长计时器的超时时间。

示例

#include "esp_timer.h"

void restart_timer_callback(void* arg) {
    printf("Timer expired and restarted\n");
    // 重启计时器，这里假设每次重启时间是 3 秒
    esp_timer_restart((esp_timer_handle_t)arg, 3000000); // 重新设置为3秒
}

void app_main() {
    esp_timer_handle_t restart_timer;
    esp_timer_create_args_t restart_timer_args = {
        .callback = &restart_timer_callback,
        .arg = (void*)&restart_timer,
        .name = "restart_timer"
    };
    esp_timer_create(&restart_timer_args, &restart_timer);
    esp_timer_start_once(restart_timer, 2000000); // 初始设置为2秒

    // 模拟在某个事件发生时重启计时器
    vTaskDelay(1000 / portTICK_PERIOD_MS); // 等待1秒
    esp_timer_restart(restart_timer, 5000000); // 重新设置为5秒
}

在这个示例中，计时器初始设置为2秒超时，然后在1秒后手动重启计时器，并将新的超时时间设为5秒。在回调函数中，计时器每次触发后都会被重新设置为3秒。