ESP32 SERIES

Getting Started Guide

for SDK based on FreeRTOS

Version 0.1
Copyright 2015
 About This Guide
This guide describes the software, firmware environment and development recommendations
required to build an application around the ESP32 development board with build-in ESP32
chip.

Note：

l
This guide is only for SDK Verison 1.0.0. Refer to the “ESP32 System Description” for more details on
the ESP32 development board.

a
This document is structured as follows:

it
Chapter Title Subject

Introduces the ESP32 and software and hardware required.

Chapter 1 Introduction Explains the software package with details on its architecture and

n
contents.

Guides users how to build and upload an application firmware

Chapter 2 Getting Started
provided by Espressif.

Style Identifiers
This is a code input style.

d e
fi
Code Input

This is a code output style.

Release Notes
Code output

o Date
n Version Release notes

C 2015.12 V0.1 Confidential for internal use only.

 Table of Contents
1. Introduction ...............................................................................................................................................4
1.1. ESP32 .......................................................................................................................................................................4
1.2. Requirements .........................................................................................................................................................4
1.2.1. Hardware ......................................................................................................................................................... 4
1.2.2. Software ...........................................................................................................................................................6

2. Getting Started ..........................................................................................................................................8

2.1.

a l
Getting Started to Use SDK ................................................................................................................................8

it
2.1.1. Process Overview ......................................................................................................................................... 8
2.1.2. Building Toolchain ........................................................................................................................................8
2.1.3. Building Firmware ........................................................................................................................................ 11

n
2.1.4. Uploading Firmware ................................................................................................................................... 12
2.1.5. Running Application.................................................................................................................................... 15
2.2. SSC Command Reference ...................................................................................................................................15

e
2.2.1. op ......................................................................................................................................................................15
2.2.2. sta..................................................................................................................................................................... 16

d
2.2.3. ap ......................................................................................................................................................................17
2.2.4. mac...................................................................................................................................................................17

fi
2.2.5. dhcp................................................................................................................................................................. 18
2.2.6. ip....................................................................................................................................................................... 18

n
2.2.7. reboot ............................................................................................................................................................. 19
2.2.8. ram ................................................................................................................................................................... 19

C o
 1. Introduction

1. Introduction
1.1. ESP32
ESP32 provides a Wi-Fi plus Bluetooth 4.2 combo solution in the 2.4GHz band by using 40nm
technology. It delivers highly integrated Wi-Fi SoC solution to meet the continuous demands
for efficient power usage, compact design and reliable performance.

l
You can use ESP32 series hardware and software provided by Espressif to develop and
program some useful Wi-Fi, Bluetooth and wearable electronics applications and products in
Internet of Things(IoT) industry.

1.2. Requirements

it a
Before getting started to run and develop firmware applications on your ESP32, there are

n
some hardware and software requirements.

1.2.1. Hardware

e
• An ESP32 development board or ESP-WROOM-03(build-in ESP32).
• A USB TTL Serial cable or a Micro-USB cable.

d
• Debian GNU/Linux OS on an x86 machine.

fi
Notes：
1. We assume to use the Debian or Ubuntu Linux OS. You may make some modifications for the

n
other Linux OS.
2. For more information about ESP-WROOM-03, refer to “ESP-WROOM-03 Specification".

C o

Espressif Systems 4/20 2015.12

 1. Introduction

ESP32 Development Board

ESP32 development board (hereafter referred to as a board) is shown as Figure 1-1 and Table
1-1.

1. 8-digit Toggle Switch(Low Level) 8. CHIP_PU Switch(Power off)

8. CHIP_PU Switch(Power on)

1. 8-digit Toggle Switch(High Level)

7. Antenna Jack (SMA Female)

l
2. GPIO

a
6. Power for ESP32

it
4. 5V Switch (Power on)
5. 5V Power Jack

3. UART 4. 5V Switch (Power off)

n
Figure 1-1. ESP32 Development Board

e
Table 1-1. ESP32 Development Board

No. Name Description

d
Set the board to the SPI and the uploading mode with the 8-digit Toggle
1 8-digit Toggle Switch
Switch. More information refer to Table 1-2.

fi
2 GPIO -

n
3 UART Upload the firmware with UART.

GND: Power off

4 5V Switch

o
5V: Power on

5 5V Power Jack(DC-044) Connect the board with a 5V/1A(Max) Dc power cable.

6 Power for ESP32 -

C
7 Antenna Jack Connect the antenna to the board with the SMA Female Jack.

GND: Power off

8 CHIP_PU Switch
CHIP_PU: Power on

Table 1-2. 8-digit Toggle Switch

Switch No. 1 2 3 4 5 6

Pin MTDO GPIO2 GPIO0 GPIO4 GPIO5 U0TXD

SPI Mode x x High Level x High Level High Level

Uploading Mode x Low Level Low Level x x x

Espressif Systems 5/20 2015.12

 1. Introduction

1.2.2. Software
Development Platform
ESP32 RTOS SDK is a development platform provided for the users to develop their project.
• For the latest version, go to Download ESP32 RTOS SDK in Github.
• For the package components, refer to Figure 1-2.

l
Bin files to be downloaded to the flash

Bin files for SSC

it a
Example codes of SDK applications

driver codes

e n Sample project template

fid Extra head files for compiling

o n Header files required for compilation

Header files provided by Espressif

Header files of freeRTOS

C
Header files of Json library

Header files of LwIP library

Header files of SSL library

Files for SDK compilation and link

Library files of SDK compilation

Library files of open source code

Compilation tools

Figure 1-2. Package Components

Espressif Systems 6/ 20 2015.12

 1. Introduction

Serial Terminal Tool

We recommend using Minicom as a serial terminal tool to show the communication
information and debug code.
Uploading Tool
We recommend using Python 2.6 or 2.7 and esptool_ESP32.py to upload firmware to the
flash.
• For the latest version of Python, go to Download Python.
• esptool_ESP32.py file is in the ESP32 RTOS SDK > tools folder, refer to Figure 1-2.

l
Package Components.
• For the details of instructions, refer to 2.5.2 Uploading Files.

it a
e n
fid
o n
C
Espressif Systems 7/20 2015.12
 2. Getting Started

2. Getting Started
2.1. Getting Started to Use SDK

l
2.1.1. Process Overview

a
Start

Building
toolchain

it
e
Building
firmware

n
fid Uploading
firmware

n
Configuring
firmware

2.1.2.

C o
Building Toolchain
End

Figure 2-1. Process Overview

We suggest to choose Crosstool-ng as the compiler toolchain. Follow the instructions below to
install Crosstool-ng.

Note：

Your PC needs to connect to the Internet.

1. Update the system.

sudo apt-get update

Espressif Systems 8/20 2015.12

 2. Getting Started

2. Install the required toolchain packages.

sudo apt-get install git autoconf build-essential gperf bison flex
texinfo libtool libncurses5-dev wget gawk libc6 python-serial
libexpat-dev

2 upgraded, 37 newly installed, 0 to remove and 395 not upgraded.

Need to get 10.4 MB of archives.
After this operation, 48.7 MB of additional disk space will be used.

Do you want to continue? [Y/n]

Setting up texinfo (5.2.0.dfsg.1-2) ...

a l
it
Setting up libwww-perl (6.05-2) ...
Setting up liblwp-protocol-https-perl (6.04-2ubuntu0.1) ...

n
Setting up libxml-parser-perl (2.41-1build3) ...
Setting up libxml-sax-expat-perl (0.40-2) ...

e
update-perl-sax-parsers: Registering Perl SAX parser XML::SAX::Expat
with priority 50...

d
update-perl-sax-parsers: Updating overall Perl SAX parser modules
info file...
Replacing config file /etc/perl/XML/SAX/ParserDetails.ini with new

fi
version

n
3. Create a directory to store the toolchain.
sudo mkdir /opt/Espressif

o
4. Make the current user as the owner.
sudo chown $USER /opt/Espressif/

C
5. Download the latest toolchain installation file.
cd /opt/Espressif/
git clone -b esp108-1.21.0 git://github.com/jcmvbkbc/crosstool-NG.git

Cloning into 'crosstool-NG'...

remote: Counting objects: 28443, done.
remote: Total 28443 (delta 0), reused 0 (delta 0), pack-reused 28443

Receiving objects: 100% (28443/28443), 15.83 MiB | 71.00 KiB/s, done.

Resolving deltas: 100% (16473/16473), done.
Checking connectivity... done.

Espressif Systems 9/ 20 2015.12

 2. Getting Started

6. Install toolchain.
cd crosstool-NG/
./bootstrap && ./configure --prefix=`pwd` && make && make install

For auto-completion, do not forget to install 'ct-ng.comp' into

your bash completion directory (usually /etc/bash_completion.d)
username:/opt/Espressif/crosstool-NG$

./ct-ng xtensa-esp108-elf

***********************************************************
WARNING! This sample may enable experimental features.

a l
it
Please be sure to review the configuration prior

to building and using your toolchain!

Now, you have been warned!

n
***********************************************************
Now configured for "xtensa-esp108-elf"

e
username:/opt/Espressif/crosstool-NG$

d
./ct-ng build

[INFO ] Cleaning-up the toolchain's directory

fi
[INFO ] Stripping all toolchain executables
[INFO ] Cleaning-up the toolchain's directory: done in 1.85s (at

n
24:28)
[INFO ] Build completed at 20151210.175153

o
[INFO ] (elapsed: 24:27.54)

[INFO ] Finishing installation (may take a few seconds)...

C
Note：

It takes about dozens of minutes to build toolchain.

7. Set the PATH variable to point to the newly compiled toolchain.

export PATH=/opt/Espressif/crosstool-NG/builds/xtensa-esp108-elf/bin:
$PATH

⚠ Notice：

Make sure you set the correct path, or it will occur a compile error.

Espressif Systems 10/20 2015.12

 2. Getting Started

Note：

You need to do Step 6 every time you open a new shell, or you can put it inside your .bashrc file.

2.1.3. Building Firmware

1. Create a directory to store a new project.
mkdir ~/Workspace

l
cd ~/Workspace

a
2. Download the latest ESP32 RTOS SDK.

it
git clone https://github.com/espressif/ESP32_RTOS_SDK.git

Notes：

n
1. For the package components of the SDK, refer to “1.3 Package Components”.
2. You can build customized project according the ESP32_RTOS_SDK/examples/project_template.

e
3. Create a directory to store the.bin files compiled.
mkdir –p ~/Workspace/ESP32_BIN

d
4. Set the PATHs variable to point to the SDK and BIN files.

fi
export SDK_PATH=~/Workspace/ESP32_RTOS_SDK

export BIN_PATH=~/Workspace/ESP32_BIN

5.
⚠ Warning：

o n
Make sure you set the correct paths, or it will occur a compile error.

Start to compile files.

C
cd ~/Workspace/project_template
make clean
make

Note：

You need to do Step 3 every time you open a new shell, or you can put it inside your .bashrc file.

Espressif Systems 11/20 2015.12

 2. Getting Started

Note：

If your project is successfully compiled, the irom1.bin, irom0_flash.bin, and user.ota files will be
generated in /Workspace/ESP32_BIN directory. Current contents of /Workspace/ESP32_BIN
directory is shown as Table2-1.

Table 2-1. ESP32_BIN Directory Files

File Name Description

blank.bin • Provided with the SDK.

l
• Used to initialize the system parameters.
boot.bin • Provided with the SDK.
• Main program.

it a
irom1.bin • Generated from compiling.
• Main program.
irom0_flash.bin • Generated from compiling.
• Main program.

n
User.ota • Generated from compiling.
• Main program.
• Don’t need to be uploaded, and will be updated by OTA.

2.1.4. Uploading Firmware

1.

d e
Power on the board with 5V/1A power.

fi
2. Connect the development board to a PC.
3. Toggle 8-digit Toggle Switch to the Download Boot as Table 1-2.

n
4. Install Minicom.
sudo apt-get install minicom

o
5. Run Minicom.
sudo minicom -s

C
6. Configure the items as Figure 2-2.

Figure 2-2. Configuration items of Minicom

Espressif Systems 12/20 2015.12

 2. Getting Started

The configuration items are shown in Table 2-2.

Table 2-2. Configuration Items of Minicom

Item Value

Bps/Par/Bits 115200 8N1

Hardware Flow Control No

Software Flow Control No

l
7. Upload files.
>python esptool_ESP32.py -p dev/tty8 -b 115200 write_flash -ff 40m -

a
fm qio -fs 2m

it
0x0 ~/Workspace/ESP32_BIN/boot.bin
0x04000 ~/Workspace/ESP32_BIN/irom1.bin

0x40000 ~/Workspace/ESP32_BIN/bin/irom0_flash.bin

n
0xFC000 ~/Workspace/ESP32_BIN/blank.bin
0x1FC000 ~/Workspace/ESP32_BIN/esp_init_data_default.bin

below.

Connecting...

d e
For the configuration instructions, refer to Table 2-3. The system will show the information as

fi
Erasing flash...
Wrote 3072 bytes at 0x00000000 in 0.3 seconds (73.8 kbit/s)...

n
Erasing flash...
Wrote 395264 bytes at 0x04000000 in 43.2 seconds (73.2 kbit/s)...

o
Erasing flash...
Wrote 1024 bytes at 0x40000000 in 0.1 seconds (74.5 kbit/s)...

C
Erasing flash...

Wrote 4096 bytes at 0xfc000000 in 0.4 seconds (73.5 kbit/s)...

Erasing flash...
Wrote 4096 bytes at 0x1fc00000 in 0.5 seconds (73.8 kbit/s)...
Leaving...

Table 2-3. Configuration Items of uploading files

Item Value

COM Port You can choose an available COM port for the uploading. We use dev/tty in this example.

Baud Rate Set the baud rate of the uploading. The default value is 115200 bps.

Espressif Systems 13/20 2015.12

 2. Getting Started

Item Value

SPI Speed Set the SPI speed of the uploading. The default value is 40 MHz.

SPI Mode Set the SPI speed of the uploading. The default value is QIO.

Flash Size The size of your flash, We use 2Mbit flash in this example.
The flash size of 1MB, 2MB, 4MB, 8MB, 16MB and 32MB are supported.

Start Address Set the start addresses of the bin files. The start address of blank.bin and
esp_init_data_default.bin may be different when you use a different flash size.
For the start Address of different size of flash, refer to Table 2-4.

Table 2-4. Configuration Items of uploading files

Start Address

a l
it
File Name Notes
Flash Size: 1 MB Flash Size: 2 MB

boot.bin 0x00000 -

n
irom1.bin 0x04000 -

irom0_flash.bin 0x40000 -

e
user.ota① Doesn’t need to be uploaded. -

As shown in the figure above, the file will

blank.bin 0xFE000 0x1FE000 start from the second section(4K) from

d
bottom of the flash.②

As shown in the figure above, the file will

fi
esp_init_data_defa
0xFC000 0x1FC000 start from the fourth section(4K) from
ult.bin③
bottom of the flash.②

n
Notes:
1. User.ota file doesn’t need to be uploaded, and will be used in OTA upgrading.
2. The flash size of 1MB, 2MB, 4MB, 8MB, 16MB and 32MB are supported.

o
3. esp_init_data_default.bin isn’t provided in the version 1.0.0.

C
Espressif Systems 14/20 2015.12
 2. Getting Started

Result
The flash layout is shown as Figure 2-3.

esp_init_data_default.bin

16K 240K 3840K 4K 4K 4K 4K

boot.bin irom1.bin irom0_flash.bin

blank.bin

l
System Parameter

a
Available segment

it
Figure 2-3. Flash Layout

For the flash usage, refer to Table 2-5.

n
Table 2-5. Flash Usage

e
Segment Name Start Address Length

dport0_0_seg org = 0x3FF00000 len = 0x10

d
dram0_0_seg org = 0x3FFD8000 len = 0x24000

iram1_0_seg org = 0x40040000 len = 0x20000

fi
irom0_0_seg org = 0x40080010 len = 0x37FFF0

irom0_1_seg org = 0x3FE04010 len = 0x3BFF0

2.1.5. Running Application

o n
1. Power off and switch the hardware to the running mode.
2. Power on the hardware and run the application.

C
🔚

2.2. SSC Command Reference

Here lists some common Wi-Fi commands for you to test the board.

2.2.1. op
Description
op commands are used to set and query the Wi-Fi mode of the system.
Example
op -Q

Espressif Systems 15/ 20 2015.12

 2. Getting Started

op -S -o wmode

Parameter

Table 2-6. op Command Parameter

Parameter Description

-Q Query Wi-Fi mode.

-S Set Wi-Fi mode.

l
There are 3 Wi-Fi modes:
• mode = 1: STA mode

a
wmode
• mode = 2: AP mode

it
• mode = 3: STA+AP mode

2.2.2. sta

n
Description
sta commands are used to scan the STA network interface, connect or disconnect AP, and

e
query the connecting status of STA network interface.
Example

d
sta -S [-s ssid] [-b bssid] [-n channel] [-h]
sta -Q

fi
sta -C [-s ssid] [-p password]

n
sta -D

Parameter

o
Table 2-7. sta Command Parameter

Parameter Description

C
-S scan Scan Access Points.

-s ssid Scan or connect Access Points with the ssid.

-b bssid Scan the Access Points with the bssid.

-n channel Scan the channel.

-h Show scan results with hidden ssid Access Points.

-Q Show STA connect stutus.

-D Disconnected with current Access Points.

Espressif Systems 16/20 2015.12

 2. Getting Started

2.2.3. ap
Description
ap commands are used to set the parameter of AP network interface.
Example
ap -S [-s ssid] [-p password] [-t encrypt] [-n channel] [-h] [-m
max_sta]
ap –Q

l
ap –L

Parameter

Parameter

-S
Table 2-8. ap Command Parameter

Set AP mode.

it
Description

a
n
-s ssid Set AP ssid.

-p password Set AP password.

e
-t encrypt Set AP encrypt mode.

-h Hide ssid.

d
-m max_sta Set AP max connections.

fi
-Q Show AP parameters.

-L Show MAC Address and IP Address of the connected station.

2.2.4. mac
Description

Example

o n
mac commands are used to query the MAC address of the network interface.

Parameter

C
mac -Q [-o mode]

Parameter

-Q
Table 2-9. mac Command Parameter

Show MAC address.

Description

• mode = 1: MAC address in STA mode.

-o mode
• mode = 2: MAC address in AP mode.

Espressif Systems 17/ 20 2015.12

 2. Getting Started

2.2.5. dhcp
Description
dhcp commands are used to enable or disable dhcp server/client.
Example
dchp -S [-o mode]

dhcp -E [-o mode]

dhcp -Q [-o mode]

l
Parameter

a
Table 2-10. dhcp Command Parameter

it
Parameter Description

-S Start DHCP (Client/Server).

-E End DHCP (Client/Server).

n
-Q show DHCP status.

• mode = 1 : DHCP client of STA interface.

e
-o mode • mode = 2 : DHCP server of AP interface.
• mode = 3 : both.

2.2.6. ip
Description

fid
ip command are used to set and query the IP address of the network interface.
Example

Parameter

o
ip -Q [-o mode]

n
ip -S [-i ip] [-o mode] [-m mask] [-g gateway]

C Parameter

-Q

-o mode
Table 2-11. ip Command Parameter

Show IP address.
Description

• mode = 1 : IP address of interface STA.

• mode = 2 : IP address of interface AP.
• mode = 3 : both
-S Set IP address.

-i ip IP address.

-m mask Subnet address mask.

-g gateway Default gateway.

Espressif Systems 18/20 2015.12

 2. Getting Started

2.2.7. reboot
Description
reboot command is used to reboot the board.
Example
reboot

2.2.8. ram

l
ram command is used to query the size of the remaining heap in the system.
Example

a
ram

it
e n
fid
o n
C
Espressif Systems 19/20 2015.12
 a l
it
e n
fid
o n
C 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, NON-INFRINGEMENT, 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. The Bluetooth logo is a
registered trademark of Bluetooth SIG.
Espressif System
All trade names, trademarks and registered trademarks mentioned in this document are
IOT Team property of their respective owners, and are hereby acknowledged.

http://bbs.espressif.com Copyright 2015 Espressif Systems Inc. All rights reserved.