Miscellaneous System APIs

Software reset

To perform software reset of the chip, esp_restart() function is provided. When the function is called, execution of the program will stop, both CPUs will be reset, application will be loaded by the bootloader and started again.

Additionally, esp_register_shutdown_handler() function is provided to register a routine which needs to be called prior to restart (when done by esp_restart()). This is similar to the functionality of atexit POSIX function.

Reset reason

ESP-IDF application can be started or restarted due to a variety of reasons. To get the last reset reason, call esp_reset_reason() function. See description of esp_reset_reason_t for the list of possible reset reasons.

Heap memory

Two heap memory related functions are provided:

esp_get_free_heap_size() returns the current size of free heap memory
esp_get_minimum_free_heap_size() returns the minimum size of free heap memory that was available during program execution.

Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the size of heap memory which can be allocated using malloc family of functions. For further information about heap memory see Heap Memory Allocation.

MAC Address

These APIs allow querying and customizing MAC addresses for different network interfaces that supported (e.g. Wi-Fi, Bluetooth, Ethernet).

To fetch MAC address for a specific interface (e.g. Wi-Fi, Bluetooth, Ethernet), call the function esp_read_mac() function.

In ESP-IDF these addresses are calculated from a single Base MAC address. By default, the Espressif base MAC address is used. This MAC is pre-programmed into ESP32-S3 eFuse from the factory.

Interface	MAC address (4 universally administered, default)	MAC address (2 universally administered)
Wi-Fi Station	base_mac	base_mac
Wi-Fi SoftAP	base_mac, +1 to the last octet	Local MAC derived from Wi-Fi Station MAC)
Bluetooth	base_mac, +2 to the last octet	base_mac, +1 to the last octet
Ethernet	base_mac, +3 to the last octet	Local MAC (derived from Bluetooth MAC)

Note

The default configuration is 4 universally administered MAC addresses, and this is recommended when using Espressif-provided MAC addresses.

Note

ESP32-S3 has no integrated Ethernet MAC, but it’s still possible to calculate an Ethernet MAC address. This MAC address can only be used with an external interface such as a SPI-Ethernet device, see Ethernet.

Custom Base MAC

The default Base MAC is pre-programmed by Espressif in eFuse BLK1. To set a custom Base MAC instead, call the function esp_base_mac_addr_set() before initializing any network interfaces or calling the esp_read_mac() function. The customized MAC address can be stored in any supported storage device (e.g. Flash, NVS, etc).

The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Configure the option CONFIG_ESP32S3_UNIVERSAL_MAC_ADDRESSES to set the number of valid universal MAC addresses that can be derived from the custom base MAC, according to the table above.

Note

It is also possible to call the function esp_netif_set_mac() to set the specific MAC used by a network interface, after network initialization. It’s recommended to use the Base MAC approach documented here instead, to avoid the possibility of the original MAC address briefly appearing on the network before it is changed.

Custom MAC address in eFuse

When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function esp_efuse_mac_get_custom(). This loads the MAC address from eFuse BLK3. This function assumes that the custom base MAC address is stored in the following format:

Field	# of bits	Range of bits
MAC address	48	200:248

Note

The eFuse BLK3 uses RS-coding during a burn operation it means that all eFuse fields in this block must be burnt at the same time.

Once MAC address has been obtained using esp_efuse_mac_get_custom(), call esp_base_mac_addr_set() to set this MAC address as base MAC address.

Local vs Universal MAC addresses

ESP32-S3 comes pre-programmed with enough valid Espressif universally administered MAC addresses for all internal interfaces. The specific calculations to derive an interface’s MAC address from the base MAC address is shown in the table above..

When using a custom MAC address scheme, it’s possible that not all interfaces can be assigned a universally administered MAC address. In these cases, a locally administered MAC address is assigned. Note that these addresses are intended for use on a single local network, only.

See this article for the definition of local and universally administered MAC addresses.

Function esp_derive_local_mac() is called internally to derive a local MAC address from a universal MAC address. The process is as follows:

The U/L bit (bit value 0x2) is set in the first octet of the universal MAC address, creating a local MAC address.
If this bit is already set in the supplied universal MAC address (meaning: the supplied “universal” MAC address was in fact already a local MAC address), then the first octet of the local MAC address is XORed with 0x4.

Chip version

esp_chip_info() function fills esp_chip_info_t structure with information about the chip. This includes the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.

SDK version

esp_get_idf_version() returns a string describing the IDF version which was used to compile the application. This is the same value as the one available through IDF_VER variable of the build system. The version string generally has the format of git describe output.

To get the version at build time, additional version macros are provided. They can be used to enable or disable parts of the program depending on IDF version.

ESP_IDF_VERSION_MAJOR, ESP_IDF_VERSION_MINOR, ESP_IDF_VERSION_PATCH are defined to integers representing major, minor, and patch version.

ESP_IDF_VERSION_VAL and ESP_IDF_VERSION can be used when implementing version checks:

#include "esp_idf_version.h"

#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
    // enable functionality present in IDF v4.0
#endif

App version

Application version is stored in esp_app_desc_t structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after esp_image_header_t and esp_image_segment_header_t structures. The field version has string type and max length 32 chars.

To set version in your project manually you need to set PROJECT_VER variable in your project CMakeLists.txt/Makefile:

In application CMakeLists.txt put set(PROJECT_VER "0.1.0.1") before including project.cmake.

(For legacy GNU Make build system: in application Makefile put PROJECT_VER = "0.1.0.1" before including project.mk.)

If CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CONFIG_APP_PROJECT_VER will be used. Otherwise if PROJECT_VER variable is not set in the project then it will be retrieved from either $(PROJECT_PATH)/version.txt file (if present) else using git command git describe. If neither is available then PROJECT_VER will be set to “1”. Application can make use of this by calling esp_ota_get_app_description() or esp_ota_get_partition_description() functions.

API Reference

Header File

components/esp_system/include/esp_system.h

Functions

esp_err_t esp_register_shutdown_handler(shutdown_handler_t handle)

Register shutdown handler.

This function allows you to register a handler that gets invoked before the application is restarted using esp_restart function.

Parameters

handle – function to execute on restart

Returns

ESP_OK on success
ESP_ERR_INVALID_STATE if the handler has already been registered
ESP_ERR_NO_MEM if no more shutdown handler slots are available

esp_err_t esp_unregister_shutdown_handler(shutdown_handler_t handle)

Unregister shutdown handler.

This function allows you to unregister a handler which was previously registered using esp_register_shutdown_handler function.

ESP_OK on success
ESP_ERR_INVALID_STATE if the given handler hasn’t been registered before

void esp_restart(void)

Restart PRO and APP CPUs.

This function can be called both from PRO and APP CPUs. After successful restart, CPU reset reason will be SW_CPU_RESET. Peripherals (except for WiFi, BT, UART0, SPI1, and legacy timers) are not reset. This function does not return.

esp_reset_reason_t esp_reset_reason(void)

Get reason of last reset.

Returns: See description of esp_reset_reason_t for explanation of each value.

uint32_t esp_get_free_heap_size(void)

Get the size of available heap.

Note that the returned value may be larger than the maximum contiguous block which can be allocated.

Returns: Available heap size, in bytes.

uint32_t esp_get_free_internal_heap_size(void)

Get the size of available internal heap.

Note that the returned value may be larger than the maximum contiguous block which can be allocated.

Returns: Available internal heap size, in bytes.

uint32_t esp_get_minimum_free_heap_size(void)

Get the minimum heap that has ever been available.

Returns: Minimum free heap ever available

void esp_system_abort(const char *details)

Trigger a software abort.

Parameters: details – Details that will be displayed during panic handling.

Type Definitions

typedef void (*shutdown_handler_t)(void): Shutdown handler type

Enumerations

enum esp_reset_reason_t

Reset reasons.

Values:

enumerator ESP_RST_UNKNOWN: Reset reason can not be determined.

enumerator ESP_RST_POWERON: Reset due to power-on event.

enumerator ESP_RST_EXT: Reset by external pin (not applicable for ESP32)

enumerator ESP_RST_SW: Software reset via esp_restart.

enumerator ESP_RST_PANIC: Software reset due to exception/panic.

enumerator ESP_RST_INT_WDT: Reset (software or hardware) due to interrupt watchdog.

enumerator ESP_RST_TASK_WDT: Reset due to task watchdog.

enumerator ESP_RST_WDT: Reset due to other watchdogs.

enumerator ESP_RST_DEEPSLEEP: Reset after exiting deep sleep mode.

enumerator ESP_RST_BROWNOUT: Brownout reset (software or hardware)

enumerator ESP_RST_SDIO: Reset over SDIO.

Header File

components/esp_common/include/esp_idf_version.h

Functions

const char *esp_get_idf_version(void)

Return full IDF version string, same as ‘git describe’ output.

Note

If you are printing the ESP-IDF version in a log file or other information, this function provides more information than using the numerical version macros. For example, numerical version macros don’t differentiate between development, pre-release and release versions, but the output of this function does.

Returns: constant string from IDF_VER

Macros

ESP_IDF_VERSION_MAJOR: Major version number (X.x.x)

ESP_IDF_VERSION_MINOR: Minor version number (x.X.x)

ESP_IDF_VERSION_PATCH: Patch version number (x.x.X)

ESP_IDF_VERSION_VAL(major, minor, patch)

Macro to convert IDF version number into an integer

To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)

ESP_IDF_VERSION

Current IDF version, as an integer

To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)

Provide feedback about this document