Библиотека лога предоставляет 2 способа установки подробности вывода информации (verbosity level):

· В момент компиляции (compile time): в menuconfig установить verbosity level по умолчанию, используя опцию CONFIG_LOG_DEFAULT_LEVEL.
· Опционально, также в menuconfig, установите максимальный уровень подробности (maximum verbosity level), используя опцию CONFIG_LOG_MAXIMUM_LEVEL. По умолчанию она имеет такое же значение, что и CONFIG_LOG_DEFAULT_LEVEL, однако её можно установить на более высокий уровень, чтобы скомпилировать в firmware больше опциональных логов.
· Во время работы приложения (runtime): все логи, у которых уровни подробности меньше, чем CONFIG_LOG_DEFAULT_LEVEL, по умолчанию разрешены. Функция esp_log_level_set() может использоваться для установки уровня подробности лога в пределах одного модуля (файла исходного кода). Модули идентифицируются по своим тегам, которые являются удобочитаемыми строками ASCIIZ.

Существуют следующие уровни подробности лога (verbosity level):

· Error (самый низкий уровень, выводятся только ошибки)
· Warning
· Info
· Debug
· Verbose (самый высокий уровень подробности вывода)

Замечание: функция esp_log_level_set() не может установить уровни подробности лога выше, чем это указано опцией CONFIG_LOG_MAXIMUM_LEVEL. Чтобы увеличить уровень лога для определенного фала выше этого максимума в момент компиляции, используйте макрос LOG_LOCAL_LEVEL (подробнее об этом см. далее).

[Как использовать библиотеку лога ESP-IDF]

В каждом C-файле (модуле), в котором используется лог, определите переменную TAG, как показано ниже:

static const char* TAG = "MyModule";

Затем используйте макросы вывода, например:

ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud",
              error * 100, baud_req, baud_real);

Доступны несколько макросов для разных уровней подробности вывода:

ESP_LOGE - error (самый низкий уровень)
ESP_LOGW - warning
ESP_LOGI - info
ESP_LOGD - debug
ESP_LOGV - verbose (самый высокий уровень)

Эти макросы отличаются друг от друга двумя моментами: во-первых, будет или не будет выведено макросом сообщение, зависит от текущего установленного уровня подробности. Во-вторых, отличается цвет текста выводимых сообщений в команде idf.py monitor. Например, ESP_LOGI выведет сообщение зеленым текстом, ESP_LOGW желтым текстом, а ESP_LOGE красным текстом.

Дополнительно существуют версии ESP_EARLY_LOGx для этих макросов, например ESP_EARLY_LOGE. Эти версии явно используются только в коде раннего запуска (startup), до того момента, как инициализируется куча (heap allocator) и системные вызовы (syscalls). Обычные макросы ESP_LOGx могут также использоваться, когда компилируется bootloader, однако для них произойдет откат обратно к той же реализации, что и у макросов ESP_EARLY_LOGx.

Также существуют версии ESP_DRAM_LOGx этих макросов, например ESP_DRAM_LOGE. Эти версии используются в некоторых местах, где вывод в лог может привести в условиях запрещенных прерываний, или когда кэш памяти flash недоступна. Использование этих макросов должно быть максимально щадящим, поскольку вывод в лог на таких местах кода вообще следует избегать по соображениям производительности.

Замечание: внутри критических секций кода прерывания запрещены, так что можно использовать только лишь ESP_DRAM_LOGx (что предпочтительнее) или ESP_EARLY_LOGx. Несмотря на то, что есть возможность использовать такой лог в этих ситуациях, лучше всего хорошо структурировать программу, чтобы это вовсе не потребовалось.

Чтобы отменить уровень подробности лога по умолчанию для области файла или области компонента, определите макрос LOG_LOCAL_LEVEL.

Для области файла определите этот макрос перед подключением esp_log.h, например:

#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE

#include "esp_log.h"

В области компонента определите его в файле CMakeLists компонента:

target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_VERBOSE")

Для конфигурирования вывода в области модуля runtime, добавьте вызовы функции esp_log_level_set() следующим образом:

esp_log_level_set("*", ESP_LOG_ERROR);        // установить уровень ERROR для всех компонентов
esp_log_level_set("wifi", ESP_LOG_WARN);      // разрешить логи WARN для стека WiFi
esp_log_level_set("dhcpc", ESP_LOG_INFO);     // разрешить логи INFO из клиента DHCP

Замечание: варианты макросов лога "DRAM" и "EARLY", упомянутые выше, не поддерживают установку подробности вывода в лог в области модуля. Эти макросы всегда будут использовать verbosity level по умолчанию, который можно поменять runtime только вызовом esp_log_level("*", level).

Лог на хост через JTAG. По умолчанию библиотека лога использует функцию наподобие vprintf для форматированного вывода в выделенный для программирования и лога UART. Вместо этого простым API-вызовом вывод может быть перенаправлен в JTAG, что сделает вывод в лог в несколько раз быстрее. За подробностями обратитесь в раздел "Logging to Host" документации [2].

[Пример приложения]

Библиотека лога используется в большинстве компонентов примеров и примеров ESP-IDF как основной метод отладки и поиска ошибок. Для демонстрации функционала вывода в лог просмотрите содержимое директории examples каталога установки ESP-IDF. Наиболее подходящие примеры для исследования работы лога:

system/ota
storage/sd_card
protocols/https_request

[Справочник по API]

Заголовочный файл библиотеки лога components/log/include/esp_log.h.

В следующей таблице приведен общий список API-функций и макросов лога с кратким описанием. Подробное описание с назначением параметров, возвращаемых значений, типов данных см. в документации [1].

API-функции

Макросы

[Ссылки]

1. ESP-IDF Logging library site:espressif.com.
2. ESP-IDF Application Level Tracing library site:espressif.com.