Esp8266 SDK
Esp8266 SDK
API Reference
Version 3.0.2
Espressif Systems
Copyright © 2020
www.espressif.com
About This Guide
This document lists ESP8266_NONOS_SDK APIs.
Release Notes
Added Section 3.3.50, 3.3.51, 3.3.52, 3.5.76, 3.5.77, 3.5.78, 3.5.79, A.6
Remove system_phy_freq_trace_enable
3.13.10.sntp_get_timezone ..........................................................................................................96
1. Preambles
ESP8266 Wi-Fi SoC offers a complete and self-contained Wi-Fi networking solution; it can
be used to host applications or to offload Wi-Fi networking functions from another
application processor. When the ESP8266 hosts application, it boots up directly from an
external flash. It has an integrated cache to improve the performance of system’s running
applications. Alternately, serving as a Wi-Fi adapter, wireless internet access can be added
into any microcontroller-based design with simple connectivity through UART interface or
the CPU AHB bridge interface.
ESP8266EX is amongst the most integrated Wi-Fi chips in the industry; it integrates the
antenna switches, RF balun, power amplifier, low noise receive amplifier, filters, and power
management modules. Thus, it requires minimal external circuitry, and the entire solution,
including front-end module, is designed to occupy minimal PCB area.
ESP8266EX also integrates an enhanced version of Tensilica’s L106 Diamond series 32-bit
processor, with on-chip SRAM, on top of its Wi-Fi functionalities. It is integrated with
external sensors and other application specific devices through its GPIOs. Codes for such
applications are provided as examples in the SDK.
Sophisticated system-level features include fast sleep/wake switching for energy-efficient
VoIP, adaptive radio biasing for low-power operations, advanced signal processing, spur
cancellation and radio co-existence features for common cellular, Bluetooth, DDR, LVDS,
LCD interference mitigation.
The SDK based on ESP8266 IoT platform offers the users an easy, fast and efficient way to
develop IoT devices. This programming guide provides overview of the SDK as well as
detailed description of the APIs. It is written to help embedded software developers
program on ESP8266 IoT platform.
Espressif ! /!164
1 2020.09
2. Non-OS SDK
!
2. Non-OS SDK
2.1. Non-OS SDK Introduction
The non-OS SDK provides a set of application programming interfaces (APIs) for core
ESP8266 functionalities such as data reception/transmission over Wi-Fi, TCP/IP stack
functions, hardware interface functions and basic system management functions. Thus, the
SDK APIs allow programmers to focus on the application under development at a higher
level. Users can access all core capabilities of ESP8266 without studying its chip
architecture in detail.
All networking functions on the ESP8266 IoT platform are realized in the library, and are
available to users in the form of well-defined APIs. Users can initialize the system hardware
and network interface in user_main.c when ESP8266 boots up.
void user_init (void) is the default method provided. Users can add functions like
firmware initialization, network parameters setting, and timer initialization within user_init.
• For ESP8266_NONOS_SDK_v3.0.0 and later versions, please add void
ICACHE_FLASH_ATTR user_pre_init(void) in user_main.c, and register your
partition table in user_pre_init.
• For versions ESP8266_NONOS_SDK_v1.5.2 to ESP8266_NONOS_SDK_v2.2.1,
void user_rf_pre_init (void) and uint32 user_rf_cal_sector_set(void) need
to be added to user_main.c. For an example of how to set the RF calibration sector,
please refer to ESP8266_NONOS_SDK/examples/IOT_Demo/user/user_main.c.
Users can call system_phy_set_rfoption to set the RF option in user_rf_pre_init,
or call system_deep_sleep_set_option before Deep-sleep. If RF is disabled,
ESP8266 Station and SoftAP will both be disabled, so the related APIs must not be
called. Wi-Fi radio functions and network stack management APIs are not available
when the radio is disabled.
From ESP8266_NONOS_SDK_v2.1.0 onwards, when the DIO-to-QIO flash is not used,
users can add an empty function void user_spi_flash_dio_to_qio_pre_init(void) on
the application side to reduce iRAM usage.
APIs for JSON packet construction and parsing are included in the SDK. Users themselves
can define the format of data packets.
Espressif ! /!164
2 2020.09
2. Non-OS SDK
!
The RTOS SDK is an alternative to non-OS SDK, and may be used where task-based,
modular programming is desirable. To read more about the RTOS SDK, please refer to the
ESP8266 SDK Getting Started Guide.
The code structure in non-OS SDK may be described as follows:
• The non-OS SDK does not implement user task scheduling like RTOS based
systems do. The non-OS SDK uses four types of functions:
- Application functions
- Callback functions
- Interrupt service routines (ISRs)
- User tasks
Application functions refer to the usual type of C functions used in embedded C
programming. These functions must be called by another function. Application
functions may be attributed with ICACHE_FLASH_ATTR to fetch and execute programs
from the flash. IRAM_ATTR-attributed functions are stored in the iRAM prior to
execution.
Callback functions refer to functions that are not called directly from the user
program. Callback functions are executed by the non-OS SDK core when a system
event occurs. This enables the programmer to respond to real-time events without
using RTOS or polling for events.
To program a callback function, users first need to register the callback function using
the corresponding register_cb API. Examples of callback functions include timer
callback functions and network event callback functions.
Interrupt Service Routines (ISRs) are simply callback functions of a special type.
These functions are called when a hardware interrupt occurs. When an interrupt is
enabled, a corresponding interrupt handler functions must be registered. Note that
ISRs must be attributed as IRAM_ATTR.
User tasks can be classified according to three priority levels: 0, 1, 2. Priority level
has the following order: 2>1>0. Non-OS SDK can only support up to three tasks at a
time. One priority level for one task.
User tasks are normally used when a function cannot be called directly. To create a
user task, please refer to the API description of system_os_task() in this document.
For example, espconn_disconnect() API may not be called from within an espconn
callback, therefore a user task must be created within the espconn callback to
execute espconn_disconnect.
• As stated earlier, the non-OS SDK does not preempt tasks or switch context. Users
are responsible for the proper execution of code and the user code must not occupy
the CPU on a particular function for too long. This may cause a watchdog reset and
prompt ESP8266 to reboot.
If for some reason the user application must execute a task for too long (say, longer
than 500 ms), it is recommended that the system_soft_wdt_feed() API be called
often to reset the WDT. Disabling the softWDT is not recommended.
Espressif ! /!164
3 2020.09
2. Non-OS SDK
!
Espressif ! /!164
4 2020.09
2. Non-OS SDK
!
• There is no internal non-volatile storage within ESP8266 for storing user code or data.
The ESP8285 chip is an ESP8266 variant with integrated flash memory. Please refer to
the ESP8285 Datasheet for more details.
• ESP8266 features 160 Kbytes of RAM, of which iRAM is 64 KB and dRAM is 96KB
(dRAM: 80 KB for SDK+HEAP, 16 KB for ROM). The iRAM is further segmented into two
blocks. A 32 KB iRAM block stores code marked with IRAM_ATTR and the other 32 KB
block is used to cache code from flash, i.e. code marked with ICACHE_FLASH_ATTR.
• Since ESP8266_NonOS_SDK_v3.0, we have added a new feature to enable using iRAM
as memory, which can provide about 17 KB extra memory (but the cache size will
decrease to be only 16 KB). Please find the details below. Please note that it may effect
the system performance, so it’s recommended to conduct a thorough test to ensure
what works best for you.
- Define function user_iram_memory_is_enabled in application and return 1 to
enable iRAM as memory. For example,
#define CONFIG_ENABLE_IRAM_MEMORY 1
#ifdef CONFIG_ENABLE_IRAM_MEMORY
uint32 user_iram_memory_is_enabled(void)
return CONFIG_ENABLE_IRAM_MEMORY;
#endif
- After setting as above, iRAM is enabled as the first chosen memory by default.
os_malloc, os_zalloc and os_calloc will allocate from iRAM first, and dRAM
will be the next available memory when iRAM is used up.
- Or users can directly call os_malloc_iram, os_zalloc_iram, os_calloc_iram to
allocate from iRAM (dRAM will be the next available memory when iRAM is used
up); and os_malloc_dram, os_zalloc_dram, os_calloc_dram to allocate from
dRAM.
- Or to be compatible with earlier applications, users can define
MEM_DEFAULT_USE_DRAM to make os_malloc, os_zalloc and os_calloc allocate
from dRAM, and use os_malloc_iram, os_zalloc_iram, os_calloc_iram to
allocate from iRAM (dRAM will be the next available memory when iRAM is used
up). For example, add below codes in makefile:
CONFIGURATION_DEFINES += -DMEM_DEFAULT_USE_DRAM
Espressif ! /!164
5 2020.09
2. Non-OS SDK
!
#else
#endif
• RAM and flash access have to be word-aligned (4 byte boundary aligned access only).
Casting pointers directly is not recommended. Please use os_memcpy, or other APIs for
memory operations.
Espressif ! /!164
6 2020.09
3. Application Programming Interface (APIs)
!
3. Application Programming
Interface (APIs)
3.1. Software Timer
Timer APIs can be found in /ESP8266_NONOS_SDK/include/osapi.h.
Please note that os_timer APIs listed below are software timers executed in tasks, thus
timer callbacks may not be precisely executed at the right time; it depends on priority. If you
need a precise timer, please use a hardware timer which can be executed in hardware
interrupt. For details please refer to hw_timer.c.
• For the same timer, os_timer_arm (or os_timer_arm_us) cannot be invoked repeatedly.
os_timer_disarm should be invoked first.
• os_timer_setfn can only be invoked when the timer is not enabled, i.e., after
os_timer_disarm or before os_timer_arm (or os_timer_arm_us).
3.1.1. os_timer_arm
void os_timer_arm (
os_timer_t *ptimer,
Prototype uint32_t milliseconds,
bool repeat_flag
)
Return none
3.1.2. os_timer_disarm
Return none
Espressif ! /164
7 2020.09
3. Application Programming Interface (APIs)
!
3.1.3. os_timer_setfn
Set timer callback function. The timer callback function must be set before arming
Function
a timer.
void os_timer_setfn(
os_timer_t *ptimer,
Prototype os_timer_func_t *pfunction,
void *parg
)
Return none
3.1.4. system_timer_reinit
Function Reinitiate the timer when you need to use microsecond timer.
Parameter none
Return none
1. Define USE_US_TIMER;
Note
2. Put system_timer_reinit at the beginning of user_init, in the first sentence.
3.1.5. os_timer_arm_us
void os_timer_arm_us (
os_timer_t *ptimer,
Prototype uint32_t microseconds,
bool repeat_flag
)
Parameter uint32_t microseconds: timing; unit: microsecond, the minimum value is 0x64,
the maximum value allowed to input is 0xFFFFFFF.
bool repeat_flag: whether the timer will be invoked repeatedly or not.
Return none
Espressif ! /164
8 2020.09
3. Application Programming Interface (APIs)
!
📖 Notes:
• If NM is used as the ISR source for auto-loading the timer, parameter val of hw_timer_arm can not be
less than 100.
• When NMI source is used, the timer has the highest priority. It can interrupt other ISRs. FRC1 source
should be used to prevent the timer from interrupting other ISRs.
• APIs in hw_timer.c can not be called when PWM APIs are in use, because they all use the same
hardware timer.
• The hardware timer callback function must NOT be defined with ICACHE_FLASH_ATTR.
3.2.1. hw_timer_init
void hw_timer_init (
Prototype FRC1_TIMER_SOURCE_TYPE source_type,
u8 req
)
Parameter
NMI_SOURCE: timer uses NMI ISR as ISR source.
Return none
3.2.2. hw_timer_arm
• In autoload mode:
Return none
Espressif ! /164
9 2020.09
3. Application Programming Interface (APIs)
!
3.2.3. hw_timer_set_func
Return none
uint32 tick_now2 = 0;
void hw_test_timer_cb(void)
static uint16 j = 0;
j++;
tick_now2 = WDEV_NOW();
os_printf("b%u:%d\n",idx++,j);
j = 0;
hw_timer_init(FRC1_SOURCE,1);
hw_timer_set_func(hw_test_timer_cb);
hw_timer_arm(100);
Espressif ! /164
10 2020.09
3. Application Programming Interface (APIs)
!
3.3.1. system_get_sdk_version
Parameter none
3.3.2. system_restore
Parameter none
Return none
3.3.3. system_restart
Function Restart.
Parameter none
Return none
Note The ESP8266 will not restart immediately. Please do not call other functions after
calling this API.
3.3.4. system_init_done_cb
Return none
Espressif ! /164
11 2020.09
3. Application Programming Interface (APIs)
!
3.3.5. system_get_chip_id
Parameter none
3.3.6. system_get_vdd33
Function Measure the power voltage of VDD3P3 pin 3 and 4; unit: 1/1024 V.
Parameter none
3.3.7. system_adc_read
Parameter none
Espressif ! /164
12 2020.09
3. Application Programming Interface (APIs)
!
3.3.8. system_adc_read_fast
Parameter uint16 adc_num: sampling number of ADC continuously fast sampling; range [1,
65535].
uint8 adc_clk_div: ADC working clock = 80M/adc_clk_div; range [8, 32], the
recommended value is 8.
Return none
Espressif ! /164
13 2020.09
3. Application Programming Interface (APIs)
!
os_timer_t timer;
wifi_set_opmode(NULL_MODE);
uint16 adc_addr[10];
uint8 adc_clk_div = 8;
Example
uint32 i;
os_timer_disarm(&timer);
os_timer_arm(&timer,1000,1);
- If the [107] byte = 0XFF, VDD33 is measured internally, TOUT pin cannot
work as ADC input.
- When the valid value range of the [107] byte vdd33_const is [18, 36], the
unit is 0.1V, and the value should be set as the real power voltage of
VDD33 to optimize the RF working condition. TOUT pin can work as ADC
input.
- When the [107] byte vdd33_const is in the range of (0, 18) or (36, 255), the
default 3.3V will be used as the power voltage to optimize the RF working
condition. TOUT pin can work as ADC input.
3.3.9. system_deep_sleep
Espressif ! /164
14 2020.09
3. Application Programming Interface (APIs)
!
uint64 time_in_us: the duration of time (μs) when the device is in Deep-sleep.
The theoretical maximum value of time_in_us can be calculated by formula:
(time_in_us / cali) << 12 = 2^31 - 1
Parameter • cali = system_rtc_clock_cali_proc(), the cali is the RTC clock period (in
us); bit11 ~ bit0 are decimal. For more details about the cali, please see the
API: system_rtc_clock_cali_proc.
• The input value of time_in_us should be less than the theoretical maximum
value.
true: Success
Return
false: Failure
3.3.10. system_deep_sleep_set_option
Call this API before system_deep_sleep to set whether the chip will do RF
Function calibration or not when it wakes up from deep-sleep again. The option is 1 by
default.
uint8 option:
0: RF calibration after deep-sleep wakeup depends on both the times of entering
Deep-sleep (deep_sleep_number, returns 0 upon each power-up) and byte 108 of
esp_init_data_default.bin (0 ~ 127 bytes).
• If deep_sleep_number <= byte 108, no RF calibration after Deep-sleep wakeup;
this reduces the current consumption.
Parameter • If deep_sleep_number = byte 108 +1, the behavior after Deep-sleep wakeup
will be the same as power-up, and deep_sleep_number returns to 0.
- The behavior after Deep-sleep wakeup will be the same as power-up.
- No RF calibration after Deep-sleep wakeup; this reduces the current
consumption.
- Disable RF after Deep-sleep wakeup, just like Modem-sleep; this has
the least current consumption; the device is not able to transmit or
receive data after wakeup.
true: Success
Return
false: Failure
Espressif ! /164
15 2020.09
3. Application Programming Interface (APIs)
!
3.3.11. system_phy_set_rfoption
uint8 option:
• 0: RF calibration after deep-sleep wakeup depends on both the times of
entering Deep-sleep (deep_sleep_number, returns 0 upon each power-up) and
byte 108 of esp_init_data_default.bin (0 ~ 127 bytes).
- If deep_sleep_number <= byte 108, no RF calibration after wakeup from
Deep-sleep; this reduces the current consumption.
- If deep_sleep_number = byte 108 +1, the behavior after Deep-sleep
Parameter wakeup will be the same as power-up, and deep_sleep_number
becomes 0.
• The behavior after Deep-sleep wakeup will be the same as power-up.
Return none
3.3.12. system_phy_set_powerup_option
Set whether the chip will do RF calibration or not when power up. The option is 0
Function
by default.
Return none
Espressif ! /164
16 2020.09
3. Application Programming Interface (APIs)
!
3.3.13. system_phy_set_max_tpw
uint8 max_tpw: maximum value of RF Tx Power, unit: 0.25 dBm, range [0, 82].
Parameter It can be set by referring to the 34th byte (target_power_qdb_0) of
esp_init_data_default.bin (0 ~ 127 bytes).
Return none
3.3.14. system_phy_set_tpw_via_vdd33
Return none
3.3.15. system_set_os_print
Return none
3.3.16. system_print_meminfo
Parameter none
Return none
Espressif ! /164
17 2020.09
3. Application Programming Interface (APIs)
!
3.3.17. system_get_free_heap_size
Parameter none
3.3.18. system_os_task
bool system_os_task(
os_task_t task,
uint8 prio,
Prototype
os_event_t *queue,
uint8 qlen
)
Parameters Three priorities are supported: 0/1/2; 0 is the lowest priority. This means only 3
tasks are allowed to be set up.
os_event_t *queue: message queue pointer.
uint8 qlen: message queue depth.
true:Success
Return
false:Failure
#define SIG_RX 0
#define TEST_QUEUE_LEN 4
os_event_t *testQueue;
void test_task (os_event_t *e) {
switch (e->sig) {
case SIG_RX:
os_printf(sig_rx %c/n, (char)e->par);
break;
Example default:
break;
}
}
void task_init(void) {
testQueue=(os_event_t
*)os_malloc(sizeof(os_event_t)*TEST_QUEUE_LEN);
system_os_task(test_task,USER_TASK_PRIO_0,testQueue,TEST_QUEUE_LEN);
}
Espressif ! /164
18 2020.09
3. Application Programming Interface (APIs)
!
3.3.19. system_os_post
bool system_os_post (
uint8 prio,
Prototype os_signal_t sig,
os_param_t par
)
true:Success
Return
false:Failure
void task_post(void) {
Example system_os_post(USER_TASK_PRIO_0, SIG_RX, ‘a’);
}
Print sig_rx a
3.3.20. system_get_time
Parameter none
3.3.21. system_get_rtc_time
Function Get RTC time, as denoted by the number of RTC clock periods.
Parameter none
Espressif ! /164
19 2020.09
3. Application Programming Interface (APIs)
!
System time will return to zero because of system_restart, but RTC still goes on.
If an external hardware reset the chip via EXT_RST or CHIP_EN (such as timed
wakeup from Deep-sleep), the RTC timer will be reset.
• Reset by pin EXT_RST: RTC memory won’t change; RTC timer starts to zero.
Note • Watchdog reset: RTC memory won’t change; RTC timer won’t change.
• Power-on: RTC memory contains a random value; RTC timer starts from zero.
• Reset by pin CHIP_EN: RTC memory contains a random value; RTC timer
starts from zero.
3.3.22. system_rtc_clock_cali_proc
Parameter none
Return RTC clock period (in us); bit11 ~ bit0 are decimal.
Note • RTC clock period tends to drift with changes in temperature, so RTC timer is
not very precise.
• See RTC demo in Appendix.A.
3.3.23. system_rtc_mem_write
During Deep-sleep mode, the RTC is still operational and can store user data in the defined
Function
user-data area.
bool system_rtc_mem_write (
uint32 des_addr,
Prototype void * src_addr,
uint32 save_size
)
uint32 des_addr: destination address (block number) in RTC memory, des_addr >=64
true: Success
Return
false: Failure
Espressif ! /164
20 2020.09
3. Application Programming Interface (APIs)
!
Data read/write accesses to the RTC memory must be word-aligned (4-byte boundary
Note aligned). Parameter des_addr means block number (4 bytes per block). For example, to
save data at the beginning of user data area, des_addr will be 256/4 = 64, and save_size
will be data length.
3.3.24. system_rtc_mem_read
Read user data from RTC memory. Only user data area should be accessed by the user.
Function
|<------system data (256 bytes)------->|<-----------------user data (512 bytes)--------------->|
bool system_rtc_mem_read (
uint32 src_addr,
Prototype void * des_addr,
uint32 save_size
)
uint32 src_addr: source address (block number) in RTC memory, src_addr >= 64
Parameter void * des_addr: data pointer
uint32 save_size: data length; unit: byte
true: Success
Return
false: Failure
Data read/write accesses to the RTC memory must be word aligned (4 bytes boundary
Note aligned). Parameter src_addr means block number(4 bytes per block). For example, to
read data from the beginning of user data area, src_addr will be 256/4=64, save_size will
be data length.
3.3.25. system_uart_swap
UART0 swap. Use MTCK as UART0 Rx, MTDO as UART0 Tx, so ROM log will not
Function output from this new UART0. MTDO (U0RTS) and MTCK (U0CTS) also need to be
used as UART0 in hardware.
Parameter none
Return none
3.3.26. system_uart_de_swap
Function Disable UART0 swap. Use original UART0, not MTCK and MTDO.
Parameter none
Return none
Espressif ! /164
21 2020.09
3. Application Programming Interface (APIs)
!
3.3.27. system_get_boot_version
Parameter none
Note If boot version >= 3, it is possible to enable enhanced boot mode (for details of
which please see system_restart_enhance).
3.3.28. system_get_userbin_addr
Function Get address of the current running user bin (user1.bin or user2.bin).
Parameter none
3.3.29. system_get_boot_mode
Parameter none
3.3.30. system_restart_enhance
bool system_restart_enhance(
uint8 bin_type,
Prototype
uint32 bin_addr
)
Parameter
#define SYS_BOOT_TEST_BIN 1 // can only be Espressif test bin
Espressif ! /164
22 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
Note SYS_BOOT_TEST_BIN is for factory test during production; you can apply for the test
bin from Espressif Systems.
3.3.31. system_update_cpu_freq
true: Success
Return
false: Failure
System bus frequency is 80 MHz, and it is not affected by CPU frequency. The
Note frequency of UART, SPI, or other peripheral devices, are divided from system bus
frequency, so they will not be affected by CPU frequency either.
3.3.32. system_get_cpu_freq
Parameter none
3.3.33. system_get_flash_size_map
Espressif ! /164
23 2020.09
3. Application Programming Interface (APIs)
!
enum flash_size_map {
FLASH_SIZE_4M_MAP_256_256 = 0,
FLASH_SIZE_2M,
FLASH_SIZE_8M_MAP_512_512,
FLASH_SIZE_16M_MAP_512_512,
Structure FLASH_SIZE_32M_MAP_512_512,
FLASH_SIZE_16M_MAP_1024_1024,
FLASH_SIZE_32M_MAP_1024_1024,
FLASH_SIZE_64M_MAP_1024_1024,
FLASH_SIZE_128M_MAP_1024_1024,
};
Parameter none
3.3.34. system_get_rst_info
enum rst_reason {
REANSON_EXCEPTION_RST = 2,
REANSON_SOFT_WDT_RST = 3,
REANSON_SOFT_RESTART = 4,
Structure
};
struct rst_info {
uint32 exccause;
uint32 epc2;
uint32 epc3;
uint32 excvaddr;
uint32 depc;
};
Espressif ! /164
24 2020.09
3. Application Programming Interface (APIs)
!
Parameter none
3.3.35. system_soft_wdt_stop
Parameter none
Return none
Note The software watchdog must not be stopped for too long (over 6 seconds),
otherwise it will trigger hardware watchdog reset.
Espressif ! /164
25 2020.09
3. Application Programming Interface (APIs)
!
3.3.36. system_soft_wdt_restart
Parameter none
Return none
3.3.37. system_soft_wdt_feed
Parameter none
Return none
3.3.38. system_show_malloc
Function For debugging memory leak issue and printing the memory usage.
Parameter none
Return none
Espressif ! /164
26 2020.09
3. Application Programming Interface (APIs)
!
3.3.39. os_memset
Return none
uint8 buffer[32];
Example
os_memset(buffer, 0, sizeof(buffer));
3.3.40. os_memcpy
Note
os_memcpy(buffer, "abcd", 4);
3.3.41. os_strlen
Example
os_memcpy(softAP_config.ssid, ssid, os_strlen(ssid));
3.3.42. os_printf
Espressif ! /164
27 2020.09
3. Application Programming Interface (APIs)
!
• Default to be output from UART 0. uart_init in IOT_Demo can set baud rate
of UART, and os_install_putc1((void *)uart1_write_char) in it will set
Note os_printf to be output from UART 1.
• Continuously printing more than 125 bytes or repeated calls to this API may
cause loss of print data.
3.3.43. os_bzero
Return none
3.3.44. os_delay_us
Return none
3.3.45. os_install_putc1
3.3.46. os_random
Espressif ! /164
28 2020.09
3. Application Programming Interface (APIs)
!
3.3.47. os_get_random
Parameter
size_t len: specified bytes of the random number
0: Success
Return
otherwise: Failure
3.3.48. user_rf_cal_sector_set
Espressif ! /164
29 2020.09
3. Application Programming Interface (APIs)
!
Set the 5th sector from the end of the flash to store the RF_CAL parameter.
uint32 user_rf_cal_sector_set(void)
uint32 rf_cal_sec = 0;
switch (size_map) {
case FLASH_SIZE_4M_MAP_256_256:
rf_cal_sec = 128 - 5;
break;
case FLASH_SIZE_8M_MAP_512_512:
rf_cal_sec = 256 - 5;
break;
case FLASH_SIZE_16M_MAP_512_512:
case FLASH_SIZE_16M_MAP_1024_1024:
rf_cal_sec = 512 - 5;
Example break;
case FLASH_SIZE_32M_MAP_512_512:
case FLASH_SIZE_32M_MAP_1024_1024:
rf_cal_sec = 512 - 5;
break;
case FLASH_SIZE_64M_MAP_1024_1024:
rf_cal_sec = 2048 - 5;
break;
case FLASH_SIZE_128M_MAP_1024_1024:
rf_cal_sec = 4096 - 5;
break;
default:
rf_cal_sec = 0;
break;
return rf_cal_sec;
3.3.49. system_deep_sleep_instant
uint64 time_in_us: the duration of time (μs) when the device is in Deep-sleep.
The theoretical maximum value of time_in_us can be calculated by formula:
(time_in_us / cali) << 12 = 2^32 - 1
Parameter • cali = system_rtc_clock_cali_proc(), the cali is the RTC clock period (in
us); bit11 ~ bit0 are decimal. For more details about the cali, please see the
API: system_rtc_clock_cali_proc.
• The input value of time_in_us should be less than the theoretical maximum
value.
true: Success
Return
false: Failure
Espressif ! /164
30 2020.09
3. Application Programming Interface (APIs)
!
3.3.50. system_partition_table_regist
bool system_partition_table_regist(
uint32_t map
Parameter uint32_t map: flash map. The value of this parameter should be the same as the
flash map selected during the compilation and downloading. Otherwise, it may
cause abnormal startup. It’s recommended that Marco SPI_FLASH_SIZE_MAP,
which stores the value of flash map during the compilation, is passed to this
parameter.
true: Success
Return
false: Failure
• This API must be called in the user_pre_init to register partition table. If the
API returns false, please check your definition of the partition table.
Note
• Please refer to ESP8266_NONOS_SDK/examples/IoT_Demo/user/
user_main.c.
3.3.51. system_partition_get_ota_partition_size
Parameter -
Note OTA partition is the flash partition where user1.bin or user2.bin is stored.
Espressif ! /164
31 2020.09
3. Application Programming Interface (APIs)
!
3.3.52. system_partition_get_item
true: Success
Return
false: Failure
3.4.1. spi_flash_get_id
Parameter none
3.4.2. spi_flash_erase_sector
Parameter uint16 sec: Sector number, the count starts at sector 0, 4 KB per sector.
typedef enum{
SPI_FLASH_RESULT_OK,
Return SPI_FLASH_RESULT_ERR,
SPI_FLASH_RESULT_TIMEOUT
} SpiFlashOpResult;
3.4.3. spi_flash_write
Function Write data to flash. Flash read/write has to be aligned to the 4-byte boundary.
Espressif ! /164
32 2020.09
3. Application Programming Interface (APIs)
!
SpiFlashOpResult spi_flash_write (
uint32 des_addr,
Prototype uint32 *src_addr,
uint32 size
)
typedef enum{
SPI_FLASH_RESULT_OK,
Return SPI_FLASH_RESULT_ERR,
SPI_FLASH_RESULT_TIMEOUT
} SpiFlashOpResult;
3.4.4. spi_flash_read
Function Read data to flash. Flash read/write has to be aligned to the 4-byte boundary.
SpiFlashOpResult spi_flash_read(
uint32 src_addr,
Prototype uint32 * des_addr,
uint32 size
)
typedef enum {
SPI_FLASH_RESULT_OK,
Return SPI_FLASH_RESULT_ERR,
SPI_FLASH_RESULT_TIMEOUT
} SpiFlashOpResult;
uint32 value;
3.4.5. system_param_save_with_protect
Write data into flash with protection. Flash read/write has to be aligned to the 4-
byte boundary.
Function Protection of flash read/write : 3 sectors (4 KB per sector) are used to save 4 KB
data with protection; sector 0 and sector 1 are data sectors and back up each
other; data is saved alternately; sector 2 is flag sector that points out which sector
is keeping the latest data—sector 0 or sector 1.
Espressif ! /164
33 2020.09
3. Application Programming Interface (APIs)
!
bool system_param_save_with_protect (
uint16 start_sec,
Prototype void *param,
uint16 len
)
uint16 start_sec: start sector (sector 0) of the 3 sectors which used for flash
read/write protection.
For example, in IOT_Demo we could use the 3 sectors (3*4 KB) starts from flash
Parameter 0x3D000 for flash read/write protection, so the parameter start_sec should be
0x3D.
void *param: pointer of data need to save.
uint16 len: data length, should less than a sector which is 4*1024.
true: Success
Return
false: Failure
uint32 value;
Example
spi_flash_read(0x3E * SPI_FLASH_SEC_SIZE, (uint32 *)addr, 4);
3.4.6. system_param_load
Read protected data from flash. Flash read/write has to be aligned to the 4-byte
boundary.
Function Protection of flash read/write : 3 sectors (4 KB per sector) are used to save 4 KB
data with protection; sector 0 and sector 1 are data sectors and back up each
other; data is saved alternately; sector 2 is flag sector that points out which sector
is keeping the latest data—sector 0 or sector 1.
bool system_param_load (
uint16 start_sec,
void *param,
uint16 len
)
uint16 start_sec: start sector (sector 0) of the 3 sectors which used for flash
read/write protection. It cannot be sectors 1 or 2.
For example, in IOT_Demo we could use the 3 sectors (3*4 KB) starts from flash
0x3D000 for flash read/write protection, so the parameter start_sec should be
Parameter 0x3D.
uint16 offset: offset of data saved in sector.
void *param: pointer of data need to save.
uint16 len: data length, should less than a sector which is 4*1024.
true: Success
Return
false: Failure
Espressif ! /164
34 2020.09
3. Application Programming Interface (APIs)
!
uint32 value;
Example
spi_flash_read(0x3E * SPI_FLASH_SEC_SIZE, (uint32 *)addr, 4);
3.4.7. spi_flash_set_read_func
Return none
SpiFlashChip *spi,
Parameter Definition uint32 src_addr,
uint32 * des_addr,
uint32 size
)
Note This API can be only used in SPI overlap mode, for details please see
ESP8266_NONOS_SDK\driver_lib\driver\spi_overlap.c.
3.4.8. spi_flash_erase_protect_enable
Note It can prevent users from erasing the running firmware mistakenly. And users still
can erase / write the parameter area on the flash.
Parameter none
true: Success
Return
false: Failure
3.4.9. spi_flash_erase_protect_disable
Parameter none
true: Success
Return
false: Failure
Espressif ! /164
35 2020.09
3. Application Programming Interface (APIs)
!
3.5.1. wifi_get_opmode
Parameter none
Note This API can be only used in SPI overlap mode, for details please see
ESP8266_NONOS_SDK\driver_lib\driver\spi_overlap.c.
3.5.2. wifi_get_opmode_default
Parameter none
Note This API can be only used in SPI overlap mode, for details please see
ESP8266_NONOS_SDK\driver_lib\driver\spi_overlap.c.
Espressif ! /164
36 2020.09
3. Application Programming Interface (APIs)
!
3.5.3. wifi_set_opmode
Set Wi-Fi working mode to Station mode, SoftAP or Station + SoftAP, and save it
Function
in flash. The default mode is SoftAP mode.
true: Success
Return
false: Failure
3.5.4. wifi_set_opmode_current
Set Wi-Fi working mode to Station mode, SoftAP or Station + SoftAP, and do not
Function
update flash.
true: Success
Return
false: Failure
3.5.5. wifi_station_get_config
true: Success
Return
false: Failure
Espressif ! /164
37 2020.09
3. Application Programming Interface (APIs)
!
3.5.6. wifi_station_get_config_default
true: Success
Return
false: Failure
3.5.7. wifi_station_set_config
true: Success
Return
false: Failure
void ICACHE_FLASH_ATTR
user_set_station_config(void)
Example
wifi_station_set_config(&stationConf);
void user_init(void)
user_set_station_config();
Espressif ! /164
38 2020.09
3. Application Programming Interface (APIs)
!
3.5.8. wifi_station_set_config_current
true: Success
Return
false: Failure
void ICACHE_FLASH_ATTR
user_set_station_config(void)
Example
wifi_station_set_config(&stationConf);
void user_init(void)
user_set_station_config();
3.5.9. wifi_station_set_cert_key
bool wifi_station_set_cert_key (
uint8 *client_cert, int client_cert_len,
Prototype
uint8 *private_key, int private_key_len,
uint8 *private_key_passwd, int private_key_passwd_len,)
Espressif ! /164
39 2020.09
3. Application Programming Interface (APIs)
!
Parameter int private_key_len: length of private key; less than 2048 bits.
uint8 *private_key_passwd: password for private key; to be supported; can
only be NULL now.
int private_key_passwd_len: length of password; to be supported; can only be
0 now.
0: Success
Return
otherwise: Failure
Example Then the array should be uint8 key[]={0x2d, 0x2d, 0x2d, 0x2d, 0x2d, 0x42, 0x45,
0x47, … … 0x00 };
It is the ASCII of the characters, and the array needs to terminate with 0x00.
3.5.10. wifi_station_clear_cert_key
Parameter none
Return none
Espressif ! /164
40 2020.09
3. Application Programming Interface (APIs)
!
3.5.11. wifi_station_set_username
0 : Success
Return
otherwise: Failure
3.5.12. wifi_station_clear_username
Parameter none
Return none
3.5.13. wifi_station_connect
Parameter none
true: Success
Return
false: Failure
3.5.14. wifi_station_disconnect
Parameter none
Espressif ! /164
41 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
Note Do not call this API in user_init. This API need to be called after system initializes
and the ESP8266 Station mode is enabled.
3.5.15. wifi_station_get_connect_status
Parameter none
enum{
STATION_IDLE = 0,
STATION_CONNECTING,
Return STATION_WRONG_PASSWORD,
STATION_NO_AP_FOUND,
STATION_CONNECT_FAIL,
STATION_GOT_IP
};
3.5.16. wifi_station_scan
struct scan_config {
uint8 *ssid; // AP’s ssid
uint8 *bssid; // AP’s bssid
Structure uint8 channel; //scan a specific channel
uint8 show_hidden; //scan APs of which ssid is hidden.
wifi_scan_type_t scan_type; // scan type, active or passive
wifi_scan_time_t scan_time; // scan time per channel
};
Espressif ! /164
42 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
Note Do not call this API in user_init. This API need to be called after system initializes
and the ESP8266 Station mode is enabled.
3.5.17. scan_done_cb_t
void *arg: information of APs that were found, refer to struct bss_info.
Parameter
STATUS status: get status.
Return none
wifi_station_scan(&config, scan_done);
static void ICACHE_FLASH_ATTR scan_done(void *arg, STATUS status) {
if (status == OK) {
Example struct bss_info *bss_link = (struct bss_info *)arg;
...
}
}
3.5.18. wifi_station_ap_number_set
Sets the number of APs that will be cached for ESP8266 Station mode. Whenever
Function ESP8266 Station connects to an AP, it caches a record of this AP’s SSID and
password. The cached ID index starts from 0.
Parameter uint8 ap_number: the number of APs that can be recorded (MAX: 5)
true: Success
Return
false: Failure
wifi_station_scan(&config, scan_done);
static void ICACHE_FLASH_ATTR scan_done(void *arg, STATUS status) {
if (status == OK) {
Example struct bss_info *bss_link = (struct bss_info *)arg;
...
}
}
Note This configuration will be saved in flash system parameter area if changed.
3.5.19. wifi_station_get_ap_info
Espressif ! /164
43 2020.09
3. Application Programming Interface (APIs)
!
3.5.20. wifi_station_ap_change
true: Success
Return
false: Failure
3.5.21. wifi_station_get_current_ap_id
Get the current cached ID of AP. ESP8266 records the ID of each AP it connects
Function
with. The ID number starts from 0.
Parameter none
Return The ID of the AP to which ESP8266 is currently connected, in the cached AP list.
3.5.22. wifi_station_get_auto_connect
Parameter none
3.5.23. wifi_station_set_auto_connect
• 1: to connect automatically
true: Success
Return
false: Failure
Espressif ! /164
44 2020.09
3. Application Programming Interface (APIs)
!
3.5.24. wifi_station_dhcpc_start
Parameter none
true: Success
Return
false: Failure
3.5.25. wifi_station_dhcpc_stop
Parameter none
true: Success
Return
false: Failure
3.5.26. wifi_station_dhcpc_status
Parameter none
enum dhcp_status {
Return DHCP_STOPPED,
DHCP_STARTED
};
3.5.27. wifi_station_dhcpc_set_maxtry
Set the maximum number that ESP8266 Station DHCP client will try to reconnect
Function
to the AP.
Espressif ! /164
45 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
3.5.28. wifi_station_set_reconnect_policy
true: Success
Return
false: Failure
3.5.29. wifi_station_get_rssi
Parameter none
3.5.30. wifi_station_set_hostname
true: Success
Return
false: Failure
Espressif ! /164
46 2020.09
3. Application Programming Interface (APIs)
!
3.5.31. wifi_station_get_hostname
Parameter none
Return hostname
3.5.32. wifi_softap_get_config
true: Success
Return
false: Failure
3.5.33. wifi_softap_get_config_default
true: Success
Return
false: Failure
3.5.34. wifi_softap_set_config
true: Success
Return
false: Failure
Espressif ! /164
47 2020.09
3. Application Programming Interface (APIs)
!
3.5.35. wifi_softap_set_config_current
Function Set Wi-Fi SoftAP configuration; settings are not updated in flash memory.
true: Success
Return
false: Failure
Note • In SoftAP + Station mode, the ESP8266 SoftAP will adjust its channel
configuration to be the as same as that of the ESP8266 Station. For more
details please see Appendix A.
3.5.36. wifi_softap_get_station_num
Parameter none
3.5.37. wifi_softap_get_station_info
Get information on connected Station devices under SoftAP mode, including MAC
Function
and IP.
Parameter none
Note This API depends on DHCP, so it cannot get static IP, etc. in case DHCP is not
used.
3.5.38. wifi_softap_free_station_info
Parameter none
Return none
Espressif ! /164
48 2020.09
3. Application Programming Interface (APIs)
!
3.5.39. wifi_softap_dhcps_start
Parameter none
true: Success
Return
false: Failure
3.5.40. wifi_softap_dhcps_stop
Parameter none
true: Success
Return
false: Failure
Espressif ! /164
49 2020.09
3. Application Programming Interface (APIs)
!
3.5.41. wifi_softap_set_dhcps_lease
Function Set the IP range that can be allocated by the ESP8266 SoftAP DHCP server.
struct dhcps_lease {
Parameter struct ip_addr start_ip;
struct ip_addr end_ip;
};
true: Success
Return
false: Failure
void dhcps_lease_test(void)
dhcp_lease.start_ip.addr = ipaddr_addr(start_ip);
dhcp_lease.end_ip.addr = ipaddr_addr(end_ip);
wifi_softap_set_dhcps_lease(&dhcp_lease);
or
void dhcps_lease_test(void)
Example
IP4_ADDR(&dhcp_lease.end_ip, 192, 168, 5, 105);
wifi_softap_set_dhcps_lease(&dhcp_lease);
void user_init(void)
wifi_softap_dhcps_stop();
IP4_ADDR(&info.ip, 192, 168, 5, 1);
IP4_ADDR(&info.gw, 192, 168, 5, 1);
IP4_ADDR(&info.netmask, 255, 255, 255, 0);
wifi_set_ip_info(SOFTAP_IF, &info);
dhcps_lease_test();
wifi_softap_dhcps_start();
• IP range has to be in the same sub-net with the ESP8266 SoftAP IP address.
Espressif ! /164
50 2020.09
3. Application Programming Interface (APIs)
!
3.5.42. wifi_softap_get_dhcps_lease
Function Query the IP range that can be allocated by the ESP8266 SoftAP DHCP server.
true: Success
Return
false: Failure
Note This API can only be called when ESP8266 SoftAP DHCP server is enabled.
3.5.43. wifi_softap_set_dhcps_lease_time
Function Set ESP8266 SoftAP DHCP server lease time, 120 minutes by default.
Parameter uint32 minute: lease time, uint: minute, range: [1, 2880].
true: Success
Return
false: Failure
Note This API can only be called when ESP8266 SoftAP DHCP server is enabled.
3.5.44. wifi_softap_get_dhcps_lease_time
Note This API can only be called when ESP8266 SoftAP DHCP server is enabled.
3.5.45. wifi_softap_reset_dhcps_lease_time
Reset ESP8266 SoftAP DHCP server lease time to its default value, which is 120
Function
minutes.
true: Success
Return
false: Failure
Note This API can only be called when ESP8266 SoftAP DHCP server is enabled.
Espressif ! /164
51 2020.09
3. Application Programming Interface (APIs)
!
3.5.46. wifi_softap_dhcps_status
Parameter none
enum dhcp_status {
Return DHCP_STOPPED,
DHCP_STARTED
};
Note This API can only be called when ESP8266 SoftAP DHCP server is enabled.
3.5.47. wifi_softap_set_dhcps_offer_option
enum dhcps_offer_option{
OFFER_START = 0x00,
OFFER_END
};
true: Success
Return
false: Failure
uint8 mode = 0;
Example
wifi_softap_set_dhcps_offer_option(OFFER_ROUTER, &mode);
3.5.48. wifi_set_phy_mode
Espressif ! /164
52 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
3.5.49. wifi_get_phy_mode
Parameter none
enum phy_mode{
PHY_MODE_11B = 1,
Return PHY_MODE_11G = 2,
PHY_MODE_11N = 3
};
3.5.50. wifi_get_ip_info
bool wifi_get_ip_info(
Prototype uint8 if_index,
struct ip_info *info
)
uint8 if_index: the interface to get IP info: 0x00 for STATION_IF; 0x01 for
Parameter SOFTAP_IF.
true: Success
Return
false: Failure
3.5.51. wifi_set_ip_info
bool wifi_set_ip_info(
Prototype uint8 if_index,
struct ip_info *info
)
Espressif ! /164
53 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
wifi_station_dhcpc_stop();
wifi_softap_dhcps_stop();
IP4_ADDR(&info.ip, 192, 168, 3, 200);
Example IP4_ADDR(&info.gw, 192, 168, 3, 1);
IP4_ADDR(&info.netmask, 255, 255, 255, 0);
wifi_set_ip_info(STATION_IF, &info);
IP4_ADDR(&info.ip, 10, 10, 10, 1);
IP4_ADDR(&info.gw, 10, 10, 10, 1);
IP4_ADDR(&info.netmask, 255, 255, 255, 0);
wifi_set_ip_info(SOFTAP_IF, &info);
wifi_softap_dhcps_start();
3.5.52. wifi_set_macaddr
bool wifi_set_macaddr(
Prototype uint8 if_index,
uint8 *macaddr
)
true: Success
Return
false: Failure
wifi_set_opmode(STATIONAP_MODE);
Espressif ! /164
54 2020.09
3. Application Programming Interface (APIs)
!
• ESP8266 SoftAP and station have different MAC addresses, please do not set
Note them to be the same.
• The bit 0 of the first byte of ESP8266 MAC address can not be 1. For example,
MAC address can be “1a:XX:XX:XX:XX:XX”, but can not be
“15:XX:XX:XX:XX:XX”.
3.5.53. wifi_get_macaddr
bool wifi_get_macaddr(
Prototype uint8 if_index,
uint8 *macaddr
)
true: Success
Return
false: Failure
3.5.54. wifi_set_sleep_type
Function Sets sleep type for power saving. Set NONE_SLEEP_T to disable power saving.
true: Success
Return
false: Failure
• In order to lower the power comsumption, ESP8266 changes the TCP timer
Note tick from 250ms to 3s in light-sleep mode, which leads to increased timeout for
TCP timer. Therefore, the modem-sleep or deep-sleep mode should be used
where there is a requirement for the accurancy of the TCP timer.
Espressif ! /164
55 2020.09
3. Application Programming Interface (APIs)
!
3.5.55. wifi_get_sleep_type
Parameter none
enum sleep_type {
NONE_SLEEP_T = 0;
Return LIGHT_SLEEP_T,
MODEM_SLEEP_T
};
3.5.56. wifi_status_led_install
void wifi_status_led_install (
uint8 gpio_id,
Prototype uint32 gpio_name,
uint8 gpio_func
)
Return none
3.5.57. wifi_status_led_uninstall
Parameter none
Return none
Espressif ! /164
56 2020.09
3. Application Programming Interface (APIs)
!
3.5.58. wifi_set_broadcast_if
Set ESP8266 to send UDP broadcast from Station interface or SoftAP interface,
Function
or both Station and SoftAP interfaces. The default interface is SoftAP.
uint8 interface:
• 1: Station
Parameter
• 2: SoftAP
• 3: Station + SoftAP
true: Success
Return
false: Failure
Note If broadcast is set to be in station interface only, the SoftAP DHCP server will be
disabled.
3.5.59. wifi_get_broadcast_if
Get interface which ESP8266 sends UDP broadcast from. This is usually used
Function
when you have Station + SoftAP mode to avoid ambiguity.
Parameter none
1: Station
Return 2: SoftAP
3: Both Station and SoftAP
Espressif ! /164
57 2020.09
3. Application Programming Interface (APIs)
!
3.5.60. wifi_set_event_handler_cb
Return none
void wifi_handle_event_cb(System_Event_t *evt)
switch (evt->event) {
case EVENT_STAMODE_CONNECTED:
evt->event_info.connected.ssid,
evt->event_info.connected.channel);
break;
case EVENT_STAMODE_DISCONNECTED:
evt->event_info.disconnected.ssid,
evt->event_info.disconnected.reason);
break;
case EVENT_STAMODE_AUTHMODE_CHANGE:
evt->event_info.auth_change.old_mode,
evt->event_info.auth_change.new_mode);
break;
case EVENT_STAMODE_GOT_IP:
IP2STR(&evt->event_info.got_ip.ip),
IP2STR(&evt->event_info.got_ip.mask),
Example IP2STR(&evt->event_info.got_ip.gw));
os_printf("\n");
break;
case EVENT_SOFTAPMODE_STACONNECTED:
MAC2STR(evt->event_info.sta_connected.mac),
evt->event_info.sta_connected.aid);
break;
case EVENT_SOFTAPMODE_STADISCONNECTED:
MAC2STR(evt->event_info.sta_disconnected.mac),
evt->event_info.sta_disconnected.aid);
break;
default:
break;
void user_init(void)
wifi_set_event_hander_cb(wifi_handle_event_cb);
Espressif ! /164
58 2020.09
3. Application Programming Interface (APIs)
!
3.5.61. wifi_wps_enable
WPS_TYPE_DISABLE=0,
WPS_TYPE_PBC,
Structure WPS_TYPE_PIN,
WPS_TYPE_DISPLAY,
WPS_TYPE_MAX,
}WPS_TYPE_t;
true: Success
Return
false: Failure
3.5.62. wifi_wps_disable
Function Disable Wi-Fi WPS function and release resources allocated to it.
Parameter none
true: Success
Return
false: Failure
3.5.63. wifi_wps_start
Parameter none
true: WPS starts. But it does not mean Wi-Fi protection setup is successfully
Return completed.
false: Failure
Espressif ! /164
59 2020.09
3. Application Programming Interface (APIs)
!
3.5.64. wifi_set_wps_cb
Function Set WPS callback; parameter of the callback is the status of WPS.
enum wps_cb_status {
WPS_CB_ST_SUCCESS = 0,
Parameter Struture
WPS_CB_ST_TIMEOUT,
true: Success
Return
false: Failure
Espressif ! /164
60 2020.09
3. Application Programming Interface (APIs)
!
3.5.65. wifi_register_send_pkt_freedom_cb
The send callback can determine the status of a transmitted packet, however,
note that:
Solution: the sender application should re-transmit the packet, and the
receiver should detect the retransmitted packet.
0: Success
Return
-1: Failure
Note Only after the previous packet was sent, entered the freedom_outside_cb_t, the
next packet is allowed to be sent.
3.5.66. wifi_unregister_send_pkt_freedom_cb
Parameter none
Return none
Espressif ! /164
61 2020.09
3. Application Programming Interface (APIs)
!
3.5.67. wifi_send_pkt_freedom
0: Success
Return
-1: Failure
• Packet has to be the whole 802.11 packet, excluding the FCS. The length of
the packet has to be longer than the minimum length of the header of 802.11
packet, which is 24 bytes, and less than 1400 bytes.
• Duration area is invalid for user, it will be filled in SDK.
• The rate of sending packet is same as the management packet which is the
same as the system rate of sending packets.
3.5.68. wifi_rfid_locp_recv_open
Function Enable RFID LOCP (Location Control Protocol) to receive WDS packets.
Parameter none
0: Success
Return
otherwise: Failure
3.5.69. wifi_rfid_locp_recv_close
Parameter none
Return none
Espressif ! /164
62 2020.09
3. Application Programming Interface (APIs)
!
3.5.70. wifi_register_rfid_locp_recv_cb
Register a callback on receiving WDS packets, only if the first MAC address of the
Function
WDS packet is a multicast address.
Callback Definition typedef void (*rfid_locp_cb_t)(uint8 *frm, int len, int rssi);
0: Success
Return
otherwise: Failure
3.5.71. wifi_unregister_rfid_locp_recv_cb
Parameter none
Return none
3.5.72. wifi_enable_gpio_wakeup
Return none
Example
PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12);
wifi_enable_gpio_wakeup(12, GPIO_PIN_INTR_LOLEVEL);
Espressif ! /164
63 2020.09
3. Application Programming Interface (APIs)
!
3.5.73. wifi_disable_gpio_wakeup
Disable the function that the GPIO can wake the ESP8266 up from light-sleep
Function
mode.
Parameter none
Return none
3.5.74. wifi_set_country
true: Success
Return
false: Failure
3.5.75. wifi_get_country
true: Success
Return
false: Failure
Espressif ! /164
64 2020.09
3. Application Programming Interface (APIs)
!
3.6.1. wifi_set_user_fixed_rate
Function Set the fixed rate and mask of sending data from ESP8266.
enum FIXED_RATE {
PHY_RATE_48 = 0x8,
PHY_RATE_24 = 0x9,
PHY_RATE_12 = 0xA,
PHY_RATE_6 = 0xB,
PHY_RATE_54 = 0xC,
Structure and PHY_RATE_36 = 0xD,
Definition PHY_RATE_18 = 0xE,
PHY_RATE_9 = 0xF,
}
uint8 enable_mask:
• 0x00: disable the fixed rate
0: Success
Return
otherwise: Failure
Espressif ! /164
65 2020.09
3. Application Programming Interface (APIs)
!
3.6.2. wifi_get_user_fixed_rate
0: Success
Return
otherwise: Failure
3.6.3. wifi_set_user_sup_rate
Set the rate range in the IE of support rate in ESP8266’s beacon, probe req/resp
Function and other packets. Tell other devices about the rate range supported by ESP8266
to limit the rate of sending packets from other devices.
enum support_rate {
RATE_11B5M = 0,
RATE_11B11M = 1,
RATE_11B1M = 2,
RATE_11B2M = 3,
RATE_11G6M = 4,
Parameter RATE_11G12M = 5,
RATE_11G24M = 6,
RATE_11G48M = 7,
RATE_11G54M = 8,
RATE_11G9M = 9,
RATE_11G18M = 10,
RATE_11G36M = 11,
};
uint8 min: the minimum value of the support rate, according to enum
support_rate.
Parameter
uint8 max: the maximum value of the support rate, according to enum
support_rate.
0: Success
Return
otherwise: Failure
Note This API can only support 802.11g now, but it will support 802.11b in next
version.
Espressif ! /164
66 2020.09
3. Application Programming Interface (APIs)
!
3.6.4. wifi_set_user_rate_limit
Limit the initial rate of sending data from ESP8266. The rate of retransmission is
Function
not limited by this API.
enum RATE_11B_ID {
RATE_11B_B11M = 0,
RATE_11B_B5M = 1,
RATE_11B_B2M = 2,
RATE_11B_B1M = 3,
}
enum RATE_11G_ID {
RATE_11G_G54M = 0,
RATE_11G_G48M = 1,
RATE_11G_G36M = 2,
RATE_11G_G24M = 3,
RATE_11G_G18M = 4,
RATE_11G_G12M = 5,
RATE_11G_G9M = 6,
RATE_11G_G6M = 7
RATE_11G_B5M = 8,
Parameter Definition RATE_11G_B2M = 9,
RATE_11G_B1M = 10
}
enum RATE_11N_ID {
RATE_11N_MCS7S = 0,
RATE_11N_MCS7 = 1,
RATE_11N_MCS6 = 2,
RATE_11N_MCS5 = 3,
RATE_11N_MCS4 = 4,
RATE_11N_MCS3 = 5,
RATE_11N_MCS2 = 6,
RATE_11N_MCS1 = 7,
RATE_11N_MCS0 = 8,
RATE_11N_B5M = 9,
RATE_11N_B2M = 10,
RATE_11N_B1M = 11
}
#define RC_LIMIT_11G 1
#define RC_LIMIT_11N 2
uint8 ifidx: interface of ESP8266
Parameter
• 0x00: ESP8266 Station
• 0x01: ESP8266 SoftAP
uint8 max: the maximum value of the rate, according to the enum rate
corresponding to the first parameter mode.
uint8 min: the minimum value of the rate, according to the enum rate
corresponding to the first parameter mode.
true: Success
Return
false: Failure
Espressif ! /164
67 2020.09
3. Application Programming Interface (APIs)
!
3.6.5. wifi_set_user_limit_rate_mask
uint8 enable_mask:
true: Success
Return
false: Failure
3.6.6. wifi_get_user_limit_rate_mask
Parameter none
Espressif ! /164
68 2020.09
3. Application Programming Interface (APIs)
!
3.7.1. wifi_fpm_open
Parameter none
Return none
3.7.2. wifi_fpm_close
Parameter none
Return none
3.7.3. wifi_fpm_do_wakeup
Parameter none
Return none
This API can only be called when MODEM_SLEEP_T force sleep function is enabled,
Note after calling wifi_fpm_open. This API can not be called after calling
wifi_fpm_close.
Espressif ! /164
69 2020.09
3. Application Programming Interface (APIs)
!
3.7.4. wifi_fpm_set_wakeup_cb
Return none
This API can only be called when force sleep function is enabled, after calling
wifi_fpm_open. This API can not be called after calling wifi_fpm_close.
Note fpm_wakeup_cb_func will be called after system wakes up only if the force sleep
time out (wifi_fpm_do_sleep and the parameter is not 0xFFFFFFF).
fpm_wakeup_cb_func will not be called if wake-up is caused by
wifi_fpm_do_wakeup from MODEM_SLEEP_T type force sleep.
3.7.5. wifi_fpm_do_sleep
Force ESP8266 to enter sleep mode, and it will wake up automatically on time
Function
out.
0, setting successful;
Return -1, failed to sleep, sleep status error;
-2, failed to sleep, force sleep function is not enabled.
This API can only be called when force sleep function is enabled, after calling
wifi_fpm_open. This API can not be called after calling wifi_fpm_close.
Note fpm_wakeup_cb_func will be called after system wakes up only if the force sleep
time out (wifi_fpm_do_sleep and the parameter is not 0xFFFFFFF).
fpm_wakeup_cb_func will not be called if wake-up is caused by
wifi_fpm_do_wakeup from MODEM_SLEEP_T type force sleep.
3.7.6. wifi_fpm_set_sleep_type
Espressif ! /164
70 2020.09
3. Application Programming Interface (APIs)
!
enum sleep_type{
NONE_SLEEP_T = 0,
Parameter LIGHT_SLEEP_T,
MODEM_SLEEP_T,
};
Return none
3.7.7. wifi_fpm_get_sleep_type
Parameter none
enum sleep_type{
NONE_SLEEP_T = 0,
Return LIGHT_SLEEP_T,
MODEM_SLEEP_T,
};
3.7.8. wifi_fpm_auto_sleep_set_in_null_mode
Set whether enter modem sleep mode automatically or not after disabled Wi-Fi
Function
mode (wifi_set_opmode(NULL_MODE)).
uint8 req:
Parameter • 0: disable auto-sleep function;
Return none
3.7.9. Example
For example, forced sleep interface can be called, the RF circuit can be closed mandatorily
so as to lower the power.
📖 Note:
When forced sleep interface is called, the chip will not enter sleep mode instantly, it will enter sleep mode
when the system is executing idle task. Please refer to the below sample code.
Espressif ! /164
71 2020.09
3. Application Programming Interface (APIs)
!
void fpm_wakup_cb_func1(void)
{
wifi_fpm_close(); // disable force sleep function
wifi_set_opmode(STATION_MODE); // set station mode
wifi_station_connect(); // connect to AP
}
void user_func(...)
{
wifi_station_disconnect();
wifi_set_opmode(NULL_MODE); // set WiFi mode to null mode.
wifi_fpm_set_sleep_type(MODEM_SLEEP_T); // modem sleep
wifi_fpm_open(); // enable force sleep
#ifdef SLEEP_MAX
/* For modem sleep, FPM_SLEEP_MAX_TIME can only be wakened by calling
wifi_fpm_do_wakeup. */
wifi_fpm_do_sleep(FPM_SLEEP_MAX_TIME);
#else
// wakeup automatically when timeout.
wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback
wifi_fpm_do_sleep(50*1000);
#endif
}
#ifdef SLEEP_MAX
void func1(void)
{
wifi_fpm_do_wakeup();
wifi_fpm_close(); // disable force sleep function
wifi_set_opmode(STATION_MODE); // set station mode
wifi_station_connect(); // connect to AP
}
#endif
void fpm_wakup_cb_func1(void)
{
wifi_fpm_close(); // disable force sleep function
wifi_set_opmode(STATION_MODE); // set station mode
wifi_station_connect(); // connect to AP
}
#ifndef SLEEP_MAX
// Wakeup till time out.
void user_func(...)
{
wifi_station_disconnect();
wifi_set_opmode(NULL_MODE); // set WiFi mode to null mode.
wifi_fpm_set_sleep_type(LIGHT_SLEEP_T); // light sleep
wifi_fpm_open(); // enable force sleep
wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback
wifi_fpm_do_sleep(50*1000);
}
#else
// Or wake up by GPIO
void user_func(...)
{
wifi_station_disconnect();
wifi_set_opmode(NULL_MODE); // set WiFi mode to null mode.
wifi_fpm_set_sleep_type(LIGHT_SLEEP_T); // light sleep
wifi_fpm_open(); // enable force sleep
Espressif ! /164
72 2020.09
3. Application Programming Interface (APIs)
!
PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12);
wifi_enable_gpio_wakeup(12, GPIO_PIN_INTR_LOLEVEL);
wifi_fpm_set_wakeup_cb(fpm_wakup_cb_func1); // Set wakeup callback
wifi_fpm_do_sleep(FPM_SLEEP_MAX_TIME);
...
}
#endif
Espressif ! /164
73 2020.09
3. Application Programming Interface (APIs)
!
enum esp_now_role {
ESP_NOW_ROLE_IDLE = 0,
ESP_NOW_ROLE_CONTROLLER,
ESP_NOW_ROLE_SLAVE,
ESP_NOW_ROLE_MAX,
};
3.8.2. esp_now_init
Parameter none
0: Success
Return
otherwise: Failure
Espressif ! /164
74 2020.09
3. Application Programming Interface (APIs)
!
3.8.3. esp_now_deinit
Parameter none
0: Success
Return
otherwise: Failure
3.8.4. esp_now_register_recv_cb
0: Success
Return
otherwise: Failure
3.8.5. esp_now_unregister_recv_cb
Parameter none
0: Success
Return
otherwise: Failure
3.8.6. esp_now_register_send_cb
Espressif ! /164
75 2020.09
3. Application Programming Interface (APIs)
!
0: Success
Return
otherwise: Failure
Parameter:
mt_tx_status {
MT_TX_STATUS_OK = 0,
MT_TX_STATUS_FAILED,
}
The status will be updated to MT_TX_STATUS_OK, if ESP-NOW send the packet
successfully. Users must explicitly make sure that the key for communication is
correct.
The send callback can determine the status of a transmitted packet, however,
please note the following points:
Solution: the sender application should re-transmit the packet, and the
receiver should detect the retransmitted packet.
Espressif ! /164
76 2020.09
3. Application Programming Interface (APIs)
!
3.8.7. esp_now_unregister_send_cb
Parameter none
0: Success
Return
otherwise: Failure
3.8.8. esp_now_send
u8 *da: Destination MAC address. If it’s NULL, the packet is sent to all MAC
addresses recorded by ESP-NOW; otherwise, the packet is sent to the target
MAC address only.
Parameter
u8 *data: data to be sent.
0: Success
Return
otherwise: Failure
3.8.9. esp_now_add_peer
Add an ESP-NOW peer, store MAC address of target device into ESP-NOW MAC
Function
list.
0: Success
Return
otherwise: Failure
Espressif ! /164
77 2020.09
3. Application Programming Interface (APIs)
!
3.8.10. esp_now_del_peer
Delete an ESP-NOW peer, delete MAC address of the device from ESP-NOW
Function
MAC list.
0: Success
Return
otherwise: Failure
3.8.11. esp_now_set_self_role
0: Success
Return
otherwise: Failure
3.8.12. esp_now_get_self_role
Prototype u8 esp_now_get_self_role(void)
Parameter none
3.8.13. esp_now_set_peer_role
Set the ESP-NOW role for a target device. If it is set more than one times, the new
Function
role setting will override the old role.
0: Success
Return
otherwise: Failure
Espressif ! /164
78 2020.09
3. Application Programming Interface (APIs)
!
3.8.14. esp_now_get_peer_role
3.8.15. esp_now_set_peer_key
Set ESP-NOW key for a target device. If it is set multiple times, the latest setting
Function
will be valid.
0: Success
Return
otherwise: Failure
3.8.16. esp_now_get_peer_key
Parameter u8 *key: pointer to the key, buffer size has to be 16 bytes at least.
0: Success
Return > 0: Found target device but cannot get key
< 0: Failure
3.8.17. esp_now_set_peer_channel
Espressif ! /164
79 2020.09
3. Application Programming Interface (APIs)
!
Parameter
u8 channel: channel, usually to be 1 ~ 13, some area may use channel 14.
0: Success
Return
otherwise: Failure
3.8.18. esp_now_get_peer_channel
3.8.19. esp_now_is_peer_exist
3.8.20. esp_now_fetch_peer
Get MAC address of ESP-NOW device which is pointed now, and move the
Function pointer to next one in ESP-NOW MAC list or move the pointer to the first one in
ESP-NOW MAC list.
bool restart:
Parameter • true: move pointer to the first one in ESP-NOW MAC list;
Espressif ! /164
80 2020.09
3. Application Programming Interface (APIs)
!
3.8.21. esp_now_get_cnt_info
Get the total number of ESP-NOW devices which are associated, and the number
Function
count of encrypted devices.
Parameter
u8 *encryp_cnt: number count of encrypted devices.
0: Success
Return
otherwise: Failure
3.8.22. esp_now_set_kok
Set the encryption key for the communication key. All ESP-NOW devices share
the same encrypt key. If users do not set the encrypt key, ESP-NOW
Function communication key will be encrypted by a default key.
0: Success
Return
otherwise: Failure
Espressif ! /164
81 2020.09
3. Application Programming Interface (APIs)
!
typedef enum {
SP_ST_MAX,
} SP_ST_t;
3.9.2. register_simple_pair_status_cb
Parameters:
Callback Definition
• u8 *sa: the MAC address of the remote device;
0: Success
Return
otherwise: Failure
3.9.3. unregister_simple_pair_status_cb
Parameter none
Espressif ! /164
82 2020.09
3. Application Programming Interface (APIs)
!
Return none
3.9.4. simple_pair_init
Parameter none
0: Success
Return
otherwise: Failure
3.9.5. simple_pair_deinit
Parameter none
Return none
3.9.6. simple_pair_state_reset
Reset the state of simple pair. When simple pair needs to be restarted again, this
Function
API can be called to reset the state.
Parameter none
0: Success
Return
otherwise: Failure
3.9.7. simple_pair_ap_enter_announce_mode
Parameter none
0: Success
Return
otherwise: Failure
Espressif ! /164
83 2020.09
3. Application Programming Interface (APIs)
!
3.9.8. simple_pair_sta_enter_scan_mode
Parameter none
0: Success
Return
otherwise: Failure
3.9.9. simple_pair_sta_start_negotiate
Parameter none
0: Success
Return
otherwise: Failure
3.9.10. simple_pair_ap_start_negotiate
Parameter none
0: Success
Return
otherwise: Failure
3.9.11. simple_pair_ap_refuse_negotiate
Parameter none
0: Success
Return
otherwise: Failure
Espressif ! /164
84 2020.09
3. Application Programming Interface (APIs)
!
3.9.12. simple_pair_set_peer_ref
Set configuration of the peer which needs to negotiate. Note that this only sets the
configuration of the peer, and does not install keys or perform any other relevant
operations.
Function If the device runs as the station peer, this API needs to be called before
simple_pair_sta_start_negotiate.
If the device runs as the AP peer, this API needs to be called before
simple_pair_ap_start_negotiate or simple_pair_ap_refuse_negotiate.
u8 *peer_mac: MAC address of the target peer of negotiation, length: 6 bytes, can
NOT be null.
0: Success
Return
otherwise: Failure
3.9.13. simple_pair_get_peer_ref
Parameter u8 *tmp_key: the temporary key to encrypt the negotiation, length: 16 bytes.
0: Success
Return
otherwise: Failure
Espressif ! /164
85 2020.09
3. Application Programming Interface (APIs)
!
3.10.1. system_upgrade_userbin_check
Parameter none
3.10.2. system_upgrade_flag_set
uint8 flag:
#define UPGRADE_FLAG_IDLE 0x00
Parameter
#define UPGRADE_FLAG_START 0x01
#define UPGRADE_FLAG_FINISH 0x02
Return none
Note If you using spi_flash_write to upgrade firmware yourself, this flag need to be
set to UPGRADE_FLAG_FINISH, then call system_upgrade_reboot to reboot to run
new firmware.
3.10.3. system_upgrade_flag_check
Parameter none
Espressif ! /164
86 2020.09
3. Application Programming Interface (APIs)
!
3.10.4. system_upgrade_start
Return
false: upgrade cannot be started.
3.10.5. system_upgrade_reboot
Parameter none
Return none
Espressif ! /164
87 2020.09
3. Application Programming Interface (APIs)
!
3.11.1. wifi_promiscuous_enable
uint8 promiscuous:
Parameter • 0: disable promiscuous;
• 1: enable promiscuous
Return none
• During promiscuous mode (sniffer), ESP8266 Station and SoftAP are disabled.
Note • Before enable promiscuous mode, please call wifi_station_disconnect first.
3.11.2. wifi_promiscuous_set_mac
Set a destination MAC address filter for sniffer. It will filter all packets sent to the
Function
specific MAC address, including broadcast packets.
Return none
Example
wifi_promiscuous_set_mac(ap_mac);
3.11.3. wifi_set_promiscuous_rx_cb
Function Registers an Rx callback function in promiscuous mode, which will be called when
data packet is received.
Return none
Espressif ! /164
88 2020.09
3. Application Programming Interface (APIs)
!
3.11.4. wifi_get_channel
Parameter none
3.11.5. wifi_set_channel
true: Success
Return
false: Failure
Espressif ! /164
89 2020.09
3. Application Programming Interface (APIs)
!
3.12.1. smartconfig_start
Start smart configuration mode. Connect ESP8266 Station to AP, by sniffing for
special packets from the air, containing SSID and password of desired AP. You
Function
need to broadcast the SSID and password (e.g. from mobile device or computer)
with the SSID and password encoded.
typedef enum {
SC_STATUS_GETTING_SSID_PSWD,
SC_STATUS_LINK,
Structure
SC_STATUS_LINK_OVER, // Got IP, connect to AP
successfully
} sc_status;
typedef enum {
SC_TYPE_ESPTOUCH = 0,
SC_TYPE_AIRKISS,
} sc_type;
bool smartconfig_start(
Prototype sc_callback_t cb,
uint8 log
)
uint8 log: 1: UART outputs logs; otherwise: UART only outputs the result. It is
suggested that this log is only used for debugging. Users should not set it to 1
while SmartConfig is working.
Espressif ! /164
90 2020.09
3. Application Programming Interface (APIs)
!
true: Success
Return
false: Failure
void ICACHE_FLASH_ATTR
switch(status) {
case SC_STATUS_WAIT:
os_printf("SC_STATUS_WAIT\n");
break;
case SC_STATUS_FIND_CHANNEL:
os_printf("SC_STATUS_FIND_CHANNEL\n");
break;
case SC_STATUS_GETTING_SSID_PSWD:
os_printf("SC_STATUS_GETTING_SSID_PSWD\n");
if (*type == SC_TYPE_ESPTOUCH) {
os_printf("SC_TYPE:SC_TYPE_ESPTOUCH\n");
} else {
os_printf("SC_TYPE:SC_TYPE_AIRKISS\n");
break;
os_printf("SC_STATUS_LINK\n");
wifi_station_set_config(sta_conf);
wifi_station_disconnect();
wifi_station_connect();
break;
case SC_STATUS_LINK_OVER:
os_printf("SC_STATUS_LINK_OVER\n");
if (pdata != NULL) {
smartconfig_stop();
break;
}
}
smartconfig_start(smartconfig_done);
Note • Can not call smartconfig_start twice before it finish, please call
smartconfig_stop first.
• Don’t call any other APIs during smart-config, please call smartconfig_stop
first.
Espressif ! /164
91 2020.09
3. Application Programming Interface (APIs)
!
3.12.2. smartconfig_stop
Parameter none
true: Success
Return
false: Failure
3.12.3. smartconfig_set_type
typedef enum {
SC_TYPE_ESPTOUCH = 0,
Parameter SC_TYPE_AIRKISS,
SC_TYPE_ESPTOUCH_AIRKISS,
} sc_type;
true: Success
Return
false: Failure
3.12.4. airkiss_version
Parameter none
Espressif ! /164
92 2020.09
3. Application Programming Interface (APIs)
!
3.12.5. airkiss_lan_recv
For the function that AirKiss can detect the ESP8266 devices in LAN, more details
of this function refer to http://iot.weixin.qq.com.
int airkiss_lan_recv(
const void* body,
Prototype
unsigned short length,
const airkiss_config_t* config)
Refer to airkiss_lan_ret_t,
< 0: Failure
3.12.6. airkiss_lan_pack
User packet assembly for the function that AirKiss can detect the ESP8266
Function
devices in LAN.
int airkiss_lan_pack(
airkiss_lan_cmdid_t ak_lan_cmdid,
void* appid,
void* deviceid,
Prototype void* _datain,
unsigned short inlength,
void* _dataout,
unsigned short* outlength,
const airkiss_config_t* config)
Refer to airkiss_lan_ret_t
< 0: Failure
Espressif ! /164
93 2020.09
3. Application Programming Interface (APIs)
!
3.13.1. sntp_setserver
unsigned char idx: SNTP server index; 3 SNTP server is supported at most (0 ~
Parameter 2); index 0 is the main server, and index 1 and 2 are backups.
Return none
3.13.2. sntp_getserver
Parameter unsigned char idx: SNTP server index; supports 3 SNTP servers at most (0 ~ 2).
Return IP address
3.13.3. sntp_setservername
Function Set SNTP server by domain name; support 3 SNTP server at most.
unsigned char idx: SNTP server index, supports 3 SNTP servers at most (0 ~ 2);
Parameter index 0 is the main server, and index 1 and 2 are as backup.
char *server: domain name; users need to ensure that it is an SNTP server.
Return none
3.13.4. sntp_getservername
Parameter unsigned char idx: SNTP server index; supports 3 SNTP servers at most (0 ~ 2).
Espressif ! /164
94 2020.09
3. Application Programming Interface (APIs)
!
3.13.5. sntp_init
Parameter none
Return none
3.13.6. sntp_stop
Parameter none
Return none
3.13.7. sntp_get_current_timestamp
Get current timestamp from basic time (1970.01.01 00:00:00 GMT + 8); uint:
Function
second.
Parameter none
3.13.8. sntp_get_real_time
3.13.9. sntp_set_timezone
true: Success
Return
false: Failure
Espressif ! /164
95 2020.09
3. Application Programming Interface (APIs)
!
sntp_stop();
Example
sntp_init();
3.13.10.sntp_get_timezone
Parameter none
3.13.11.SNTP Example
Step 1. Enable SNTP.
ipaddr_aton("210.72.145.44", addr);
sntp_init();
os_free(addr);
os_timer_disarm(&sntp_timer);
uint32 current_stamp;
current_stamp = sntp_get_current_timestamp();
if(current_stamp == 0){
Espressif ! /164
96 2020.09
3. Application Programming Interface (APIs)
!
} else{
os_timer_disarm(&sntp_timer);
Espressif ! /164
97 2020.09
3. Application Programming Interface (APIs)
!
3.14.1. wifi_station_set_wpa2_enterprise_auth
int enable:
Parameter • 0, disable authentication of WPA2_Enterprise, clear the status;
0: Success
Return
otherwise: Failure
3.14.2. wifi_station_set_enterprise_cert_key
Set user certificate and private key for connecting to WPA2_Enterprise AP. It is
Function
used for EAP-TLS authentication.
int wifi_station_set_enterprise_cert_key (
u8 *client_cert, int client_cert_len,
Prototype
u8 *private_key, int private_key_len,
u8 *private_key_passwd, int private_key_passwd_len,)
u8 *private_key: private key, HEX array, can NOT be longer than 2048 bits
0: Success
Return
otherwise: Failure
Espressif ! /164
98 2020.09
3. Application Programming Interface (APIs)
!
then array should be uint8 key[]={0x2d, 0x2d, 0x2d, 0x2d, 0x2d, 0x42, 0x45,
Example 0x47, … … 0x00 };
It is the ASCII code for the characters, and the array needs to terminate with
0x00.
• Please call this API to set certificate and private key before connecting to
WPA2_ Enterprise AP and the application needs to hold the certificate and
private key. Call wifi_station_clear_enterprise_cert_key to release
resources and clear status after being connected to the target AP, and then the
application can release the certificate and private key.
• If the private key is encrypted, please use openssl pkey command to change it
to unencrypted file to use, or use openssl rsa related commands to change it
(or change the start TAG).
3.14.3. wifi_station_clear_enterprise_cert_key
Release user certificate and private key resources and clear related status after
Function
being connected to the WPA2_Enterprise AP.
Parameter none
Return none
3.14.4. wifi_station_set_enterprise_ca_cert
0 : Success
Return
otherwise : Failure
Espressif ! /164
99 2020.09
3. Application Programming Interface (APIs)
!
3.14.5. wifi_station_clear_enterprise_ca_cert
Release root certificate resources and clear related status after being connected
Function
to the WPA2_Enterprise AP.
Parameter none
Return none
3.14.6. wifi_station_set_enterprise_username
Function Set ESP8266 Station’s user name for connecting to WPA2_Enterprise AP.
0: Success
Return
otherwise: Failure
• For EAP-TTLS and EAP-PEAP authentication, the user name has to be set. It is
used in phase 2 of the authentication, only the user name that the server
Note supported can pass the authentication.
• For EAP-TTLS and EAP-PEAP authentication, the user name is only an option.
Without setting user name, the authentication can still be done anonymously.
3.14.7. wifi_station_clear_enterprise_username
Release the user name resources and clear related status after being connected
Function
to the WPA2_Enterprise AP.
Parameter none
Return none
3.14.8. wifi_station_set_enterprise_password
Set the password for connecting to WPA2_Enterprise AP. It is used for EAP-
Function
TTLS / EAP-PEAP authentication.
0: Success
Return
otherwise: Failure
3.14.9. wifi_station_clear_enterprise_password
Clear the password resources and clear related status data after being connected
Function
to the WPA2_Enterprise AP.
Parameter none
Return none
3.14.10.wifi_station_set_enterprise_new_password
Set the new password for connecting to WPA2_Enterprise AP. It is used for
Function
MSCHAPV2.
0: Success
Return
otherwise: Failure
3.14.11.wifi_station_clear_enterprise_new_password
Release the new password resources and clear related status after being
Function
connected to the WPA2_Enterprise AP.
Parameter none
Return none
3.14.12.wifi_station_set_enterprise_disable_time_check
bool disable:
• true, will NOT check the expiration time;
Parameter
• false, check the expiration time, wpa2_enterprise_set_user_get_time has
to be called.
Return none
3.14.13.wifi_station_get_enterprise_disable_time_check
Parameter none
3.14.14.wpa2_enterprise_set_user_get_time
Return none
Example
//Set Callback
wpa2_enterprise_set_user_get_time(sys_get_current_time);
4. TCP/UDP APIs
Found in ESP8266_NONOS_SDK/include/espconn.h. The network APIs can be grouped
into the following types:
• General APIs: APIs can be used for both TCP and UDP .
• TCP APIs: APIs that are only used for TCP.
• UDP APIs: APIs that are only used for UDP.
• mDNS APIs: APIs that related to mDNS.
0: Success
Corresponding API:
Note TCP: espconn_accept;
UDP: espconn_create.
4.1.2. espconn_gethostbyname
Function DNS
err_t espconn_gethostbyname(
struct espconn *pespconn,
Prototype const char *hostname,
ip_addr_t *addr,
dns_found_callback found
)
err_t:
• ESPCONN_OK: Success.
UDP: espconn_create.
ip_addr_t esp_server_ip;
LOCAL void ICACHE_FLASH_ATTR
user_esp_platform_dns_found(const char *name, ip_addr_t *ipaddr, void
*arg) {
struct espconn *pespconn = (struct espconn *)arg;
if (ipaddr != NULL)
Example os_printf(user_esp_platform_dns_found %d.%d.%d.%d/n,
*((uint8 *)&ipaddr->addr), *((uint8 *)&ipaddr->addr + 1),
*((uint8 *)&ipaddr->addr + 2), *((uint8 *)&ipaddr->addr + 3));
}
void dns_test(void) {
espconn_gethostbyname(pespconn,"iot.espressif.cn", &esp_server_ip,
user_esp_platform_dns_found);
}
4.1.3. espconn_port
Parameter none
4.1.4. espconn_regist_sentcb
Register data sent function which will be called back when data are successfully
Function
sent.
sint8 espconn_regist_sentcb(
struct espconn *espconn,
Prototype
espconn_sent_callback sent_cb
)
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find network
transmission according to structure espconn.
4.1.5. espconn_regist_recvcb
Function Register data receive function which will be called back when data is received.
sint8 espconn_regist_recvcb(
struct espconn *espconn,
Prototype
espconn_recv_callback recv_cb
)
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find network
transmission according to structure espconn.
4.1.6. espconn_sent_callback
void *arg: pointer corresponding structure espconn. This pointer may be different
in different callbacks, please don’t use this pointer directly to distinguish one from
Parameter
another in multiple connections, use remote_ip and remote_port in espconn
instead.
Return none
4.1.7. espconn_recv_callback
void espconn_recv_callback (
void *arg,
Prototype char *pdata,
unsigned short len
)
void *arg: pointer corresponding structure espconn. This pointer may be different
in different callbacks, please don’t use this pointer directly to distinguish one from
another in multiple connections, use remote_ip and remote_port in espconn
Parameter instead.
Return none
4.1.8. espconn_get_connection_info
Get the information about a TCP connection or UDP transmission. Usually used in
Function
the espconn_recv_callback.
sint8 espconn_get_connection_info(
struct espconn *espconn,
Prototype remot_info **pcon_info,
uint8 typeflags
)
- 0, regular server;
- 1, ssl server.
0: Success
Return
if (espconn_get_connection_info(pesp_conn,&premot,0) ==
ESPCONN_OK){
pesp_conn->proto.tcp->remote_port = premot->remote_port;
pesp_conn->proto.tcp->remote_ip[0] = premot-
Example >remote_ip[0];
pesp_conn->proto.tcp->remote_ip[1] = premot-
>remote_ip[1];
pesp_conn->proto.tcp->remote_ip[2] = premot-
>remote_ip[2];
pesp_conn->proto.tcp->remote_ip[3] = premot-
>remote_ip[3];
4.1.9. espconn_send
sint8 espconn_send(
struct espconn *espconn,
Prototype uint8 *psent,
uint16 length
)
0: Success
4.1.10. espconn_sent
[@deprecated] This API is deprecated, please use espconn_send instead.
sint8 espconn_send(
struct espconn *espconn,
Prototype uint8 *psent,
uint16 length
)
0: Success
4.2.1. espconn_accept
0: Success
4.2.2. espconn_regist_time
sint8 espconn_regist_time(
struct espconn *espconn,
Prototype uint32 interval,
uint8 type_flag
)
0: Success.
Return ESPCONN_ARG: illegal argument, cannot find TCP connection according to structure
espconn.
4.2.3. espconn_connect
0: Success
4.2.4. espconn_regist_connectcb
Function Register a connected callback which will be called on successful TCP connection.
sint8 espconn_regist_connectcb(
Prototype struct espconn *espconn,
espconn_connect_callback connect_cb
)
Parameter
espconn_connect_callback connect_cb: registered callback function.
0: Success
Return Otherwise: error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.5. espconn_connect_callback
Return none
4.2.6. espconn_set_opt
enum espconn_option{
ESPCONN_START = 0x00,
ESPCONN_REUSEADDR = 0x01,
Structure ESPCONN_NODELAY = 0x02,
ESPCONN_COPY = 0x04,
ESPCONN_KEEPALIVE = 0x08,
ESPCONN_END
}
- bit 0: 1: free memory after TCP disconnection. Need not wait for 2
minutes.
Parameter - bit 1: 1: disable nagle algorithm during TCP data transmission, thus
quickening the data transmission.
0: Success
Return Otherwise: error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.7. espconn_clear_opt
sint8 espconn_clear_opt(
Prototype struct espconn *espconn,
uint8 opt
)
enum espconn_option{
ESPCONN_START = 0x00,
ESPCONN_REUSEADDR = 0x01,
ESPCONN_NODELAY = 0x02,
Structure
ESPCONN_COPY = 0x04,
ESPCONN_KEEPALIVE = 0x08,
ESPCONN_END
0: Success
Return Otherwise: error code ESPCONN_ARG: illegal argument; cannot find TCP
connection according to structure espconn.
4.2.8. espconn_set_keepalive
enum espconn_level{
ESPCONN_KEEPIDLE,
Structure ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
Please note that keep alive interval is not precise, only for reference, it
depends on priority.
Parameter
Description:
0: Success
Return Otherwise: error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.9. espconn_get_keepalive
enum espconn_level{
ESPCONN_KEEPIDLE,
Structure ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
• uint8 level:
0: Success
Return Otherwise: error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.10. espconn_reconnect_callback
This callback is entered when an error occurs, TCP connection broken. This
Function
callback is registered by espconn_regist_reconcb.
enum espconn_level{
ESPCONN_KEEPIDLE,
Structure ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
- ESCONN_TIMEOUT: Timeout.
Parameter - ESPCONN_ABRT: TCP connection aborted.
Return none
4.2.11. espconn_regist_reconcb
sint8 espconn_regist_reconcb(
Prototype struct espconn *espconn,
espconn_reconnect_callback recon_cb
)
enum espconn_level{
ESPCONN_KEEPIDLE,
Structure ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
0: Success.
Return Otherwise: Error code ESPCONN_ARG: illegal argument, cannot find TCP connection
according to structure espconn.
4.2.12. espconn_disconnect
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument, cannot find TCP connection
according to structure espconn.
Do not call this API in any espconn callback. If needed, please use
Note
system_os_task and system_os_post to trigger espconn_disconnect.
4.2.13. espconn_regist_disconcb
sint8 espconn_regist_disconcb(
Prototype struct espconn *espconn,
espconn_connect_callback discon_cb
)
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument, cannot find TCP connection
according to structure espconn.
4.2.14. espconn_abort
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
Do not call this API in any espconn callback. If needed, please use
Note
system_os_task and system_os_post to trigger espconn_abort.
4.2.15. espconn_regist_write_finish
Register a callback which will be called when all sending data is completely written
Function
into write buffer or sent.
sint8 espconn_regist_write_finish (
Prototype struct espconn *espconn,
espconn_connect_callback write_finish_fn
)
• write-buffer is used to keep TCP data that is waiting to be sent, queue number
of the write-buffer is 8 which means that it can keep 8 packets at most. The size
Notes of write-buffer is 2920 bytes.
0 : Success
Return Non-0 : Error code ESPCONN_ARG - illegal argument, cannot find TCP connection
according to structure espconn
4.2.16. espconn_tcp_get_max_con
Parameter none
4.2.17. espconn_tcp_set_max_con
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.18. espconn_tcp_get_max_con_allow
Get the maximum number of TCP clients allowed to connect to ESP8266 TCP
Function
server.
4.2.19. espconn_tcp_set_max_con_allow
Set the maximum number of TCP clients allowed to connect to ESP8266 TCP
Function
server.
Parameter
• uint8 num: Maximum number of TCP clients allowed.
0: Success
Return
Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.20. espconn_recv_hold
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.21. espconn_recv_unhold
0: Success
Return
Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find TCP connection
according to structure espconn.
4.2.22. espconn_secure_accept
0: Success
• This API can be called only once. Only one SSL server is allowed to be created,
and only one SSL client can be connected.
• If the SSL encrypted packet size is larger than ESP8266’s SSL buffer size
(default 2 KB, set by espconn_secure_set_size), SSL connection will fail.
ESP8266 will enter espconn_reconnect_callback.
Note • SSL-related APIs named as espconn_secure_XXX are different from normal TCP
APIs and must not be used interchangeably. In SSL connection, only
espconn_secure_XXX APIs, espconn_regist_XXXcb APIs and espconn_port can
be used.
4.2.23. espconn_secure_delete
Function Delete the SSL connection when ESP8266 runs as SSL server.
0: Success;
4.2.24. espconn_secure_set_size
• uint16 size: buffer size; range: 1 ~ 8192; unit: byte, default to be 2048.
true: Success
Return
false: Failure
The default buffer size is 2 KB. Please call this API before espconn_secure_accept
Note (ESP8266 as TCP SSL server) or espconn_secure_connect (ESP8266 as TCP
SSL client) to change buffer size.
4.2.25. espconn_secure_get_size
4.2.26. espconn_secure_connect
0: Success
• Only one connection is allowed when the ESP8266 acts as a SSL client. This
API can be called only once. Users can call espconn_secure_disconnect to
disconnect first before calling this API to create another SSL connection.
• If the SSL encrypted packet size is larger than the ESP8266 SSL buffer size (2
KB by default, set by espconn_secure_set_size), the SSL connection will fail.
The ESP8266 will enter espconn_reconnect_callback
4.2.27. espconn_secure_send
sint8 espconn_secure_send (
struct espconn *espconn,
Prototype uint8 *psent,
uint16 length
)
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find SSL connection
according to structure espconn.
4.2.28. espconn_secure_sent
[@deprecated] This API is deprecated; please use espconn_secure_send instead.
sint8 espconn_secure_send (
struct espconn *espconn,
Prototype uint8 *psent,
uint16 length
)
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find SSL connection
according to structure espconn.
4.2.29. espconn_secure_disconnect
0: Success
Return Otherwise: Error code ESPCONN_ARG: illegal argument; cannot find SSL connection
according to structure espconn.
Do not call this API in any espconn callback. If needed, please use
Note
system_os_task and system_os_post to trigger espconn_secure_disconnect.
4.2.30. espconn_secure_ca_enable
true: Success
Return
false: Failure
4.2.31. espconn_secure_ca_disable
true: Success
Return
false: Failure
4.2.32. espconn_secure_cert_req_enable
Function Enable certification verification function when the ESP8266 runs as SSL client.
uint8 level: can only be set as 0x01 when ESP8266 runs as SSL client;
true: Success
Return
false: Failure
4.2.33. espconn_secure_cert_req_disable
Function Disable certification verification function when ESP8266 runs as SSL client.
Parameter uint8 level: can only be set as 0x01 when ESP8266 runs as SSL client.
true: Success
Return
false: Failure
4.2.34. espconn_secure_set_default_certificate
true: Success
Return
false: Failure
4.2.35. espconn_secure_set_default_private_key
Function Set the secure key when ESP8266 runs as SSL server.
true: Success
Return
false: Failure
0: Success
Note Parameter remote_ip and remote_port need to be set. Do not set them to be 0.
4.3.2. espconn_sendto
0: Success
4.3.3. espconn_igmp_join
0: Success
Return
Otherwise: Error code ESPCONN_MEM: Out of memory.
Note This API can only be called after the ESP8266 Station connects to a router.
4.3.4. espconn_igmp_leave
0: Success
Return
Otherwise: Error code ESPCONN_MEM: Out of memory.
4.3.5. espconn_dns_setserver
Function Set default DNS server. Two DNS servers are allowed to be set.
Return none
4.3.6. espconn_dns_getserver
struct mdns_info{
char *host_name;
char *server_name;
Structure uint16 server_port;
unsigned long ipAddr;
char *txt_data[10];
};
Return none
4.4.2. espconn_mdns_close
Parameter none
Return none
4.4.3. espconn_mdns_server_register
Parameter none
Return none
4.4.4. espconn_mdns_server_unregister
Parameter none
Return none
4.4.5. espconn_mdns_get_servername
Parameter none
4.4.6. espconn_mdns_set_servername
Return none
4.4.7. espconn_mdns_set_hostname
Return none
4.4.8. espconn_mdns_get_hostname
Parameter none
4.4.9. espconn_mdns_enable
Parameter none
Return none
4.4.10. espconn_mdns_disable
Parameter none
Return none
void user_mdns_config()
wifi_get_ip_info(STATION_IF, &ipconfig);
info->host_name = "espressif";
info->ipAddr = ipconfig.ip.addr; //ESP8266 Station IP
info->server_name = "iot";
info->server_port = 8080;
info->txt_data[0] = "version = now";
info->txt_data[1] = "user1 = data1";
info->txt_data[2] = "user2 = data2";
espconn_mdns_init(&info);
}
5. Application-Related APIs
5.1. AT APIs
AT APIs can be found in /ESP8266_NONOS_SDK/include/at_custom.h.
For AT APIs examples, refer to ESP8266_NONOS_SDK/examples/at.
5.1.1. at_response_ok
Parameter none
Return none
5.1.2. at_response_error
Parameter none
Return none
5.1.3. at_cmd_array_regist
Register user-defined AT commands. It can be called only once to register all user-
Function
defined AT commands.
void at_cmd_array_regist (
Prototype at_function * custom_at_cmd_arrar,
uint32 cmd_num
)
Return none
5.1.4. at_get_next_int_dec
- 1: no number is found;
true: parser succeeds (Notes: if no number is found, it will return True, but returns
error code 1);
Return false: parser is unable to parse string; some probable causes are: int number is
more than 10 bytes; string contains termination characters \r; string contains only
-.
5.1.5. at_data_str_copy
length of string:
Return • >=0: Success, and returns the length of the string;
5.1.6. at_init
Parameter none
Return none
5.1.7. at_port_print
Return none
5.1.8. at_set_custom_info
Return none
5.1.9. at_enter_special_state
Enter processing state. In processing state, AT core will return busy for any further
Function
AT commands.
Parameter none
Return none
5.1.10. at_leave_special_state
Parameter none
Return none
5.1.11. at_get_version
Parameter none
5.1.12. at_register_uart_rx_intr
Return none
os_printf("len=%d \r\n",len);
os_printf(data);
Example
at_register_uart_rx_intr(NULL);
5.1.13. at_response
Return none
5.1.14. at_register_response_func
Return none
5.1.15. at_fake_uart_enable
Parameter
at_fake_uart_tx_func_type func: callback for UART Tx simulation.
true: Success
Return
false: Failure
5.1.16. at_fake_uart_rx
Function UART Rx; can be used to develop AT commands through SDIO or network.
Parameter
uint32 length: length of data.
If successful, the return value will be equal to length, otherwise, the API fails to
Return
perform its function.
5.1.17. at_set_escape_character
Function Set an escape character for AT commands. The default escape character is \.
true: Success
Return
false: Failure
5.2.1. jsonparse_setup
void jsonparse_setup(
struct jsonparse_state *state,
Prototype const char *json,
int len
)
Return none
5.2.2. jsonparse_next
5.2.3. jsonparse_copy_value
int jsonparse_copy_value(
struct jsonparse_state *state,
Prototype char *str,
int size
)
5.2.4. jsonparse_get_value_as_int
5.2.5. jsonparse_get_value_as_long
5.2.6. jsonparse_get_len
5.2.7. jsonparse_get_value_as_type
5.2.8. jsonparse_strcmp_value
Parameter
const char *str: character buffer.
5.2.9. jsontree_set_up
void jsontree_setup(
struct jsontree_context *js_ctx,
Prototype struct jsontree_value *root,
int (* putchar)(int)
)
Return none
5.2.10. jsontree_reset
Return none
5.2.11. jsontree_path_name
5.2.12. jsontree_write_int
void jsontree_write_int(
const struct jsontree_context *js_ctx,
Prototype
int value
)
Return none
5.2.13. jsontree_write_int_array
void jsontree_write_int_array(
const struct jsontree_context *js_ctx,
Prototype const int *text,
uint32 length
)
Return none
5.2.14. jsontree_write_string
void jsontree_write_string(
const struct jsontree_context *js_ctx,
Prototype
const char *text
)
Return none
5.2.15. jsontree_print_next
5.2.16. jsontree_find_next
uint32_t timer_expire;
uint32_t timer_period;
ETSTimerFunc *timer_func;
void *timer_arg;
} ETSTimer;
typedef struct {
int8 rssi;
AUTH_MODE authmode;
} wifi_fast_scan_threshold_t;
struct station_config {
uint8 ssid[32];
uint8 password[64];
uint8 bssid_set; // Note: If bssid_set is 1, station will just connect to the router
// with both ssid[] and bssid[] matched. Please check about this.
uint8 bssid[6];
wifi_fast_scan_threshold_t threshold;
};
⚠ Notice:
BSSID is the MAC address of AP, which will be used when several APs have the same SSID. If
station_config.bssid_set==1 , station_config.bssid has to be set; otherwise, the connection will fail. In
general, station_config.bssid_set need to be 0.
AUTH_OPEN = 0,
AUTH_WEP,
AUTH_WPA_PSK,
AUTH_WPA2_PSK,
AUTH_WPA_WPA2_PSK
} AUTH_MODE;
struct softap_config {
uint8 ssid[32];
uint8 password[64];
uint8 ssid_len;
};
⚠ Notice:
If softap_config.ssid_len==0, SSID is checked till a termination character is found; otherwise, set the
length of SSID according to softap_config.ssid_len.
struct scan_config {
uint8 *ssid;
uint8 *bssid;
uint8 channel;
uint8 show_hidden; // Scan APs which are hiding their SSID or not.
};
struct bss_info {
STAILQ_ENTRY(bss_info) next;
uint8 bssid[6];
uint8 ssid[32];
uint8 ssid_len;
uint8 channel;
sint8 rssi;
AUTH_MODE authmode;
sint16 freqcal_val;
uint8 *esp_mesh_ie;
uint8 simple_pair;
CIPHER_TYPE pairwise_cipher;
CIPHER_TYPE group_cipher;
uint32_t phy_11b:1;
uint32_t phy_11g:1;
uint32_t phy_11n:1;
uint32_t wps:1;
uint32_t reserved:28;
};
enum {
EVENT_STAMODE_CONNECTED = 0,
EVENT_STAMODE_DISCONNECTED,
EVENT_STAMODE_AUTHMODE_CHANGE,
EVENT_STAMODE_GOT_IP,
EVENT_STAMODE_DHCP_TIMEOUT,
EVENT_SOFTAPMODE_STACONNECTED,
EVENT_SOFTAPMODE_STADISCONNECTED,
EVENT_SOFTAPMODE_PROBEREQRECVED,
EVENT_OPMODE_CHANGED,
EVENT_SOFTAPMODE_DISTRIBUTE_STA_IP
EVENT_MAX
};
enum {
REASON_UNSPECIFIED = 1,
REASON_AUTH_EXPIRE = 2,
REASON_AUTH_LEAVE = 3,
REASON_ASSOC_EXPIRE = 4,
REASON_ASSOC_TOOMANY = 5,
REASON_NOT_AUTHED = 6,
REASON_NOT_ASSOCED = 7,
REASON_ASSOC_LEAVE = 8,
REASON_ASSOC_NOT_AUTHED = 9,
REASON_BEACON_TIMEOUT = 200,
REASON_NO_AP_FOUND = 201,
REASON_AUTH_FAIL = 202,
REASON_ASSOC_FAIL = 203,
REASON_HANDSHAKE_TIMEOUT = 204,
};
typedef struct {
uint8 ssid[32];
uint8 ssid_len;
uint8 bssid[6];
uint8 channel;
} Event_StaMode_Connected_t;
typedef struct {
uint8 ssid[32];
uint8 ssid_len;
uint8 bssid[6];
uint8 reason;
} Event_StaMode_Disconnected_t;
typedef struct {
uint8 old_mode;
uint8 new_mode;
} Event_StaMode_AuthMode_Change_t;
typedef struct {
} Event_StaMode_Got_IP_t;
typedef struct {
uint8 mac[6];
uint8 aid;
} Event_SoftAPMode_StaConnected_t;
typedef struct {
uint8 mac[6];
uint8 aid;
} Event_SoftAPMode_Distribute_Sta_IP_t;
typedef struct {
uint8 mac[6];
uint8 aid;
} Event_SoftAPMode_StaDisconnected_t;
typedef struct {
int rssi;
uint8 mac[6];
} Event_SoftAPMode_ProbeReqRecved_t;
typedef struct {
uint8 old_opmode;
uint8 new_opmode;
} Event_OpMode_Change_t;
typedef union {
Event_StaMode_Connected_t connected;
Event_StaMode_Disconnected_t disconnected;
Event_StaMode_AuthMode_Change_t auth_change;
Event_StaMode_Got_IP_t got_ip;
Event_SoftAPMode_StaConnected_t sta_connected;
Event_SoftAPMode_Distribute_Sta_IP_t distribute_sta_ip;
Event_SoftAPMode_StaDisconnected_t sta_disconnected;
Event_SoftAPMode_ProbeReqRecved_t ap_probereqrecved;
Event_OpMode_Change_t opmode_changed;
} Event_Info_u;
uint32 event;
Event_Info_u event_info;
} System_Event_t;
typedef enum {
SC_STATUS_GETTING_SSID_PSWD,
SC_STATUS_LINK,
} sc_status;
typedef enum {
SC_TYPE_ESPTOUCH = 0,
SC_TYPE_AIRKISS,
SC_TYPE_ESPTOUCH_AIRKISS,
} sc_type;
struct jsontree_value {
uint8_t type;
};
struct jsontree_pair {
};
struct jsontree_context {
uint16_t index[JSONTREE_MAX_DEPTH];
int (* putchar)(int);
uint8_t depth;
uint8_t path;
int callback_state;
};
struct jsontree_callback {
uint8_t type;
};
struct jsontree_object {
uint8_t type;
uint8_t count;
};
struct jsontree_array {
uint8_t type;
uint8_t count;
};
struct jsonparse_state {
int pos;
int len;
int depth;
int vstart;
int vlen;
char vtype;
char error;
char stack[JSONPARSE_MAX_DEPTH];
};
JSON_TYPE_OBJECT, /
sizeof(jsontree_pair_##name)/sizeof(struct jsontree_pair), /
jsontree_pair_##name }
JSON_TYPE_ARRAY, /
sizeof(jsontree_value_##name)/sizeof(struct jsontree_value*), /
jsontree_value_##name }
int remote_port;
int local_port;
uint8 local_ip[4];
uint8 remote_ip[4];
espconn_connect_callback connect_callback;
espconn_reconnect_callback reconnect_callback;
espconn_connect_callback disconnect_callback;
espconn_connect_callback write_finish_fn;
} esp_tcp;
int remote_port;
int local_port;
uint8 local_ip[4];
uint8 remote_ip[4];
} esp_udp;
enum espconn_type {
ESPCONN_INVALID = 0,
/* ESPCONN_TCP Group */
ESPCONN_TCP = 0x10,
/* ESPCONN_UDP Group */
ESPCONN_UDP = 0x20,
};
/** Current state of the espconn. Non-TCP espconn are always in state ESPCONN_NONE! */
enum espconn_state {
ESPCONN_NONE,
ESPCONN_WAIT,
ESPCONN_LISTEN,
ESPCONN_CONNECT,
ESPCONN_WRITE,
ESPCONN_READ,
ESPCONN_CLOSE
};
enum espconn_option{
ESPCONN_START = 0x00,
ESPCONN_REUSEADDR = 0x01,
ESPCONN_NODELAY = 0x02,
ESPCONN_COPY = 0x04,
ESPCONN_KEEPALIVE = 0x08,
ESPCONN_MANUALRECV = 0x10,
ESPCONN_END
enum espconn_level{
ESPCONN_KEEPIDLE,
ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
struct espconn {
union {
esp_tcp *tcp;
esp_udp *udp;
} proto;
/** A callback function that is informed about events for this espconn */
espconn_recv_callback recv_callback;
espconn_sent_callback sent_callback;
uint8 link_cnt;
};
/* interrupt related */
#define ETS_SPI_INUM 2
#define ETS_GPIO_INUM 4
#define ETS_UART_INUM 5
#define ETS_UART1_INUM 5
#define ETS_FRC_TIMER1_INUM 9
/* enable a interrupt */
/* disable a interrupt */
7. Peripheral-Related Drivers
For peripheral drivers please see /ESP8266_NONOS_SDK/driver_lib.
7.1.2. gpio_output_set
void gpio_output_set(
uint32 set_mask,
Prototype uint32 clear_mask,
uint32 enable_mask,
uint32 disable_mask
)
Return none
7.1.5. gpio_pin_intr_state_set
void gpio_pin_intr_state_set(
Prototype uint32 i,
GPIO_INT_TYPE intr_state
)
uint32 i : GPIO pin ID, if you want to set GPIO14, pls use
GPIO_ID_PIN(14);
GPIO_INT_TYPE intr_state : interrupt type as the following:
typedef enum {
GPIO_PIN_INTR_DISABLE = 0,
Parameter GPIO_PIN_INTR_POSEDGE = 1,
GPIO_PIN_INTR_NEGEDGE = 2,
GPIO_PIN_INTR_ANYEDGE = 3,
GPIO_PIN_INTR_LOLEVEL = 4,
GPIO_PIN_INTR_HILEVEL = 5
} GPIO_INT_TYPE;
Return none
uint32 gpio_status;
gpio_status = GPIO_REG_READ(GPIO_STATUS_ADDRESS);
GPIO_REG_WRITE(GPIO_STATUS_W1TC_ADDRESS, gpio_status);
7.2.1. uart_init
void uart_init(
Prototype UartBautRate uart0_br,
UartBautRate uart1_br
)
Parameter
UartBautRate uart1_br: UART1 baud rate.
typedef enum {
BIT_RATE_9600 = 9600,
BIT_RATE_19200 = 19200,
BIT_RATE_38400 = 38400,
BIT_RATE_57600 = 57600,
Baud rates BIT_RATE_74880 = 74880,
BIT_RATE_115200 = 115200,
BIT_RATE_230400 = 230400,
BIT_RATE_460800 = 460800,
BIT_RATE_921600 = 921600
} UartBautRate;
Return none
7.2.2. uart0_tx_buffer
Return none
7.2.3. uart0_rx_intr_handler
UART0 interrupt processing function. Users can process the received data in this
Function
function.
Return none
7.2.4. uart_div_modify
Return none
Parameter none
Return none
7.3.2. i2c_master_init
Parameter none
Return none
7.3.3. i2c_master_start
Parameter none
Return none
7.3.4. i2c_master_stop
Parameter none
Return none
7.3.5. i2c_master_send_ack
Parameter none
Return none
7.3.6. i2c_master_send_nack
Parameter none
Return none
7.3.7. i2c_master_checkAck
Parameter none
7.3.8. i2c_master_readByte
Parameter none
7.3.9. i2c_master_writeByte
Return none
7.4.1. pwm_init
Function Initialize PWM function, including GPIO selection, period and duty cycle.
void pwm_init(
uint32 period,
Prototype uint8 *duty,
uint32 pwm_channel_num,
uint32 (*pin_info_list)[3])
Return none
uint32 io_info[][3] =
{{PWM_0_OUT_IO_MUX,PWM_0_OUT_IO_FUNC,PWM_0_OUT_IO_NUM},
Example {PWM_1_OUT_IO_MUX,PWM_1_OUT_IO_FUNC,PWM_1_OUT_IO_NUM},
{PWM_2_OUT_IO_MUX,PWM_2_OUT_IO_FUNC,PWM_2_OUT_IO_NUM}};
7.4.2. pwm_start
Function Starts PWM. This function needs to be called after PWM configuration is changed.
Parameter none
Return none
7.4.3. pwm_set_duty
Sets duty cycle of a PWM output. Set the time that high-level signal will last. The
Function range of duty depends on PWM period. Its maximum value of which can be
Period * 1000 /45. For example, for 1-KHz PWM, the duty range is 0 ~ 22222.
uint32 duty: the time that high-level single will last, duty cycle will be (duty*45)/
(period*1000);
Parameter
uint8 channel: PWM channel, which depends on how many PWM channels is
used. In IOT_Demo it depends on #define PWM_CHANNEL.
Return none
7.4.4. pwm_get_duty
Function Get duty cycle of PWM output; duty cycle will be (duty*45)/ (period*1000).
uint8 channel: PWM channel, which depends on how many PWM channels is
Parameter
used. In IOT_Demo it depends on #define PWM_CHANNEL.
7.4.5. pwm_set_period
Function Set PWM period, unit: μs. For example, for 1-KHz PWM, the period is 1000 μs.
Return none
After updating the configuration, pwm_start must be called for the changes to
Note
take effect.
7.4.6. pwm_get_period
Parameter none
7.4.7. get_pwm_version
Parameter none
7.5.1. sdio_slave_init
Parameter none
Return none
7.5.2. sdio_load_data
Function Load data into SDIO buffer, and inform SDIO host to read it.
The length of data that be loaded successfully. If the data length is too long to fit in
Return
SDIO buffer, this API will return 0, which means it failed to load data.
7.5.3. sdio_register_recv_cb
Register a callback which will be called when ESP8266 receives data from the
Function
host through SDIO.
true: Success
Return
false: Failure
A. Appendix
A.1. ESPCONN Programming
For Espressif sample codes, please see:
https://github.com/espressif/esp8266-nonos-sample-code
https://github.com/espressif/esp8266-rtos-sample-code
⚠ Notice:
• ESP8266, working in Station mode, will start client connections when given an IP address of the AP
(the router) it connects to.
• ESP8266, working in SoftAP mode, will start client connections when the devices connected to the
ESP8266 are given IP addresses.
Steps:
1. Initialize espconn parameters according to protocols.
2. Register connect callback function and reconnect callback function.
• Call espconn_regist_connectcb and espconn_regist_reconcb.
⚠ Notice:
• If the ESP8266 is in Station mode, it will start server listening when given an IP address.
Steps:
1. Initialize espconn parameters according to protocols.
2. Register connect callback function and reconnect callback function.
⚠ Notice:
• Parameter arg of callback is the pointer corresponding structure espconn. This pointer may be different
in different callbacks, please do not use this pointer directly to distinguish one from another in multiple
connections. Use remote_ip and remote_port in espconn instead.
• If espconn_connect (or espconn_secure_connect) fails and returns a otherwise value, that means there
is no connection, so it won’t enter any espconn callback.
• Don’t call espconn_disconnect (or espconn_secure_disconnect) to break the TCP connection in any
espconn callback.
• If it is needed, please use system_os_task and system_os_post to trigger the disconnection
(espconn_disconnect or espconn_secure_disconnect).
#include "ets_sys.h"
#include "osapi.h"
#include "user_interface.h"
os_timer_t rtc_test_t;
typedef struct {
uint64 time_acc;
uint32 magic ;
uint32 time_base;
}RTC_TIMER_DEMO;
void rtc_count()
RTC_TIMER_DEMO rtc_time;
if(rtc_time.magic!=RTC_MAGIC){
rtc_time.magic = RTC_MAGIC;
rtc_time.time_acc= 0;
rtc_time.time_base = system_get_rtc_time();
os_printf("==================\r\n");
uint32 rtc_t1,rtc_t2;
uint32 st1,st2;
rtc_t1 = system_get_rtc_time();
st1 = system_get_time();
cal1 = system_rtc_clock_cali_proc();
os_delay_us(300);
st2 = system_get_time();
rtc_t2 = system_get_rtc_time();
cal2 = system_rtc_clock_cali_proc();
os_printf("==================\r\n\r\n");
rtc_time.time_base = rtc_t2;
os_printf("------------------------\r\n");
if(5== (cnt++)){
os_printf("system restart\r\n");
system_restart();
}else{
os_printf("continue ...\r\n");
void user_init(void)
rtc_count();
os_timer_disarm(&rtc_test_t);
os_timer_setfn(&rtc_test_t,rtc_count,NULL);
os_timer_arm(&rtc_test_t,10000,1);
Messages Description
1: power on
boot mode 1: ESP8266 is in UART-down mode (and downloads firmware into flash).
(the first parameter) 3: ESP8266 is in Flash-boot mode (and boots up from flash).
chksum If chksum == csum, it means that flash is correctly read during booting.
(1) After start up, call wifi_set_opmode to enable station mode, and then call
wifi_enable_signaling_measurement to enable signal measurement.
(2) If you need to test 11n or 11b, please call wifi_set_phy_mode to set phy mode first.
Otherwise, it is not necessary to call API as ESP8266 will be in 11g mode by default.
(3) Call wifi_station_connect to connect ESP8266 to the tester.