To perform software reset of the chip, the esp_restart() function is provided. When the function is called, execution of the program stops, both CPUs are reset, the application is loaded by the bootloader and starts execution again.
Additionally, the esp_register_shutdown_handler() function can register a routine that will be automatically called before a restart (that is triggered by esp_restart()) occurs. This is similar to the functionality of atexit POSIX function.
ESP-IDF applications 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.
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 has ever been available (i.e., the smallest size of free heap memory in the application's lifetime).
Note that ESP-IDF supports multiple heaps with different capabilities. The functions mentioned in this section return the size of heap memory that can be allocated using the malloc family of functions. For further information about heap memory, see Heap Memory Allocation.
These APIs allow querying and customizing MAC addresses for different supported network interfaces (e.g., Wi-Fi, Bluetooth, Ethernet).
To fetch the MAC address for a specific network interface (e.g., Wi-Fi, Bluetooth, Ethernet), call the function esp_read_mac().
In ESP-IDF, the MAC addresses for the various network interfaces are calculated from a single base MAC address. By default, the Espressif base MAC address is used. This base MAC address is pre-programmed into the ESP32 eFuse in the factory during production.
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 configuration configures the number of universally administered MAC addresses that are provided by Espressif.
Custom Interface MACïSometimes you may need to define custom MAC addresses that are not generated from the base MAC address. To set a custom interface MAC address, use the esp_iface_mac_addr_set() function. This function allows you to overwrite the MAC addresses of interfaces set (or not yet set) by the base MAC address. Once a MAC address has been set for a particular interface, it will not be affected when the base MAC address is changed.
The default base MAC is pre-programmed by Espressif in eFuse BLK0. To set a custom base MAC instead, call the function esp_iface_mac_addr_set() with the ESP_MAC_BASE argument (or esp_base_mac_addr_set()) before initializing any network interfaces or calling the esp_read_mac() function. The custom MAC address can be stored in any supported storage device (e.g., flash, NVS).
The custom base MAC addresses should be allocated such that derived MAC addresses will not overlap. Based on the table above, users can configure the option CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES to set the number of valid universal MAC addresses that can be derived from the custom base MAC.
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. But it is recommended to use the base MAC approach documented here to avoid the possibility of the original MAC address briefly appearing on the network before being changed.
When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function esp_efuse_mac_get_custom(). Users can also use esp_read_mac() with the ESP_MAC_EFUSE_CUSTOM argument. This loads the MAC address from eFuse BLK3. The esp_efuse_mac_get_custom() function assumes that the custom base MAC address is stored in the following format:
Field
# of bits
Range of bits
Notes
Version
8
191:184
0: invalid, others â valid
Reserved
128
183:56
MAC address
48
55:8
MAC address CRC
8
7:0
CRC-8-CCITT, polynomial 0x07
Note
If the 3/4 coding scheme is enabled, all eFuse fields in this block must be burnt at the same time.
Once custom eFuse MAC address has been obtained (using esp_efuse_mac_get_custom() or esp_read_mac()), you need to set it as the base MAC address. There are two ways to do it:
Use an old API: call esp_base_mac_addr_set().
Use a new API: call esp_iface_mac_addr_set() with the ESP_MAC_BASE argument.
ESP32 comes pre-programmed with enough valid Espressif universally administered MAC addresses for all internal interfaces. The table above shows how to calculate and derive the MAC address for a specific interface according to the base MAC address.
When using a custom MAC address scheme, it is possible that not all interfaces can be assigned with 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 locally 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 (i.e., 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.
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.
esp_get_idf_version() returns a string describing the ESP-IDF version which is 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 the ESP-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 ESP-IDF v4.0
#endif
The 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 type of the field version is string and it has a maximum length of 32 chars.
To set the version in your project manually, you need to set the PROJECT_VER variable in the CMakeLists.txt of your project. In application CMakeLists.txt, put set(PROJECT_VER "0.1.0.1") before including project.cmake.
If the CONFIG_APP_PROJECT_VER_FROM_CONFIG option is set, the value of CONFIG_APP_PROJECT_VER will be used. Otherwise, if the PROJECT_VER variable is not set in the project, it will be retrieved either from the $(PROJECT_PATH)/version.txt file (if present) or using git command git describe. If neither is available, PROJECT_VER will be set to "1". Application can make use of this by calling esp_app_get_description() or esp_ota_get_partition_description() functions.
system/base_mac_address demonstrates how to retrieve, set, and derive the base MAC address for each network interface on ESP32 from non-volatile memory, using either the eFuse blocks or external storage.
Register shutdown handler.
This function allows you to register a handler that gets invoked before the application is restarted using esp_restart function.
handle -- function to execute on restart
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
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
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 Wi-Fi, BT, UART0, SPI1, and legacy timers) are not reset. This function does not return.
Get reason of last reset.
See description of esp_reset_reason_t for explanation of each value.
Get the size of available heap.
Note
Note that the returned value may be larger than the maximum contiguous block which can be allocated.
Available heap size, in bytes.
Get the size of available internal heap.
Note
Note that the returned value may be larger than the maximum contiguous block which can be allocated.
Available internal heap size, in bytes.
Get the minimum heap that has ever been available.
Minimum free heap ever available
Trigger a software abort.
details -- Details that will be displayed during panic handling.
Shutdown handler type
Reset reasons.
Values:
Reset reason can not be determined.
Reset due to power-on event.
Reset by external pin (not applicable for ESP32)
Software reset via esp_restart.
Software reset due to exception/panic.
Reset (software or hardware) due to interrupt watchdog.
Reset due to task watchdog.
Reset due to other watchdogs.
Reset after exiting deep sleep mode.
Brownout reset (software or hardware)
Reset over SDIO.
Reset by USB peripheral.
Reset by JTAG.
Reset due to efuse error.
Reset due to power glitch detected.
Reset due to CPU lock up (double exception)
This header file can be included with:
#include "esp_idf_version.h"
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.
constant string from IDF_VER
Major version number (X.x.x)
Minor version number (x.X.x)
Patch version number (x.x.X)
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)
Current IDF version, as an integer
To be used in comparisons, such as ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(4, 0, 0)
This header file can be included with:
Set base MAC address with the MAC address which is stored in BLK3 of EFUSE or external storage e.g. flash and EEPROM.
Base MAC address is used to generate the MAC addresses used by network interfaces.
If using a custom base MAC address, call this API before initializing any network interfaces. Refer to the ESP-IDF Programming Guide for details about how the Base MAC is used.
Note
Base MAC must be a unicast MAC (least significant bit of first byte must be zero).
Note
If not using a valid OUI, set the "locally administered" bit (bit value 0x02 in the first byte) to avoid collisions.
mac -- base MAC address, length: 6 bytes. length: 6 bytes for MAC-48
ESP_OK on success ESP_ERR_INVALID_ARG If mac is NULL or is not a unicast MAC
Return base MAC address which is set using esp_base_mac_addr_set.
Note
If no custom Base MAC has been set, this returns the pre-programmed Espressif base MAC address.
mac -- base MAC address, length: 6 bytes. length: 6 bytes for MAC-48
ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL ESP_ERR_INVALID_MAC base MAC address has not been set
Return base MAC address which was previously written to BLK3 of EFUSE.
Base MAC address is used to generate the MAC addresses used by the networking interfaces. This API returns the custom base MAC address which was previously written to EFUSE BLK3 in a specified format.
Writing this EFUSE allows setting of a different (non-Espressif) base MAC address. It is also possible to store a custom base MAC address elsewhere, see esp_base_mac_addr_set() for details.
Note
This function is currently only supported on ESP32.
mac -- base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y)
ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL ESP_ERR_INVALID_MAC CUSTOM_MAC address has not been set, all zeros (for esp32-xx) ESP_ERR_INVALID_VERSION An invalid MAC version field was read from BLK3 of EFUSE (for esp32) ESP_ERR_INVALID_CRC An invalid MAC CRC was read from BLK3 of EFUSE (for esp32)
Return base MAC address which is factory-programmed by Espressif in EFUSE.
mac -- base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y)
ESP_OK on success ESP_ERR_INVALID_ARG mac is NULL
Read base MAC address and set MAC address of the interface.
This function first get base MAC address using esp_base_mac_addr_get(). Then calculates the MAC address of the specific interface requested, refer to ESP-IDF Programming Guide for the algorithm.
The MAC address set by the esp_iface_mac_addr_set() function will not depend on the base MAC address.
mac -- base MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI-64(used for IEEE 802.15.4, if CONFIG_SOC_IEEE802154_SUPPORTED=y)
type -- Type of MAC address to return
ESP_OK on success
Derive local MAC address from universal MAC address.
This function copies a universal MAC address and then sets the "locally
administered" bit (bit 0x2) in the first octet, creating a locally administered MAC address.
If the universal MAC address argument is already a locally administered MAC address, then the first octet is XORed with 0x4 in order to create a different locally administered MAC address.
local_mac -- base MAC address, length: 6 bytes. length: 6 bytes for MAC-48
universal_mac -- Source universal MAC address, length: 6 bytes.
ESP_OK on success
Set custom MAC address of the interface. This function allows you to overwrite the MAC addresses of the interfaces set by the base MAC address.
mac -- MAC address, length: 6 bytes/8 bytes. length: 6 bytes for MAC-48 8 bytes for EUI-64(used for ESP_MAC_IEEE802154 type, if CONFIG_SOC_IEEE802154_SUPPORTED=y)
type -- Type of MAC address
ESP_OK on success
Return the size of the MAC type in bytes.
If CONFIG_SOC_IEEE802154_SUPPORTED is set then for these types:
ESP_MAC_IEEE802154 is 8 bytes.
ESP_MAC_BASE, ESP_MAC_EFUSE_FACTORY and ESP_MAC_EFUSE_CUSTOM the MAC size is 6 bytes.
ESP_MAC_EFUSE_EXT is 2 bytes. If CONFIG_SOC_IEEE802154_SUPPORTED is not set then for all types it returns 6 bytes.
type -- Type of MAC address
0 MAC type not found (not supported) 6 bytes for MAC-48. 8 bytes for EUI-64.
Values:
MAC for WiFi Station (6 bytes)
MAC for WiFi Soft-AP (6 bytes)
MAC for Bluetooth (6 bytes)
MAC for Ethernet (6 bytes)
if CONFIG_SOC_IEEE802154_SUPPORTED=y, MAC for IEEE802154 (8 bytes)
Base MAC for that used for other MAC types (6 bytes)
MAC_FACTORY eFuse which was burned by Espressif in production (6 bytes)
MAC_CUSTOM eFuse which was can be burned by customer (6 bytes)
if CONFIG_SOC_IEEE802154_SUPPORTED=y, MAC_EXT eFuse which is used as an extender for IEEE802154 MAC (2 bytes)
This header file can be included with:
#include "esp_chip_info.h"
Fill an esp_chip_info_t structure with information about the chip.
out_info -- [out] structure to be filled
The structure represents information about the chip.
Public Members
chip model, one of esp_chip_model_t
bit mask of CHIP_FEATURE_x feature flags
chip revision number (in format MXX; where M - wafer major version, XX - wafer minor version)
number of CPU cores
Chip has embedded flash memory.
Chip has 2.4GHz WiFi.
Chip has Bluetooth LE.
Chip has Bluetooth Classic.
Chip has IEEE 802.15.4.
Chip has embedded psram.
Chip models.
Values:
ESP32.
ESP32-S2.
ESP32-S3.
ESP32-C3.
ESP32-C2.
ESP32-C6.
ESP32-H2.
ESP32-P4.
ESP32-C61.
ESP32-C5.
ESP32-H21.
ESP32-H4.
The code is running on POSIX/Linux simulator.
This header file can be included with:
Stall a CPU core.
core_id -- The core's ID
Resume a previously stalled CPU core.
core_id -- The core's ID
Reset a CPU core.
core_id -- The core's ID
Wait for Interrupt.
This function causes the current CPU core to execute its Wait For Interrupt (WFI or equivalent) instruction. After executing this function, the CPU core will stop execution until an interrupt occurs.
Get the current core's ID.
This function will return the ID of the current CPU (i.e., the CPU that calls this function).
The current core's ID [0..SOC_CPU_CORES_NUM - 1]
Get the current [RISC-V] CPU core's privilege level.
This function returns the current privilege level of the CPU core executing this function.
The current CPU core's privilege level, -1 if not supported.
Read the current stack pointer address.
Stack pointer address
Get the current CPU core's cycle count.
Each CPU core maintains an internal counter (i.e., cycle count) that increments every CPU clock cycle.
Current CPU's cycle count, 0 if not supported.
Set the current CPU core's cycle count.
Set the given value into the internal counter that increments every CPU clock cycle.
cycle_count -- CPU cycle count
Convert a program counter (PC) value to address.
If the architecture does not store the true virtual address in the CPU's PC or return addresses, this function will convert the PC value to a virtual address. Otherwise, the PC is just returned
pc -- PC value
Virtual address
Get a CPU interrupt's descriptor.
Each CPU interrupt has a descriptor describing the interrupt's capabilities and restrictions. This function gets the descriptor of a particular interrupt on a particular CPU.
core_id -- [in] The core's ID
intr_num -- [in] Interrupt number
intr_desc_ret -- [out] The interrupt's descriptor
Set the base address of the current CPU's Interrupt Vector Table (IVT)
ivt_addr -- Interrupt Vector Table's base address
Check if a particular interrupt already has a handler function.
Check if a particular interrupt on the current CPU already has a handler function assigned.
Note
This function simply checks if the IVT of the current CPU already has a handler assigned.
intr_num -- Interrupt number (from 0 to 31)
True if the interrupt has a handler function, false otherwise.
Set the handler function of a particular interrupt.
Assign a handler function (i.e., ISR) to a particular interrupt on the current CPU.
Note
This function simply sets the handler function (in the IVT) and does not actually enable the interrupt.
intr_num -- Interrupt number (from 0 to 31)
handler -- Handler function
handler_arg -- Argument passed to the handler function
Get a handler function's argument of.
Get the argument of a previously assigned handler function on the current CPU.
intr_num -- Interrupt number (from 0 to 31)
The the argument passed to the handler function
Enable particular interrupts on the current CPU.
intr_mask -- Bit mask of the interrupts to enable
Disable particular interrupts on the current CPU.
intr_mask -- Bit mask of the interrupts to disable
Get the enabled interrupts on the current CPU.
Bit mask of the enabled interrupts
Acknowledge an edge interrupt.
intr_num -- Interrupt number (from 0 to 31)
Configure the CPU to disable access to invalid memory regions.
Set and enable a hardware breakpoint on the current CPU.
Note
This function is meant to be called by the panic handler to set a breakpoint for an attached debugger during a panic.
Note
Overwrites previously set breakpoint with same breakpoint number.
bp_num -- Hardware breakpoint number [0..SOC_CPU_BREAKPOINTS_NUM - 1]
bp_addr -- Address to set a breakpoint on
ESP_OK if breakpoint is set. Failure otherwise
Clear a hardware breakpoint on the current CPU.
Note
Clears a breakpoint regardless of whether it was previously set
bp_num -- Hardware breakpoint number [0..SOC_CPU_BREAKPOINTS_NUM - 1]
ESP_OK if breakpoint is cleared. Failure otherwise
Set and enable a hardware watchpoint on the current CPU.
Set and enable a hardware watchpoint on the current CPU, specifying the memory range and trigger operation. Watchpoints will break/panic the CPU when the CPU accesses (according to the trigger type) on a certain memory range.
Note
Overwrites previously set watchpoint with same watchpoint number. On RISC-V chips, this API uses method0(Exact matching) and method1(NAPOT matching) according to the riscv-debug-spec-0.13 specification for address matching. If the watch region size is 1byte, it uses exact matching (method 0). If the watch region size is larger than 1byte, it uses NAPOT matching (method 1). This mode requires the watching region start address to be aligned to the watching region size.
wp_num -- Hardware watchpoint number [0..SOC_CPU_WATCHPOINTS_NUM - 1]
wp_addr -- Watchpoint's base address, must be naturally aligned to the size of the region
size -- Size of the region to watch. Must be one of 2^n and in the range of [1 ... SOC_CPU_WATCHPOINT_MAX_REGION_SIZE]
trigger -- Trigger type
ESP_ERR_INVALID_ARG on invalid arg, ESP_OK otherwise
Clear a hardware watchpoint on the current CPU.
Note
Clears a watchpoint regardless of whether it was previously set
wp_num -- Hardware watchpoint number [0..SOC_CPU_WATCHPOINTS_NUM - 1]
ESP_OK if watchpoint was cleared. Failure otherwise.
Check if the current CPU has a debugger attached.
True if debugger is attached, false otherwise
Trigger a call to the current CPU's attached debugger.
Given the return address, calculate the address of the preceding call instruction This is typically used to answer the question "where was the function called from?".
return_address -- The value of the return address register. Typically set to the value of __builtin_return_address(0).
Address of the call instruction preceding the return address.
Atomic compare-and-set operation.
addr -- Address of atomic variable
compare_value -- Value to compare the atomic variable to
new_value -- New value to set the atomic variable to
Whether the atomic variable was set or not
CPU interrupt descriptor.
Each particular CPU interrupt has an associated descriptor describing that particular interrupt's characteristics. Call esp_cpu_intr_get_desc() to get the descriptors of a particular interrupt.
Public Members
Priority of the interrupt if it has a fixed priority, (-1) if the priority is configurable.
Whether the interrupt is an edge or level type interrupt, ESP_CPU_INTR_TYPE_NA if the type is configurable.
Flags indicating extra details.
Interrupt descriptor flags of esp_cpu_intr_desc_t.
The interrupt is a special interrupt (e.g., a CPU timer interrupt)
The interrupt is reserved for internal use
CPU cycle count type.
This data type represents the CPU's clock cycle count
CPU interrupt handler type.
CPU interrupt type.
Values:
CPU watchpoint trigger type.
Values:
This header file can be included with:
#include "esp_app_desc.h"
This header file is a part of the API provided by the esp_app_format component. To declare that your component depends on esp_app_format, add the following to your CMakeLists.txt:
or
PRIV_REQUIRES esp_app_format
Return esp_app_desc structure. This structure includes app version.
Return description for running app.
Pointer to esp_app_desc structure.
Fill the provided buffer with SHA256 of the ELF file, formatted as hexadecimal, null-terminated. If the buffer size is not sufficient to fit the entire SHA256 in hex plus a null terminator, the largest possible number of bytes will be written followed by a null.
dst -- Destination buffer
size -- Size of the buffer
Number of bytes written to dst (including null terminator)
Return SHA256 of the ELF file which is already formatted as hexadecimal, null-terminated included. Can be used in panic handler or core dump during when cache is disabled. The length is defined by CONFIG_APP_RETRIEVE_LEN_ELF_SHA option.
Hexadecimal SHA256 string
Description about application.
Public Members
Magic word ESP_APP_DESC_MAGIC_WORD
Secure version
reserv1
Application version
Project name
Compile time
Compile date
Version IDF
sha256 of elf file
Minimal eFuse block revision supported by image, in format: major * 100 + minor
Maximal eFuse block revision supported by image, in format: major * 100 + minor
MMU page size in log base 2 format
reserv3
reserv2
The magic word for the esp_app_desc structure that is in DROM.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4