[Software Reset]

Для выполнения программного сброса (software reset) предоставляется функция esp_restart(). Когда эта функция вызвана, выполнение программы останавливается, CPU сбрасывается, и приложение загружается кодом bootloader, после чего приложение снова запускается.

Дополнительно может быть зарегистрирована функция esp_register_shutdown_handler() как подпрограмма, которая будет автоматически вызвана перед перезапуском (который был из-за esp_restart()). Функционал этого аналогичен функции atexit POSIX.

[Reset Reason]

Приложение ESP-IDF может быть запущено или сброшено по разным причинам - после перепрошивки, из-за сбоя программного обеспечения, из-за пропадания питания. Чтобы узнать последнюю причину, которая вызвала перезагрузку (reset reason), вызовите функцию esp_reset_reason(). В перечислении esp_reset_reason_t определен список возможных причин сброса.

/**

 * @brief Причины сброса

 */

typedef enum
{
   ESP_RST_UNKNOWN,    //!< Причину сброса выяснить не удалось
   ESP_RST_POWERON,    //!< Сброс после подачи питания (power-on event)
   ESP_RST_EXT,        //!< Сброс от внешнего вывода (неприменимо для ESP32)
   ESP_RST_SW,         //!< Программный сброс от вызова esp_restart
   ESP_RST_PANIC,      //!< Программный сброс из-за сбоя ПО (exception/panic)
   ESP_RST_INT_WDT,    //!< Сброс (программный или аппаратный) из-за прерывания
                       //   от сторожевого таймера (interrupt watchdog)
   ESP_RST_TASK_WDT,   //!< Сброс из-за задачи сторожевого таймера (task watchdog)
   ESP_RST_WDT,        //!< Сброс из-за других сторожевых таймеров
   ESP_RST_DEEPSLEEP,  //!< Сброс после выхода из режима deep sleep
   ESP_RST_BROWNOUT,   //!< Сброс от сбоя по питанию (brownout reset,
                       //   программный или аппаратный)
   ESP_RST_SDIO,       //!< Сброс через SDIO
} esp_reset_reason_t;

[Память кучи]

Предоставляются 2 функции, связанные с кучей (heap):

esp_get_free_heap_size() возвратит текущий размер свободной памяти в куче.

esp_get_minimum_free_heap_size() возвратит минимальный размер свободной памяти кучи, который был когда-либо доступен (т. е. самый маленький размер свободной памяти в куче, который был за время жизни приложения).

Обратите внимание, что ESP-IDF поддерживает несколько куч с разными возможностями. Функции, упомянутые в этой секции, возвратят размер памяти кучи, которую можно выделить с использованием функций семейства malloc. Для дополнительной информации о памяти кучи см. [2].

[MAC-адрес]

Эти функции позволяют запрашивать и настраивать MAC-адреса различных сетевых интерфейсов (например Wi-Fi, Bluetooth, Ethernet).

Для извлечения MAC-адреса определенного сетевого интерфейса (Wi-Fi, Bluetooth, Ethernet) вызовите функцию esp_read_mac().

В ESP-IDF адреса MAC для различных сетевых интерфейсов вычисляются из одного базового MAC-адреса. По умолчанию используется Espressif base MAC. Этот базовый MAC-адрес предварительно программируется в eFuse-память ESP32-C3 на заводе, в процессе производства чипов.

Таблица 1. Принцип назначения MAC-адресов для различных интерфейсов.

Конфигурация задает количество универсально администрируемых MAC-адресов, которые предоставлены Espressif.

Примечание: хотя у ESP32-C3 нет встроенной аппаратуры Ethernet MAC, все еще можно вычислить адрес Ethernet MAC. Однако этот MAC-адрес может использоваться только с внешним интерфейсом Ethernet, таким как устройство SPI-Ethernet [3].

Custom Interface MAC. Иногда может понадобиться определить пользовательский MAC-адрес, который не был сгенерирован на основе base MAC address. Чтобы установить MAC-адрес пользовательского интерфейса, используйте функцию esp_iface_mac_addr_set(). Она позволяет перезаписать MAC-адреса для набора интерфейсов. Как только MAC-адрес для определенного интерфейса был установлен, на него больше не будет влиять изменение базового MAC-адреса.

Custom Base MAC. Базовый MAC по умолчанию запрограммирован на заводе Espressif в eFuse BLK1. Чтобы установить вместо него пользовательский базовый MAC, вызовите функцию esp_iface_mac_addr_set() с аргументом ESP_MAC_BASE (или esp_base_mac_addr_set()) перед инициализацией любого сетевого интерфейса или вызова esp_read_mac(). Пользовательский MAC-адрес может быть сохранен в любое поддерживаемое энергонезависимое хранилище (например flash, NVS).

Адреса custom base MAC должны быть выделены таким образом, чтобы вычисленные MAC-адреса не перекрывались. На основе показанной выше таблицы 1 пользователи могут сконфигурировать опцию CONFIG_ESP32C3_UNIVERSAL_MAC_ADDRESSES для установки количества допустимых универсальных MAC-адресов, которые могут быть вычислены из custom base MAC.

Примечание: можно вызвать esp_netif_set_mac() для установки определенного MAC, используемого сетевым интерфейсом, после инициализации сети. Однако рекомендуется использовать базовый подход к MAC-адресам, описанный здесь, чтобы избежать возможности краткого отображения исходного MAC-адреса в сети перед его изменением.

Custom MAC Address в eFuse. Когда из eFuse считываются пользовательские MAC-адреса, ESP-IDF предоставляет вспомогательную функцию esp_mac_get_custom(). Пользователи могут также использовать для этого esp_read_mac() с параметром ESP_MAC_EFUSE_CUSTOM. Это загрузит MAC-адрес из eFuse BLK3. Функция esp_mac_get_custom() подразумевает, что custom base MAC address сохранен в следующем формате:

Примечание: eFuse BLK3 при прошивке значений бит использует RS-кодирование. Это означает, что все поля eFuse в этом блоке должны быть прошиты одновременно.

Как только custom eFuse MAC address был получен (с использованием esp_efuse_mac_get_custom() или esp_read_mac()), вам нужно установить его как base MAC address. Для этого существует 2 способа:

Старое API: вызов esp_base_mac_addr_set().
Новое API: вызов esp_iface_mac_addr_set() с аргументом ESP_MAC_BASE.

Local MAC против Universal MAC. ESP32-C3 поставляется запрограммированным достаточным количеством универсально администрируемых MAC-адресов Espressif для всех внутренних интерфейсов. В таблице 1 показано, как вычислить и получить MAC-адрес для определенного интерфейса в соответствии с base MAC address.

Когда используется пользовательская схема MAC-адресов (custom MAC address), возможна ситуация, когда не всем интерфейсам может быть назначен универсально администрируемый MAC-адрес (Universal MAC). В таких случаях назначается локально администрируемый MAC-адрес (Local MAC). Обратите внимание, что эти адреса предназначены только для использования в одной локальной сети. См. Википедию [4] для определения локально и универсально администрируемых MAC-адресов.

Функция esp_derive_local_mac() вызывается внутри системы для получения локального MAC-адреса из универсального MAC-адреса. Этот процесс заключается в следующем:

1. Бит U/L (значение бита 0x2) устанавливается в первом октете универсального MAC-адреса, создавая локальный MAC-адрес.

2. Если этот бит уже установлен в предоставленном универсальном MAC-адресе (например предоставленный "универсальный" MAC-адрес уже был фактически локальным MAC-адресом), то на первый октет локального MAC-адреса применяется операция XOR со значением 0x4.

[Chip Version]

Функция esp_chip_info() заполнит структуру esp_chip_info_t информацией работающего чипа. Она включает ревизию чипа, количество ядер CPU и битовую маску функций, разрешенных в чипе.

[SDK Version]

Функция esp_get_idf_version() возвратит строку, описывающую версию ESP-IDF, которая использовалась для компиляции приложения. У этой строки такое же значение, которое доступна в переменной IDF_VER системы сборки [6]. У строки версии обычно такой же формат, как у вывода команды git describe.

Чтобы получить значение версии во время сборки, предоставляются дополнительные макросы. Они могут использоваться для разрешения или запрета определенных частей программы в зависимости от версии ESP-IDF version.

ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH определены в целые числа, представляющие значения версий major, minor и patch.

ESP_IDF_VERSION_VAL и ESP_IDF_VERSION могут использоваться для реализации проверок версии:

#include "esp_idf_version.h"

#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
   // Разрешен функционал, присутствующий в ESP-IDF v4.0

#endif

[App Version]

Версия приложения сохранена в структуре esp_app_desc_t [7]. Она находится в секторе DROM, и имеет фиксированное смещение относительно двоичного образа файла прошивки. Эта структура находится за структурами esp_image_header_t и esp_image_segment_header_t. Тип поля version это строка с максимум 3 символами, включая байт 0 в качестве терминатора строки.

Чтобы вручную установить версию проекта, необходимо установить значение переменной PROJECT_VER в файле CMakeLists.txt проекта. В файле CMakeLists.txt приложения поместите строку set(PROJECT_VER "0.1.0.1") перед подключением project.cmake.

Если установлена опция CONFIG_APP_PROJECT_VER_FROM_CONFIG, то будет использоваться значение опции CONFIG_APP_PROJECT_VER. Иначе, если переменная PROJECT_VER в проекте не установлена, она будет получена либо из файла $(PROJECT_PATH)/version.txt (если он присутствует) либо с помощью команды git describe. Если ничего из этого недоступно, то PROJECT_VER будет установлено в "1". Приложение может использовать это значение вызовом функций esp_app_get_description() или esp_ota_get_partition_description().

[Справочник по API-функциям]

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

[Ссылки]

1. ESP32-C3 Miscellaneous System API site:espressif.com.
2. ESP32-C3: выделение памяти из кучи.
3. ESP32-C3 Ethernet site:espressif.com.
4. MAC address site:en.wikipedia.org.
5. ESP32: процесс запуска приложения.
6. ESP-IDF Build System.
7. ESP-IDF: формат файла образа приложения.