ESP32学习笔记——LOG日志库的使用

注：本文由CHATGPT辅助创作，未经验证，实际工程使用请仔细甄别。
对于设置日志级别的几种方式（esp_log_level_set、CONFIG_LOG_DEFAULT_LEVEL、CONFIG_LOG_MAXIMUM_LEVEL、LOG_LOCAL_LEVEL ）容易混淆，特此学习并记录。

ESP官网参考链接：
https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/system/log.html（日志库）

ESP32的日志库（esp_log.h）提供了一个简单而高效的方式来记录调试信息、错误和其他日志。使用这个库可以方便地将日志信息输出到串口、文件等，有助于开发过程中的调试和性能分析。以下是它的使用方法和一些常见的API。

一. 初始化与基础用法

在FreeRTOS系统中，只需包含头文件即可使用，不需要专门初始化。默认情况下，所有日志会输出到UART。

#include "esp_log.h"

二. 日志级别

ESP32的日志库支持以下几种日志级别，按优先级从高到低排列：

• ESP_LOG_ERROR：错误信息，严重的问题。
• ESP_LOG_WARN：警告信息，潜在问题。
• ESP_LOG_INFO： 一般信息，系统状态或进程说明。
• ESP_LOG_DEBUG：调试信息，用于开发阶段的详细信息。
• ESP_LOG_VERBOSE：最详细的信息，一般用于跟踪代码流。

可以使用环境变量或代码设置日志级别控制输出。

三. 日志函数

以下是常见的日志函数，TAG是用来标记日志来源的字符串，可以方便地追踪日志属于哪个模块。

#define TAG "my_module"  // 定义一个TAG用于标记模块名称ESP_LOGE(TAG, "This is an error message: %d", error_code);    // 错误日志
ESP_LOGW(TAG, "This is a warning");                          // 警告日志
ESP_LOGI(TAG, "System is running at %d MHz", cpu_freq);      // 信息日志
ESP_LOGD(TAG, "Variable x = %d", x);                         // 调试日志
ESP_LOGV(TAG, "Entering function foo()");                    // 详细日志

这些宏会根据设置的日志级别进行编译，如果设置为较低的日志级别（例如ESP_LOG_INFO），则不会编译更高详细级别（如DEBUG或VERBOSE），从而节省资源。
(见下章)

四. 设置日志级别

在ESP-IDF中，CONFIG_LOG_DEFAULT_LEVEL配置、 LOG_LOCAL_LEVEL宏定义、esp_log_level_set(TAG, level)函数，这三者都可以控制日志的输出级别，但它们的作用范围和应用时机各有不同。以下是这三个方法的详细说明和它们之间的区别：

1. esp_log_level_set(TAG, level)

启用 CONFIG_LOG_DYNAMIC_LEVEL_CONTROL 选项后，则可在运行时通过 esp_log_level_set() 更改日志级别。
动态更改日志级别提高了灵活性，但也会产生额外的代码开销。 如果应用程序不需要动态更改日志级别，并且不需要使用标签来控制每个模块的日志，建议禁用 CONFIG_LOG_DYNAMIC_LEVEL_CONTROL。

• 作用范围：运行时设置特定模块的日志级别。
• 作用对象：仅针对指定的 TAG（模块）生效。
• 生效时机：运行时动态控制，可以在代码的不同部分调整同一模块的日志级别。
• 使用场景：当需要在运行时动态调整某个模块的日志级别时使用，例如调试特定模块而不影响其他模块的日志输出。

esp_log_level_set("my_module", ESP_LOG_WARN);  // 将"my_module"模块的日志级别设置为WARN
esp_log_level_set("*", ESP_LOG_INFO);  // 将所有模块的日志级别设置为INFO

注意，函数 esp_log_level_set() 无法将日志级别设置为高于 CONFIG_LOG_MAXIMUM_LEVEL 指定的级别。如需在编译时将特定文件的日志级别提高到此最高级别以上，请使用 LOG_LOCAL_LEVEL 宏。

2. CONFIG_LOG_DEFAULT_LEVEL

在 menuconfig 中，使用选项 CONFIG_LOG_DEFAULT_LEVEL 来设置日志级别。配置后，项目中所有模块的默认日志级别将被设置（如 ESP_LOG_WARN），即启用所有级别低于 CONFIG_LOG_DEFAULT_LEVEL 的日志。

• 作用范围：全局默认日志级别，影响整个项目的日志输出。
• 作用对象：所有模块的默认日志级别。
• 生效时机：编译时配置，通过 menuconfig 设置。此选项在项目编译前生效，编译完成后无法动态更改。
• 使用场景：用于为整个项目设置统一的日志级别，适合在正式发布时限制日志输出。

通过 menuconfig 配置：

idf.py menuconfig
# 进入 "Component config" -> "Log output" -> "Default log verbosity"
# 设置全局默认日志级别，例如设置为 WARN

3. LOG_LOCAL_LEVEL

• 作用范围：文件级别，影响单个源文件的日志输出。
• 作用对象：当前源文件中的所有日志宏调用。
• 生效时机：编译时控制，必须在文件顶部定义；在编译时决定当前文件可输出的日志级别。
• 使用场景：当某个源文件需要更高或更低的日志级别，而不影响其他文件的日志输出时使用。

在文件顶部定义：

#define LOG_LOCAL_LEVEL ESP_LOG_WARN
#include "esp_log.h"

这样设置后，当前文件中的所有日志输出会限制在 WARN 级别及以上，即使在代码中调用了 ESP_LOGD()，这些低级别日志也不会输出。

CONFIG_LOG_MAXIMUM_LEVEL

可以在 menuconfig 中使用选项 CONFIG_LOG_MAXIMUM_LEVEL 设置最高日志级别。这个选项默认被配置为默认级别，但这个选项也可以被配置为更高级别，将更多的可选日志编译到固件中。

三者的优先级和交互关系

1. CONFIG_LOG_DEFAULT_LEVEL 是项目的全局默认日志级别，影响所有模块，但它可以被 esp_log_level_set和 LOG_LOCAL_LEVEL 覆盖。
2. LOG_LOCAL_LEVEL 的优先级高于CONFIG_LOG_DEFAULT_LEVEL，并且只能影响定义了它的源文件。如果某文件定义了 #define LOG_LOCAL_LEVEL ESP_LOG_WARN，即便全局日志级别为 INFO，该文件仍会限制在 WARN 及以上。

总结

• 如果想控制单个模块的日志输出，可以在代码中用 esp_log_level_set(TAG, level)。
• 如果希望在编译时控制单个文件的日志级别，可以使用 LOG_LOCAL_LEVEL。
• 如果需要在项目整体上控制日志级别，使用 CONFIG_LOG_DEFAULT_LEVEL。

五. 日志格式

默认的日志输出格式包括时间戳、日志级别和标签等。输出样例如下：

I (200) my_module: System is running at 160 MHz

其中：

• I 表示 INFO 级别。
• (200) 表示时间戳（从系统启动以来的毫秒数）。
• my_module 是 TAG 标签。