System APIs. More...

Modules
	Boot APIs
	boot APIs

	Upgrade APIs
	Firmware upgrade (FOTA) APIs.

Data Structures
struct	rst_info

Enumerations
enum	rst_reason { REASON_DEFAULT_RST = 0, REASON_WDT_RST, REASON_EXCEPTION_RST, REASON_SOFT_WDT_RST, REASON_SOFT_RESTART, REASON_DEEP_SLEEP_AWAKE, REASON_EXT_SYS_RST }

Functions
struct rst_info *	system_get_rst_info (void)
	Get the reason of restart. More...

const char *	system_get_sdk_version (void)
	Get information of the SDK version. More...

void	system_restore (void)
	Reset to default settings. More...

void	system_restart (void)
	Restart system. More...

void	system_deep_sleep (uint32 time_in_us)
	Set the chip to deep-sleep mode. More...

bool	system_deep_sleep_set_option (uint8 option)
	Call this API before system_deep_sleep to set the activity after the next deep-sleep wakeup. More...

uint32	system_get_time (void)
	Get system time, unit: microsecond. More...

void	system_print_meminfo (void)
	Print the system memory distribution, including data/rodata/bss/heap. More...

uint32	system_get_free_heap_size (void)
	Get the size of available heap. More...

uint32	system_get_chip_id (void)
	Get the chip ID. More...

uint32	system_rtc_clock_cali_proc (void)
	Get the RTC clock cycle. More...

uint32	system_get_rtc_time (void)
	Get RTC time, unit: RTC clock cycle. More...

bool	system_rtc_mem_read (uint8 src, void *dst, uint16 n)
	Read user data from the RTC memory. More...

bool	system_rtc_mem_write (uint8 dst, const void *src, uint16 n)
	Write user data to the RTC memory. More...

void	system_uart_swap (void)
	UART0 swap. More...

void	system_uart_de_swap (void)
	Disable UART0 swap. More...

uint16	system_adc_read (void)
	Measure the input voltage of TOUT pin 6, unit : 1/1024 V. More...

uint16	system_get_vdd33 (void)
	Measure the power voltage of VDD3P3 pin 3 and 4, unit : 1/1024 V. More...

bool	system_param_save_with_protect (uint16 start_sec, void *param, uint16 len)
	Write data into flash with protection. More...

bool	system_param_load (uint16 start_sec, uint16 offset, void *param, uint16 len)
	Read the data saved into flash with the read/write protection. More...

void	system_phy_set_max_tpw (uint8 max_tpw)
	Set the maximum value of RF TX Power, unit : 0.25dBm. More...

void	system_phy_set_tpw_via_vdd33 (uint16 vdd33)
	Adjust the RF TX Power according to VDD33, unit : 1/1024 V. More...

void	system_phy_set_rfoption (uint8 option)
	Enable RF or not when wakeup from deep-sleep. More...

Detailed Description

System APIs.

Enumeration Type Documentation

enum rst_reason

Enumerator
REASON_DEFAULT_RST	normal startup by power on
REASON_WDT_RST	hardware watch dog reset
REASON_EXCEPTION_RST	exception reset, GPIO status won't change
REASON_SOFT_WDT_RST	software watch dog reset, GPIO status won't change
REASON_SOFT_RESTART	software restart ,system_restart , GPIO status won't change
REASON_DEEP_SLEEP_AWAKE	wake up from deep-sleep
REASON_EXT_SYS_RST	external system reset

Function Documentation

uint16 system_adc_read ( void )

Measure the input voltage of TOUT pin 6, unit : 1/1024 V.

Attention: 1. system_adc_read can only be called when the TOUT pin is connected to the external circuitry, and the TOUT pin input voltage should be limited to 0~1.0V.; 2. When the TOUT pin is connected to the external circuitry, the 107th byte (vdd33_const) of esp_init_data_default.bin(0~127byte) should be set as the real power voltage of VDD3P3 pin 3 and 4.; 3. The unit of vdd33_const is 0.1V, the effective value range is [18, 36]; if vdd33_const is in [0, 18) or (36, 255), 3.3V is used to optimize RF by default.

Parameters

null

Returns: Input voltage of TOUT pin 6, unit : 1/1024 V

void system_deep_sleep ( uint32 time_in_us )

Set the chip to deep-sleep mode.

The device will automatically wake up after the deep-sleep time set by the users. Upon waking up, the device boots up from user_init.

Attention: 1. XPD_DCDC should be connected to EXT_RSTB through 0 ohm resistor in order to support deep-sleep wakeup.; 2. system_deep_sleep(0): there is no wake up timer; in order to wake up, connect a GPIO to pin RST, the chip will wake up by a falling-edge on pin RST

Parameters

uint32 time_in_us : deep-sleep time, unit: microsecond

Returns: null

bool system_deep_sleep_set_option ( uint8 option )

Call this API before system_deep_sleep to set the activity after the next deep-sleep wakeup.

If this API is not called, default to be system_deep_sleep_set_option(1).

Parameters

uint8	option :
0	: Radio calibration after the deep-sleep wakeup is decided by byte 108 of esp_init_data_default.bin (0~127byte).
1	: Radio calibration will be done after the deep-sleep wakeup. This will lead to stronger current.
2	: Radio calibration will not be done after the deep-sleep wakeup. This will lead to weaker current.
4	: Disable radio calibration after the deep-sleep wakeup (the same as modem-sleep). This will lead to the weakest current, but the device can't receive or transmit data after waking up.

Returns: true : succeed; false : fail

uint32 system_get_chip_id ( void )

Get the chip ID.

Parameters

null

Returns: The chip ID.

uint32 system_get_free_heap_size ( void )

Get the size of available heap.

Parameters

null

Returns: Available heap size.

struct rst_info* system_get_rst_info ( void )

Get the reason of restart.

Parameters

null

Returns: struct rst_info* : information of the system restart

uint32 system_get_rtc_time ( void )

Get RTC time, unit: RTC clock cycle.

Example: If system_get_rtc_time returns 10 (it means 10 RTC cycles), and system_rtc_clock_cali_proc returns 5.75 (it means 5.75 microseconds per RTC clock cycle), (then the actual time is 10 x 5.75 = 57.5 microseconds.

Attention: System time will return to zero because of system_restart, but the RTC time still goes on. If the chip is reset by pin EXT_RST or pin CHIP_EN (including the deep-sleep wakeup), situations are shown as below:; 1. reset by pin EXT_RST : RTC memory won't change, RTC timer returns to zero; 2. watchdog reset : RTC memory won't change, RTC timer won't change; 3. system_restart : RTC memory won't change, RTC timer won't change; 4. power on : RTC memory is random value, RTC timer starts from zero; 5. reset by pin CHIP_EN : RTC memory is random value, RTC timer starts from zero

Parameters

null

Returns: RTC time.

const char* system_get_sdk_version ( void )

Get information of the SDK version.

Parameters

null

Returns: Information of the SDK version.

uint32 system_get_time ( void )

Get system time, unit: microsecond.

Parameters

null

Returns: System time, unit: microsecond.

uint16 system_get_vdd33 ( void )

Measure the power voltage of VDD3P3 pin 3 and 4, unit : 1/1024 V.

Attention: 1. system_get_vdd33 depends on RF, please do not use it if RF is disabled.; 2. system_get_vdd33 can only be called when TOUT pin is suspended.; 3. The 107th byte in esp_init_data_default.bin (0~127byte) is named as "vdd33_const", when TOUT pin is suspended vdd33_const must be set as 0xFF, that is 255.

Parameters

null

Returns: Power voltage of VDD33, unit : 1/1024 V

bool system_param_load	(	uint16	start_sec,
		uint16	offset,
		void *	param,
		uint16	len
	)

Read the data saved into flash with the read/write protection.

Flash read/write has to be 4-bytes aligned.

Read/write protection of flash: use 3 sectors (4KB per sector) to save 4KB data with protect, sector 0 and sector 1 are data sectors, back up each other, save data alternately, sector 2 is flag sector, point out which sector is keeping the latest data, sector 0 or sector 1.

Parameters

uint16	start_sec : start sector (sector 0) of the 3 sectors used for flash read/write protection. It cannot be sector 1 or sector 2. For example, in IOT_Demo, the 3 sectors (3 * 4KB) starting from flash 0x3D000 can be used for flash read/write protection. The parameter start_sec is 0x3D, and it cannot be 0x3E or 0x3F.
uint16	offset : offset of data saved in sector
void	*param : data pointer
uint16	len : data length, offset + len =< 4 * 1024

Returns: true : succeed; false : fail

bool system_param_save_with_protect	(	uint16	start_sec,
		void *	param,
		uint16	len
	)

Write data into flash with protection.

Flash read/write has to be 4-bytes aligned.

Protection of flash read/write : use 3 sectors (4KBytes per sector) to save 4KB data with protect, sector 0 and sector 1 are data sectors, back up each other, save data alternately, sector 2 is flag sector, point out which sector is keeping the latest data, sector 0 or sector 1.

Parameters

uint16	start_sec : start sector (sector 0) of the 3 sectors which are used for flash read/write protection. For example, in IOT_Demo we can use the 3 sectors (3 * 4KB) starting from flash 0x3D000 for flash read/write protection, so the parameter start_sec should be 0x3D
void	*param : pointer of the data to be written
uint16	len : data length, should be less than a sector, which is 4 * 1024

Returns: true : succeed; false : fail

void system_phy_set_max_tpw ( uint8 max_tpw )

Set the maximum value of RF TX Power, unit : 0.25dBm.

Parameters

uint8 max_tpw : the maximum value of RF Tx Power, unit : 0.25dBm, range [0, 82]. It can be set refer to the 34th byte (target_power_qdb_0) of esp_init_data_default.bin(0~127byte)

Returns: null

void system_phy_set_rfoption ( uint8 option )

Enable RF or not when wakeup from deep-sleep.

Attention: 1. This API can only be called in user_rf_pre_init.; 2. Function of this API is similar to system_deep_sleep_set_option, if they are both called, it will disregard system_deep_sleep_set_option which is called before deep-sleep, and refer to system_phy_set_rfoption which is called when deep-sleep wake up.; 3. Before calling this API, system_deep_sleep_set_option should be called once at least.

Parameters

uint8

option :

0 : Radio calibration after deep-sleep wake up depends on esp_init_data_default.bin (0~127byte) byte 108.
1 : Radio calibration is done after deep-sleep wake up; this increases the current consumption.
2 : No radio calibration after deep-sleep wake up; this reduces the current consumption.
4 : Disable RF after deep-sleep wake up, just like modem sleep; this has the least current consumption; the device is not able to transmit or receive data after wake up.

Returns: null

void system_phy_set_tpw_via_vdd33 ( uint16 vdd33 )

Adjust the RF TX Power according to VDD33, unit : 1/1024 V.

Attention: 1. When TOUT pin is suspended, VDD33 can be measured by system_get_vdd33.; 2. When TOUT pin is connected to the external circuitry, system_get_vdd33 can not be used to measure VDD33.

Parameters

uint16 vdd33 : VDD33, unit : 1/1024V, range [1900, 3300]

Returns: null

void system_print_meminfo ( void )

Print the system memory distribution, including data/rodata/bss/heap.

Parameters

null

Returns: null

void system_restart ( void )

Restart system.

Parameters

null

Returns: null

void system_restore ( void )

Reset to default settings.

Reset to default settings of the following APIs : wifi_station_set_auto_connect, wifi_set_phy_mode, wifi_softap_set_config related, wifi_station_set_config related, and wifi_set_opmode.

Parameters

null

Returns: null

uint32 system_rtc_clock_cali_proc ( void )

Get the RTC clock cycle.

Attention: 1. The RTC clock cycle has decimal part.; 2. The RTC clock cycle will change according to the temperature, so RTC timer is not very precise.

Parameters

null

Returns: RTC clock period (unit: microsecond), bit11~ bit0 are decimal.

bool system_rtc_mem_read	(	uint8	src,
		void *	dst,
		uint16	n
	)

Read user data from the RTC memory.

The user data segment (512 bytes, as shown below) is used to store user data.

|<-— system data(256 bytes) -—>|<--------— user data(512 bytes) ------—>|

Attention: Read and write unit for data stored in the RTC memory is 4 bytes.; src_addr is the block number (4 bytes per block). So when reading data at the beginning of the user data segment, src_addr will be 256/4 = 64, n will be data length.

Parameters

uint8	src : source address of rtc memory, src_addr >= 64
void	*dst : data pointer
uint16	n : data length, unit: byte

Returns: true : succeed; false : fail

bool system_rtc_mem_write	(	uint8	dst,
		const void *	src,
		uint16	n
	)

Write user data to the RTC memory.

During deep-sleep, only RTC is working. So users can store their data in RTC memory if it is needed. The user data segment below (512 bytes) is used to store the user data.

|<-— system data(256 bytes) -—>|<--------— user data(512 bytes) ------—>|

Attention: Read and write unit for data stored in the RTC memory is 4 bytes.; src_addr is the block number (4 bytes per block). So when storing data at the beginning of the user data segment, src_addr will be 256/4 = 64, n will be data length.

Parameters

uint8	src : source address of rtc memory, src_addr >= 64
void	*dst : data pointer
uint16	n : data length, unit: byte

Returns: true : succeed; false : fail

void system_uart_de_swap ( void )

Disable UART0 swap.

Use the original UART0, not MTCK and MTDO.

Parameters

null

Returns: null

void system_uart_swap ( void )

UART0 swap.

Use MTCK as UART0 RX, MTDO as UART0 TX, so ROM log will not output from this new UART0. We also need to use MTDO (U0RTS) and MTCK (U0CTS) as UART0 in hardware.

Parameters

null

Returns: null

Modules

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation