ESP8266 IoT SDK User Manual v0.8

ESP8266EX SDK IoT User Manual

1 / 24 Espressif Systems June 19, 2014

Espressif IOT SDK:

USER MANUAL

Status Released

Current version V0.8

Author Fei Yu

Completion Date 2014.8.14

Reviewer Jiangang Wu

Completion Date 2014.8.14

[ ] CONFIDENTIAL

[ ] INTERNAL

[ ] PUBLIC



Version Info

Date Version Author Comments / Changes

2013.12.24 0.1 Jiangang Wu Draft

2014.1.15

~

2014.6.19

0.2 ~ 0.6 Jiangang Wu

/ Han Liu

/ Fei Yu

Internal modification

2014.7.10 0.7 Fei Yu Support Cloud Upgrade（OTA）

2014.8.14 0.8 Fei Yu Add Flash Download Tool

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.



Table of Contents

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

Table of Contents ........................................................................................................... 3

1. Foreword ............................................................................................................. 4

2. Virtual Machine ................................................................................................... 5

2.1. Virtual Machine Software .................................................................................... 5

2.2. Virtual Computer ................................................................................................. 5

2.2.1. Image ................................................................................................................ 5

2.2.2. Import .............................................................................................................. 5

2.2.3. Network ........................................................................................................... 8

2.2.4. Shared folders .................................................................................................. 9

2.2.5. Interface ......................................................................................................... 11

3. Development Tools ............................................................................................ 12

3.1. Compilers ........................................................................................................... 12

3.2. Serial Port .......................................................................................................... 14

3.2.1. USB Serial Port ............................................................................................... 14

3.2.2. SecureCRT ...................................................................................................... 15

3.3. Download Tools ................................................................................................. 16

3.3.1. XTCOM_UTIL .................................................................................................. 16

3.3.2. ESP_FLASH_DOWNLOAD ............................................................................... 19

3.4. NetAssist ............................................................................................................ 20

3.5. Postman ............................................................................................................. 20

3.6. Tomcat ............................................................................................................... 20

4. SDK Software Package ..................................................................................... 21

4.1. Introduction ....................................................................................................... 21

4.2. Directory Structure ............................................................................................ 21

4.3. Compiling and Burning into Flash ...................................................................... 22

4.3.1. Version that does not support Cloud Update（OTA）.................................. 22

4.3.2. Version that support Cloud Update（OTA） ................................................. 23



1. Foreword

This manual mainly introduces how to use ESP8266-based SDK for Internet of

Things, including virtual machine installation, development tool usage, SDK software

development kit etc.



2. Virtual Machine

All development tools for ESP8266 Internet of Things Module-based secondary

development have been installed on a virtual machine and users only have to install

the virtual machine and import it before they can start development.

2.1. Virtual Machine Software

VirtualBox is used as our virtual machine, which can be downloaded at:

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

Please choose the version for the right platform.

2.2. Virtual Computer

2.2.1. Image

Open virtual format (*.ova) is used for virtual computer image and the file is

ESP_IOT_SDK.ova which can be imported into other virtual machine software.

2.2.2. Import

In default condition, VirtualBox will import virtual computer into system disk and

this import will take up a lot of system space as users use the virtual computer.

Hence, it is recommended to install virtual computer on non-system disk.

Step 1: Select "Global setting" in the management menu

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



Step 2: Select "General" where you can set the path for virtual computer, for

example: D:\vm

Step 3: Select "Import virtual computer" in the management menu

Step 4: Set the path for the virtual computer to be imported, for example:



D:\vm\ESP_IOT_SDK.ova

Step 5: import



After the import, the following files can be found in D:\vm\ESP_IOT_SDK:

2.2.3. Network

Set virtual computer and ESP8266 module in the same subnet, so that the virtual

computer can access ESP8266. Please select a correct internet card compatible with

the hosting machine before using the virtual computer.

Click "Setting" on the VirtualBox interface to enter the "Internet" tab.



For interface name, please choose the correct network card to connect to the

router.

2.2.4. Shared folders

Please share the folders in the hosting machine with the virtual machine before

using the virtual machine, for example: create a file holder named "share", which is

dedicated to mapping the virtual computer, and the hosting machine can share files

with the virtual machine by copying files into this file holder. The specific steps are as

follows:



After successful setup, map the shared drive in the virtual computer, see the

picture below for details:

Set the drive as D: and "share" is the file folder for sharing files in VirtualBox. By

default, shared folder is already setup in the virtual computer.

The shared drive will appear in "My Computer" in the virtual computer. See the



picture below for details. Save the SDK source code and other documents in the drive

and share them with the hosting machine.

2.2.5. Interface

After successful import and setting, users can enter the system.



3. Development Tools

All software tools needed for development are installed on virtual computer,

including compilers, flash downloads and debuggers. Users can choose to install

other software that they may need.

3.1. Compilers

Our source code can only be compiled by “xtensa” in virtual computer now.

Double-click the icon to run the complier, for which all parameters

have already been set and the path is d:\esp_iot_sdk\app. Please set the shared

folder according to the steps in 2.2.4 and then double click on it, 3 windows shown

below will appear:

1、

2、



3、

1 and 2 are the license windows for the compiler, which you can ignore. 3 is the

compiler window where users, if they need to revise the source codes, can execute

relevant instructions to generate the bin files needed for flash download.



3.2. Serial Port

ESP8266 motherboard communicates with computer through serial ports. Users

can connect serial ports with the virtual computer and communicate with ESP8266

using the software tools in the virtual computer. Please install the relevant drivers

before use.

3.2.1. USB Serial Port

There are many different types of USB serial port cables in the market and the

one we use is FT232R cable. In the menu, assign the PC’s USB serial port to the

virtual computer. In this way, USB serial port cable can be connected to the virtual

computer.

USB serial port number can be set in the virtual computer and it is

recommended to set the number as 6.



The Driver Genius in the virtual computer can be used to install drivers for other

models of USB serial ports.

3.2.2. SecureCRT

ESP8266 module adopts 74880 baud rate which can be set in SecureCRT.



3.3. Download Tools

3.3.1. XTCOM_UTIL

Double-click the icon to run the download tool to download the

compiled *.bin files onto the SPI Flash on the ESP8266 motherboard.

Set the jumper on the motherboard as MTDO：0，GPIO0：0，GPIO2：1, then it

will enter download mode. Steps are as follows:

Step 1: set serial port

Step 2: select the right serial port number and open

Step 3: connect



Step 4: download the image file

Step 5: select and download the bin file which you are going to burn into the

flash

Note: Program Address Offset varies in accordance with bin file. For example,

the corresponding Program Address Offset for eagle.app.v6.flash.bin is 0x0000.

Please refer to bin directory descriptions in "4.2 Directory Structure".

Step 6: re-connect

After completion of Step 5, re-connect ESP8266 motherboard to power. Close



serial port and repeat Step 2 and Step 3.

Step 7: select and download next bin file which you are going to burn into the

flash, for example, eagle.app.v6.irom0text.bin.

Note: the corresponding Program Address Offset for eagle.app.v6.irom0text.bin

is 0x40000. Please refer to bin directory descriptions in "4.2 Directory Structure".

Step 8: close serial port

After the downloading, users can check and print relevant information with

SecureCRT.

Set the jumper on the motherboard as MTDO：0，GPIO0：1，GPIO2：1, then it

will enter operatings mode.

Note: please disconnect the power when setting the jumpers.



3.3.2. ESP_FLASH_DOWNLOAD

Espressif also provides the tool "ESP_FLASH_DOWNLOAD" for users to burn

several bin files altogether at once, and download several complied *.bin files at a

time into the SPI Flash on the ESP8266 motherboard.

“ESP_FLASH_DOWNLOAD” introduction：

（1） Bin-Select Area: Choose bins to burn，and burn them in corresponding

address.

（2） SPI FLASH CONFIG: Set config of spi flash. “CombineBin” merges all bins

selected above to one (target.bin). “Default” reset to the default config.



（3） Mac Address：Mac address of ESP8266.

Also set the jumper on the motherboard as MTDO：0，GPIO0：0，GPIO2：1, then

it will enter download mode. Steps are as follows:

(1) See the red boxes in the picture above, select the bin file to be burned ->fill in the

path ->check burning options.

(2) Set COM port and baud rate.

(3) Click "START" to start downloading.

(4) After the downloading, disconnect the power for the motherboard, and change the

jumper into operation mode. Re-connect the power for operation. Set the jumper

on the motherboard as MTDO：0，GPIO0：1，GPIO2：1 for operating mode.

Note: please disconnect the power when setting the jumper.

3.4. NetAssist

NetAssist is used to test TCP and UDP.

3.5. Postman

Chrome plug-in is used to test REST-structured web service.

3.6. Tomcat

Web application server, used to store updates.



4. SDK Software Package

4.1. Introduction

By default, the SDK software package is stored in the root directory in network

drive D in the virtual computer and the working directory for compiler xtensa is set

to d:\esp_iot_sdk\app.

4.2. Directory Structure

All header files, library files and compilation files needed for secondary

development are included in the SDK software package. See the picture below for

directory structure:

Detailed description:

1. The "app" folder is the main working folder which includes two folders

"user" and "include". User source code and header files are all stored in the

two folders. See the examples and the descriptions in Step 4 for details.



2. "bin" folder stores the bin files downloaded into the Flash, "at" folder stores

the bin files that support AT+ instructions and "upgrade" folder stores the

bin files that support cloud update.

3. "examples" folder stores SDK examples, which only requires copying the

"user" and "include" folders and Makefile in the IoT_Demo folder to "app"

folder;

4. "include" folder stores the header files pre-installed in the SDK, which may

include relevant API functions and other definitions. Users can use them

directly and do not need to change anything;

5. "ld" folder stores the files needed for SDK software link. Users can use them

directly and do not need to change anything;

6. "lib" folder stores the library files needed for SDK compilation;"tools" folder

stores the tools needed for generating bin files. Users can use them directly

and do not need to change anything.

4.3. Compiling and Burning into Flash

When compiling, please remember to copy the "user" and "include" folders and

Makefile in the esp_iot_sdk\examples to esp_iot_sdk\app.

Please refer to "3.3 Download Tools" for details about burning into flash. Note

that the serial port will be closed every time a bin file is downloaded into the Flash

and needs to be reconnected for burning of next bin file.

4.3.1. Version that does not support Cloud Update（OTA）

esp_iot_sdk_v0.7 and previous versions do not support cloud update.

Compilation Steps:

(1) Run the compiler xtensa which is directed d:\esp_iot_sdk\app by default



(2) Enter "make" and press "Enter". Generate .output folder in accordance with

makefile, which will store lib and obj files.

(3) Enter "gen_misc.bat" and press "Enter" to generate the corresponding bin

file.

4.3.1.1. Bin file descriptions

blank.bin, provided in SDK; to be burned to 0x7E000

eagle.app.v6.flash.bin, compiled by the steps said above; to be burned to 0x0000

master_device_key.bin, obtained from Espressif Cloud Server; to be burned to

0x3E000

eagle.app.v6.irom0text.bin, compiled by the steps said above; to be burned to

0x40000

esp_init_data_default.bin, provided by Espressif; stores default parameter values

and to be burned to 0x7c000.

Note:

1. It is not necessary to burn blank.bin every time and it is only necessary for

SDK update or clearing of WIFI configuration

2. It is not necessary to burn master_device_key.bin every time and it is only

necessary for initial write-in and revision of master_device_key

3. Normally, it is only necessary to burn these 2 bins

eagle.app.v6.flash.bin->eagle.app.v6.irom0text.bin.

4.3.2. Version that support Cloud Update（OTA）

esp_iot_sdk_v0.8 and later versions support cloud update and are compatible

with previous compilation and burning methods, and hence allow compiling and

burn in method in 4.3.1 Does Not Support Cloud Update if users do not need cloud



update.

Please refer to document “Firmware update through cloud server" for details

about cloud update.

Compilation Steps:

(1) Run the compiler, compile user1.bin first and execute the instruction "make

APP=1"

(2) Run gen_misc_plus.bat user1 and generate user1.bin at

“\esp_iot_sdk\bin\upgrade"

(3) Run "make clean" to clean up all previous compilation

(4) Then compile user2.bin and execute the instruction “makeAPP=2”

(5) Run "gen_misc_plus.bat user2" to generate user2.bin at

"\esp_iot_sdk\bin\upgrade"

4.3.2.1. Bin file descriptions

blank.bin; provided in SDK and to be burned to 0x7E000;

esp_init_data_default.bin, provided by Espressif; stores default parameter values

and to be burned to 0x7c000.

boot.bin, provided in SDK and to be burned to 0x00000;

user1.bin, compiled by the steps said above and to be burned to 0x01000;

master_device_key.bin, applied for through Espressif server and to be burned to

0x3E000;

Note:

Only four steps are required during initial burn in and user2.bin is not

needed.

For future updates, please upload user1.bin and user2.bin to the server and

the server will send update information to users. If users choose to update, then

the device will select and download user1.bin or user2.bin, whichever is

necessary for cloud update.

ESP8266 IoT SDK User Manual v0.8

Documents

Transcript of ESP8266 IoT SDK User Manual v0.8