ESP8266_RTOS_SDK v1.4.0

- Main Page
- Modules
- Data Structures
- Files

Modules | Data Structures | Enumerations | Functions
System APIs

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