ESP8266 IoT SDK Programming Guide v0.9.1

Download as pdf or txt
Download as pdf or txt
You are on page 1of 64

ESP8266EX SDK Programming Guide

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

1 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

Version Info
Date

Version

2013.12.25

0.1

2013.12.25

0.1.1

2014.1.15

0.2

2014.1.29

0.3

2014.3.20

0.4

2014.4.17

0.5

Jiangang Wu
/ Han Liu

2014.5.14

0.6

2014.6.18

0.7

Jiangang Wu
Jiangang Wu

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

2 / 64

Author
Jiangang Wu
Han Liu
Jiangang Wu
Han Liu
Jiangang Wu
/ Han Liu

Espressif Systems

Comments/Changes
Draft
Revise Json APIs
Revise some APIs
Add client/server APIs
1.Add UART APIs
2.Add i2c master APIs
3.Revise client/server APIs
4.Add secure espconn APIs
5.Add upgrade APIs
1.Revise espconn APIs
2.Add gpio APIs instruction
3.Add some other instructions
Add some APIs
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

June 19, 2014

ESP8266EX SDK Programming Guide

Disclaimer and Copyright Notice


Information in this document, including URL references, is subject to change without
notice.
THIS DOCUMENT IS PROVIDED "AS IS" WITH NO WARRANTIES
WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY,
NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY
WARRANTY

OTHERWISE

ARISING

OUT

OF

ANY

PROPOSAL,

SPECIFICATION OR SAMPLE. All liability, including liability for infringement of


any proprietary rights, relating to use of information in this document is disclaimed. No
licenses express or implied, by estoppel or otherwise, to any intellectual property rights
are granted herein.
The Wi-Fi Alliance Member Logo is a trademark of the Wi-Fi Alliance.
All trade names, trademarks and registered trademarks mentioned in this document are
property of their respective owners, and are hereby acknowledged.
Copyright 2013 Espressif Systems Inc. All rights reserved.

3 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
5 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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
6 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

7 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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.

8 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

2. Overview
The SDK provides a set of interfaces for data receive and transmit functions over
the Wi-Fi and TCP/IP layer so programmers can focus on application development on
the high level. Users can easily make use of the corresponding interfaces to realize data
receive and transmit.
All networking functions on the ESP8266 IoT platform are realized in the library,
and are not transparent to users. Instead, users can initialize the interface in
user_main.c
void 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.

9 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

3. Application Programming Interface (APIs)


3.1. Timer
Locate in \esp_iot_sdk\include\osapi.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

10 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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 \include\user_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:
11 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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:
12 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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:
13 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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
14 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

os_event_t *testQueue;
void test_task (os_event_t *e)
{
15 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


switch (e->sig) {
case SIG_RX:
os_printf(sig_rx %c\n, (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);
}
16 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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,
17 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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
18 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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.
19 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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.

20 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

21 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
22 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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.


23 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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,


24 / 64

Espressif Systems

including mac and ip


June 19, 2014

ESP8266EX SDK Programming Guide


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();
25 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

3.2.33.

// Free it by calling functions

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


26 / 64

ip information
Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

uint8 *macaddr

#define STATION_IF

0x00

#define SOFTAP_IF

0x01

mac address

Example
char sofap_mac[6] = {0x16, 0x34, 0x56, 0x78, 0x90, 0xab};
char sta_mac[6] = {0x12, 0x34, 0x56, 0x78, 0x90, 0xab};
27 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
28 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

Example
Use GPIO0 as wifi status LED
#define HUMITURE_WIFI_LED_IO_MUX

PERIPHS_IO_MUX_GPIO0_U

#define HUMITURE_WIFI_LED_IO_NUM

#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
29 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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_sdk\include\espconn.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.

30 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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.%d\n",
*((uint8 *)&ipaddr->addr), *((uint8 *)&ipaddr->addr + 1),
*((uint8 *)&ipaddr->addr + 2), *((uint8 *)&ipaddr->addr + 3));
}
Void dns_test(void)
31 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


{
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

Not 0

error, pls refer to espconn.h

32 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

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:
33 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

Not 0 -

succeed, #define ESPCONN_OK

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
34 / 64

succeed, #define ESPCONN_OK

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

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

Not 0

error, pls refer to espconn.h

35 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

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

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:
36 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

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:
037 / 64

succeed, #define ESPCONN_OK

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


Not 0 -

3.3.2.9.

error, pls refer to espconn.h

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

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

Not 0 38 / 64

succeed, #define ESPCONN_OK

error, pls refer to espconn.h


Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

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

Not 0 -

succeed, #define ESPCONN_OK

error, pls refer to espconn.h

3.3.2.13. espconn_secure_disconnect
Function: secure TCP disconnection(SSL)
39 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


Function definition:
Sint8 espconn_secure_disconnect(struct espconn *espconn)
Input parameters:
struct espconn *espconncorresponding connected control block structure
Return:
0

succeed, #define ESPCONN_OK

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

Not 0

succeed#define ESPCONN_OK 0

3.3.3.2.

Erropls refer to espconn.h

espconn_delete

Function: delete UDP transmission.


Prototype
Sin8 espconn_delete(struct espconn *espconn)
Parameter
struct espconn *espconncorresponding connected control block structure
Return
40 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


0

Not 0

succeed#define ESPCONN_OK 0
-

Erropls refer to espconn.h

3.4. json APIs


Locate in : esp_iot_sdk\include\json\jsonparse.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:
41 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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:
42 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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,
43 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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


44 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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:
45 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

46 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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,
47 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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;
};
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;
49 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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 = {
50 / 64

Espressif Systems

\
\

June 19, 2014

ESP8266EX SDK Programming Guide


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


51 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


enum espconn_type {
ESPCONN_INVALID

= 0,

/* ESPCONN_TCP Group */
ESPCONN_TCP

= 0x10,

/* ESPCONN_UDP Group */
ESPCONN_UDP

= 0x20,

};

/** Current state of the espconn. Non-TCP espconn are always in state
ESPCONN_NONE! */
enum espconn_state {
ESPCONN_NONE,
ESPCONN_WAIT,
ESPCONN_LISTEN,
ESPCONN_CONNECT,
ESPCONN_WRITE,
ESPCONN_READ,
ESPCONN_CLOSE
};

/** 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;
52 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

53 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
54 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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

55 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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.
56 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

57 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
58 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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
59 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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

60 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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
61 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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
62 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide


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.

63 / 64

Espressif Systems

June 19, 2014

ESP8266EX SDK Programming Guide

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.

64 / 64

Espressif Systems

June 19, 2014

You might also like