esp8266 iot sdk user manual v0.8
Post on 10-Dec-2015
289 Views
Preview:
DESCRIPTION
TRANSCRIPT
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
ESP8266EX SDK IoT User Manual
2 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
3 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
4 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
5 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
6 / 24 Espressif Systems June 19, 2014
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:
ESP8266EX SDK IoT User Manual
7 / 24 Espressif Systems June 19, 2014
D:\vm\ESP_IOT_SDK.ova
Step 5: import
ESP8266EX SDK IoT User Manual
8 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
9 / 24 Espressif Systems June 19, 2014
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:
ESP8266EX SDK IoT User Manual
10 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
11 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
12 / 24 Espressif Systems June 19, 2014
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、
ESP8266EX SDK IoT User Manual
13 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
14 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
15 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
16 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
17 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
18 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
19 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
20 / 24 Espressif Systems June 19, 2014
(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.
ESP8266EX SDK IoT User Manual
21 / 24 Espressif Systems June 19, 2014
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.
ESP8266EX SDK IoT User Manual
22 / 24 Espressif Systems June 19, 2014
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
ESP8266EX SDK IoT User Manual
23 / 24 Espressif Systems June 19, 2014
(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
ESP8266EX SDK IoT User Manual
24 / 24 Espressif Systems June 19, 2014
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.
top related