Руководство пользователя espressif iot sdk

Related Manuals for Espressif Systems ESP8266 SDK

• ESP8266EX SDK Programming Guide

  1 / 95 Espressif Systems February 9, 2015

  Espressif IoT SDK:

  Programming Guide

  Status Released

  Current version V0.9.5

  Author Fei Yu

  Completion Date 2015.01.22

  Reviewer JG Wu

  Completion Date 2015.01.22

  [ ] CONFIDENTIAL

  [ ] INTERNAL

  [ ] PUBLIC

• ESP8266EX SDK Programming Guide

  2 / 95 Espressif Systems February 9, 2015

  Version Info

  Date Version Author Comments/Changes

  2013.12.25

  ~2014.7.10

  0.1~0.8 JG Wu /

  Han Liu/

  Fei Yu

  Draft and changes

  2014.8.13 0.9 Fei Yu 1.Revise espconn APIs

  2.Add sniffer APIs

  3.Add system_get_chip_id

  4.Add APIs to read/ write mac&ip

  2014.9.23 0.9.1 Fei Yu 1Add system_deep_sleep;

  2Revise APIs to read/write flash;

  3Add APIs for AP_CHE

  4Revise UDP APIs

  2014.11.20 0.9.3 Fei Yu Introduce esp_iot_sdk_v0.9.3

  1Add APIs for auto connecting to

  router when power on or not;

  2Add APIs for UART swap;

  3Add APIs for DHCP;

  4Add APIs for RTC

  2014.12.19 0.9.4 Fei Yu Introduce esp_iot_sdk_v0.9.4

  1Add APIs for sleep type;

  2Add APIs for igmp

  2015.01.22 0.9.5 Fei Yu Introduce esp_iot_sdk_v0.9.5

  1Revised upgrade APIs

  2Add more DHCP APIs

  3Add API to get recorded AP info

  4Add smart config APIs

  5Add API to block TCP receiving

  data

  6Add API for AT commands

• ESP8266EX SDK Programming Guide

  3 / 95 Espressif Systems February 9, 2015

  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 2013 Espressif Systems Inc. All rights reserved.

• ESP8266EX SDK Programming Guide

  4 / 95 Espressif Systems February 9, 2015

  Table of Contents

  Version Info
  ……………………………………………………………………………………………………
  2

  Table of Contents
  …………………………………………………………………………………………..
  4

  1. Foreword
  ……………………………………………………………………………….
  9

  2. Overview
  ……………………………………………………………………………..
  10

  3. Application Programming Interface (APIs)
  ………………………….. 11

  3.1. Timer
  ……………………………………………………………………………………
  11

  3.1.1. os_timer_arm
  ……………………………………………………………………….
  11

  3.1.2. os_timer_disarm
  ……………………………………………………………………
  11

  3.1.3. os_timer_setfn
  ………………………………………………………………………
  12

  3.2. System APIs
  …………………………………………………………………………..
  12

  3.2.1. system_restore
  ………………………………………………………………………
  12

  3.2.2. system_restart
  ………………………………………………………………………
  12

  3.2.3. system_timer_reinit
  ……………………………………………………………….
  13

  3.2.4. system_init_done_cb
  ……………………………………………………………..
  13

  3.2.5. system_get_chip_id
  ……………………………………………………………….
  14

  3.2.6. system_deep_sleep
  ……………………………………………………………….
  14

  3.2.7. system_deep_sleep_set_option
  ……………………………………………… 15

  3.2.8. system_set_os_print
  ………………………………………………………………
  16

  3.2.9. system_print_meminfo
  …………………………………………………………..
  16

  3.2.10. system_get_free_heap_size
  …………………………………………………… 16

  3.2.11. system_os_task
  ……………………………………………………………………..
  17

  3.2.12. system_os_post
  …………………………………………………………………….
  18

  3.2.13. system_get_time
  ……………………………………………………………………
  18

  3.2.14. system_get_rtc_time
  ……………………………………………………………..
  19

  3.2.15. system_rtc_clock_cali_proc
  …………………………………………………….
  19

  3.2.16. system_rtc_mem_write
  ………………………………………………………….
  20

  3.2.17. system_rtc_mem_read
  …………………………………………………………..
  20

  3.2.18. system_uart_swap
  …………………………………………………………………
  21

  3.2.19. system_adc_read
  …………………………………………………………………..
  21

  3.3. SPI Flash Related APIs
  …………………………………………………………….
  22

  3.3.1. spi_flash_get_id
  …………………………………………………………………….
  22

  3.3.2. spi_flash_erase_sector
  …………………………………………………………..
  22

  3.3.3. spi_flash_write
  ………………………………………………………………………
  23

  3.3.4. spi_flash_read
  ……………………………………………………………………….
  23

  3.4. WIFI Related APIs
  …………………………………………………………………..
  25

  3.4.1. wifi_get_opmode
  …………………………………………………………………..
  25

  3.4.2. wifi_set_opmode
  …………………………………………………………………..
  25

  3.4.3. wifi_station_get_config
  ………………………………………………………….
  26

  3.4.4. wifi_station_set_config
  …………………………………………………………..
  26

  3.4.5. wifi_station_connect
  ……………………………………………………………..
  27

• ESP8266EX SDK Programming Guide

  5 / 95 Espressif Systems February 9, 2015

  3.4.6. wifi_station_disconnect
  ………………………………………………………….
  27

  3.4.7.
  wifi_station_get_connect_status……………………………………………..
  27

  3.4.8. wifi_station_scan
  …………………………………………………………………..
  28

  3.4.9. scan_done_cb_t
  …………………………………………………………………….
  29

  3.4.10. wifi_station_ap_number_set
  ………………………………………………….. 30

  3.4.11. wifi_station_get_ap_info
  ………………………………………………………..
  30

  3.4.12. wifi_station_ap_change
  ………………………………………………………….
  31

  3.4.13. wifi_station_get_current_ap_id
  ……………………………………………… 31

  3.4.14. wifi_station_get_auto_connect
  ………………………………………………. 31

  3.4.15. wifi_station_set_auto_connect
  ………………………………………………. 32

  3.4.16. wifi_station_dhcpc_start
  ………………………………………………………..
  32

  3.4.17. wifi_station_dhcpc_stop
  …………………………………………………………
  32

  3.4.18. wifi_station_dhcpc_status
  ………………………………………………………
  33

  3.4.19. wifi_softap_get_config
  …………………………………………………………..
  33

  3.4.20. wifi_softap_set_config
  ……………………………………………………………
  34

  3.4.21. wifi_softap_get_station_info
  ………………………………………………….. 34

  3.4.22. wifi_softap_free_station_info
  ………………………………………………… 34

  3.4.23. wifi_softap_dhcps_start
  …………………………………………………………
  35

  3.4.24. wifi_softap_dhcps_stop
  ………………………………………………………….
  36

  3.4.25.
  wifi_softap_set_dhcps_lease…………………………………………………..
  36

  3.4.26. wifi_softap_dhcps_status
  ……………………………………………………….
  37

  3.4.27. wifi_set_phy_mode
  ……………………………………………………………….
  37

  3.4.28. wifi_get_phy_mode
  ……………………………………………………………….
  38

  3.4.29. wifi_get_ip_info
  …………………………………………………………………….
  38

  3.4.30. wifi_set_ip_info
  …………………………………………………………………….
  39

  3.4.31. wifi_set_macaddr
  ………………………………………………………………….
  40

  3.4.32. wifi_get_macaddr
  ………………………………………………………………….
  40

  3.4.33. wifi_set_sleep_type
  ……………………………………………………………….
  41

  3.4.34. wifi_get_sleep_type
  ……………………………………………………………….
  41

  3.4.35. wifi_status_led_install
  ……………………………………………………………
  42

  3.4.36. wifi_status_led_uninstall
  ………………………………………………………..
  42

  3.5. Upgrade(FOTA) APIs
  ……………………………………………………………….
  43

  3.5.1. system_upgrade_userbin_check
  …………………………………………….. 43

  3.5.2. system_upgrade_flag_set
  ……………………………………………………….
  43

  3.5.3.
  system_upgrade_flag_check……………………………………………………
  44

  3.5.4. system_upgrade_start
  ……………………………………………………………
  44

  3.5.5. system_upgrade_reboot
  …………………………………………………………
  44

  3.6. Sniffer Related APIs
  ………………………………………………………………..
  45

  3.6.1. wifi_promiscuous_enable
  ……………………………………………………….
  45

  3.6.2. wifi_set_promiscuous_rx_cb
  ………………………………………………….. 45

  3.6.3. wifi_get_channel
  ……………………………………………………………………
  45

  3.6.4. wifi_set_channel
  ……………………………………………………………………
  46

  3.7. smart config APIs
  …………………………………………………………………..
  46

• ESP8266EX SDK Programming Guide

  6 / 95 Espressif Systems February 9, 2015

  3.7.1. smartconfig_start
  …………………………………………………………………..
  46

  3.7.2. smartconfig_stop
  …………………………………………………………………..
  47

  3.7.3. get_smartconfig_status
  ………………………………………………………….
  48

  3.8. Network APIs
  …………………………………………………………………………
  49

  3.8.1. General APIs
  ………………………………………………………………………….
  49

  3.8.1.1. espconn_delete
  …………………………………………………………….
  49

  3.8.1.2. espconn_gethostbyname
  ……………………………………………… 49

  3.8.1.3. espconn_port
  ………………………………………………………………..
  50

  3.8.1.4. espconn_regist_sentcb
  ………………………………………………… 51

  3.8.1.5. espconn_regist_recvcb
  ………………………………………………… 51

  3.8.1.6. espconn_sent_callback
  ………………………………………………… 52

  3.8.1.7. espconn_recv_callback
  ………………………………………………… 52

  3.8.1.8. espconn_sent
  ………………………………………………………………..
  53

  3.8.2. TCP
  APIs………………………………………………………………………………..
  53

  3.8.2.1. espconn_accept
  ……………………………………………………………
  53

  3.8.2.2. espconn_secure_accept
  ………………………………………………. 54

  3.8.2.3. espconn_regist_time
  ……………………………………………………..
  54

  3.8.2.4. espconn_get_connection_info
  ……………………………………… 55

  3.8.2.5. espconn_connect
  ………………………………………………………….
  55

  3.8.2.6. espconn_connect_callback
  ………………………………………….. 55

  3.8.2.7. espconn_set_opt
  …………………………………………………………..
  56

  3.8.2.8. espconn_disconnect
  ……………………………………………………..
  57

  3.8.2.9. espconn_regist_connectcb
  …………………………………………… 57

  3.8.2.10. espconn_regist_reconcb
  ………………………………………………. 57

  3.8.2.11. espconn_regist_disconcb
  …………………………………………….. 58

  3.8.2.12. espconn_secure_connect
  …………………………………………….. 59

  3.8.2.13. espconn_secure_sent
  ………………………………………………….. 59

  3.8.2.14. espconn_secure_disconnect
  ………………………………………… 60

  3.8.2.15. espconn_tcp_get_max_con
  ………………………………………….. 60

  3.8.2.16. espconn_tcp_set_max_con
  ………………………………………….. 60

  3.8.2.17. espconn_tcp_get_max_con_allow
  ……………………………….. 61

  3.8.2.18. espconn_tcp_set_max_con_allow
  ……………………………….. 61

  3.8.2.19. espconn_recv_hold
  ……………………………………………………….
  62

  3.8.2.20. espconn_recv_unhold
  ………………………………………………….. 62

  3.8.3. UDP APIs
  ………………………………………………………………………………
  63

  3.8.3.1. espconn_create
  …………………………………………………………….
  63

  3.8.3.2. espconn_igmp_join
  ……………………………………………………….
  63

  3.8.3.3. espconn_igmp_leave
  …………………………………………………….
  64

  3.9. AT APIs
  ………………………………………………………………………………….
  65

  3.9.1. at_response_ok
  ……………………………………………………………………..
  65

  3.9.2. at_response_error
  …………………………………………………………………
  65

  3.9.3. at_cmd_array_regist
  ………………………………………………………………
  65

  3.9.4. at_get_next_int_dec
  ………………………………………………………………
  66

• ESP8266EX SDK Programming Guide

  7 / 95 Espressif Systems February 9, 2015

  3.9.5. at_data_str_copy
  …………………………………………………………………..
  66

  3.9.6. at_init
  …………………………………………………………………………………..
  67

  3.9.7. at_port_print
  ………………………………………………………………………..
  67

  3.10. json APIs
  ……………………………………………………………………………….
  68

  3.10.1. jsonparse_setup
  …………………………………………………………………….
  68

  3.10.2. jsonparse_next
  ………………………………………………………………………
  68

  3.10.3. jsonparse_copy_value
  ……………………………………………………………
  68

  3.10.4. jsonparse_get_value_as_int
  …………………………………………………… 69

  3.10.5.
  jsonparse_get_value_as_long………………………………………………….
  69

  3.10.6. jsonparse_get_len
  ………………………………………………………………….
  69

  3.10.7. jsonparse_get_value_as_type
  ………………………………………………… 70

  3.10.8. jsonparse_strcmp_value
  …………………………………………………………
  70

  3.10.9. jsontree_set_up
  …………………………………………………………………….
  70

  3.10.10. jsontree_reset
  ……………………………………………………………………….
  71

  3.10.11. jsontree_path_name
  ……………………………………………………………..
  71

  3.10.12. jsontree_write_int
  …………………………………………………………………
  72

  3.10.13. jsontree_write_int_array
  ………………………………………………………..
  72

  3.10.14. jsontree_write_string
  …………………………………………………………….
  72

  3.10.15. jsontree_print_next
  ……………………………………………………………….
  73

  3.10.16. jsontree_find_next
  …………………………………………………………………
  73

  4. Structure definition
  ………………………………………………………………
  74

  4.1. Timer
  ……………………………………………………………………………………
  74

  4.2. Wifi related structure
  ……………………………………………………………..
  74

  4.2.1. station related
  ……………………………………………………………………….
  74

  4.2.2. softap related
  ………………………………………………………………………..
  75

  4.2.3. scan related
  …………………………………………………………………………..
  75

  4.3. smart config structure
  …………………………………………………………….
  76

  4.4. json related structure
  ……………………………………………………………..
  77

  4.3.1. json structure
  ………………………………………………………………………..
  77

  4.3.2. json macro definition
  ……………………………………………………………..
  78

  4.5. espconn parameters
  ………………………………………………………………
  79

  4.4.1 callback function
  ……………………………………………………………………
  79

  4.4.2 espconn
  ………………………………………………………………………………..
  79

  5. Driver
  …………………………………………………………………………………..
  82

  5.1. GPIO APIs
  ……………………………………………………………………………..
  82

  5.1.1. PIN setting macro
  …………………………………………………………………..
  82

  5.1.2. gpio_output_set
  ……………………………………………………………………
  82

  5.1.3. GPIO input and output macro
  …………………………………………………. 83

  5.1.4. GPIO interrupt
  ……………………………………………………………………….
  83

  5.1.5. gpio_pin_intr_state_set
  ………………………………………………………….
  84

  5.1.6. GPIO interrupt handler
  …………………………………………………………..
  84

  5.2. UART APIs
  ……………………………………………………………………………..
  84

  5.2.1. uart_init
  ……………………………………………………………………………….
  85

• ESP8266EX SDK Programming Guide

  8 / 95 Espressif Systems February 9, 2015

  5.2.2. uart0_tx_buffer
  ……………………………………………………………………..
  85

  5.2.3. uart0_rx_intr_handler
  ……………………………………………………………
  86

  5.3. i2c master APIs
  ………………………………………………………………………
  86

  5.3.1. i2c_master_gpio_init
  ……………………………………………………………..
  86

  5.3.2. i2c_master_init
  ……………………………………………………………………..
  86

  5.3.3. i2c_master_start
  ……………………………………………………………………
  87

  5.3.4. i2c_master_stop
  ……………………………………………………………………
  87

  5.3.5. i2c_master_send_ack
  …………………………………………………………….
  87

  5.3.6. i2c_master_send_nack
  …………………………………………………………..
  88

  5.3.7. i2c_master_checkAck
  …………………………………………………………….
  88

  5.3.8. i2c_master_readByte
  ……………………………………………………………..
  88

  5.3.9. i2c_master_writeByte
  …………………………………………………………….
  89

  5.4. pwm
  …………………………………………………………………………………….
  90

  5.4.1. pwm_init
  ………………………………………………………………………………
  90

  5.4.2. pwm_start
  …………………………………………………………………………….
  90

  5.4.3. pwm_set_duty
  ………………………………………………………………………
  90

  5.4.4. pwm_set_freq
  ……………………………………………………………………….
  91

  5.4.5. pwm_get_duty
  ………………………………………………………………………
  91

  5.4.6.
  pwm_get_freq……………………………………………………………………….
  91

  6. Appendix
  ……………………………………………………………………………..
  92

  A. ESPCONN Programming
  ………………………………………………………….
  92

  A.1. TCP Client Mode
  …………………………………………………………………….
  92

  A.1.1. Instructions
  …………………………………………………………………………..
  92

  A.1.2. Steps
  …………………………………………………………………………………….
  92

  A.2. TCP Server Mode
  ……………………………………………………………………
  93

  A.2.1. Instructions
  …………………………………………………………………………..
  93

  A.2.2. Steps
  …………………………………………………………………………………….
  93

  B. RTC APIs Example
  …………………………………………………………………..
  93

• ESP8266EX SDK Programming Guide

  9 / 95 Espressif Systems February 9, 2015

  1. Foreword

  The SDK based on ESP8266 IoT platform offers users an easy, fast
  and

  efficient way to develop IoT devices.

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

• ESP8266EX SDK Programming Guide

  10 / 95 Espressif Systems February 9, 2015

  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 usre_init(void) is the default method provided. Users can
  add

  functions like firmware initialization, network parameters
  setting, and timer

  initialization in the interface.

  The SDK provides an API to handle json, and users can also use
  self-

  defined data types to handle the them.

• ESP8266EX SDK Programming Guide

  11 / 95 Espressif Systems February 9, 2015

  3. Application Programming Interface

  (APIs)

  3.1. Timer

  Locate in esp_iot_sdkincludeosapi.h

  3.1.1. os_timer_arm

  Function: arm timer

  Prototype:

  void os_timer_arm(ETSTimer *ptimer, uint32_t milliseconds,

  boolrepeat_flag)

  Input parameters:

  ETSTimer*ptimerTimer structure

  uint32_t millisecondsTiming, Unit: milisecond

  boolrepeat_flagWhether to repeat the timing

  Return:

  null

  3.1.2. os_timer_disarm

  Function: Disarm timer

  Prototype:

  void os_timer_disarm (ETSTimer *ptimer)

  Input parameters:

  ETSTimer*ptimerTimer structure

  Return:

  null

• ESP8266EX SDK Programming Guide

  12 / 95 Espressif Systems February 9, 2015

  3.1.3. os_timer_setfn

  Function: Set timer callback function

  Prototype:

  void os_timer_setfn (ETSTimer *ptimer, ETSTimerFunc *pfunction,
  void

  *parg)

  Input parameters:

  ETSTimer*ptimerTimer structure

  TESTimerFunc*pfunctiontimer callback function

  void*pargcallback function parameter

  Return:

  null

  3.2. System APIs

  3.2.1. system_restore

  Function: Reset to default settings

  Prototype:

  void system_restore(void)

  Input parameters:

  null

  Return:

  null

  3.2.2. system_restart

  Function: Restart

  Prototype:

  void system_restart(void)

  Input parameters:

• ESP8266EX SDK Programming Guide

  13 / 95 Espressif Systems February 9, 2015

  null

  Return:

  null

  3.2.3. system_timer_reinit

  Function: Reinitiate the timer when you need to use microsecond
  timer

  Not es: 1. Define USE_US_TIMER;

  2. Put system_timer_reinit at the beginning and user_init in the
  first

  sentence.

  Function definition:

  void system_timer_reinit (void)

  Input parameters:

  null

  Return:

  Null

  3.2.4. system_init_done_cb

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

  Notewifi_station_scan need 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

• ESP8266EX SDK Programming Guide

  14 / 95 Espressif Systems February 9, 2015

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

  }

  3.2.5. system_get_chip_id

  Function: Get chip id

  Prototype:

  uint32 system_get_chip_id (void)

  Input parameters:

  null

  Return:

  Chip id

  3.2.6. system_deep_sleep

  Function: Set for deep-sleep mode. Device in deep-sleep mode
  automatically,

  every X us wake up once. Everytime device wakes up, it starts
  from user_init.

  Prototype

  void system_deep_sleep(uint32 time_in_us)

  parameters

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

  Return

• ESP8266EX SDK Programming Guide

  15 / 95 Espressif Systems February 9, 2015

  NULL

  Note:

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

  EXT_RSTB with 0R).

  system_deep_sleep(0) set no wake up timerconnect a GPIO to pin
  RST,

  the chip will wake up by a falling-edge on pin RST

  3.2.7. system_deep_sleep_set_option

  Function: Call this API before system_deep_sleep to set what the
  chip will do

  when deep-sleep wake up.

  Note: following init data means esp_init_data_default.bin.

  Prototype

  bool system_deep_sleep_set_option(uint8 option)

  Parameter

  uint8 option — option=0, init data byte 108 is valuable;

  option>0, init data byte 108 is valueless.

  More details as follows

  deep_sleep_set_option(0), RF_CAL or not after deep-sleep wake
  up,

  depends on init data byte 108.

  deep_sleep_set_option(1), RF_CAL after deep-sleep wake up, there
  will be

  large current.

  deep_sleep_set_option(2) , no RF_CAL after deep-sleep wake up,
  there will

  only be small current.

  deep_sleep_set_option(4) , disable RF after deep-sleep wake up,
  just like

  modem sleep, there will be the smallest current.

  Return:

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  16 / 95 Espressif Systems February 9, 2015

  3.2.8. system_set_os_print

  Function: Turn on/off print logFunction

  Function definition:

  void system_set_os_print (uint8onoff)

  Input parameters:

  uint8 onoff turn on/off print function;

  0x00 : print function off

  0x01: print function on

  Defaut: print function on

  Return:

  null

  3.2.9. system_print_meminfo

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

  Function definition:

  void system_print_meminfo (void)

  Input parameters:

  null

  Return:

  null

  3.2.10. system_get_free_heap_size

  Function: Get free heap size

  Function definition:

  uint32 system_get_free_heap_size(void)

  Input parameters:

  null

  Return:

• ESP8266EX SDK Programming Guide

  17 / 95 Espressif Systems February 9, 2015

  uint32 available heap size

  3.2.11. system_os_task

  Function: Set up tasks

  Function definition:

  bool system_os_task(os_task_t task, uint8 prio, os_event_t
  *queue,

  uint8 qlen)

  Input parameters:

  os_task_t tasktask function

  uint8 priotask priority. 3 priorities are supported, 0/1/2, 0 is
  the lowest

  priority.

  os_event_t *queuemessage queue pointer

  uint8 qlenmessage 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 %cn, (char)e->par);

  break;

  default:

  break;

  }

• ESP8266EX SDK Programming Guide

  18 / 95 Espressif Systems February 9, 2015

  }

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

  }

  3.2.12. system_os_post

  Function: send message to task

  Function definition:

  bool system_os_post (uint8 prio, os_signal_t sig, os_param_t
  par)

  Input parameters:

  uint8 priotask priority, corresponding to that you set up

  os_signal_t sigmessage type

  os_param_t parmessage parameters

  Return

  True — succeed

  False — fail.

  Refer to the example above:

  void task_post(void)

  {

  system_os_post(USER_TASK_PRIO_0, SIG_RX, a);

  }

  Printout: sig_rx a

  3.2.13. system_get_time

  FunctionGet system time (us).

  Prototype

• ESP8266EX SDK Programming Guide

  19 / 95 Espressif Systems February 9, 2015

  uint32 system_get_time(void)

  Parameter

  Null

  Return

  System time in us.

  3.2.14. system_get_rtc_time

  FunctionGet RTC time , count by RTC clock period.

  Example: If system_get_rtc_time returns 10 (means 10 RTC
  cycles),

  system_rtc_clock_cali_proc returns 5 (means 5us per RTC cycle),
  then real

  time is 10 x 5 = 50 us.

  Note: System time will return to zero because of deep sleep or
  system_restart,

  but RTC still goes on.

  Prototype

  uint32 system_get_rtc_time(void)

  Parameter

  Null

  Return

  RTC time.

  3.2.15. system_rtc_clock_cali_proc

  Function: Get RTC clock period.

  Prototype

  uint32 system_rtc_clock_cali_proc(void)

  Parameter

  Null

  Return

• ESP8266EX SDK Programming Guide

  20 / 95 Espressif Systems February 9, 2015

  RTC clock period (in us), bit11~ bit0 are decimal.

  Note: RTC demo in Appendix.

  3.2.16. 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 succeedFalsefail.

  3.2.17. system_rtc_mem_read

  Function: Read user data from RTC memory. Only user data area
  here can

  be used by user.

  |_ _ _ _ _system data _ _ _ _ _|_ _ _ _ _ _ _ _ _ user data _ _
  _ _ _ _ _ _ _|

  | 256 bytes | 512 bytes |

• ESP8266EX SDK Programming Guide

  21 / 95 Espressif Systems February 9, 2015

  Note: RTC memory is 4 bytes aligned for read and write
  operations. Parameter

  src_addr means block number(4 bytes per block). So, if we want
  to read some

  data from the beginning of user data area, src_addr will be
  256/4 = 64,

  save_size will be data length.

  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 lengthbyte

  Return

  True succeedFalsefail.

  3.2.18. system_uart_swap

  Function: UART0 swap. Use MTCK as UART0 RXMTDO as UART0 TX,
  so

  ROM log wont 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

  3.2.19. system_adc_read

  Function: Get the value of ADC.

• ESP8266EX SDK Programming Guide

  22 / 95 Espressif Systems February 9, 2015

  Prototype

  Uint16 system_adc_read (void)

  Paratmeter

  NULL

  Return

  Value of ADC.

  3.3. SPI Flash Related APIs

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

  3.3.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{

• ESP8266EX SDK Programming Guide

  23 / 95 Espressif Systems February 9, 2015

  SPI_FLASH_RESULT_OK,

  SPI_FLASH_RESULT_ERR,

  SPI_FLASH_RESULT_TIMEOUT

  }SpiFlashOpResult

  3.3.3. spi_flash_write

  FunctionWrite data to flash

  Note: More details in document

  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

  3.3.4. spi_flash_read

  Function Read data from flash.

  Note: More details in document

• ESP8266EX SDK Programming Guide

  24 / 95 Espressif Systems February 9, 2015

  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

• ESP8266EX SDK Programming Guide

  25 / 95 Espressif Systems February 9, 2015

  3.4. WIFI Related APIs

  3.4.1. wifi_get_opmode

  Function: get wifi working mode

  Function definition:

  uint8 wifi_get_opmode (void)

  Input parameters:

  null

  Return:

  Wifi working modes:

  0x01 means STATION_MODE,

  0x02 means SOFTAP_MODE,

  0x03 means STATIONAP_MODE.

  3.4.2. wifi_set_opmode

  Function: set wifi working mode as STATION, SOFTAP or
  STATION+SOFTAP

  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.

  Function definition:

  bool wifi_set_opmode (uint8 opmode)

  Input parameters:

  uint8 opmodeWifi working modes: 0x01 means STATION_MODE,

  0x02

  means SOFTAP_MODE, 0x03 means STATIONAP_MODE.

  Return:

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  26 / 95 Espressif Systems February 9, 2015

  3.4.3. wifi_station_get_config

  Function: get wifi station configuration

  Function definition:

  bool wifi_station_get_config (struct station_config *config)

  Input parameters:

  struct station_config *configwifi station configuration
  pointer

  Return:

  True — succeed

  False — fail.

  3.4.4. wifi_station_set_config

  Function: Set wifi station configuration

  Note: 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.

  Function definition:

  bool wifi_station_set_config (struct station_config *config)

  Input parameters:

  struct station_config *configwifi station configuration
  pointer

  Return:

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  27 / 95 Espressif Systems February 9, 2015

  3.4.5. wifi_station_connect

  Function: wifi station connected AP

  Noteif ESP8266 has already connected to a routerits necessary to
  call

  wifi_station_disconnect firstthen call wifi_station_connect to
  connect.

  Function definition:

  bool wifi_station_connect (void)

  Input parameters:

  null

  Return:

  True — succeed

  False — fail.

  3.4.6. wifi_station_disconnect

  Function: wifi station disconnected AP

  Function definition:

  bool wifi_station_disconnect (void)

  Input parameters:

  null

  Return:

  True — succeed

  False — fail.

  3.4.7. wifi_station_get_connect_status

  Function: get the connection status between wifi station and
  AP

  Function definition:

  uint8 wifi_station_get_connect_status (void)

• ESP8266EX SDK Programming Guide

  28 / 95 Espressif Systems February 9, 2015

  Input parameters:

  null

  Return:

  enum{

  STATION_IDLE = 0,

  STATION_CONNECTING,

  STATION_WRONG_PASSWORD,

  STATION_NO_AP_FOUND,

  STATION_CONNECT_FAIL,

  STATION_GOT_IP

  };

  3.4.8. wifi_station_scan

  Function: Scan AP

  Note: Do not call this API in user_init. This API need to be
  called after system

  initialize done and station enable.

  Function definition:

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

  Structure

  struct scan_config{

  uint8 *ssid; // APs ssid

  uint8 *bssid; // APs 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.ssidconfig.bssid are nullconfig.channel isnt null,
  ESP8266

• ESP8266EX SDK Programming Guide

  29 / 95 Espressif Systems February 9, 2015

  will scan the specific channel.

  scan_done_cb_t cb — callback function after scan

  Return:

  True — succeed

  False — fail.

  3.4.9. scan_done_cb_t

  Function: scan callback function

  Function definition:

  void scan_done_cb_t (void *arg, STATUS status);

  Input parameters:

  void *arginformation of APs that be found, refer to struct
  bss_info

  STATUS statusget status

  Return:

  NULL

  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

  }

  }

• ESP8266EX SDK Programming Guide

  30 / 95 Espressif Systems February 9, 2015

  3.4.10. wifi_station_ap_number_set

  Function: Set the number of APs that can be recorded for ESP8266
  station.

  When ESP8266 station connects to an AP, ESP8266 keeps a record
  of this AP.

  Record id starts counting from 0.

  Prototype

  bool wifi_station_ap_number_set (uint8 ap_number);

  Parameters

  uint8 ap_number how many APs can be recordedMAX: 5

  eg: if ap_number is 5, record id : 0 ~ 4

  Return

  True — succeed

  False — fail.

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

  How many APs that is actually recorded.

  Example

  struct station_config config[5];

  int i = wifi_station_get_ap_info(config);

• ESP8266EX SDK Programming Guide

  31 / 95 Espressif Systems February 9, 2015

  3.4.12. wifi_station_ap_change

  Function: ESP8266 station change to connect to the AP which is
  recorded in

  specific id.

  Prototype

  bool wifi_station_ap_change (uint8 current_ap_id);

  Parameters

  uint8 current_ap_id APs record id, start counting from 0.

  Return

  True — succeed

  False — fail.

  3.4.13. 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 record id of the AP which ESP8266 is connected with right
  now.

  3.4.14. wifi_station_get_auto_connect

  Function: Check whether ESP8266 station will connect to AP
  (which is

  recorded) automatically or not when power on.

  Prototype

  uint8 wifi_station_get_auto_connect(void)

  Parameter

  Null

  Return

• ESP8266EX SDK Programming Guide

  32 / 95 Espressif Systems February 9, 2015

  0 , wont connect to AP automatically

  Non-0 , will connect to AP automatically.

  3.4.15. wifi_station_set_auto_connect

  Function: Set whether ESP8266 station will connect to AP (which
  is recorded)

  automatically or not when power on.

  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.

  Prototype

  bool wifi_station_set_auto_connect(uint8 set)

  Parameter

  uint8 set Automatically connect or not

  0wont connect automatically1will connect automatically.

  Return

  True succeedFalse fail.

  3.4.16. wifi_station_dhcpc_start

  FunctionEnable ESP8266 station dhcp client.

  NoteDHCP default enable

  Prototype

  bool wifi_station_dhcpc_start(void)

  Parameter

  Null

  Return

  True succeedFalse fail.

  3.4.17. wifi_station_dhcpc_stop

  FunctionDisable ESP8266 station dhcp client.

  NoteDHCP default enable.

• ESP8266EX SDK Programming Guide

  33 / 95 Espressif Systems February 9, 2015

  Prototype

  bool wifi_station_dhcpc_stop(void)

  Parameter

  Null

  Return

  True succeedFalse fail.

  3.4.18. wifi_station_dhcpc_status

  FunctionGet ESP8266 station dhcp client status.

  Prototype

  enum dhcp_status wifi_station_dhcpc_status(void)

  Parameter

  Null

  Return

  enum dhcp_status {

  DHCP_STOPPED,

  DHCP_STARTED

  };

  3.4.19. wifi_softap_get_config

  Function: set wifi softap configuration

  Function definition:

  bool wifi_softap_get_config(struct softap_config *config)

  Parameter

  struct softap_config *configESP8266 softap config

  Return

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  34 / 95 Espressif Systems February 9, 2015

  3.4.20. wifi_softap_set_config

  Function: set wifi softap configuration

  Function definition:

  bool wifi_softap_set_config (struct softap_config *config)

  Parameter

  struct softap_config *config wifi softap configuration
  pointer

  Return

  True — succeed

  False — fail.

  3.4.21. wifi_softap_get_station_info

  Function: get connected station devices under softap mode,
  including mac

  and ip

  Function definition

  struct station_info * wifi_softap_get_station_info(void)

  Input parameters:

  null

  Return:

  struct station_info*station information structure

  3.4.22. wifi_softap_free_station_info

  Function: free the struct station_info by calling the
  wifi_softap_get_station_info

  function

  Function definition:

  void wifi_softap_free_station_info(void)

  Input parameters:

  null

  Return:

• ESP8266EX SDK Programming Guide

  35 / 95 Espressif Systems February 9, 2015

  null

  Examples of getting mac and ip information:

  Method 1:

  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;

  }

  Method 2

  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

  3.4.23. wifi_softap_dhcps_start

  FunctionEnable ESP8266 softAP dhcp server.

  NoteDHCP default enable.

  Prototype

  bool wifi_softap_dhcps_start(void)

  Parameter

  Null

  Return

• ESP8266EX SDK Programming Guide

  36 / 95 Espressif Systems February 9, 2015

  True — succeed

  False — fail.

  3.4.24. wifi_softap_dhcps_stop

  FunctionDisable ESP8266 softAP dhcp server.

  NoteDHCP default enable.

  Prototype

  bool wifi_softap_dhcps_stop(void)

  Parameter

  Null

  Return

  True — succeed

  False — fail.

  3.4.25. wifi_softap_set_dhcps_lease

  FunctionSet the IP range that can be got from ESP8266 softAP
  dhcp server.

  NoteThis API need to be called during DHCP server disable.

  Prototype

  bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please)

  Parameter

  struct dhcps_lease {

  uint32 start_ip;

  uint32 end_ip;

  };

  Return

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  37 / 95 Espressif Systems February 9, 2015

  3.4.26. wifi_softap_dhcps_status

  FunctionGet ESP8266 softAP dhcp server status.

  Prototype

  enum dhcp_status wifi_softap_dhcps_status(void)

  Parameter

  NULL

  Return

  enum dhcp_status {

  DHCP_STOPPED,

  DHCP_STARTED

  };

  3.4.27. wifi_set_phy_mode

  FuctionSet ESP8266 physical mode802.11b/g/n.

  NoteESP8266 softAP 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.

• ESP8266EX SDK Programming Guide

  38 / 95 Espressif Systems February 9, 2015

  3.4.28. wifi_get_phy_mode

  FunctionGet ESP8266 physical mode802.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

  };

  3.4.29. wifi_get_ip_info

  Function: Get ip info of wifi station or softap interface

  Function definition:

  bool wifi_get_ip_info(uint8 if_index, struct ip_info *info)

  Parameters:

  uint8 if_indexthe interface to get ip info: 0x00 for STATION_IF,
  0x01

  for

  SOFTAP_IF.

  struct ip_info *infopointer to get ip info of a certain
  interface

  Return

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  39 / 95 Espressif Systems February 9, 2015

  3.4.30. wifi_set_ip_info

  Function: Set ip address of ESP8266 station or softAP

  Note: only can be used in user_init.

  Function definition:

  bool wifi_set_ip_info(uint8 if_index, struct ip_info *info)

  Prototype

  uint8 if_index set station ip or softAP ip

  #define STATION_IF 0x00

  #define SOFTAP_IF 0x01

  struct ip_info *info ip information

  Example

  struct ip_info info;

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

  Return

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  40 / 95 Espressif Systems February 9, 2015

  3.4.31. wifi_set_macaddr

  Function: set mac address

  Note: only can be used in user_init

  Function definition:

  bool wifi_set_macaddr(uint8 if_index, uint8 *macaddr)

  Parameter

  uint8 if_index set station mac or softAP 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.

  3.4.32. wifi_get_macaddr

  Function: get mac address

  Function definition:

  Bool wifi_get_macaddr(uint8 if_index , uint8 *macaddr)

  Parameter

  uint8 if_index set station mac or softAP mac

  #define STATION_IF 0x00

  #define SOFTAP_IF 0x01

• ESP8266EX SDK Programming Guide

  41 / 95 Espressif Systems February 9, 2015

  uint8 *macaddr mac address

  Return

  True — succeed

  False — fail.

  3.4.33. wifi_set_sleep_type

  FunctionSet sleep type for power saving. Set NONE_SLEEP_T to
  disable

  power saving

  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 succeedFalse fail.

  3.4.34. wifi_get_sleep_type

  Function: Get 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

  };

• ESP8266EX SDK Programming Guide

  42 / 95 Espressif Systems February 9, 2015

  3.4.35. wifi_status_led_install

  Function: Install wifi status LED

  Function definition:

  Void wifi_status_led_install (uint8 gpio_id, uint32 gpio_name,
  uint8

  gpio_func)

  Parameter

  uint8 gpio_idgpio number

  uint8 gpio_namegpio mux name

  uint8 gpio_funcgpio function

  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)

  3.4.36. wifi_status_led_uninstall

  Function: Uninstall wifi status LED

  Function definition:

  Void wifi_status_led_uninstall ()

  Parameter

  NULL

  Return

  NULL

• ESP8266EX SDK Programming Guide

  43 / 95 Espressif Systems February 9, 2015

  3.5. Upgrade(FOTA) APIs

  3.5.1. system_upgrade_userbin_check

  Function: Check userbin

  Function definition:

  uint8 system_upgrade_userbin_check()

  Input parameters:

  null

  Return:

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

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

  3.5.2. system_upgrade_flag_set

  Function: Set 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

• ESP8266EX SDK Programming Guide

  44 / 95 Espressif Systems February 9, 2015

  3.5.3. system_upgrade_flag_check

  Function: Get upgrade status flag.

  Prototype

  uint8 system_upgrade_flag_check()

  Parameter

  NULL

  Return

  #define UPGRADE_FLAG_IDLE 0x00

  #define UPGRADE_FLAG_START 0x01

  #define UPGRADE_FLAG_FINISH 0x02

  3.5.4. system_upgrade_start

  Function: Configure parameters and start upgrade

  Function definition:

  bool system_upgrade_start (struct upgrade_server_info
  *server)

  Parameters:

  struct upgrade_server_info *server server related parameters

  Return

  true: start upgrade

  false: upgrade cant be started.

  3.5.5. system_upgrade_reboot

  Function: reboot system and use new version

  Function definition:

  void system_upgrade_reboot (void)

  Input parameters:

  null

  Return:

• ESP8266EX SDK Programming Guide

  45 / 95 Espressif Systems February 9, 2015

  Null

  3.6. Sniffer Related APIs

  3.6.1. wifi_promiscuous_enable

  Function: Enable promiscuous mode for sniffer

  Function definition:

  Void wifi_promiscuous_enable(uint8 promiscuous)

  Parameter

  uint8 promiscuous 0, disable promiscuous

  1, enable promiscuous

  Return:

  null

  Example: apply for a demo of sniffer function from Espressif

  3.6.2. wifi_set_promiscuous_rx_cb

  Function: register a rx callback function in promiscuous mode,
  which will be

  called when data packet is received.

  Function definition:

  Void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb)

  Parameter

  wifi_promiscuous_cb_t cb callback

  Return:

  null

  3.6.3. wifi_get_channel

  Function: get channel number, for sniffer

  Function definition:

• ESP8266EX SDK Programming Guide

  46 / 95 Espressif Systems February 9, 2015

  uint8 wifi_get_channel(void)

  parameters:

  null

  Return:

  Channel number

  3.6.4. wifi_set_channel

  Function: set channel number, for sniffer

  Function definition:

  bool wifi_set_channel (uint8 channel)

  Parameters

  uint8 channel channel number

  Return

  True — succeed

  False — fail.

  3.7. smart config APIs

  3.7.1. smartconfig_start

  FunctionMake ESP8266 station connect to AP

  NoteIn this APIESP8266 will be set to station mode. Run phone
  APP to

  make device listen to the SSID and password of targeting AP. Can
  not call

  smartconfig_start twice before it finish.

  Prototype

  bool smartconfig_start(sc_type type, sc_callback_t cb)

  Parameter

  sc_type type smart config protocol typeAirKiss or ESP-TOUCH

  sc_callback_t cb smart config callbackgo into it when ESP8266
  got

  SSID and password of targeting APparameter of this callback
  refer to the

• ESP8266EX SDK Programming Guide

  47 / 95 Espressif Systems February 9, 2015

  examplea pointer of struct station_config

  Return

  True — succeed

  False — fail.

  Example

  void ICACHE_FLASH_ATTR

  smartconfig_done(void *data)

  {

  struct station_config *sta_conf = data;

  wifi_station_set_config(sta_conf);

  wifi_station_disconnect();

  wifi_station_connect();

  user_devicefind_init();

  user_esp_platform_init();

  }

  smartconfig_start(SC_TYPE_ESPTOUCH,smartconfig_done);

  3.7.2. smartconfig_stop

  Functionstop smart configfree the buffer taken by
  smartconfig_start.

  Note: When connect to AP succeed, this API should be called to
  free memory

  taken by smartconfig_start.

  Prototype

  bool smartconfig_stop(void)

  Parameter

  NULL

  Return

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  48 / 95 Espressif Systems February 9, 2015

  3.7.3. get_smartconfig_status

  Functionget smart config status

  NoteCan not call this API after smartconfig_stopbecause
  smartconfig_stop

  will free memory which contains this smart config status

  Prototype

  sc_status get_smartconfig_status(void)

  Parameter

  NULL

  Return

  typedef enum {

  SC_STATUS_FIND_CHANNEL = 0,

  SC_STATUS_GETTING_SSID_PSWD,

  SC_STATUS_GOT_SSID_PSWD,

  SC_STATUS_LINK,

  } sc_status;

• ESP8266EX SDK Programming Guide

  49 / 95 Espressif Systems February 9, 2015

  3.8. Network APIs

  Locate in esp_iot_sdkincludeespconn.h

  General APIsAPIs can be used for both TCP and UDP .

  TCP APIsAPIs that are only used for TCP.

  UDP APIsAPIs that are only used for UDP.

  3.8.1. General APIs

  3.8.1.1. espconn_delete

  Function: Delete a transmission.

  Note: Correspondence create api : TCP espconn_accept, UDP
  espconn_create

  Prototype

  Sin8 espconn_delete(struct espconn *espconn)

  Parameter

  struct espconn *espconn corresponding connected control
  block

  structure

  Return

  0 — succeed#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

  3.8.1.2. espconn_gethostbyname

  Function: DNS

  Function definition:

  Err_t espconn_gethostbyname(struct espconn *pespconn, const
  char

  *hostname, ip_addr_t *addr, dns_found_callback found)

  Parameters:

  struct espconn *espconncorresponding connected control block

• ESP8266EX SDK Programming Guide

  50 / 95 Espressif Systems February 9, 2015

  structure

  const char *hostnamedomain name string pointer

  ip_addr_t *addrip address

  dns_found_callback foundcallback

  Return:

  Err_tESPCONN_OK

  ESPCONN_INPROGRESS

  ESPCONN_ARG

  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.%dn»,

  *((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_es

  p_platform_dns_found);

  }

  3.8.1.3. espconn_port

  Function: get void ports

  Function definition:

• ESP8266EX SDK Programming Guide

  51 / 95 Espressif Systems February 9, 2015

  uint32 espconn_port(void);

  Input parameters:

  null

  Return:

  uint32id of the port you get

  3.8.1.4. espconn_regist_sentcb

  Function: register data sent function which will be called back
  when data are

  successfully sent.

  Function definition:

  Sint8 espconn_regist_sentcb(struct espconn *espconn,

  espconn_sent_callback sent_cb)

  Parameters

  struct espconn *espconncorresponding connected control block

  structure

  espconn_sent_callback sent_cbregistered callback function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.1.5. espconn_regist_recvcb

  Function: register data receive function which will be called
  back when data are

  received

  Function definition:

  Sint8 espconn_regist_recvcb(struct espconn *espconn,

  espconn_recv_callback recv_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block

• ESP8266EX SDK Programming Guide

  52 / 95 Espressif Systems February 9, 2015

  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.1.6. espconn_sent_callback

  Function: callback after the data are sent

  Function definition:

  void espconn_sent_callback (void *arg)

  Input parameters:

  void *argcall back function parameters

  Return:

  null

  3.8.1.7. espconn_recv_callback

  Function: callback after data are received

  Function definition:

  void espconn_recv_callback (void *arg, char *pdata, unsigned
  short len)

  Input parameters:

  void *argcallback function parameters

  char *pdatareceived data entry parameters

  unsigned short lenreceived data length

  Return:

  null

• ESP8266EX SDK Programming Guide

  53 / 95 Espressif Systems February 9, 2015

  3.8.1.8. espconn_sent

  Function: send data through wifi

  Note: Please call espconn_sent after espconn_sent_callback of
  the pre-packet.

  Function definition:

  sint8 espconn_sent(struct espconn *espconn, uint8 *psent, uint16
  length)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  uint8 *psentsent data pointer

  uint16 lengthsent data length

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2. TCP APIs

  3.8.2.1. espconn_accept

  Function: listening connection. This function is used when
  create a TCP server.

  Function definition:

  sint8 espconn_accept(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  54 / 95 Espressif Systems February 9, 2015

  3.8.2.2. espconn_secure_accept

  Function: encrypted listening connection. This function is used
  when create a

  TCP server which support SSL.

  Function definition:

  sint8 espconn_secure_accept(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.3. espconn_regist_time

  Function: register timeout interval when ESP8266 is TCP
  server

  Function definition:

  sint8 espconn_regist_time(struct espconn *espconn, uint32
  interval, uint8

  type_flag)

  Input parameters:

  struct espconn *espconncorresponding 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, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  55 / 95 Espressif Systems February 9, 2015

  3.8.2.4. espconn_get_connection_info

  Function: get a connections info in TCP multi-connection
  case

  Function definition:

  sint8 espconn_get_connection_info(struct espconn *espconn,
  remot_info

  **pcon_info, uint8 typeflags)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  remot_info **pcon_infoconnect to client info

  uint8 typeflags 0, regular server;1, ssl server

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.5. espconn_connect

  Function: connect to a TCP server, and ESP8266 is the TCP
  client.

  Function definition:

  sint8 espconn_connect(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.6. espconn_connect_callback

  Function: successful listening(ESP8266 as TCP server) or

• ESP8266EX SDK Programming Guide

  56 / 95 Espressif Systems February 9, 2015

  connection(ESP8266 as TCP client) callback

  Function definition:

  void espconn_connect_callback (void *arg)

  Input parameters:

  void *argcallback function parameters

  Return:

  null

  3.8.2.7. espconn_set_opt

  Function: Set option of TCP connection

  Prototype

  sint8 espconn_set_opt(struct espconn *espconn, uint8 opt)

  Parameter

  struct espconn *espconncorresponding connected control
  structure

  uint8 opt

  0, free memory after TCP disconnection happen need not wait
  2

  minutes

  1disable nalgo algorithm during TCP data transmission, quiken
  the

  data transmission.

  Return

  0 — succeed#define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  Note

  In general, we need not call this API

  If call espconn_set_opt(espconn, 0)please call it in connected
  callback

  If call espconn_set_opt(espconn, 1)please call it before
  disconnect

• ESP8266EX SDK Programming Guide

  57 / 95 Espressif Systems February 9, 2015

  3.8.2.8. espconn_disconnect

  Function: disconnect a TCP connection

  Function definition:

  sint8 espconn_disconnect(struct espconn *espconn);

  Input parameters:

  struct espconn *espconncorresponding connected control
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.9. espconn_regist_connectcb

  Function: register connection function which will be called back
  under

  successful TCP connection

  Function definition:

  Sint8 espconn_regist_connectcb(struct espconn *espconn,

  espconn_connect_callback connect_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.10. espconn_regist_reconcb

  Function: register reconnect callback

  Note: Reconnect callback is more like a network error handler,
  no matter error

• ESP8266EX SDK Programming Guide

  58 / 95 Espressif Systems February 9, 2015

  occurred in any phase, it will go into reconnect callback. For
  example, if

  espconn_sent fail, it will go into reconnect callback as network
  is broken.

  Function definition:

  sint8 espconn_regist_reconcb(struct espconn *espconn,

  espconn_connect_callback recon_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.11. espconn_regist_disconcb

  Function: register disconnection function which will be called
  back under

  successful TCP disconnection

  Function definition:

  Sint8 espconn_regist_disconcb(struct espconn *espconn,

  espconn_connect_callback discon_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  59 / 95 Espressif Systems February 9, 2015

  3.8.2.12. espconn_secure_connect

  Function: Secure connect(SSL) to a TCP server, and ESP8266 is
  the TCP

  client.

  Function definition:

  Sint8 espconn_secure_connect (struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.13. espconn_secure_sent

  Function: send encrypted dataSSL

  Function definition:

  Sint8 espconn_secure_sent (struct espconn *espconn, uint8
  *psent, uint16

  length)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  uint8 *psentsent data pointer

  uint16 lengthsent data length

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  60 / 95 Espressif Systems February 9, 2015

  3.8.2.14. espconn_secure_disconnect

  Function: secure TCP disconnection(SSL)

  Function definition:

  Sint8 espconn_secure_disconnect(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block

  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.15. espconn_tcp_get_max_con

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

  3.8.2.16. espconn_tcp_set_max_con

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

  Prototype

  Sint8 espconn_tcp_set_max_con(uint8 num)

  Parameter

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

  Return:

• ESP8266EX SDK Programming Guide

  61 / 95 Espressif Systems February 9, 2015

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.8.2.17. 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 *espconncorresponding connected control
  structure

  Return:

  Maximum number of TCP clients which are allowed.

  3.8.2.18. espconn_tcp_set_max_con_allow

  Function: Set the maximum number of TCP clients which are
  allowed to

  connect to ESP8266 TCP server.

  Prototype

  Sint8 espconn_tcp_set_max_con_allow(struct espconn *espconn,
  uint8

  num)

  Parameter:

  struct espconn *espconncorresponding connected control
  structure

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

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  62 / 95 Espressif Systems February 9, 2015

  3.8.2.19. espconn_recv_hold

  FunctionBlock TCP receiving data

  NoteThis API block TCP receiving data eventuallynot
  immediatelyso we

  recommended to call it while reserving 1460*5 Bytes memory. This
  API can be

  called more than once.

  Prototype

  Sint8 espconn_recv_hold(struct espconn *espconn)

  Parameter:

  struct espconn *espconncorresponding connected control
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.hESPCONN_ARG means could
  not

  find the TCP connection according to parameter espconn

  3.8.2.20. espconn_recv_unhold

  FunctionStop blocking TCP receiving data

  NoteThis API take effect immediately

  Prototype

  Sint8 espconn_recv_unhold(struct espconn *espconn)

  Parameter:

  struct espconn *espconncorresponding connected control
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.hESPCONN_ARG means could
  not

  find the TCP connection according to parameter espconn

• ESP8266EX SDK Programming Guide

  63 / 95 Espressif Systems February 9, 2015

  3.8.3. UDP APIs

  3.8.3.1. espconn_create

  Functioncreate UDP transmission.

  Prototype

  Sin8 espconn_create(struct espconn *espconn)

  Parameter

  struct espconn *espconn corresponding connected control
  block

  structure

  Return

  0 — succeed#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

  3.8.3.2. espconn_igmp_join

  FunctionJoin a multicast group

  Prototype

  Sin8 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#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

• ESP8266EX SDK Programming Guide

  64 / 95 Espressif Systems February 9, 2015

  3.8.3.3. espconn_igmp_leave

  FunctionQuit a multicast group

  Prototype

  Sin8 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#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

• ESP8266EX SDK Programming Guide

  65 / 95 Espressif Systems February 9, 2015

  3.9. AT APIs

  AT APIs example refer to
  esp_iot_sdk/examples/5.at/user/user_main.c

  3.9.1. at_response_ok

  Functionoutput OK to AT Port (UART0)

  Prototype

  void at_response_ok(void)

  Parameter

  NULL

  Return

  NULL

  3.9.2. at_response_error

  Functionoutput ERROR to AT Port (UART0)

  Prototype

  void at_response_error(void)

  Parameter

  NULL

  Return

  NULL

  3.9.3. at_cmd_array_regist

  Functionregister user-define AT commands

  Prototype

  void at_cmd_array_regist (at_funcation * custom_at_cmd_arrar,
  uint32

  cmd_num)

  Parameter

• ESP8266EX SDK Programming Guide

  66 / 95 Espressif Systems February 9, 2015

  at_funcation * custom_at_cmd_arrar Array of user-define AT
  commands

  uint32 cmd_num Number counts of user-define AT commands

  Return

  NULL

  Examplerefer to esp_iot_sdk/examples/5.at/user/user_main.c

  3.9.4. at_get_next_int_dec

  Functionparse 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 — error code

  1int number is omitreturn error code 1

  3only -be found, return error code 3

  Return

  TRUEparser succeed (if int number default omitit will return
  Truebut

  error code to be 1)

  FALSEparser error with error code, probable causeint number more
  than

  10 bytescontains termination charactersr only contains —

  Example: refer to esp_iot_sdk/examples/5.at/user/user_main.c

  3.9.5. at_data_str_copy

  Functionparse 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

• ESP8266EX SDK Programming Guide

  67 / 95 Espressif Systems February 9, 2015

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

  int32 max_len max string length that allowed

  Return

  If succeedreturns the length of the string

  If failreturns -1

  Example: refer to esp_iot_sdk/examples/5.at/user/user_main.c

  3.9.6. at_init

  Function: AT initialize

  Prototype

  void at_init (void)

  Parameter

  NULL

  Return

  NULL

  Example: refer to esp_iot_sdk/examples/5.at/user/user_main.c

  3.9.7. at_port_print

  Funtion: 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/5.at/user/user_main.c

• ESP8266EX SDK Programming Guide

  68 / 95 Espressif Systems February 9, 2015

  3.10. json APIs

  Locate in : esp_iot_sdkincludejsonjsonparse.h &
  jsontree.h

  3.10.1. jsonparse_setup

  Function:json initialize parsing

  Function definition:

  void jsonparse_setup(struct jsonparse_state *state, const char
  *json, int

  len)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  const char *jsonjson parsing character string

  int lencharacter string length

  Return:

  null

  3.10.2. jsonparse_next

  Function: jsonparse next object

  Function definition:

  int jsonparse_next(struct jsonparse_state *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsing result

  3.10.3. jsonparse_copy_value

  Function: copy current parsing character string to a certain
  buffer

  Function definition:

  int jsonparse_copy_value(struct jsonparse_state *state, char
  *str, int

• ESP8266EX SDK Programming Guide

  69 / 95 Espressif Systems February 9, 2015

  size)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  char *strbuffer pointer

  int sizebuffer size

  Return:

  intcopy result

  3.10.4. jsonparse_get_value_as_int

  Function: parse json to get integer

  Function definition:

  int jsonparse_get_value_as_int(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsing result

  3.10.5. jsonparse_get_value_as_long

  Function: parse json to get long integer

  Function definition:

  long jsonparse_get_value_as_long(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  longparsing result

  3.10.6. jsonparse_get_len

  Function: get parsed json length

  Function definition:

• ESP8266EX SDK Programming Guide

  70 / 95 Espressif Systems February 9, 2015

  int jsonparse_get_value_len(struct jsonparse_state *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsed jason length

  3.10.7. jsonparse_get_value_as_type

  Function: parsed json data type

  Function definition:

  int jsonparse_get_value_as_type(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsed json data type

  3.10.8. jsonparse_strcmp_value

  Function: compare parsed json and certain character string

  Function definition:

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

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  const char *strcharacter buffer

  Return:

  intcomparison result

  3.10.9. jsontree_set_up

  Function: create json data tree

  Function definition:

  void jsontree_setup(struct jsontree_context *js_ctx,

• ESP8266EX SDK Programming Guide

  71 / 95 Espressif Systems February 9, 2015

  struct jsontree_value *root, int (* putchar)(int))

  Input parameters:

  struct jsontree_context *js_ctxjson tree element pointer

  struct jsontree_value *rootroot element pointer

  int (* putchar)(int)input function

  Return:

  null

  3.10.10. jsontree_reset

  Function: reset json tree

  Function definition:

  void jsontree_reset(struct jsontree_context *js_ctx)

  Input parameters:

  struct jsontree_context *js_ctxjson data tree pointer

  Return:

  null

  3.10.11. jsontree_path_name

  Function: get json tree parameters

  Function definition:

  const char *jsontree_path_name(const struct jsontree_cotext
  *js_ctx, int

  depth)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int depthjson tree depth

  Return:

  char*parameter pointer

• ESP8266EX SDK Programming Guide

  72 / 95 Espressif Systems February 9, 2015

  3.10.12. jsontree_write_int

  Function: write integer to joson tree

  Function definition:

  void jsontree_write_int(const struct jsontree_context *js_ctx,
  int value)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int valueinteger value

  Return:

  null

  3.10.13. jsontree_write_int_array

  Function: write integer array to json tree

  Function definition:

  void jsontree_write_int_array(const struct jsontree_context
  *js_ctx, const

  int *text, uint32 length)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int *textarray entry address

  uint32 lengtharray length

  Return:

  null

  3.10.14. jsontree_write_string

  Function: write string to json tree

  Function definition:

  void jsontree_write_string(const struct jsontree_context
  *js_ctx, const

  char *text)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

• ESP8266EX SDK Programming Guide

  73 / 95 Espressif Systems February 9, 2015

  const char* textcharacter string pointer

  Return:

  null

  3.10.15. jsontree_print_next

  Function: json tree depth

  Function definition:

  int jsontree_print_next(struct jsontree_context *js_ctx)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  Return:

  intjson tree depth

  3.10.16. jsontree_find_next

  Function: find json tree element

  Function definition:

  struct jsontree_value *jsontree_find_next(struct
  jsontree_context *js_ctx,

  int type)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  inttype

  Return:

  struct jsontree_value *json tree element pointer

• ESP8266EX SDK Programming Guide

  74 / 95 Espressif Systems February 9, 2015

  4. Structure definition

  4.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;

  4.2. Wifi related structure

  4.2.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 serveral APs have
  the same

  ssid.

  If station_config.bssid_set

• ESP8266EX SDK Programming Guide

  1 / 64 Espressif Systems June 19, 2014

  Espressif IoT SDK:

  Programming Guide

  Status Released

  Current version V0.9.1

  Author Fei Yu

  Completion Date 2014.9.23

  Reviewer Jiangang Wu

  Completion Date 2014.9.23

  [ ] CONFIDENTIAL

  [ ] INTERNAL

  [ ] PUBLIC

• ESP8266EX SDK Programming Guide

  2 / 64 Espressif Systems June 19, 2014

  Version Info

  Date Version Author Comments/Changes

  2013.12.25 0.1 Jiangang Wu Draft

  2013.12.25 0.1.1 Han Liu Revise Json APIs

  2014.1.15 0.2 Jiangang Wu Revise some APIs

  2014.1.29 0.3 Han Liu Add client/server APIs

  2014.3.20 0.4 Jiangang Wu

  / Han Liu

  1.Add UART APIs

  2.Add i2c master APIs

  3.Revise client/server APIs

  4.Add secure espconn APIs

  5.Add upgrade APIs

  2014.4.17 0.5 Jiangang Wu

  / Han Liu

  1.Revise espconn APIs

  2.Add gpio APIs instruction

  3.Add some other instructions

  2014.5.14 0.6 Jiangang Wu Add some APIs

  2014.6.18 0.7 Jiangang Wu 1.Add dns APIs

  2.Revise save-param APIs

  3.Add task APIs

  4.Add API to get connected stations

  info when ESP8266 in softAP mode;

  5. Add API to get free heap size.

  6.Others

  2014.7.10 0.8 Fei Yu 1.Add OTA APIs

  2.Add API to ON/OFF printf

  3.Add wifi_station_get_connect_status

  4.Add TCP Server(SSL) APIs

  2014.8.13 0.9 Fei Yu 1.Revise espconn APIs

  2.Add sniffer APIs

  3.Add system_get_chip_id

  4.Add APIs to read/ write mac&ip

  2014.9.23 0.9.1 Fei Yu 1Add system_deep_sleep;

  2Revise APIs to read/write flash;

  3Add APIs for AP_CHE

  4Revise UDP APIs

• ESP8266EX SDK Programming Guide

  3 / 64 Espressif Systems June 19, 2014

  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 2013 Espressif Systems Inc. All rights reserved.

• ESP8266EX SDK Programming Guide

  4 / 64 Espressif Systems June 19, 2014

  Table of Contents

  Version Info
  ……………………………………………………………………………………………………..
  2

  Table of Contents
  ……………………………………………………………………………………………..
  4

  1. Foreword
  …………………………………………………………………………………………………..
  8

  2. Overview
  …………………………………………………………………………………………………..
  9

  3. Application Programming Interface (APIs)
  …………………………………………………… 10

  3.1. Timer
  ……………………………………………………………………………………
  10

  3.1.1. os_timer_arm
  ……………………………………………………………………….
  10

  3.1.2. os_timer_disarm
  ……………………………………………………………………
  10

  3.1.3. os_timer_setfn
  ………………………………………………………………………
  11

  3.2. System APIs
  …………………………………………………………………………..
  11

  3.2.1. system_restore
  ………………………………………………………………………
  11

  3.2.2. system_restart
  ………………………………………………………………………
  11

  3.2.3. system_get_chip_id
  ……………………………………………………………….
  12

  3.2.4. system_deep_sleep
  ……………………………………………………………….
  12

  3.2.5. system_upgrade_userbin_check
  …………………………………………….. 12

  3.2.6. system_upgrade_start
  ……………………………………………………………
  13

  3.2.7. system_upgrade_reboot
  …………………………………………………………
  13

  3.2.8. system_set_os_print
  ………………………………………………………………
  13

  3.2.9. system_timer_reinit
  ……………………………………………………………….
  14

  3.2.10. system_print_meminfo
  …………………………………………………………..
  14

  3.2.11. system_get_free_heap_size
  …………………………………………………… 15

  3.2.12. system_os_task
  ……………………………………………………………………..
  15

  3.2.13. system_os_post
  …………………………………………………………………….
  16

  3.2.14. spi_flash_erase_sector
  …………………………………………………………..
  17

  3.2.15. spi_flash_write
  ………………………………………………………………………
  17

  3.2.16. spi_flash_read
  ……………………………………………………………………….
  18

  3.2.17. wifi_get_opmode
  …………………………………………………………………..
  18

  3.2.18. wifi_set_opmode
  …………………………………………………………………..
  19

  3.2.19. wifi_station_get_config
  ………………………………………………………….
  19

  3.2.20. wifi_station_set_config
  …………………………………………………………..
  20

  3.2.21. wifi_station_connect
  ……………………………………………………………..
  20

  3.2.22. wifi_station_disconnect
  ………………………………………………………….
  21

  3.2.23.
  wifi_station_get_connect_status……………………………………………..
  21

  3.2.24. wifi_station_scan
  …………………………………………………………………..
  22

  3.2.25. scan_done_cb_t
  …………………………………………………………………….
  22

  3.2.26. wifi_station_ap_number_set
  ………………………………………………….. 23

  3.2.27. wifi_station_ap_change
  ………………………………………………………….
  23

  3.2.28. wifi_station_get_current_ap_id
  ……………………………………………… 23

  3.2.29. wifi_softap_get_config
  …………………………………………………………..
  24

  3.2.30. wifi_softap_set_config
  ……………………………………………………………
  24

• ESP8266EX SDK Programming Guide

  5 / 64 Espressif Systems June 19, 2014

  3.2.31. wifi_softap_get_station_info
  ………………………………………………….. 24

  3.2.32. wifi_softap_free_station_info
  ………………………………………………… 25

  3.2.33. wifi_get_ip_info
  …………………………………………………………………….
  26

  3.2.34. wifi_set_ip_info
  …………………………………………………………………….
  26

  3.2.35. wifi_set_macaddr
  ………………………………………………………………….
  27

  3.2.36. wifi_get_macaddr
  ………………………………………………………………….
  28

  3.2.37. wifi_status_led_install
  ……………………………………………………………
  28

  3.2.38. wifi_promiscuous_enable
  ……………………………………………………….
  29

  3.2.39. wifi_set_promiscuous_rx_cb
  ………………………………………………….. 29

  3.2.40. wifi_get_channel
  ……………………………………………………………………
  30

  3.2.41. wifi_set_channel
  ……………………………………………………………………
  30

  3.3. Espconn APIs
  …………………………………………………………………………
  30

  3.3.1. General APIs
  ………………………………………………………………………….
  31

  3.3.1.1. espconn_gethostbyname
  …………………………………………………. 31

  3.3.1.2. espconn_port
  ………………………………………………………………….
  32

  3.3.1.3. espconn_regist_sentcb
  …………………………………………………….
  32

  3.3.1.4. espconn_regist_recvcb
  …………………………………………………….
  33

  3.3.1.5. espconn_sent_callback
  …………………………………………………….
  33

  3.3.1.6. espconn_recv_callback
  …………………………………………………….
  33

  3.3.1.7. espconn_sent
  ………………………………………………………………….
  34

  3.3.2. TCP
  APIs………………………………………………………………………………..
  34

  3.3.2.1. espconn_accept
  ………………………………………………………………
  34

  3.3.2.2.
  espconn_secure_accept……………………………………………………
  35

  3.3.2.3. espconn_regist_time
  ……………………………………………………….
  35

  3.3.2.4. espconn_get_connection_info
  …………………………………………. 36

  3.3.2.5. espconn_connect
  …………………………………………………………….
  36

  3.3.2.6. espconn_connect_callback
  ………………………………………………. 36

  3.3.2.7. espconn_disconnect
  ………………………………………………………..
  37

  3.3.2.8. espconn_regist_connectcb
  ………………………………………………. 37

  3.3.2.9. espconn_regist_reconcb
  ………………………………………………….. 38

  3.3.2.10. espconn_regist_disconcb
  …………………………………………………. 38

  3.3.2.11. espconn_secure_connect
  ………………………………………………… 39

  3.3.2.12. espconn_secure_sent
  ………………………………………………………
  39

  3.3.2.13. espconn_secure_disconnect
  …………………………………………….. 39

  3.3.3. UDP APIs
  ………………………………………………………………………………
  40

  3.3.3.1. espconn_create
  ……………………………………………………………….
  40

  3.3.3.2. espconn_delete
  ……………………………………………………………….
  40

  3.4. json APIs
  ……………………………………………………………………………….
  41

  3.4.1. jsonparse_setup
  …………………………………………………………………….
  41

  3.4.2. jsonparse_next
  ………………………………………………………………………
  41

  3.4.3. jsonparse_copy_value
  ……………………………………………………………
  41

  3.4.4. jsonparse_get_value_as_int
  …………………………………………………… 42

  3.4.5.
  jsonparse_get_value_as_long………………………………………………….
  42

• ESP8266EX SDK Programming Guide

  6 / 64 Espressif Systems June 19, 2014

  3.4.6. jsonparse_get_len
  ………………………………………………………………….
  42

  3.4.7. jsonparse_get_value_as_type
  ………………………………………………… 43

  3.4.8. jsonparse_strcmp_value
  …………………………………………………………
  43

  3.4.9. jsontree_set_up
  …………………………………………………………………….
  43

  3.4.10. jsontree_reset
  ……………………………………………………………………….
  44

  3.4.11. jsontree_path_name
  ……………………………………………………………..
  44

  3.4.12. jsontree_write_int
  …………………………………………………………………
  44

  3.4.13. jsontree_write_int_array
  ………………………………………………………..
  45

  3.4.14. jsontree_write_string
  …………………………………………………………….
  45

  3.4.15. jsontree_print_next
  ……………………………………………………………….
  46

  3.4.16. jsontree_find_next
  …………………………………………………………………
  46

  4. Structure definition
  …………………………………………………………………………………..
  47

  4.1. Timer
  ……………………………………………………………………………………
  47

  4.2. Wifi parameters
  …………………………………………………………………….
  47

  4.2.1. station parameters
  …………………………………………………………………
  47

  4.2.2. softap parameters
  ………………………………………………………………….
  47

  4.2.3. scan parameters
  …………………………………………………………………….
  48

  4.3. json related structure
  ……………………………………………………………..
  48

  4.3.1. json structure
  ………………………………………………………………………..
  48

  4.3.2. json macro definition
  ……………………………………………………………..
  50

  4.4. espconn parameters
  ………………………………………………………………
  51

  4.4.1 callback function
  ……………………………………………………………………
  51

  4.4.2 espconn
  ………………………………………………………………………………..
  51

  5. Driver
  ………………………………………………………………………………………………………
  54

  5.1. GPIO APIs
  ……………………………………………………………………………..
  54

  5.1.1. PIN setting macro
  …………………………………………………………………..
  54

  5.1.2. gpio_output_set
  ……………………………………………………………………
  54

  5.1.3. GPIO input and output macro
  …………………………………………………. 55

  5.1.4. GPIO interrupt
  ……………………………………………………………………….
  55

  5.1.5. gpio_pin_intr_state_set
  ………………………………………………………….
  56

  5.1.6. GPIO interrupt handler
  …………………………………………………………..
  56

  5.2. UART APIs
  ……………………………………………………………………………..
  56

  5.2.1. uart_init
  ……………………………………………………………………………….
  57

  5.2.2. uart0_tx_buffer
  ……………………………………………………………………..
  57

  5.2.3. uart0_rx_intr_handler
  ……………………………………………………………
  58

  5.3. i2c master APIs
  ………………………………………………………………………
  58

  5.3.1. i2c_master_gpio_init
  ……………………………………………………………..
  58

  5.3.2. i2c_master_init
  ……………………………………………………………………..
  58

  5.3.3. i2c_master_start
  ……………………………………………………………………
  59

  5.3.4. i2c_master_stop
  ……………………………………………………………………
  59

  5.3.5. i2c_master_setAck
  …………………………………………………………………
  59

  5.3.6.
  i2c_master_getAck…………………………………………………………………
  60

  5.3.7. i2c_master_readByte
  ……………………………………………………………..
  60

• ESP8266EX SDK Programming Guide

  7 / 64 Espressif Systems June 19, 2014

  5.3.8. i2c_master_writeByte
  …………………………………………………………….
  60

  5.4. pwm
  …………………………………………………………………………………….
  61

  5.4.1. pwm_init
  ………………………………………………………………………………
  61

  5.4.2. pwm_start
  …………………………………………………………………………….
  61

  5.4.3. pwm_set_duty
  ………………………………………………………………………
  61

  5.4.4. pwm_set_freq
  ……………………………………………………………………….
  62

  5.4.5. pwm_get_duty
  ………………………………………………………………………
  62

  5.4.6.
  pwm_get_freq……………………………………………………………………….
  62

  6. Appendix
  …………………………………………………………………………………………………
  63

  A. ESPCONN Programming
  ………………………………………………………….
  63

  A.1. TCP Client Mode
  …………………………………………………………………….
  63

  A.1.1. Instructions
  …………………………………………………………………………..
  63

  A.1.2. Steps
  …………………………………………………………………………………….
  63

  A.2. TCP Server Mode
  ……………………………………………………………………
  64

  A.2.1. Instructions
  …………………………………………………………………………..
  64

  A.2.2. Steps
  …………………………………………………………………………………….
  64

• ESP8266EX SDK Programming Guide

  8 / 64 Espressif Systems June 19, 2014

  1. Foreword

  The SDK based on ESP8266 IoT platform offers users an easy, fast
  and efficient

  way to develop IoT devices.

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

• ESP8266EX SDK Programming Guide

  9 / 64 Espressif Systems June 19, 2014

  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 usre_init(void) is the default method provided. Users can
  add functions like

  firmware initialization, network parameters setting, and timer
  initialization in the

  interface.

  The SDK provides an API to handle json, and users can also use
  self-defined data

  types to handle the them.

• ESP8266EX SDK Programming Guide

  10 / 64 Espressif Systems June 19, 2014

  3. Application Programming Interface (APIs)

  3.1. Timer

  Locate in esp_iot_sdkincludeosapi.h

  3.1.1. os_timer_arm

  Function: arm timer

  Prototype:

  void os_timer_arm(ETSTimer *ptimer, uint32_t milliseconds,
  boolrepeat_flag)

  Input parameters:

  ETSTimer*ptimerTimer structure

  uint32_t millisecondsTiming, Unit: milisecond

  boolrepeat_flagWhether to repeat the timing

  Return:

  null

  3.1.2. os_timer_disarm

  Function: Disarm timer

  Prototype:

  void os_timer_disarm (ETSTimer *ptimer)

  Input parameters:

  ETSTimer*ptimerTimer structure

  Return:

  null

• ESP8266EX SDK Programming Guide

  11 / 64 Espressif Systems June 19, 2014

  3.1.3. os_timer_setfn

  Function: Set timer callback function

  Prototype:

  void os_timer_setfn (ETSTimer *ptimer, ETSTimerFunc *pfunction,
  void *parg)

  Input parameters:

  ETSTimer*ptimerTimer structure

  TESTimerFunc*pfunctiontimer callback function

  void*pargcallback function parameter

  Return:

  null

  3.2. System APIs

  Locate in esp_iot_sdk includeuser_interface.h

  3.2.1. system_restore

  Function: Reset to default settings

  Prototype:

  void system_restore(void)

  Input parameters:

  null

  Return:

  null

  3.2.2. system_restart

  Function: Restart

  Prototype:

  void system_restart(void)

  Input parameters:

• ESP8266EX SDK Programming Guide

  12 / 64 Espressif Systems June 19, 2014

  null

  Return:

  null

  3.2.3. system_get_chip_id

  Function: Get chip id

  Prototype:

  uint32 system_get_chip_id (void)

  Input parameters:

  null

  Return:

  Chip id

  3.2.4. system_deep_sleep

  Function: Set for deep-sleep mode. Device in deep-sleep mode
  automatically, every X

  us wake up once. Everytime device wakes up, it starts from
  user_init.

  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

  3.2.5. system_upgrade_userbin_check

  Function: Check userbin

  Function definition:

• ESP8266EX SDK Programming Guide

  13 / 64 Espressif Systems June 19, 2014

  uint8 system_upgrade_userbin_check()

  Input parameters:

  null

  Return:

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

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

  3.2.6. system_upgrade_start

  Function: Configure parameters and start upgrade

  Function definition:

  bool system_upgrade_start (struct upgrade_server_info
  *server)

  Parameters:

  struct upgrade_server_info *server server related parameters

  Return

  true: start upgrade

  false: upgrade cant be started.

  3.2.7. system_upgrade_reboot

  Function: reboot system and use new version

  Function definition:

  void system_upgrade_reboot (void)

  Input parameters:

  null

  Return:

  null

  3.2.8. system_set_os_print

  Function: Turn on/off print logFunction

  Function definition:

• ESP8266EX SDK Programming Guide

  14 / 64 Espressif Systems June 19, 2014

  void system_set_os_print (uint8onoff)

  Input parameters:

  uint8 onoff turn on/off print function;

  0x00 : print function off

  0x01: print function on

  Defaut: print function on

  Return:

  null

  3.2.9. system_timer_reinit

  Function: Reinitiate the timer when you need to use microsecond
  timer

  Not es: 1. Define USE_US_TIMER;

  2. Put system_timer_reinit at the beginning and user_init in the
  first

  sentence.

  Function definition:

  void system_timer_reinit (void)

  Input parameters:

  null

  Return:

  null

  3.2.10. system_print_meminfo

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

  Function definition:

  void system_print_meminfo (void)

  Input parameters:

  null

  Return:

  null

• ESP8266EX SDK Programming Guide

  15 / 64 Espressif Systems June 19, 2014

  3.2.11. system_get_free_heap_size

  Function: Get free heap size

  Function definition:

  uint32 system_get_free_heap_size(void)

  Input parameters:

  null

  Return:

  uint32 available heap size

  3.2.12. system_os_task

  Function: Set up tasks

  Function definition:

  void system_os_task(os_task_t task, uint8 prio, os_event_t
  *queue, uint8

  qlen)

  Input parameters:

  os_task_t tasktask function

  uint8 priotask priority. 3 priorities are supported, 0/1/2, 0 is
  the lowest

  priority.

  os_event_t *queuemessage queue pointer

  uint8 qlenmessage queue depth

  Return:

  null

  Example:

  #define SIG_RX 0

  #define TEST_QUEUE_LEN 4

  os_event_t *testQueue;

  void test_task (os_event_t *e)

  {

• ESP8266EX SDK Programming Guide

  16 / 64 Espressif Systems June 19, 2014

  switch (e->sig) {

  case SIG_RX:

  os_printf(sig_rx %cn, (char)e->par);

  break;

  default:

  break;

  }

  }

  void task_init(void)

  {

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

  }

  3.2.13. system_os_post

  Function: send message to task

  Function definition:

  void system_os_post (uint8 prio, os_signal_t sig, os_param_t
  par)

  Input parameters:

  uint8 priotask priority, corresponding to that you set up

  os_signal_t sigmessage type

  os_param_t parmessage parameters

  Return:

  null

  Refer to the example above:

  void task_post(void)

  {

  system_os_post(USER_TASK_PRIO_0, SIG_RX, a);

  }

• ESP8266EX SDK Programming Guide

  17 / 64 Espressif Systems June 19, 2014

  Printout: sig_rx a

  3.2.14. spi_flash_erase_sector

  Function: erase sector in flash

  Note: More details in document

  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.2.15. spi_flash_write

  FunctionWrite data to flash

  Note: More details in document

  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,

• ESP8266EX SDK Programming Guide

  18 / 64 Espressif Systems June 19, 2014

  SPI_FLASH_RESULT_ERR,

  SPI_FLASH_RESULT_TIMEOUT

  }SpiFlashOpResult

  3.2.16. spi_flash_read

  Function Read data from flash.

  Note: More details in document

  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

  3.2.17. wifi_get_opmode

  Function: get wifi working mode

  Function definition:

  uint8 wifi_get_opmode (void)

  Input parameters:

  null

• ESP8266EX SDK Programming Guide

  19 / 64 Espressif Systems June 19, 2014

  Return:

  Wifi working modes:

  0x01 means STATION_MODE,

  0x02 means SOFTAP_MODE,

  0x03 means STATIONAP_MODE.

  3.2.18. wifi_set_opmode

  Function: set wifi working mode as STATION, SOFTAP or
  STATION+SOFTAP

  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.

  Function definition:

  bool wifi_set_opmode (uint8 opmode)

  Input parameters:

  uint8 opmodeWifi working modes: 0x01 means STATION_MODE,
  0x02

  means SOFTAP_MODE, 0x03 means STATIONAP_MODE.

  Return:

  True — succeed

  False — fail.

  3.2.19. wifi_station_get_config

  Function: get wifi station configuration

  Function definition:

  bool wifi_station_get_config (struct station_config *config)

  Input parameters:

  struct station_config *configwifi station configuration
  pointer

  Return:

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  20 / 64 Espressif Systems June 19, 2014

  3.2.20. wifi_station_set_config

  Function: Set wifi station configuration

  Note: 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.

  Function definition:

  bool wifi_station_set_config (struct station_config *config)

  Input parameters:

  struct station_config *configwifi station configuration
  pointer

  Return:

  True — succeed

  False — fail.

  3.2.21. wifi_station_connect

  Function: wifi station connected AP

  Note if ESP8266 has already connected to a router its necessary
  to call

  wifi_station_disconnect firstthen call wifi_station_connect to
  connect.

  Function definition:

  bool wifi_station_connect (void)

  Input parameters:

  null

  Return:

  True — succeed

  False — fail.

• ESP8266EX SDK Programming Guide

  21 / 64 Espressif Systems June 19, 2014

  3.2.22. wifi_station_disconnect

  Function: wifi station disconnected AP

  Function definition:

  bool wifi_station_disconnect (void)

  Input parameters:

  null

  Return:

  True — succeed

  False — fail.

  3.2.23. wifi_station_get_connect_status

  Function: get the connection status between wifi station and
  AP

  Function definition:

  uint8 wifi_station_get_connect_status (void)

  Input parameters:

  null

  Return:

  enum{

  STATION_IDLE = 0,

  STATION_CONNECTING,

  STATION_WRONG_PASSWORD,

  STATION_NO_AP_FOUND,

  STATION_CONNECT_FAIL,

  STATION_GOT_IP

  };

• ESP8266EX SDK Programming Guide

  22 / 64 Espressif Systems June 19, 2014

  3.2.24. wifi_station_scan

  Function: Scan AP

  Function definition:

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

  Structure

  struct scan_config{

  uint8 *ssid; // APs ssid

  uint8 *bssid; // APs bssid

  uint8 channel; //scan a specific channel

  };

  Parameters:

  struct scan_config *config AP config for scan

  if config = Null scan all APs

  if config.ssidconfig.bssid are nullconfig.channel isnt null,
  ESP8266 will scan

  the specific channel.

  scan_done_cb_t cb — callback function after scan

  Return:

  True — succeed

  False — fail.

  3.2.25. scan_done_cb_t

  Function: scan callback function

  Function definition:

  void scan_done_cb_t (void *arg, STATUS status);

  Input parameters:

  void *argget Aps input parameters

  STATUS statusget status

• ESP8266EX SDK Programming Guide

  23 / 64 Espressif Systems June 19, 2014

  Return:

  null

  3.2.26. wifi_station_ap_number_set

  Function: Set the number of APs that can be recorded for ESP8266
  station. When

  ESP8266 station connects to an AP, ESP8266 keeps a record of
  this AP. Record id starts

  counting from 0.

  Prototype

  bool wifi_station_ap_number_set (uint8 ap_number);

  Parameters

  uint8 ap_number how many APs can be recordedMAX: 5

  eg: if ap_number is 5, record id : 0 ~ 4

  Return

  True — succeed

  False — fail.

  3.2.27. wifi_station_ap_change

  Function: ESP8266 station change to connect to the AP which is
  recorded in specific

  id.

  Prototype

  bool wifi_station_ap_change (uint8 current_ap_id);

  Parameters

  uint8 current_ap_id APs record id, start counting from 0.

  Return

  True — succeed

  False — fail.

  3.2.28. wifi_station_get_current_ap_id

  Function: Get the current record id of AP.

• ESP8266EX SDK Programming Guide

  24 / 64 Espressif Systems June 19, 2014

  Prototype

  Uint8 wifi_station_get_current_ap_id ();

  Parameter

  Null

  Return

  The record id of the AP which ESP8266 is connected with right
  now.

  3.2.29. wifi_softap_get_config

  Function: set wifi softap configuration

  Function definition:

  bool wifi_softap_get_config(struct softap_config *config)

  Parameter

  struct softap_config *configESP8266 softap config

  Return

  True — succeed

  False — fail.

  3.2.30. wifi_softap_set_config

  Function: set wifi softap configuration

  Function definition:

  bool wifi_softap_set_config (struct softap_config *config)

  Parameter

  struct softap_config *config wifi softap configuration
  pointer

  Return

  True — succeed

  False — fail.

  3.2.31. wifi_softap_get_station_info

  Function: get connected station devices under softap mode,
  including mac and ip

• ESP8266EX SDK Programming Guide

  25 / 64 Espressif Systems June 19, 2014

  Function definition

  struct station_info * wifi_softap_get_station_info(void)

  Input parameters:

  null

  Return:

  struct station_info*station information structure

  3.2.32. wifi_softap_free_station_info

  Function: free the struct station_info by calling the
  wifi_softap_get_station_info

  function

  Function definition:

  void wifi_softap_free_station_info(void)

  Input parameters:

  null

  Return:

  null

  Examples of getting mac and ip information:

  Method 1:

  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;

  }

  Method 2

  struct station_info * station =
  wifi_softap_get_station_info();

• ESP8266EX SDK Programming Guide

  26 / 64 Espressif Systems June 19, 2014

  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

  3.2.33. wifi_get_ip_info

  Function: Get ip info of wifi station or softap interface

  Function definition:

  bool wifi_get_ip_info(uint8 if_index, struct ip_info *info)

  Parameters:

  uint8 if_indexthe interface to get ip info: 0x00 for STATION_IF,
  0x01 for

  SOFTAP_IF.

  struct ip_info *infopointer to get ip info of a certain
  interface

  Return

  True — succeed

  False — fail.

  3.2.34. wifi_set_ip_info

  Function: Set ip address of ESP8266 station or softAP

  Note: only can be used in user_init.

  Function definition:

  bool wifi_set_ip_info(uint8 if_index, struct ip_info *info)

  Prototype

  uint8 if_index set station ip or softAP ip

  #define STATION_IF 0x00

  #define SOFTAP_IF 0x01

  struct ip_info *info ip information

• ESP8266EX SDK Programming Guide

  27 / 64 Espressif Systems June 19, 2014

  Example

  struct ip_info info;

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

  Return

  True — succeed

  False — fail.

  3.2.35. wifi_set_macaddr

  Function: set mac address

  Note: only can be used in user_init

  Function definition:

  bool wifi_set_macaddr(uint8 if_index, uint8 *macaddr)

  Parameter

  uint8 if_index set station mac or softAP 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};

• ESP8266EX SDK Programming Guide

  28 / 64 Espressif Systems June 19, 2014

  wifi_set_macaddr(SOFTAP_IF, sofap_mac);

  wifi_set_macaddr(STATION_IF, sta_mac);

  Return

  True — succeed

  False — fail.

  3.2.36. wifi_get_macaddr

  Function: get mac address

  Function definition:

  Bool wifi_get_macaddr(uint8 if_index , uint8 *macaddr)

  Parameter

  uint8 if_index set station mac or softAP mac

  #define STATION_IF 0x00

  #define SOFTAP_IF 0x01

  uint8 *macaddr mac address

  Return

  True — succeed

  False — fail.

  3.2.37. wifi_status_led_install

  Function: Install wifi status LED

  Function definition:

  Void wifi_status_led_install (uint8 gpio_id, uint32 gpio_name,
  uint8 gpio_func)

  Parameter

  uint8 gpio_idgpio number

  uint8 gpio_namegpio mux name

  uint8 gpio_funcgpio function

  Return

• ESP8266EX SDK Programming Guide

  29 / 64 Espressif Systems June 19, 2014

  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)

  3.2.38. wifi_promiscuous_enable

  Function: Enable promiscuous mode for sniffer

  Function definition:

  Void wifi_promiscuous_enable(uint8 promiscuous)

  Parameter

  uint8 promiscuous 0, disable promiscuous

  1, enable promiscuous

  Return:

  null

  Example: apply for a demo of sniffer function from Espressif

  3.2.39. wifi_set_promiscuous_rx_cb

  Function: register a rx callback function in promiscuous mode,
  which will be called

  when data packet is received.

  Function definition:

  Void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb)

  Parameter

  wifi_promiscuous_cb_t cb callback

  Return:

  null

• ESP8266EX SDK Programming Guide

  30 / 64 Espressif Systems June 19, 2014

  3.2.40. wifi_get_channel

  Function: get channel number, for sniffer

  Function definition:

  uint8 wifi_get_channel(void)

  parameters:

  null

  Return:

  Channel number

  3.2.41. wifi_set_channel

  Function: set channel number, for sniffer

  Function definition:

  bool wifi_set_channel (uint8 channel)

  Parameters

  uint8 channel channel number

  Return

  True — succeed

  False — fail.

  3.3. Espconn APIs

  Locate in esp_iot_sdkincludeespconn.h

  General APIsAPIs can be used for both TCP and UDP .

  TCP APIsAPIs that are only used for TCP.

  UDP APIsAPIs that are only used for UDP.

• ESP8266EX SDK Programming Guide

  31 / 64 Espressif Systems June 19, 2014

  3.3.1. General APIs

  3.3.1.1. espconn_gethostbyname

  Function: DNS

  Function definition:

  Err_t espconn_gethostbyname(struct espconn *pespconn, const char
  *hostname,

  ip_addr_t *addr, dns_found_callback found)

  Parameters:

  struct espconn *espconncorresponding connected control block
  structure

  const char *hostnamedomain name string pointer

  ip_addr_t *addrip address

  dns_found_callback foundcallback

  Return:

  Err_tESPCONN_OK

  ESPCONN_INPROGRESS

  ESPCONN_ARG

  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.%dn»,

  *((uint8 *)&ipaddr->addr), *((uint8
  *)&ipaddr->addr + 1),

  *((uint8 *)&ipaddr->addr + 2), *((uint8
  *)&ipaddr->addr + 3));

  }

  Void dns_test(void)

• ESP8266EX SDK Programming Guide

  32 / 64 Espressif Systems June 19, 2014

  {

  espconn_gethostbyname(pespconn,iot.espressif.cn,&esp_server_ip,user_esp_platf

  orm_dns_found);

  }

  3.3.1.2. espconn_port

  Function: get void ports

  Function definition:

  uint32 espconn_port(void);

  Input parameters:

  null

  Return:

  uint32id of the port you get

  3.3.1.3. espconn_regist_sentcb

  Function: register data sent function which will be called back
  when data are

  successfully sent.

  Function definition:

  Sint8 espconn_regist_sentcb(struct espconn *espconn,
  espconn_sent_callback

  sent_cb)

  Parameters

  struct espconn *espconncorresponding connected control block
  structure

  espconn_sent_callback sent_cbregistered callback function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  33 / 64 Espressif Systems June 19, 2014

  3.3.1.4. espconn_regist_recvcb

  Function: register data receive function which will be called
  back when data are

  received

  Function definition:

  Sint8 espconn_regist_recvcb(struct espconn *espconn,
  espconn_recv_callback

  recv_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.1.5. espconn_sent_callback

  Function: callback after the data are sent

  Function definition:

  void espconn_sent_callback (void *arg)

  Input parameters:

  void *argcall back function parameters

  Return:

  null

  3.3.1.6. espconn_recv_callback

  Function: callback after data are received

  Function definition:

  void espconn_recv_callback (void *arg, char *pdata, unsigned
  short len)

  Input parameters:

• ESP8266EX SDK Programming Guide

  34 / 64 Espressif Systems June 19, 2014

  void *argcallback function parameters

  char *pdatareceived data entry parameters

  unsigned short lenreceived data length

  Return:

  null

  3.3.1.7. espconn_sent

  Function: send data through wifi

  Function definition:

  sint8 espconn_sent(struct espconn *espconn, uint8 *psent, uint16
  length)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  uint8 *psentsent data pointer

  uint16 lengthsent data length

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2. TCP APIs

  3.3.2.1. espconn_accept

  Function: listening connection. This function is used when
  create a TCP server.

  Function definition:

  sint8 espconn_accept(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

• ESP8266EX SDK Programming Guide

  35 / 64 Espressif Systems June 19, 2014

  Not 0 — error, pls refer to espconn.h

  3.3.2.2. espconn_secure_accept

  Function: encrypted listening connection. This function is used
  when create a TCP

  server which support SSL.

  Function definition:

  sint8 espconn_secure_accept(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.3. espconn_regist_time

  Function: register timeout interval when ESP8266 is TCP
  server

  Function definition:

  sint8 espconn_regist_time(struct espconn *espconn, uint32
  interval, uint8

  type_flag)

  Input parameters:

  struct espconn *espconncorresponding 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, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  36 / 64 Espressif Systems June 19, 2014

  3.3.2.4. espconn_get_connection_info

  Function: get a connections info in TCP multi-connection
  case

  Function definition:

  sint8 espconn_get_connection_info(struct espconn *espconn,
  remot_info

  **pcon_info, uint8 typeflags)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  remot_info **pcon_infoconnect to client info

  uint8 typeflags 0, regular server;1, ssl server

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.5. espconn_connect

  Function: connect to a TCP server, and ESP8266 is the TCP
  client.

  Function definition:

  sint8 espconn_connect(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.6. espconn_connect_callback

  Function: successful listening(ESP8266 as TCP server) or
  connection(ESP8266 as TCP

  client) callback

  Function definition:

• ESP8266EX SDK Programming Guide

  37 / 64 Espressif Systems June 19, 2014

  void espconn_connect_callback (void *arg)

  Input parameters:

  void *argcallback function parameters

  Return:

  null

  3.3.2.7. espconn_disconnect

  Function: disconnect a TCP connection

  Function definition:

  sint8 espconn_disconnect(struct espconn *espconn);

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.8. espconn_regist_connectcb

  Function: register connection function which will be called back
  under successful TCP

  connection

  Function definition:

  Sint8 espconn_regist_connectcb(struct espconn *espconn,

  espconn_connect_callback connect_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

• ESP8266EX SDK Programming Guide

  38 / 64 Espressif Systems June 19, 2014

  Not 0 — error, pls refer to espconn.h

  3.3.2.9. espconn_regist_reconcb

  Function: register reconnection function, which will be called
  back when TCP

  reconnection starts

  Function definition:

  sint8 espconn_regist_reconcb(struct espconn *espconn,

  espconn_connect_callback recon_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.10. espconn_regist_disconcb

  Function: register disconnection function which will be called
  back under successful

  TCP disconnection

  Function definition:

  Sint8 espconn_regist_disconcb(struct espconn *espconn,

  espconn_connect_callback discon_cb)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  espconn_connect_callback connect_cbregistered callback
  function

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

• ESP8266EX SDK Programming Guide

  39 / 64 Espressif Systems June 19, 2014

  3.3.2.11. espconn_secure_connect

  Function: Secure connect(SSL) to a TCP server, and ESP8266 is
  the TCP client.

  Function definition:

  Sint8 espconn_secure_connect (struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.12. espconn_secure_sent

  Function: send encrypted dataSSL

  Function definition:

  Sint8 espconn_secure_sent (struct espconn *espconn, uint8
  *psent, uint16

  length)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  uint8 *psentsent data pointer

  uint16 lengthsent data length

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.2.13. espconn_secure_disconnect

  Function: secure TCP disconnection(SSL)

• ESP8266EX SDK Programming Guide

  40 / 64 Espressif Systems June 19, 2014

  Function definition:

  Sint8 espconn_secure_disconnect(struct espconn *espconn)

  Input parameters:

  struct espconn *espconncorresponding connected control block
  structure

  Return:

  0 — succeed, #define ESPCONN_OK 0

  Not 0 — error, pls refer to espconn.h

  3.3.3. UDP APIs

  3.3.3.1. espconn_create

  Functioncreate UDP transmission.

  Prototype

  Sin8 espconn_create(struct espconn *espconn)

  Parameter

  struct espconn *espconncorresponding connected control block
  structure

  Return

  0 — succeed#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

  3.3.3.2. espconn_delete

  Function: delete UDP transmission.

  Prototype

  Sin8 espconn_delete(struct espconn *espconn)

  Parameter

  struct espconn *espconncorresponding connected control block
  structure

  Return

• ESP8266EX SDK Programming Guide

  41 / 64 Espressif Systems June 19, 2014

  0 — succeed#define ESPCONN_OK 0

  Not 0 — Erropls refer to espconn.h

  3.4. json APIs

  Locate in : esp_iot_sdkincludejsonjsonparse.h &
  jsontree.h

  3.4.1. jsonparse_setup

  Function:json initialize parsing

  Function definition:

  void jsonparse_setup(struct jsonparse_state *state, const char
  *json, int len)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  const char *jsonjson parsing character string

  int lencharacter string length

  Return:

  null

  3.4.2. jsonparse_next

  Function: jsonparse next object

  Function definition:

  int jsonparse_next(struct jsonparse_state *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsing result

  3.4.3. jsonparse_copy_value

  Function: copy current parsing character string to a certain
  buffer

  Function definition:

• ESP8266EX SDK Programming Guide

  42 / 64 Espressif Systems June 19, 2014

  int jsonparse_copy_value(struct jsonparse_state *state, char
  *str, int size)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  char *strbuffer pointer

  int sizebuffer size

  Return:

  intcopy result

  3.4.4. jsonparse_get_value_as_int

  Function: parse json to get integer

  Function definition:

  int jsonparse_get_value_as_int(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsing result

  3.4.5. jsonparse_get_value_as_long

  Function: parse json to get long integer

  Function definition:

  long jsonparse_get_value_as_long(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  longparsing result

  3.4.6. jsonparse_get_len

  Function: get parsed json length

  Function definition:

• ESP8266EX SDK Programming Guide

  43 / 64 Espressif Systems June 19, 2014

  int jsonparse_get_value_len(struct jsonparse_state *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsed jason length

  3.4.7. jsonparse_get_value_as_type

  Function: parsed json data type

  Function definition:

  int jsonparse_get_value_as_type(struct jsonparse_state
  *state)

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  Return:

  intparsed json data type

  3.4.8. jsonparse_strcmp_value

  Function: compare parsed json and certain character string

  Function definition:

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

  Input parameters:

  struct jsonparse_state *statejson parsing pointer

  const char *strcharacter buffer

  Return:

  intcomparison result

  3.4.9. jsontree_set_up

  Function: create json data tree

  Function definition:

  void jsontree_setup(struct jsontree_context *js_ctx,

• ESP8266EX SDK Programming Guide

  44 / 64 Espressif Systems June 19, 2014

  struct jsontree_value *root, int (* putchar)(int))

  Input parameters:

  struct jsontree_context *js_ctxjson tree element pointer

  struct jsontree_value *rootroot element pointer

  int (* putchar)(int)input function

  Return:

  null

  3.4.10. jsontree_reset

  Function: reset json tree

  Function definition:

  void jsontree_reset(struct jsontree_context *js_ctx)

  Input parameters:

  struct jsontree_context *js_ctxjson data tree pointer

  Return:

  null

  3.4.11. jsontree_path_name

  Function: get json tree parameters

  Function definition:

  const char *jsontree_path_name(const struct jsontree_cotext
  *js_ctx, int depth)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int depthjson tree depth

  Return:

  char*parameter pointer

  3.4.12. jsontree_write_int

  Function: write integer to joson tree

• ESP8266EX SDK Programming Guide

  45 / 64 Espressif Systems June 19, 2014

  Function definition:

  void jsontree_write_int(const struct jsontree_context *js_ctx,
  int value)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int valueinteger value

  Return:

  null

  3.4.13. jsontree_write_int_array

  Function: write integer array to json tree

  Function definition:

  void jsontree_write_int_array(const struct jsontree_context
  *js_ctx, const int

  *text, uint32 length)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  int *textarray entry address

  uint32 lengtharray length

  Return:

  null

  3.4.14. jsontree_write_string

  Function: write string to json tree

  Function definition:

  void jsontree_write_string(const struct jsontree_context
  *js_ctx, const char

  *text)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  const char* textcharacter string pointer

  Return:

• ESP8266EX SDK Programming Guide

  46 / 64 Espressif Systems June 19, 2014

  null

  3.4.15. jsontree_print_next

  Function: json tree depth

  Function definition:

  int jsontree_print_next(struct jsontree_context *js_ctx)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  Return:

  intjson tree depth

  3.4.16. jsontree_find_next

  Function: find json tree element

  Function definition:

  struct jsontree_value *jsontree_find_next(struct
  jsontree_context *js_ctx, int

  type)

  Input parameters:

  struct jsontree_context *js_ctxjson tree pointer

  inttype

  Return:

  struct jsontree_value *json tree element pointer

• ESP8266EX SDK Programming Guide

  47 / 64 Espressif Systems June 19, 2014

  4. Structure definition

  4.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;

  4.2. Wifi parameters

  4.2.1. station parameters

  struct station_config {

  uint8 ssid[32];

  uint8 password[64];

  };

  4.2.2. softap parameters

  typedef enum _auth_mode {

  AUTH_OPEN = 0,

  AUTH_WEP,

  AUTH_WPA_PSK,

  AUTH_WPA2_PSK,

• ESP8266EX SDK Programming Guide

  48 / 64 Espressif Systems June 19, 2014

  AUTH_WPA_WPA2_PSK

  } AUTH_MODE;

  struct softap_config {

  uint8 ssid[32];

  uint8 password[64];

  uint8 channel;

  uint8 authmode;

  uint8 ssid_hidden;

  uint8 max_connection;

  };

  4.2.3. scan parameters

  struct bss_info {

  STAILQ_ENTRY(bss_info) next;

  u8 bssid[6];

  u8 ssid[32];

  u8 channel;

  s8 rssi;

  u8 authmode;

  };

  typedef void (* scan_done_cb_t)(void *arg, STATUS status);

  4.3. json related structure

  4.3.1. json structure

  struct jsontree_value {

  uint8_t type;

  };

• ESP8266EX SDK Programming Guide

  49 / 64 Espressif Systems June 19, 2014

  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;

  };

  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;

• ESP8266EX SDK Programming Guide

  50 / 64 Espressif Systems June 19, 2014

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

  };

  4.3.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 }

  #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 = {

• ESP8266EX SDK Programming Guide

  51 / 64 Espressif Systems June 19, 2014

  JSON_TYPE_ARRAY,

  sizeof(jsontree_value_##name)/sizeof(struct jsontree_value*),

  jsontree_value_##name }

  4.4. espconn parameters

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

  4.4.2 espconn

  typedef void* espconn_handle;

  typedef struct _esp_tcp {

  int client_port;

  int server_port;

  char ipaddr[4];

  espconn_connect_callback connect_callback;

  espconn_connect_callback reconnect_callback;

  espconn_connect_callback disconnect_callback;

  } esp_tcp;

  typedef struct _esp_udp {

  int _port;

  char ipaddr[4];

  } esp_udp;

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

• ESP8266EX SDK Programming Guide

  52 / 64 Espressif Systems June 19, 2014

  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

  };

  /** A espconn descriptor */

  struct espconn {

  /** type of the espconn (TCP, UDP) */

  enum espconn_type type;

  /** current state of the espconn */

  enum espconn_state state;

  union {

  esp_tcp *tcp;

  esp_udp *udp;

• ESP8266EX SDK Programming Guide

  53 / 64 Espressif Systems June 19, 2014

  } proto;

  /** A callback function that is informed about events for this
  espconn */

  espconn_recv_callback recv_callback;

  espconn_sent_callback sent_callback;

  espconn_handle esp_pcb;

  uint8 *ptrbuf;

  uint16 cntr;

  };

• ESP8266EX SDK Programming Guide

  54 / 64 Espressif Systems June 19, 2014

  5. Driver

  5.1. GPIO APIs

  Please refer to user user_plug.c

  5.1.1. PIN setting macro

  PIN_PULLUP_DIS(PIN_NAME)

  Disable pin pull up

  PIN_PULLUP_EN(PIN_NAME)

  Enable pin pull up

  PIN_PULLDWN_DIS(PIN_NAME)

  Disable pin pull down

  PIN_PULLDWN_EN(PIN_NAME)

  Enable pin pull down

  PIN_FUNC_SELECT(PIN_NAME, FUNC)

  Select pin function

  ExamplePIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12);

  Use MTDI pin as GPIO12

  5.1.2. gpio_output_set

  Function: set gpio property

  Function definition:

  void gpio_output_set(uint32 set_mask, uint32 clear_mask, uint32
  enable_mask,

  uint32 disable_mask)

  Input parameters:

  uint32 set_maskset high output: 1 means high output; 0 means no
  status

  change

  uint32 clear_maskset low output: 1 means low output; 0 means no
  status

• ESP8266EX SDK Programming Guide

  55 / 64 Espressif Systems June 19, 2014

  change

  uint32 enable_maskenable outpout bit

  uint32 disable_maskenable input bit

  Return:

  Null

  Example

  Set GPIO12 as high-level outputgpio_output_set(BIT12, 0, BIT12,
  0);

  Set GPIO12 as low-level outputgpio_output_set(0, BIT12, BIT12,
  0);

  Set GPIO12 as high-level outputGPIO13 as low-level output

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

  Set GPIO12 as input : gpio_output_set(0, 0, 0, BIT12);

  5.1.3. GPIO input and output macro

  GPIO_OUTPUT_SET(gpio_no, bit_value)

  Set gpio_no as output bit_valuethe 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.

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

• ESP8266EX SDK Programming Guide

  56 / 64 Espressif Systems June 19, 2014

  5.1.5. gpio_pin_intr_state_set

  Function: set gpio interrupt state

  Function definition:

  void gpio_pin_intr_state_set(uint32 i, GPIO_INT_TYPE
  intr_state)

  Input parameters:

  uint32 iGPIO pin ID, if you want to set GPIO14, pls use
  GPIO_ID_PIN(14);

  GPIO_INT_TYPE intr_stateinterrupt type

  as

  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

  5.1.6. GPIO interrupt handler

  Follow below steps 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);

  5.2. UART 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.

• ESP8266EX SDK Programming Guide

  57 / 64 Espressif Systems June 19, 2014

  5.2.1. uart_init

  Function: initialize baud rates of the two uarts

  Function definition:

  void uart_init(UartBautRate uart0_br, UartBautRate uart1_br)

  Parameters

  UartBautRate uart0_bruart0 baud rate

  UartBautRate uart1_bruart1 baud rate

  As

  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

  5.2.2. uart0_tx_buffer

  Function: send user-defined data through UART0

  Function definition:

  Void uart0_tx_buffer(uint8 *buf, uint16 len)

  Parameter:

  Uint8 *bufdata to send later

  Uint16 lenthe length of data to send later

  Return:

  NULL

• ESP8266EX SDK Programming Guide

  58 / 64 Espressif Systems June 19, 2014

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

  Function definition:

  Void uart0_rx_intr_handler(void *para)

  Parameter:

  Void*parathe pointer pointing to RcvMsgBuff structure

  Return:

  NULL

  5.3. i2c master APIs

  5.3.1. i2c_master_gpio_init

  Function: set GPIO in i2c master mode

  Function definition:

  void i2c_master_gpio_init (void)

  Input parameters:

  null

  Return:

  null

  5.3.2. i2c_master_init

  Function: initialize i2c

  Function definition:

  void i2c_master_init(void)

  Input parameters:

  null

• ESP8266EX SDK Programming Guide

  59 / 64 Espressif Systems June 19, 2014

  Return:

  null

  5.3.3. i2c_master_start

  Function: set i2c to start data delivery

  Function definition:

  void i2c_master_start(void)

  Input parameters:

  null

  Return:

  null

  5.3.4. i2c_master_stop

  Function: set i2c to stop data delivery

  Function definition:

  Void i2c_master_stop(void)

  Input parameters:

  null

  Return:

  null

  5.3.5. i2c_master_setAck

  Function: set i2c ACK

  Function definition:

  void i2c_master_setAck (uint8 level)

  Input parameters:

  uint8 levelack 0 or 1

  Return:

  null

• ESP8266EX SDK Programming Guide

  60 / 64 Espressif Systems June 19, 2014

  5.3.6. i2c_master_getAck

  Function: get ACK from slave

  Function definition:

  uint8 i2c_master_getAck (void)

  Input parameters:

  null

  Return:

  uint80 or 1

  5.3.7. i2c_master_readByte

  Function: read a byte from slave

  Function definition:

  uint8 i2c_master_readByte (void)

  Input parameters:

  null

  Return:

  uint8the value you read

  5.3.8. i2c_master_writeByte

  Function: write a byte to slave

  Function definition:

  void i2c_master_writeByte (uint8 wrdata)

  Input parameters:

  uint8 wrdatadata to write

  Return:

  null

• ESP8266EX SDK Programming Guide

  61 / 64 Espressif Systems June 19, 2014

  5.4. pwm

  4 PWM outputs are supported, more details in pwm.h.

  5.4.1. pwm_init

  Function: initialize pwm function, including gpio, frequency,
  and duty cycle

  Function definition:

  void pwm_init(uint16 freq, uint8 *duty)

  Input parameters:

  uint16 freqpwms frequency;

  uint8 *dutyduty cycle of each output

  Return:

  null

  5.4.2. pwm_start

  Function: start PWM. This function need to be called after every
  pwm config changing.

  Prototype

  Void pwm_start (void)

  Parameter

  null

  Return

  null

  5.4.3. pwm_set_duty

  Function: set duty cycle of an output

  Function definition:

  void pwm_set_duty(uint8 duty, uint8 channel)

  Input parameters:

  uint8 dutyduty cycle

• ESP8266EX SDK Programming Guide

  62 / 64 Espressif Systems June 19, 2014

  uint8 channelan output

  Return:

  null

  5.4.4. pwm_set_freq

  Function: set pwm frequency

  Function definition:

  void pwm_set_freq(uint16 freq)

  Input parameters:

  uint16 freqpwm frequency

  Return:

  null

  5.4.5. pwm_get_duty

  Function: get duty cycle of an output

  Function definition:

  uint8 pwm_get_duty(uint8 channel)

  Input parameters:

  uint8 channelchannel of which to get duty cycle

  Return:

  uint8duty cycle

  5.4.6. pwm_get_freq

  Function: get pwm frequency

  Function definition:

  uint16 pwm_get_freq(void)

  Input parameters:

  null

• ESP8266EX SDK Programming Guide

  63 / 64 Espressif Systems June 19, 2014

  Return:

  uint16frequency

  6. Appendix

  A. ESPCONN Programming

  Programming guide for ESP8266 running as TCP client and TCP
  server.

  A.1. TCP Client Mode

  A.1.1. Instructions

  ESP8266, working in Station mode, will start client connection
  when given an IP

  address.

  ESP8266, working in softap mode, will start client connection
  when the devices

  which are connected to ESP8266 are given an IP address.

  A.1.2. Steps

  1) Initialize espconn parameters according to protocols.

  2) Register connect callback function, and register recv
  callback function.

  3) Call espconn_connect function and set up the connection with
  TCP Server.

  4) Call registered connect function after successful connection,
  which will register

  the corresponding callback function. Recommend to register
  disconnect callback

  function.

  5) When using recv 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.

• ESP8266EX SDK Programming Guide

  64 / 64 Espressif Systems June 19, 2014

  A.2. TCP Server Mode

  A.2.1. Instructions

  ESP8266, working in Station mode, will start server listening
  when given an IP

  address.

  ESP8266, working in softAP mode, will start server
  listening.

  A.2.2. Steps

  (1) Initialize espconn parameters according to protocols.

  (2) Register connect callback function. You can omit this step
  in udp protocol, but

  register recv callback function.

  (3) Call espconn_accept function to listen to the connection
  with host.

  (4) Call registered connect function after successful
  connection, which will register

  corresponding callback function.

ESP8266 SDK

Getting Started Guide

Version 2.8

Copyright © 2017

About This Guide

This document takes ESP-LAUNCHER and ESP-WROOM-02 as examples to introduce how to use the ESP8266 SDK. The contents include preparations before compilation, SDK compilation and firmware download. The document is structured as follows.

Chapter Title

Chapter 1 Overview

Chapter 2 Preparing the Hardware

Chapter 3 Preparing the Software

Chapter 4 Flash Maps

Chapter 5 Compiling the SDK

Chapter 6

Appendix A

Downloading the

Firmware

Configuring ISSI & MXIC

Flash QIO Mode

Appendix B Learning Resources

Content

Introduction to the overall procedure of using the SDK, and familiarization with the HDK, FW and toolkit of the ESP8266.

Hardware configuration and setup for programming, illustrated with two examples, ESP-LAUNCHER and ESP-WROOM-02.

Presentation of the non-OS SDK and RTOS SDK. Information on the tools for compiling the SDK and downloading the firmware.

Addresses and layout specifications for downloading the firmware to flash memory. Explanation of the OTA and non-OTA firmware.

Introductions on how to compiling the SDK using the relevant tools.

Introductions on how to download the firmware with download tools.

Introduction to ISSI & MXIC Flash QIO mode.

List of ESP8266-related must-read documents and must-have resources.

Release Notes

Date

2016.04

2016.07

2016.07

2016.08

2016.10

2016.11

2017.01

2017.02

Version

V2.0

V2.1

V2.2

V2.3

V2.4

V2.5

V2.6

V2.7

Release notes

First release.

Added MXIC Flash QIO mode

；

Modified the default value of byte 112 to 0.

Updated Section 3.3.1.

Updated the Baidu link in Section 3.3.1.

Updated the flash address of eagle.irom0.text.bin in Section 4.1.1.

Added Appendix B—Learning Resources.

Modified the default value of byte 113 to 0 in Table 6-6.

Added two Github links of RTOS and non-OS SDK sample code in

Appendix B.2—Must-Have Resources.

Updated sections 3.1 and 3.2;

Updated the link for the OVA image file in section 3.3.1;

Updated Section 5.1.2.

Date

2017.05

Version

V2.8

Release notes

Update Chapter 4 for 8MB and 16MB flash support.

Table of Contents

1. Overview ………………………………………………………………………………………………………………..

1

1.1. Procedure Overview …………………………………………………………………………………………………….

1

1.2. ESP8266 HDK …………………………………………………………………………………………………………….

1

1.3. ESP8266 SDK …………………………………………………………………………………………………………….

2

1.3.1. Non-OS SDK …………………………………………………………………………………………………..

2

1.3.2. RTOS SDK ……………………………………………………………………………………………………..

2

1.4. ESP8266 FW ………………………………………………………………………………………………………………

2

1.5. ESP8266 Toolkit ………………………………………………………………………………………………………….

3

1.5.1. Compiler ………………………………………………………………………………………………………..

3

1.5.2. Firmware Download Tool ………………………………………………………………………………….

3

1.5.3. Serial Port Debug Tool ……………………………………………………………………………………..

3

2. Preparing the Hardware …………………………………………………………………………………………..

5

2.1. ESP-LAUNCHER …………………………………………………………………………………………………………

5

2.2. ESP-WROOM-02 ………………………………………………………………………………………………………..

6

3. Preparing the Software …………………………………………………………………………………………….

8

3.1. Non-OS SDK ………………………………………………………………………………………………………………

8

3.2. RTOS SDK …………………………………………………………………………………………………………………

8

3.3. ESP8266 Toolkit ………………………………………………………………………………………………………..

10

3.3.1. Compiler ………………………………………………………………………………………………………

10

3.3.2. Firmware Download Tool ………………………………………………………………………………..

12

4. Flash Maps ……………………………………………………………………………………………………………

13

4.1. Non-OTA ………………………………………………………………………………………………………………….

14

4.1.1. Flash Map …………………………………………………………………………………………………….

14

4.1.2. Download Addresses ……………………………………………………………………………………..

15

4.2. OTA Firmware ……………………………………………………………………………………………………………

15

4.2.1. Flash Map …………………………………………………………………………………………………….

15

4.2.2. Download Addresses ……………………………………………………………………………………..

16

5. Compiling the SDK ………………………………………………………………………………………………..

17

5.1. Preparations ……………………………………………………………………………………………………………..

17

5.1.1. Modifying SDK Files ………………………………………………………………………………………

17

5.1.2. Downloading SDK Files ………………………………………………………………………………….

18

5.2. Compilation ………………………………………………………………………………………………………………

19

5.2.1. Compile ESP8266_NONOS_SDK_v0.9.5 and Later Versions ………………………………

19

5.2.2. ESP8266_NONOS_SDK_v0.9.4 and Earlier Versions ………………………………………….

20

6. Downloading the Firmware …………………………………………………………………………………….

21

6.1. Download Procedure …………………………………………………………………………………………………

21

6.2. Check Log File ………………………………………………………………………………………………………….

23

6.2.1. ESP8266 IOT Demo ……………………………………………………………………………………….

23

6.2.2. ESP8266 AT ………………………………………………………………………………………………….

24

6.3. Configuration of RF initialization (Optional) ……………………………………………………………………

24

6.3.1. Configuration of RF InitConfig Options …………………………………………………………….

25

6.3.2. Configuration of RF InitConfig Parameters ………………………………………………………..

26

6.3.3. Configuration Examples …………………………………………………………………………………

28

A. Appendix—Configuring ISSI & MXIC Flash QIO Mode ………………………………………………

30

B. Appendix—Learning Resources ……………………………………………………………………………..

31

B.1. Must-Read Documents ………………………………………………………………………………………………

31

B.2. Must-Have Resources ………………………………………………………………………………………………..

32

1. Overview

1.

Overview

1.1. Procedure Overview

Figure 1-1 shows the overall procedure of the SDK compilation.

Chapter 3. Preparing the Software Chapter 2. Preparing the Hardware

Tool Download SDK Download

ESP-WROOM-02

ESP-LAUNCHER

Chapter 4. Flash

Map

Compiler ESP8266 SDK Chapter 5.

Compiling the SDK

Tool Download ESP8266 FW

ESP8266 HDK

ESP8266 Toolkit

Chapter 6.

Downloading the Firmware

Figure 1-1 Procedure Overview

1.2. ESP8266 HDK

The ESP8266 HDK (Hardware Development Kit) includes the chip—ESP8266EX, the module—ESP-WROOM-02 and the development board—ESP-LAUNCHER. Users can download the pre-compiled firmware using ESP-WROOM-02 or ESP-LAUNCHER.

📖

Notes:

• If users use other development boards or modules that integrate ESP8266EX, please use the

development firmware provided by the corresponding manufacturers.

• If users would like to purchase ESP-WROOM-02 or ESP-LAUNCHER, please visit Espressif’s official

online store at: https://espressif.taobao.com

,

Espressif 2017.05

1. Overview

1.3. ESP8266 SDK

The ESP8266 Software Development Kit (SDK) is an Internet of Things (IoT) application development platform developed by Espressif for developers. It includes such examples of application development as Smart Lights and Smart Plugs.

Depending on whether they are based on an operating system (OS), SDKs can be categorized into two types: Non-OS SDK and RTOS SDK.

1.3.1. Non-OS SDK

Non-OS SDK is not based on an operating system. It supports the compilation of

IOT_Demo and AT commands. Non-OS SDK uses timers and callbacks as the main way to perform various functions such as nested events and functions triggered by certain conditions. Non-OS SDK uses the espconn network interface; users need to develop their software according to usage rules of the espconn interface.

1.3.2. RTOS SDK

RTOS SDK is based on FreeRTOS, open-source software development on Github.

•

•

The FreeRTOS SDK is based on FreeRTOS , a multi-tasking OS. Users can use standard interfaces to realize resource management, recycling operations, execution delays, inter-task messaging and synchronization, and other task-oriented process design approaches. For the specifics of interface methods, please refer to the official website of FreeRTOS or USING THE FreeRTOS REAL TIME KERNEL—A Practical

Guide

The network operation interface in RTOS SDK is the standard lwIP API. RTOS SDK provides a package which enables a BSD Socket API interface. Users can directly use the socket API to develop software applications; and port to ESP8266 other applications from other platforms using the socket API, effectively reducing the learning costs arising from switching platforms.

•

•

RTOS SDK introduces cJSON library whose functions make it easier to parse JSON packets.

RTOS is compatible with non-OS SDK in Wi-Fi interfaces, SmartConfig interfaces,

Sniffer related interfaces, system interfaces, timer interfaces, FOTA interfaces and peripheral driver interfaces, but does not support AT implementation.

1.4. ESP8266 FW

ESP8266 FW (Firmware) has been provided in binary format files (.BIN) that can be downloaded directly to the HDK. Users can choose between Over-The-Air (OTA) and non-

OTA firmware. For detailed information, please refer to Table 1-1.

Espressif 2017.05

1. Overview

Table 1-1. ESP8266 FW

Binaries

Compulsory or optional

Description Non-OTA

master_device_key.bin

eagle.irom0text.bin

user1.bin

user2.bin

Optional

esp_init_data_default.bin Compulsory

blank.bin

eagle.flash.bin

Compulsory

Compulsory

Users can apply for it from

Espressif Cloud to get Espressif

Cloud service.

Default system parameters provided in SDK.

Default system parameters provided in SDK.

☑

☑

☑

Main program compiled from SDK. ☑

Compulsory Main program compiled from SDK. ☑

Compulsory for first usage.

Main program compiled from SDK.

❌

Used in firmware upgrade.

Main program compiled from SDK.

❌

☑

☑

☑

❌

❌

☑

☑

OTA

📖 Notes:

•

For the contents of SDK, please refer to Chapter 3, «Preparing the Software».

•

•

For SDK compilation, please refer to Chapter 5, «Compiling the SDK».

For the addresses of binaries in the flash, please refer to Chapter 4, «Flash Maps».

1.5. ESP8266 Toolkit

1.5.1. Compiler

Linux OS is required to compile the ESP8266 SDK. When using Windows OS, we recommend VirtualBox as the virtual machine for ESP8266. In order to simplify the compilation procedure, we have installed the compiling tools on the virtual machine. Users can directly compile the ESP8266 SDK by importing the ESP8266 compiler (OVA image) into the virtual machine.

1.5.2. Firmware Download Tool

The ESP8266 DOWNLOAD TOOL is the official firmware download tool developed by

Espressif. Users can download multiple binaries to the SPI Flash of the ESP8266 mother board (ESP-LAUNCHER or ESP-WROOM-02) at the same time according to the actual compilation mode and flash size.

1.5.3. Serial Port Debug Tool

The serial port debug tool can be used to directly communicate with the ESP8266 module over a standard RS-232 port. For PCs that do not have a physical serial port, a virtual com port (USB-to-serial converter) can be used.

Espressif 2017.05

1. Overview

Users may directly input commands into the terminal and view or record responses in real time.

📖 Note:

We recommend CoolTerm (for Windows and Mac OS) and Minicom (for Linux OS) as the serial port debug tool.

Espressif 2017.05

2. Preparing the Hardware

2.

Preparing the Hardware

Depending on whether the ESP-LAUNCHER or the ESP-WROOM-02 is used, users will need either of the hardware mentioned in Table 2-1 below:

ESP-LAUNCHER

• 1 × ESP-LAUNCHER

• 1 × USB cable

Table 2-1. Hardware Preparations

ESP-WROOM-02

• 1 × ESP-WROOM-02

• 1 × USB-to-TTL converter (FT232R recommended)

• 6 × Dupont lines

• 1 × soldering tool suite

OR

1 × PC with pre-installed Windows OS

⚠ Notice:

The ESP8266 Wi-Fi module needs a 3.3V power supply and may draw a minimum current of 500 mA.

2.1. ESP-LAUNCHER

1. Connect PC to the USB-UART interface of ESP-LAUNCHER using the USB cable.

2. Set ESP-LAUNCHER to download mode.

Steps Result

GPIO0 Control Chip Switch

•

•

Slide Power Switch towards the outer side as the figure on the right 👉 shows.

Slide GPIO0 Control towards the inner side to enable ESP-LAUNCHER’s download mode.

⚠ Notice:

J82 must be shorted by a jumper, otherwise code cannot be downloaded to the board.

USB-UART

USB-serial Cable

1

Power Switch J82

1

Espressif 2017.05

2. Preparing the Hardware

3. Connect the USB-to-TTL converter to the PC.

📖 Note:

Make sure that the proper driver for the USB-to-TTL converter is installed and recognized by the PC.

4. Power on ESP-LAUNCHER by sliding the Power Switch towards the inner side.

5. Power on the chip by sliding the Chip Switch towards the outer side.

6. Download firmware to flash with the ESP8266 DOWNLOAD TOOL.

📖 Note:

On how to download firmware, please refer to Chapter 4, «Flash Map» and Chapter 6, «Downloading the

Firmware».

7. After downloading, slide the GPIO0 Control towards the outer side to enable ESP-

LAUNCHER’s working mode.

8. Power on the chip again with the Chip Switch and the chip will read and run programs from the flash.

—— 🔚

For more information on the ESP-LAUNCHER hardware, please refer to

ESP8266 System

Description

.

2.2. ESP-WROOM-02

1. Lead out the pins of the ESP-WROOM-02, as shown in Table 2-2.

Pin

EN

3V3

IO15

IO0

GND

RXD

Table 2-2. ESP-WROOM-02 Pins

Pin status

Pull up

3.3V power supply (VDD)

Pull down

UART download: pull down;

Flash boot: floating/pull up

GND

Receive-end in UART download

Figure

TXD

Transmit-end in UART download; floating/pull up

Espressif 2017.05

Espressif

2. Preparing the Hardware

2. Connect ESP-WROOM-02 to the USB-to-TTL converter, using Dupont lines, as shown in Figure 2-1.

ESP-WROOM-02

3V3

EN

RXD

TXD

GND

USB-to-TTL converter

3V3

TXD

RXD

GND

PC

IO15 IO0

Figure 2-1. ESP-WROOM-02 Download Mode

3. Connect the USB-to-TTL converter to the PC.

4. Download firmware to flash with the ESP8266 DOWNLOAD TOOL.

📖 Note:

On how to download firmware, please refer to Chapter 4, «Flash Maps» and Chapter 6, «Downloading the

Firmware».

5. After downloading, switch ESP-WROOM-02 to working mode.


Set IO0 as floating or pull-up.

6. Power on ESP-LAUNCHER again and the chip will read and run programs from the flash.

——

🔚

📖 Notes:

•

IO0

is an internal pull-up pin.

•

For more information on ESP-WROOM-02 hardware, please refer to ESP8266 System Description and

ESP-WROOM-02 Datasheet .

2017.05

3. Preparing the Software

3.

Preparing the Software

3.1. Non-OS SDK

Users can download the non-OS SDK (including application examples) from:


http://www.espressif.com/en/support/download/sdks-demos?

keys=&field_type_tid%5B%5D=14

.

Figure 3-1 shows the directory structure of the non-OS SDK.

•

•

•

•

•

•

•

•

Figure 3-1. Non-OS SDK Directory Structure

bin: compiled binaries to be downloaded directly into the flash.

documents: SDK-related documents or links.

driver_lib: library files that drive peripherals, such as UART, I2C and GPIO.

examples: sample codes for secondary development, for example, IoT Demo.

include: header files pre-installed in SDK. The files contain relevant API functions and other macro definitions. Users do not need to modify them.

ld: linker scripts. We suggest users not modifying them without any specific reasons.

lib: library files provided in SDK.

tools: tools needed for compiling binaries. Users do not need to modify them.

3.2. RTOS SDK

Users can download RTOS SDK and its application examples (ESP8266_IOT_PLATFORM) from:

•

RTOS SDK


https://github.com/espressif/ESP8266_RTOS_SDK

Espressif 2017.05

•

ESP8266_IOT_PLATFORM


https://github.com/espressif/ESP8266_IOT_PLATFORM

Table 3-2 shows the directory structure of the RTOS SDK.

3. Preparing the Software

Espressif

•

•

•

•

•

•

•

•

•

Figure 3-2. RTOS SDK Directory Structure

bin: boot and initialization firmware.

documents: ESP8266_RTOS_SDK files.

driver_lib: sample codes of drivers.

examples: sample codes for Espressif’s application programs.

openssl_demo: sample codes of the openssl API function.

—

project_template: sample codes of project templates.

smart_config: sample codes of SmartConfig.

—

spiffs_test: sample codes of the spiffs file system function.

websocket_demo: sample codes of web socket.

include: header files of ESP8266_RTOS_SDK, including software interfaces and macro functions for users to use.

ld: link files used when compiling; users do not need to modify them.

lib: library file of ESP8266_RTOS_SDK.

third_party: third-party library of Espressif’s open-source codes, currently including free RTOS, JSON, lwIP, mbedTLS, noPoll, OpenSSL, spiffs, and SSL.

tools: tools needed for compiling binaries; users do not need to modify them.

2017.05

3. Preparing the Software

3.3. ESP8266 Toolkit

3.3.1. Compiler

Please download VirtualBox from:

https://www.virtualbox.org/wiki/Downloads

.

📖 Note:

Please choose the right version of VirtualBox according to the host machine’s OS.

Please download the compiler

ESP8266_lubuntu_20141021.ova from:

http://downloads.espressif.com/FB/ESP8266_GCC.zip

Steps Results

1. Start Windows OS and install the virtual machine.

• Double-click

VirtualBox-5.0.16-105871-Win.exe and install VirtualBox.

📖 Note:

VirtualBox has different versions. We are using Windows V.5.0.16 as an example.

•

Double-click

Oracle VM

VirtualBox.exe to run the program, and the system will show the main menu 👉 .

💬

Tip:

The ESP8266 virtual machine takes up much space (memory). Please reserve enough space for it.

2. Import the image file.

Espressif 2017.05

Espressif

Steps

•

•

•

Select File > Import Appliance, and a dialog box will show up 👉 .

Select the image file to import, for example,

C:

ESP8266_lubuntu_20141021.ova, and click Next.

Click Import to confirm the settings.

3. Create a shared folder.

•

•

•

Create a new folder named

D:

VMshare.

Select

Machine > Settings >

Shared Folders…, and a dialog box will show up 👉 .

Select the shared folder in

Machine

Folders, for example, D:VMshare.

4. Run the virtual machine.

Results

3. Preparing the Software

2017.05

Steps

•

•

After importing, a virtual machine named ESP8266_lubuntu shows up

👉 .

Double-click ESP8266_lubuntu or

Start to run the virtual machine.

•

•

The system shows the ESP8266 virtual machine 👉 .

If a dialog box like the one below 👇 shows up, please enter the password: espressif.

3.3.2. Firmware Download Tool

Please download the ESP8266 DOWNLOAD TOOL from:

http://www.espressif.com/support/download/other-tools

.

Results

3. Preparing the Software

Espressif 2017.05

4.

4. Flash Maps

Flash Maps

This chapter provides the flash maps for OTA firmware and non-OTA firmware in flash memories with a different capacity. Users can modify the map as needed.

Figure 4-1 shows the flash maps for the two different types of firmware.

Non-FOTA

Partition 2

Partition 1

System Program eagle.flash.bin

User Data

System Program eagle.irom0text.bin

Partition 1

User Param master_device_key.bin

FOTA

Partition 2

User Data

System Param (16 kB)

blank.bin

esp_init_data_default.bin

System Program

1.bin

User Data

System Program

2.bin

User Data

Espressif

Boot Data

User Param master_device_key.bin

Reserved

System Param (16 kB)

blank.bin

esp_init_data_default.bin

Figure 4-1. Flash Maps

📖 Note:

For ESP8266 firmware, please refer to Section 1.3, «ESP8266 FW».

•

•

•

System Program: this area stores the firmware necessary for the system to run.

User Data: If system data do not take up all the flash memory, the remaining area can be used to store user data.

User Param: Users can define the address. In IOT_Demo, the four sectors starting from

0x3C000 are defined as the user parameter area. Users can define any available address for this area.

2017.05

4. Flash Maps

•

•

•

master_device_key.bin: In IOT_Demo, it is located in the third sector of user parameter area.

System Param: this area contains the last four sectors of the flash.

—

blank.bin: the download address is the second-to-last sector in the flash.

esp_init_data_default.bin: the download address is the fourth-to-last sector of flash.

Boot Data: It is located in Partition 1 of OTA firmware, and stores OTA-related data.

Reserved: It is a reserved area in Partition 2 of OTA firmware, corresponding to the

Boot data area in Partition 1 of OTA firmware.

📖 Notes:

•

Each sector of the flash is 4 KB.

•

For detailed download addresses, please refer to the following sections..

4.1. Non-OTA

4.1.1. Flash Map

For flash memories with different capacity levels, the storage space of

eagle.irom0text.bin is limited. Users can change the limit by modifying

ESP8266_NONOS_SDK/ld/

eagle.app.v6.ld.

Users can modify the len field in irom0_0_seg, as shown in Figure 4-2 (red rectangle).

The location of

irom0.text varies across different versions of SDK. Users must consult the

eagle.app.v6.ld file and ensure that they are downloading eagle.irom0.text.bin to the correct offset in the flash. The address in the blue rectangle marks the location of

eagle.irom0.text.bin in the flash.

Espressif

Figure 4-2. Location for irom0.text

Table 4-1 shows the storage limits of eagle.irom0text.bin with different len values.

Table 4-1. Non-OTA Flash Map (unit: KB)

Flash capacity

512

1024 eagle.flash.bin

eagle.irom0text.bin

≤ 64

≤ 64

≤ 240

≤ 752

User data

≥ 176

≥ 176 len

0x3C000 16

User/System

Param

0xBC000 16

2017.05

4. Flash Maps

Flash capacity

2048

4096

8192

16*1024 eagle.flash.bin

eagle.irom0text.bin

≤ 64

≤ 64

≤ 64

≤ 64

≤ 768

≤ 768

≤ 768

≤ 768

User data

≥ 176

≥ 176

≥ 176

≥ 176 len

0xC0000 16

User/System

Param

0xC0000 16

0xC0000 16

0xC0000 16

📖 Note:

ESP8266 presently only supports a System Param area of up to 1024 KB.

4.1.2. Download Addresses

Table 4-2 lists the download addresses for non-OTA firmware.

Table 4-2. Download Address for Non-OTA Firmware (unit: KB)

Binaries

512

master_device_key.bin

esp_init_data_default.bin 0x7C000

blank.bin

0x7E000

eagle.flash.bin

eagle.irom0text.bin

Download addresses in flash with different capacities

1024 2048 4096 8192 16*1024

0xFC000

0xFE000

0x3E000

0x1FC000 0x3FC000 0x7FC000 0xFFC000

0x1FE000 0x3FE000 0x7FE000 0xFFE000

0x00000

0x10000

📖 Notes:

• In general, ESP Flash Download Tool can be used to download firmware into flash.

•

But for 8 MB or 16 MB flash, please use esptool instead.

4.2. OTA Firmware

4.2.1. Flash Map

Table 4-3 lists the download addresses for the OTA firmware.

Flash capacity

512

1024

4

4

Table 4-3. OTA Flash Map (unit: KB) boot user1.bin

user2.bin

≤ 236

≤ 492

≤ 236

≤ 492

User/System

Param

16 ≥ 0

User data

16 ≥ 0

Espressif 2017.05

4. Flash Maps

Flash capacity

2048 (Partition 1 = 512)

4

2048 (Partition 1 = 1024)

4

4096 (Partition 1 = 512)

4

4096 (Partition 1 = 1024)

4

8192 (Partition 1 = 1024)

4

16384 (Partition 1 = 1024) 4 boot user1.bin

≤ 492

≤ 1004

≤ 492

≤ 1004

≤ 1004

≤ 1004 user2.bin

≤ 492

≤ 1004

≤ 492

≤ 1004

≤ 1004

≤ 1004

16

16

16

User/System

Param

16

User data

≥ 1024

16

16

≥ 0

≥ 3072

≥ 2048

≥ 6144

≥ 14336

4.2.2. Download Addresses

Table 4-4 lists the download addresses for the OTA firmware.

Table 4-4. Download Addresses for OTA Firmware (unit: KB) user2.bin

Download addresses in flash with different capacities

Binaries

512 1024

512+512

2048

1024+102

4 master_device_key

.bin

esp_init_data

_default.bin

0x3E000 0x7E000 0x7E000

0x7C000 0xFC000

0xFE000

0x1FC000 blank.bin

0x7E000

0xFE000

0x1FE000 boot.bin

user1.bin

512+512

0x7E000

0x00000

0x01000

4096 8192

1024+1024 1024+1024

0xFE000

0x3FC000

0x3FE000

0xFE000

0x7FC000

0x7FE000

16384

1024+1024

0xFE000

0xFFC000

0xFFE000

0x41000 0x81000 0x81000 0x101000 0x81000 0x101000 0x101000 0x101000

📖 Notes:

•

In general, ESP Flash Download Tool can be used to download firmware into flash.

• But for 8 MB or 16 MB flash, please use esptool instead.

•

For OTA firmware, users do not need to download user2.bin, but upgrade the firmware via the cloud server.

•

For details on the functional description of OTA firmware, please refer to ESP8266 FOTA Guide .

Espressif 2017.05

5. Compiling the SDK

5.

Compiling the SDK

📖 Notes:

•

This chapter demonstrates how to compile the SDK by taking

ESP8266_NONOS_SDK/examples/

•

IoT_Demo as an example.

IoT_Demo defines three types of devices, i.e., LIGHT_DEVICE, PLUG_DEVICE and SENSOR_DEVICE in examples>IoT_Demo/include/user_config.h. Users can only configure one device at a time. The default device for configuration is LIGHT_DEVICE.

5.1. Preparations

5.1.1. Modifying SDK Files

📖 Note:

Users need to modify the SDK files if using the OTA firmware.

1. Start Windows OS.

2. Modify files in

ESP8266_NONOS_SDK/examples/IoT_Demo/include according to the flash map.

•

Modify #define PRIV_PARAM_START_SEC in user_light.h and user_plug.h.

Espressif

•

Modify #define ESP_PARAM_START_SEC in

user_esp_platform.h.

Table 5-1 lists the modified values.

Default value

(512)

0x3C

0x3D

—

Table 5-1. Modify the Field Values in the «include» File (unit: kB)

512 1024

0x7C

2048

(512+512)

0x7C

2048

(1024+1024)

0xFC

Modified values

4096

(512+512)

4096

(1024+1024)

0x7C 0xFC

8192

(1024+1024)

0xFC

16384

(1024+1024)

0xFC

0x7D 0x7D 0xFD 0x7D 0xFD 0xFD 0xFD

2017.05

📖 Note:

Users need not modify the SDK files if using a 512-KB flash.

5.1.2. Downloading SDK Files

1. Start Linux OS.

2. Run LXTerminal on the desktop of the virtual machine.

3. Copy the files to be compiled to the shared folder.

Steps

•

•

Copy ESP8266_NONOS_SDK folder to the shared directory, for example, C:VMshare.

Copy IoT_Demo folder to C:

VMshareESP8266_NONOS_SDK, as shown in the figure on the right 👉 .

Results

5. Compiling the SDK

4. Download shared directory.

Steps

•

•

•

Execute ./mount.sh.

Input the password: espressif.


Downloading shared files is completed.

Open the shared directory

ESP8266_NONOS_SDK in the virtual machine and confirm whether the download has been successful.

— If successful, the directory contains such files as those in the figure on the right 👉 .

— If not, the directory will be empty, and users will need to go over this step again.

Results

Espressif

⚠ Notice:

If users use the RTOS SDK, please continue with the following steps; if use the non-OS SDK, please skip

Step 5.

5. Set the variable PATH to point to SDK and binaries. export SDK_PATH=~/Share/ESP8266_RTOS_SDK
export BIN_PATH=~/Share/ESP8266_RTOS_SDK/bin

2017.05

5. Compiling the SDK

📖 Note:

Users can add it to .bashrc file, otherwise Step 5 needs to be repeated each time the compiler is restarted.

5.2. Compilation

5.2.1. Compile ESP8266_NONOS_SDK_v0.9.5 and Later Versions

1. Switch to the /Share/ESP8266_NONOS_SDK/IoT_Demo directory in the terminal. cd /home/esp8266/Share/ESP8266_NONOS_SDK/IoT_Demo

./gen_misc.sh

The system shows the following information: gen_misc.sh version 20150511

Please follow below steps(1-5) to generate specific bin(s):

2. Select the required options as shown in Figure 5-1.

FOTA?

Y

New version?

N

0

Y

1

N

2

STEP 1: choose boot version

(0=boot_v1.1, 1=boot_v1.2+, 2=none) enter(0/1/2, default 2)

First-time usage?

N

2 Y 1 0

STEP 2: choose bin generate

(0=eagle.flash.bin+eagle.irom0text.bin

, 1=user1.bin, 2=user2.bin) enter (0/1/2, default 0)

Choose as required

0

1 2 3

STEP 3: choose spi speed

(0=20MHz, 1=26.7MHz, 2=40MHz, 3=80MHz) enter (0/1/2/3, default 2)

Choose as required

0 1 2 3

STEP 4: choose spi mode

(0=QIO, 1=QOUT, 2=DIO, 3=DOUT) enter (0/1/2/3, default 0)

Choose as required

0 2

3

4 5 6

STEP 5: choose spi size and map

0= 512KB( 256KB+ 256KB) enter (0/2/3/4/5/6, default 0)

Example Option

Figure 5-1. Compile SDK

Espressif 2017.05

5. Compiling the SDK

📖 Notes:

•

The sample options are marked in green. Users can select the right options as needed.

•

•

•

•

For OTA and non-OTA firmware, please refer to Section 1.4, «ESP8266 FW».

Only sdk_v1.1.0 + boot 1.4 + flash download tool_v1.2 and higher versions support options 5 and 6 in

Step 5.

After compiling

user1.bin, execute make clean first to clear the temporary files generated by the last

compilation, and then compile user2.bin.

For the flash map in Step 5, please refer to Chapter 4, «Flash Maps».

3. After compilation, the generated binaries and the addresses in flash are shown as follows:

Generate user1.2048.new.3.bin successfully in folder bin/upgrade.

boot.bin————>0x00000
user1.2048.new.3.bin—>0xSupport boot_v1.2 and +

01000

!!!

📖 Note:

Users can open the

/home/esp8266/Share/ESP8266_NONOS_SDK/bin directory and check the compiled binaries.

−−

🔚

5.2.2. ESP8266_NONOS_SDK_v0.9.4 and Earlier Versions

For ESP8266_NONOS_SDK_v0.9.4 and previous versions, the compilation process is as follows:

1. Execute ./gen_misc_plus.sh 1 to generate user1.bin under the


/ESP8266_NONOS_SDK/bin/upgrade path.

2. Execute make clean to clear previous compilation data.

3. Execute ./gen_misc_plus.sh 2 to generate

user2.bin under the


/ESP8266_NONOS_SDK/bin/upgrade path.

📖 Note:

ESP8266_NONOS_SDK_v0.7 and earlier are non-OTA firmware.

Espressif 2017.05

6. Downloading the Firmware

6.

Downloading the Firmware

6.1. Download Procedure

1. Start Windows OS.

2. Double-click ESP_DOWNLOAD_TOOL.exe to open Flash tool.

Espressif

SPIDownload

HSPIDownload

RFConfig

MutiDownload

Figure 6-1. ESP8266 DOWNLOAD TOOL—SPIDownload

For SPI Flash download.

For HSPI Flash download.

RF initialization Configuration.

For multi-mother boards download.

2017.05

Espressif

6. Downloading the Firmware

3. Double-click !

in

Download Path Config panel to select the binaries to be downloaded. Set the corresponding download addresses in ADDR.

4. Configure SPIDownload.

📖 Note:

The binaries to be downloaded and the corresponding addresses vary with different SPI Flash sizes and actual demands. For details, please refer to Chapter 4, «Flash Maps».

Items

CrystalFreq

CombineBin

Default

SPI SPEED

SPI MODE

FLASH SIZE

SpiAutoSet

DoNotChgBin

START

STOP

MAC Address

COM PORT

Table 6-1. SPIDownload Configuration

Description

SPI FLASH CONFIG

Select the crystal frequency according to the crystal oscillator used.

Combine the selected binaries into target.bin with the address 0x0000.

Set the SPI Flash to the default value.

Select SPI read/write speed with the maximum value of 80 MHz.

Select SPI mode according to the SPI Flash used. If the flash is Dual SPI, select

DIO or DOUT. If the flash is Quad SPI, select DIO or DOUT.

⚠ Notice:

If ISSI Flash is used, please refer to Appendix, «Configure ISSI & MXIC Flash QIO

Mode».

Select the flash size according to the flash type.

📖 Note:

16Mbit-C1 refers to 1024+1024 flash map and 32Mbit-C1 1024+1024 flash map as well.

We recommend not checking SpiAutoSet, but configuring the flash manually as needed.

If users select SpiAutoSet, the binaries will be downloaded according to the default flash map. The flash map of 16 Mbit and 32 Mbit will be 512 KByte + 512

KByte.

•

•

If users select DoNotChgBin, the flash working frequency, mode, and flash map will be based on the configuration when compiling.

If users do not select DoNotChgBin, the flash working frequency, mode, and flash map will be defined by the final configuration of the compiler.

Download Panel

Click START to start download. When the download completes, FINISH will appear in the green area on the left.

Click STOP to stop download.

If download is successful, the system will show the MAC addresses of ESP8266

STA and ESP8266 AP.

Select the actual COM port of ESP8266.

2017.05

6. Downloading the Firmware

Items Description

SPI FLASH CONFIG

BAUDRATE

Select the baud rate of downloading. The default value is 115200.

5. After downloading, turn GPIO0 Control on ESP-LAUNCHER to the outer side and power the board on to enable the working mode.

6.2. Check Log File

After downloading firmware, users can check the log printed in the terminal by using the serial port debug tool.

Users need to configure the settings of the serial port debug tool, as follows:

Items

Table 6-2. Serial Port Debug Tool Configuration

Configuration Description

Protocol

Port number

Baud rate

Data bit

Calibration

Flow control

Serial port.

Set the port number according to the connected device.

•

•

•

The baud rate at which the device is running, related to the crystal oscillator.

69120 (24 M crystal oscillator)

74880 (26 M crystal oscillator)

115200 (40 M crystal oscillator)

The ESP8266 AT example supports the baud rate of 115200 by default.

Users cannot modify it.

The ESP8266 IOT Demo example supports the baud rate of 74880. Users can modify it.

8

None.

None.

6.2.1. ESP8266 IOT Demo

If users download ESP8266 IOT Demo firmware, the system in working mode will show the initialization information including the SDK version, etc. “Finish” means the firmware works properly.

SDK version:X.X.X(e67da894)

IOT VERSION = v1.0.5t45772(a)
reset reason: 0

PWM version: 00000003
mode: sta(18:fe:34:a4:8c:a3) + softAP(1a:fe:34:a4:8c:a3)

Espressif 2017.05

6. Downloading the Firmware add if0
add if1
dhcp server start:(ip:192.168.4.1,mask:255.255.255.0,gw:192.168.4.1)
bcn 100
finish

6.2.2. ESP8266 AT

If users download the ESP8266 AT firmware, or the default firmware in ESP-LAUNCHER or

ESP-WROOM-02, the system in working mode will display “Ready” at the end. Input command “AT” in the terminal and the system will return “OK”, which means that the firmware works properly.

📖 Notes:

•

•

The baud rate in AT firmware is configured as 115200 manually, however, the default baud rate of

ESP8266 is 74880, due to this discrepancy, the system initialization information will be displayed as mojibake. It is a normal phenomenon as long as the system shows “Ready” at the end.

For more information on AT commands, please refer to

ESP8266 AT Instruction Set

.

6.3. Configuration of RF initialization (Optional)

Before downloading binaries to flash, users can modify the RF initialization settings in the

RF InitConfig tab. The newly-generated esp_init_data_setting.bin can be downloaded to the flash instead of esp_init_data_default.bin. Users can configure both the options and the parameters of the RF settings.

Espressif 2017.05

6. Downloading the Firmware

Figure 6-2. ESP8266 DOWNLOAD TOOL — RF InitConfig

6.3.1. Configuration of RF InitConfig Options

RF InitConfig options are listed in the upper part of Figure 6-2. Please refer to Table 6-3 for a description of this configuration.

Items

Table 6-3. Configuration of RF InitConfig Options

Description

TxTargetPowerConfig

Users need not configure this. It varies with the options in LowPowerMode.

LowPowerMode

CrystalFreq

Configure the low power mode as required.

•

•

• LowPowerEn: enable low power mode, set a power value for all data rates.

PowerLimtEn: set a limit for output power.

BackOffEn: set backoff value for each data rate.

📖 Note:

Users cannot configure LowPowerEn and PowerLimtEn at the same time.

Select the crystal oscillator frequency according to the crystal oscillator used.

📖 Note:

If a different option is selected when downloading, it will override this configuration.

Espressif 2017.05

6. Downloading the Firmware

Items

TOUT PinConf

FreqOffset

RFInt mode

Description

Configure the TOUT pin according to the actual TOUT pin status. We recommend the default value.

• TOUT_ADC_EN: When the TOUT pin connects to an external circuit, measure the external voltage (0V — 1V) through the internal ADC.

• TOUT_VDD_EN: When TOUT pin is left floating, measure VDD33 voltage through uint16 system_get_vdd33(void).

⚠ Notice:

•

Users cannot configure TOUT_ADC_EN and TOUT_VDD_EN at the same time.

•

When users use TOUT_ADC_EN, they need to input the actual voltage on

VDD3P3 pin 3 and pin 4.

• SetFreqEnable: Set the frequency offset manually.

— PracticalFreqOffset: the option is valid when selecting SetFreqEnable.

• AutoCalEn: Set the frequency offset automatically.

Users can select the RF initialization mode:

• LoadRFCalParam: During the RF initialization, RF data are loaded directly from the flash without any calibration. It takes about 2 ms and the least initial current.

• TxPwrCtrl in init: During the RF initialization, only Tx Power calibration will be performed, and other data are loaded from flash. It takes about 20 ms and small initial current.

• FullRFCal in RFInit: All calibrations are performed during the RF initialization. It takes 200 ms and large initial current.

6.3.2. Configuration of RF InitConfig Parameters

RF InitConfig parameters are listed in the lower part of Figure 6-2. The description of parameters’ configuration is shown in Table 6-4.

Items

A

D

E

B

C

Table 6-4. Configuration of RF InitConfig Parameters

Description

The byte in esp_init_data_setting.bin (0 ~ 127 byte). For example, A = 0 represents Byte 0 in esp_init_data_setting.bin.

The item name. Users cannot modify it if marked as Reserved.

The item name. Users cannot modify it if marked as Reserved.

Data types of configuration items, including unsigned and signed data types.

The hexadecimal value of a configuration item.

⚠ Notice:

Please do not modify the parameters marked as Reserved.

Espressif 2017.05

6. Downloading the Firmware

The following section introduces how to modify the 112 ~ 114 byte parameters. Figure 6-3 shows the initial configuration.

Espressif

Figure 6-3. 112

～ 114 Byte Parameters

Modify the RF Initialization Parameters

Byte 114 is used to control THE RF initialization when ESP8266 is powered on. Table 6-5 provides the parameter configuration.

📖 Note:

Supported by ESP8266_NONOS_SDK_V1.5.3 and ESP8266_RTOS_SDK_V1.3.0 and higher.

Option byte 114 = 0 byte 114 = 1 byte 114 = 2 byte 114 = 3

Table 6-5. Modify RF Initialization Parameters

Description

Only a VDD33 calibration is performed during the RF initialization. It takes about 2 ms and the least initial current.

The default value is 1.

VDD33 and TX power calibrations are performed during the RF initialization. It takes about 18 ms and small initial current.

The same as when “ byte 114 = 0”.

All calibrations are performed during the RF initialization. It takes about 200 ms and large initial current.

Correct Frequency Offset

Byte 112 and byte 113 relate to the frequency offset correction. Table 6-6 provides the parameter configuration.

📖 Note:

Supported by ESP8266_NONOS_SDK_V1.4.0 and ESP8266_RTOS_SDK_V1.3.0 and higher.

Option bit 0

Table 6-6. Options for Frequency Offset Correction

Description

The default value of byte 112 is 0.

This bit is of the highest priority.

• bit 0 = 0: frequency offset cannot be corrected.

• bit 0 = 1: frequency offset can be corrected.

2017.05

6. Downloading the Firmware

Option bit 1

{bit 3

，bit 2}

113 byte

Description

The default value of byte 112 is 0.

When value = 0, it means that the bbpll is 168 M. Both positive and negative frequency offsets can be corrected.

However, this may effect the digital peripheral performance and, therefore, it is not recommended.

When value = 1, it means that the bbpll is 160 M. Only the positive frequency offset can be corrected.

When value = 0, it means that the chip will track and correct the frequency offset automatically. The initial correction value is 0. When value = 1, it means that the chip is manually programmed to change the frequency offset to that of byte 113, so the chip will not track and correct the frequency offset automatically. When value = 2, it means that the chip will track and correct the frequency offset automatically. The initial correction value is that of byte 113.

The default value of byte 113 is 0.

It is the value when the frequency offset is corrected manually or the initial correction value in frequency tracking. The data type is sign int8, in multiples of 8 kHz.

6.3.3. Configuration Examples

The configuration of bytes 112 and 113 depends depends on users’ specific needs. We provide some examples below:

1. The module works at ambient temperature, and needs no correction of the frequency offset.

•

Set byte 112 = 0, byte 113 = 0.

2. The module works at ambient temperature and needs no automatic tracking and correction of the frequency offset; yet the frequency offset is large. In this case, a manual correction of the frequency offset is recommended.

• If the frequency offset is +160 KHz (at ambient temperature), users can set byte 112

= 0x07, byte 113 = (256 — 160/8) = 236 = 0xEC.

•

If the frequency offset is -160 KHz (at ambient temperature), users can set byte 112 =

0x05, byte 113 = 160/8 = 20 = 0x14. This may effect the digital peripheral performance, so we do not recommend it.

3. Applications, such as smart lights, work at a wide temperature range of -40 °C to

125 °C, and need to track and correct the frequency offset automatically. The frequency offset at ambient temperature is small, so the initial offset correction value is not needed.

•

Set byte 112 = 0x03, byte 113 = 0.

Espressif 2017.05

6. Downloading the Firmware

4. Applications, such as smart lights, work at a wide temperature range of -40 °C to

125 °C, and need to track and correct the frequency offset automatically. The frequency offset at ambient temperature is large, so the initial offset correction value is needed.

•

If the frequency offset is +160 kHz (at ambient temperature), users can set byte 112

= 0x0B, byte 113 = (256 — 160/8) = 236 = 0xEC.

•

If the frequency offset is -160 kHz (at ambient temperature), users can set byte 112

= 0x09, byte 113 = 160/8 = 20 = 0x14. But this may effect the digital peripheral performance and needs substantive tests, so we do not recommend it.

We recommend Example 3.

When the configuration of RF initialization is done, click

GenInitBin button to generate

esp_init_data_setting.bin.

In addition, users can click Default button to set the value of frequency offset to default, or click

LoadInitBin button to import a binary file for configuration.

Espressif 2017.05

Appendix A

A. Appendix—Configuring ISSI &

MXIC Flash QIO Mode

⚠ Notice:

Choose DIO or DOUT mode when downloading, otherwise errors may occur. There is no need to modify binaries in DIO or DOUT mode.

When using QIO mode of ISSI flash or MXIC flash, users need to modify the first two bytes in

blank.bin, as shown in Table A-1. During initialization, ESP8266 will automatically check the first two bytes and switch to QIO mode to read ISSI_FLASH or MXIC_FLASH. The structure of blank.bin is shown below:

strcut boot_hdr{

char user_bin:2; //low_bit

char boot_status:1;

char to_qio:1;

char reverse:4;

char version:5; //low bit

char test_pass_flag:1;

char test_start_flag:1;

char enhance_boot_flag:1;

}

Option

Table A-1. blank.bin Configuration

Description

Without secondary boot loader

Modify to_qio to 0.

With secondary boot loader

Modify use_bin to 0 and to_qio to 0, as well. Modify version according to the current boot version.

Example:

If users use the secondary boot_v1.5.bin, please modify the first two bytes FF FF to F4 E5.

Espressif 2017.05

Appendix B

B.

Appendix—Learning

Resources

B.1. Must-Read Documents

•

ESP8266EX Datasheet

Description: This document introduces the specifications of ESP8266EX, including an overview of the features, protocols, technical parameters and applications. It also describes the pin layout, as well as major functional modules integrated in ESP8266EX

(CPU, flash and memory, clock, radio, Wi-Fi, and low-power management). Additionally, it provides descriptions of peripheral interfaces integrated on ESP8266EX, lists the electrical data of ESP8266EX and illustrates the package details of ESP8266EX.

ESP8266 Hardware Resources

•

•

•

Description: This zip package includes the manufacturing specifications of the ESP8266 board and its modules, manufacturing BOM and schematics.

ESP8266 Non-OS SDK IoT_Demo Guide

Description: This documents provides simple demo implementations of three types of smart devices: Smart Light, Smart Power Plug, and Sensor Device. It also introduces the readers to curl toolkits, functions in LAN and WAN.

ESP8266 RTOS SDK Programming Guide

Description: This document provides sample codes based on ESP8266_RTOS_SDK, including basic examples, networking protocol examples and advanced examples.

ESP8266 AT Command Examples

•

•

Description: This document introduces some specific examples of how to use Espressif

AT commands, including single connection as a TCP client, UDP transmission and transparent transmission, and multiple connection as a TCP server.

ESP8266 AT Instruction Set

•

•

Description: This document provides lists of AT commands based on

ESP8266_NONOS_SDK, including user-defined AT commands, basic AT commands,

Wi-Fi AT commands and TCP/IP-related AT commands. It also introduces the downloading of AT firmware into flash.

ESP8266 Non-OS SDK API Reference

Description: This document lists ESP8266_NONOS_SDK APIs, provides an overview of

ESP8266_NONOS_SDK and introduces the readers to system APIs, TCP/UDP APIs, mesh APIs, application specific APIs, definitions and data structures, and APIs for peripheral interfacing.

ESP8266 RTOS SDK API Reference

Espressif 2017.05

Appendix B

•

Description: This document lists ESP8266_RTOS_SDK APIs, including functions for Wi-

Fi related APIs, boot APIs, etc.

FAQ

B.2. Must-Have Resources

•

•

•

•

•

•

•

•

ESP8266 SDKs

Description: This webpage provides links to the latest version of ESP8266 SDK and the older ones.

RTOS Sample Code

Description: This webpage provides the sample code for the commonly used functions.

Non-OS Sample Code

Description: This webpage provides the sample code for the commonly used functions.

ESP8266 Tools

Description: This webpage provides links to the ESP8266 flash download tools and

ESP8266 performance evaluation tools.

ESP8266 APK

ESP8266 Certification and Test Guide

ESP8266 BBS

ESP8266 Resources

Espressif 2017.05

Espressif IOT Team

www.espressif.com

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, NON-INFRINGEMENT, 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. The Bluetooth logo is a registered trademark of Bluetooth SIG.

All trade names, trademarks and registered trademarks mentioned in this document are property of their respective owners, and are hereby acknowledged.

Copyright © 2017 Espressif Inc. All rights reserved.