Professional Documents
Culture Documents
ESP8266 - IoT - SDK - Programming Guide - v0.9.1 PDF
ESP8266 - IoT - SDK - Programming Guide - v0.9.1 PDF
Status Released
Current version V0.9.1
Author Fei Yu
[ ] CONFIDENTIAL
[ ] INTERNAL
[ ] PUBLIC
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 1.Add UART APIs;
/ Han Liu 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 1.Revise espconn APIs;
/ Han Liu 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 station’s
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 1、Add system_deep_sleep;
2、Revise APIs to read/write flash;
3、Add APIs for AP_CHE
4、Revise UDP APIs
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
4 / 64 Espressif Systems June 19, 2014
ESP8266EX SDK Programming Guide
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
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.
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.
3.1. Timer
Locate in “\esp_iot_sdk\include\osapi.h”
3.1.1. os_timer_arm
3.1.2. os_timer_disarm
3.1.3. os_timer_setfn
3.2.1. system_restore
3.2.2. system_restart
Function: Restart
Prototype:
void system_restart(void)
Input parameters:
3.2.3. system_get_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
3.2.6. system_upgrade_start
3.2.7. system_upgrade_reboot
3.2.8. system_set_os_print
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
3.2.11. system_get_free_heap_size
3.2.12. system_os_task
3.2.13. system_os_post
3.2.14. spi_flash_erase_sector
3.2.15. spi_flash_write
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,
3.2.16. spi_flash_read
3.2.17. wifi_get_opmode
3.2.18. wifi_set_opmode
3.2.19. wifi_station_get_config
3.2.20. wifi_station_set_config
3.2.21. wifi_station_connect
3.2.22. wifi_station_disconnect
3.2.23. wifi_station_get_connect_status
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; // AP’s ssid
uint8 *bssid; // AP’s bssid
uint8 channel; //scan a specific channel
};
Parameters:
struct scan_config *config – AP config for scan
if config = Null, scan all APs
if config.ssid、config.bssid are null,config.channel isn’t 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
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 recorded(MAX: 5)
eg: if ap_number is 5, record id : 0 ~ 4
Return:
True - succeed;
False - fail.
3.2.27. wifi_station_ap_change
3.2.28. wifi_station_get_current_ap_id
3.2.29. wifi_softap_get_config
3.2.30. wifi_softap_set_config
3.2.31. wifi_softap_get_station_info
Function: get connected station devices under softap mode, including mac and ip
3.2.32. wifi_softap_free_station_info
3.2.33. wifi_get_ip_info
3.2.34. wifi_set_ip_info
3.2.35. wifi_set_macaddr
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
3.2.37. wifi_status_led_install
3.2.38. wifi_promiscuous_enable
3.2.39. wifi_set_promiscuous_rx_cb
3.2.40. wifi_get_channel
3.2.41. wifi_set_channel
Locate in “esp_iot_sdk\include\espconn.h”
General APIs:APIs can be used for both TCP and UDP .
TCP APIs:APIs that are only used for TCP.
UDP APIs:APIs that are only used for UDP.
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 *espconn——corresponding connected control block structure
const char *hostname——domain name string pointer
ip_addr_t *addr——ip address
dns_found_callback found——callback
Return:
Err_t——ESPCONN_OK
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.%d\n",
*((uint8 *)&ipaddr->addr), *((uint8 *)&ipaddr->addr + 1),
*((uint8 *)&ipaddr->addr + 2), *((uint8 *)&ipaddr->addr + 3));
}
Void dns_test(void)
3.3.1.2. espconn_port
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 *espconn——corresponding connected control block structure
espconn_sent_callback sent_cb——registered callback function
Return:
0 - succeed, #define ESPCONN_OK 0
Not 0 - error, pls refer to espconn.h
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 *espconn——corresponding connected control block structure
espconn_connect_callback connect_cb——registered callback function
Return:
0 - succeed, #define ESPCONN_OK 0
Not 0 - error, pls refer to espconn.h
3.3.1.5. espconn_sent_callback
3.3.1.6. espconn_recv_callback
3.3.1.7. espconn_sent
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 *espconn——corresponding connected control block structure
Return:
0 - succeed, #define ESPCONN_OK 0
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 *espconn——corresponding 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
3.3.2.4. espconn_get_connection_info
3.3.2.5. espconn_connect
3.3.2.6. espconn_connect_callback
3.3.2.7. espconn_disconnect
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 *espconn——corresponding connected control block structure
espconn_connect_callback connect_cb——registered callback function
Return:
0- succeed, #define ESPCONN_OK 0
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 *espconn——corresponding connected control block structure
espconn_connect_callback connect_cb——registered 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 *espconn——corresponding connected control block structure
espconn_connect_callback connect_cb——registered callback function
Return:
0 - succeed, #define ESPCONN_OK 0
Not 0 - error, pls refer to espconn.h
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 *espconn——corresponding 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
3.3.2.13. espconn_secure_disconnect
3.3.3.1. espconn_create
3.3.3.2. espconn_delete
3.4.1. jsonparse_setup
3.4.2. jsonparse_next
3.4.3. jsonparse_copy_value
3.4.4. jsonparse_get_value_as_int
3.4.5. jsonparse_get_value_as_long
3.4.6. jsonparse_get_len
3.4.7. jsonparse_get_value_as_type
3.4.8. jsonparse_strcmp_value
3.4.9. jsontree_set_up
3.4.10. jsontree_reset
3.4.11. jsontree_path_name
3.4.12. jsontree_write_int
3.4.13. jsontree_write_int_array
3.4.14. jsontree_write_string
3.4.15. jsontree_print_next
3.4.16. jsontree_find_next
4. Structure definition
4.1. Timer
struct station_config {
uint8 ssid[32];
uint8 password[64];
};
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);
struct jsontree_value {
uint8_t type;
};
48 / 64 Espressif Systems June 19, 2014
ESP8266EX SDK Programming Guide
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;
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.4.2 espconn
/** 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
};
5. Driver
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
Example:PIN_FUNC_SELECT(PERIPHS_IO_MUX_MTDI_U, FUNC_GPIO12);
Use MTDI pin as GPIO12。
5.1.2. gpio_output_set
Example:
Set GPIO12 as high-level output:gpio_output_set(BIT12, 0, BIT12, 0);
Set GPIO12 as low-level output:gpio_output_set(0, BIT12, BIT12, 0);
Set GPIO12 as high-level output,GPIO13 as low-level output,则:
gpio_output_set(BIT12, BIT13, BIT12|BIT13, 0);
Set GPIO12 as input : gpio_output_set(0, 0, 0, BIT12);
GPIO_OUTPUT_SET(gpio_no, bit_value)
Set gpio_no as output bit_value,the same as the output example in 5.1.2
GPIO_DIS_OUTPUT(gpio_no)
Set gpio_no as input, the same as the input example in 5.1.2.
GPIO_INPUT_GET(gpio_no)
Get the level status of gpio_no.
ETS_GPIO_INTR_ATTACH(func, arg)
Register GPIO interrupt control function
ETS_GPIO_INTR_DISABLE()
Disable GPIO interrupt
ETS_GPIO_INTR_ENABLE()
Enable GPIO interrupt
5.1.5. gpio_pin_intr_state_set
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);
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.
5.2.1. uart_init
5.2.2. uart0_tx_buffer
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*para——the pointer pointing to RcvMsgBuff structure
Return:
NULL
5.3.1. i2c_master_gpio_init
5.3.2. i2c_master_init
5.3.3. i2c_master_start
5.3.4. i2c_master_stop
5.3.5. i2c_master_setAck
5.3.6. i2c_master_getAck
5.3.7. i2c_master_readByte
5.3.8. i2c_master_writeByte
5.4. pwm
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 freq——pwm’s frequency;
uint8 *duty——duty 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
5.4.4. pwm_set_freq
5.4.5. pwm_get_duty
5.4.6. pwm_get_freq
6. Appendix
A. ESPCONN Programming
Programming guide for ESP8266 running as TCP client and TCP server.
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
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