System¶

API Reference¶

Header File¶

esp8266/include/esp_system.h

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

esp_err_t esp_mac_init(void)¶

Initialize MAC address.

Return: 0 if sucess or others failed

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.

ESP_RST_FAST_SW¶: Fast reboot.

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.