ESP8266 SDK API Guide

Version 1.1.1

Espressif Systems IOT Team

Copyright (c) 2015
! ! Espressif Systems ! ESP8266 SDK API Guide

Disclaimer and Copyright Notice

Information in this document, including URL references, is subject to change without notice.
THIS DOCUMENT IS PROVIDED AS IS WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY
WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR
PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR
SAMPLE. All liability, including liability for infringement of any proprietary rights, relating to use of
information in this document is disclaimed. No licenses express or implied, by estoppel or otherwise,
to any intellectual property rights are granted herein.
The Wi-Fi Alliance Member Logo is a trademark of the Wi-Fi Alliance.
All trade names, trademarks and registered trademarks mentioned in this document are property of
their respective owners, and are hereby acknowledged.
Copyright © 2015 Espressif Systems Inc. All rights reserved.

Espressif Systems Confidential 2/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

Table of Content
1. Preambles .................................................................................................12

2. Overview ....................................................................................................13

3. Application Programming Interface (APIs)..............................................14

3.1. Timer ........................................................................................................14

1. os_timer_arm ..........................................................................................14
2. os_timer_disarm .....................................................................................15
3. os_timer_setfn ........................................................................................15
4. system_timer_reinit .................................................................................15
5. os_timer_arm_us ....................................................................................16
3.2. System APIs ..........................................................................................16

1. system_restore .......................................................................................16
2. system_restart ........................................................................................17
3. system_init_done_cb ..............................................................................17
4. system_get_chip_id ................................................................................17
5. system_get_vdd33 .................................................................................18
6. system_adc_read ...................................................................................18
7. system_deep_sleep ................................................................................19
8. system_deep_sleep_set_option ..............................................................19
9. system_phy_set_rfoption ........................................................................20
10. system_phy_set_max_tpw ......................................................................21
11. system_phy_set_tpw_via_vdd33 .............................................................21
12. system_set_os_print ...............................................................................21
13. system_print_meminfo ............................................................................22
14. system_get_free_heap_size ....................................................................22
15. system_os_task ......................................................................................22
16. system_os_post .....................................................................................23
17. system_get_time .....................................................................................24
18. system_get_rtc_time ...............................................................................24
19. system_rtc_clock_cali_proc ....................................................................25
20. system_rtc_mem_write ...........................................................................26

Espressif Systems Confidential 3/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
21. system_rtc_mem_read ...........................................................................26
22. system_uart_swap ..................................................................................27
23. system_uart_de_swap ............................................................................27
24. system_get_boot_version .......................................................................28
25. system_get_userbin_addr .......................................................................28
26. system_get_boot_mode .........................................................................28
27. system_restart_enhance .........................................................................29
28. system_update_cpu_freq ........................................................................29
29. system_get_cpu_freq ..............................................................................29
30. system_get_flash_size_map ....................................................................30
31. system_get_rst_info ...............................................................................31
32. os_memset .............................................................................................31
33. os_memcpy ............................................................................................32
34. os_strlen .................................................................................................32
35. os_printf .................................................................................................33
36. os_bzero .................................................................................................33
37. os_delay_us ............................................................................................34
38. os_install_putc1 ......................................................................................34
3.3. SPI Flash Related APIs ..........................................................................34

1. spi_flash_get_id ......................................................................................34
2. spi_flash_erase_sector ............................................................................35
3. spi_flash_write ........................................................................................35
4. spi_flash_read .........................................................................................36
5. system_param_save_with_protect .........................................................36
6. system_param_load ...............................................................................37
3.4. Wi-Fi Related APIs .................................................................................38

1. wifi_get_opmode ....................................................................................38
2. wifi_get_opmode_default ........................................................................39
3. wifi_set_opmode .....................................................................................39
4. wifi_set_opmode_current ........................................................................39
5. wifi_station_get_config ............................................................................40
6. wifi_station_get_config_default ................................................................40
7. wifi_station_set_config ............................................................................41

Espressif Systems Confidential 4/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
8. wifi_station_set_config_current ...............................................................42
9. wifi_station_connect ...............................................................................42
10. wifi_station_disconnect ...........................................................................43
11. wifi_station_get_connect_status .............................................................43
12. wifi_station_scan ....................................................................................44
13. scan_done_cb_t .....................................................................................44
14. wifi_station_ap_number_set ....................................................................45
15. wifi_station_get_ap_info ..........................................................................45
16. wifi_station_ap_change ...........................................................................46
17. wifi_station_get_current_ap_id ................................................................46
18. wifi_station_get_auto_connect ................................................................46
19. wifi_station_set_auto_connect ................................................................47
20. wifi_station_dhcpc_start .........................................................................47
21. wifi_station_dhcpc_stop .........................................................................48
22. wifi_station_dhcpc_status .......................................................................48
23. wifi_station_set_reconnect_policy ...........................................................48
24. wifi_station_get_rssi ................................................................................49
25. wifi_softap_get_config ............................................................................49
26. wifi_softap_get_config_default ................................................................49
27. wifi_softap_set_config .............................................................................50
28. wifi_softap_set_config_current ................................................................50
29. wifi_softap_get_station_num ...................................................................51
30. wifi_softap_get_station_info ....................................................................51
31. wifi_softap_free_station_info ...................................................................51
32. wifi_softap_dhcps_start ..........................................................................52
33. wifi_softap_dhcps_stop ..........................................................................53
34. wifi_softap_set_dhcps_lease ...................................................................53
35. wifi_softap_dhcps_status ........................................................................54
36. wifi_softap_set_dhcps_offer_option ........................................................54
37. wifi_set_phy_mode .................................................................................55
38. wifi_get_phy_mode .................................................................................56
39. wifi_get_ip_info .......................................................................................56
40. wifi_set_ip_info .......................................................................................56

Espressif Systems Confidential 5/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
41. wifi_set_macaddr ....................................................................................57
42. wifi_get_macaddr ...................................................................................58
43. wifi_set_sleep_type .................................................................................58
44. wifi_get_sleep_type .................................................................................59
45. wifi_status_led_install ..............................................................................59
46. wifi_status_led_uninstall ..........................................................................60
47. wifi_set_broadcast_if ...............................................................................60
48. wifi_get_broadcast _if .............................................................................61
49. wifi_set_event_handler_cb ......................................................................61
3.5. Upgrade (FOTA) APIs .............................................................................63

1. system_upgrade_userbin_check .............................................................63
2. system_upgrade_flag_set .......................................................................63
3. system_upgrade_flag_check ...................................................................63
4. system_upgrade_start ............................................................................64
5. system_upgrade_reboot .........................................................................64
3.6. Sniffer Related APIs ...............................................................................65

1. wifi_promiscuous_enable ........................................................................65
2. wifi_promiscuous_set_mac .....................................................................65
3. wifi_set_promiscuous_rx_cb ...................................................................66
4. wifi_get_channel .....................................................................................66
5. wifi_set_channel .....................................................................................66
3.7. smart config APIs ..................................................................................67

1. smartconfig_start ....................................................................................67
2. smartconfig_stop ....................................................................................69
3.8. SNTP APIs ............................................................................................69

1. sntp_setserver ........................................................................................69
2. sntp_getserver ........................................................................................69
3. sntp_setservername ...............................................................................70
4. sntp_getservername ...............................................................................70
5. sntp_init ..................................................................................................70
6. sntp_stop ...............................................................................................71
7. sntp_get_current_timestamp ..................................................................71
8. sntp_get_real_time ..................................................................................71

Espressif Systems Confidential 6/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
9. SNTP Example ......................................................................................72

4. TCP/UDP APIs...........................................................................................74
4.1. Generic TCP/UDP APIs .........................................................................74

1. espconn_delete ......................................................................................74
2. espconn_gethostbyname .......................................................................74
3. espconn_port .........................................................................................75
4. espconn_regist_sentcb ...........................................................................76
5. espconn_regist_recvcb ...........................................................................76
6. espconn_sent_callback ..........................................................................77
7. espconn_recv_callback ...........................................................................77
8. espconn_sent .........................................................................................77
4.2. TCP APIs ...............................................................................................78

1. espconn_accept .....................................................................................78
2. espconn_secure_accept .........................................................................79
3. espconn_regist_time ...............................................................................79
4. espconn_get_connection_info ................................................................80
5. espconn_connect ...................................................................................80
6. espconn_connect_callback .....................................................................81
7. espconn_regist_connectcb .....................................................................81
8. espconn_set_opt ....................................................................................82
9. espconn_clear_opt .................................................................................83
10. espconn_set_keepalive ...........................................................................83
11. espconn_get_keepalive ..........................................................................84
12. espconn_reconnect_callback ..................................................................85
13. espconn_regist_reconcb .........................................................................86
14. espconn_disconnect ...............................................................................86
15. espconn_regist_disconcb .......................................................................87
16. espconn_regist_write_finish ....................................................................87
17. espconn_secure_set_size .......................................................................88
18. espconn_secure_get_size .......................................................................88
19. espconn_secure_connect .......................................................................89
20. espconn_secure_sent .............................................................................89
21. espconn_secure_disconnect ..................................................................90

Espressif Systems Confidential 7/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
22. espconn_tcp_get_max_con ....................................................................90
23. espconn_tcp_set_max_con ....................................................................90
24. espconn_tcp_get_max_con_allow ..........................................................91
25. espconn_tcp_set_max_con_allow ..........................................................91
26. espconn_recv_hold .................................................................................91
27. espconn_recv_unhold .............................................................................92
4.3. UDP APIs ...............................................................................................92

1. espconn_create ......................................................................................92
2. espconn_igmp_join .................................................................................93
3. espconn_igmp_leave ..............................................................................93
4. espconn_dns_setserver ..........................................................................93
4.4. mDNS APIs ...........................................................................................94

1. espconn_mdns_init .................................................................................94
2. espconn_mdns_close .............................................................................95
3. espconn_mdns_server_register ..............................................................95
4. espconn_mdns_server_unregister ...........................................................96
5. espconn_mdns_get_servername ............................................................96
6. espconn_mdns_set_servername ............................................................96
7. espconn_mdns_set_hostname ...............................................................96
8. espconn_mdns_get_hostname ...............................................................97
9. espconn_mdns_disable ..........................................................................97
10. espconn_mdns_enable ...........................................................................97

5. Application Related ..................................................................................99

5.1. AT APIs ..................................................................................................99

1. at_response_ok ......................................................................................99
2. at_response_error ...................................................................................99
3. at_cmd_array_regist ...............................................................................99
4. at_get_next_int_dec ..............................................................................100
5. at_data_str_copy ..................................................................................100
6. at_init ....................................................................................................101
7. at_port_print .........................................................................................101
8. at_set_custom_info ...............................................................................101
9. at_enter_special_state ..........................................................................102

Espressif Systems Confidential 8/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
10. at_leave_special_state ..........................................................................102
11. at_get_version ......................................................................................102
12. at_register_uart_rx_intr ..........................................................................103
13. at_response ..........................................................................................103
14. at_register_response_func ....................................................................104
5.2. Related JSON APIs ..............................................................................105

1. jsonparse_setup ...................................................................................105
2. jsonparse_next .....................................................................................105
3. jsonparse_copy_value ...........................................................................105
4. jsonparse_get_value_as_int ..................................................................106
5. jsonparse_get_value_as_long ...............................................................106
6. jsonparse_get_len .................................................................................106
7. jsonparse_get_value_as_type ...............................................................107
8. jsonparse_strcmp_value .......................................................................107
9. jsontree_set_up ....................................................................................107
10. jsontree_reset .......................................................................................108
11. jsontree_path_name .............................................................................108
12. jsontree_write_int ..................................................................................109
13. jsontree_write_int_array ........................................................................109
14. jsontree_write_string .............................................................................109
15. jsontree_print_next ...............................................................................110
16. jsontree_find_next .................................................................................110

6. Definitions & Structures .........................................................................111

6.1. Timer ....................................................................................................111

6.2. WiFi Related Structures .......................................................................111

1. Station Related .....................................................................................111

2. soft-AP related ....................................................................................111
3. scan related ..........................................................................................112
4. WiFi event related structure ...................................................................112
5. smart config structure ...........................................................................115
6.3. JSON Related Structure ......................................................................115

1. json structure ........................................................................................115

2. json macro definition .............................................................................116

Espressif Systems Confidential 9/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
6.4. espconn parameters ............................................................................117

1. callback function ...................................................................................117

2. espconn ...............................................................................................117
6.5. interrupt related definition ....................................................................119

7. Peripheral Related Drivers .....................................................................122

7.1. GPIO Related APIs ..............................................................................122

1. PIN Related Macros ..............................................................................122

2. gpio_output_set ....................................................................................122
3. GPIO input and output macro ...............................................................123
4. GPIO interrupt .....................................................................................123
5. gpio_pin_intr_state_set .........................................................................123
6. GPIO Interrupt Handler .........................................................................124
7.2. UART Related APIs ..............................................................................124

1. uart_init .................................................................................................124
2. uart0_tx_buffer ......................................................................................125
3. uart0_rx_intr_handler ............................................................................125
7.3. I2C Master Related APIs .....................................................................126

1. i2c_master_gpio_init .............................................................................126
2. i2c_master_init ......................................................................................126
3. i2c_master_start ...................................................................................126
4. i2c_master_stop ...................................................................................127
5. i2c_master_send_ack ...........................................................................127
6. i2c_master_send_nack .........................................................................127
7. i2c_master_checkAck ...........................................................................127
8. i2c_master_readByte ............................................................................128
9. i2c_master_writeByte ............................................................................128
7.4. PWM Related .......................................................................................128

1. pwm_init ...............................................................................................128
2. pwm_start ............................................................................................129
3. pwm_set_duty ......................................................................................130
4. pwm_get_duty ......................................................................................130
5. pwm_set_period ..................................................................................130
6. pwm_get_period ..................................................................................131

Espressif Systems Confidential 10/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
7. get_pwm_version ................................................................................131

8. Appendix..................................................................................................132
8.1. ESPCONN Programming .....................................................................132

1. TCP Client Mode ..................................................................................132

2. TCP Server Mode .................................................................................132
3. espconn callback .................................................................................133
8.2. RTC APIs Example ..............................................................................133

8.3. Sniffer Structure Introduction ..............................................................135

8.4. ESP8266 soft-AP and station channel configuration ..........................139

Espressif Systems Confidential 11/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

1. Preambles
ESP8266 WiFi SoC offers a complete and self-contained Wi-Fi networking solution; it can be used to
host the application or to offload Wi-Fi networking functions from another application processor.
When ESP8266 hosts the application, it boots up directly from an external flash. In has integrated
cache to improve the performance of the system in such applications. Alternately, serving as a Wi-Fi
adapter, wireless internet access can be added to any microcontroller-based design with simple
connectivity through UART interface or the CPU AHB bridge interface.
ESP8266EX is amongst the most integrated WiFi chip in the industry; it integrates the antenna
switches, RF balun, power amplifier, low noise receive amplifier, filters, power management modules,
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, besides the Wi-Fi functionalities. ESP8266EX is often integrated with external
sensors and other application specific devices through its GPIOs; codes for such applications are
provided in examples in the SDK.
Sophisticated system-level features include fast sleep/wake context switching for energy-efficient
VoIP, adaptive radio biasing for low-power operation, advance signal processing, and spur
cancellation and radio co-existence features for common cellular, Bluetooth, DDR, LVDS, LCD
interference mitigation.
The SDK based on ESP8266 IoT platform offers users an easy, fast and efficient way to develop IoT
devices. This programming guide provides overview of the SDK as well as details on the API. It is
written for embedded software developers to help them program on ESP8266 IoT platform.

Espressif Systems Confidential 12/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

2. Overview
The SDK provides a set of interfaces for data receive and transmit functions over the Wi-Fi and TCP/
IP layer so programmers can focus on application development on the high level. Users can easily
make use of the corresponding interfaces to realize data receive and transmit.
All networking functions on the ESP8266 IoT platform are realized in the library, and are not
transparent to users. Instead, users can initialize the interface in user_main.c.
void user_init(void) is the default method provided. Users can add functions like firmware
initialization, network parameters setting, and timer initialization in the interface.
void user_rf_pre_init(void) need to be added in user_main.c since SDK_v1.1.0, refer to
IOT_Demo. It is provided for RF initialization. User can call system_phy_set_rfoption to set RF
option in user_rf_pre_init. If RF is disable, ESP8266 station and soft-AP are both disabled.
The SDK provides APIs to handle JSON, and users can also use self-defined data types to handle the
them.

Notice：
• Using non-OS SDK which is single-threaded, any task should not occupy CPU too long；

‣ If a task occupied CPU for a long time, ESP8266 can't feed the dog, will cause a watchdog
reset；

‣ Task should not occupy CPU more than 10 ms, otherwise may cause Wi-Fi connection
break.
• We suggest to use a timer to check periodically.
• Using non-OS SDK, please don’t call any function defined with ICACHE_FLASH_ATTR in
interrupt handler.
• We suggest to use RTOS SDK, RTOS can schedule different tasks.

Espressif Systems Confidential 13/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

3. Application Programming Interface (APIs)

3.1. Timer
Timer APIs can be found: /esp_iot_sdk/include/osapi.h. Please be noted that os_timer APIs
listed below are software timer, they are executed in task, so timer callback may not be precisely
executed at the right time, it depends on priority. If you need a precise timer, please use hardware
timer which will be executed in hardware interrupt, 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).

1. os_timer_arm
Function: 

Enable a millisecond timer.

Prototype:

void os_timer_arm (

ETSTimer *ptimer, 

uint32_t milliseconds, 

bool repeat_flag

)

Parameters:

ETSTimer *ptimer : Timer structure

uint32_t milliseconds : Timing, Unit: millisecond

‣ if called system_timer_reinit, the maximum value allowed to input is

0x41893

‣ if didn’t call system_timer_reinit, the maximum value allowed to input

is 0xFFFFFFF

bool repeat_flag : Whether the timer will be invoked repeatedly or not

Return:

null

Espressif Systems Confidential 14/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
2. os_timer_disarm
Function: 

Disarm timer

Prototype:

void os_timer_disarm (ETSTimer *ptimer)

Parameters:

ETSTimer *ptimer : Timer structure

Return:

null

3. os_timer_setfn
Function: 

Set timer callback function.

For enabled timer, timer callback has to be set.

Prototype:

void os_timer_setfn(

ETSTimer *ptimer, 

ETSTimerFunc *pfunction, 

void *parg

)

Parameters:

ETSTimer *ptimer : Timer structure

TESTimerFunc *pfunction : timer callback function

void *parg : callback function parameter

Return:

null

4. system_timer_reinit
Function: 

Reinitiate the timer when you need to use microsecond timer

Notes: 

1. Define USE_US_TIMER;

2. Put system_timer_reinit at the beginning of user_init , in the first
sentence.

Prototype:

void system_timer_reinit (void)

Espressif Systems Confidential 15/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameters:

null

Return:

null

5. os_timer_arm_us
Function: 

Enable a microsecond timer.

Notes: 

1. Define USE_US_TIMER;

2. Put system_timer_reinit at the beginning of user_init , in the first
sentence.

Prototype:

void os_timer_arm_us (

ETSTimer *ptimer, 

uint32_t microseconds, 

bool repeat_flag

)

Parameters:

ETSTimer *ptimer : Timer structure

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:

null

3.2. System APIs

1. system_restore
Function: 

Reset to default settings of following APIs ：wifi_station_set_auto_connect,
wifi_set_phy_mode, wifi_softap_set_config related, wifi_station_set_config
related, wifi_set_opmode, and APs information recorded by #define AP_CACHE

Prototype:

void system_restore(void)

Parameters:

null

Espressif Systems Confidential 16/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

null

2. system_restart
Function: 

Restart

Prototype:

void system_restart(void)

Parameters:

null

Return:

null

3. system_init_done_cb
Function: 

Call this API in user_init to register a system-init-done callback.

Note:

wifi_station_scan has to be called after system init done and station
enable.

Prototype:

void system_init_done_cb(init_done_cb_t cb)

Parameter: 

init_done_cb_t cb : system-init-done callback

Return: 

null

Example: 

void to_scan(void) { wifi_station_scan(null,scan_done); } 

void user_init(void) { 

wifi_set_opmode(STATION_MODE); 

system_init_done_cb(to_scan); 

}

4. system_get_chip_id
Function: 

Get chip ID

Espressif Systems Confidential 17/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

uint32 system_get_chip_id (void)

Parameters:

null

Return:

Chip ID

5. system_get_vdd33
Function: 

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

Note:

• system_get_vdd33 can only be called when TOUT pin is suspended

• The 107th byte in esp_init_data_default.bin（0〜～127byte）is named as

“vdd33_const“ , when TOUT pin is suspended vdd33_const must be set as
0xFF， that is 255

Prototype: 

uint16 system_get_vdd33(void)

Parameter: 

none

Return: 

power voltage of VDD33, unit：1/1024 V

6. system_adc_read
Function: 

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

Note:

• system_adc_read is only available when wire TOUT pin to external

circuitry，Input Voltage Range restricted to 0 ~ 1.0V.

• The 107th byte in esp_init_data_default.bin(0〜～127byte) is named as

“vdd33_const”, and when wire TOUT pin to external circuitry, the
vdd33_const must be set as real power voltage of VDD3P3 pin 3 and 4.

• The range of operating voltage of ESP8266 is 1.8V~3.6V，the unit of

vdd33_const is 0.1V，so effective value range of vdd33_const is [18,
36].

Espressif Systems Confidential 18/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype: 

uint16 system_adc_read(void)

Parameter: 

none

Return: 

input voltage of TOUT pin 6, unit：1/1024 V

7. system_deep_sleep
Function: 

Configures chip for deep-sleep mode. When the device is in deep-sleep, it
automatically wakes up periodically; the period is configurable. Upon waking
up, the device boots up from user_init.

Note:

• Hardware has to support deep-sleep wake up (XPD_DCDC connects to EXT_RSTB

with 0R).

• system_deep_sleep(0): there is no wake up timer; in order to wakeup,

connect a GPIO to pin RST, the chip will wake up by a falling-edge on
pin RST

Prototype:

void system_deep_sleep(uint32 time_in_us)

Parameters: 

uint32 time_in_us : during the time (us) device is in deep-sleep

Return: 

null

8. system_deep_sleep_set_option
Function: 

Call this API before system_deep_sleep to set what the chip will do when
next deep-sleep wake up.

Prototype: 

bool system_deep_sleep_set_option(uint8 option)

Espressif Systems Confidential 19/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

uint8 option : 

deep_sleep_set_option(0): Radio calibration after deep-sleep wake up depends
on esp_init_data_default.bin（0〜～127byte）byte 108. 

deep_sleep_set_option(1): Radio calibration is done after deep-sleep wake
up; this increases the current consumption.

deep_sleep_set_option(2): No radio calibration after deep-sleep wake up;
this reduces the current consumption.

deep_sleep_set_option(4): Disable RF after deep-sleep wake up, just like
modem sleep; this has the least current consumption; the device is not able
to transmit or receive data after wake up.

Return: 

true : succeed

false : fail

9. system_phy_set_rfoption
Function: 

Enable RF or not. This API can only be called in user_rf_pre_init.

Note: 

Function system_phy_set_rfoption is similar to system_deep_sleep_set_option,
if they are both called, it will disregard system_deep_sleep_set_option
which is called before deep-sleep, and refer to system_phy_set_rfoption
which is called when deep-sleep wake up.

Prototype: 

void system_phy_set_rfoption(uint8 option)

Parameter: 

uint8 option :

system_phy_set_rfoption(0) : Radio calibration after deep-sleep wake up

depends on esp_init_data_default.bin（0〜～127byte）byte 108.

   system_phy_set_rfoption(1) : Radio calibration is done after deep-sleep wake

up; this increases the current consumption.

   system_phy_set_rfoption(2) : No radio calibration after deep-sleep wake up;

this reduces the current consumption.

   system_phy_set_rfoption(4) : Disable RF after deep-sleep wake up, just like

modem sleep; this has the least current consumption; the device is not able
to transmit or receive data after wake up.

Espressif Systems Confidential 20/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

none

10. system_phy_set_max_tpw
Function: 

Set maximum value of RF TX Power, unit ：0.25dBm

Prototype: 

void system_phy_set_max_tpw(uint8 max_tpw)

Parameter: 

uint8 max_tpw : maximum value of RF Tx Power, unit : 0.25dBm, range [0, 82]

it can be set refer to the 34th byte (target_power_qdb_0) of

esp_init_data_default.bin(0〜～127byte)

Return: 

none

11. system_phy_set_tpw_via_vdd33
Function: 

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

Note: 

When TOUT pin is suspended, VDD33 can be got by system_get_vdd33;

When wire TOUT pin to external circuitry, system_get_vdd33 can not be used.

Prototype: 

void system_phy_set_tpw_via_vdd33(uint16 vdd33)

Parameter: 

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

Return: 

none

12. system_set_os_print
Function: 

Turn on/off print logFunction

Prototype:

void system_set_os_print (uint8 onoff)

Parameters:

uint8 onoff

Espressif Systems Confidential 21/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Note:

onoff==0: print function off

onoff==1: print function on

Default: 

print function on

Return:

null

13. system_print_meminfo
Function: 

Print memory information, including data/rodata/bss/heap

Prototype:

void system_print_meminfo (void)

Parameters:

null

Return:

null

14. system_get_free_heap_size
Function: 

Get free heap size

Prototype:

uint32 system_get_free_heap_size(void)

Parameters:

null

Return:

uint32 : available heap size

15. system_os_task
Function: 

Set up tasks

Espressif Systems Confidential 22/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

bool system_os_task(

os_task_t task, 

uint8 prio, 

os_event_t *queue, 

uint8 qlen

)

Parameters:

os_task_t task : task function

uint8 prio : task priority. 3 priorities are supported: 0/1/2; 0 is the
lowest priority. This means only 3 tasks is allowed to set up.

os_event_t *queue : message queue pointer

uint8 qlen : message queue depth

Return: 

true: succeed

false: fail

Example:

#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;

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);

}

16. system_os_post
Function: send message to task

Espressif Systems Confidential 23/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

bool system_os_post (

uint8 prio, 

os_signal_t sig, 

os_param_t par

)

Parameters:

uint8 prio : task priority, corresponding to that you set up

os_signal_t sig : message type

os_param_t par : message parameters

Return: 

true: succeed

false: fail

Referring to the above example:


void task_post(void) {

system_os_post(USER_TASK_PRIO_0, SIG_RX, ‘a’);

}

Printout: 

sig_rx a

17. system_get_time
Function: 

Get system time (us).

Prototype: 

uint32 system_get_time(void)

Parameter: 

null

Return: 

System time in microsecond.

18. system_get_rtc_time
Function: Get RTC time, as denoted by the number of RTC clock periods.

Example: 

If system_get_rtc_time returns 10 (it means 10 RTC cycles), and
system_rtc_clock_cali_proc returns 5.75 (means 5.75us per RTC cycle), then
the real time is 10 x 5.75 = 57.5 us.

Espressif Systems Confidential 24/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Note: 

System time will return to zero because of system_restart, but RTC still
goes on.

• reset by pin EXT_RST : RTC memory won’t change, RTC timer returns to zero

• watchdog reset : RTC memory won’t change, RTC timer won’t change

• system_restart : RTC memory won’t change, RTC timer won’t change

• power on : RTC memory is random value, RTC timer starts from zero

• reset by pin CHIP_EN : RTC memory is random value, RTC timer starts from
zero

Prototype: 

uint32 system_get_rtc_time(void)

Parameter: 

null

Return:

RTC time

19. system_rtc_clock_cali_proc
Function: 

Get RTC clock period.

Note:

RTC clock period has decimal part.

RTC clock period will change according to temperature, so RTC timer is not
very precise.

Prototype: 

uint32 system_rtc_clock_cali_proc(void)

Parameter: 

null

Return: 

RTC clock period (in us), bit11~ bit0 are decimal. ((RTC_CAL * 100)>> 12 )

Note: 

see RTC demo in Appendix.

Espressif Systems Confidential 25/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
20. system_rtc_mem_write
Function: 

During deep sleep, only RTC still working, so maybe we need to save some
user data in RTC memory. Only user data area can be used by user. 

|<--------system data--------->|<-----------------user data--------------->|

| 256 bytes | 512 bytes |

Note: 

RTC memory is 4 bytes aligned for read and write operations. Parameter
des_addr means block number(4 bytes per block). So, if we want to save some
data at the beginning of user data area, des_addr will be 256/4 = 64,
save_size will be data length.

Prototype: 

bool system_rtc_mem_write (

uint32 des_addr, 

void * src_addr, 

uint32 save_size

)

Parameter: 

uint32 des_addr : destination address (block number) in RTC memory,
des_addr >=64

void * src_addr : data pointer.

uint32 save_size : data length ( byte)

Return:

true: succeed

false: fail

21. system_rtc_mem_read
Function: 

Read user data from RTC memory. Only user data area should be accessed by
the user.

|<--------system data--------->|<-----------------user data--------------->|

| 256 bytes | 512 bytes |

Note: 

RTC memory is 4 bytes aligned for read and write operations. Parameter
src_addr means block number(4 bytes per block). So, to read data from the
beginning of user data area, src_addr will be 256/4=64, save_size will be
data length.

Espressif Systems Confidential 26/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

bool system_rtc_mem_read (

uint32 src_addr, 

void * des_addr, 

uint32 save_size

)

Parameter: 

uint32 src_addr : source address (block number) in rtc memory, src_addr >=
64

void * des_addr : data pointer

uint32 save_size : data length, byte

Return:

true: succeed

false: fail

22. system_uart_swap
Function: 

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

Prototype: 

void system_uart_swap (void)

Parameter: 

null

Return: 

null

23. system_uart_de_swap
Function: 

Disable UART0 swap. Use original UART0, not MTCK and MTDO.

Prototype: 

void system_uart_de_swap (void)

Parameter: 

null

Return: 

null

Espressif Systems Confidential 27/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

24. system_get_boot_version
Function: 

Get version info of boot

Prototype: 

uint8 system_get_boot_version (void)

Parameter: 

null

Return: 

Version info of boot.

Note: 

If boot version >= 3 , you could enable boot enhance mode (refer to
system_restart_enhance)

25. system_get_userbin_addr
Function: Get address of the current running user bin (user1.bin or user2.bin).

Prototype: 

uint32 system_get_userbin_addr (void)

Parameter: 

null

Return: 

Start address info of the current running user bin.

26. system_get_boot_mode
Function: Get boot mode.

Prototype: 

uint8 system_get_boot_mode (void)

Parameter: 

null

Return: 

#define SYS_BOOT_ENHANCE_MODE 0

#define SYS_BOOT_NORMAL_MODE 1

Note: 

Enhance boot mode: can load and run FW at any address;

Normal boot mode: can only load and run normal user1.bin (or user2.bin).

Espressif Systems Confidential 28/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
27. system_restart_enhance
Function: 

Restarts system, and enters enhance boot mode.

Prototype: 

bool system_restart_enhance(

uint8 bin_type, 

uint32 bin_addr

)

Parameter: 

uint8 bin_type : type of bin 

#define SYS_BOOT_NORMAL_BIN 0 // user1.bin or user2.bin

#define SYS_BOOT_TEST_BIN 1 // can only be Espressif test bin

uint32 bin_addr : start address of bin file

Return: 

true: succeed

false: Fail

Note: 

SYS_BOOT_TEST_BIN is for factory test during production; you can apply for
the test bin from Espressif Systems.

28. system_update_cpu_freq
Function: 

Set CPU frequency. Default is 80MHz.

Prototype: 

bool system_update_cpu_freq(uint8 freq)

Parameter: 

uint8 freq : CPU frequency

#define SYS_CPU_80MHz 80 

#define SYS_CPU_160MHz 160

Return:

true: succeed

false: fail

29. system_get_cpu_freq
Function: 

Get CPU frequency.

Espressif Systems Confidential 29/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

uint8 system_get_cpu_freq(void)

Parameter: 

null

Return: 

CPU frequency, unit : MHz.

30. system_get_flash_size_map
Function: 

Get current flash size and flash map.

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

Structure：

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,

FLASH_SIZE_32M_MAP_512_512,

FLASH_SIZE_16M_MAP_1024_1024,

FLASH_SIZE_32M_MAP_1024_1024

};

Prototype: 

enum flash_size_map system_get_flash_size_map(void)

Parameter: 

none

Return: 

flash map

Espressif Systems Confidential 30/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
31. system_get_rst_info
Function: 

Get information about current startup.

Structure：

enum rst_reason {
REANSON_DEFAULT_RST = 0, // normal startup by power on
REANSON_WDT_RST = 1, // hardware watch dog reset
// exception reset, GPIO status won’t change
REANSON_EXCEPTION_RST = 2,
// software watch dog reset, GPIO status won’t change
REANSON_SOFT_WDT_RST = 3,
// software restart ,system_restart , GPIO status won’t change
REANSON_SOFT_RESTART = 4,
REANSON_DEEP_SLEEP_AWAKE = 5, // wake up from deep-sleep
};

struct rst_info {
uint32 reason; // enum rst_reason
uint32 exccause;
uint32 epc1;
uint32 epc2;
uint32 epc3;
uint32 excvaddr;
uint32 depc;
};

Prototype: 

struct rst_info* system_get_rst_info(void)

Parameter: 

none

Return: 

Information about startup.

32. os_memset
Function: 

Set value of memory

Espressif Systems Confidential 31/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype: 

os_memset(void *s, int ch, size_t n)

Parameter: 

void *s - pointer of memory

int ch - set value

size_t n - size

Return: 

none

Example：

uint8 buffer[32];

os_memset(buffer, 0, sizeof(buffer));

33. os_memcpy
Function: 

copy memory

Prototype: 

os_memcpy(void *des, void *src, size_t n)

Parameter: 

void *des - pointer of destination

void *src - pointer of source

size_t n - memory size

Return: 

none

Example：

uint8 buffer[4] = {0};

os_memcpy(buffer, “abcd”, 4);

34. os_strlen
Function: 

Get string length

Prototype: 

os_strlen(char *s)

Parameter: 

char *s - string

Espressif Systems Confidential 32/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

string length

Example：

char *ssid = “ESP8266”;

os_memcpy(softAP_config.ssid, ssid, os_strlen(ssid));

35. os_printf
Function: 

print format

Note：

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
os_printf to be output from UART 1.

Prototype: 

os_printf(const char *s)

Parameter: 

const char *s - string

Return: 

none

Example：

os_printf(“SDK version: %s \n”, system_get_sdk_version());

36. os_bzero
Function: 

Set the first n bytes of string p to be 0, include ’\0’

Prototype: 

void os_bzero(void *p, size_t n)

Parameter: 

void *p - pointer of memory need to be set 0

size_t n - length

Return: 

none

Espressif Systems Confidential 33/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
37. os_delay_us
Function: 

Time delay, max : 65535 us

Prototype: 

void os_delay_us(uint16 us)

Parameter: 

uint16 us - time, unit: us

Return: 

none

38. os_install_putc1
Function: 

Register print output function.

Prototype: 

void os_install_putc1(void(*p)(char c))

Parameter: 

void(*p)(char c) - pointer of print function

Return: 

none

Example:

os_install_putc1((void *)uart1_write_char) in uart_init will set os_printf

to be output from UART 1, otherwise, os_printf default output from UART 0.

3.3. SPI Flash Related APIs

1. spi_flash_get_id
Function: 

Get ID info of spi flash

Prototype: 

uint32 spi_flash_get_id (void)

Parameters: 

null

Return: 

SPI flash ID

Espressif Systems Confidential 34/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
2. spi_flash_erase_sector
Function: 

Erase sector in flash

Note: 

More details in document Espressif IOT Flash RW Operation

Prototype: 

SpiFlashOpResult spi_flash_erase_sector (uint16 sec)

Parameters: 

uint16 sec : Sector number, the count starts at sector 0, 4KB per sector.

Return: 

typedef enum{

SPI_FLASH_RESULT_OK,

SPI_FLASH_RESULT_ERR,

SPI_FLASH_RESULT_TIMEOUT

} SpiFlashOpResult;

3. spi_flash_write
Function: 

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

Note: 

More details in document Espressif IOT Flash RW Operation

Prototype: 

SpiFlashOpResult spi_flash_write (

uint32 des_addr, 

uint32 *src_addr, 

uint32 size

)

Parameters: 

uint32 des_addr : destination address in flash.

uint32 *src_addr : source address of the data. 

uint32 size :length of data

Return: 

typedef enum{

SPI_FLASH_RESULT_OK,

SPI_FLASH_RESULT_ERR,

SPI_FLASH_RESULT_TIMEOUT

} SpiFlashOpResult;

Espressif Systems Confidential 35/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
4. spi_flash_read
Function: 

Read data from flash. Flash read/write has to be 4-bytes aligned.

Prototype: 

SpiFlashOpResult spi_flash_read(

uint32 src_addr, 

uint32 * des_addr, 

uint32 size

)

Parameters: 

uint32 src_addr: source address in flash 

uint32 *des_addr: destination address to keep data.

uint32 size: length of data

Return: 

typedef enum {

SPI_FLASH_RESULT_OK,

SPI_FLASH_RESULT_ERR,

SPI_FLASH_RESULT_TIMEOUT

} SpiFlashOpResult;

Example：

uint32 value;

uint8 *addr = (uint8 *)&value;

spi_flash_read(0x3E * SPI_FLASH_SEC_SIZE, (uint32 *)addr, 4);

os_printf("0x3E sec:%02x%02x%02x%02x\r\n", addr[0], addr[1], addr[2],

addr[3]);

5. system_param_save_with_protect
Function: 

Write data into flash with protection. Flash read/write has to be 4-bytes
aligned.

Protection of flash read/write : use 3 sectors (4KBytes per sector) to save

4KB data with protect, sector 0 and sector 1 are data sectors, back up each
other, save data alternately, sector 2 is flag sector, point out which
sector is keeping the latest data, sector 0 or sector 1.

Espressif Systems Confidential 36/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Note: 

More details about protection of flash read/write in document “99A-SDK-
Espressif IOT Flash RW Operation” http://bbs.espressif.com/viewtopic.php?
f=21&t=413

Prototype: 

bool system_param_save_with_protect (

uint16 start_sec, 

void *param, 

uint16 len

)

Parameter: 

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 * 4KB) starts from
flash 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

Return: 

true，succeed；

false，fail

6. system_param_load
Function: 

Read data which saved into flash with protection. Flash read/write has to be
4-bytes aligned.

Protection of flash read/write : use 3 sectors (4KBytes per sector) to save

4KB data with protect, sector 0 and sector 1 are data sectors, back up each
other, save data alternately, sector 2 is flag sector, point out which
sector is keeping the latest data, sector 0 or sector 1.

Note: 

More details about protection of flash read/write in document “99A-SDK-
Espressif IOT Flash RW Operation” http://bbs.espressif.com/viewtopic.php?
f=21&t=413

Prototype: 

bool system_param_load (

uint16 start_sec,

Espressif Systems Confidential 37/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
uint16 offset,
void *param,
uint16 len

)
Parameter: 

uint16 start_sec : start sector (sector 0) of the 3 sectors which used for
flash read/write protection. It can not sector 1 or sector 2.

For example, in IOT_Demo we could use the 3 sectors (3 * 4KB) starts from
flash 0x3D000 for flash read/write protection, so the parameter start_sec is
0x3D, can not be 0x3E or 0x3F.

uint16 offset : offset of data saved in sector


void *param : data pointer

uint16 len : data length, offset + len ≤ 4 * 1024

Return: 

true，succeed；

false，fail

3.4. Wi-Fi Related APIs

wifi_station APIs and other APIs which set/get configuration of ESP8266 station can only be
called if ESP8266 station is enabled.
wifi_softap APIs and other APIs which set/get configuration of ESP8266 soft-AP can only be
called if ESP8266 soft-AP is enabled.
Flash system parameter area is the last 16KB of flash.

1. wifi_get_opmode
Function: 

get WiFi current operating mode

Prototype:

uint8 wifi_get_opmode (void)

Parameters:

null

Return:

WiFi working modes:

0x01: station mode

0x02: soft-AP mode

0x03: station+soft-AP

Espressif Systems Confidential 38/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
2. wifi_get_opmode_default
Function: 

get WiFi operating mode that saved in flash

Prototype:

uint8 wifi_get_opmode_default (void)

Parameters:

null

Return:

WiFi working modes:

0x01: station mode

0x02: soft-AP mode

0x03: station+soft-AP

3. wifi_set_opmode
Function: 

Sets WiFi working mode as station, soft-AP or station+soft-AP, and save it
to flash. Default is soft-AP mode.

Note: 

Versions before esp_iot_sdk_v0.9.2, need to call system_restart() after this
api; after esp_iot_sdk_v0.9.2, need not to restart.

This configuration will be saved in flash system parameter area if changed.

Prototype:

bool wifi_set_opmode (uint8 opmode)

Parameters:

uint8 opmode: WiFi operating modes: 

0x01: station mode

0x02: soft-AP mode

0x03: station+soft-AP

Return:

true: succeed

false: fail

4. wifi_set_opmode_current
Function: 

Sets WiFi working mode as station, soft-AP or station+soft-AP, and won’t
save to flash

Espressif Systems Confidential 39/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

bool wifi_set_opmode_current (uint8 opmode)

Parameters:

uint8 opmode: WiFi operating modes: 

0x01: station mode

0x02: soft-AP mode

0x03: station+soft-AP

Return:

true: succeed

false: fail

5. wifi_station_get_config
Function: 

Get WiFi station current configuration

Prototype:

bool wifi_station_get_config (struct station_config *config)

Parameters:

struct station_config *config : WiFi station configuration pointer

Return:

true: succeed

false: fail

6. wifi_station_get_config_default
Function: 

Get WiFi station configuration that saved in flash

Prototype:

bool wifi_station_get_config_default (struct station_config *config)

Parameters:

struct station_config *config : WiFi station configuration pointer

Return:

true: succeed

false: fail

Espressif Systems Confidential 40/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
7. wifi_station_set_config
Function: 

Set WiFi station configuration, and save it to flash

Note:

• This API can be called only if ESP8266 station is enabled.

• If wifi_station_set_config is called in user_init , there is no need to

call wifi_station_connect after that, ESP8266 will connect to router
automatically; otherwise, need wifi_station_connect to connect.

• In general, station_config.bssid_set need to be 0, otherwise it will

check bssid which is the MAC address of AP.

• This configuration will be saved in flash system parameter area if

changed.

Prototype:

bool wifi_station_set_config (struct station_config *config)

Parameters:

struct station_config *config: WiFi station configuration pointer

Return:

true: succeed

false: fail

Example：

void ICACHE_FLASH_ATTR
user_set_station_config(void)
{
    char ssid[32] = SSID;
    char password[64] = PASSWORD;
    struct station_config stationConf;

    stationConf.bssid_set = 0; //need not check MAC address of AP

   
    os_memcpy(&stationConf.ssid, ssid, 32);
    os_memcpy(&stationConf.password, password, 64);
    wifi_station_set_config(&stationConf);
}
void user_init(void)
{
    wifi_set_opmode(STATIONAP_MODE); //Set softAP + station mode

Espressif Systems Confidential 41/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
    user_set_station_config();
}

8. wifi_station_set_config_current
Function: 

Set WiFi station configuration, won’t save to flash

Note:

• This API can be called only if ESP8266 station is enabled.

• If wifi_station_set_config_current is called in user_init , there is no

need to call wifi_station_connect after that, ESP8266 will connect to
router automatically; otherwise, need wifi_station_connect to connect.

• In general, station_config.bssid_set need to be 0, otherwise it will

check bssid which is the MAC address of AP.

Prototype:

bool wifi_station_set_config_current (struct station_config *config)

Parameters:

struct station_config *config: WiFi station configuration pointer

Return:

true: succeed

false: fail

9. wifi_station_connect
Function: 

To connect WiFi station to AP

Note:

• If ESP8266 has already connected to a router, then we need to call

wifi_station_disconnect first, before calling wifi_station_connect.

• Do not call this API in user_init. This API need to be called after
system initialize done and ESP8266 station enable.

Prototype:

bool wifi_station_connect (void)

Parameters:

null

Espressif Systems Confidential 42/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

true: succeed

false: fail

10. wifi_station_disconnect
Function: 

Disconnects WiFi station from AP

Note：

Do not call this API in user_init. This API need to be called after system
initialize done and ESP8266 station enable.

Prototype:

bool wifi_station_disconnect (void)

Parameters:

null

Return:

true: succeed

false: fail

11. wifi_station_get_connect_status
Function: 

Get connection status of WiFi station to AP

Prototype:

uint8 wifi_station_get_connect_status (void)

Parameters:

null

Return:

enum{

STATION_IDLE = 0,

STATION_CONNECTING,

STATION_WRONG_PASSWORD,

STATION_NO_AP_FOUND,

STATION_CONNECT_FAIL,

STATION_GOT_IP

};

Espressif Systems Confidential 43/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
12. wifi_station_scan
Function: 

Scan all available APs

Note: 

Do not call this API in user_init. This API need to be called after system
initialize done and ESP8266 station enable.

Prototype:

bool wifi_station_scan (struct scan_config *config, scan_done_cb_t cb);

Structure: 

struct scan_config {

uint8 *ssid; // AP’s ssid

uint8 *bssid; // AP’s bssid

uint8 channel; //scan a specific channel

uint8 show_hidden; //scan APs of which ssid is hidden.

};

Parameters:

struct scan_config *config: AP config for scan

if config==null: scan all APs

if config.ssid==null && config.bssid==null && config.channel!=null:

ESP8266 will scan the specific channel.

scan_done_cb_t cb: callback function after scan

Return:

true: succeed

false: fail

13. scan_done_cb_t
Function: 

Callback function for wifi_station_scan

Prototype:

void scan_done_cb_t (void *arg, STATUS status)

Parameters:

void *arg: information of APs that be found, refer to struct bss_info

STATUS status: get status

Return:

null

Espressif Systems Confidential 44/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Example:

wifi_station_scan(&config, scan_done);

static void ICACHE_FLASH_ATTR scan_done(void *arg, STATUS status) {

if (status == OK) {

struct bss_info *bss_link = (struct bss_info *)arg;

bss_link = bss_link->next.stqe_next; //ignore first

...

}

}

14. wifi_station_ap_number_set
Function: 

Sets the number of APs that will be cached for ESP8266 station mode.
Whenever ESP8266 station connects to an AP, it keeps caches a record of this
AP's SSID and password. The cached ID index starts from 0.

Note：

This configuration will be saved in flash system parameter area if changed.

Prototype: 

bool wifi_station_ap_number_set (uint8 ap_number)

Parameters: 

uint8 ap_number: the number of APs can be recorded (MAX: 5)

Return:

true: succeed

false: fail

15. wifi_station_get_ap_info
Function: 

Get information of APs recorded by ESP8266 station.

Prototype: 

uint8 wifi_station_get_ap_info(struct station_config config[])

Parameters: 

struct station_config config[]: information of APs, array size has to be 5.

Return: 

The number of APs recorded.

Example: 

struct station_config config[5];

int i = wifi_station_get_ap_info(config);

Espressif Systems Confidential 45/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
16. wifi_station_ap_change
Function: 

Switch ESP8266 station connection to AP as specified

Prototype: 

bool wifi_station_ap_change (uint8 new_ap_id)

Parameters: 

uint8 new_ap_id : AP’s record id, start counting from 0.

Return:

true: succeed

false: fail

17. wifi_station_get_current_ap_id
Function: 

Get the current record id of AP.

Prototype:

uint8 wifi_station_get_current_ap_id ();

Parameter: 

null

Return: 

The index of the AP, which ESP8266 is currently connected to, in the cached
AP list.

18. wifi_station_get_auto_connect
Function: 

Checks if ESP8266 station mode will connect to AP (which is cached)
automatically or not when it is powered on.

Prototype:

uint8 wifi_station_get_auto_connect(void)

Parameter: 

null

Return: 

0: wil not connect to AP automatically; 

Non-0: will connect to AP automatically.

Espressif Systems Confidential 46/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
19. wifi_station_set_auto_connect
Function: 

Set whether ESP8266 station will connect to AP (which is recorded)
automatically or not when power on. Default to enable auto-connect.

Note: 

Call this API in user_init, it is effective in this current power on; call
it in other place, it will be effective in next power on.

This configuration will be saved in flash system parameter area if changed.

Prototype: 

bool wifi_station_set_auto_connect(uint8 set)

Parameter: 

uint8 set: Automatically connect or not:

0: will not connect automatically

1: to connect automatically

Return:

true: succeed

false: fail

20. wifi_station_dhcpc_start
Function: 

Enable ESP8266 station DHCP client.

Note: 

DHCP default enable.

This configuration interacts with static IP API (wifi_set_ip_info):

If enable DHCP, static IP will be disabled;

If enable static IP, DHCP will be disabled;

This will depend on the last configuration.

Prototype: 

bool wifi_station_dhcpc_start(void)

Parameter: 

null

Return:

true: succeed

false: fail

Espressif Systems Confidential 47/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
21. wifi_station_dhcpc_stop
Function: 

Disable ESP8266 station DHCP client.

Note: 

DHCP default enable.

Prototype: 

bool wifi_station_dhcpc_stop(void)

Parameter: 

null

Return:

true: succeed

false: fail

22. wifi_station_dhcpc_status
Function: Get ESP8266 station DHCP client status.

Prototype: 

enum dhcp_status wifi_station_dhcpc_status(void)

Parameter: 

null

Return: 

enum dhcp_status {

DHCP_STOPPED,

DHCP_STARTED

};

23. wifi_station_set_reconnect_policy
Function:

Set whether reconnect or not when ESP8266 station disconnected from AP

Note：

We suggest to call this API in user_init

This API can only be called when ESP8266 station enable.

Prototype: 

bool wifi_station_set_reconnect_policy(bool set)

Parameter: 

bool set - true, enable reconnect；false，disable reconnect

Espressif Systems Confidential 48/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

true：succeed

false：fail


24. wifi_station_get_rssi
Function:

Get rssi of the AP which ESP8266 station connected to

Prototype: 

sint8 wifi_station_get_rssi(void)

Parameter: 

none

Return:

< 0 ：succeed，return rssi

31 ：fail，return error code

25. wifi_softap_get_config
Function: 

Get WiFi soft-AP current configuration

Prototype:

bool wifi_softap_get_config(struct softap_config *config)

Parameter: 

struct softap_config *config : ESP8266 soft-AP config

Return:

true: succeed

false: fail

26. wifi_softap_get_config_default
Function: 

Get WiFi soft-AP configuration that saved in flash

Prototype:

bool wifi_softap_get_config_default(struct softap_config *config)

Espressif Systems Confidential 49/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

struct softap_config *config : ESP8266 soft-AP config

Return:

true: succeed

false: fail

27. wifi_softap_set_config
Function: 

Set WiFi soft-AP configuration and save it to flash

Note：

• This API can be called only if ESP8266 soft-AP is enabled.

• This configuration will be saved in flash system parameter area if

changed.

• In soft-AP + station mode, ESP8266 soft-AP will adjust its channel

configuration to be as same as ESP8266. More details in appendix or
BBS http://bbs.espressif.com/viewtopic.php?f=10&t=324

Prototype:

bool wifi_softap_set_config (struct softap_config *config)

Parameter: 

struct softap_config *config : WiFi soft-AP configuration pointer

Return:

true: succeed

false: fail

28. wifi_softap_set_config_current
Function: 

Set WiFi soft-AP configuration, won’t save it to flash

Note:

• This API can be called only if ESP8266 soft-AP is enabled.

• In soft-AP + station mode, ESP8266 soft-AP will adjust its channel

configuration to be as same as ESP8266. More details in appendix or
BBS http://bbs.espressif.com/viewtopic.php?f=10&t=324

Prototype:

bool wifi_softap_set_config_current (struct softap_config *config)

Espressif Systems Confidential 50/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

struct softap_config *config : WiFi soft-AP configuration pointer

Return:

true: succeed

false: fail

29. wifi_softap_get_station_num
Function: 

Number count of stations which connected to ESP8266 soft-AP

Prototype: 

uint8 wifi_softap_get_station_num(void)

Parameter: 

none

Return: 

how many stations connected to ESP8266 soft-AP

30. wifi_softap_get_station_info
Function: 

Get connected station devices under soft-AP mode, including MAC and IP

Note:

This API can only be used when ESP8266 soft-AP DHCP enabled.

Prototype: 

struct station_info * wifi_softap_get_station_info(void)

Input Parameters:

null

Return:

struct station_info* : station information structure

31. wifi_softap_free_station_info
Function: 

Frees the struct station_info by calling the wifi_softap_get_station_info
function

Prototype:

void wifi_softap_free_station_info(void)

Espressif Systems Confidential 51/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Input Parameters:

null

Return:

null

Examples 1 (Getting MAC and IP information):


struct station_info * station = wifi_softap_get_station_info();

struct station_info * next_station;

while(station) {

os_printf(bssid : MACSTR, ip : IPSTR/n, 

MAC2STR(station->bssid), IP2STR(&station->ip));

next_station = STAILQ_NEXT(station, next);

os_free(station); // Free it directly

station = next_station;

}

Examples 2 (Getting MAC and IP information):


struct station_info * station = wifi_softap_get_station_info();

while(station){

os_printf(bssid : MACSTR, ip : IPSTR/n, 

MAC2STR(station->bssid), IP2STR(&station->ip));

station = STAILQ_NEXT(station, next);

}

wifi_softap_free_station_info(); // Free it by calling functions

32. wifi_softap_dhcps_start
Function: Enable ESP8266 soft-AP DHCP server.

Note: 

DHCP default enable.

This configuration interacts with static IP API (wifi_set_ip_info):

If enable DHCP, static IP will be disabled;

If enable static IP, DHCP will be disabled;

This will depend on the last configuration.

Prototype: 

bool wifi_softap_dhcps_start(void)

Parameter: 

null

Espressif Systems Confidential 52/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

true: succeed

false: fail

33. wifi_softap_dhcps_stop
Function: Disable ESP8266 soft-AP DHCP server.

Note: DHCP default enable.

Prototype: 

bool wifi_softap_dhcps_stop(void)

Parameter: 

null

Return:

true: succeed

false: fail

34. wifi_softap_set_dhcps_lease
Function: 

Set the IP range that can be got from ESP8266 soft-AP DHCP server.

Note:

This API has to be called during DHCP server disable(wifi_softap_dhcps_stop)

This configuration only take effect on next wifi_softap_dhcps_start, if then

wifi_softap_dhcps_stop is called； user needs to call this API to set IP
range again if needed，then call wifi_softap_dhcps_start to take effect.

Prototype: 

bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please)

Parameter: 

struct dhcps_lease {

struct ip_addr start_ip;

struct ip_addr end_ip;

};

Return:

true: succeed

false: fail

Example:

void dhcps_lease_test(void)
{

Espressif Systems Confidential 53/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
struct dhcps_lease dhcp_lease;
const char* start_ip = “192.168.5.100”;
const char* end_ip = “192.168.5.105”;

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)
{
struct dhcps_lease dhcp_lease;
IP4_ADDR(&dhcp_lease.start_ip, 192, 168, 5, 100);
IP4_ADDR(&dhcp_lease.end_ip, 192, 168, 5, 105);
wifi_softap_set_dhcps_lease(&dhcp_lease);
}

35. wifi_softap_dhcps_status
Function: Get ESP8266 soft-AP DHCP server status.

Prototype: 

enum dhcp_status wifi_softap_dhcps_status(void)

Parameter: 

null

Return: 

enum dhcp_status {

DHCP_STOPPED,

DHCP_STARTED

};

36. wifi_softap_set_dhcps_offer_option
Function:

Set ESP8266 soft-AP DHCP server option.

Structure：

enum dhcps_offer_option{

OFFER_START = 0x00,

OFFER_ROUTER = 0x01,

Espressif Systems Confidential 54/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
OFFER_END

};

Prototype: 

bool wifi_softap_set_dhcps_offer_option(uint8 level, void* optarg)

Parameter: 

uint8 level - OFFER_ROUTER set router option

void* optarg - default to be enable

bit0, 0 disable router information from ESP8266 softAP DHCP server；

bit0, 1 enable router information from ESP8266 softAP DHCP server；

Return:

true : succeed 

false : fail

Example:

uint8 mode = 0；

wifi_softap_set_dhcps_offer_option(OFFER_ROUTER, &mode);


37. wifi_set_phy_mode
Fuction: Set ESP8266 physical mode (802.11b/g/n).

Note: ESP8266 soft-AP only support bg.

Prototype: 

bool wifi_set_phy_mode(enum phy_mode mode)

Parameter: 

enum phy_mode mode : physical mode

enum phy_mode {

PHY_MODE_11B = 1,

PHY_MODE_11G = 2,

PHY_MODE_11N = 3

};

Return: 

true : succeed

false : fail

Espressif Systems Confidential 55/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
38. wifi_get_phy_mode
Function: 

Get ESP8266 physical mode (802.11b/g/n)

Prototype: 

enum phy_mode wifi_get_phy_mode(void)

Parameter: 

null

Return: 

enum phy_mode{

PHY_MODE_11B = 1,

PHY_MODE_11G = 2,

PHY_MODE_11N = 3

};

39. wifi_get_ip_info
Function: 

Get IP info of WiFi station or soft-AP interface

Prototype:

bool wifi_get_ip_info(

uint8 if_index, 

struct ip_info *info

)

Parameters:

uint8 if_index : the interface to get IP info: 0x00 for STATION_IF, 0x01 for
SOFTAP_IF.

struct ip_info *info : pointer to get IP info of a certain interface

Return:

true: succeed

false: fail

40. wifi_set_ip_info
Function: 

Set IP address of ESP8266 station or soft-AP

Note:

To set static IP, please disable DHCP first (wifi_station_dhcpc_stop or

wifi_softap_dhcps_stop):

If enable static IP, DHCP will be disabled;

Espressif Systems Confidential 56/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
If enable DHCP, static IP will be disabled;

Prototype:

bool wifi_set_ip_info(

uint8 if_index, 

struct ip_info *info

)

Prototype: 

uint8 if_index : set station IP or soft-AP IP

#define STATION_IF 0x00

#define SOFTAP_IF 0x01

struct ip_info *info : IP information

Example: 

struct ip_info info;
wifi_station_dhcpc_stop();
wifi_softap_dhcps_stop();


IP4_ADDR(&info.ip, 192, 168, 3, 200);

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();

Return:

true: succeed

false: fail

41. wifi_set_macaddr
Function: 

Sets MAC address

Note: 

Can only be used in user_init.

Espressif Systems Confidential 57/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

bool wifi_set_macaddr(

uint8 if_index, 

uint8 *macaddr

)

Parameter: 

uint8 if_index : set station MAC or soft-AP mac

#define STATION_IF 0x00

#define SOFTAP_IF 0x01

uint8 *macaddr : MAC address

Example: 

char sofap_mac[6] = {0x16, 0x34, 0x56, 0x78, 0x90, 0xab};

char sta_mac[6] = {0x12, 0x34, 0x56, 0x78, 0x90, 0xab};

wifi_set_macaddr(SOFTAP_IF, sofap_mac);

wifi_set_macaddr(STATION_IF, sta_mac);

Return:

true: succeed

false: fail

42. wifi_get_macaddr
Function: get MAC address

Prototype:

bool wifi_get_macaddr(

uint8 if_index, 

uint8 *macaddr

)

Parameter: 

uint8 if_index : set station MAC or soft-AP mac

#define STATION_IF 0x00

#define SOFTAP_IF 0x01

uint8 *macaddr : MAC address

Return:

true: succeed

false: fail

43. wifi_set_sleep_type
Function: 

Sets sleep type for power saving. Set NONE_SLEEP_T to disable power saving.

Espressif Systems Confidential 58/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Note: Default to be Modem sleep.

Prototype: 

bool wifi_set_sleep_type(enum sleep_type type)

Parameters:

enum sleep_type type : sleep type

Return:

true: succeed

false: fail

44. wifi_get_sleep_type
Function: 

Gets sleep type.

Prototype: 

enum sleep_type wifi_get_sleep_type(void)

Parameters: 

null

Return: 

enum sleep_type {

NONE_SLEEP_T = 0;

LIGHT_SLEEP_T,

MODEM_SLEEP_T

};

45. wifi_status_led_install
Function: 

Installs WiFi status LED

Prototype:

void wifi_status_led_install (

uint8 gpio_id, 

uint32 gpio_name, 

uint8 gpio_func

)

Parameter:

uint8 gpio_id : gpio number

uint8 gpio_name : gpio mux name

uint8 gpio_func : gpio function

Espressif Systems Confidential 59/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

null

Example: 

Use GPIO0 as WiFi status LED

#define HUMITURE_WIFI_LED_IO_MUX PERIPHS_IO_MUX_GPIO0_U

#define HUMITURE_WIFI_LED_IO_NUM 0

#define HUMITURE_WIFI_LED_IO_FUNC FUNC_GPIO0

wifi_status_led_install(HUMITURE_WIFI_LED_IO_NUM, 

HUMITURE_WIFI_LED_IO_MUX, HUMITURE_WIFI_LED_IO_FUNC)

46. wifi_status_led_uninstall
Function: Uninstall WiFi status LED

Prototype:

void wifi_status_led_uninstall ()

Parameter: 

null

Return: 

null

47. wifi_set_broadcast_if
Function: 

Set ESP8266 send UDP broadcast from station interface or soft-AP interface,
or both station and soft-AP interfaces. Default to be soft-AP.

Note：

If set broadcast interface to be station only，ESP8266 softAP DHCP server

will be disable.

Prototype: 

bool wifi_set_broadcast_if (uint8 interface)

Parameter: 

uint8 interface : 1:station; 2:soft-AP, 3:station+soft-AP

Return:

true: succeed

false: fail

Espressif Systems Confidential 60/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
48. wifi_get_broadcast _if
Function: 

Get interface which ESP8266 sent UDP broadcast from. This is usually used
when you have STA + soft-AP mode to avoid ambiguity.

Prototype:

uint8 wifi_get_broadcast_if (void)

Parameter: 

null

Return: 

1: station 

2: soft-AP 

3: both station and soft-AP

49. wifi_set_event_handler_cb
Function: 

Register Wi-Fi event handler

Prototype: 

void wifi_set_event_handler_cb(wifi_event_handler_cb_t cb)

Parameter: 

wifi_event_handler_cb_t cb - callback

Return: 

none

Example:

void wifi_handle_event_cb(System_Event_t *evt)

{
os_printf("event %x\n", evt->event);
switch (evt->event) {
case EVENT_STAMODE_CONNECTED:
os_printf("connect to ssid %s, channel %d\n",
evt->event_info.connected.ssid,
evt->event_info.connected.channel);
break;
case EVENT_STAMODE_DISCONNECTED:
os_printf("disconnect from ssid %s, reason %d\n",
evt->event_info.disconnected.ssid,
evt->event_info.disconnected.reason);
break;

Espressif Systems Confidential 61/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
case EVENT_STAMODE_AUTHMODE_CHANGE:
os_printf("mode: %d -> %d\n",
evt->event_info.auth_change.old_mode,
evt->event_info.auth_change.new_mode);
break;
case EVENT_STAMODE_GOT_IP:
os_printf("ip:" IPSTR ",mask:" IPSTR ",gw:" IPSTR,
IP2STR(&evt->event_info.got_ip.ip),
IP2STR(&evt->event_info.got_ip.mask),
IP2STR(&evt->event_info.got_ip.gw));
os_printf("\n");
break;
case EVENT_SOFTAPMODE_STACONNECTED:
os_printf("station: " MACSTR "join, AID = %d\n",
MAC2STR(evt->event_info.sta_connected.mac),
evt->event_info.sta_connected.aid);
break;
case EVENT_SOFTAPMODE_STADISCONNECTED:
os_printf("station: " MACSTR "leave, AID = %d\n",
MAC2STR(evt->event_info.sta_disconnected.mac),
evt->event_info.sta_disconnected.aid);
break;
default:
break;
}
}

void user_init(void)
{
// TODO: add your own code here....
wifi_set_event_hander_cb(wifi_handle_event_cb);
}

Espressif Systems Confidential 62/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
3.5. Upgrade (FOTA) APIs
1. system_upgrade_userbin_check
Function: 

Checks user bin

Prototype:

uint8 system_upgrade_userbin_check()

Parameter:

none

Return:

0x00 : UPGRADE_FW_BIN1, i.e. user1.bin

0x01 : UPGRADE_FW_BIN2, i.e. user2.bin

2. system_upgrade_flag_set
Function: 

Sets upgrade status flag.

Note:

If you using system_upgrade_start to upgrade, this API need not be called.

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.

Prototype:

void system_upgrade_flag_set(uint8 flag)

Parameter: 

uint8 flag:

#define UPGRADE_FLAG_IDLE 0x00

#define UPGRADE_FLAG_START 0x01

#define UPGRADE_FLAG_FINISH 0x02

Return: 

null

3. system_upgrade_flag_check
Function: 

Gets upgrade status flag.

Prototype: 

uint8 system_upgrade_flag_check()

Espressif Systems Confidential 63/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

null

Return: 

#define UPGRADE_FLAG_IDLE 0x00

#define UPGRADE_FLAG_START 0x01

#define UPGRADE_FLAG_FINISH 0x02

4. system_upgrade_start
Function: 

Configures parameters and start upgrade

Prototype:

bool system_upgrade_start (struct upgrade_server_info *server)

Parameters:

struct upgrade_server_info *server : server related parameters

Return:

true: start upgrade

false: upgrade can’t be started.

5. system_upgrade_reboot
Function: reboot system and use new version

Prototype:

void system_upgrade_reboot (void)

Parameters:

none

Return:

none

Espressif Systems Confidential 64/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
3.6. Sniffer Related APIs
1. wifi_promiscuous_enable
Function: 

Enable promiscuous mode for sniffer

Note：

(1)promiscuous mode can only be enabled in station mode.

(2)During promiscuous mode（sniffer），ESP8266 station and soft-AP are disabled.

(3)Before enable promiscuous mode，please call wifi_station_disconnect first

(4)Don’t call any other APIs during sniffer，please call

wifi_promiscuous_enable(0) first.

Prototype:

void wifi_promiscuous_enable(uint8 promiscuous)

Parameter: 

uint8 promiscuous : 

0: disable promiscuous; 

1: enable promiscuous

Return:

null

2. wifi_promiscuous_set_mac
Function: 

Set MAC address filter for sniffer.

Note: 

This filter only be available in the current sniffer phase, if you disable
sniffer and then enable sniffer, you need to set filter again if you need
it.

Prototype: 

void wifi_promiscuous_set_mac(const uint8_t *address)

Parameter: 

const uint8_t *address : MAC address

Return: 

null

Example:

char ap_mac[6] = {0x16, 0x34, 0x56, 0x78, 0x90, 0xab};

Espressif Systems Confidential 65/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
wifi_promiscuous_set_mac(ap_mac);

3. wifi_set_promiscuous_rx_cb
Function: 

Registers an RX callback function in promiscuous mode, which will be called
when data packet is received.

Prototype:

void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb)

Parameter: 

wifi_promiscuous_cb_t cb : callback

Return:

null

4. wifi_get_channel
Function: 

Get channel number for sniffer functions

Prototype:

uint8 wifi_get_channel(void)

Parameters:

null

Return:

Channel number

5. wifi_set_channel
Function: 

Set channel number for sniffer functions

Prototype:

bool wifi_set_channel (uint8 channel)

Parameters: 

uint8 channel : channel number

Return:

true: succeed

false: fail

Espressif Systems Confidential 66/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
3.7. smart config APIs
1. smartconfig_start
Function: 

Start smart configuration mode, to connect ESP8266 station to AP, by
sniffing for special packets from the air, containing SSID and password of
desired AP. You need to broadcast the SSID and password (e.g. from mobile
device or computer) with the SSID and password encoded.

Note:

(1)This api can only be called in station mode.

(2)During smart config，ESP8266 station and soft-AP are disabled.

(3)Can not call smartconfig_start twice before it finish，please call

smartconfig_stop first.

(4)Don’t call any other APIs during smart config, please call smartconfig_stop
first.

Prototype: 

bool smartconfig_start(

sc_type type, 

sc_callback_t cb, 

uint8 log

)

Parameter: 

sc_type type : smart config protocol type: AirKiss or ESP-TOUCH.

sc_callback_t cb : smart config callback; executed when smartconfig status
changed;

parameter status of this callback shows the status of smartconfig：

• if status == SC_STATUS_LINK， parameter void *pdata is a pointer of

struct station_config;

• if status == SC_STATUS_LINK_OVER , parameter void *pdata is a pointer of

mobile phone’s IP address, 4 bytes. This is only available in
ESPTOUCH, otherwise, it is NULL.

• otherwise, parameter void *pdata is NULL.

uint8 log : 1: UART output logs; otherwise: UART only outputs the result.

Return:

true: succeed

false: fail

Espressif Systems Confidential 67/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Example: 

sc_type SC_Type;

void ICACHE_FLASH_ATTR

sc_smartconfig_done(sc_status status, void *pdata)

{
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");
            break;
        case SC_STATUS_LINK:
            os_printf("SC_STATUS_LINK\n");
            struct station_config *sta_conf = pdata;
   
            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 (SC_Type == SC_TYPE_ESPTOUCH) {
uint8 phone_ip[4] = {0};
memcpy(phone_ip, (uint8*)pdata, 4);
printf("Phone ip: %d.%d.%d.%d
\n",phone_ip[0],phone_ip[1],phone_ip[2],phone_ip[3]);
}
            smartconfig_stop();
            break;
    }
}

SC_Type = SC_TYPE_ESPTOUCH;

smartconfig_start(SC_TYPE_ESPTOUCH,smartconfig_done);

Espressif Systems Confidential 68/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
2. smartconfig_stop
Function: 

stop smart config, free the buffer taken by smartconfig_start.

Note: 

Whether connect to AP succeed or not, this API should be called to free
memory taken by smartconfig_start.

Prototype: 

bool smartconfig_stop(void)

Parameter: 

null

Return:

true: succeed

false: fail

3.8. SNTP APIs

1. sntp_setserver
Function: 

Set SNTP server by IP address, support 3 SNTP server at most

Prototype: 

void sntp_setserver(unsigned char idx, ip_addr_t *addr)

Parameter: 

unsigned char idx : SNTP server index， support 3 SNTP server at most（0 ~
2）；index 0 is the main server，index 1 and 2 are as backup. 

ip_addr_t *addr : IP address; users need to ensure that it’s a SNTP server

Return: 

none

2. sntp_getserver
Function: 

Get IP address of SNTP server which set by sntp_setserver

Prototype: 

ip_addr_t sntp_getserver(unsigned char idx)

Parameter: 

unsigned char idx : SNTP server index, support 3 SNTP server at most（0 ~ 2）

Espressif Systems Confidential 69/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

IP address

3. sntp_setservername
Function: 

Set SNTP server by domain name, support 3 SNTP server at most

Prototype: 

void sntp_setservername(unsigned char idx, char *server)

Parameter: 

unsigned char idx : SNTP server index， support 3 SNTP server at most（0 ~
2）；index 0 is the main server，index 1 and 2 are as backup. 

char *server : domain name； users need to ensure that it’s a SNTP server

Return: 

none

4. sntp_getservername
Function: 

Get domain name of SNTP server which set by sntp_setservername

Prototype: 

char * sntp_getservername(unsigned char idx)

Parameter: 

unsigned char idx : SNTP server index， support 3 SNTP server at most（0 ~ 2)

Return: 

domain name

5. sntp_init
Function: 

SNTP initialize

Prototype: 

void sntp_init(void)

Parameter: 

none

Espressif Systems Confidential 70/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

none

6. sntp_stop
Function: 

Stop SNTP

Prototype: 

void sntp_stop(void)

Parameter: 

none

Return: 

none

7. sntp_get_current_timestamp
Function: 

Get current timestamp from basic time（1970.01.01 00：00：00 GMT + 8）,
uint:second

Prototype: 

uint32 sntp_get_current_timestamp()

Parameter: 

none

Return:

time stamp

8. sntp_get_real_time
Function: 

Get real time（GMT + 8）

Prototype: 

char* sntp_get_real_time(long t)

Parameter: 

long t - time stamp

Return:

real time

Espressif Systems Confidential 71/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
9. sntp_set_timezone

Function: 

Set time zone

Prototype: 

bool sntp_set_timezone (sint8 timezone)

Note：

Before call sntp_set_timezone, please call sntp_stop first

Parameter: 

sint8 timezone – time zone，range：-11 ~ 13

Return：

true，succeed；

false，fail

Example：

sntp_stop();

if( true == sntp_set_timezone(-5) ) {

sntp_init();

10. SNTP Example

ip_addr_t *addr = (ip_addr_t *)os_zalloc(sizeof(ip_addr_t));

sntp_setservername(0, ”us.pool.ntp.org”); // set server 0 by domain name

sntp_setservername(1, ”ntp.sjtu.edu.cn”); // set server 1 by domain name

ipaddr_aton(“210.72.145.44”, addr);

sntp_setserver(2, addr); // set server 2 by IP address

sntp_init();

os_free(addr);

uint32 current_stamp;

current_stamp = sntp_get_current_timestamp();

os_printf(“sntp: %d, %s \n”,current_stamp, sntp_get_real_time(current_stamp));

Espressif Systems Confidential 72/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

Espressif Systems Confidential 73/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

4. TCP/UDP APIs
Found in esp_iot_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

4.1. Generic TCP/UDP APIs

1. espconn_delete
Function: 

Delete a transmission.

Note: 

Corresponding creation API : 

TCP: espconn_accept, 

UDP: espconn_create

Prototype:

sint8 espconn_delete(struct espconn *espconn)

Parameter: 

struct espconn *espconn : corresponding connected control block structure

Return: 

0 : succeed

Non-0 : error, return error code ESPCONN_ARG - illegal argument，can’t find
network transmission according to structure espconn

2. espconn_gethostbyname
Function: 

DNS

Espressif Systems Confidential 74/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

err_t espconn_gethostbyname(

struct espconn *pespconn, 

const char *hostname, 

ip_addr_t *addr, 

dns_found_callback found

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

const char *hostname : domain name string pointer

ip_addr_t *addr : IP address

dns_found_callback found : callback

Return:

err_t : ESPCONN_OK - succeed

ESPCONN_INPROGRESS - error code : already connected

ESPCONN_ARG - error code : illegal argument，can’t find network
transmission according to structure espconn

Example as follows. Pls refer to source code of IoT_Demo: 


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;

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);

}

3. espconn_port
Function: get void ports

Prototype:

uint32 espconn_port(void)

Parameter:

null

Espressif Systems Confidential 75/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

uint32 : id of the port you get

4. espconn_regist_sentcb
Function: 

Register data sent function which will be called back when data are
successfully sent.

Prototype:

sint8 espconn_regist_sentcb(

struct espconn *espconn, 

espconn_sent_callback sent_cb

)

Parameters: 

struct espconn *espconn : corresponding connected control block structure

espconn_sent_callback sent_cb : registered callback function

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find network
transmission according to structure espconn

5. espconn_regist_recvcb
Function: 

register data receive function which will be called back when data are
received

Prototype:

sint8 espconn_regist_recvcb(

struct espconn *espconn, 

espconn_recv_callback recv_cb

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

espconn_connect_callback connect_cb : registered callback function

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find network
transmission according to structure espconn

Espressif Systems Confidential 76/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
6. espconn_sent_callback
Function: 

Callback after the data are sent

Prototype:

void espconn_sent_callback (void *arg)

Parameters:

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

Return:

null

7. espconn_recv_callback
Function: 

callback after data are received

Prototype:

void espconn_recv_callback (

void *arg, 

char *pdata, 

unsigned short len

)

Parameters:

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

char *pdata : received data entry parameters

unsigned short len : received data length

Return:

null

8. espconn_sent
Function: 

Send data through WiFi

Note: 

Please call espconn_sent after espconn_sent_callback of the pre-packet.

Espressif Systems Confidential 77/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

sint8 espconn_sent(

struct espconn *espconn, 

uint8 *psent, 

uint16 length

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

uint8 *psent : sent data pointer

uint16 length : sent data length

Return:

0 : succeed

Non-0 : error code

ESPCONN_MEM - Out of memory

ESPCONN_ARG - illegal argument，can’t find network transmission according

to structure espconn

4.2. TCP APIs

TCP APIs act only on TCP connections and do not affect nor apply to UDP connections.

1. espconn_accept
Function: 

Creates a TCP server (i.e. accepts connections.)

Prototype:

sint8 espconn_accept(struct espconn *espconn)

Parameter:

struct espconn *espconn : corresponding connected control block structure

Return:

0 : succeed

Non-0 : error code

ESPCONN_MEM - Out of memory

ESPCONN_ISCONN - Already connected

ESPCONN_ARG - illegal argument，can’t find TCP connection according to

structure espconn

Espressif Systems Confidential 78/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
2. espconn_secure_accept
Function: 

Creates an SSL TCP server.

Note:

(1) Only created one SSL server is allowed，this API can be called only once，
and only one SSL client is allowed to connect.

(2) If SSL encrypted packet size is larger than ESP8266 SSL buffer size
(default 2KB, set by espconn_secure_set_size), SSL connection will fail,
will enter espconn_reconnect_callback

(3) SSL related APIs named as espconn_secure_XXX are different from normal TCP
APIs, so please don’t mixed use. In SSL connection, only espconn_secure_XXX
APIs, espconn_regist_XXX APIs and espconn_port can be used.

Prototype:

sint8 espconn_secure_accept(struct espconn *espconn)

Parameter:

struct espconn *espconn : corresponding connected control block structure

Return:

0 : succeed

Non-0 : error code

ESPCONN_MEM - Out of memory

ESPCONN_ISCONN - Already connected

ESPCONN_ARG - illegal argument，can’t find TCP connection according to

structure espconn

3. espconn_regist_time
Function: 

Register timeout interval of ESP8266 TCP server.

Note:

Call this API after espconn_accept, before listened a TCP connection.

This timeout interval is not very precise, only as reference.


If timeout is set to 0, timeout will be disable and ESP8266 TCP server will
not disconnect TCP clients has stopped communication. This usage of
timeout=0, is deprecated.

Espressif Systems Confidential 79/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

sint8 espconn_regist_time(

struct espconn *espconn, 

uint32 interval, 

uint8 type_flag

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

uint32 interval : timeout interval, unit: second, maximum: 7200 seconds

uint8 type_flag : 0, set all connections; 1, set a single connection

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

4. espconn_get_connection_info
Function: 

Get a connection’s info in TCP multi-connection case

Prototype:

sint8 espconn_get_connection_info(

struct espconn *espconn, 

remot_info **pcon_info, 

uint8 typeflags

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

remot_info **pcon_info : connect to client info

uint8 typeflags : 0, regular server;1, ssl server

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

5. espconn_connect
Function: 

Connect to a TCP server (ESP8266 acting as TCP client).

Prototype:

sint8 espconn_connect(struct espconn *espconn)

Espressif Systems Confidential 80/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameters:

struct espconn *espconn : corresponding connected control block structure

Return:

0 : succeed

Non-0 : error code

ESPCONN_RTE - Routing Problem

ESPCONN_MEM - Out of memory

ESPCONN_ISCONN - Already connected

ESPCONN_ARG - illegal argument，can’t find TCP connection according to

structure espconn

6. espconn_connect_callback
Function: successful listening (ESP8266 as TCP server) or connection (ESP8266
as TCP client) callback, register by espconn_regist_connectcb

Prototype:

void espconn_connect_callback (void *arg)

Parameter:

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

Return:

null

7. espconn_regist_connectcb
Function: 

Register connection function which will be called back under successful TCP
connection

Prototype:

sint8 espconn_regist_connectcb(

struct espconn *espconn, 

espconn_connect_callback connect_cb

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

espconn_connect_callback connect_cb : registered callback function

Espressif Systems Confidential 81/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

8. espconn_set_opt
Function: Set option of TCP connection

Prototype: 

sint8 espconn_set_opt(

struct espconn *espconn, 

uint8 opt

)

Structure：

enum espconn_option{
ESPCONN_START = 0x00，
ESPCONN_REUSEADDR = 0x01，
ESPCONN_NODELAY = 0x02，
ESPCONN_COPY = 0x04，
ESPCONN_KEEPALIVE = 0x08，
ESPCONN_END
}

Parameter: 

struct espconn *espconn : corresponding connected control structure

uint8 opt : Option of TCP connection, refer to espconn_option

bit 0: 1: free memory after TCP disconnection happen need not wait 2
minutes; 

bit 1: 1: disable nagle algorithm during TCP data transmission, quiken the
data transmission. 

bit 2: 1: use 2920 bytes write buffer for the data espconn_sent sending.

bit 3: 1: enable TCP keep alive

Return: 

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

Note:

In general, we need not call this API; 

If call espconn_set_opt, please call it in espconn_connect_callback.

Espressif Systems Confidential 82/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
9. espconn_clear_opt
Function:

Clear option of TCP connection.

Prototype: 

sint8 espconn_clear_opt(

struct espconn *espconn, 

uint8 opt

)

Structure：

enum espconn_option{
ESPCONN_START = 0x00，
ESPCONN_REUSEADDR = 0x01，
ESPCONN_NODELAY = 0x02，
ESPCONN_COPY = 0x04，
ESPCONN_KEEPALIVE = 0x08，
ESPCONN_END
}

Parameters: 

struct espconn *espconn : corresponding connected control block structure

uint8 opt : option of TCP connection,refer to espconn_option

Return: 

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

10. espconn_set_keepalive
Function: 

Set configuration of TCP keep alive .

Prototype: 

sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void*
optarg)

Structure：

enum espconn_level{

ESPCONN_KEEPIDLE,

ESPCONN_KEEPINTVL,

Espressif Systems Confidential 83/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
ESPCONN_KEEPCNT

Parameters: 

struct espconn *espconn : corresponding connected control block structure

uint8 level : Default to do TCP keep-alive detection every ESPCONN_KEEPIDLE,

if there in no response, retry ESPCONN_KEEPCNT times every
ESPCONN_KEEPINTVL. If still no response, considers it as TCP connection
broke, goes into espconn_reconnect_callback .

Notice, keep alive interval is not precise, only for reference, it depends
on priority.

description：

ESPCONN_KEEPIDLE - TCP keep-alive interval，unit：500 millisecond

ESPCONN_KEEPINTVL - packet interval during TCP keep-alive，unit：500

millisecond

ESPCONN_KEEPCNT - maximum packet count of TCP keep-alive

void* optarg ：value of parameter

Return: 

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

Note:

In general, we need not call this API; 

If needed, please call it in espconn_connect_callback and call
espconn_set_opt to enable keep alive first.

11. espconn_get_keepalive
Function: 

Get value of TCP keep-alive parameter

Prototype: 

sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void*
optarg)

Structure：

enum espconn_level{

ESPCONN_KEEPIDLE,

Espressif Systems Confidential 84/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
ESPCONN_KEEPINTVL,

ESPCONN_KEEPCNT

Parameter: 

struct espconn *espconn : corresponding connected control block structure

uint8 level :

ESPCONN_KEEPIDLE - TCP keep-alive interval，unit：500 millisecond

ESPCONN_KEEPINTVL - packet interval during TCP keep-alive，unit：500

millisecond

ESPCONN_KEEPCNT - maximum packet count of TCP keep-alive

void* optarg ：value of parameter

Return: 

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

12. espconn_reconnect_callback
Function:

Enter this callback when error occurred, TCP connection broke. This callback
is registered by espconn_regist_reconcb

Prototype: 

void espconn_reconnect_callback (void *arg, sint8 err)

Parameter: 

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

sint8 err : error code

ESCONN_TIMEOUT - Timeout
ESPCONN_ABRT - TCP connection aborted
ESPCONN_RST - TCP connection abort
ESPCONN_CLSD - TCP connection closed
ESPCONN_CONN - TCP connection
ESPCONN_HANDSHAKE - TCP SSL handshake fail

Espressif Systems Confidential 85/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
ESPCONN_PROTO_MSG - SSL application invalid
Return: 

none

13. espconn_regist_reconcb
Function: 

Register reconnect callback

Note: 

espconn_reconnect_callback is more like a network-broken error handler; it
handles errors that occurred in any phase of the connection. For instance,
if espconn_sent fails, espconn_reconnect_callback will be called because the
network is broken.

Prototype:

sint8 espconn_regist_reconcb(

struct espconn *espconn, 

espconn_reconnect_callback recon_cb

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

espconn_reconnect_callback recon_cb : registered callback function

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

14. espconn_disconnect
Function: 

disconnect a TCP connection

Prototype:

sint8 espconn_disconnect(struct espconn *espconn)

Parameters:

struct espconn *espconn : corresponding connected control structure

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

Espressif Systems Confidential 86/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
15. espconn_regist_disconcb
Function:

Register disconnection function which will be called back under successful

TCP disconnection

Prototype:

sint8 espconn_regist_disconcb(

struct espconn *espconn, 

espconn_connect_callback discon_cb

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

espconn_connect_callback connect_cb : registered callback function

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

16. espconn_regist_write_finish
Function: 

Register a callback which will be called when all sending data is completely
write into write buffer or sent. Need to call espconn_set_opt to enable
write-buffer first.

Note:

write-buffer is used to keep TCP data that waiting for sending, users can
enable it by espconn_set_opt. Then users can call espconn_sent to send next
packet in write_finish_callback instead of espconn_sent_callback.

Prototype:

sint8 espconn_regist_write_finish (

struct espconn *espconn, 

espconn_connect_callback write_finish_fn

)

Parameters:

struct espconn *espconn : corresponding connected control block structure

espconn_connect_callback write_finish_fn : registered callback function

Espressif Systems Confidential 87/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

17. espconn_secure_set_size
Function: 

Set buffer size of encrypted data (SSL)

Note:

Buffer size default to be 2Kbytes. If need to change, please call this API
before espconn_secure_accept (ESP8266 as TCP SSL server) or
espconn_secure_connect (ESP8266 as TCP SSL client)

Prototype:

bool espconn_secure_set_size (uint8 level, uint16 size)

Parameters:

uint8 level : set buffer for ESP8266 SSL server/client：

0x01 SSL client；0x02 SSL server；0x03 SSL client and SSL server

uint16 size : buffer size，range：1 ~ 8192，unit：byte，default to be 2048

Return:

true : succeed

false : fail

18. espconn_secure_get_size
Function: 

Get buffer size of encrypted data (SSL)

Prototype:

sint16 espconn_secure_get_size (uint8 level)

Parameters:

uint8 level : buffer for ESP8266 SSL server/client：

0x01 SSL client；0x02 SSL server；0x03 SSL client and SSL server

Return:

buffer size

Espressif Systems Confidential 88/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
19. espconn_secure_connect
Function: 

Secure connect (SSL) to a TCP server (ESP8266 is acting as TCP client.)

Note:

(1) Only one connection is allowed when ESP8266 as SSL client, this API can be
called only once, or call espconn_secure_disconnect to disconnect first,
then call this API to create another SSL connection.

(2) If SSL encrypted packet size is larger than ESP8266 SSL buffer size
(default 2KB, set by espconn_secure_set_size), SSL connection will fail,
will enter espconn_reconnect_callback

(3) SSL related APIs named as espconn_secure_XXX are different from normal TCP
APIs, so please don’t mixed use. In SSL connection, only espconn_secure_XXX
APIs, espconn_regist_XXX APIs and espconn_port can be used.

Prototype:

sint8 espconn_secure_connect (struct espconn *espconn)

Parameters:

struct espconn *espconn : corresponding connected control block structure

Return:

0 : succeed

Non-0 : error code

ESPCONN_MEM - Out of memory

ESPCONN_ISCONN - Already connected

ESPCONN_ARG - illegal argument，can’t find TCP connection

according to structure espconn

20. espconn_secure_sent
Function: send encrypted data (SSL)

Note:

Please call espconn_secure_sent after espconn_sent_callback of the pre-packet.

Prototype:

sint8 espconn_secure_sent (

struct espconn *espconn, 

uint8 *psent, 

uint16 length

)

Espressif Systems Confidential 89/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameters:

struct espconn *espconn : corresponding connected control block structure

uint8 *psent : sent data pointer

uint16 length : sent data length

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

21. espconn_secure_disconnect
Function: secure TCP disconnection(SSL)

Prototype:

sint8 espconn_secure_disconnect(struct espconn *espconn)

Parameters:

struct espconn *espconn : corresponding connected control block structure

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

22. espconn_tcp_get_max_con
Function: 

Get maximum number of how many TCP connection is allowed.

Prototype: 

uint8 espconn_tcp_get_max_con(void)

Parameter: 

null

Return: 

Maximum number of how many TCP connection is allowed.

23. espconn_tcp_set_max_con
Function: 

Set the maximum number of how many TCP connection is allowed.

Prototype: 

sint8 espconn_tcp_set_max_con(uint8 num)

Espressif Systems Confidential 90/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

uint8 num : Maximum number of how many TCP connection is allowed.

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

24. espconn_tcp_get_max_con_allow
Function: 

Get the maximum number of TCP clients which are allowed to connect to
ESP8266 TCP server.

Prototype: 

sint8 espconn_tcp_get_max_con_allow(struct espconn *espconn)

Parameter:

struct espconn *espconn : corresponding connected control structure

Return:

> 0 : Maximum number of TCP clients which are allowed.

< 0 : error code ESPCONN_ARG - illegal argument，can’t find TCP connection

according to structure espconn

25. espconn_tcp_set_max_con_allow
Function: 

Set the maximum number of TCP clients allowed to connect to ESP8266 TCP
server.

Prototype: 

sint8 espconn_tcp_set_max_con_allow(struct espconn *espconn, uint8 num)

Parameter:

struct espconn *espconn : corresponding connected control structure

uint8 num : Maximum number of TCP clients which are allowed.

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

26. espconn_recv_hold
Function: 

Puts in a request to block the TCP receive function.

Espressif Systems Confidential 91/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Note: 

The function does not act immediately; we recommend calling it while
reserving 5*1460 bytes of memory. 

This API can be called more than once.

Prototype: 

sint8 espconn_recv_hold(struct espconn *espconn)

Parameter:

struct espconn *espconn : corresponding connected control structure

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

27. espconn_recv_unhold
Function: 

Unblock TCP receiving data (i.e. undo espconn_recv_hold).

Note: 

This API takes effect immediately.

Prototype: 

sint8 espconn_recv_unhold(struct espconn *espconn)

Parameter:

struct espconn *espconn : corresponding connected control structure

Return:

0 : succeed

Non-0 : error code ESPCONN_ARG - illegal argument，can’t find TCP
connection according to structure espconn

4.3. UDP APIs

1. espconn_create
Function: create UDP transmission.

Prototype: 

sin8 espconn_create(struct espconn *espconn)

Parameter: 

struct espconn *espconn : corresponding connected control block structure

Espressif Systems Confidential 92/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

0 : succeed

Non-0 : error code

ESPCONN_ISCONN - Already connected

ESPCONN_MEM - Out of memory

ESPCONN_ARG - illegal argument，can’t find UDP transmission according to

structure espconn

2. espconn_igmp_join
Function: 

Join a multicast group

Prototype: 

sint8 espconn_igmp_join(ip_addr_t *host_ip, ip_addr_t *multicast_ip)

Parameters: 

ip_addr_t *host_ip : IP of host 

ip_addr_t *multicast_ip : IP of multicast group

Return: 

0 : succeed

Non-0 : error code ESPCONN_MEM - Out of memory

3. espconn_igmp_leave
Function: 

Quit a multicast group

Prototype: 

sint8 espconn_igmp_leave(ip_addr_t *host_ip, ip_addr_t *multicast_ip)

Parameters: 

ip_addr_t *host_ip : IP of host

ip_addr_t *multicast_ip : IP of multicast group

Return: 

0 : succeed

Non-0 : error code ESPCONN_MEM - Out of memory

4. espconn_dns_setserver
Function: 

Set default DNS server. Two DNS server is allowed to be set.

Note：

Espressif Systems Confidential 93/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Only if ESP8266 DHCP client is disabled (wifi_station_dhcpc_stop), this API
can be used

Prototype: 

void espconn_dns_setserver(char numdns, ip_addr_t *dnsserver)

Parameter: 

char numdns : DNS server ID，0 or 1

ip_addr_t *dnsserver : DNS server IP

Return: 

none

4.4. mDNS APIs

1. espconn_mdns_init
Function: 

mDNS initialization

Note：

（1）Only ESP8266 station support mDNS, please get IP address of ESP8266

station first，then call this API to initial mDNS；

（2）txt_data has to be set as “ key = value ”，as Example；

Structure: 

struct mdns_info{

char *host_name;

char *server_name;

uint16 server_port;

unsigned long ipAddr;

char *txt_data[10];

};

Prototype: 

void espconn_mdns_init(struct mdns_info *info)

Parameter: 

struct mdns_info *info : mdns information

Espressif Systems Confidential 94/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

none

Example：

struct mdns_info *info = (struct mdns_info *)os_zalloc(sizeof(struct

mdns_info));

info->host_name = “espressif”;

info->ipAddr = station_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);

2. espconn_mdns_close
Function: 

close mDNS, corresponding creation API : espconn_mdns_init

Prototype: 

void espconn_mdns_close(void)

Parameter: 

none

Return: 

none

3. espconn_mdns_server_register
Function: 

register mDNS server

Prototype: 

void espconn_mdns_server_register(void)

Parameter: 

none

Return: 

none

Espressif Systems Confidential 95/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
4. espconn_mdns_server_unregister
Function: 

unregister mDNS server

Prototype: 

void espconn_mdns_server_unregister(void)

Parameter: 

none

Return: 

none

5. espconn_mdns_get_servername
Function: 

Get mDNS server name

Prototype: 

char* espconn_mdns_get_servername(void)

Parameter: 

none

Return: 

server name

6. espconn_mdns_set_servername
Function: 

Set mDNS server name

Prototype: 

void espconn_mdns_set_servername(const char *name)

Parameter: 

const char *name - server name

Return: 

none

7. espconn_mdns_set_hostname
Function: 

Set mDNS host name

Prototype: 

void espconn_mdns_set_hostname(char *name)

Espressif Systems Confidential 96/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

char *name - host name

Return: 

none

8. espconn_mdns_get_hostname
Function: 

Get mDNS host name

Prototype: 

char* espconn_mdns_get_hostname(void)

Parameter: 

none

Return: 

host name

9. espconn_mdns_disable
Function: 

Disable mDNS , corresponding creation API : espconn_mdns_enable

Prototype: 

void espconn_mdns_disable(void)

Parameter: 

none

Return: 

none

10. espconn_mdns_enable
Function: 

Enable mDNS

Prototype: 

void espconn_mdns_enable(void)

Parameter: 

none

Return: 

none

Espressif Systems Confidential 97/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

Espressif Systems Confidential 98/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

5. Application Related

5.1. AT APIs
for AT APIs examples, refer to esp_iot_sdk/examples/at/user/user_main.c.

1. at_response_ok
Function: 

Output OK to AT Port (UART0)

Prototype: 

void at_response_ok(void)

Parameter: 

null

Return: 

null

2. at_response_error
Function: 

output ERROR to AT Port (UART0)

Prototype: 

void at_response_error(void)

Parameter: 

null

Return: 

null

3. at_cmd_array_regist
Function: 

register user-define AT commands.

Can be called only once to register all user-define AT commands.

Prototype: 

void at_cmd_array_regist (

at_function * custom_at_cmd_arrar, 

uint32 cmd_num

)

Espressif Systems Confidential 99/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

at_function * custom_at_cmd_arrar : Array of user-define AT commands

uint32 cmd_num : Number counts of user-define AT commands

Return: 

null

Example: 

refer to esp_iot_sdk/examples/at/user/user_main.c

4. at_get_next_int_dec
Function: 

parse int from AT command

Prototype: 

bool at_get_next_int_dec (char **p_src,int* result,int* err)

Parameter: 

char **p_src : *p_src is the AT command that need to be parsed

int* result : int number parsed from the AT command

int* err : 1: no number is found; 3: only ’-’ is found.

Return: 

true: parser succeeds (NOTE: if no number is found, it will return True,
but returns error code 1) 

false: parser is unable to parse string; some probable causes are: int
number more than 10 bytes; string contains termination characters '/r';
string contains only '-'.

Example: 

refer to esp_iot_sdk/examples/at/user/user_main.c

5. at_data_str_copy
Function: parse string from AT command

Prototype: 

int32 at_data_str_copy (char * p_dest, char ** p_src,int32 max_len)

Parameter: 

char * p_dest : string parsed from the AT command

char ** p_src : *p_src is the AT command that need to be parsed

int32 max_len : max string length that allowed

Espressif Systems Confidential 100/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return: 

length of string:

>=0: succeed and returns the length of the string

<0 : fail and returns -1

Example: 

refer to esp_iot_sdk/examples/at/user/user_main.c

6. at_init
Function: 

AT initialize

Prototype: 

void at_init (void)

Parameter: 

null

Return: 

null

Example: 

refer to esp_iot_sdk/examples/at/user/user_main.c

7. at_port_print
Function: 

output string to AT PORT(UART0)

Prototype: 

void at_port_print(const char *str)

Parameter: 

const char *str : string that need to output

Return: 

null

Example: 

refer to esp_iot_sdk/examples/at/user/user_main.c

8. at_set_custom_info
Function: 

User-define version info of AT which can be got by AT+GMR.

Prototype: 

void at_set_custom_info (char *info)

Espressif Systems Confidential 101/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

char *info : version info

Return: 

null

9. at_enter_special_state
Function: 

Enter processing state. In processing state, AT core will return busy for
any further AT commands.

Prototype: 

void at_enter_special_state (void)

Parameter: 

null

Return: 

null

10. at_leave_special_state
Function: 

Exit from AT processing state.

Prototype: 

void at_leave_special_state (void)

Parameter: 

null

Return: 

null

11. at_get_version
Function: 

Get Espressif AT lib version.

Prototype: 

uint32 at_get_version (void)

Parameter: 

null

Return: 

Espressif AT lib version

Espressif Systems Confidential 102/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
12. at_register_uart_rx_intr
Function: 

Set UART0 to be used by user or AT commands.

Note:

This API can be called multiple times.

Running AT，UART0 default to be used by AT commands.

Prototype: 

void at_register_uart_rx_intr(at_custom_uart_rx_intr rx_func)

Parameter: 

at_custom_uart_rx_intr : register a UART0 RX interrupt handler so that
UART0 can be used by the customer, while if it’s NULL, UART0 is assigned to
AT commands.

Return: 

null

Example:

void user_uart_rx_intr(uint8* data, int32 len)

{
// UART0 rx for user
os_printf(“len=%d \r\n”,len);
os_printf(data);

// change UART0 for AT

at_register_uart_rx_intr(NULL);
}
void user_init(void){ at_register_uart_rx_intr(user_uart_rx_intr); }

13. at_response
Function: 

Set AT response

Note：

at_response outputs from UART0 TX by default which is same as at_port_print.

But if called at_register_response_func, the string of at_response will be
the parameter of response_func, users can define their own behavior.

Prototype: 

void at_response (const char *str)

Espressif Systems Confidential 103/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameter: 

const char *str : string

Return: 

none

14. at_register_response_func
Function: 

Register callback of at_response for user-define response. After called
at_register_response_func, the string of at_response will be the parameter
of response_func, users can define their own behavior.

Prototype: 

void at_register_response_func (at_custom_response_func_type response_func)

Parameter: 

at_custom_response_func_type : callback of at_response

Return: 

none

Espressif Systems Confidential 104/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
5.2. Related JSON APIs
Found in : esp_iot_sdk/include/json/jsonparse.h & jsontree.h

1. jsonparse_setup
Function:

json initialize parsing

Prototype:

void jsonparse_setup(

struct jsonparse_state *state, 

const char *json, 

int len

)

Parameters:

struct jsonparse_state *state : json parsing pointer

const char *json : json parsing character string

int len : character string length

Return:

null

2. jsonparse_next
Function: 

Returns jsonparse next object

Prototype:

int jsonparse_next(struct jsonparse_state *state)

Parameters:

struct jsonparse_state *state : json parsing pointer

Return:

int : parsing result

3. jsonparse_copy_value
Function: 

Copies current parsing character string to a certain buffer

Espressif Systems Confidential 105/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

int jsonparse_copy_value(

struct jsonparse_state *state, 

char *str, 

int size

)

Parameters:

struct jsonparse_state *state : json parsing pointer

char *str : buffer pointer

int size : buffer size

Return:

int : copy result

4. jsonparse_get_value_as_int
Function: 

Parses json to get integer

Prototype:

int jsonparse_get_value_as_int(struct jsonparse_state *state)

Parameters:

struct jsonparse_state *state : json parsing pointer

Return:

int : parsing result

5. jsonparse_get_value_as_long
Function: 

Parses json to get long integer

Prototype:

long jsonparse_get_value_as_long(struct jsonparse_state *state)

Parameters:

struct jsonparse_state *state : json parsing pointer

Return:

long : parsing result

6. jsonparse_get_len
Function: 

Gets parsed json length

Espressif Systems Confidential 106/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

int jsonparse_get_value_len(struct jsonparse_state *state)

Parameters:

struct jsonparse_state *state : json parsing pointer

Return:

int : parsed jason length

7. jsonparse_get_value_as_type
Function: 

Parses json data type

Prototype:

int jsonparse_get_value_as_type(struct jsonparse_state *state)

Parameters:

struct jsonparse_state *state : json parsing pointer

Return:

int : parsed json data type

8. jsonparse_strcmp_value
Function: 

Compares parsed json and certain character string

Prototype:

int jsonparse_strcmp_value(struct jsonparse_state *state, const char *str)

Parameters:

struct jsonparse_state *state : json parsing pointer

const char *str : character buffer

Return:

int : comparison result

9. jsontree_set_up
Function: 

Creates json data tree

Espressif Systems Confidential 107/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

void jsontree_setup(

struct jsontree_context *js_ctx, 

struct jsontree_value *root, 

int (* putchar)(int)

)

Parameters:

struct jsontree_context *js_ctx : json tree element pointer

struct jsontree_value *root : root element pointer

int (* putchar)(int) : input function

Return:

null

10. jsontree_reset
Function: 

Resets json tree

Prototype:

void jsontree_reset(struct jsontree_context *js_ctx)

Parameters:

struct jsontree_context *js_ctx : json data tree pointer

Return:

null

11. jsontree_path_name
Function: 

get json tree parameters

Prototype:

const char *jsontree_path_name(

const struct jsontree_cotext *js_ctx, 

int depth

)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

int depth : json tree depth

Return:

char* : parameter pointer

Espressif Systems Confidential 108/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
12. jsontree_write_int
Function: 

write integer to json tree

Prototype:

void jsontree_write_int(

const struct jsontree_context *js_ctx, 

int value

)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

int value : integer value

Return:

null

13. jsontree_write_int_array
Function: 

Writes integer array to json tree

Prototype:

void jsontree_write_int_array(

const struct jsontree_context *js_ctx, 

const int *text, 

uint32 length

)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

int *text : array entry address

uint32 length : array length

Return:

null

14. jsontree_write_string
Function: 

Writes string to json tree

Espressif Systems Confidential 109/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

void jsontree_write_string(

const struct jsontree_context *js_ctx, 

const char *text

)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

const char* text : character string pointer

Return:

null

15. jsontree_print_next
Function: 

json tree depth

Prototype:

int jsontree_print_next(struct jsontree_context *js_ctx)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

Return:

int : json tree depth

16. jsontree_find_next
Function: 

find json tree element

Prototype:

struct jsontree_value *jsontree_find_next(

struct jsontree_context *js_ctx, 

int type

)

Parameters:

struct jsontree_context *js_ctx : json tree pointer

int : type

Return:

struct jsontree_value * : json tree element pointer

Espressif Systems Confidential 110/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

6. Definitions & Structures

6.1. Timer
typedef void ETSTimerFunc(void *timer_arg);
typedef struct _ETSTIMER_ {
struct _ETSTIMER_ *timer_next;
uint32_t timer_expire;
uint32_t timer_period;
ETSTimerFunc *timer_func;
void *timer_arg;
} ETSTimer;

6.2. WiFi Related Structures

1. Station Related
struct station_config {

uint8 ssid[32];

uint8 password[64];

uint8 bssid_set;

uint8 bssid[6];

};

Note:

BSSID as MAC address of AP, 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.

2. soft-AP related
typedef enum _auth_mode {
AUTH_OPEN = 0,
AUTH_WEP,
AUTH_WPA_PSK,
AUTH_WPA2_PSK,
AUTH_WPA_WPA2_PSK
} AUTH_MODE;
struct softap_config {

Espressif Systems Confidential 111/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
uint8 ssid[32];
uint8 password[64];
uint8 ssid_len;
uint8 channel; // support 1 ~ 13
uint8 authmode; // Don’t support AUTH_WEP in soft-AP mode
uint8 ssid_hidden; // default 0
uint8 max_connection; // default 4, max 4
uint16 beacon_interval; // 100 ~ 60000 ms, default 100
};

Note:

If softap_config.ssid_len==0, check ssid till find a termination characters;
otherwise, it depends on softap_config.ssid_len.

3. scan related
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;
u8 bssid[6];
u8 ssid[32];
u8 channel;
s8 rssi;
u8 authmode;
uint8 is_hidden; // SSID of current AP is hidden or not.
};
typedef void (* scan_done_cb_t)(void *arg, STATUS status);

4. WiFi event related structure

enum {
EVENT_STAMODE_CONNECTED = 0,
EVENT_STAMODE_DISCONNECTED,
EVENT_STAMODE_AUTHMODE_CHANGE,
EVENT_STAMODE_GOT_IP,
EVENT_SOFTAPMODE_STACONNECTED,

Espressif Systems Confidential 112/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
EVENT_SOFTAPMODE_STADISCONNECTED,
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_DISASSOC_PWRCAP_BAD = 10, /* 11h */
REASON_DISASSOC_SUPCHAN_BAD = 11, /* 11h */
REASON_IE_INVALID = 13, /* 11i */
REASON_MIC_FAILURE = 14, /* 11i */
REASON_4WAY_HANDSHAKE_TIMEOUT = 15, /* 11i */
REASON_GROUP_KEY_UPDATE_TIMEOUT = 16, /* 11i */
REASON_IE_IN_4WAY_DIFFERS = 17, /* 11i */
REASON_GROUP_CIPHER_INVALID = 18, /* 11i */
REASON_PAIRWISE_CIPHER_INVALID = 19, /* 11i */
REASON_AKMP_INVALID = 20, /* 11i */
REASON_UNSUPP_RSN_IE_VERSION = 21, /* 11i */
REASON_INVALID_RSN_IE_CAP = 22, /* 11i */
REASON_802_1X_AUTH_FAILED = 23, /* 11i */
REASON_CIPHER_SUITE_REJECTED = 24, /* 11i */

REASON_BEACON_TIMEOUT = 200,
REASON_NO_AP_FOUND = 201,
};

typedef struct {
uint8 ssid[32];
uint8 ssid_len;
uint8 bssid[6];
uint8 channel;
} Event_StaMode_Connected_t;

Espressif Systems Confidential 113/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

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 {
struct ip_addr ip;
struct ip_addr mask;
struct ip_addr gw;
} 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_StaDisconnected_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_StaDisconnected_t sta_disconnected;
} Event_Info_u;

typedef struct _esp_event {

Espressif Systems Confidential 114/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
uint32 event;
Event_Info_u event_info;
} System_Event_t;

5. smart config structure

typedef enum {
SC_STATUS_WAIT = 0, // Please don’t start connection in this phase
SC_STATUS_FIND_CHANNEL, // Start connection by APP in this phase
SC_STATUS_GETTING_SSID_PSWD,
SC_STATUS_LINK,
SC_STATUS_LINK_OVER, // Got IP, connect to AP successfully
} sc_status;
typedef enum {
SC_TYPE_ESPTOUCH = 0,
SC_TYPE_AIRKISS,
} sc_type;

6.3. JSON Related Structure

1. json structure
struct jsontree_value {
uint8_t type;
};

struct jsontree_pair {
const char *name;
struct jsontree_value *value;
};

struct jsontree_context {
struct jsontree_value *values[JSONTREE_MAX_DEPTH];
uint16_t index[JSONTREE_MAX_DEPTH];
int (* putchar)(int);
uint8_t depth;
uint8_t path;
int callback_state;
};

Espressif Systems Confidential 115/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
struct jsontree_callback {
uint8_t type;
int (* output)(struct jsontree_context *js_ctx);
int (* set)(struct jsontree_context *js_ctx, 

struct jsonparse_state *parser);
};

struct jsontree_object {
uint8_t type;
uint8_t count;
struct jsontree_pair *pairs;
};

struct jsontree_array {
uint8_t type;
uint8_t count;
struct jsontree_value **values;
};

struct jsonparse_state {
const char *json;
int pos;
int len;
int depth;
int vstart;
int vlen;
char vtype;
char error;
char stack[JSONPARSE_MAX_DEPTH];
};

2. json macro definition

#define JSONTREE_OBJECT(name, ...) /
static struct jsontree_pair jsontree_pair_##name[] = {__VA_ARGS__}; /
static struct jsontree_object name = { /
JSON_TYPE_OBJECT, /
sizeof(jsontree_pair_##name)/sizeof(struct jsontree_pair), /
jsontree_pair_##name }

Espressif Systems Confidential 116/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
#define JSONTREE_PAIR_ARRAY(value) (struct jsontree_value *)(value)
#define JSONTREE_ARRAY(name, ...) /
static struct jsontree_value* jsontree_value_##name[] = {__VA_ARGS__}; /
static struct jsontree_array name = { /
JSON_TYPE_ARRAY, /
sizeof(jsontree_value_##name)/sizeof(struct jsontree_value*), /
jsontree_value_##name }

6.4. espconn parameters

1. callback function
/** callback prototype to inform about events for a espconn */
typedef void (* espconn_recv_callback)(void *arg, char *pdata, unsigned short
len);
typedef void (* espconn_callback)(void *arg, char *pdata, unsigned short len);
typedef void (* espconn_connect_callback)(void *arg);

2. espconn
typedef void* espconn_handle;
typedef struct _esp_tcp {
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;

typedef struct _esp_udp {

int remote_port;
int local_port;
uint8 local_ip[4];
uint8 remote_ip[4];
} esp_udp;

/** Protocol family and type of the espconn */

Espressif Systems Confidential 117/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
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_END
}

enum espconn_level{
ESPCONN_KEEPIDLE,
ESPCONN_KEEPINTVL,
ESPCONN_KEEPCNT
}
/** A espconn descriptor */
struct espconn {
/** type of the espconn (TCP, UDP) */
enum espconn_type type;
/** current state of the espconn */

Espressif Systems Confidential 118/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
enum espconn_state state;
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;
void *reverse; // reversed for customer use
};

6.5. interrupt related definition

/* 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

/* disable all interrupts */

#define ETS_INTR_LOCK() ets_intr_lock()

/* enable all interrupts */

#define ETS_INTR_UNLOCK() ets_intr_unlock()

/* register interrupt handler of frc timer1 */

#define ETS_FRC_TIMER1_INTR_ATTACH(func, arg) \

ets_isr_attach(ETS_FRC_TIMER1_INUM, (func), (void *)(arg))

/* register interrupt handler of GPIO */

#define ETS_GPIO_INTR_ATTACH(func, arg) \

ets_isr_attach(ETS_GPIO_INUM, (func), (void *)(arg))

Espressif Systems Confidential 119/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

/* register interrupt handler of UART */

#define ETS_UART_INTR_ATTACH(func, arg) \

ets_isr_attach(ETS_UART_INUM, (func), (void *)(arg))

/* register interrupt handler of SPI */

#define ETS_SPI_INTR_ATTACH(func, arg) \

ets_isr_attach(ETS_SPI_INUM, (func), (void *)(arg))

/* enable a interrupt */

#define ETS_INTR_ENABLE(inum) ets_isr_unmask((1<<inum))

/* disable a interrupt */

#define ETS_INTR_DISABLE(inum) ets_isr_mask((1<<inum))

/* enable SPI interrupt */

#define ETS_SPI_INTR_ENABLE() ETS_INTR_ENABLE(ETS_SPI_INUM)

/* enable UART interrupt */

#define ETS_UART_INTR_ENABLE() ETS_INTR_ENABLE(ETS_UART_INUM)

/* disable UART interrupt */

#define ETS_UART_INTR_DISABLE() ETS_INTR_DISABLE(ETS_UART_INUM)

/* enable frc1 timer interrupt */

#define ETS_FRC1_INTR_ENABLE() ETS_INTR_ENABLE(ETS_FRC_TIMER1_INUM)

/* disable frc1 timer interrupt */

#define ETS_FRC1_INTR_DISABLE() ETS_INTR_DISABLE(ETS_FRC_TIMER1_INUM)

/* enable GPIO interrupt */

#define ETS_GPIO_INTR_ENABLE() ETS_INTR_ENABLE(ETS_GPIO_INUM)

/* disable GPIO interrupt */

Espressif Systems Confidential 120/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
#define ETS_GPIO_INTR_DISABLE() ETS_INTR_DISABLE(ETS_GPIO_INUM)

Espressif Systems Confidential 121/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

7. Peripheral Related Drivers

7.1. GPIO Related APIs

Please refer to /user/user_plug.c.
Users can apply to Espressif Systems for GPIO document which contains more details.

1. PIN Related Macros

The following macros are used to control the GPIO pins' status.

PIN_PULLUP_DIS(PIN_NAME)

Disable pin pull up

PIN_PULLUP_EN(PIN_NAME)

Enable pin pull up

PIN_FUNC_SELECT(PIN_NAME, FUNC)

Select pin function

Example: 

PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12); // Use MTDI pin as
GPIO12.

2. gpio_output_set
Function: set gpio property

Prototype:

void gpio_output_set(

uint32 set_mask, 

uint32 clear_mask, 

uint32 enable_mask, 

uint32 disable_mask

)

Input Parameters:

uint32 set_mask : set high output; 1:high output; 0:no status change

uint32 clear_mask : set low output; 1:low output; 0:no status change

uint32 enable_mask : enable outpout bit

uint32 disable_mask : enable input bit

Return:

null

Espressif Systems Confidential 122/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Example: 

gpio_output_set(BIT12, 0, BIT12, 0):

Set GPIO12 as high-level output;

gpio_output_set(0, BIT12, BIT12, 0):

Set GPIO12 as low-level output

gpio_output_set(BIT12, BIT13, BIT12|BIT13, 0):

Set GPIO12 as high-level output, GPIO13 as low-level output.

gpio_output_set(0, 0, 0, BIT12): 

Set GPIO12 as input

3. GPIO input and output macro

GPIO_OUTPUT_SET(gpio_no, bit_value)

Set gpio_no as output bit_value, the same as the output example in 5.1.2

GPIO_DIS_OUTPUT(gpio_no)

Set gpio_no as input, the same as the input example in 5.1.2.

GPIO_INPUT_GET(gpio_no)

Get the level status of gpio_no.

4. GPIO interrupt
ETS_GPIO_INTR_ATTACH(func, arg)

Register GPIO interrupt control function

ETS_GPIO_INTR_DISABLE()

Disable GPIO interrupt

ETS_GPIO_INTR_ENABLE()

Enable GPIO interrupt

5. gpio_pin_intr_state_set
Function: 

set GPIO interrupt state

Prototype:

void gpio_pin_intr_state_set(

uint32 i, 

GPIO_INT_TYPE intr_state

)

Espressif Systems Confidential 123/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Input Parameters:

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,

GPIO_PIN_INTR_POSEDGE = 1,

GPIO_PIN_INTR_NEGEDGE = 2,

GPIO_PIN_INTR_ANYEGDE = 3,

GPIO_PIN_INTR_LOLEVEL = 4,

GPIO_PIN_INTR_HILEVEL = 5

} GPIO_INT_TYPE;

Return: 

null

6. GPIO Interrupt Handler

Follow the steps below to clear interrupt status in GPIO interrupt processing function:

uint32 gpio_status;
gpio_status = GPIO_REG_READ(GPIO_STATUS_ADDRESS);
//clear interrupt status
GPIO_REG_WRITE(GPIO_STATUS_W1TC_ADDRESS, gpio_status);

7.2. UART Related APIs

By default, UART0 is debug output interface. In the case of dual UART, UART0 works as data receive
and transmit interface, and UART1as debug output interface. Please make sure all hardware are
correctly connected.
Users can apply to Espressif Systems for UART document which contains more details.

1. uart_init
Function: 

Initializes baud rates of the two uarts

Prototype:

void uart_init(

UartBautRate uart0_br, 

UartBautRate uart1_br

)

Espressif Systems Confidential 124/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Parameters: 

UartBautRate uart0_br : uart0 baud rate

UartBautRate uart1_br : uart1 baud rate

Baud Rates: 

typedef enum {

BIT_RATE_9600 = 9600,

BIT_RATE_19200 = 19200,

BIT_RATE_38400 = 38400,

BIT_RATE_57600 = 57600,

BIT_RATE_74880 = 74880,

BIT_RATE_115200 = 115200,

BIT_RATE_230400 = 230400,

BIT_RATE_460800 = 460800,

BIT_RATE_921600 = 921600

} UartBautRate;

Return:

null

2. uart0_tx_buffer
Function: 

Sends user-defined data through UART0

Prototype: 

void uart0_tx_buffer(uint8 *buf, uint16 len)

Parameter:

uint8 *buf : data to send later

uint16 len : the length of data to send later

Return:

null

3. uart0_rx_intr_handler
Function: 

UART0 interrupt processing function. Users can add the processing of
received data in this function. (Receive buffer size: 0x100; if the received
data are more than 0x100, pls handle them yourselves.)

Prototype:

void uart0_rx_intr_handler(void *para)

Parameter:

void *para : the pointer pointing to RcvMsgBuff structure

Espressif Systems Confidential 125/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Return:

null

7.3. I2C Master Related APIs

Users can apply to Espressif Systems for I2C document which contains more details.

1. i2c_master_gpio_init
Function: 

Set GPIO in I2C master mode

Prototype:

void i2c_master_gpio_init (void)

Input Parameters:

null

Return:

null

2. i2c_master_init
Function: 

Initialize I2C

Prototype:

void i2c_master_init(void)

Input Parameters:

null

Return:

null

3. i2c_master_start
Function: configures I2C to start sending data

Prototype:

void i2c_master_start(void)

Input Parameters:

null

Return:

null

Espressif Systems Confidential 126/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
4. i2c_master_stop
Function: 

configures I2C to stop sending data

Prototype:

void i2c_master_stop(void)

Input Parameters:

null

Return:

null

5. i2c_master_send_ack
Function: 

Sends I2C ACK

Prototype:

void i2c_master_send_ack (void)

Input Parameters:

null

Return:

null

6. i2c_master_send_nack
Function: 

Sends I2C NACK

Prototype:

void i2c_master_send_nack (void)

Input Parameters:

null

Return:

null

7. i2c_master_checkAck
Function: 

Checks ACK from slave

Prototype:

bool i2c_master_checkAck (void)

Espressif Systems Confidential 127/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Input Parameters:

null

Return:

true: get I2C slave ACK

false: get I2C slave NACK

8. i2c_master_readByte
Function: 

Read one byte from I2C slave

Prototype:

uint8 i2c_master_readByte (void)

Input Parameters:

null

Return:

uint8 : the value that was read

9. i2c_master_writeByte
Function: 

Write one byte to slave

Prototype:

void i2c_master_writeByte (uint8 wrdata)

Input Parameters:

uint8 wrdata : data to write

Return:

null

7.4. PWM Related

Herein only introduces the PWM related APIs in pwm.h. Users can apply to Espressif Systems for PWM
document which contains more details.

1. pwm_init
Function: 

Initialize PWM function, including GPIO selection, period and duty cycle.

Note:

This API can be called only once.

Espressif Systems Confidential 128/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Prototype:

void pwm_init(

uint32 period,

uint8 *duty,

uint32 pwm_channel_num,

uint32 (*pin_info_list)[3])

Parameter:

uint32 period : PWM period 

uint8 *duty : duty cycle of each output

uint32 pwm_channel_num: PWM channel number

uint32 (*pin_info_list)[3]: GPIO parameter of PWM channel, it is a pointer

of n * 3 array which defines GPIO register, IO reuse of corresponding PIN
and GPIO number.

Return:

null

Example:

uint32 io_info[][3] =

{{PWM_0_OUT_IO_MUX,PWM_0_OUT_IO_FUNC,PWM_0_OUT_IO_NUM},
{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}};

pwm_init(light_param.pwm_period, light_param.pwm_duty, 3, io_info);

2. pwm_start
Function: 

Starts PWM. This function needs to be called after PWM config is changed.

Prototype: 

void pwm_start (void)

Parameter: 

null

Return: 

null

Espressif Systems Confidential 129/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
3. pwm_set_duty
Function: 

Sets duty cycle of a PWM output. Set the time that high-level single will
last, duty depends on period, the maximum value can be Period * 1000 /45.
For example, 1KHz PWM, duty range is 0 ~ 22222

Note:

After set configuration，pwm_start need to be called to take effect.

Prototype:

void pwm_set_duty(uint8 duty, uint8 channel)

Input Parameters:

uint8 duty : the time that high-level single will last, duty cycle will be
(duty*45)/ (period*1000)

uint8 channel : PWM channel, depends on how many PWM channels is used, in
IOT_Demo it depends on #define PWM_CHANNEL

Return:

null

4. pwm_get_duty
Function: 

Gets duty cycle of PWM output, duty cycle will be (duty*45)/ (period*1000)

Prototype:

uint8 pwm_get_duty(uint8 channel)

Input Parameters:

uint8 channel : PWM channel, depends on how many PWM channels is used, in
IOT_Demo it depends on #define PWM_CHANNEL

Return:

uint8 : duty cycle of PWM output

5. pwm_set_period
Function: 

Sets PWM period, unit: us. For example, for 1KHz PWM, period is 1000 us

Note:

After set configuration，pwm_start need to be called to take effect.

Prototype:

void pwm_set_period(uint32 period)

Espressif Systems Confidential 130/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
Input Parameters:

uint32 period : PWM period, unit: us

Return:

null

6. pwm_get_period
Function: 

Gets PWM period.

Prototype:

uint32 pwm_get_period(void)

Parameter:

null

Return:

PWM period, unit: us.

7. get_pwm_version
Function: 

Get version information of PWM.

Prototype:

uint32 get_pwm_version(void)

Parameter: 

none

Return: 

PWM version

Espressif Systems Confidential 131/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide

8. Appendix

8.1. ESPCONN Programming

1. TCP Client Mode

Notes
• ESP8266, working in Station mode, will start client connection when given an IP address.
• ESP8266, working in soft-AP mode, will start client connection when the devices which are
connected to ESP8266 are given an IP address.

Steps
• Initialize espconn parameters according to protocols.
• Register connect callback function, and register reconnect callback function.
‣ (Call espconn_regist_connectcb and espconn_regist_reconcb )
• Call espconn_connect function and set up the connection with TCP Server.
• Registered connected callback function will be called after successful connection, which will
register the corresponding callback function. Recommend to register disconnect callback
function.
‣ (Call espconn_regist_recvcb , espconn_regist_sentcb and espconn_regist_disconcb
in connected callback)
• When using receive callback function or sent callback function to run disconnect, it is
recommended to set a time delay to make sure that the all the firmware functions are
completed.

2. TCP Server Mode

Notes
• If ESP8266 is in Station mode, it will start server listening when given an IP address.
• If ESP8266 is in soft-AP mode, it will start server listening.

Steps
• Initialize espconn parameters according to protocols.
• Register connect callback and reconnect callback function.
‣ (Call espconn_regist_connectcb and espconn_regist_reconcb )
• Call espconn_accept function to listen to the connection with host.

Espressif Systems Confidential 132/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
• Registered connect function will be called after successful connection, which will register
corresponding callback function.
‣ (Call espconn_regist_recvcb , espconn_regist_sentcb and espconn_regist_disconcb
in connected callback)

3. espconn callback

Register Function Callback Description

espconn_regist_connectcb espconn_connect_callback TCP connected successfully
espconn_regist_reconcb espconn_reconnect_callback Error occur，TCP disconnected
espconn_regist_sentcb espconn_sent_callback Sent TCP or UDP data
espconn_regist_recvcb espconn_recv_callback Received TCP or UDP data
espconn_regist_write_finish espconn_write_finish_callback Write data into TCP-send-buffer
espconn_regist_disconcb espconn_disconnect_callback TCP disconnected successfully

Notice: Parameter arg of callback is the 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 instead.

8.2. RTC APIs Example

Demo code below shows how to get RTC time and to read and write to RTC memory.

#include "ets_sys.h"
#include "osapi.h"
#include "user_interface.h"

os_timer_t rtc_test_t;
#define RTC_MAGIC 0x55aaaa55

typedef struct {
uint64 time_acc;
uint32 magic ;
uint32 time_base;
}RTC_TIMER_DEMO;

void rtc_count()

Espressif Systems Confidential 133/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
{
RTC_TIMER_DEMO rtc_time;
static uint8 cnt = 0;
system_rtc_mem_read(64, &rtc_time, sizeof(rtc_time));

if(rtc_time.magic!=RTC_MAGIC){
os_printf("rtc time init...\r\n");
rtc_time.magic = RTC_MAGIC;
rtc_time.time_acc= 0;
rtc_time.time_base = system_get_rtc_time();
os_printf("time base : %d \r\n",rtc_time.time_base);
}

os_printf("==================\r\n");
os_printf("RTC time test : \r\n");

uint32 rtc_t1,rtc_t2;
uint32 st1,st2;
uint32 cal1, cal2;

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(" rtc_t2-t1 : %d \r\n",rtc_t2-rtc_t1);
os_printf(" st2-t2 : %d \r\n",st2-st1);
os_printf("cal 1 : %d.%d \r\n", ((cal1*1000)>>12)/1000,
((cal1*1000)>>12)%1000 );
os_printf("cal 2 : %d.%d \r\n",((cal2*1000)>>12)/1000,
((cal2*1000)>>12)%1000 );
os_printf("==================\r\n\r\n");
rtc_time.time_acc += ( ((uint64)(rtc_t2 - rtc_time.time_base)) *
( (uint64)((cal2*1000)>>12)) ) ;

Espressif Systems Confidential 134/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
os_printf("rtc time acc : %lld \r\n",rtc_time.time_acc);
os_printf("power on time : %lld us\r\n", rtc_time.time_acc/1000);
os_printf("power on time : %lld.%02lld S\r\n", (rtc_time.time_acc/
10000000)/100, (rtc_time.time_acc/10000000)%100);

rtc_time.time_base = rtc_t2;
system_rtc_mem_write(64, &rtc_time, sizeof(rtc_time));
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_printf("SDK version:%s\n", system_get_sdk_version());

os_timer_disarm(&rtc_test_t);
os_timer_setfn(&rtc_test_t,rtc_count,NULL);
os_timer_arm(&rtc_test_t,10000,1);
}

8.3. Sniffer Structure Introduction

ESP8266 can enter promiscuous mode (sniffer) and capture IEEE 802.11 packets in the air.
The following HT20 packets are support:
• 802.11b
• 802.11g
• 802.11n (from MCS0 to MCS7)
• AMPDU types of packets

Espressif Systems Confidential 135/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
The following are not supported:
• HT40
• LDPC
Although ESP8266 can not completely decipher these kinds of IEEE80211 packets completely, it can
still obtain the length of these special packets.
In summary, while in sniffer mode, ESP8266 can either capture completely the packets or obtain the
length of the packet:
• Packets that ESP8266 can decipher completely; ESP8266 returns with the
‣ MAC address of the both side of communication and encryption type and
‣ the length of entire packet.
• Packets that ESP8266 can only partial decipher; ESP8266 returns with
‣ the length of packet.
Structure RxControl and sniffer_buf are used to represent these two kinds of packets. Structure
sniffer_buf contains structure RxControl.

struct RxControl {
signed rssi:8; // signal intensity of packet
unsigned rate:4;
unsigned is_group:1;
unsigned:1;
unsigned sig_mode:2; // 0:is 11n packet; 1:is not 11n packet;
unsigned legacy_length:12; // if not 11n packet, shows length of packet.
unsigned damatch0:1;
unsigned damatch1:1;
unsigned bssidmatch0:1;
unsigned bssidmatch1:1;
unsigned MCS:7; // if is 11n packet, shows the modulation
// and code used (range from 0 to 76)
unsigned CWB:1; // if is 11n packet, shows if is HT40 packet or not
unsigned HT_length:16;// if is 11n packet, shows length of packet.
unsigned Smoothing:1;
unsigned Not_Sounding:1;
unsigned:1;
unsigned Aggregation:1;
unsigned STBC:2;
unsigned FEC_CODING:1; // if is 11n packet, shows if is LDPC packet or not.

Espressif Systems Confidential 136/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
unsigned SGI:1;
unsigned rxend_state:8;
unsigned ampdu_cnt:8;
unsigned channel:4; //which channel this packet in.
unsigned:12;
};

struct LenSeq{
u16 len; // length of packet
u16 seq; // serial number of packet, the high 12bits are serial number,
// low 14 bits are Fragment number (usually be 0)
u8 addr3[6]; // the third address in packet
};

struct sniffer_buf{
struct RxControl rx_ctrl;
u8 buf[36 ]; // head of ieee80211 packet
u16 cnt; // number count of packet
struct LenSeq lenseq[1]; //length of packet
};

struct sniffer_buf2{
struct RxControl rx_ctrl;
u8 buf[112];
u16 cnt;
u16 len; //length of packet
};

Callback wifi_promiscuous_rx has two parameters ( buf and len). len means the length of buf, it
can be: len = 128, len = X * 10, len = 12 :

Case of LEN == 128

• buf contains structure sniffer_buf2: it is the management packet, it has 112 bytes data.

• sniffer_buf2.cnt is 1.

• sniffer_buf2.len is the length of packet.

Case of LEN == X * 10
• buf contains structure sniffer_buf: this structure is reliable, data packets represented by it
has been verified by CRC.

Espressif Systems Confidential 137/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
• sniffer_buf.cnt means the count of packets in buf. The value of len depends on
sniffer_buf.cnt.

‣ sniffer_buf.cnt==0, invalid buf; otherwise, len = 50 + cnt * 10

• sniffer_buf.buf contains the first 36 bytes of ieee80211 packet. Starting from

sniffer_buf.lenseq[0], each structure lenseq represent a length information of packet.
lenseq[0] represents the length of first packet. If there are two packets where
(sniffer_buf.cnt == 2), lenseq[1] represents the length of second packet.

• If sniffer_buf.cnt > 1, it is a AMPDU packet, head of each MPDU packets are similar, so
we only provide the length of each packet (from head of MAC packet to FCS)
• This structure contains: length of packet, MAC address of both sides of communication,
length of the head of packet.

Case of LEN == 12
• buf contains structure RxControl; but this structure is not reliable, we can not get neither
MAC address of both sides of communication nor length of the head of packet.
• For AMPDU packet, we can not get the count of packets or the length of packet.
• This structure contains: length of packet, rssi and FEC_CODING.
• RSSI and FEC_CODING are used to guess if the packets are sent from same device.

Summary
We should not take too long to process the packets. Otherwise, other packets may be lost.
The diagram below shows the format of a ieee80211 packet:

• The first 24 bytes of MAC Header of data packet are needed:

‣ Address 4 field depends on FromDS and ToDS which is in Frame Control;

‣ QoS Control field depends on Subtype which is in Frame Control;

‣ HT Control field depends on Order Field which is in Frame Control;

‣ More details are found in IEEE Std 80211-2012.

Espressif Systems Confidential 138/139 Friday, June 5, 2015

! ! Espressif Systems ! ESP8266 SDK API Guide
• For WEP packets, MAC Header is followed by 4 bytes IV and before FCS there are 4 bytes
ICV.
• For TKIP packet, MAC Header is followed by 4 bytes IV and 4 bytes EIV, and before FCS there
are 8 bytes MIC and 4 bytes ICV.
• For CCMP packet, MAC Header is followed by 8 bytes CCMP header, and before FCS there
are 8 bytes MIC.

8.4. ESP8266 soft-AP and station channel configuration

Even though ESP8266 can be in soft-AP + station mode，it actually has only one hardware channel.
So in soft-AP + station mode, ESP8266 soft-AP will adjust its channel configuration to be as same as
ESP8266 station.
This limitation may cause some inconvenience in softAP + station mode users need to pay
attention，for example:
Case 1.
（1） If user connect ESP8266 station to a router(e.g. router is in channel 6)
（2） Then set ESP8266 softAP by wifi_softap_set_config
（3） The API may return true, but channel will always be channel 6. Because we have only one
hardware channel.
Case 2.
（1）If user set ESP8266 softAP a channel number(e.g. channel 5) by wifi_softap_set_config
（2）Some stations connected to ESP8266 softAP.
（3）Then connect ESP8266 station to a router of which channel number is different (e.g. channel
6) .
（4）ESP8266 softAP has to adjust its channel to be as same as ESP8266 station , in this case, is
channel 6.
（5）So the stations that connected to ESP8266 softAP in step 2 will be disconnected because of the
channel change.

Espressif Systems Confidential 139/139 Friday, June 5, 2015