ESP8266

Quick Start Guide

NS D
D) SIG DE
RN DE EN
M
M
NE O
R EC
W
FO T R

(N
NO

Version 1.5
Copyright © 2023
 About This Guide
This document is a quick start guide to ESP8266. The document is structured as follows.

Chapter Title Content

Introduction to the ESP8266 development board ESP-

Con guring the Development
Chapter 1 LAUNCHER, and how to download rmware to the board and
Board ESP-LAUNCHER
run it.

Compiling
Chapter 2 Compiling the ESP8266_NONOS_SDK in the virtual machine.
ESP8266_NONOS_SDK

Compiling
Chapter 3 Compiling the ESP8266_RTOS_SDK.
ESP8266_RTOS_SDK

Chapter 4 Common Debug Methods Common debugging methods and sample codes.

Downloading Firmware into Instructions on how to download rmware with ESP-

Chapter 5
the ESP-WROOM-02 WROOM-02.

ESP8266-related must-read documents and must-have

Appendix A Learning Resources
resources.

Release Notes
Date Version Release notes

2016.08 V1.0 First release.

2016.11 V1.1 Added Appendix A—Learning Resources.

Added two Github links to RTOS and non-OS SDK sample

2017.01 V1.2
code in Appendix A.2—Must-Have Resources.

2017.02 V1.3 Updated the link to the OVA image le in Section 2.1.

2017.05 V1.4 Updated Chapter 1.

• Removed a broken link in the Appendix;

2023.06 V1.5 • Added NRND in title page and footer;

• Note that this document is no longer being updated.

fi
fi
fi
fi
 Table of Contents
1. Con guring the Development Board ESP-LAUNCHER .......................................................1
1.1. Hardware Preparation ................................................................................................................1
1.2. Software Preparation .................................................................................................................1
1.3. Downloading Firmware into the ESP-LAUNCHER .....................................................................2

2. Compiling ESP8266_NONOS_SDK .......................................................................................7

2.1. Downloading the Virtual Machine ..............................................................................................7
2.2. Setting up Development Environment .......................................................................................7
2.3. Compiling Process .....................................................................................................................9

3. Compiling ESP8266_RTOS_SDK ........................................................................................12

3.1. Compiling Process ...................................................................................................................12
3.2. ESP8266_RTOS_SDK Architecture ..........................................................................................15

4. Common Debug Methods ...................................................................................................16

4.1. Common Debug Methods........................................................................................................16
4.1.1. Add UART Output Logs ..............................................................................................16
4.1.2. Debug Fatal Exception ...............................................................................................16

5. Downloading Firmware into the ESP-WROOM-02 .............................................................17

A. Appendix—Learning Resources .........................................................................................19

A.1. Must-Read Documents ............................................................................................................19
A.2. Must-Have Resources..............................................................................................................20
fi
 1. Con guring the Development Board ESP-LAUNCHER

1. Con guring the Development

Board ESP-LAUNCHER
1.1. Hardware Preparation
To start developing applications for the ESP8266, users need the following hardware and
its corresponding software tools:
• One of the ESP8266 Hardware Development Kits (HDKs) speci ed below:
- ESP8266’s development board, ESP-LAUNCHER, as shown in Table 1-1.
- ESP8266’s module, ESP-WROOM-02, as described in Chapter 5.
• PC for programming: Windows XP or Windows 7 OS is recommended, with enough
RAM to run a Linux virtual machine.
• Micro-USB cable.

📖 Notes:
! When users deploy third-party development boards or modules that integrate ESP8266, they should
use development rmware provided by the corresponding manufacturers.
! To purchase ESP-WROOM-02 or ESP-LAUNCHER, please visit Espressif’s of cial online store at:
https://espressif.taobao.com,

Table 1-1. The ESP-LAUNCHER

• 1 ESP-LAUNCHER
• 1 Micro-USB cable

⚠ Notice:
The ESP8266 Wi-Fi module requires 3.3V power supply capable of delivering a peak current of 500 mA.

1.2. Software Preparation

• ESP8266’s Flash Download Tool

- Download it from: ESP8266 Flash Download Tools

• ESP8266’s SDK

- Download the SDK from: ESP8266 SDK

Not Recommended For New Designs (NRND)

Espressif 1/21 2023.06
fi
fi
fi
fi
fi
 1. Con guring the Development Board ESP-LAUNCHER

- The of cial AT rmware (ESP8266_NONOS_SDK\bin\at) can be downloaded into

the ESP-LAUNCHER by referring to the BIN locations included in the Readme le
which is in the same directory. For instructions on downloading the rmware into ESP-
LAUNCHER, please refer to Section 1.3.
• UART terminal emulator tool

The default baud rate of ESP8266 is74880, therefore, UART tools that can support the
default baud rate are recommended. Please note that certain USB-UART converters
may not support all baud rates if users use a third-party development board.

1.3. Downloading Firmware into the ESP-LAUNCHER

1. We use the ESP8266_NONOS_SDK_V2.0.0_16_07_19 as an example. The AT
rmware binaries are located in
ESP8266_NONOS_SDK_V2.0.0_16_07_19\ESP8266_NONOS_SDK\bin.

Figure 1-1. ESP8266_NONOS_SDK BIN Folder

2. Settings of the development board, ESP-LAUNCHER.

Figure 1-2. The ESP-LAUNCHER

• switch 1: toggle to the lower side;

Not Recommended For New Designs (NRND)

Espressif 2/21 2023.06
fi
fi
fi
fi
fi
fi
 1. Con guring the Development Board ESP-LAUNCHER

• switch 2: toggle to the lower side;

• switch 3: toggle to the upper side;
• pin4: put a jumper cap on the two pins above;
• pin5: put a jumper cap on it.

3. Use a Micro-USB cable to connect ESP-LAUNCHER to the PC. The UART driver needs
to be installed on the PC.
4. Double-click on ESPFlashDownloadTool_v3.3.4.exe to run the ESP8266 Flash
Download Tool on the PC.

Figure 1-3. ESP8266 Flash Download Tool

Figure 1-3 uses 16Mbit-C1 (1024+1024 map) ash as an example. The download
addresses are shown in Table 1-2.

Not Recommended For New Designs (NRND)

Espressif 3/21 2023.06
fi
fl
 1. Con guring the Development Board ESP-LAUNCHER

Table 1-2. Download AT Binaries for 16 Mbit-C1 Flash Map

BIN Address Description

blank.bin 0x1FB000 It initializes the RF_CAL parameter area.

It stores the default RF parameter values and has to be

downloaded into the ash at least once.
esp_init_data_default.bin 0x1FC000
If the RF_CAL parameter area is initialized, this BIN has to be
downloaded too.

blank.bin 0xFE000 It initializes the user parameter area.

blank.bin 0x1FE000 It initializes the system parameter area.

boot.bin 0x00000 It is the main program located in \bin\at.

user1.2048.new.5.bin 0x01000 It is the main program located in \bin\at\1024+1024.

📖 Note:
The SpiFlashConfig and the COM on the ESP8266 Flash Download Tool should be set according to the
actual situation.

5. Click the START button and wait for the ESP-LAUNCHER to power up.
6. Power on the ESP-LAUNCHER by toggling switch 1 as is shown in Figure 1-2 to the
upper side. Toggle switch 2 as is shown in Figure 1-2 to the lower side to enter the
download mode.
7. The ESP8266 Flash Download Tool will start to download AT rmware into the ESP-
LAUNCHER. The DETECTED INFO area will display the information of the ash chip on
ESP-LAUNCHER.

Not Recommended For New Designs (NRND)

Espressif 4/21 2023.06
fi
fl
fi
fl
 1. Con guring the Development Board ESP-LAUNCHER

Figure 1-4. ESP8266 Flash Download Tool - Downloading Firmware

8. After the download is nished, as Figure 1-5 shows, toggle switch 1 to the lower side to
power off the ESP-LAUNCHER.

Figure 1-5. ESP8266 Flash Download Tool–Finishing Downloading Firmware

9. Open the UART tool on the PC, set the baud rate to 115200, and con gure new line
mode.

📖 Note:

When using AT commands, then a baud rate of 115200 and new line mode are needed.

10.Set the ESP8266 to working mode by toggling switch 2 to the upper side. Then toggle
switch 1 to the upper side to power on the ESP-LAUNCHER.

Not Recommended For New Designs (NRND)

Espressif 5/21 2023.06
fi
fi
fi
 1. Con guring the Development Board ESP-LAUNCHER

The log print may look garbled, as shown in Figure 1-6 (which is normal, because the
default power-on baud rate of ESP8266 is 74880). The “ready” message indicates that
ESP-LAUNCHER is working successfully.
11.Input command AT+GMR and press Enter button. The information of the AT rmware will
appear, as Figure 1-7 shows.

Figure 1-6. AT Logs on the UART Tool

For more AT commands and examples, please refer to documents:

ESP8266 AT Instruction Set and ESP8266 AT Command Examples.

Not Recommended For New Designs (NRND)

Espressif 6/21 2023.06
fi
fi
 2. Compiling ESP8266_NONOS_SDK

2. Compiling
ESP8266_NONOS_SDK
This chapter describes how to compile ESP8266_NONOS_SDK by using the AT demo as
an example.

2.1. Downloading the Virtual Machine

1. PC: Windows XP or Windows 7 OS is recommended.
2. The development environment provided by Espressif Systems is based on Lubuntu. We
also provide a virtual image of the development environment that can be run on
VirtualBox.
• Download VirtualBox-5.0.16-105871-Win.exe from:
https://www.virtualbox.org/wiki/Downloads
• Download ESP8266_lubuntu_20141021.ova from:
http://downloads.espressif.com/FB/ESP8266_GCC.zip

2.2. Setting up Development Environment

Steps Results

1. Start Windows OS and install the virtual machine.

• Double-click on
VirtualBox-5.0.16-105871-Win.exe
and install VirtualBox.
📖 Note:
VirtualBox has different versions. We are
using Windows V.5.0.16 as an
example.
• Double-click on Oracle VM
VirtualBox.exe to run the program
and the system will display the main
menu 👉 .

💬 Tip:
ESP8266’s virtual machine takes up
much space (RAM). Please make sure
the machine has enough memory to
spare.

2. Set the default machine folder.

Not Recommended For New Designs (NRND)

Espressif 7/21 2023.06
 2. Compiling ESP8266_NONOS_SDK

Steps Results

• Create a new folder, for example, D:

\VM.
• Select File > Preferences, and the
system will show the dialog box 👉 .
• In the General tab, set the location
for the virtual machine in Default
Machine Folder, for example, D:
\VM.

💬 Tip:
ESP8266’s virtual machine takes up
much space (RAM). Please make sure
the machine has enough memory to
spare.

3. Import the image le.

• Select File > Import Appliance...,

and a dialog box will show up 👉 .
• Select the image le, for example, C:
\ESP8266_lubuntu_20141021.ova,
and click on Next.
• Click Import to con rm the settings.

4. Create a shared folder.

• Create a new folder named D:

\VM\share.
• Select Machine > Settings >
Shared Folders…, and a dialog box
will show up 👉 .
• Select the shared folder in Machine
Folders, for example, D:\VM\share.

Not Recommended For New Designs (NRND)

Espressif 8/21 2023.06
fi
fi
fi
 2. Compiling ESP8266_NONOS_SDK

5. Run the virtual machine.

• After importing, a virtual machine

named ESP8266_lubuntu shows up
👉.
• Double-click on ESP8266_lubuntu
or Start to power on the virtual
machine.

• The system shows the ESP8266

virtual machine 👉 .
• If the virtual machine enters idle
mode and is locked, a dialog box like
the one below👇 will show up. This
is where the users enter the
password: espressif.

• Double-click on LXTerminal to start

compiling applications. For more
details please refer to Chapter 2.3.

2.3. Compiling Process

1. Start the virtual machine. Run LXTerminal on the desktop.
2. Copy the ESP8266_NONOS_SDK to the shared folder.

Not Recommended For New Designs (NRND)

Espressif 9/21 2023.06
 2. Compiling ESP8266_NONOS_SDK

Steps Result

• Copy the ESP8266_NONOS_SDK folder to the

shared directory, for example, D:\VM\share.
• Copy the
ESP8266_NONOS_SDK\examples\at folder to
the directory D:
\VM\share\ESP8266_NONOS_SDK, as shown
in the gure on the right 👉 .

3. Mount the shared directory to the virtual machine.

Steps Result

• Execute command ./mount.sh in the

LXTerminal.
• Input the password espressif.
Shared folder mounting is completed.

• Open the shared directory

ESP8266_NONOS_SDK in the virtual machine
and check if the mounting has been successful.
- If successful, the directory contains les as
the gure on the right 👉 shows.
- If not, the directory will be empty and users
will need to repeat the previous step.

Not Recommended For New Designs (NRND)

Espressif 10/21 2023.06
fi
fi
fi
 2. Compiling ESP8266_NONOS_SDK

4. Change the directory to /Share/ESP8266_NONOS_SDK/at in the LXTerminal.

Steps Result

• In the LXTerminal, execute the command:

cd /home/esp8266/Share/ESP8266_NONOS_SDK/at

• Then execute command:

./gen_misc.sh
to start compiling.
• For example, the options for STEP 1 ~ 5 can be:
1, 1, 2, 0, 5.

📖 Note:
For more details on compiling, please refer to ESP8266 SDK Getting Started Guide.

5. After compilation, the binaries generated and their corresponding download addresses
in the ash memory will be shown as follows:
Support boot_v1.4 and +

Generate user1.2048.new.5.bin successfully in folder bin/upgrade.

boot.bin------------>0x00000

user1.2048.new.5.bin--->0x01000

!!!

📖 Note:
Users can open the /home/esp8266/Share/ESP8266_NONOS_SDK/bin/upgrade directory and check the
binaries compiled.

6. The AT binaries generated can be downloaded to the ESP-LAUNCHER (refer to Section

1.3 ) and run.

Not Recommended For New Designs (NRND)

Espressif 11/21 2023.06
fl
 3. Compiling ESP8266_RTOS_SDK

3. Compiling
ESP8266_RTOS_SDK
3.1. Compiling Process
1. Download ESP8266_RTOS_SDK from:
https://github.com/espressif/ESP8266_RTOS_SDK
ESP8266_IOT_PLATFORM is a demo application based on ESP8266_RTOS_SDK.
Download from: https://github.com/espressif/ESP8266_IOT_PLATFORM
2. Copy ESP8266_IOT_PLATFORM and ESP8266_RTOS_SDK to the shared folder.

Steps Result

Copy ESP8266_RTOS_SDK and

ESP8266_IOT_PLATFORM to the shared folder,
for example, D:\VM\share as shown on the right
👉.

3. Start the virtual machine. Run LXTerminal.

Steps Result

• Start ESP8266 virtual machine 👉 .

- If the virtual machine is locked, please enter
the password: espressif to unlock it.
• Double-click on LXTerminal to start the
compilation.

Not Recommended For New Designs (NRND)

Espressif 12/21 2023.06
 3. Compiling ESP8266_RTOS_SDK

4. Mount the shared directory to the virtual machine.

Steps Result

• Execute command ./mount.sh in the

LXTerminal.
• Input the password: espressif.
Shared folder mounting is completed.

• Open the shared directory

ESP8266_RTOS_SDK in the virtual machine
and con rm if the mounting has been
successful.
- If successful, the directory contains les as
shown in the gure on the right 👉 .
- If not, the directory will be empty, and users
will need to repeat the previous step.

5. Modify the le ESP8266_IOT_PLATFORM/gen_misc.sh. Set the variable PATH to point

to the SDK and binaries.

Steps Result

• SDK_PATH: the path of ESP8266_RTOS_SDK

• BIN_PATH: the path where the generated
binaries are stored after compilation
• Please see the gure on the right 👉 .

6. Modify ESP8266_IOT_PLATFORM/makefile.

Steps Result

Modify the LINKFLAGS_eagle.app.v6 area in the

ESP8266_IOT_PLATFORM/makefile by:
- Deleting -lminic
- Adding -lcirom and -lmirom

Not Recommended For New Designs (NRND)

Espressif 13/21 2023.06
fi
fi
fi
fi
fi
 3. Compiling ESP8266_RTOS_SDK

7. Switch to /Share/ESP8266_IOT_PLATFORM in the LXTerminal.

Steps Result

• Execute the command:

cd /home/esp8266/Share/ESP8266_IOT_PLATFORM
• Then execute the command:
./gen_misc.sh
to start compiling.

📖 Note:
For more details on compilation, please refer to ESP8266 SDK Getting Started Guide.

8. After compilation, the binaries generated and their download addresses in the ash
memory will be shown as follows:
Support boot_v1.4 and +

Generate user1.1024.new.2.bin successfully in BIN_PATH

boot.bin------------>0x00000

user1.1024.new.2.bin--->0x01000

!!!

📖 Note:
Users can open the /home/esp8266/Share/ESP8266_RTOS_SDK/bin directory and check the binaries
compiled.

9. Download the generated binaries to the ESP-LAUNCHER and run.

📖 Note:
The default baud rate of ESP8266 is 74880.

Not Recommended For New Designs (NRND)

Espressif 14/21 2023.06
fl
 3. Compiling ESP8266_RTOS_SDK

3.2. ESP8266_RTOS_SDK Architecture

Application
(application logic, configurations and policies)

Application Framework & Service

Restful Web Cloud Firmware
HTTP Client HTTP Server
Services Protocol Upgrade

ESP Power XML/

TCP/IP mDNS TLS/SSL
Protocols Management cJSON

Wi-Fi Control Interface

RTOS

Low Level Control and Physical Abstract Layer

High MAC

Low MAC

Figure 3-1. ESP8266_RTOS_SDK Architecture

Not Recommended For New Designs (NRND)

Espressif 15/21 2023.06
 4. Common Debug Methods

4. Common Debug Methods

4.1. Common Debug Methods
4.1.1. Add UART Output Logs
For ESP8266_NONOS_SDK, users can add debug logs as below:
os_printf("SDK version:%s\n", system_get_sdk_version());

For ESP8266_RTOS_SDK, users can add debug logs as below:

printf("SDK version:%s\n", system_get_sdk_version());

4.1.2. Debug Fatal Exception

If a fatal exception occurs, the UART output logs will be shown as below:
Fatal exception (28):

epc1=0x4025bfa6, epc2=0x00000000, epc3=0x00000000, excvaddr=0x0000000f, depc=0x00000000

The debugging steps are as follows:

1. Find the .s le that corresponds to the rmware that is currently running.
For example, if eagle.flash.bin and eagle.irom0text.bin are running, then the
corresponding le is eagle .s.
2. Locate the address of epc1 (in the form of 0x40XXXXXX) in the .s le to nd the target
function.
3. Add the UART logs before and after the target function to debug the fatal exception
problem.

Not Recommended For New Designs (NRND)

Espressif 16/21 2023.06
fi
fi
fi
fi
fi
 5. Downloading Firmware into the ESP-WROOM-02

5. Downloading Firmware into the

ESP-WROOM-02
Please follow the steps below to download rmware into ESP-WROOM-02.
1. ESP-WROOM-02 is the of cial ESP8266 module provided by Espressif Systems. Lead
out the pins of ESP-WROOM-02, as shown in Table 5-1.

Table 5-1. ESP-WROOM-02 Pins

Pin Pin status Figure

EN Pull up

3V3 3.3V power supply (VDD)

IO15 Pull down

UART Download mode: pull down;

IO0
FLASH Boot mode: oating/pull up

GND GND

RXD UART Download Rx

TXD UART Download Tx, oating/pull up

2. Connect ESP-WROOM-02 to the USB-to-TTL converter, using Dupont lines, as shown

in Figure 5-1.

ESP-WROOM-02

USB-to-TTL converter
3V3
3V3
EN

RXD TXD
PC

TXD RXD

GND GND

IO15 IO0

Figure 5-1. ESP-WROOM-02 Download Mode

3. Connect the USB-to-TTL converter to the PC.

4. Download rmware to ash with the ESP8266 Flash Download Tool.

Not Recommended For New Designs (NRND)

Espressif 17/21 2023.06
fi
fl
fl
fl
fi
fi
 5. Downloading Firmware into the ESP-WROOM-02

📖 Note:
On how to download rmware, please refer to Section 1.3.

5. After downloading, set IO0 as oating or pull up and switch ESP-WROOM-02 to

working mode.
6. Power on ESP-LAUNCHER again and the chip will read and run programs from the
ash.

📖 Note:
IO0 is an internal pull-up pin. For more information on the ESP-WROOM-02 hardware, please refer to
ESP8266 System Description and ESP-WROOM-02 Datasheet.

Not Recommended For New Designs (NRND)

Espressif 18/21 2023.06
fl
fi
fl
 Appendix A

A. Appendix—Learning
Resources
A.1. Must-Read Documents
• ESP8266EX Datasheet

Description: This document introduces the speci cations of ESP8266EX, including an

overview of its features, protocols, technical parameters and applications. It also
provides ESP8266EX’s pin layout and the relevant description, as well as major
functional modules and protocols applied on ESP8266EX (CPU, ash and memory,
clock, radio, Wi-Fi, and low-power management). Furthermore, it provides a description
of peripheral interfaces integrated on ESP8266EX, lists the electrical data of ESP8266EX
and illustrates the package details for ESP8266EX.
• ESP8266 Hardware Resources
Description: This zip package includes the manufacturing speci cations of the ESP8266
board and the modules, manufacturing bill of materials (BOM) and schematics.
• ESP8266 RTOS SDK Programming Guide
Description: This document provides sample codes based on ESP8266_RTOS_SDK,
including basic examples, networking protocol examples and advanced examples.
• ESP8266 AT Command Examples
Description: This document introduces some speci c examples of using Espressif’s AT
commands, including setting up single connection using ESP8266 as a TCP client,
setting up UDP transmission and transparent transmission, and setting up multiple
connection using ESP8266 as a TCP server.
• ESP8266 AT Instruction Set
Description: This document provides lists of AT commands based on
ESP8266_NONOS_SDK, including user-de ned AT commands, basic AT commands,
Wi-Fi AT commands and TCP/IP-related AT commands. It also introduces the
downloading of AT rmware into ash.
• ESP8266 Non-OS SDK API Reference
Description: This document lists ESP8266_NONOS_SDK APIs, and provides an
overview of the ESP8266_NONOS_SDK. It also introduces the readers to system APIs,
TCP/UDP APIs, mesh APIs, application-speci c APIs, de nitions and data structures, as
well as APIs for peripheral interfacing.
• ESP8266 RTOS SDK API Reference
Description: This document lists ESP8266_RTOS_SDK APIs, including functions for Wi-
Fi-related APIs, and boot APIs, etc.

Not Recommended For New Designs (NRND)

Espressif 19/21 2023.06
fi
fl
fi
fi
fi
fi
fi
fi
fl
 Appendix A

• FAQ

A.2. Must-Have Resources

• ESP8266 SDKs
Description: This webpage provides links to the latest version of the ESP8266 SDK as
well as the older ones.
• RTOS Sample Code
Description: This webpage provides sample code for the commonly-used functions.
• Non-OS Sample Code
Description: This webpage provides sample code for the commonly used functions.
• ESP8266 Tools
Description: This webpage provides links to the ESP8266 ash download tools and
ESP8266 performance evaluation tools.
• ESP8266 APK
• ESP8266 Certi cation and Test Guide
• ESP8266 BBS
• ESP8266 Resources

Not Recommended For New Designs (NRND)

Espressif 20/21 2023.06
fi
fl
 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.
All trade names, trademarks and registered trademarks mentioned in this document are
Espressif IOT Team property of their respective owners, and are hereby acknowledged.
www.espressif.com Copyright © 2023 Espressif Inc. All rights reserved.