2C SDK Espressif IoT SDK Programming Guide v0.9.5
2C SDK Espressif IoT SDK Programming Guide v0.9.5
Status
Released
Current version
V0.9.5
Author
Fei Yu
Completion Date
2015.01.22
Reviewer
JG Wu
Completion Date
2015.01.22
[ ] CONFIDENTIAL
1 / 95
] INTERNAL
] PUBLIC
Espressif Systems
February 9, 2015
Version Info
Date
Version
2013.12.25
~2014.7.10
0.1~0.8
2014.8.13
0.9
Author
JG Wu /
Han Liu/
Fei Yu
Fei Yu
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
2 / 95
Espressif Systems
Comments/Changes
Draft and changes
February 9, 2015
OTHERWISE
ARISING
OUT
OF
ANY
PROPOSAL,
3 / 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
4 / 95
Espressif Systems
February 9, 2015
Espressif Systems
February 9, 2015
Espressif Systems
February 9, 2015
Espressif Systems
February 9, 2015
8 / 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.
9 / 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 selfdefined data types to handle the them.
10 / 95
Espressif Systems
February 9, 2015
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
3.1.2. os_timer_disarm
Function: Disarm timer
Prototype:
void os_timer_disarm (ETSTimer *ptimer)
Input parameters:
ETSTimer*ptimerTimer structure
Return:
null
11 / 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.2. system_restart
Function: Restart
Prototype:
void system_restart(void)
Input parameters:
12 / 95
Espressif Systems
February 9, 2015
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
13 / 95
Espressif Systems
February 9, 2015
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
14 / 95
Espressif Systems
February 9, 2015
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
15 / 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
Espressif Systems
February 9, 2015
3.2.11.
system_os_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
#define TEST_QUEUE_LEN
os_event_t *testQueue;
void test_task (os_event_t *e)
{
switch (e->sig) {
case SIG_RX:
os_printf(sig_rx %c\n, (char)e->par);
break;
default:
break;
}
17 / 95
Espressif Systems
February 9, 2015
3.2.12.
system_os_post
os_signal_t sig,
os_param_t par)
Input parameters:
uint8 priotask priority,
a);
}
Printout: sig_rx a
3.2.13.
system_get_time
Espressif Systems
February 9, 2015
3.2.14.
system_get_rtc_time
3.2.15.
system_rtc_clock_cali_proc
Espressif Systems
February 9, 2015
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
20 / 95
512 bytes
Espressif Systems
|
February 9, 2015
3.2.18.
system_uart_swap
system_uart_swap (void)
Parameter
NULL
Return
NULL
3.2.19.
system_adc_read
Espressif Systems
February 9, 2015
3.3.2. spi_flash_erase_sector
Function: erase sector in flash
Note: More details in document Espressif IOT Flash RW Operation
Prototype
SpiFlashOpResult
Parameters
uint16 sec Sector number, the count starts at sector 0, 4KB per sector.
Return
Typedef enum{
22 / 95
Espressif Systems
February 9, 2015
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
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
23 / 95
Espressif Systems
February 9, 2015
24 / 95
Espressif Systems
February 9, 2015
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.
25 / 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.
26 / 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)
27 / 95
Espressif Systems
February 9, 2015
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;
uint8 show_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
28 / 95
Espressif Systems
February 9, 2015
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
}
}
29 / 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
30 / 95
Espressif Systems
February 9, 2015
3.4.12.
wifi_station_ap_change
3.4.13.
wifi_station_get_current_ap_id
3.4.14.
wifi_station_get_auto_connect
Espressif Systems
February 9, 2015
3.4.15.
wifi_station_set_auto_connect
3.4.16.
wifi_station_dhcpc_start
3.4.17.
wifi_station_dhcpc_stop
Espressif Systems
February 9, 2015
3.4.18.
wifi_station_dhcpc_status
3.4.19.
wifi_softap_get_config
33 / 95
Espressif Systems
February 9, 2015
3.4.20.
wifi_softap_set_config
3.4.21.
wifi_softap_get_station_info
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
Espressif Systems
February 9, 2015
"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
Espressif Systems
February 9, 2015
3.4.24.
wifi_softap_dhcps_stop
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.
36 / 95
Espressif Systems
February 9, 2015
3.4.26.
wifi_softap_dhcps_status
3.4.27.
wifi_set_phy_mode
37 / 95
Espressif Systems
February 9, 2015
3.4.28.
wifi_get_phy_mode
3.4.29.
wifi_get_ip_info
38 / 95
Espressif Systems
February 9, 2015
3.4.30.
wifi_set_ip_info
0x00
#define SOFTAP_IF
0x01
ip information
Example
struct ip_info info;
39 / 95
Espressif Systems
February 9, 2015
3.4.31.
wifi_set_macaddr
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};
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
40 / 95
#define STATION_IF
0x00
#define SOFTAP_IF
0x01
Espressif Systems
February 9, 2015
3.4.33.
wifi_set_sleep_type
3.4.34.
wifi_get_sleep_type
41 / 95
Espressif Systems
February 9, 2015
3.4.35.
wifi_status_led_install
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.4.36.
wifi_status_led_uninstall
Espressif Systems
February 9, 2015
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
43 / 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:
44 / 95
Espressif Systems
February 9, 2015
3.6.2. wifi_set_promiscuous_rx_cb
Function: register a rx callback function in promiscuous mode,
which will be
3.6.3. wifi_get_channel
Function: get channel number, for sniffer
Function definition:
45 / 95
Espressif Systems
February 9, 2015
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.
Espressif Systems
February 9, 2015
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.
47 / 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;
48 / 95
Espressif Systems
February 9, 2015
espconn_delete
Not 0
succeed#define ESPCONN_OK 0
-
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
49 / 95
Espressif Systems
February 9, 2015
os_printf("user_esp_platform_dns_found %d.%d.%d.%d\n",
*((uint8 *)&ipaddr->addr), *((uint8 *)&ipaddr->addr + 1),
*((uint8 *)&ipaddr->addr + 2), *((uint8 *)&ipaddr->addr + 3));
}
Void dns_test(void)
{
espconn_gethostbyname(pespconn,iot.espressif.cn,&esp_server_ip,user_es
p_platform_dns_found);
}
3.8.1.3.
espconn_port
Espressif Systems
February 9, 2015
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
Not 0
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
51 / 95
Espressif Systems
February 9, 2015
Not 0
3.8.1.6.
espconn_sent_callback
3.8.1.7.
espconn_recv_callback
char *pdata,
Input parameters:
void *argcallback function parameters
char *pdatareceived data entry parameters
unsigned short lenreceived data length
Return:
null
52 / 95
Espressif Systems
February 9, 2015
3.8.1.8.
espconn_sent
uint16 length)
Input parameters:
struct espconn *espconncorresponding connected control block
structure
uint8 *psentsent data pointer
uint16 lengthsent data length
Return:
0
Not
0-
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
Not
0-
53 / 95
Espressif Systems
February 9, 2015
3.8.2.2.
espconn_secure_accept
Not 0
3.8.2.3.
espconn_regist_time
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,
Return:
0
Not 0
54 / 95
Espressif Systems
February 9, 2015
3.8.2.4.
espconn_get_connection_info
remot_info
uint8 typeflags)
Input parameters:
struct espconn *espconncorresponding connected control block
structure
remot_info **pcon_infoconnect to client info
uint8 typeflags
Return:
0
Not 0
3.8.2.5.
espconn_connect
Not 0
3.8.2.6.
Function:
55 / 95
espconn_connect_callback
successful
listening(ESP8266
Espressif Systems
as
TCP
server)
or
February 9, 2015
3.8.2.7.
espconn_set_opt
succeed#define ESPCONN_OK 0
Not 0
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
56 / 95
Espressif Systems
February 9, 2015
3.8.2.8.
espconn_disconnect
Not 0
3.8.2.9.
espconn_regist_connectcb
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:
0Not 0 -
3.8.2.10. espconn_regist_reconcb
Function: register reconnect callback
Note: Reconnect callback is more like a network error handler, no matter error
57 / 95
Espressif Systems
February 9, 2015
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
Not 0
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
Not
0-
58 / 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
Not 0
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
Not
0-
59 / 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
Not 0
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:
60 / 95
Espressif Systems
February 9, 2015
Not 0
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
Not 0
61 / 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
Not 0
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
Not 0
62 / 95
Espressif Systems
February 9, 2015
espconn_create
Not 0
3.8.3.2.
succeed#define ESPCONN_OK 0
-
espconn_igmp_join
ip of multicast group
Return
0
Not 0
63 / 95
succeed#define ESPCONN_OK 0
-
Espressif Systems
February 9, 2015
3.8.3.3.
espconn_igmp_leave
Not 0
64 / 95
succeed#define ESPCONN_OK 0
-
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
65 / 95
Espressif Systems
February 9, 2015
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 characters\r 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
66 / 95
Espressif Systems
February 9, 2015
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
67 / 95
Espressif Systems
February 9, 2015
3.10.1.
jsonparse_setup
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
3.10.3.
jsonparse_copy_value
Espressif Systems
char *str,
int
February 9, 2015
3.10.4.
jsonparse_get_value_as_int
3.10.5.
jsonparse_get_value_as_long
3.10.6.
jsonparse_get_len
Espressif Systems
February 9, 2015
3.10.7.
jsonparse_get_value_as_type
3.10.8.
jsonparse_strcmp_value
Input parameters:
struct jsonparse_state *statejson parsing pointer
const char *strcharacter buffer
Return:
intcomparison result
3.10.9.
jsontree_set_up
Espressif Systems
February 9, 2015
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
71 / 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,
int *text,
const
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
72 / 95
Espressif Systems
February 9, 2015
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
73 / 95
Espressif Systems
February 9, 2015
4. Structure definition
4.1. Timer
typedef void ETSTimerFunc(void *timer_arg);
*timer_next;
uint32_t
timer_expire;
uint32_t
timer_period;
ETSTimerFunc
void
*timer_func;
*timer_arg;
} ETSTimer;
Espressif Systems
February 9, 2015
= 0,
AUTH_WEP,
AUTH_WPA_PSK,
AUTH_WPA2_PSK,
AUTH_WPA_WPA2_PSK
} AUTH_MODE;
struct softap_config {
uint8 ssid[32];
uint8 password[64];
uint8 ssid_len;
uint8 channel;
uint8 authmode;
uint8 ssid_hidden;
uint8 max_connection;
uint8 beacon_interval; // 100 ~ 60000 ms, default 100
};
Note:
If softap_config.ssid_len == 0, check ssid till find a termination characters;
otherwise it depends on softap_config.ssid_len.
Espressif Systems
February 9, 2015
struct bss_info {
STAILQ_ENTRY(bss_info)
next;
u8 bssid[6];
u8 ssid[32];
u8 channel;
s8 rssi;
u8 authmode;
uint8 is_hidden; // SSID of current AP is hidden or not.
};
typedef void (* scan_done_cb_t)(void *arg, STATUS status);
SC_STATUS_FIND_CHANNEL = 0,
SC_STATUS_GETTING_SSID_PSWD,
SC_STATUS_GOT_SSID_PSWD,
SC_STATUS_LINK,
} sc_status;
typedef enum
SC_TYPE_ESPTOUCH = 0,
SC_TYPE_AIRKISS,
} sc_type;
76 / 95
Espressif Systems
February 9, 2015
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 {
77 / 95
Espressif Systems
February 9, 2015
struct jsontree_array {
uint8_t type;
uint8_t count;
struct jsontree_value **values;
};
struct jsonparse_state {
const char *json;
int pos;
int len;
int depth;
int vstart;
int vlen;
char vtype;
char error;
char stack[JSONPARSE_MAX_DEPTH];
};
JSONTREE_OBJECT(name,
...)
\
static struct jsontree_pair jsontree_pair_##name[] = {__VA_ARGS__};
78 / 95
Espressif Systems
February 9, 2015
sizeof(jsontree_pair_##name)/sizeof(struct jsontree_pair),
jsontree_pair_##name }
JSONTREE_ARRAY(name,
...)
\
static struct jsontree_value* jsontree_value_##name[] = {__VA_ARGS__};
static struct jsontree_array name = {
JSON_TYPE_ARRAY,
\
\
sizeof(jsontree_value_##name)/sizeof(struct jsontree_value*),
jsontree_value_##name }
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;
79 / 95
Espressif Systems
February 9, 2015
= 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
};
80 / 95
Espressif Systems
February 9, 2015
81 / 95
Espressif Systems
February 9, 2015
5. Driver
5.1. GPIO APIs
Please refer to \user\ user_plug.c
PIN_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
Espressif Systems
February 9, 2015
83 / 95
Espressif Systems
February 9, 2015
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
Espressif Systems
February 9, 2015
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
85 / 95
Espressif Systems
February 9, 2015
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.2. i2c_master_init
Function: initialize i2c
Function definition:
void i2c_master_init(void)
86 / 95
Espressif Systems
February 9, 2015
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_send_ack
Function: set i2c ACK
Function definition:
void i2c_master_send_ack (void)
Input parameters:
NULL
87 / 95
Espressif Systems
February 9, 2015
5.3.6. i2c_master_send_nack
Function: set i2c NACK
Function definition:
void i2c_master_setAck (void)
Input parameters:
NULL
Return:
NULL
5.3.7. i2c_master_checkAck
Function: check ACK from slave
Function definition:
bool i2c_master_getAck (void)
Input parameters:
NULL
Return:
TRUE, get i2c slave ACK
FALSE, get i2c slave NACK
5.3.8. i2c_master_readByte
Function: read a byte from slave
Function definition:
uint8 i2c_master_readByte (void)
Input parameters:
null
Return:
88 / 95
Espressif Systems
February 9, 2015
5.3.9. 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
89 / 95
Espressif Systems
February 9, 2015
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:
90 / 95
Espressif Systems
February 9, 2015
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:
91 / 95
Espressif Systems
February 9, 2015
6. Appendix
A. ESPCONN Programming
Programming guide for ESP8266 running as TCP client and TCP server.
A.1.2. Steps
1) Initialize espconn parameters according to protocols.
2) Register connect callback function, and register reconnect callback
function.
(Call espconn_regist_connectcb and espconn_regist_reconcb )
3) Call espconn_connect function and set up the connection with TCP
Server.
4) Registered connected callback function will be called after successful
connection, which will register the corresponding callback function.
Recommend to register disconnect callback function.
(Call espconn_regist_recvcb , espconn_regist_sentcb and
92 / 95
Espressif Systems
February 9, 2015
A.2.2. Steps
(1) Initialize espconn parameters according to protocols.
(2) Register connect callback and reconnect callback function.
(Call espconn_regist_connectcb and espconn_regist_reconcb )
(3) Call espconn_accept function to listen to the connection with host.
(4) Registered connect function will be called after successful connection,
which will register corresponding callback function.
(Call espconn_regist_recvcb , espconn_regist_sentcb and
espconn_regist_disconcb in connected callback)
Espressif Systems
February 9, 2015
rtc_time2 = system_get_rtc_time();
stime2 = system_get_time();
Espressif Systems
February 9, 2015
os_delay_us(500000);
system_restart();
95 / 95
Espressif Systems
February 9, 2015