2c-esp8266__sdk__programming guide__en_v1 2 0

1、 ESP8266 SDK API GuideVersion 1.2.0Espressif Systems IOT TeamCopyright (c) 2015 Espressif SystemsESP8266 SDK Programming GuideDisclaimer and Copyright NoticeInformation in this document, including URL references, is subject to change without notice.THIS DOCUMENT IS PROVIDED AS IS WITH NO WARRANTIES

2、WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION ORSAMPLE. All liability, including liability for infringement of any proprietary rights, relating to use of information in

3、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 prope

4、rty of their respective owners, and are hereby acknowledged.Copyright 2015 Espressif Systems Inc. All rights reserved.Espressif Systems Confidential2/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming GuideTable of ContentPreambles131.2.Overview143.Application Programming Interface (AP

5、Is)153.1.1.2.3.4.5.3.2.1.2.3.4.3.3.1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.Software Timer15os_timer_arm15os_timer_disarm16os_timer_setfn16system_timer_reinit16os_timer_arm_us17Hardware Timer17hw_timer_init18hw_timer_arm18hw_timer_set_func18hardware timer example19System APIs20system_get_sdk_version20sys

6、tem_restore20system_restart20system_init_done_cb21system_get_chip_id21system_get_vdd3321system_adc_read22system_deep_sleep22system_deep_sleep_set_option23system_phy_set_rfoption23system_phy_set_max_tpw24system_phy_set_tpw_via_vdd3325system_set_os_print25system_print_meminfo25system_get_free_heap_siz

7、e26Espressif Systems Confidential3/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41.3.4.1.2.3.4.5.6.system_os_task26system_os_post27system_get_time28system_get_rtc_time28system_rtc_clock_cali_proc28sys

8、tem_rtc_mem_write29system_rtc_mem_read30system_uart_swap30system_uart_de_swap31system_get_boot_version31system_get_userbin_addr31system_get_boot_mode32system_restart_enhance32system_update_cpu_freq33system_get_cpu_freq33system_get_flash_size_map33system_get_rst_info34system_soft_wdt_stop35system_sof

9、t_wdt_restart35os_memset36os_memcpy36os_strlen36os_printf37os_bzero37os_delay_us38os_install_putc138SPI Flash Related APIs38spi_flash_get_id38spi_flash_erase_sector39spi_flash_write39spi_flash_read40system_param_save_with_protect40system_param_load41Espressif Systems Confidential4/157Friday, July 3,

10、 2015 Espressif SystemsESP8266 SDK Programming Guide7.3.5.1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.spi_flash_set_read_func42Wi-Fi Related APIs44wifi_get_opmode44wifi_get_opmode_default44wifi_set_opmode45wifi_set_opmode_current45wifi_station_get_config45wifi

11、_station_get_config_default46wifi_station_set_config46wifi_station_set_config_current47wifi_station_connect48wifi_station_disconnect48wifi_station_get_connect_status49wifi_station_scan49scan_done_cb_t50wifi_station_ap_number_set50wifi_station_get_ap_info51wifi_station_ap_change51wifi_station_get_cur

12、rent_ap_id51wifi_station_get_auto_connect52wifi_station_set_auto_connect52wifi_station_dhcpc_start52wifi_station_dhcpc_stop53wifi_station_dhcpc_status53wifi_station_set_reconnect_policy54wifi_station_get_rssi54wifi_station_set_hostname54wifi_station_get_hostname55wifi_softap_get_config55wifi_softap_

13、get_config_default55wifi_softap_set_config56wifi_softap_set_config_current56wifi_softap_get_station_num57Espressif Systems Confidential5/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide32.33.34.35.36.37.38.39.40.41.42.43.44.45.46.47.48.49.50.51.52.53.54.55.56.57.3.6.1.2.3.4.5.6

14、.wifi_softap_get_station_info57wifi_softap_free_station_info57wifi_softap_dhcps_start58wifi_softap_dhcps_stop59wifi_softap_set_dhcps_lease59wifi_softap_dhcps_status60wifi_softap_set_dhcps_offer_option61wifi_set_phy_mode62wifi_get_phy_mode62wifi_get_ip_info62wifi_set_ip_info63wifi_set_macaddr64wifi_g

15、et_macaddr65wifi_set_sleep_type65wifi_get_sleep_type65wifi_status_led_install66wifi_status_led_uninstall66wifi_set_broadcast_if67wifi_get_broadcast _if67wifi_set_event_handler_cb67wifi_get_channel69wifi_set_channel69wifi_wps_enable70wifi_wps_disable70wifi_wps_start71wifi_set_wps_cb71ESP-NOW APIs73es

16、p_now_init73esp_now_deinit73esp_now_register_recv_cb73esp_now_unregister_recv_cb74esp_now_send74esp_now_add_peer75Espressif Systems Confidential6/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide7.8.9.10.11.12.13.14.15.16.17.18.3.7.1.2.3.4.5.3.8.1.2.3.3.9.1.2.3.10.1.2.3.4.5.6.7.

17、esp_now_del_peer75esp_now_set_self_role76esp_now_get_self_role76esp_now_set_peer_role77esp_now_get_peer_role77esp_now_set_peer_key78esp_now_get_peer_key78esp_now_set_peer_channel78esp_now_get_peer_channel79esp_now_is_peer_exist79esp_now_fetch_peer80esp_now_get_cnt_info80Upgrade (FOTA) APIs81system_u

18、pgrade_userbin_check81system_upgrade_flag_set81system_upgrade_flag_check81system_upgrade_start82system_upgrade_reboot82Snier Related APIs83wifi_promiscuous_enable83wifi_promiscuous_set_mac83wifi_set_promiscuous_rx_cb84smart config APIs85smartconfig_start85smartconfig_stop87SNTP APIs88sntp_setserver8

19、8sntp_getserver88sntp_setservername88sntp_getservername89sntp_init89sntp_stop89sntp_get_current_timestamp89Espressif Systems Confidential7/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide8.9.sntp_get_real_time90SNTP Example914.TCP/UDP APIs924.1.1.2.3.4.5.6.7.8.4.2.1.2.3.4.5.6.7

20、.8.9.10.11.12.13.14.15.16.17.18.19.20.Generic TCP/UDP APIs92espconn_delete92espconn_gethostbyname92espconn_port93espconn_regist_sentcb94espconn_regist_recvcb94espconn_sent_callback95espconn_recv_callback95espconn_sent95TCP APIs96espconn_accept96espconn_secure_accept97espconn_regist_time97espconn_get

21、_connection_info98espconn_connect98espconn_connect_callback99espconn_regist_connectcb99espconn_set_opt100espconn_clear_opt101espconn_set_keepalive101espconn_get_keepalive103espconn_reconnect_callback103espconn_regist_reconcb104espconn_disconnect105espconn_regist_disconcb105espconn_regist_write_finis

22、h105espconn_secure_set_size106espconn_secure_get_size107espconn_secure_connect107espconn_secure_sent108Espressif Systems Confidential8/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide21.22.23.24.25.26.27.28.29.4.3.1.2.3.4.4.4.1.2.3.4.5.6.7.8.9.10.espconn_secure_disconnect108esp

23、conn_secure_ca_disable109espconn_secure_ca_enable109espconn_tcp_get_max_con110espconn_tcp_set_max_con110espconn_tcp_get_max_con_allow110espconn_tcp_set_max_con_allow111espconn_recv_hold111espconn_recv_unhold112UDP APIs112espconn_create112espconn_igmp_join113espconn_igmp_leave113espconn_dns_setserver

24、113mDNS APIs114espconn_mdns_init114espconn_mdns_close115espconn_mdns_server_register115espconn_mdns_server_unregister115espconn_mdns_get_servername116espconn_mdns_set_servername116espconn_mdns_set_hostname116espconn_mdns_get_hostname117espconn_mdns_disable117espconn_mdns_enable1175.Application Relat

25、ed1185.1.1.2.3.4.5.6.AT APIs118at_response_ok118at_response_error118at_cmd_array_regist118at_get_next_int_dec119at_data_str_copy119at_init120Espressif Systems Confidential9/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide7.8.9.10.11.12.13.14.5.2.1.2.3.4.5.6.7.8.9.10.11.12.13.14

26、.15.16.at_port_print120at_set_custom_info120at_enter_special_state121at_leave_special_state121at_get_version121at_register_uart_rx_intr122at_response122at_register_response_func123Related JSON APIs124jsonparse_setup124jsonparse_next124jsonparse_copy_value124jsonparse_get_value_as_int125jsonparse_get

27、_value_as_long125jsonparse_get_len125jsonparse_get_value_as_type126jsonparse_strcmp_value126jsontree_set_up126jsontree_reset127jsontree_path_name127jsontree_write_int128jsontree_write_int_array128jsontree_write_string128jsontree_print_next129jsontree_find_next1296.Definitions & Structures1306.1.6.2.

28、1.2.3.4.5.Timer130WiFi Related Structures130Station Related130soft-AP related130scan related131WiFi event related structure131smart config structure134Espressif Systems Confidential10/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide6.3.1.2.6.4.1.2.6.5.JSON Related Structure134j

29、son structure134json macro definition135espconn parameters136callback function136espconn136interrupt related definition1387.Peripheral Related Drivers1407.1.1.2.3.4.5.6.7.2.1.2.3.7.3.1.2.3.4.5.6.7.8.9.7.4.1.2.3.GPIO Related APIs140PIN Related Macros140gpio_output_set140GPIO input and output macro141

30、GPIO interrupt141gpio_pin_intr_state_set141GPIO Interrupt Handler142UART Related APIs142uart_init142uart0_tx_buffer143uart0_rx_intr_handler143I2C Master Related APIs144i2c_master_gpio_init144i2c_master_init144i2c_master_start144i2c_master_stop145i2c_master_send_ack145i2c_master_send_nack145i2c_maste

31、r_checkAck145i2c_master_readByte146i2c_master_writeByte146PWM Related147pwm_init147pwm_start148pwm_set_duty148Espressif Systems Confidential11/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programming Guide4.5.6.7.pwm_get_duty148pwm_set_period149pwm_get_period149get_pwm_version1498.Appendix15

32、08.1.1.2.3.8.2.8.3.8.4.ESPCONN Programming150TCP Client Mode150TCP Server Mode150espconn callback151RTC APIs Example151Snier Structure Introduction153ESP8266 soft-AP and station channel configuration157Espressif Systems Confidential12/157Friday, July 3, 2015 Espressif SystemsPreamblesESP8266 SDK Pro

33、gramming Guide1.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

34、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

35、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 are

36、a.ESP8266EX also integrates an enhanced version of Tensilicas 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 prov

37、ided 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, L

38、VDS, 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 ESP826

39、6 IoT platform.Espressif Systems Confidential13/157Friday, July 3, 2015 Espressif SystemsOverviewESP8266 SDK Programming Guide2.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 hig

40、h 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)

41、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

42、call system_phy_set_rfoption to set RF option in user_rf_pre_init, or call system_deep_sleep_set_option before deep-sleep. If RF is disable, ESP8266 station and soft-AP are both disabled, please dont call related APIs.The SDK provides APIs to handle JSON, and users can also use self-defined data typ

43、es 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 cant 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 su

44、ggest to use a timer to check periodically.Using non-OS SDK, please dont call any function defined with ICACHE_FLASH_ATTR in interrupt handler.We suggest to use RTOS SDK, RTOS can schedule different tasks.Espressif Systems Confidential14/157Friday, July 3, 2015 Espressif SystemsESP8266 SDK Programmi

45、ng Guide3.Application Programming Interface (APIs)3.1.Software TimerTimer APIs can be found: /esp_iot_sdk/include/osapi.h. Please be noted that os_timer APIs listed beloware software timer, theyare executed in task, so timer callback may not be precisely executed atthe right time, it depends onprior

46、ity. If you needa 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

47、 not enabled, i.e., afteros_timer_disarm or before os_timer_arm (or os_timer_arm_us).1.os_timer_armEspressif Systems Confidential15/157Friday, July 3, 2015Function: Enable a millisecond timer. Prototype: void os_timer_arm ( ETSTimer *ptimer, uint32_t milliseconds, bool repeat_flag ) Parameters: ETST

48、imer *ptimer : Timer structure uint32_t milliseconds : Timing, Unit: millisecond if called system_timer_reinit, the maximum value allowed to input is 0x41893 if didnt call system_timer_reinit, the maximum value allowed to input is 0xFFFFFFF bool repeat_flag : Whether the timer will be invoked repeat

49、edly or not Return:null Espressif SystemsESP8266 SDK Programming Guide2.os_timer_disarm3.os_timer_setfn4.system_timer_reinitEspressif Systems Confidential16/157Friday, July 3, 2015Function: Reinitiate the timer when you need to use microsecond timer Notes: 1. Define USE_US_TIMER; 2. Put system_timer

50、_reinit at the beginning of user_init , in the first sentence. Prototype: void system_timer_reinit (void) Function: Set timer callback function. For enabled timer, timer callback has to be set. Prototype: void os_timer_setfn( ETSTime r *ptimer, ETSTimerFunc *pfunction, void *parg ) Parameters: ETSTi

51、mer *ptimer : Timer structure TESTimerFunc *pfunction : timer callback function void *parg : callback function parameter Return: null Function: Disarm timer Prototype: void os_timer_disarm (ETSTimer *ptimer) Parameters: ETSTimer *ptimer : Timer structure Return: null Espressif SystemsESP8266 SDK Pro

52、gramming Guide5.os_timer_arm_us3.2.Hardware TimerHardware timer APIs can be found in /esp_iot_sdk/examples/driver_lib/hw_timer.c. User can use it according to “readme.txt” which in folder driver_lib.NOTE:if use NMI source, for autoload timer , parameter val of hw_timer_arm cant be less than 100. if use NMI source, this timer has highest priority,can interrupt other ISR.if use FRC1 source, this timer cant interrupt other ISR.APIs in hw_timer.c can not be called when PWM APIs are using, because they are using the same hardware timer.Es