System

API Reference

Functions

esp_err_t esp_base_mac_addr_set(uint8_t *mac)

Set base MAC address with the MAC address which is stored in EFUSE or external storage e.g. flash and EEPROM.

Base MAC address is used to generate the MAC addresses used by the networking interfaces. If using base MAC address stored in EFUSE or external storage, call this API to set base MAC address with the MAC address which is stored in EFUSE or external storage before initializing WiFi.

Return
ESP_OK on success
Parameters
  • mac: base MAC address, length: 6 bytes.

esp_err_t esp_base_mac_addr_get(uint8_t *mac)

Return base MAC address which is set using esp_base_mac_addr_set.

Return
ESP_OK on success ESP_ERR_INVALID_MAC base MAC address has not been set
Parameters
  • mac: base MAC address, length: 6 bytes.

esp_err_t esp_efuse_mac_get_default(uint8_t *mac)

Return base MAC address which is factory-programmed by Espressif in EFUSE.

Return
ESP_OK on success
Parameters
  • mac: base MAC address, length: 6 bytes.

esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type)

Read base MAC address and set MAC address of the interface.

This function first get base MAC address using esp_base_mac_addr_get or reads base MAC address from EFUSE. Then set the MAC address of the interface including wifi station and wifi softap.

Return
ESP_OK on success
Parameters
  • mac: MAC address of the interface, length: 6 bytes.
  • type: type of MAC address, 0:wifi station, 1:wifi softap.

esp_err_t esp_derive_local_mac(uint8_t *local_mac, const uint8_t *universal_mac)

Derive local MAC address from universal MAC address.

This function derives a local MAC address from an universal MAC address. A definition of local vs universal MAC address can be found on Wikipedia <>. In ESP8266, universal MAC address is generated from base MAC address in EFUSE or other external storage. Local MAC address is derived from the universal MAC address.

Return
ESP_OK on success
Parameters
  • local_mac: Derived local MAC address, length: 6 bytes.
  • universal_mac: Source universal MAC address, length: 6 bytes.

void esp_set_cpu_freq(esp_cpu_freq_t cpu_freq)

Switch CPU frequency.

If a PLL-derived frequency is requested (80, 160), this function will enable the PLL. Otherwise, PLL will be disabled. Note: this function is not optimized for switching speed. It may take several hundred microseconds to perform frequency switch.

Parameters
  • cpu_freq: new CPU frequency

void system_restore(void)

Reset to default settings.

void esp_restart(void)

Restart CPU.

This function does not return.

esp_reset_reason_t esp_reset_reason(void)

Get reason of last reset.

Return
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.

Return
Available heap size, in bytes.

uint32_t esp_get_minimum_free_heap_size(void)

Get the minimum heap that has ever been available.

Return
Minimum free heap ever available

uint32_t esp_random(void)

Get one random 32-bit word from hardware RNG.

Return
Random value between 0 and UINT32_MAX

void esp_fill_random(void *buf, size_t len)

Fill a buffer with random bytes from hardware RNG.

Note
This function has the same restrictions regarding available entropy as esp_random()
Parameters
  • buf: Pointer to buffer to fill with random numbers.
  • len: Length of buffer in bytes

void esp_chip_info(esp_chip_info_t *out_info)

Fill an esp_chip_info_t structure with information about the chip.

Parameters
  • out_info: structure to be filled

flash_size_map system_get_flash_size_map(void)

Get the current Flash size and Flash map.

Flash map depends on the selection when compiling, more details in document “2A-ESP8266__IOT_SDK_User_Manual”

Return
enum flash_size_map

Structures

struct esp_chip_info_t

The structure represents information about the chip.

Public Members

esp_chip_model_t model

chip model, one of esp_chip_model_t

uint32_t features

bit mask of CHIP_FEATURE_x feature flags

uint8_t cores

number of CPU cores

uint8_t revision

chip revision number

Macros

CRYSTAL_USED
CHIP_FEATURE_EMB_FLASH

Chip has embedded flash memory.

Chip feature flags, used in esp_chip_info_t

CHIP_FEATURE_WIFI_BGN

Chip has 2.4GHz WiFi.

CHIP_FEATURE_BLE

Chip has Bluetooth LE.

CHIP_FEATURE_BT

Chip has Bluetooth Classic.

Enumerations

enum esp_mac_type_t

Values:

ESP_MAC_WIFI_STA
ESP_MAC_WIFI_SOFTAP
enum esp_reset_reason_t

Reset reasons.

Values:

ESP_RST_UNKNOWN = 0

Reset reason can not be determined.

ESP_RST_POWERON

Reset due to power-on event.

ESP_RST_EXT

Reset by external pin (not applicable for ESP8266)

ESP_RST_SW

Software reset via esp_restart.

ESP_RST_PANIC

Software reset due to exception/panic.

ESP_RST_INT_WDT

Reset (software or hardware) due to interrupt watchdog.

ESP_RST_TASK_WDT

Reset due to task watchdog.

ESP_RST_WDT

Reset due to other watchdogs.

ESP_RST_DEEPSLEEP

Reset after exiting deep sleep mode.

ESP_RST_BROWNOUT

Brownout reset (software or hardware)

ESP_RST_SDIO

Reset over SDIO.

enum esp_cpu_freq_t

CPU frequency values.

Values:

ESP_CPU_FREQ_80M = 1

80 MHz

ESP_CPU_FREQ_160M = 2

160 MHz

enum flash_size_map

Values:

FLASH_SIZE_4M_MAP_256_256 = 0

Flash size : 4Mbits. Map : 256KBytes + 256KBytes

FLASH_SIZE_2M

Flash size : 2Mbits. Map : 256KBytes

FLASH_SIZE_8M_MAP_512_512

Flash size : 8Mbits. Map : 512KBytes + 512KBytes

FLASH_SIZE_16M_MAP_512_512

Flash size : 16Mbits. Map : 512KBytes + 512KBytes

FLASH_SIZE_32M_MAP_512_512

Flash size : 32Mbits. Map : 512KBytes + 512KBytes

FLASH_SIZE_16M_MAP_1024_1024

Flash size : 16Mbits. Map : 1024KBytes + 1024KBytes

FLASH_SIZE_32M_MAP_1024_1024

Flash size : 32Mbits. Map : 1024KBytes + 1024KBytes

FLASH_SIZE_32M_MAP_2048_2048

attention: don’t support now ,just compatible for nodemcu; Flash size : 32Mbits. Map : 2048KBytes + 2048KBytes

FLASH_SIZE_64M_MAP_1024_1024

Flash size : 64Mbits. Map : 1024KBytes + 1024KBytes

FLASH_SIZE_128M_MAP_1024_1024

Flash size : 128Mbits. Map : 1024KBytes + 1024KBytes

FALSH_SIZE_MAP_MAX
enum esp_chip_model_t

Chip models.

Values:

CHIP_ESP8266 = 0

ESP8266.

CHIP_ESP32 = 1

ESP32.