ESP-Techpedia_EN

Release master
Espressif Systems
Oct 12, 2024
Table of contents

Table of contents i

1 ESP-FAQ 3

2 ESP Friends 5
2.1 Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 Board selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 Flash Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.3 Environment Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.1.4 Getting Started with Project Development . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.2 Advanced Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.2.1 Component Management and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.2.2 Advanced Code Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.2.3 Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
2.2.4 Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.3 Solution Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.3.1 AI Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
2.3.2 Brushless Motor Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
2.3.3 Camera Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
2.3.4 LCD Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
2.3.5 Lighting Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
2.3.6 Mesh Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
2.3.7 Provisioning Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
2.3.8 Wireless Network Card Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
2.4 Recommended Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.4.1 Wireshark Packet Capture Tutorial on Windows . . . . . . . . . . . . . . . . . . . . . . 134

i
ii
Table of contents

ESP-Techpedia is a comprehensive platform by Espressif Systems, which aggregates various technical documents
with the aim to provide developers with comprehensive and accurate information about Espressif s technologies.
We not only cover documents necessary for getting started with software development, but also collect common
technical Q&A to address developers queries when using Espressif s chips, modules, or development boards.
On ESP-Techpedia, you can easily access a wide range of Espressif technical documents. For instance, the ESP
Friends documentation helps you quickly get started with Espressif development, while the ESP-FAQ provides solu-
tions to common issues.
In addition to compiling a variety of technical documents, ESP-Techpedia warmly welcomes new document requests
from developers worldwide. We hope to offer more valuable technical documents through close interaction, making
development an effortless experience.
Whether you are a beginner or an experienced developer, ESP-Techpedia will be your indispensable technical ref-
erence, empowering you to achieve your project goals more efficiently.

ESP Friends ESP FAQ

Espressif Systems 1 Release master

Submit Document Feedback
Table of contents

Espressif Systems 2 Release master

Submit Document Feedback
Chapter 1

ESP-FAQ

Please refer to ESP-FAQ

3
Chapter 1. ESP-FAQ

Espressif Systems 4 Release master

Submit Document Feedback
Chapter 2

ESP Friends

ESP Friends documents can help developers quickly get started with Espressif s development, such as guidance on
how to select ESP hardware, build an environment, get started with software, etc. ESP solution recommendations
and other advanced development documents will be added in the future, so stay tuned!

2.1 Get Started

In this section, we provide a basic getting started guide for ESP beginners. Whether you re new to it or want to
solidify the basics, this section will guide you through the basics of ESP operation. You will learn key basic knowledge,
including hardware selection, firmware programming, environment setup, etc.

2.1.1 Board selection

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

In the rapidly changing IoT market, Espressif has launched a series of distinctive ESP chips to fully meet the evolving
demands. Choosing the right ESP chip is particularly important as it will directly affect performance and functionality
of the product. Choose the suitable ESP chip based on the project s application scenario, power consumption,
wireless communication, GPIO and memory requirements.
To help developers better understand the ESP chips and modules, below is a brief comparison chart.

5
Chapter 2. ESP Friends

Table 1: Chip Comparison

Chip Year of Application Sce- Wireless GPIO SRAM PSRAM
Release narios Functions Support
ESP32-C6 2023 Ultra-low power IoT BLE 5.0 + Wi- 23 512 KB ×
devices with long Fi 6 + Thread +
battery life, Thread Zigbee
border routers, Mat-
ter gateways, Zigbee
bridges
ESP32-C2 2022 Sockets, lighting, BLE 5.0 + Wi- 14 272 KB ×
sensors, simple smart Fi 4
home appliances
ESP32-H2 2021 Thread border BLE 5.0 + 19 230 KB ✓
routers, Matter Thread +
gateways, Zigbee Zigbee
bridges
ESP32-S3 2020 Smart cameras, face BLE 5.0 + Wi- 36 320 KB ✓
recognition, voice Fi 4
recognition, voice
wake-up, real-time
data collection and
processing, complex
peripheral control
ESP32-S2 2020 Real-time data col- Wi-Fi 4 36 320 KB ✓
lection and process-
ing, complex periph-
eral control
ESP32-C3 2020 Electrical lighting, BLE 5.0 + Wi- 15 400 KB ×
switch sockets, smart Fi 4
home appliances,
industrial control
field
ESP32 2016 Recommended to BLE 4.2 + BT + 26 520 KB ✓
use the latest released Wi-Fi 4
ESP32-S3
ESP8266 2014 Recommended Wi-Fi 4 11 160 KB ×
to use the latest
released ESP32-
C2 or ESP32-C3.
ESP8266 is about
to reach the 12-year
supply guarantee
time

Note: The above is just a brief introduction to the ESP chip series. If you want to further understand the specific
details and features of each series of chips or modules, you can use the ESP Chip & Module Selection Tool to easily
obtain relevant informations. This tool will select the ESP chip most suitable for the developer s application based
on project requirements and technical specifications.

Chips, Modules, Development Boards

Espressif officially provides chips, modules, and development boards, which have different uses and features in the
development and deployment process of IoT applications.
1. Chip:

Espressif Systems 6 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• The ESP series chip is the fundamental integrated circuit (IC) manufactured by Espressif, serving as the
core component of the entire product line. These chips typically integrate processors (CPUs), memory,
communication interfaces, General Purpose Input Output (GPIO), and other hardware functionalities.
They can be directly integrated into custom circuit boards to create highly specialized IoT devices, making
them suitable for projects demanding compact size and specific functionalities.
• The chips require connection to external components for power and functionality. Additionally, devel-
oping products with these chips involves certification for wireless communication protocols, which can
be somewhat intricate.
2. Module:

• The module is a package of Espressif chips that integrats chips, crystals, antennas, and flash. Espressif
s modules typically include pre-integrated wireless functions such as Wi-Fi, Bluetooth, and are certified
with FCC, CE, and other regulatory certifications. This allows developers to focus more on applications
development without the need to manage the complexities of wireless communication, thereby acceler-
ating time-to-market for products.
• Compared to individual chips, modules offer greater convenience in hardware design and project devel-
opment.
3. Development Board:

Espressif Systems 7 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• The development board is a comprehensive development platform that integrates Espressif modules. It
includes various interfaces and resources for debugging, development, and testing, and facilitates software
debugging and firmware flashing during the development phase. Typically, in the early stages of project
development, rapid testing and verification are conducted using the development board. As the product
moves towards mass production, the module is integrated into the final design.
• Moreover, the development board serves as an essential tool for developers new to Espressif chips, en-
abling them to quickly familiarize themselves with the platform. It accelerates the verification of devel-
opers ideas and designs, enabling rapid prototyping.

Selection Guide Choosing the right chip, module, or development board depends on the project s requirements,
timeline, technical capabilities, and budget. Here are some factors to consider when choosing:
1. Rapid development and prototype verification:
• Development boards are highly beneficial for rapid function development and verification in the early stages
of the project
2. Custom hardware design:
• If a highly customized circuit board and hardware design are required, chips are a more suitable
choice

Note: Custom designs require certification through wireless communication protocols, which may
increase development time and cost.

3. Speed to market:
• Modules can usually accelerate the product s time to market, as they have pre-integrated wireless functions
(such as Wi-Fi, Bluetooth) and relevant certifications. Developers can focus more on application development
without dealing with the details of wireless communication
4. Cost budget:
• Using chips typically costs less, but custom design may increase time and development difficulty. Modules
have a relatively higher cost, but can speed up the development process
5. Team technical capabilities:

Espressif Systems 8 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• If your team is new to Espressif chips or has limited technical resources, using modules is easier to get started,
accelerates the project process and reduces technical risks. Using chips requires higher technical capabilities
and more development experience

ESP32-C6

Supported Features:
• 30 (QFN40) or 22 (QFN32) programmable GPIO pins, supporting SPI, UART, I2C, I2S, RMT, TWAI, and
PWM
• Can be used for development solutions: ultra-low power IoT devices with long battery life, Thread border
routers, Matter gateways, Zigbee bridges

Development Boards
• ESP32-C6-DevKitC-1 : ESP32-C6-DevKitC-1 is an entry-level development board that can be used to flash
and experience examples in IDF.

• ESP32-C6-DevKitM-1 : ESP32-C6-DevKitCM-1 is an entry-level development board that can be used to flash

and experience examples in IDF.

Espressif Systems 9 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Hardware Design Guide

• ESP32-C6 Hardware Design Guide

Purchase Link
• ESP32-C6 Development Board

ESP32-C2

Supported Features
• 14 programmable GPIO pins: SPI, UART, I2C, LED PWM controller, SAR ADC/DAC, temperature sensor
• Can be used for development schemes: sockets, lighting, sensors, simple smart home appliances

Development Board
• ESP8684-DevKitM-1 ESP8684-DevKitM-1 is an entry-level development board that can be used to flash
and experience examples in IDF.

Espressif Systems 10 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Hardware Design Guide

• ESP32-C2 Hardware Design Guide

Purchase Link
• ESP32-C2 Development Board

ESP32-H2

Supported Features:
• 19 programmable GPIO pins, supporting common peripheral interfaces such as UART, SPI, I2C, I2S, infrared
transceiver, LED PWM, full-speed USB serial/JTAG controller, GDMA, MCPWM
• Can be used for development schemes: Thread border router, Matter gateway, Zigbee bridge

Development Board
• ESP32-H2-DevKitM-1 : ESP32-H2-DevKitM-1 is an entry-level development board that can be used to pro-
vision and experience examples in IDF.

Espressif Systems 11 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Hardware Design Guide

• ESP32-H2 Hardware Design Guide

Purchase Link:
• ESP32-H2 Development Board

ESP32-S3

Supported Features:
• Common peripheral interfaces such as SPI, I2S, I2C, PWM, RMT, ADC, UART, SD/MMC host controller,
and TWAI controller, etc.
• Can be used for development schemes: Smart camera, face recognition, voice recognition, voice wake-up,
real-time data collection and processing, complex peripheral control

Development Board:
• EESP32-S3-DevKitC-1 : ESP32-S3-DevKitC-1 is an entry-level development board that can be used to pro-
vision and experience examples in IDF.

• ESP32-S3-DevKitM-1 : ESP32-S3-DevKitM-1 is a beginner-friendly development board that can be used to

flash and experience examples in IDF.

• ESP32-S3-BOX : ESP-BOX provides users with a platform for developing and controlling smart home devices
based on voice assistant + touch screen control, sensors, infrared controllers, and smart Wi-Fi gateways.

Espressif Systems 12 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-S3-EYE : ESP32-S3-EYE is a small AI (Artificial Intelligence) development board launched by Espres-

sif. The development board is equipped with a 2-megapixel camera, an LCD display, and a microphone,
suitable for applications such as image recognition and audio processing. You can use ESP-WHO to develop
various AIoT (Artificial Intelligence of Things) applications, such as smart doorbells, monitoring systems, face
recognition attendance machines, etc.

Espressif Systems 13 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-S3-USB-OTG : ESP32-S3-USB-OTG is a development board focused on USB-OTG function verifi-

cation and application development, based on ESP32-S3 SoC, supports Wi-Fi and BLE 5.0 wireless functions,
supports USB host and USB slave functions. It can be used to develop wireless storage devices, Wi-Fi network
cards, LTE MiFi, multimedia devices, virtual keyboards and mice, and other applications.

• ESP32-S3-Korvo-1 : ESP32-S3-Korvo-1 is an AI development board launched by Espressif, equipped with

Espressif Systems 14 Release master

Submit Document Feedback
Chapter 2. ESP Friends

the ESP32-S3 chip and Espressif s voice recognition SDK ESP-Skainet. ESP32-S3-Korvo-1 supports voice
wake-up and offline voice command recognition in both Chinese and English. You can use ESP-Skainet to
develop various voice recognition applications, such as smart screens, smart plugs, smart switches, etc.

• ESP32-S3-Korvo-2 : ESP32-S3-Korvo-2 is a multimedia development board based on the ESP32-S3 chip,

equipped with a dual microphone array, supporting voice recognition and near/far field voice wake-up. It
also carries peripherals such as LCD, camera, microSD card, etc., and can support JPEG-based video stream
processing, meeting the development needs of users for low-cost, low-power, and networked audio and video
products.

Hardware Design Guide

Espressif Systems 15 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-S3 Hardware Design Guide

Purchase link:
• ESP32-S3 Development Board

ESP32-S2

Supported Features:
• Full-speed USB OTG interface, SPI, I2S, UART, I2C, LED PWM, LCD interface, Camera interface, ADC,
DAC, touch sensor
• Can be used for development solutions: real-time data collection and processing, complex peripheral control

Development Boards:
• ESP32-S2-DevKitC-1 : ESP32-S2-DevKitC-1 is a beginner-level development board that can be used to flash
and experience examples in IDF.

• ESP32-S2-HMI-DevKit-1 : ESP32-S2-HMI-DevKit-1 is designed for GUI application scenarios, capable of

realizing smart home interactive panels, speakers with screens, alarm clocks, and other human-machine inter-
active interfaces for intelligent control. This development board has a wealth of onboard sensors and expansion
interfaces, making it easy for users to quickly carry out secondary development and implement various func-
tions.

Espressif Systems 16 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-S2-Saola-1 : ESP32-S2-Saola-1 is a small development board based on ESP32-S2 from Espressif,

which can be used to flash and experience examples in IDF.

Hardware Design Guide

• ESP32-S2 Hardware Design Guide

Purchase link:
• ESP32-S2 Development Board

ESP32-C3

Supported Features:
• Rich communication interfaces and GPIO pins, supporting multiple external SPI, Dual SPI, Quad SPI, QPI
flash
• Can be used for development solutions: electrical lighting, switch sockets, smart home appliances, industrial
control fields

Espressif Systems 17 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Development Board
• ESP32-C3-DevKitM-1 : ESP32-C3-DevKitM-1 is an entry-level development board, using the ESP32-C3-
MINI-1 module, which is named for its small size. It can be used to flash and experience examples in IDF.

• ESP32-C3-DevKitC-02 : ESP32-C3-DevKitC-02 is an entry-level development board, which can be used to

flash and experience examples in IDF.

• ESP32-C3-DevKit-RUST-1 : ESP32-C3-DevKit-RUST-1 is an entry-level development board, which can be

used to flash and experience examples in IDF.
• ESP32-C3-AWS-ExpressLink-DevKit : ESP32-C3-AWS-ExpressLink-DevKit uses an abstract application
programming interface (API) to connect any host application to AWS IoT Core and its services. It has the
shape of an Arduino expansion board, so it can be directly plugged into a standard Arduino. It can also be used
with Raspberry Pi or any other host.

Espressif Systems 18 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Hardware Design Guide

• ESP32-C3 Hardware Design Guide

Purchase link
• ESP32-C3 Development Board

ESP32

Supported Features:
• Provides multiple GPIO pins, including digital input/output, analog input, PWM output, I2C, SPI, UART, etc.
• Development plan: Recommend using the latest released ESP32-S3

Development Boards
• ESP32-DevKitC : ESP32-DevKitC V4 is a small development board based on ESP32, which can be used to
flash and experience examples in IDF.
• ESP-EYE : ESP-EYE is a development board aimed at the face recognition and voice recognition market,
equipped with a 200 W pixel camera, digital microphone, which can meet various AI application development
needs. In addition, this development board also supports Wi-Fi image transmission, Micro USB debugging
and power supply, can achieve voice wake-up, face detection and recognition functions, and can assist users in
developing highly integrated AI solutions.
• ESP32-LyraT : ESP32-LyraT is designed for the audio application market. It provides an audio codec chip,
onboard dual microphones, headphone output, two 3-watt speaker outputs, dual auxiliary inputs, and lithium
battery charging management hardware support.
• In addition, there are seven other development boards in the ESP32 series for audio processing, but we rec-
ommend developers to use the latest ESP32-S3 series audio development boards.
• ESP32-LCDKit : ESP32-LCDKit is an HMI (Human-Machine Interaction) development board with ESP32-
DevKitC as the core, which can be connected to an external screen and integrates peripherals such as SD-Card,
DAC-Audio, mainly used for HMI related development and evaluation.

Espressif Systems 19 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-Ethernet-Kit : The ESP32-Ethernet-Kit is an Ethernet to Wi-Fi development board that can provide
Wi-Fi connectivity for Ethernet devices. To provide more flexible power options, the ESP32-Ethernet-Kit also
supports Power over Ethernet (PoE).

Hardware Design Guide

• ESP32 Hardware Design Guide

Purchase Link:
• ESP32 Development Board

ESP8266

Supported Features:
• Provides multiple GPIO pins that can be used for various purposes, such as UART, I2C, SPI, etc.
• Development Solution: It is recommended to use the latest released ESP32-C2 or ESP32-C3

Development Board
• ESP8266-DevKitC : The ESP8266-DevKitC is a compact ESP8266 development board that can be used to
flash and experience examples in IDF.

Hardware Design Guide

• ESP8266 Hardware Design Guide

Purchase Link:
• ESP8266 Development Board

2.1.2 Flash Programming

This document shows the hardware and software environment that each ESP chip needs to meet when programming
firmware.

Hardware Requirements for Entering Download Mode on Different ESP Chips

When using a chip or module, please select the corresponding ESP series chip for hardware wiring configuration.

ESP8266
The ESP8266 downloads firmware via UART0 (TX0 (GPIO1) and RXD (GPIO3) ) by default.

Hardware Connection The following wiring conditions need to be satisfied:

Espressif Systems 20 Release master

Submit Document Feedback
Chapter 2. ESP Friends

VDD > 3V3

GND -> GND
EN -> Pull Up (Used for power on, can't be float)
GPIO0 -> Pull Down (Enter download mode)
GPIO15 -> Pull Down
TXD0(GPIO1) -> RX
RXD0(GPIO3) -> TX

Hardware conditions must be met

• ESP8266 chip working voltage range is 2.5 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP8266 modules working voltage range is 2.7 V ~ 3.6 V; if you use a single power supply, the recom-
mended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.

Reference Official Documentation:

• ESP8266 Datasheet
• ESP8266 Hardware Design Guidelines

ESP32
The ESP32 downloads firmware via UART0 (TX0 (GPIO1) and RXD (GPIO3) ) by default.

Hardware Connection The following wiring conditions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO0 -> Pull Down (Enter download mode)
GPIO2 -> Pull Down (Default is lw level)
TXD0(GPIO1) -> RX
RXD0(GPIO3) -> TX

Note:
• The Strapping pin GIO12(MTDI) is used for selecting the VDD_SPI Flash voltage.
– When use the 1.8V VDD_SPI Flash , the GIO12(MTDI) need pull up when chip power on.
– When use the 3.3V VDD_SPI Flash , the GIO12(MTDI) need pull down when chip power on.

Hardware conditions must be met

• ESP32 chip working voltage range is 2.3 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.

Reference Official Documentation:

• ESP32 Datasheet
• ESP32 Hardware Design Guidelines

ESP32-S2
The ESP32-S2 supports two ways to download the firmware: UART0 and USB.

Espressif Systems 21 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Hardware Connection When you are use the UART0 pins to download the firmware ,the following wiring condi-
tions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on, can't be float)
GPIO0 -> Pull Down (Enter download mode)
GPIO46 -> Pull Down
TXD0(GPIO43) -> RX
RXD0(GPIO44) -> TX

When you are use the USB pins to download the firmware ,the following wiring conditions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on, can't be float)
GPIO0 -> Pull Down (Enter download mode)
GPIO46 -> Pull Down (Default is Low level)
GPIO19 -> USB_D-
GPIO20 -> USB_D+

Note:
• The Strapping pin GIO45 is used for selecting the VDD_SPI Flash voltage.
– When use the 1.8V VDD_SPI Flash , the GIO45 need pull up when chip power on.
– When use the 3.3V VDD_SPI Flash , the GIO45 need pull down when chip power on.
• The strapping combination of GPIO46 = 1 and GPIO0 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-S2 chip working voltage range is 2.8 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32-S2 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or
more.

Reference Official Documentation:

• ESP32-S2 Datasheet
• ESP32-S2 Hardware Design Guidelines

ESP32-C3
The ESP32-C3 supports two ways to download the firmware: UART0 and USB.

Hardware Connection When you are use the UART0 pins to download the firmware ,the following wiring condi-
tions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO2 -> Pull Up (Controls the SPI Flash startup mode)
GPIO8 -> Pull Up
GPIO9 -> Pull Down (Enter download mode)
TXD0(GPIO21) -> RX
RXD0(GPIO20) -> TX

When you are use the USB pins to download the firmware ,the following wiring conditions need to be satisfied:

Espressif Systems 22 Release master

Submit Document Feedback
Chapter 2. ESP Friends

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO2 -> Pull Up (Controls the SPI Flash startup mode)
GPIO8 -> Pull Up
GPIO9 -> Pull Down (Enter download mode)
GPIO18 -> USB_D-
GPIO19 -> USB_D+

Note:
• After powering up the chip/module, you can verify whether it has entered Download Boot mode by using
the UART0 serial port.
• The strapping combination of GPIO8 = 0 and GPIO9 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-C3 chip working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32-C3 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or
more.

Reference Summary of Hardware Wiring Principles:

• The hardware conditions for the ESP32-C3 chip to enter the Download Mode
• ESP32C3 USB & UART Download Mode

• ESP32-C3 Datasheet
• ESP32-C3 Hardware Design Guidelines

ESP32-S3
The ESP32-S3 supports two ways to download the firmware: UART0 and USB.

Hardware Connection When you are use the UART0 pins to download the firmware ,the following wiring condi-
tions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on, can't be float)
GPIO0 -> Pull Down (Enter download mode)
GPIO46 -> Pull Down
TXD0(GPIO43) -> RX
RXD0(GPIO44) -> TX

For more details, please refer to the wiring diagram below:

Espressif Systems 23 Release master

Submit Document Feedback
Chapter 2. ESP Friends

When you are use the USB pins to download the firmware ,the following wiring conditions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on, can't be float)
GPIO0 -> Pull Down (Enter Download Mode)
GPIO46 -> Pull Down (Default is Low level)
GPIO19 -> USB_D-
GPIO20 -> USB_D+

Note:
• The Strapping pin GIO45 is used for selecting the VDD_SPI Flash voltage.
– When use the 1.8V VDD_SPI Flash , the GIO45 need pull up when chip power on.
– When use the 3.3V VDD_SPI Flash , the GIO45 need pull down when chip power on.
• The strapping combination of GPIO46 = 1 and GPIO0 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-S3 chip working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32-S3 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or
more.

Reference Official Documentation:

• ESP32-S3 Datasheet

Espressif Systems 24 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• ESP32-S3 Hardware Design Guidelines

ESP32-C2
The ESP32-C2 downloads firmware via UART0 (TXD (GPIO20) and RXD (GPIO19) ) by default.

Hardware Connection The following wiring conditions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO8 -> Pull Up (Default is float)
GPIO9 -> Pull Down (Default is high level)
TXD0(GPIO20) -> RX
RXD0(GPIO19) -> TX

Note:
• After powering up the chip/module, you can verify whether it has entered Download Boot mode by using
the UART0 serial port.
• The strapping combination of GPIO8 = 0 and GPIO9 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-C2 chip working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32-C2 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or
more.

Reference Summary of Hardware Wiring Principles:

• The hardware conditions for the ESP32-C2 chip to enter the Download Mode
Official Documentation:
• ESP32-C2 Datasheet
• ESP32-C2 Hardware Design Guidelines

ESP32-H2
The ESP32-H2 supports two ways to download the firmware: UART0 and USB.

Hardware Connection When you are use the UART0 pins to download the firmware ,the following wiring condi-
tions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO8 -> Pull Up (Default is float)
GPIO9 -> Pull Down (Default is high level)
TXD0(GPIO24) -> RX
RXD0(GPIO23) -> TX

When you are use the USB pins to download the firmware ,the following wiring conditions need to be satisfied:

Espressif Systems 25 Release master

Submit Document Feedback
Chapter 2. ESP Friends

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO8 -> Pull Up (Default is float)
GPIO9 -> Pull Down (Default is high level)
GPIO26 -> USB_D-
GPIO27 -> USB_D+

Note:
• After powering up the chip/module, you can verify whether it has entered Download Boot mode by using
the UART0 serial port.
• The strapping combination of GPIO8 = 0 and GPIO9 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-H2 chip working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 350 mA or more.
• ESP32-H2 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 350 mA or
more.

Reference Summary of Hardware Wiring Principles:

• The hardware conditions for the ESP32-H2 chip to enter the Download Mode
Official Documentation:
• ESP32-H2 Datasheet
• ESP32-H2 Hardware Design Guidelines

ESP32-C6
The ESP32-C6 supports two ways to download the firmware: UART0 and USB.

Hardware Connection When you are use the UART0 pins to download the firmware ,the following wiring condi-
tions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO8 -> Pull Up (Default is float)
GPIO9 -> Pull Down (Default is high level)
TXD0(GPIO16) -> RX
RXD0(GPIO17) -> TX

When you are use the USB pins to download the firmware ,the following wiring conditions need to be satisfied:

VDD -> 3V3

GND -> GND
EN -> Pull Up (Used for power on Control, can't be float)
GPIO8 -> Pull Up (Default is float)
GPIO9 -> Pull Down (Default is high level)
GPIO12 -> USB_D-
GPIO13 -> USB_D+

Note:

Espressif Systems 26 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• After powering up the chip/module, you can verify whether it has entered Download Boot mode by using
the UART0 serial port.
• The strapping combination of GPIO8 = 0 and GPIO9 = 0 is invalid and will trigger unexpected behavior.

Hardware conditions must be met

• ESP32-C6 chip working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the recommended
voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or more.
• ESP32-C6 modules working voltage range is 3.0 V ~ 3.6 V; if you use a single power supply, the
recommended voltage of the power supply is 3.3 V, and its recommended output current is 500 mA or
more.

Reference Summary of Hardware Wiring Principles:

• The hardware conditions for the ESP32-C6 chip to enter the Download Mode
Official Documentation:
• ESP32-C6 Datasheet
• ESP32-C6 Hardware Design Guidelines

Selecting the Suitable Flashing Platform

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Espressif officially provides the following flashing methods for different needs:
1. Quick Firmware Testing: ESP LAUNCHPAD Quick Firmware Flashing
• Advantage: Simple and fast, no need to set up an environment or additional tools, firmware can be easily
flashed through the Web interface
2. Non-developers performing flashing: Flash Download Tool Flashing
• Advantage: Provides a graphical interface, no need to understand command line operations in depth, also
suitable for automated deployment and batch production flashing
3. Professional developers for comprehensive firmware development: IDE Flashing
• Advantage: Integrated Development Environment (IDE) provides an intuitive user interface and toolset,
supports firmware development, debugging and integrated flashing
4. Professional developers for comprehensive firmware development and more detailed configuration: IDF
Terminal Flashing
• Advantage: Allows developers to precisely manage projects, including firmware parameter settings. Con-
venient for flashing during development and debugging to quickly verify changes

Preparation

Espressif Systems 27 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Note: If you haven t selected a suitable development board for your project yet, please refer to Board
selection
For the differences between chips, modules, and development boards, please refer to Chips, Modules,
Development Boards

Using the Development Board You can flash by connecting the USB or UART interface with a data cable.

Note: Some development boards use the USB Type C interface. Please make sure to use the appropriate data cable.

Using the Chip or Module Espressif chips generally have two modes:
1. Firmware Flashing Mode: The chip will wait to receive firmware from the serial port for flashing. Usually, a
flashing tool is needed to send firmware data
2. Normal Operating Mode: This is the normal working mode of the chip, it will load and run the firmware from
the Flash storage
To use the chip or module, you need to enter the flashing mode by setting the status of specific pins, and flash through
the UART0 or USB peripheral.

Note: Specific pin information should be referenced from the corresponding chip s technical datasheet, which can
be found on the Espressif official website.

ESP LAUNCHPAD Quick Firmware Flashing ESP LAUNCHPAD is a platform that allows developers to
quickly experience the features of Espressif chips.
• After selecting some example firmware provided by Espressif, you can directly flash it on the web page

Espressif Systems 28 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Developers can also upload their compiled .bin files and flash them on the web page

ESP LAUNCHPAD Flashing Process The following uses ESP-BOX as an example:

Open the website ESP LAUCHPAD
1. Click on the top right Connect
2. In the pop-up window, select the Port to connect to the ESP-BOX
3. Click Connect below

4. Select the firmware to be flashed to the ESP-BOX

5. Select ESP Chipset Type as ESP32-S3

6. Click the bottom left Flash button to start flashing
7. After the flashing starts, it will jump to the console interface, if correct, the flashing progress will be displayed

Espressif Systems 29 Release master

Submit Document Feedback
Chapter 2. ESP Friends

8. After the flashing is completed, press the top left Reset Device button, or click Disconnect in the top right
corner.

Flash Download Tool Flashing The Flash Download Tool is a tool developed by Espressif for flashing firmware
to its ESP series chips, used to load pre-compiled firmware files into the chip s flash memory, enabling the chip to
correctly run applications or firmware.
• Download Flash download tool

Using the Flash download tool Flashing Process

1. Run the .exe file of flash_download_tool
2. Select Development Board (ChipType) as the corresponding development board, there will generally be a
mark on the chip. Select Flashing Mode (LoadMode) as UART and then click OK below

Espressif Systems 30 Release master

Submit Document Feedback
Chapter 2. ESP Friends

3. Click to select the .bin file to be flashed

4. Enter the address offset to be flashed, you can default to the starting position 0x0
5. Select the COM port connected to the development board
6. Click START at the bottom left to start flashing

Espressif Systems 31 Release master

Submit Document Feedback
Chapter 2. ESP Friends

7. The interface will display a blue FINISH after the flashing is completed

Use Flash download tool for Flash encryption and secure boot
1. Disable all secure boot and Flash encryption configurations in menuconfig to ensure that plaintext firmware
can be generated after compilation
2. Adjust the offset of the default partition table (Offset of partition table), adjust from 0x8000 to 0xa000

Note: Flash encryption will increase the size of the bootloader .bin firmware, so you must leave

Espressif Systems 32 Release master

Submit Document Feedback
Chapter 2. ESP Friends

enough space for the offset address

3. Open the folder of Flash Download Tool, open configure -> esp chip type -> security.conf. Enable the
following configurations and save the file:

[SECURE BOOT]
secure_boot_en = True
[FLASH ENCRYPTION]
flash_encryption_en = True
reserved_burn_times = 3
[ENCRYPTION KEYS SAVE]
keys_save_enable = True
encrypt_keys_enable = False
encrypt_keys_aeskey_path =
[DISABLE FUNC]
jtag_disable = False
dl_encrypt_disable = False
dl_decrypt_disable = False
dl_cache_disable = False

4. Restart Flash Download Tool

5. Add the generated plaintext firmware to the Flash Download Tool and set the corresponding offset address
6. Use the Flash Download Tool to flash the .bin plaintext firmware according to the above Using the Flash
download tool Flashing Process, the encryption key will be saved locally

IDE Flashing After setting up the development environment, you can use the ESP-IDF plugin in the IDE to build
and flash.
• Choose an instance project of interest from esp-iot-solution or the built-in examples of ESP-IDF.

Note: For environment setup, refer to: VSCode ESP IDF Extension

We can experience the flashing process of ESP32-S3-BOX, this project uses ESP32-S3-BOX as a USB speaker.

Take VSCode as an Example:

1. Enter the path where you want to save the project in VSCode, and select Terminal -> New Terminal in the
upper left window
2. Use git clone to download the code of this project

git clone --recursive https://github.com/espressif/esp-box.git

3. Open VSCode, select file -> open folder (or use the shortcut Ctrl + K, Ctrl + O) in the upper left window to
enter the path where the project is saved -> esp-box -> examples -> usb_headset. Click to select the folder.
4. Connect the ESP-BOX to the computer via a data cable

Espressif Systems 33 Release master

Submit Document Feedback
Chapter 2. ESP Friends

5. Select the corresponding COM port in the lower left corner

Note: If the COM port is not detected, hold down the Boot key and the Reset key of the devel-
opment board at the same time to enter the download mode

6. Select Target as esp32s3, VSCode selects ESP32-S3 chip (via ESP-PROG) at the top of the interface
7. Click the ESP-IDF Build Project icon, after successful compilation, it will display:

8. Click the ESP-IDF Flash device icon to flash, then select UART at the top of the VSCode interface. After
successful flashing, it will display in the terminal: Flash Done ⚡
9. After pressing the Reset button on the development board, you can use the ESP-BOX to play sound via USB

IDF Terminal Flashing Using the IDF terminal has advantages such as stable environment, easy version switching,
and full advanced features.

Note: For environment setup, you can refer to: Windows Installation Guide.

The following will introduce how to use the IDF terminal to flash an example project:
1. Open the ESP-IDF CMD terminal window, the interface of successful installation of ESP-IDF SDK is shown
as follows:

2. Use the cd command to enter a project, for example:

Espressif Systems 34 Release master

Submit Document Feedback
Chapter 2. ESP Friends

3. Switch to the correct chip environment, for example:

idf.py set-target esp32

Note: Replace esp32 with the correct chip target

4. Run the following command to build the project:

idf.py build

5. Run the following command to flash the project, replace PORT with the serial name of the development board:

idf.py -p PORT flash

Note: Using idf.py flash will attempt to automatically connect using the available serial
port

The interface of successful flashing is shown as follows:

Mass Production Flashing

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

The Flash Download Tool Flashing in conjunction with Espressif s official flashing accessories can be used for
automated deployment and mass production flashing.
• Flashing baseboard (one module flashed at a time)
• Fixture (4 modules flashed at once)

Flashing process using Espressif s official fixture

1. Relay power supply
The adapter is connected as shown in the figure to power the relay; the relay serves as a delay to
ensure that the module is powered on after the fixture handle is pressed down stably.

Espressif Systems 35 Release master

Submit Document Feedback
Chapter 2. ESP Friends

2. The fixture baseboard serial port is connected to the computer through the HUB
Use a USB cable to connect the 4 mini USBs on the two baseboards under the fixture box to the
HUB. The HUB needs to be independently powered to ensure that each serial port provides sufficient
power to the module; then connect the HUB to the computer. (The fixture can be connected to the
computer for single serial port download)

Espressif Systems 36 Release master

Submit Document Feedback
Chapter 2. ESP Friends

3. Download
Select the firmware to be downloaded, set the serial port; place the modules in the four positions on
the fixture, press down the handle, and click START to start downloading. For detailed steps, refer
to: Using the Flash download tool Flashing Process

Production Test Reference Materials

• Production Testing Guide
• Production Testing Tool

2.1.3 Environment Setup

Espressif Systems 37 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Espressif officially supports two types of development environments: ESP-IDF and Arduino IDE.

ESP-IDF

• ESP-IDF is an official development framework launched by Espressif, supporting Windows, Linux, and macOS
operating systems.
• Development is conducted via command-line interface, enabling tasks such as configuration, compilation, flash-
ing, and serial monitoring.
• For developers who prefer graphical interfaces, Espressif also provides plugins for VSCode and Eclipse,
allowing development within the IDE s graphical environment.

Arduino IDE

• The Arduino IDE is a versatile integrated development environment. It provides a specialized core for ESP
series chips, encapsulating part of the ESP-IDF functions.
• It allows developers to utilize Arduino s simpler C++ programming language to develop ESP series chips.
• Developers do not need to have an in-depth understanding of the IDF details, making embedded programming
more accessible, especially for beginners.

Selecting the Appropriate Development Environment For beginners and developers seeking simple and fast
development:
• Arduino IDE is an excellent choice. Its user-friendly interface and basic functionalities allow for easy onboard-
ing.
For developers with some programming experience:
• Visual Studio Code with the ESP-IDF plugin is a good choice. This combination provides a more friendly
interface and automated configuration, making complex project development easier.
For advanced developers or professional developers familiar with Eclipse IDE:
• The ESP-IDF plugin for Eclipse will provide more flexibility and powerful features.
• Espressif-IDE provides a convenient ESP development environment.
For developers familiar with using the command line and seeking comprehensive features:
• ESP-IDF command line is a suitable choice. It is the official framework provided by Espressif, offering the
most complete set of features to meet the needs of developers for complex embedded solutions.

ESP-IDF and Espressif Chips

Espressif Systems 38 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Click the title link to view the latest IDF version support information.

Official Development Environment Comparison

Arduino IDE

Suitable for:
• Beginners, entry-level developers, and users seeking simple and fast development
Advantages:
• Easy configuration and setup process
• Provides an intuitive user interface and simplified workflow, making it easy to write and upload
code, which is convenient for rapid prototyping.
• Provides a wide range of libraries and ready-made codes, which are very convenient for rapid
prototype validation and simple projects.
• Arduino IDE is easy to operates on multiple operating systems, including Windows, Mac, and
Linux.
• Arduino IDE has extensive of documentation and tutorials for reference, making it easier to solve
problems when encountered.
Disadvantages:
• Limited advanced features, cannot modify the underlying code. In complex ESP-IDF projects,
using the original ESP-IDF development toolchain and command line tools can be more flexible.
• Limited debugging features. In complex ESP-IDF projects, other debugging tools are needed.
How to install:
• Document Install ESP32 Arduino Software Development Environment on Windows

ESP-IDF Command Line

Suitable for:
• Advanced developers. Developers with rich embedded system development experience, who have
a certain understanding of embedded system concepts, low-level programming, and hardware-
related knowledge. Developers who prefer or are interested in using command-line development
environments.
Advantages:
• Provides a command-line based development environment using CMD or PowerShell, offering
higher stability and flexibility.
• Developers can use scripts and command line tools in the command line development environment
to batch build, test, and deploy applications, thereby improving development efficiency.
• The command line development environment is usually more lightweight and consumes less system
resources. This makes it more suitable for development in resource-constrained embedded systems.
• Easy to install, with an official Windows one-click installation tool to quickly set up the environ-
ment.
Disadvantages:
• The command line development environment requires developers to have some knowledge of
command-line and script programming. This presents a higher learning curve for beginners.
• Lack of graphical interface, which may not be as user-friendly and intuitive as a graphical interface.
Not convenient for direct development.
• Need to edit code in other IDEs.
How to install:
• Windows One-click Installation Tool

Espressif Systems 39 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Document Windows Installation Tutorial

• Document Linux and macOS Platform Tutorial
• Video Tutorial Quickly Set Up ESP-IDF Development Environment on Windows Using One-
Click Installation Tool

Visual Studio Code Extension

Target Audience:
• Developers with some embedded development experience who are already using or prefer to use
VSCode as their main development environment.
Advantages:
• Integrates the ESP-IDF with VSCode, providing developers with the convenience of developing,
building, and debugging ESP-IDF projects within the same interface.
• Offers simplified configuration features. Developers can easily configure project parameters, com-
pilation options, and debugging settings, etc., through the plugin s configuration interface. This
makes configuring the ESP-IDF environment and projects more straightforward and intuitive.
• VSCode is a relatively lightweight editor with fast startup speed and relatively low system resource
consumption.
Disadvantages:
• Developers who are not familiar with VSCode or plugin development may need extra learning and
adaptation.
• There may be limitations due to updates to the plugin itself and compatibility with new versions of
ESP-IDF. Developers may need to monitor plugin updates and related documentation.
• Many functionalities depend on plugins.
How to Install:
• English Document Visual Studio Code Extension Installation Tutorial
• Video Tutorial Quickly Set Up ESP-IDF Development Environment Using VS Code (Windows,
Linux, MacOS)

Espressif-IDE or Eclipse Plugin

Note: Espressif-IDE comes with IDF Eclipse Plugin, basic Eclipse CDT plugins, and other third-party
plugins of the Eclipse platform to support the building of ESP-IDF applications.

Target Audience:
• Advanced and professional developers. Developers with embedded system development experience
who are already using or prefer to use Eclipse.
Advantages:
• Integrates the ESP-IDF framework with Eclipse, providing developers with the convenience of
developing, building, and debugging ESP-IDF projects under the same interface.
• Offers superior support for complex large-scale projects.
• Eclipse IDE has a vast ecosystem of plugins, allowing developers to install and use other useful
plugins according to project requirements, thereby enhancing development efficiency.
• It possesses powerful graphical debugging capabilities.
Cons:
• Compared to the aforementioned lightweight development environments or pure command-line
environments, Eclipse IDE itself may consume more system resources, especially on lower-
performance computers, it may feel slower.

Espressif Systems 40 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Eclipse is relatively complex in terms of environment configuration, and it is not very friendly to
beginners.
• Eclipse has a fairly large user community, but it is smaller compared to other environments.
How to install:
• Document Espressif-IDE
• Document Eclipse Plugin Tutorial
• English Document Eclipse Plugin Windows Installation Tutorial
• Video Tutorial Eclipse Plugin Tutorial (English)

Note: For issues with environment setup, you can refer to csdn blog

The choice of the appropriate development environment depends on your level of experience, project
complexity, and personal preference. Beginners can start with Arduino IDE, then gradually transition
to the plugin-equipped VSCode environment. Experienced developers can directly use ESP-IDF or use
the ESP-IDF plugin in Eclipse for more complex project development.

Other Development Environments

1. MicroPython
MicroPython is a highly simplified interpreter based on Python, designed specifically
for embedded systems. It allows developers to use the familiar Python language for embedded
development, making programming simpler and more efficient. MicroPython can run on a
variety of hardware platforms, including ESP series chips.
2. PlatformIO IDE
PlatformIO is a cross-platform open-source ecosystem that supports multiple hardware
platforms and development boards, and provides a unified development environment, allow-
ing developers to use different hardware and development boards for embedded develop-
ment. PlatformIO integrates multiple development tools, including compilers, debuggers,
and upload tools.
3. CLion
CLion is an IDE developed by JetBrains, designed specifically for developers of C and C++
programming languages. It provides intelligent code completion, syntax highlighting, code
navigation, powerful refactoring capabilities, and debugging tools to enhance developer effi-
ciency. CLion also integrates version control systems, such as Git, making team collaboration
more convenient.

Attention: MicroPython, PlatformIO, and CLion are platforms that are not directly developed by
Espressif, so Espressif does not maintain issues related to these development environments. There-
fore, users may encounter difficulties during use, and developers will need to seek support and solu-
tions from relevant communities and forums.

Third-Party Reference Materials

Arduino Windows
• Video Arduino ESP32 Environment Setup Guide

Arduino Ubuntu
• Video ESP32 Development Environment Setup (Arduino)

Espressif Systems 41 Release master

Submit Document Feedback
Chapter 2. ESP Friends

VSCode
• Video ESP32-IDF Environment Setup with VSCode
• Video VSCode + ESP-IDF Development Environment Setup (Implementing Step-by-Step Debugging)

Eclipse
• English Video Install ESP32 + Eclipse IDE 2020 (English)

2.1.4 Getting Started with Project Development

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

When developing an ESP project, the typical process begins with understanding the relevant ESP examples and SDK
based on the project s requirements. The next step is to select the most suitable example as a template for the target
project, and then modify it to create your own project.
This article will summarize essential knowledge required for developing general embedded projects within the Espres-
sif environment:
• General Knowledge
• Understanding ESP Series Chips and ESP-IDF Framework
• Summary of Project Development Knowledge Points
• Learning Methods

General Knowledge

Before developing an ESP project, some key general knowledge and skills are needed to ensure smooth development:
• Git:
Git is an open-source distributed version control system used to track code changes and collaborative
development. Using Git in your project can help you manage your code effectively, control versions,
and work collaboratively with team members. Learning how to use Git for code submission, branch
management, merging, etc., is a basic requirement for developing ESP projects. Here, developers
are recommended to master some common Git commands
• FreeRTOS:
FreeRTOS is an open-source real-time operating system widely used in embedded systems and
microcontroller projects. ESP series chips all support FreeRTOS, and often use it to implement
multitasking and real-time scheduling. Understanding the concepts of FreeRTOS task scheduling,
message queues, semaphores, etc., is essential knowledge for developing ESP projects.
– Developers can learn from the official FreeRTOS getting started guide.
– Learn how to use FreeRTOS in the ESP-IDF environment in the FreeRTOS section of the
ESP-IDF Programming Guide.
• Linux (optional):
ESP project development often takes place on the Linux operating system, as Linux provides a
wealth of tools and command-line environments suitable for embedded development. Developers
should understand the basic commands and usage of Linux, such as file operations, directory man-
agement, process management, etc., in order to debug and configure during development. Devel-
opers are recommended to master some common Linux file and directory management commands

- ls: Lists files and folders in the current directory.

- cd <directory>: Switches to the specified directory.
- pwd: Displays the path of the current working directory.
- cp <source> <destination>: Copies files or directories.
(continues on next page)

Espressif Systems 42 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

- rm <file_name>: Deletes a file.
- mkdir <directory>: Creates a new directory.
- rmdir <directory>: Deletes an empty directory.
- cat <file_name>: Displays the contents of a file.

Understanding ESP Series Chips and ESP-IDF Framework

• For the features and functions of ESP chips, refer to: Board selection
• Introduction and Management of ESP-IDF Versions
• Composition and Architecture of the ESP-IDF Framework
• Setting and Configuring the Development Environment
• Using ESP-IDF Tools
• Using ESP-IDF API and Guide to ESP-IDF API Usage
• Security Features of ESP Chips

Recommended Websites:
• ESP-IDF Quick Start
• ESP-IDF Programming Guide

Summary of Project Development Knowledge Points

C Language
1. Data Types
• Basic Data Types
– Integer, Character, Floating Point
• Standard Library Data Types
– Boolean (bool), String (string)
• Pointer Types
• Composite Data Types
– Array, Structure (struct), Enumeration (enum)
• Custom Data Types
• Data Type Qualifiers
– const, volatile
2. Functions, Pointers, and Memory Management
3. Compilation, Linking, and Execution Process of Engineering Projects
4. Algorithms
• Data Structures
– Linked List
– Stack and Queue
– Tree and Graph
• Sorting Algorithms
– Bubble Sort
– Selection Sort
– Insertion Sort
– Quick Sort
– Merge Sort
• Search Algorithms
– Linear Search
– Binary Search
– Hashing
• Recursive Algorithms
– Divide and Conquer
– Backtracking

Espressif Systems 43 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Dynamic Programming
• Encoding and Decoding Algorithms
– Handling Data Compression, Encryption, Encoding, and Decoding
• Signal Processing Algorithms
– Processing of audio and images
• Algorithm optimization
– Time complexity
– Space complexity

Communication Protocols
1. Master various communication protocols, such as UART, SPI, I2C, CAN, etc., for communication with ex-
ternal devices
2. Learn network protocol stacks, such as TCP/UDP, as well as higher-layer application protocols, such as HTTP,
MQTT, etc.

Project Building and Management

1. Build System
2. Partition Table
3. Component Management and Usage

Application Programming
1. GPIO (General Purpose Input/Output), General Input/Output
• GPIO initialization, mode, reading, writing
• GPIO configuration options
– Determine the function of each pin according to the datasheet and pin diagram
• GPIO interrupts
• Strapping pins
2. JTAG (Joint Test Action Group) Debugging
3. Memory Management
• Dynamic memory allocation and release, such as malloc and free
• Memory layout and stack management
4. Interrupt Handling
• Understand and handle hardware interrupts
• Implement Interrupt Service Routines (ISR) to respond to external events
5. Clocks and Timers
• Use timers and clock sources to implement time control and timed tasks
• Handle delay and timing operations
6. Exception Handling
• Handle hardware and software exceptions
7. Low Power Mode Design
• Implement power optimization strategies to extend battery life or reduce energy consumption
8. Processes
• Creation and termination of processes
• Management and scheduling of processes
• Resource allocation and usage of processes
• Methods of inter-process communication
– Pipes, Named Pipe (FIFO), Message Queue, Signal, Shared Memory, Semaphore, Socket
9. Threads
• Creation and destruction of threads
• Scheduling and synchronization of threads
• Concurrency control in multithreaded programming
• Methods of inter-thread communication
– Mutex, Condition Variable, Semaphore, Barrier, Message Queue, Shared Memory, Spin
Lock

Espressif Systems 44 Release master

Submit Document Feedback
Chapter 2. ESP Friends

10. Driver Development

• Drivers can be written for various hardware devices, including but not limited to sensor, actuator, storage
devices (such as flash memory and SD cards), communication interfaces (such as UART, SPI, I2C),
display, network interface card (NIC), etc.

Learning Methods

• Online resources and documents:

– Utilize the ESP-IDF official documentation, tutorials, and example codes to gain a deep understanding
of the framework and API usage.
– Find ESP-IDF based solutions, application examples, components, and drivers in the ESP IoT Solution
library. Most documents provide both Chinese and English versions.
• Online courses and video tutorials:
– Learn relevant knowledge and practical skills by participating in online courses and video tutorials on
ESP chip and ESP-IDF development.
• Experiments and projects:
– Deepen your understanding of hardware and software by using ESP development boards for experiments
and project development. Beginners can learn from other completed projects or solutions released by
Espressif.
• Community and forums:
– Join the ESP32 official forum, CSDN forum, or other developer communities. Exchange experiences
with other developers, seek help, and share projects and solutions.
– Submit bugs or feature requests through the Issues section on GitHub. Please check the existing Issues
before submitting new ones.
• Reference books:
– Read books related to embedded systems, C language, and ESP chip development to expand your knowl-
edge breadth and depth. Reference: ESP32 book list.
Continuous practice and project development are the most important parts of the learning process. Developers can
gradually master the skills of embedded project development with ESP chips through continuous practice and practical
application.

2.2 Advanced Development

This section is suitable for developers who wish to gain a deeper understanding and mastery of more advanced
programming techniques. We will introduce some more complex development techniques, including component
management, code debugging, etc., and this section will provide in-depth guidance.

2.2.1 Component Management and Usage

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Imagine you are developing a complex application that involves multiple functional modules, such as network com-
munication, sensor reading, and screen driving. If you write all functions in one large file, the code will become
lengthy and difficult to maintain. At this point, components play a role in modularization.
Each component focuses on a specific functional area, so each component can be developed, tested, and maintained
separately. By breaking down functions into components, you can reuse these functions in multiple projects without
having to rewrite code. This not only saves development time but also improves development efficiency. The structure
of the project will also become clearer.

Espressif Systems 45 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Finding Components
• Adding Components with Component Manager
• Using Local Components
• Pulling Components from Git Repository
• Updating Components
• Deleting Components
• Developing Components (Advanced)
• Releasing Component

IDF Components

ESP-IDF components are reusable code packages that are compiled into static libraries during build and can be linked
by other components or applications. This allows them to be used in multiple projects.
A complete component generally includes:
• Source code
• Header files
• CMakeLists.txt
– Defines source code and header files
– Defines dependencies
– Registers components
– Configures optional features
– CMake build description file, used to describe the build configuration and dependencies of the component,
instructing the compiler how to compile, link, and build the component.
• idf_component.yml
– Component manager description file, which lists the other components to be referenced and their version
information. In this way, when building a project, the ESP-IDF component manager will automatically
download and integrate the required components according to these descriptions to ensure that the project
s dependencies are met.

Component Dependencies

When compiling each component, the ESP-IDF system will recursively evaluate its dependencies. This means that
each component needs to declare the components it depends on, i.e., requires .
A dependency refers to other software libraries, modules, or components that a software project depends on. These
dependencies are necessary for building and running the project. Software projects often use existing code or libraries
to implement specific functions or provide certain services, rather than writing all the code from scratch. These
external codes or libraries are the dependencies of the project.
The role of dependencies is to promote code reuse, reduce development costs, speed up development, and improve
software quality. Using existing dependencies can avoid reinventing the wheel.
Common dependencies include:
• Third-party libraries
• Frameworks and components
• Runtime environment

Finding Components

1. IDF includes some basic functional components, which can be found in the components directory
2. idf-extra-components includes some IDF supplementary components
3. esp-iot-solution provides some peripheral driver components
4. Components maintained by Espressif and those uploaded by third parties can be found in the esp-registry.
5. Searching for third-party component libraries

Espressif Systems 46 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Component Manager

The Component Manager refers to the tool or system used for managing components. In IDF, the Component
Manager provides a set of commands for adding, removing, downloading, and managing components, so as to reuse
existing functional modules in the project.

Adding Components with Component Manager

1. Find the components needed for the project in the esp-registry.

2. Use the terminal to enter the root folder of the project directory and execute idf.py add-dependency
"[namespace]/<component name>[version number]".
• This command will automatically add an entry to main/idf_component.yml, and if the file does
not exist, it will be created automatically.
• Namespace: Optional, default from espressif (case insensitive)
• Component name: Required, the name of the component, for example usb_stream (case insensitive)
• Version number: Optional, default is * representing any version. When adding a component for the first
time, the latest version will be downloaded automatically.
3. Execute idf.py build

Note:
• No need to make additional modifications to the project CMakeLists.txt, you can directly include the public
header files of the component in the project source code, compile and link the static library of the component.
• Users cannot directly modify the components in managed_components, because the Component Manager will
automatically detect the component Hash value and restore changes.
• In addition to using the command idf.py add-dependency, users can also directly modify the
idf_component.yml file and manually modify the component entries.

Using Local Components

In the Component Manager description file idf_component.yml, add the local component address as shown in
the example below.

dependencies:
idf: ">=4.4.1"
cmake_utilities: "0.*"
iot_usbh_modem:
version: "0.1.*"
override_path: "../../../../../components/usb/iot_usbh_modem"

Pulling Components from Git Repository

In the Component Manager description file idf_component.yml, add the component s address on Github as
shown in the example below.

dependencies:
esp-gsl:
git: https://github.com/leeebo/esp-gsl.git
version: "*"
button:
git: https://github.com/espressif/esp-iot-solution.git
path: components/button
version: "*"

Espressif Systems 47 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Updating Components

1. Modify the component version in the component manager description file idf_component.yml to the
target version you want to update to
2. Delete managed_components and dependencies.lock in the project file
3. Execute idf.py build or manually execute idf.py reconfigure

Deleting Components

1. Delete the component entry in idf_component.yml

2. Delete build, managed_components and dependencies.lock
3. Execute idf.py build

Developing Components (Advanced)

1. Create a component directory, consistent with ESP-IDF component requirements, and write the corresponding
CMakeLists.txt file
2. Add idf_component.yml file, add component information, IDF version requirements, specify dependent
other components
3. Add license.txt file, add license information of the component. The license information is used to explic-
itly inform other developers or users of the terms and conditions that need to be complied with when using this
component. This can ensure that the use and distribution of the component is legal, and clarify the copyright
and authorization status of the component author for his work. The license information is generally contained
in a file named license.txt or LICENSE, which includes the following content:
• License type: Explicitly specify the license type of the component, such as MIT license, Apache license,
GPL license, etc. Different types of licenses have different terms and conditions, and developers and
users need to comply with the corresponding license regulations.
• Copyright information: Indicate the copyright ownership of the component, that is, the author or copy-
right holder of the component. Copyright information usually includes the author s name, organization
or company name, and copyright year.
• Disclaimer: May contain a disclaimer, stating that the author or copyright holder of the component does
not assume any liability for any loss or liability that may be caused by the use of the component.
• Permissions and restrictions: Explicitly specify under what conditions the component can be used and
distributed, as well as prohibited behaviors or restrictions.
• Open source license: If the component is open source software, the license information should contain
the corresponding open source license terms, such as the rules for sharing, modifying, and distributing
open source code.
4. Add README.md file, add a brief introduction of the component, simple usage instructions
5. Add CHANGELOG.md file, add the version update record of the component
• A document used to record the version update record of the component. It usually contains the changes,
improvements, fixes, and new features of each version of the component. Developers and users can
understand the version update history of the component by referring to the CHANGELOG.md file, so as
to better understand the development and use of the component.
6. Add test_apps directory, add test cases of the component
• The component s self-check tool, which can ensure the quality and stability of the component, is very
important for the development and maintenance of the component
• It contains applications that test different aspects or functions of the component
7. Add examples directory
• Provide example code for the component to demonstrate the basic usage and functions of the component
• Or specify the examples path in idf_component.yml, add example code of the component

Releasing Component

Release on ESP-Registry ESP-Registry is a central repository provided by Espressif, offering developers a con-
venient way to discover and download components for their engineering projects.

Espressif Systems 48 Release master

Submit Document Feedback
Chapter 2. ESP Friends

1. Register an account on ESP-Registry - You can complete the registration on ESP-Registry by authorizing with
your Github account
2. After registering, click on the username in the top right corner and select Tokens
3. On this page, click Create to create a Token
4. Register the newly created Token to the environment variable IDF_COMPONENT_API_TOKEN
5. Use the idf.py upload-component command to upload components to the ESP component registry
- idf.py upload-component --namespace [YOUR_NAMESPACE] --name test_cmp -
YOUR_NAMESPACE: ESP-Registry username, which can be seen in the profile - test_cmp: The name of
the component to be uploaded
6. After the upload is complete, the component can be viewed on the ESP-Registry.

Published on Github Repository If you only want to publish to the Github Repository, you can follow the compo-
nent development specifications and directly publish the component to your own Github Repository. Other developers
can pull this component using the previous Pulling Components from Git Repository method.

Related Links

• Component Manager Github

• ESP-Registry Website
• ESP-Registry Documentation
• upload-components-ci-action

2.2.2 Advanced Code Debugging

This section introduces common software exception crashes on ESP chips, as well as some commonly used advanced
code debugging methods when encountering similar problems.

Overview: Common Panic & Exception Introduction

Before debugging the code, it is necessary to understand the common Panic & Exception, which include the following
situations:
• Watchdog Interrupt
• Brownout Interrupt
• Assert / Abort
• Stack Overflow
• Cache Access Error
• Invalid Memory / Instruction Address

Watchdog Interrupt This part often involves two situations: interrupt watchdog and task watchdog. For detailed
documentation, please refer to Watchdog. The following are brief descriptions of these two watchdogs:

Interrupt Watchdog The purpose of the interrupt watchdog timer is to ensure that the interrupt service routine
(ISR) is not blocked for a long time (i.e., IWDT timeout). Blocking the timely execution of the ISR will increase the
ISR delay and also prevent task switching (because task switching is executed from the ISR). Matters that prevent the
ISR from running include:
• Disabling interrupts
• Critical section (also disables interrupts)
• Other ISRs of the same or higher priority will prevent ISRs of the same or lower priority from completing

Espressif Systems 49 Release master

Submit Document Feedback
Chapter 2. ESP Friends

When the IWDT times out, the default operation is to call the panic handler and display the error cause (Interrupt
wdt timeout on CPU0 or Interrupt wdt timeout on CPU1, depending on the situation).
At this time, the above three points need to be investigated, especially whether too much code is placed in the ISR,
causing the ISR time to be too long and triggering the interrupt watchdog.

Task Watchdog The task watchdog timer is used to monitor whether the tasks in FreeRTOS are scheduled within
a specified time. If the default lowest priority IDLE task does not feed the dog (i.e., reset the watchdog timer) within
the specified time, it will trigger the watchdog interrupt. This usually indicates that a high-priority task is always
occupying the CPU due to reasons such as calling an API in an infinite loop without delay.
The debugging method for this problem is briefly illustrated as follows, deliberately writing an infinite loop without
delay in app_main to print the log:

void app_main(void)
{
while (1) {
printf("Hello world!----------------------------------------------------\n
,→");

}
}

After the ESP is powered on and runs for CONFIG_ESP_TASK_WDT_TIMEOUT_S seconds, you can see the
following log:

E (10303) task_wdt: Task watchdog got triggered. The following tasks/users did not␣
,→reset the watchdog in time:

E (10303) task_wdt: - IDLE (CPU 0)

E (10303) task_wdt: Tasks currently running:
E (10303) task_wdt: CPU 0: main
E (10303) task_wdt: CPU 1: IDLE
E (10303) task_wdt: Print CPU 0 (current core) backtrace

The above log can be briefly analyzed as:

• E (10303) task_wdt: - IDLE (CPU 0) > IDLE0 on CPU0 did not feed the dog in time
• E (10303) task_wdt: CPU 0: main > The task currently running on CPU0 is the main task (the main task
corresponds to the app_main function)
• E (10303) task_wdt: CPU 1: IDLE > The task currently running on CPU1 is the IDLE1 task
At this time, it is indicated that the IDLE0 task triggered the watchdog reset because it did not feed the dog in time
within CONFIG_ESP_TASK_WDT_TIMEOUT_S seconds, and then it can be inferred that the main task should
always occupy the CPU to cause the task watchdog reset through the task running on CPU0. This task should be the
focus of investigation, and appropriate delays should be added to give other low-priority tasks the opportunity to be
scheduled.

Brownout Interrupt This part is a brownout interrupt. The ESP chip integrates a brownout detection circuit
internally and is enabled by default. When the brownout detector is triggered, the following information will be
printed:

Brownout detector was triggered

The chip will reset after the print information ends. At this time, you should check whether the hardware power
supply voltage meets the set threshold. For more information, please refer to the Brownout document.

Note: In the scenario of battery power supply, such as 2xAA battery power supply, the voltage is 3.1 V. At this time,
the voltage will drop for a short time due to the large instantaneous current in scenarios such as Wi-Fi connection,
triggering the brownout detection and causing the chip to restart.

Espressif Systems 50 Release master

Submit Document Feedback
Chapter 2. ESP Friends

It is recommended to use a voltage regulator chip with a larger peak current. Or replace with a battery that can
provide a large current, or try to increase the capacitance of the power supply.

Assert / Abort This part is triggered by assertion or abortion. Assertions are commonly used to check whether
assumptions in the program are true. If an assertion fails (i.e., the assumption is not established), it will trigger an
interrupt. After the interrupt, the program usually aborts (abort) and records error information in the log to help
developers debug.
Therefore, you can check which API triggered the assertion or abortion in the log at this time, and debug the code
from this API, for example:

// Function to check if input is equal to 1

int check_input(int input) {
if (input == 1) {
return 1; // Return 1 if input is equal to 1
} else {
return 0; // Return 0 if input is not equal to 1
}
}

void app_main(void)
{
// Test case for input not equal to 1
int input1 = 2;
assert(check_input(input1) == 1); // Assert that the function returns 1 for␣
,→input 1

The corresponding exception log is:

assert failed: app_main hello_world_main.c:26 (check_input(input1) == 1)

It can be seen that the reason is that assert(check_input(input1) == 1) triggered the assertion because the condition
was not satisfied. At this time, you can focus on investigating the code corresponding to this assertion.

Note: Since assertions can be disabled in the CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL

option in ESP-IDF menuconfig, it is not recommended to do calculations or function calls in assertions.

Stack Overflow This part is stack overflow. When the task stack actually used exceeds the pre-allocated task stack,
this error will occur. The error example code is as follows:

static void test_task(void *pvParameters)

{
uint32_t large_array[4096] = {0};
while (1) {
// This task obstruct a setting tx_done_sem semaphore in the UART␣
,→interrupt.

// It leads to waiting the ticks_to_wait time in uart_wait_tx_done()␣

,→function.

vTaskDelay(200 / portTICK_PERIOD_MS);
}
vTaskDelete(NULL);
}

void app_main(void)
{
(continues on next page)

Espressif Systems 51 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

xTaskCreate(test_task, "test_task", 1024, NULL, 5, NULL);
}

The corresponding error log is as follows:

***ERROR*** A stack overflow in task test_task has been detected.

From the log, you can see that a stack overflow occurred in the test_task task. Checking the code, you can see that
only 1024 bytes of task stack were allocated when xTaskCreate, but a 4096-byte array is used in the task, which
caused the stack overflow. At this time, you need to reduce the array size in the task function, or increase the task
stack allocated by xTaskCreate.

Cache Access Error For this part, you can first refer to the Cache disabled but cached memory region accessed
document. More detailed explanations of this error will be given in Locating Problems Using Guru Meditation Error
Printing.

Invalid Memory / Instruction Address When the program tries to access a non-existent memory address or
execute an invalid instruction, this type of exception will be triggered. This is usually caused by pointer errors or
memory corruption. When this type of error occurs, you can refer to Locating Problems Using Backtrace & Coredump
and Locating Memory Issues (Memory Stompings, Memory Leaks, etc.) chapters for further code debugging.

Overview: Panic Handler and Common Code Debugging Methods Introduction

Panic Handler is described in detail in the ESP-IDF Programming Guide, and will not be repeated here.
The common code debugging methods are as follows.

Log Printing / App Trace ESP-IDF provides a convenient and easy-to-use log printing library ESP Logging and
App trace.

Backtrace / Core Dump For detailed guidance on this part, please refer to Locating Problems Using Backtrace &
Coredump.

GDB Stub through UART Please refer to GDB Stub, which can be briefly summarized as follows.

GDB Stub Postmortem

1. Enable CONFIG_ESP_SYSTEM_PANIC_GDBSTUB so that when an error occurs, esp_monitor will automati-
cally enter GDB through UART
2. Use ELF + Core dump records, enter GDB through idf.py coredump-debug
Common GDB commands:
1. backtrace to trace the call stack (including incoming parameters)
2. list to print the code location
3. info threads to print all Task information
4. info locals to print the local variables of the current Task
5. print <var> to print the local/global variables of the current Task
6. thread <id> to switch Task
You can also refer to GDB Cheat Sheet.

Espressif Systems 52 Release master

Submit Document Feedback
Chapter 2. ESP Friends

GDB Stub Debugging

1. Enable CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME, you can automatically enter GDB through UART
esp_monitor at runtime (Ctrl`+`C)
Common GDB commands:
1. x/1xw <addr> to print the corresponding 32-bit memory/register address
2. watch <var> to monitor variables, when the variable value changes, GDB will automatically stop
3. break <where> to set breakpoints, which can be function names, line numbers, addresses
4. continue to continue running
5. step to run step by step, enter the function
6. next to run step by step, do not enter the function
7. print <var> to print variable values
8. set <var> = <value> to modify variable values
You can also refer to GDB Cheat Sheet.

OpenOCD & GDB Please refer to JTAG Debugging.

GPIO tracing GPIO tracing often flips IO to mark events, such as implementing GPIO flipping when a certain
event occurs in the code, so that you can determine whether the event is triggered by querying the flipping status of
GPIO.

SystemView through UART/JTAG For detailed guidance on this part, please refer to Using SystemView for Sys-
tem Analysis and Optimization.

Locating Problems Using Guru Meditation Error Printing

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

You can first refer to the Guru Meditation Errors in the ESP-IDF Programming Guide to understand common errors
and their causes. This document provides further explanations of common errors and presents feasible analytical
approaches.

Note: This analysis focuses on errors occurring in the RISC-V architecture, specifically the ESP32-C3. While errors
in the Xtensa architecture (e.g., ESP32) may differ in naming, their underlying causes remain similar. Architecture-
specific errors will be analyzed separately.

Guru Meditation errors are categorized into two types: ARCH exceptions and SOC exceptions.
Common ARCH exceptions:
• Load access fault
• Store Access Fault
• Instruction Access Fault
• IllegalInstruction
Common SOC exceptions:
• Interrupt wdt timeout on CPU0/CPU1
• Cache disable but cached memory region accessed

Espressif Systems 53 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Often, identifying the root cause of Guru Meditation errors can be challenging, as these crashes often represent
symptoms of underlying issues. The actual problems may be related to FreeRTOS, memory, flash, interrupt, etc.,
requiring specific analysis.

Load access fault LoadProhibited

Test Case This exception occurs when a load instruction (such as lw) attempts to access invalid memory. The
example code demonstrates a scenario that triggers this crash:

uint8_t *buff = NULL;

load_fault = buff[1];

Exception Phenomenon
• RISC-V

Guru Meditation Error: Core 0 panic'ed (Load access fault). Exception was␣
,→unhandled.

Core 0 register dump:

Stack dump detected
MEPC : 0x4200696a RA : 0x4200696a SP : 0x3fc8f7c0 GP :␣
,→0x3fc8b400

TP : 0x3fc87d74 T0 : 0x4005890e T1 : 0x3fc8f41c T2 :␣

,→0x00000000

S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x0000000f A1 :␣

,→0x3fc8f3f8

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x3fc8c000 A5 :␣

,→0x00000000

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000005 MTVAL :␣

,→0x00000001

• XTENSA

Guru Meditation Error: Core 0 panic'ed (LoadProhibited). Exception was unhandled.

Core 0 register dump:

PC : 0x42007c2f PS : 0x00060a30 A0 : 0x82007c42 A1 :␣
,→0x3fc97d70

A2 : 0x42011934 A3 : 0x3c023f48 A4 : 0x3c023fc8 A5 :␣

,→0x3fc97d90

A6 : 0x3fc97d70 A7 : 0x0000000c A8 : 0x00000000 A9 :␣

,→0x3fc97d20

A10 : 0x0000000f A11 : 0x3fc97fac A12 : 0x3fc97d70 A13 :␣

,→0x0000000c

A14 : 0x3fc941e4 A15 : 0x00000000 SAR : 0x00000004 EXCCAUSE:␣

,→0x0000001c

Backtrace: 0x42007c2c:0x3fc97d70 0x42007c3f:0x3fc97d90 0x42019247:0x3fc97db0␣

,→0x40379e71:0x3fc97de0

Espressif Systems 54 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Troubleshooting If further analyze the assembly code (the steps can be referred to Appendix 1 - ESP Disassembly
Corresponding Instructions), you can find it corresponds to the following instructions:

lw a1, 1(zero) // RSIC-V

l8ui a11, a8, 1 // XTENSA

When this type of exception is triggered, MTVAL/EXCVADDR will automatically update to data related to the ex-
ception. From the RISC-V exception error, you can see MTVAL : 0x00000001.
Usually, MTVAL being NULL(0x00000000) represents taking a value from a NULL address, and close to NULL
represents trying to access a member of an array or structure from a NULL address.
• For the RSIC-V architecture, the PC and RA registers contain the function pointer of the exception, and you
can find the corresponding function from the elf.
• For the Xtensa architecture, a backtrace will be printed during an exception, and the corresponding function
can also be found from the elf.

Practical Case The following figure is a typical ESP32-C3 Load access fault issue.

From the above figure, the problem lies in lw a5, 20(s0), s0 is 0x0, which corresponds to a NULL pointer.
And then analyze the previous assembly lw s0, 24(sp), the corresponding code segment is pxTimer =
xMessage.u.xTimerParameters.pxTimer;, at this point the question can be changed to why pxTimer
is NULL.
You can further locate the problem by adding the following debug log:

if (pxTimer == NULL) {
ets_printf("xMessageID: %d\n", xMessage.xMessageID);
}

The problem was finally found to be that the timer was not successfully created. The pointer pointing to the timer is
NULL. If subsequent timer operations are performed at this time, a Load access fault LoadProhibited
error will occur due to the null pointer.

Espressif Systems 55 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Precautions Not all Load access fault LoadProhibited problems can be simply located. As shown
in the figure below:

The PC address points to the ROM function rom_i2c_writeReg_mask function, and the Backtrace does not
have enough valid information. In this case, a satble reproduction is required for troubleshooting. If the problem is
difficult to be reproduced, it may be caused by hardware or wild pointer.

Store access fault StoreProhibited

Test Case When an application tries to write to an invalid memory location, this type of CPU exception occurs.
The test code is shown below:

typedef struct {
uint8_t buf[10];
uint8_t data;
} store_test_t;

void store_access_fault(store_test_t * store_test)

{
store_test->data = 0x5F;
printf("Data: %d\n", store_test->data);
}
void app_main(void)
{
store_test_t * store_test = NULL;
store_access_fault(store_test);
}

Espressif Systems 56 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Exception Phenomenon
• RISC-V
In the RISC-V architecture chip, you can see the following exception printout. Analyze the assembly instructions (the
steps can be referred to Appendix 1 - ESP Disassembly Corresponding Instructions), when this exception occurs, the
PC address points to sb/sw and other store-related instructions. At this time, the exception value 0x0000000a
stored in MTVAL indicates that it wants to access the content in an array or structure starting from NULL address.

Guru Meditation Error: Core 0 panic'ed (Store access fault). Exception was␣
,→unhandled.

Core 0 register dump:

Stack dump detected
MEPC : 0x42006960 RA : 0x42006984 SP : 0x3fc8f7c0 GP :␣
,→0x3fc8b400

TP : 0x3fc87d7c T0 : 0x4005890e T1 : 0x20000000 T2 :␣

,→0x00000000

S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x00000000 A1 :␣

,→0x3fc8f3f8

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x3fc8c000 A5 :␣

,→0x0000005f

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL :␣

,→0x0000000a

• XTENSA
In the XTENSA architecture chip, you can see the following exception printout. Analyze the assembly instruc-
tions (steps can be referred to Appendix 1 - ESP Disassembly Corresponding Instructions), when this exception oc-
curs, the PC address points to s8i/s32i and other store-related instructions. At this time, the exception value
0x0000000a stored in EXCVADDR indicates that it wants to access the content in an array or structure starting
from NULL address.

Guru Meditation Error: Core 0 panic'ed (StoreProhibited). Exception was unhandled.

Core 0 register dump:

PC : 0x42007c21 PS : 0x00060630 A0 : 0x82007c38 A1 :␣
,→0x3fc97d70

A2 : 0x00000000 A3 : 0x3c023f48 A4 : 0x3c023fc8 A5 :␣

,→0x3fc97d90

A6 : 0x3fc97d70 A7 : 0x0000000c A8 : 0x0000005f A9 :␣

,→0x3fc97d00

A10 : 0x00000031 A11 : 0x3fc97fac A12 : 0x3fc97d70 A13 :␣

,→0x0000000c

A14 : 0x3fc941e4 A15 : 0x00000000 SAR : 0x00000004 EXCCAUSE:␣

,→0x0000001d

EXCVADDR: 0x0000000a LBEG : 0x400556d5 LEND : 0x400556e5 LCOUNT :␣

,→0xfffffffd

Backtrace: 0x42007c1e:0x3fc97d70 0x42007c35:0x3fc97d90 0x4201923f:0x3fc97db0␣

,→0x40379e71:0x3fc97de0

Location Method The location method is similar to Load access fault LoadProhibited . Analyze the assembly
code (steps can be referred to Appendix 1 - ESP Disassembly Corresponding Instructions), you will see the following

Espressif Systems 57 Release master

Submit Document Feedback
Chapter 2. ESP Friends

instruction:

sb a5,10(a0) // RSIC-V
s8i a8, a2, 10 // XTENSA

When this type of exception being triggered, MTVAL/EXCVADDR will automatically update to data related to the
exception, as can be seen from the RISC-V exception information MTVAL : 0x0000000a. Usually, MTVAL
being NULL means that the CPU is trying to write data to a NULL address, and close to NULL means trying to
write data to a member of an array or structure starting from a NULL address.
• For the RSIC-V architecture, the PC and RA registers contain the function pointers of the exception, and the
corresponding function can be found from the elf
• For the Xtensa architecture, a backtrace will be printed during an exception, and the corresponding function
can also be found from the elf

Actual Case Please refer to Test Case.

Notes Similar to the Load access fault LoadProhibited issue, there are wild pointers cases that cannot be analyzed,
and further analysis is required based on the actual application code.

Instruction Access Fault(InstrFetchProhibited)

Test Case When an application tries to read instructions from an invalid address, this type of CPU exception occurs,
and the PC register often points to an invalid memory address. The test code is as follows:

typedef void (*fptr_t)(void);

volatile fptr_t fptr = (fptr_t) 0x4;
fptr();

The corresponding RISC-V assembly instruction (steps can refer to Appendix 1 - ESP Disassembly Corresponding
Instructions) is as follows:

42006958: 1101 addi sp,sp,-32

4200695a: ce06 sw ra,28(sp)
4200695c: 4791 li a5,4
4200695e: c63e sw a5,12(sp)
42006960: 47b2 lw a5,12(sp)
42006962: 9782 jalr a5
42006964: 40f2 lw ra,28(sp)
42006966: 6105 addi sp,sp,32
42006968: 8082 ret

Exception Phenomenon
• RISC-V

Guru Meditation Error: Core 0 panic'ed (Instruction access fault). Exception was␣
,→unhandled.

Core 0 register dump:

Stack dump detected
MEPC : 0x00000004 RA : 0x42006964 SP : 0x3fc8f7b0 GP :␣
,→0x3fc8b400

TP : 0x3fc87d8c T0 : 0x4005890e T1 : 0x20000000 T2 :␣

,→0x00000000

S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x00000031 A1 :␣

,→0x3fc8f3f8

(continues on next page)

Espressif Systems 58 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x3fc8c000 A5 :␣
,→0x00000004

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000001 MTVAL :␣

,→0x00000004

• Xtensa

Guru Meditation Error: Core 0 panic'ed (InstrFetchProhibited). Exception was␣

,→unhandled.

Core 0 register dump:

PC : 0x00000004 PS : 0x00060630 A0 : 0x800d539a A1 :␣
,→0x3ffb4a30

A2 : 0x400de738 A3 : 0x3f40379c A4 : 0x3f40381c A5 :␣

,→0x3ffb4a60

A6 : 0x3ffb4a40 A7 : 0x0000000c A8 : 0x800e4dbe A9 :␣

,→0x3ffb49d0

A10 : 0x00000031 A11 : 0x3ffafc64 A12 : 0x3ffb4a40 A13 :␣

,→0x0000000c

A14 : 0x3ffb2770 A15 : 0x0000cdcd SAR : 0x00000004 EXCCAUSE:␣

,→0x00000014

EXCVADDR: 0x00000004 LBEG : 0x400014fd LEND : 0x4000150d LCOUNT :␣

,→0xfffffffd

Backtrace: 0x00000001:0x3ffb4a30 0x400d5397:0x3ffb4a60 0x400e54f8:0x3ffb4a80␣

,→0x400858e9:0x3ffb4ab0

Troubleshooting Method Usually, such problems are caused by wild pointers. In this case, the PC register has no
value, and whether other registers are worth analyzing depends on the running time of the wild pointer. For this test
code, the current function has triggered a CPU exception, so the RA register contains the pointer of the upper-layer
function (Xtensa architecture using Backtrace), and the exception can be analyzed at this case. But most of the time,
the RA register will be destroyed. You can follow the steps below to locate the problem:
1. Stably reproduce the problem, ensure that the problem is the same at each time
2. Find the pattern of the problem, such as what operations are performed, or which logs are printed before the
exception starts
3. Analyze in conjunction with the code based on the location of the program exception, add debugging logs and
gradually reducing the amount of project code, and see if the problem can still be reproduced.

Actual Case As shown in the figure below, the scene of the exception has been completely destroyed. There is no
way to infer the cause of the problem based on the information. However, most registers are destroyed into a fixed
value, which is also a pattern. In cases where all registers are destroyed, it is usually a problem caused by memory
trampling, which can be analyzed using the heap memory debugging method.

Espressif Systems 59 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Illegal Instruction

Test Case During the CPU instruction fetching phase, an illegal instruction (defined in the RISC-V spec as a 16-bit
instruction all set to 0) will print this error. The test code is as follows:
uint32_t instr_dram_addr = 0x0;
intptr_t instr_addr = MAP_DRAM_TO_IRAM((intptr_t)&instr_dram_addr);
typedef void (*illegal_instr_t)(void);
illegal_instr_t illegal_instr = (uint32_t *)instr_addr; // Ensure that the memory␣
,→data in instr_addr is 0x0

illegal_instr();

Note: The ESP32 in the Xtensa platform does not support the above test case. If other chips want to run this test
case, they need to turn off the memory protection function first.

Exception Phenomenon
• RISC-V
Guru Meditation Error: Core 0 panic'ed (Illegal instruction). Exception was␣
,→unhandled.

Core 0 register dump:

Stack dump detected
MEPC : 0x4005f002 RA : 0x42006962 SP : 0x3fc8f7c0 GP :␣
,→0x3fc8b400

0x42006962: illegal_instr_fault at /home/jacques/useful_example/crash_sim/store_

,→access_fault/main/hello_world_main.c:79

TP : 0x3fc87d8c T0 : 0x4005890e T1 : 0x20000000 T2 :␣

,→ 0x00000000
S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x3fc8f840 A1 :␣
,→0x3fc8f3f8

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x3fc8c000 A5 :␣

,→0x4005f000

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000
(continues on next page)

Espressif Systems 60 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣
,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000002 MTVAL :␣

,→0x00000000

• Xtensa

Guru Meditation Error: Core 0 panic'ed (IllegalInstruction). Exception was␣

,→unhandled.

Memory dump at 0x403e298c: 00000000 00000000 00000000

Core 0 register dump:
PC : 0x403e2990 PS : 0x00060130 A0 : 0x820059fe A1 :␣
,→0x3fcf2990

A2 : 0x4200c030 A3 : 0x3c0232fc A4 : 0x3c02337c A5 :␣

,→0x3fcf29c0

A6 : 0x3fcf29a0 A7 : 0x0000000c A8 : 0x820059f4 A9 :␣

,→0x3fcf2930

A10 : 0x00000031 A11 : 0x3fcf2be4 A12 : 0x3fcf29a0 A13 :␣

,→0x0000000c

A14 : 0x3fc922c4 A15 : 0x00000000 SAR : 0x00000004 EXCCAUSE:␣

,→0x00000000

EXCVADDR: 0x00000000 LBEG : 0x400556d5 LEND : 0x400556e5 LCOUNT :␣

,→0xfffffffd

Backtrace: 0x403e298d:0x3fcf2990 |<-CORRUPTED

Troubleshooting Although the ESP-IDF documentation contains Explanation of Illegal instruction, which men-
tions that there may be 3 types of situations that trigger this issue, in actual use, most of them are caused by the CPU
fetching instructions from flash abnormally. Another part of them are caused by wild pointers fetching abnormal
memory. From the PC address, it can be seen whether the addressing is abnormal from IRAM or flash.
Senarios for problems with fetching instructions from flash include: flash powering down when chip is sleeping,
unstable CS pull-up, unstable flash power supply, and flash suspend function, etc.

Actual Case The following diagram shows an abnormal senario of the ESP chip in a low-power scenario.
From the log, there is a power save printout before the error, which suggests that the problem may be re-
lated to the chip s sleep mode. Later, by disabling the CONFIG turn off the flash power during sleep (CON-
FIG_ESP_SLEEP_POWER_DOWN_FLASH) and enabling the CONFIG CS software pull-up during sleep (CON-
FIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND), the problem no longer occurs.

Espressif Systems 61 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Cache disable but cached memory region accessed (Cache error)

Abnormal Reason During flash operations (read/write/erase), the cache is turned off for a short time. If an inter-
rupt is triggered during this time (interrupts decorated with ESP_INTR_FLAG_IRAM can be triggered when the
cache is off), such as if there are functions in the interrupt function that need to fetch instructions or data from the
flash through the cache (includingmmap), an exception will occur because the cache is turned off.

Test Case After turning off the cache, access and print the data in the flash. The test code is shown below:
static const uint32_t s_in_rodata[8] = { 0x12345678, 0xfedcba98 };
spi_flash_disable_interrupts_caches_and_other_cpu();
volatile uint32_t* src = (volatile uint32_t*) s_in_rodata;
uint32_t v1 = src[0];
uint32_t v2 = src[1];
ets_printf("%lx %lx\n", v1, v2);

Abnormal Phenomenon
• RISC-V
Guru Meditation Error: Core 0 panic'ed (Cache error).
access to cache while dbus or cache is disabled

Stack dump detected

Core 0 register dump:
MEPC : 0x40000040 RA : 0x40381e82 SP : 0x3fc8f7c0 GP :␣
,→0x3fc8b400

0x40381e82: cache_access_test_func at /home/jacques/useful_example/crash_sim/store_

,→access_fault/main/hello_world_main.c:38

TP : 0x3fc87d5c T0 : 0x4005890e T1 : 0x20000000 T2 :␣

,→ 0x00000000
S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x3c025610 A1 :␣
,→0x00000000

A2 : 0x00000000 A3 : 0x00000200 A4 : 0x600c4000 A5 :␣

,→0x3c02561c

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

(continues on next page)

Espressif Systems 62 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣
,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000019 MTVAL :␣

,→0x6944806f

• Xtensa

Guru Meditation Error: Core 0 panic'ed (Cache disabled but cached memory region␣
,→accessed).

Core 0 register dump:

PC : 0x400830ed PS : 0x00060a34 A0 : 0x800d539a A1 :␣
,→0x3ffb4a40

0x400830ed: cache_access_test_func at /home/jacques/useful_example/crash_sim/store_

,→access_fault/main/hello_world_main.c:32

A2 : 0x400de738 A3 : 0x3f40379c A4 : 0x3f40381c A5 :␣

,→ 0x3ffb4a60
0x400de738: vprintf at /builds/idf/crosstool-NG/.build/xtensa-esp32-elf/src/newlib/
,→newlib/libc/stdio/vprintf.c:30

A6 : 0x3ffb4a40 A7 : 0x0000000c A8 : 0x3f4040c4 A9 :␣

,→ 0x3ffb4a10
A10 : 0x00000001 A11 : 0xbad00bad A12 : 0x3ffb2608 A13 :␣
,→0x0000000c

A14 : 0x3ffb2770 A15 : 0x0000cdcd SAR : 0x00000004 EXCCAUSE:␣

,→0x00000007

EXCVADDR: 0x00000000 LBEG : 0x400014fd LEND : 0x4000150d LCOUNT :␣

,→0xfffffffd

Backtrace: 0x400830ea:0x3ffb4a40 0x400d5397:0x3ffb4a60 0x400e54e4:0x3ffb4a80␣

,→0x40085915:0x3ffb4ab0

Analysis Method In such cases, focus on the PC address of the exception. If the address is in flash, it means
that instructions are read from flash when the cache is closed. You need to decorate the corresponding function with
IRAM_ATTR. It should be noted that IRAM_ATTR is only for the current function. If this function has sub-functions,
all the sub-functions need to be decorated with IRAM_ATTR.
If the address is in IRAM, it means that there is no problem with this function itself, but the input parameters of this
function may need to be read from flash.

Practical Case During flash read and write operations (causing cache close), the gptimer interrupt that has been
put into IRAM is also triggered. The gptimer ISR executes some operations that need to read content from flash,
triggering this problem:

Espressif Systems 63 Release master

Submit Document Feedback
Chapter 2. ESP Friends

From the figure above, we can conclude several problem points

1. It can be confirmed that the gptimer interrupt is triggered during flash read and write operations, and there is
content in the flash in the ISR
2. The function gpio_set_level pointed by the PC has been put into IRAM instead of flash, so it should
run normally when the cache is closed
After analysis, it was finally found that the problem was caused by the input parameter LED_matrix of the function
gpio_set_level being decorated with const. The parameters decorated with const will be placed in the .rodata
section of flash, so reading this parameter requires cache.

Espressif Systems 64 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Precautions The exception of Cache disable is better captured on the Xtensa platform, and may appear as other
errors caused by the inability to read data from the cache on the RISC-V platform, such as Illegal instruction. The
code example is as follows:

gpio_set_level(12, 1);
spi_flash_disable_interrupts_caches_and_other_cpu();
gpio_set_level(12, 0);

When running in ESP32-C3 (RISC-V platform), the crash is as follows

Guru Meditation Error: Core 0 panic'ed (Illegal instruction). Exception was␣

,→unhandled.

Core 0 register dump:

Stack dump detected
MEPC : 0x42006ef2 RA : 0x40381e7e SP : 0x3fc8f7f0 GP :␣
,→0x3fc8b400

0x42006ef2: gpio_set_level at /home/jacques/sdk/esp-idf/components/driver/gpio/

,→gpio.c:233

0x40381e7e: cache_access_test_func at /home/jacques/useful_example/crash_test/main/

,→hello_world_main.c:50

TP : 0x3fc87d4c T0 : 0x4005890e T1 : 0x20000000 T2 :␣

,→0x00000000

S0/FP : 0x3c023000 S1 : 0x00000000 A0 : 0x0000000c A1 :␣

,→0x00000000

A2 : 0x00000200 A3 : 0x00000200 A4 : 0x600c4000 A5 :␣

,→0x00000000

(continues on next page)

Espressif Systems 65 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣
,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000002 MTVAL :␣

,→0x00000000

Interrupt wdt timeout on CPU0/CPU1

Exception Principle The interrupt watchdog uses the hardware watchdog timer on Timer group 1 to monitor system
task scheduling by incorporating a dog-feeding operation in the SysTick interrupt. If the dog-feeding operation is
not executed within the SysTick interrupt for an extended period (default 300 ms), the interrupt watchdog interrupt
is triggered. For more information, please refer to Interrupt Watchdog Timer (IWDT).

Test Case This issue can be triggered by disabling the interrupt. The test code is as follows:

static portMUX_TYPE s_init_spinlock = portMUX_INITIALIZER_UNLOCKED;

portENTER_CRITICAL(&s_init_spinlock);
while (1) {
}

Exception Phenomenon
• RISC-V

Guru Meditation Error: Core 0 panic'ed (Interrupt wdt timeout on CPU0).

Core 0 register dump:

Stack dump detected
MEPC : 0x42006964 RA : 0x42006964 SP : 0x3fc911a0 GP :␣
,→0x3fc8b400

0x42006964: interrupt_wdt_fault_task at /home/jacques/useful_example/crash_test/

,→main/hello_world_main.c:121 (discriminator 1)

TP : 0x3fc8971c T0 : 0x00000000 T1 : 0x00000000 T2 :␣

,→ 0x00000000
S0/FP : 0x00000000 S1 : 0x00000000 A0 : 0x00000001 A1 :␣
,→0x00000000

A2 : 0x00000000 A3 : 0x00000004 A4 : 0x00000001 A5 :␣

,→0x3fc8c000

A6 : 0x00000000 A7 : 0x00000000 S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000018 MTVAL :␣

,→0x0000a001

• Xtensa

Espressif Systems 66 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Guru Meditation Error: Core 0 panic'ed (Interrupt wdt timeout on CPU0).

Core 0 register dump:

PC : 0x40378b06 PS : 0x00060634 A0 : 0x82002239 A1 :␣
,→0x3fc984f0

0x40378b06: esp_cpu_wait_for_intr at /home/jacques/sdk/esp-idf/components/esp_hw_

,→support/cpu.c:110

A2 : 0x00000000 A3 : 0x00000000 A4 : 0x3fc96c70 A5 :␣

,→ 0x3fc96c50
A6 : 0x42005e10 A7 : 0x00000000 A8 : 0x82009452 A9 :␣
,→0x3fc984b0

0x42005e10: timer_task at /home/jacques/sdk/esp-idf/components/esp_timer/src/esp_

,→timer.c:470

A10 : 0x00000000 A11 : 0x00000000 A12 : 0x3fc96c50 A13 :␣

,→0x3fc96c30

A14 : 0x00000000 A15 : 0x00000000 SAR : 0x00000000 EXCCAUSE:␣

,→0x00000005

EXCVADDR: 0x00000000 LBEG : 0x00000000 LEND : 0x00000000 LCOUNT :␣

,→0x00000000

Backtrace: 0x40378b03:0x3fc984f0 0x42002236:0x3fc98510 0x4037b5a9:0x3fc98530␣

,→0x40379e71:0x3fc98550

0x40378b03: xt_utils_wait_for_intr at /home/jacques/sdk/esp-idf/components/xtensa/

,→include/xt_utils.h:81

(inlined by) esp_cpu_wait_for_intr at /home/jacques/sdk/esp-idf/components/esp_hw_

,→support/cpu.c:101

0x42002236: esp_vApplicationIdleHook at /home/jacques/sdk/esp-idf/components/esp_

,→system/freertos_hooks.c:59

0x4037b5a9: prvIdleTask at /home/jacques/sdk/esp-idf/components/freertos/FreeRTOS-

,→Kernel/tasks.c:4269 (discriminator 1)

0x40379e71: vPortTaskWrapper at /home/jacques/sdk/esp-idf/components/freertos/

,→FreeRTOS-Kernel/portable/xtensa/port.c:149

Core 1 register dump:

PC : 0x42007c32 PS : 0x00060034 A0 : 0x80379e74 A1 :␣
,→0x3fc99f20

0x42007c32: interrupt_wdt_fault_task at /home/jacques/useful_example/crash_test/

,→main/hello_world_main.c:121 (discriminator 1)

A2 : 0x00000000 A3 : 0x00000000 A4 : 0x00000001 A5 :␣

,→ 0x00000000
A6 : 0x00000001 A7 : 0x00000000 A8 : 0x82007c32 A9 :␣
,→0x3fc99ef0

A10 : 0x00000001 A11 : 0x3fc93a54 A12 : 0x00060020 A13 :␣

,→0x00060023

A14 : 0x00060323 A15 : 0x0000abab SAR : 0x00000000 EXCCAUSE:␣

,→0x00000005

EXCVADDR: 0x00000000 LBEG : 0x00000000 LEND : 0x00000000 LCOUNT :␣

,→0x00000000

Backtrace: 0x42007c2f:0x3fc99f20 0x40379e71:0x3fc99f40

0x42007c2f: vPortEnterCritical at /home/jacques/sdk/esp-idf/components/freertos/
,→FreeRTOS-Kernel/portable/xtensa/include/freertos/portmacro.h:573

(inlined by) interrupt_wdt_fault_task at /home/jacques/useful_example/crash_test/

,→main/hello_world_main.c:120

0x40379e71: vPortTaskWrapper at /home/jacques/sdk/esp-idf/components/freertos/

,→FreeRTOS-Kernel/portable/xtensa/port.c:149

Espressif Systems 67 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Analysis Method In case of such problems, primarily observe the PC address of the exception to determine the
location of the crash trigger. For multi-core architectures, it is necessary to observe the registers of several cores and
analyze the methods that trigger the problem.
The possible reasons and specific explanations are as follows:
1. Long time interrupt off
2. Blocking issue exists in ISR function
3. Interrupt not cleared

Long time interrupt off Turning off the interrupt is designed to protect critical code sections from being inter-
rupted. However, long time interrupt off is a primary cause of triggering the interrupt watchdog.
As in Test Case, operations like entering a critical section, the interrupt is turned off, preventing the SysTick interrupt
from executing the watchdog feeding operation in time. This leads to an interrupt watchdog timeout and triggers the
watchdog exception handler. Users must troubleshoot the logic of interrupt disabling in the problematic code area.

Blocking in ISR function When an interrupt occurs, the corresponding ISR is called for processing. ISR functions
should perform minimal operations, deferring time-consuming tasks to non-interrupt functions. If an ISR takes too
long to execute or blocks, it may trigger the interrupt watchdog.
Here is a simple example of GPIO ISR blocking:

#define GPIO_INPUT_IO_0 4

static void IRAM_ATTR gpio_isr_handler(void* arg)

{
ets_printf("ISR\n");
while(1){}
}

void app_main(void)
{
gpio_config_t io_conf;
io_conf.intr_type = GPIO_INTR_POSEDGE;
io_conf.pin_bit_mask = (1ULL<<GPIO_INPUT_IO_0);
io_conf.mode = GPIO_MODE_INPUT;
io_conf.pull_up_en = 1;
gpio_config(&io_conf);

gpio_install_isr_service(0);
gpio_isr_handler_add(GPIO_INPUT_IO_0, gpio_isr_handler, (void*) GPIO_INPUT_IO_
,→0);

Manually pull up GPIO 4 to trigger the GPIO interrupt, and print the following crash information:

ISR
Guru Meditation Error: Core 0 panic'ed (Interrupt wdt timeout on CPU0).
Core 0 register dump:
PC : 0x40082580 PS : 0x00060034 A0 : 0x80081560 A1 :␣
,→0x3ffb07c0

0x40082580: gpio_isr_handler at /home/jacques/problem/wdt/int_wdt/build/../main/

,→hello_world_main.c:40 (discriminator 1)

A2 : 0x00000004 A3 : 0x3ff0015c A4 : 0x800d6d82 A5 :␣

,→ 0x3ffb3400
A6 : 0x00000000 A7 : 0x00000001 A8 : 0x80082580 A9 :␣
,→0x3ffb0730

A10 : 0x00000004 A11 : 0x00000004 A12 : 0x00000004 A13 :␣

,→0x00000000

(continues on next page)

Espressif Systems 68 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

A14 : 0x00000000 A15 : 0x3ffb3400 SAR : 0x0000001c EXCCAUSE:␣
,→0x00000005

EXCVADDR: 0x00000000 LBEG : 0x00000000 LEND : 0x00000000 LCOUNT :␣

,→0x00000000

Core 0 was running in ISR context:

EPC1 : 0x400d1097 EPC2 : 0x00000000 EPC3 : 0x00000000 EPC4 :␣
,→0x40082580

0x400d1097: uart_hal_write_txfifo at /home/jacques/sdk/esp-idf/components/hal/uart_

,→hal_iram.c:35

0x40082580: gpio_isr_handler at /home/jacques/problem/wdt/int_wdt/build/../main/

,→hello_world_main.c:40 (discriminator 1)

Backtrace:0x4008257d:0x3ffb07c0 0x4008155d:0x3ffb07e0 0x40082102:0x3ffb0800␣

,→0x400d6702:0x3ffb3450 0x400862a2:0x3ffb3470 0x40087865:0x3ffb3490

Through the PC and Backtrace, we can confirm that the problem occurs in the gpio_isr_handle function. In addition,
the log line Core 0 was running in ISR context also indicates that it is currently running in the interrupt
function.

Interrupt not cleared After the ISR function ends, the corresponding interrupt must be manually cleared. If it is
not cleared at this time, the interrupt will keep triggering, preventing the SysTick interrupt from responding.
As in the example Blocking in ISR function, if you remove the while(1) loop in gpio_isr_handler, and comment
out gpio_hal_clear_intr_status_bit in the ESP-IDF GPIO driver, recompiling and running the program will still trigger
the interrupt watchdog crash.
If the user has not modified the default driver, interrupt clearing is usually handled by the lower-layer driver. If an
interrupt watchdog exception points to the internal driver, check whether the lower-layer driver properly clears the
interrupt.

Real Case Though it might seem that interrupt watchdog issues are straightforward to analyze, they often occur
alongside FreeRTOS in actual applications. Many FreeRTOS operations require interrupt handling. If FreeRTOS
encounters an exception, it can get stuck, appearing as an interrupt watchdog issue. Here s an example of a real
crash case:

Guru Meditation Error: Core 0 panic'ed (Interrupt wdt timeout on CPU0)

Core 0 register dump:
PC : 0x400915d2 PS : 0x00060b34 A0 : 0x800903ed A1 :␣
,→0x3ffd4e80

A2 : 0x3ffd3598 A3 : 0x3ffd4ff0 A4 : 0x00000c9f A5 :␣

,→0x3f408990

A6 : 0x3ffbf580 A7 : 0x00060023 A8 : 0x3ffd4ff0 A9 :␣

,→0x0000000f

A10 : 0x3ffd4ff0 A11 : 0x0000000f A12 : 0x00060b20 A13 :␣

,→0x00000001

A14 : 0x3ffeddf0 A15 : 0x3ffea57c SAR : 0x00000018 EXCCAUSE:␣

,→0x00000005

EXCVADDR: 0x00000000 LBEG : 0x400014fd LEND : 0x4000150d LCOUNT :␣

,→0xfffffffe

ELF file SHA256: eadf38922e335ed1

Backtrace: 0x400915cf:0x3ffd4e80 0x400903ea:0x3ffd4ea0 0x4008f514:0x3ffd4ec0␣

,→0x400ffb91:0x3ffd4f00 0x40136612:0x3ffd4f30

Analyzing the Backtrace information, as follows:

Espressif Systems 69 Release master

Submit Document Feedback
Chapter 2. ESP Friends

~$ xtensa-esp32-elf-addr2line -afe esp32_interrupt_wdt.elf 0x400915cf:0x3ffd4e80␣

,→0x400903ea:0x3ffd4ea0 0x4008f514:0x3ffd4ec0 0x400ffb91:0x3ffd4f00␣

,→0x40136612:0x3ffd4f30

0x400915cf
vListInsert
/arm/esp-idf/components/freertos/list.c:205
0x400903ea
vTaskPlaceOnEventList
/arm/esp-idf/components/freertos/tasks.c:2901 (discriminator 2)
0x4008f514
xQueueGenericReceive
/arm/esp-idf/components/freertos/queue.c:1596
0x400ffb91
arch_os_mbox_fetch
/arm/components/esp32/arch_os.c:352 (discriminator 4)
0x40136612
msg_fetch_block
/arm/components/libs/d0/delayzero.c:631

From the above log, the problem is not a crash in the interrupt, but points to FreeRTOS itself. By searching for
vListInsert, it shows that the problem occurs in the following for loop:

if( xValueOfInsertion == portMAX_DELAY )

{
pxIterator = pxList->xListEnd.pxPrevious;
}
else
{
for( pxIterator = ( ListItem_t * ) &( pxList->xListEnd ); pxIterator->pxNext->
,→xItemValue <= xValueOfInsertion; pxIterator = pxIterator->pxNext )

{
/* There is nothing to do here, just iterating to the wanted
insertion position. */
}
}

Further check whether the corresponding upper-layer code has interrupt operations at this moment. Finally in
vTaskPlaceOnEventList, it shows that interrupts are indeed disabled before performing the list insertion operation.

void vTaskPlaceOnEventList( List_t * const pxEventList, const TickType_t␣

,→xTicksToWait )

{
configASSERT( pxEventList );
taskENTER_CRITICAL(&xTaskQueueMutex);

vListInsert( pxEventList, &( pxCurrentTCB[xPortGetCoreID()]->xEventListItem )␣

,→ );

prvAddCurrentTaskToDelayedList( xPortGetCoreID(), xTicksToWait);

taskEXIT_CRITICAL(&xTaskQueueMutex);
}

For now the analysis is complete. This issue is a FreeRTOS problem that manifests as an interrupt watchdog. To
troubleshoot this type of issue, we need to analyze why it no longer exits in the for loop. It is unlikely that the issue
lies with FreeRTOS itself, rather, it is typically caused by improper use of the upper-layer application code, such as
memory stomping, blocking operations within interrupts, or similar issues.

Appendix 1 - ESP Disassembly Corresponding Instructions

• Xtensa ESP32 : xtensa-esp32-elf-objdump -S xxx.elf > a.txt
• Xtensa ESP32-S2 : xtensa-esp32s2-elf-objdump -S xxx.elf > a.txt

Espressif Systems 70 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Xtensa ESP32-S3 : xtensa-esp32s3-elf-objdump -S xxx.elf > a.txt

• RISC-V : riscv32-esp-elf-objdump -S xxx.elf > a.txt
Where xxx.elf is the project elf file, which is often in the build folder of the project directory. a.txt is the
output of the disassembly, which contains the actual assembly instructions.

Locating Problems Using Backtrace & Coredump

Backtrace Overview By default, when a Panic occurs, unless CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT

is enabled, the panic handler will print CPU registers and backtrace to the console for developers to further debug
and analyze. This is further described in the ESP-IDF Programming Guide in the section on Register Dump and
Backtrace.
Backtrace information varies for different CPU architectures. Currently, ESP primarily uses the Xtensa architecture,
exemplified by ESP32-S3, and the RISC-V architecture, exemplified by ESP32-C3:
• For Xtensa, the focus is on PC and EXCVADDR, as well as the Backtrace address.
• For RISC-V, the focus is on MEPC and MTVAL, as well as stack information (Backtrace address is not printed
by default).
Register information and Backtrace addresses can be printed and manually parsed using third-party serial tools and
addr2line or automatically through idf.py monitor. We will elaborate on how to use Backtrace & Coredump to locate
issues for these two CPU architectures.

xTensa Backtrace ESP currently uses the xTensa architecture for chips such as ESP8266, ESP32, ESP32-S2, and
ESP32-S3.
Here is an example of error logs corresponding to xTensa:

Guru Meditation Error: Core 0 panic'ed (LoadProhibited). Exception was unhandled.

Core 0 register dump:

PC : 0x42016d2f PS : 0x00060c30 A0 : 0x820088ac A1 :␣
,→0x3fc98d00

A2 : 0x00000000 A3 : 0x3fc98f34 A4 : 0x0000000a A5 :␣

,→0x3fc98d20

A6 : 0x3fc98d00 A7 : 0x0000000c A8 : 0x8200ca00 A9 :␣

,→0x3fc989b0

A10 : 0x00000002 A11 : 0xffffffff A12 : 0x00000002 A13 :␣

,→0x3fc98bc0

A14 : 0x3fc989c0 A15 : 0x00000001 SAR : 0x00000019 EXCCAUSE:␣

,→0x0000001c

EXCVADDR: 0x00000008 LBEG : 0x400556d5 LEND : 0x400556e5 LCOUNT :␣

,→0xfffffff9

Backtrace: 0x42016d2c:0x3fc98d00 0x420088a9:0x3fc98d20 0x420180ff:0x3fc98d40␣

,→0x4037a2dd:0x3fc98d70

You can further use the addr2line command to parse the Backtrace into readable function names based on the .elf
file. An example command is as follows:

xtensa-esp32s3-elf-addr2line -pfiaC -e path.elf 0x42016d2c:0x3fc98d00

The corresponding result is:

Espressif Systems 71 Release master

Submit Document Feedback
Chapter 2. ESP Friends

xtensa-esp32s3-elf-addr2line -pfiaC -e ./build/idf_debug_method.elf␣

,→ 0x42016d2c:0x3fc98d00 0x420088a9:0x3fc98d20 0x420180ff:0x3fc98d40␣
,→0x4037a2dd:0x3fc98d70

0x42016d2c: new_monkey_born at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:18

0x420088a9: app_main at /home/libo/test_github/idf_debug_method/main/idf_debug_

,→method.c:70

0x420180ff: main_task at /home/libo/esp/github_master/components/freertos/app_

,→startup.c:208 (discriminator 13)

0x4037a2dd: vPortTaskWrapper at /home/libo/esp/github_master/components/freertos/

,→FreeRTOS-Kernel/portable/xtensa/port.c:162

If you use IDF monitor to print logs, it will automatically call the above addr2line and print the parsed results, as
shown below:

Guru Meditation Error: Core 0 panic'ed (LoadProhibited). Exception was unhandled.

Core 0 register dump:

PC : 0x42016d2f PS : 0x00060c30 A0 : 0x820088ac A1 :␣
,→0x3fc98d00

0x42016d2f: new_monkey_born at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:19

A2 : 0x00000000 A3 : 0x3fc98f34 A4 : 0x0000000a A5 :␣

,→ 0x3fc98d20
A6 : 0x3fc98d00 A7 : 0x0000000c A8 : 0x8200ca00 A9 :␣
,→0x3fc989b0

A10 : 0x00000002 A11 : 0xffffffff A12 : 0x00000002 A13 :␣

,→0x3fc98bc0

A14 : 0x3fc989c0 A15 : 0x00000001 SAR : 0x00000019 EXCCAUSE:␣

,→0x0000001c

EXCVADDR: 0x00000008 LBEG : 0x400556d5 LEND : 0x400556e5 LCOUNT :␣

,→0xfffffff9

0x400556d5: strlen in ROM

0x400556e5: strlen in ROM

Backtrace: 0x42016d2c:0x3fc98d00 0x420088a9:0x3fc98d20 0x420180ff:0x3fc98d40␣

,→0x4037a2dd:0x3fc98d70

0x42016d2c: new_monkey_born at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:18

0x420088a9: app_main at /home/libo/test_github/idf_debug_method/main/idf_debug_

,→method.c:70

0x420180ff: main_task at /home/libo/esp/github_master/components/freertos/app_

,→startup.c:208 (discriminator 13)

0x4037a2dd: vPortTaskWrapper at /home/libo/esp/github_master/components/freertos/

,→FreeRTOS-Kernel/portable/xtensa/port.c:162

Now, based on the detailed backtrace log, Guru Meditation Error, and the pointers:
• PC: Program Counter
• EXCVADDR: Exception Vector Address
you can further debug and analyze the common causes of Guru Meditation errors, as explained in the section on
Locating Problems Using Guru Meditation Error Printing in the documentation.

RISC-V Backtrace Currently, ESP uses RISC-V architecture for chips such as ESP32-C3, ESP32-C2, ESP32-C6,
and ESP32-H2.

Espressif Systems 72 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Here is an example of error logs corresponding to RISC-V:

Guru Meditation Error: Core 0 panic'ed (Load access fault). Exception was␣
,→unhandled.

Core 0 register dump:

MEPC : 0x42007988 RA : 0x42007a4e SP : 0x3fc8fed0 GP :␣
,→0x3fc8b200

TP : 0x3fc870f8 T0 : 0x4005890e T1 : 0x3fc8fb2c T2 :␣

,→0x00000000

S0/FP : 0x0000000a S1 : 0x3fc90948 A0 : 0x00000000 A1 :␣

,→0x3fc8fb08

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000000 A5 :␣

,→0x00000009

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000005 MTVAL :␣

,→0x00000008

MHARTID : 0x00000000

Stack memory:
3fc8fed0: 0x3c021bd0 0x00000000 0x3c022000 0x42015de4 0x00000000 0x00001388␣
,→0x00000001 0x00000000

3fc8fef0: 0x00000000 0x00000000 0x00000000 0x40384538 0x00000000 0x00000000␣

,→0x00000000 0x00000000

You can further use the addr2line command to parse the Backtrace into readable function names based on the .elf
file. An example command is as follows:

riscv32-esp-elf-addr2line -pfiaC -e path.elf 0x42007988 0x42007a4e

The corresponding result is:

riscv32-esp-elf-addr2line -pfiaC -e ./build/idf_debug_method.elf 0x42007988␣

,→ 0x42007a4e
0x42007988: new_monkey_born at /home/libo/test_github/idf_debug_method/main/idf_
,→debug_method.c:19

0x42007a4e: app_main at /home/libo/test_github/idf_debug_method/main/idf_debug_

,→method.c:71

If you use IDF monitor to print logs, it will automatically call the above addr2line and print the parsed results, as
shown below:

Guru Meditation Error: Core 0 panic'ed (Load access fault). Exception was␣
,→unhandled.

Stack dump detected

Core 0 register dump:
MEPC : 0x42007988 RA : 0x42007a4e SP : 0x3fc8fed0 GP :␣
,→0x3fc8b200

0x42007988: new_monkey_born at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:19

0x42007a4e: app_main at /home/libo/test_github/idf_debug_method/main/idf_debug_

,→method.c:71

(continues on next page)

Espressif Systems 73 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

TP : 0x3fc870f8 T0 : 0x4005890e T1 : 0x3fc8fb2c T2 :␣
,→0x00000000

0x4005890e: memset in ROM

S0/FP : 0x0000000a S1 : 0x3fc90948 A0 : 0x00000000 A1 :␣

,→0x3fc8fb08

A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000000 A5 :␣

,→0x00000009

A6 : 0x60023000 A7 : 0x0000000a S2 : 0x00000000 S3 :␣

,→0x00000000

S4 : 0x00000000 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x00000000 T4 : 0x00000000 T5 : 0x00000000 T6 :␣

,→0x00000000

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000005 MTVAL :␣

,→0x00000008

0x40380001: _vector_table at ??:?

MHARTID : 0x00000000

Backtrace:

new_monkey_born (zoo=zoo@entry=0x0) at /home/libo/test_github/idf_debug_method/

,→main/idf_debug_method.c:19

19 zoo->monkey++;
#0 new_monkey_born (zoo=zoo@entry=0x0) at /home/libo/test_github/idf_debug_method/
,→main/idf_debug_method.c:19

#1 0x42007a4e in app_main () at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:70

#2 0x42015de4 in main_task (args=<error reading variable: value has been␣

,→optimized out>) at /home/libo/esp/github_master/components/freertos/app_startup.

,→c:208

#3 0x40384538 in vPortTaskWrapper (pxCode=<optimized out>, pvParameters=

,→<optimized out>) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/riscv/port.c:234

Now, you can further debug and analyze the common causes of Guru Meditation errors using the detailed backtrace
log, Guru Meditation Error, and the pointers:
• MEPC: Machine Exception Program Counter
• MTVAL: Machine Trap Value
Further debugging and analysis can be conducted based on pointers, Guru Meditation errors, and common causes of
Guru Meditation errors, as explained in the section on Locating Problems Using Guru Meditation Error Printing.

Common Backtrace Errors Common Backtrace errors are summarized in the table below. Detailed information
is also provided in the section on Locating Problems Using Guru Meditation Error Printing.

Espressif Systems 74 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Table 2: Xtensa and RISC-V Exception Mapping

Xtensa RISC-V Why Where
IllegalInstruction IllegalInstruction SPI Flash IO Broken / task re- Hardware or Soft-
turn without vTaskDelete / non- ware
void function return void
• Instruction Address Mis- not 2-byte aligned PC(0x4_),
aligned MEPC(0x3_-0x6_)
InstrFetchProhibited Instruction Access Fault not in IRAM/RAM range PC(0x4_),
MEPC(0x3_-0x6_)
• Memory Protection Fault write to IRAM or execute from MEPC(0x3_-0x6_)
DRAM
LoadProhibited Load Access Fault Read from NULL/invalid EXCVADDR, MT-
pointer VAL
StoreProhibited Store Access Fault Save to NULL/invalid pointer EXCVADDR, MT-
VAL
LoadStoreAlignment Load/Store Address Mis- IRAM use as DRAM, but not 4- EXCVADDR, MT-
aligned byte aligned VAL
IntegerDivideByZero • calculate n/0 PC(0x4_),
MEPC(0x3_-0x6_)
LoadStoreError • write to read-only IROM EXCVADDR, MT-
DROM VAL
Interrupt Watchdog Interrupt Watchdog Interrupt timeout/ disabled •
Timeout on CPU0/CPU1 Timeout on CPU0/CPU1
Cache disabled but Cache error set FLAG_IRAM but PC(0x4_),
cached memory region not all data/functions in MEPC(0x3_-0x6_)
accessed IRAM/DRAM
Brownout Brownout Supply voltage lower than Hardware
threshold
rst:0x10 rst:0x10 no valid program in flash Hardware
(RTCWDT_RTC_RESET) (RTCWDT_RTC_RESET)
rst:0x7 rst:0x7 Watchdog timeout Flash or PSRAM
(TG0WDT_SYS_RST) (TG0WDT_SYS_RST) Pin / software
Corrupt Heap Corrupt Heap Heap corruption detected Need further analy-
sis
• Stack protection fault Stack overflow Need further analy-
sis
Stack smashing protect Stack smashing protect Stack overflow Need further analy-
failure failure sis
Core 0 panic ed Excep- Stack canary watchpoint Stack overflow Need further analy-
tion was unhandled triggered (task_name) sis
UBSAN UBSAN Undefined behavior Need further analy-
sis

Core Dump Overview This section can be referred to in the Core Dump documentation. A brief summary is
provided below:
• Core Dump is more comprehensive than backtrace, including stack dumps for each task.
• Core Dump can be printed to the terminal or saved to flash (type: data, subtype: coredump).
• After saving Core Dump to flash, it can be analyzed directly using the idf.py coredump-info command.
• The Core Dump serial data is in BASE64 format as a binary string. Copy and save it as text, then use the idf.py
coredump-info -c </path/to/saved/base64/text> command for analysis.
• esp monitor can parse Core Dump information and display it in a readable format.
• idf.py coredump-debug can restore the scene, and GDB debugging will be opened to view variable values.

Espressif Systems 75 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Xtensa Core Dump typically looks like the following:

Initiating core dump!
I (423) esp_core_dump_uart: Press Enter to print core dump to UART...
I (431) esp_core_dump_uart: Print core dump to uart...
Core dump started (further output muted)
Received 13 kB...
Core dump finished!
===============================================================
==================== ESP32 CORE DUMP START ====================
The ROM ELF file won't load automatically since it was not found for the provided␣
,→chip type.

Crashed task handle: 0x3fc9a790, name: 'main', GDB name: 'process 1070180240'

================== CURRENT THREAD REGISTERS ===================

exccause 0x1c (LoadProhibitedCause)
excvaddr 0x8
epc1 0x40378347
epc2 0x0
epc3 0x0
epc4 0x0
epc5 0x0
epc6 0x0
eps2 0x0
eps3 0x0
eps4 0x0
eps5 0x0
eps6 0x0
pc 0x42018677 0x42018677 <new_monkey_born+7>
lbeg 0x400556d5 1074091733
lend 0x400556e5 1074091749
lcount 0xfffffffc 4294967292
sar 0x1a 26
ps 0x60c20 396320
threadptr <unavailable>
br <unavailable>
scompare1 <unavailable>
acclo <unavailable>
acchi <unavailable>
m0 <unavailable>
m1 <unavailable>
m2 <unavailable>
m3 <unavailable>
expstate <unavailable>
f64r_lo <unavailable>
f64r_hi <unavailable>
f64s <unavailable>
fcr <unavailable>
fsr <unavailable>
a0 0x8200a136 -2113887946
a1 0x3fc9a5a0 1070179744
a2 0x0 0
a3 0x3fc9a7ec 1070180332
a4 0x3c023088 1006776456
a5 0x3fc9a5d0 1070179792
a6 0x3fc9a5b0 1070179760
a7 0xc 12
a8 0x8200e2b8 -2113871176
a9 0x3fc9a250 1070178896
a10 0x10 16
a11 0xffffffff -1
a12 0x10 16
(continues on next page)

Espressif Systems 76 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

a13 0x3fc9a460 1070179424
a14 0x3fc9a260 1070178912
a15 0x1 1

==================== CURRENT THREAD STACK =====================

#0 new_monkey_born (zoo=0x0) at /home/libo/test_github/idf_debug_method/main/idf_
,→debug_method.c:21

#1 0x4200a136 in app_main () at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:57

#2 0x42019ade in main_task (args=<optimized out>) at /home/libo/esp/github_master/

,→components/freertos/app_startup.c:208

#3 0x4037a2ec in vPortTaskWrapper (pxCode=0x42019a38 <main_task>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

======================== THREADS INFO =========================

Id Target Id Frame
* 1 process 1070180240 new_monkey_born (zoo=0x0) at /home/libo/test_github/idf_
,→debug_method/main/idf_debug_method.c:21

2 process 1070182124 vPortTaskWrapper (pxCode=0x0, pvParameters=0x0) at /home/

,→libo/esp/github_master/components/freertos/FreeRTOS-Kernel/portable/xtensa/port.

,→c:161

3 process 1070184008 0x40378326 in esp_cpu_wait_for_intr () at /home/libo/esp/

,→github_master/components/esp_hw_support/cpu.c:145

4 process 1070169660 0x400559e0 in ?? ()

5 process 1070175732 0x400559e0 in ?? ()
6 process 1070171288 0x400559e0 in ?? ()

==================== THREAD 1 (TCB: 0x3fc9a790, name: 'main') =====================

#0 new_monkey_born (zoo=0x0) at /home/libo/test_github/idf_debug_method/main/idf_
,→debug_method.c:21

#1 0x4200a136 in app_main () at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:57

#2 0x42019ade in main_task (args=<optimized out>) at /home/libo/esp/github_master/

,→components/freertos/app_startup.c:208

#3 0x4037a2ec in vPortTaskWrapper (pxCode=0x42019a38 <main_task>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

==================== THREAD 2 (TCB: 0x3fc9aeec, name: 'IDLE0')␣

,→=====================

#0 vPortTaskWrapper (pxCode=0x0, pvParameters=0x0) at /home/libo/esp/github_

,→master/components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:161

#1 0x40000000 in ?? ()

==================== THREAD 3 (TCB: 0x3fc9b648, name: 'IDLE1')␣

,→=====================

#0 0x40378326 in esp_cpu_wait_for_intr () at /home/libo/esp/github_master/

,→components/esp_hw_support/cpu.c:145

#1 0x42002be5 in esp_vApplicationIdleHook () at /home/libo/esp/github_master/

,→components/esp_system/freertos_hooks.c:59

#2 0x4037b038 in prvIdleTask (pvParameters=0x0) at /home/libo/esp/github_master/

,→components/freertos/FreeRTOS-Kernel/tasks.c:4170

#3 0x4037a2ec in vPortTaskWrapper (pxCode=0x4037b02c <prvIdleTask>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

==================== THREAD 4 (TCB: 0x3fc97e3c, name: 'ipc0') =====================

#0 0x400559e0 in ?? ()
#1 0x4037a692 in vPortClearInterruptMaskFromISR (prev_level=<optimized out>) at /
,→home/libo/esp/github_master/components/freertos/FreeRTOS-Kernel/portable/xtensa/

,→include/freertos/portmacro.h:582
(continues on next page)

Espressif Systems 77 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

#2 vPortExitCritical (mux=<optimized out>) at /home/libo/esp/github_master/
,→components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:532

#3 0x4037c0c5 in xTaskGenericNotifyWait (uxIndexToWait=0, ulBitsToClearOnEntry=

,→<optimized out>, ulBitsToClearOnExit=4294967295, pulNotificationValue=0x3fc97ca0,

,→ xTicksToWait=4294967295) at /home/libo/esp/github_master/components/freertos/

,→FreeRTOS-Kernel/tasks.c:5644

#4 0x40378104 in ipc_task (arg=0x0) at /home/libo/esp/github_master/components/

,→esp_system/esp_ipc.c:58

#5 0x4037a2ec in vPortTaskWrapper (pxCode=0x403780d4 <ipc_task>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

==================== THREAD 5 (TCB: 0x3fc995f4, name: 'esp_timer')␣

,→=====================

#0 0x400559e0 in ?? ()
#1 0x4037a692 in vPortClearInterruptMaskFromISR (prev_level=<optimized out>) at /
,→home/libo/esp/github_master/components/freertos/FreeRTOS-Kernel/portable/xtensa/

,→include/freertos/portmacro.h:582

#2 vPortExitCritical (mux=<optimized out>) at /home/libo/esp/github_master/

,→components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:532

#3 0x4037bf89 in ulTaskGenericNotifyTake (uxIndexToWait=0, xClearCountOnExit=1,␣

,→xTicksToWait=<optimized out>) at /home/libo/esp/github_master/components/

,→freertos/FreeRTOS-Kernel/tasks.c:5565

#4 0x42006143 in timer_task (arg=0x0) at /home/libo/esp/github_master/components/

,→esp_timer/src/esp_timer.c:477

#5 0x4037a2ec in vPortTaskWrapper (pxCode=0x42006134 <timer_task>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

==================== THREAD 6 (TCB: 0x3fc98498, name: 'ipc1') =====================

#0 0x400559e0 in ?? ()
#1 0x4037a692 in vPortClearInterruptMaskFromISR (prev_level=<optimized out>) at /
,→home/libo/esp/github_master/components/freertos/FreeRTOS-Kernel/portable/xtensa/

,→include/freertos/portmacro.h:582

#2 vPortExitCritical (mux=<optimized out>) at /home/libo/esp/github_master/

,→components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:532

#3 0x4037c0c5 in xTaskGenericNotifyWait (uxIndexToWait=0, ulBitsToClearOnEntry=

,→<optimized out>, ulBitsToClearOnExit=4294967295, pulNotificationValue=0x3fc98300,

,→ xTicksToWait=4294967295) at /home/libo/esp/github_master/components/freertos/

,→FreeRTOS-Kernel/tasks.c:5644

#4 0x40378104 in ipc_task (arg=0x1) at /home/libo/esp/github_master/components/

,→esp_system/esp_ipc.c:58

#5 0x4037a2ec in vPortTaskWrapper (pxCode=0x403780d4 <ipc_task>,␣

,→pvParameters=0x1) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/xtensa/port.c:162

======================= ALL MEMORY REGIONS ========================

Name Address Size Attrs
.rtc.force_fast 0x600fe010 0x0 RW
.rtc_noinit 0x50000000 0x0 RW
.rtc.force_slow 0x50000000 0x0 RW
.iram0.vectors 0x40374000 0x403 R XA
.iram0.text 0x40374404 0xd56f R XA
.dram0.data 0x3fc91a00 0x3e84 RW A
.flash.text 0x42000020 0x1a41b R XA
.flash.appdesc 0x3c020020 0x100 R A
.flash.rodata 0x3c020120 0xae5c RW A
.flash.rodata_noload 0x3c02af7c 0x0 RW
.ext_ram.bss 0x3c030000 0x0 RW
.iram0.data 0x40381a00 0x0 RW
(continues on next page)

Espressif Systems 78 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

.iram0.bss 0x40381a00 0x0 RW
.dram0.heap_start 0x3fc96a28 0x0 RW
.coredump.tasks.data 0x3fc9a790 0x154 RW
.coredump.tasks.data 0x3fc9a4e0 0x2a0 RW
.coredump.tasks.data 0x3fc9aeec 0x154 RW
.coredump.tasks.data 0x3fc9ace0 0x200 RW
.coredump.tasks.data 0x3fc9b648 0x154 RW
.coredump.tasks.data 0x3fc9b3c0 0x280 RW
.coredump.tasks.data 0x3fc97e3c 0x154 RW
.coredump.tasks.data 0x3fc97b90 0x2a0 RW
.coredump.tasks.data 0x3fc995f4 0x154 RW
.coredump.tasks.data 0x3fc99350 0x290 RW
.coredump.tasks.data 0x3fc98498 0x154 RW
.coredump.tasks.data 0x3fc981f0 0x2a0 RW

===================== ESP32 CORE DUMP END =====================

===============================================================
Done!
Coredump checksum='7b5945fe'
I (1690) esp_core_dump_uart: Core dump has been written to uart.

Xtensa Core Dump typically looks like the following:

Initiating core dump!

I (696) esp_core_dump_uart: Press Enter to print core dump to UART...
I (703) esp_core_dump_uart: Print core dump to uart...
Core dump started (further output muted)
Received 3 kB...
Core dump finished!
===============================================================
==================== ESP32 CORE DUMP START ====================

Crashed task handle: 0x3fc91594, name: 'main', GDB name: 'process 1070142868'

================== CURRENT THREAD REGISTERS ===================

ra 0x42009404 0x42009404 <app_main+56>
sp 0x3fc91510 0x3fc91510
gp 0x3fc8b400 0x3fc8b400 <__c.29+52>
tp 0x3fc88368 0x3fc88368
t0 0x4005890e 1074104590
t1 0x3fc9116c 1070141804
t2 0x0 0
fp 0x3c022000 0x3c022000
s1 0x3fc91f98 1070145432
a0 0x0 0
a1 0x3fc91148 1070141768
a2 0x0 0
a3 0x1 1
a4 0x0 0
a5 0x0 0
a6 0x60023000 1610756096
a7 0xa 10
s2 0x0 0
s3 0x0 0
s4 0x0 0
s5 0x0 0
s6 0x0 0
s7 0x0 0
s8 0x0 0
s9 0x0 0
s10 0x0 0
(continues on next page)

Espressif Systems 79 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

s11 0x0 0
t3 0x0 0
t4 0x0 0
t5 0x0 0
t6 0x0 0
pc 0x4200939e 0x4200939e <new_monkey_born+4>

==================== CURRENT THREAD STACK =====================

#0 new_monkey_born (zoo=zoo@entry=0x0) at /home/libo/test_github/idf_debug_method/
,→main/idf_debug_method.c:21

#1 0x42009404 in app_main () at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:55

#2 0x42017976 in main_task (args=<error reading variable: value has been␣

,→optimized out>) at /home/libo/esp/github_master/components/freertos/app_startup.

,→c:208

#3 0x403845bc in vPortTaskWrapper (pxCode=<optimized out>, pvParameters=

,→<optimized out>) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/riscv/port.c:234

======================== THREADS INFO =========================

Id Target Id Frame
* 1 process 1070142868 new_monkey_born (zoo=zoo@entry=0x0) at /home/libo/test_
,→github/idf_debug_method/main/idf_debug_method.c:21

2 process 1070144752 vPortTaskWrapper (pxCode=0x40384f20 <prvIdleTask>,␣

,→pvParameters=0x0) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/riscv/port.c:230

3 process 1070138360 0x40384796 in vPortClearInterruptMaskFromISR (prev_int_

,→level=1) at /home/libo/esp/github_master/components/freertos/FreeRTOS-Kernel/

,→portable/riscv/port.c:417

==================== THREAD 1 (TCB: 0x3fc91594, name: 'main') =====================

#0 new_monkey_born (zoo=zoo@entry=0x0) at /home/libo/test_github/idf_debug_method/
,→main/idf_debug_method.c:21

#1 0x42009404 in app_main () at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:55

#2 0x42017976 in main_task (args=<error reading variable: value has been␣

,→optimized out>) at /home/libo/esp/github_master/components/freertos/app_startup.

,→c:208

#3 0x403845bc in vPortTaskWrapper (pxCode=<optimized out>, pvParameters=

,→<optimized out>) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/riscv/port.c:234

==================== THREAD 2 (TCB: 0x3fc91cf0, name: 'IDLE') =====================

#0 vPortTaskWrapper (pxCode=0x40384f20 <prvIdleTask>, pvParameters=0x0) at /home/
,→libo/esp/github_master/components/freertos/FreeRTOS-Kernel/portable/riscv/port.

,→c:230

#1 0x00000000 in ?? ()
Backtrace stopped: frame did not save the PC

==================== THREAD 3 (TCB: 0x3fc903f8, name: 'esp_timer')␣

,→=====================

#0 0x40384796 in vPortClearInterruptMaskFromISR (prev_int_level=1) at /home/libo/

,→esp/github_master/components/freertos/FreeRTOS-Kernel/portable/riscv/port.c:417

#1 0x403847f8 in vPortExitCritical () at /home/libo/esp/github_master/components/

,→freertos/FreeRTOS-Kernel/portable/riscv/port.c:517

#2 0x40385cfa in ulTaskGenericNotifyTake (uxIndexToWait=uxIndexToWait@entry=0,␣

,→xClearCountOnExit=xClearCountOnExit@entry=1,␣

,→xTicksToWait=xTicksToWait@entry=4294967295) at /home/libo/esp/github_master/

,→components/freertos/FreeRTOS-Kernel/tasks.c:5565

#3 0x420046b6 in timer_task (arg=<error reading variable: value has been␣

,→optimized out>) at /home/libo/esp/github_master/components/esp_timer/src/esp_

,→timer.c:477
(continues on next page)

Espressif Systems 80 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

#4 0x403845bc in vPortTaskWrapper (pxCode=<optimized out>, pvParameters=
,→<optimized out>) at /home/libo/esp/github_master/components/freertos/FreeRTOS-

,→Kernel/portable/riscv/port.c:234

======================= ALL MEMORY REGIONS ========================

Name Address Size Attrs
.rtc.force_fast 0x50000010 0x0 RW
.rtc_noinit 0x50000010 0x0 RW
.rtc.force_slow 0x50000010 0x0 RW
.iram0.text 0x40380000 0xab8a R XA
.dram0.data 0x3fc8ac00 0x21c0 RW A
.flash.text 0x42000020 0x18504 R XA
.flash.appdesc 0x3c020020 0x100 R A
.flash.rodata 0x3c020120 0x9218 RW A
.eh_frame 0x3c029338 0xe0 R A
.flash.rodata_noload 0x3c029418 0x0 RW
.iram0.data 0x4038ac00 0x0 RW
.iram0.bss 0x4038ac00 0x0 RW
.dram0.heap_start 0x3fc8e490 0x0 RW
.coredump.tasks.data 0x3fc91594 0x154 RW
.coredump.tasks.data 0x3fc91470 0x110 RW
.coredump.tasks.data 0x3fc91cf0 0x154 RW
.coredump.tasks.data 0x3fc91c40 0xa0 RW
.coredump.tasks.data 0x3fc903f8 0x154 RW
.coredump.tasks.data 0x3fc90310 0xe0 RW

===================== ESP32 CORE DUMP END =====================

===============================================================
Done!
Coredump checksum='704e2165'
I (1064) esp_core_dump_uart: Core dump has been written to uart.

Certainly, the Core Dump contains various detailed information, some of which is already included in the backtrace,
such as the current Thread/Task registers and current Thread information. The additional need for Core Dump
information often arises because it prints the state of all tasks running at the time of the current exception. This can
be helpful in resolving issues like watchdog problems associated with tasks.

Locating Memory Issues (Memory Stompings, Memory Leaks, etc.)

Common memory issues include the following:

• Heap memory leak
• Heap memory stomping
• Stack overflow
• Stack memory stomping
• Pointer used after being freed
• Pointer used before being initialized
• Double free
This section will explain the general debugging methods for the above memory issues one by one.

Heap Memory Leak Heap memory leaks often manifest as a program allocating a block of heap memory, but not
correctly freeing it after use, leading to a memory leak. This can cause the memory consumed by the program to
gradually increase during runtime, and may eventually exhaust the system s available memory.
This part can refer to the Heap Memory Debugging Document, the key points are summarized as follows:
• You can use heap_caps_get_per_task_info to get the memory allocation status of all tasks

Espressif Systems 81 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• You can use heap_caps_get_free_size to compare the remaining memory situation and roughly determine the
leak area
• Enable CONFIG_HEAP_TRACING_STANDALONE or CONFIG_HEAP_TRACING_TOHOST
• STANDALONE mode requires buffer allocation, directly record, calculate, and print results on ESP, but RISC-
V architecture cannot locate code lines
• TOHOST requires UART/JTAG to use app_trace capture, analyze on the host, no extra buffer is needed, code
lines can be located
• heap_trace_init_standalone initializes the buffer, heap_trace_start(HEAP_TRACE_LEAKS) starts recording
• heap_trace_stop() stops recording, use heap_trace_dump() to print analysis results
The typical log after using the above heap memory debugging method is as follows:
1. Xtensa

====== Heap Trace: 2 records (100 capacity) ======

36 bytes (@ 0x3fc9c524, Internal) allocated CPU 0 ccount 0x02f204e0 caller␣
,→0x42008cfd:0x42008d73

0x42008cfd: zoo_create at /home/libo/test_github/idf_debug_method/main/idf_debug_

,→method.c:68

0x42008d73: mem_leak_task at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:96 (discriminator 3)

24 bytes (@ 0x3fc9c54c, Internal) allocated CPU 0 ccount 0x02f20c00 caller␣

,→ 0x42008cfd:0x42008d73
0x42008cfd: zoo_create at /home/libo/test_github/idf_debug_method/main/idf_debug_
,→method.c:68

0x42008d73: mem_leak_task at /home/libo/test_github/idf_debug_method/main/idf_

,→debug_method.c:96 (discriminator 3)

====== Heap Trace Summary ======

Mode: Heap Trace Leaks
60 bytes 'leaked' in trace (2 allocations)
records: 2 (100 capacity, 3 high water mark)
total allocations: 3
total frees: 1
================================

2. RISC-V

====== Heap Trace: 3 records (100 capacity) ======

36 bytes (@ 0x3fc91574, Internal) allocated CPU 0 ccount 0x02cf6d38 caller
36 bytes (@ 0x3fc9159c, Internal) allocated CPU 0 ccount 0x02cf72cc caller
====== Heap Trace Summary ======
Mode: Heap Trace Leaks
72 bytes 'leaked' in trace (2 allocations)
records: 2 (100 capacity, 3 high water mark)
total allocations: 3
total frees: 1
================================

Heap Memory Stomping Heap memory stompings often occur when writing to or reading from heap memory, the
program accesses an area beyond the memory range allocated to it. This can lead to undefined behavior and corrupt
the program s memory structure. The corresponding log for this error is often:

assert failed: remove_free_block tlsf.c:331 (next && "next_free field can not be␣
,→null")

This part can refer to the Heap Memory Debugging Document, the key points are summarized as follows:
1. Locate Who and Where

Espressif Systems 82 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Enable memory debugging, raise the heap memory debugging level CON-
FIG_HEAP_CORRUPTION_DETECTION to light impact or comprehensive:
– Basic (default): Use heap properties to detect if it has been contaminated
– Light impact : Add special bytes 0xABBA1234 0xBAAD5678 before and after the allocated memory
– Comprehensive : Add uninitialized-access and use-after-free bugs check on the basis of light impact.
When memory is allocated, all memory is initialized to 0xce, and all spaces are assigned to 0xfe after
memory is released
• After enabling memory debugging, wait for crash or actively call to check memory integrity
heap_caps_check_integrity_all to trigger crash before and after the suspected memory stomping position. If
the stomping address has been located, you can directly use heap_caps_check_integrity_addr.
– Step on the tail, the current memory block operation is out of bounds CORRUPT HEAP: Bad tail at
0x3fc9ad5a. Expected 0xbaad5678 got 0x02020202
– Step on the head, the previous memory block is out of bounds CORRUPT HEAP: Bad head at 0x3fc9a94c.
Expected 0xabba1234 got 0x00000000
• Two methods can confirm the neighbors before and after the memory block
– Use heap trace, call heap_trace_start(HEAP_TRACE_ALL) to collect information
– Use heap_caps_dump_all to print the collected information (need to print before and after memory al-
location)

Note: The specific method of confirming the memory block status described above can refer to Heap Memory
Tracking.

2. Locate When
• You can set the CPU breakpoint in the code through esp_cpu_set_watchpoint(0, (void
*)0x3fc9a94c, 4, ESP_CPU_WATCHPOINT_STORE);. If you don t know which kernel, you need
to call both kernels
• The CPU will trigger a breakpoint when data is written to this address, and the code line can be
located through PC, refer to the log as follows:

Guru Meditation Error: Core 0 panic'ed (Unhandled debug exception).

Debug exception reason: Watchpoint 0 triggered
Core 0 register dump:
PC : 0x400570e8 PS : 0x00060c36 A0 : 0x82008d43 A1 ␣
,→: 0x3fc99f10

0x400570e8: memset in ROM

A2 : 0x3fc9b3ac A3 : 0x00000000 A4 : 0x000003e8 A5 ␣

,→: 0x3fc9b75c

A6 : 0x00000000 A7 : 0x0000003e A8 : 0x8200333d A9 ␣

,→: 0x3fc99ee0

A10 : 0x00000400 A11 : 0x00060c20 A12 : 0x00000000 A13 ␣

,→: 0x00060c23

A14 : 0xb33fffff A15 : 0xb33fffff SAR : 0x00000004 ␣

,→EXCCAUSE: 0x00000001

EXCVADDR: 0x00000000 LBEG : 0x400570e8 LEND : 0x400570f3 LCOUNT ␣

,→: 0x00000002

Backtrace: 0x400570e5:0x3fc99f10 0x42008d40:0x3fc99f20␣

,→0x4201874b:0x3fc99f50 0x4037a80d:0x3fc99f80

0x400570e5: memset in ROM

0x42008d40: app_main at /home/libo/test_github/idf_debug_method/main/idf_
,→debug_method.c:169 (discriminator 3)

0x4201874b: main_task at /home/libo/esp/github_master/components/freertos/

,→app_startup.c:208 (discriminator 13)

0x4037a80d: vPortTaskWrapper at /home/libo/esp/github_master/components/

,→freertos/FreeRTOS-Kernel/portable/xtensa/port.c:162

Espressif Systems 83 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Stack Overflow The manifestation of stack overflow often occurs when using stack memory during function calls.
If recursion or too many local variables are involved, the stack size may exceed the system s allowed limit, resulting
in a stack overflow. The ESP-IDF provides the following stack overflow detection mechanisms:
1. ESP-IDF FreeRTOS enables stack overflow detection by default. If a stack overflow is detected, it triggers an
assertion, printing the corresponding stack overflow information. A typical log looks like this:

***ERROR*** A stack overflow in task test_task has been detected.

For more details, refer to the Stack Overflow section.

2. ESP-IDF supports enabling the End of Stack Watchpoint, which triggers a breakpoint before FreeRTOS stack
overflow assertion.
3. The RISC-V platform supports enabling hardware stack overflow detection (Stack protection fault). For details,
see Hardware Stack Protection.

Stack Memory Stomping The manifestation of stack memory stomping is similar to heap memory stomping but
occurs when the program uses stack memory. Writing or reading data beyond the allocated stack memory range may
lead to program errors. Here are some key points to note:
1. It may lead to task stack overflow, generally detectable through FreeRTOS stack overflow mechanisms.
2. It may result in the overwriting of local variable values, causing unexpected program behavior.
3. It may cause the modification of local pointer variables, accessing illegal instructions/data addresses, leading
to program crashes.
4. It may result in the overwriting of the function return address, causing the program to jump to an incorrect
address and crash.
A simple example of error code is as follows:

int vulnerableFunction() {
int localArray[5]; // Array allocated on the stack

// Writing beyond the bounds of the array

for (int i = 0; i <= 5; ++i) {
localArray[i] = i;
}

return localArray[0];
}

void app_main() {
printf("Before vulnerable function.\n");

vulnerableFunction(); // Call the function that causes stack memory corruption

printf("After vulnerable function.\n");

}

It s worth mentioning that ESP-IDF performs partial compile-time checks for such errors and issues warnings (though
the compilation still passes). The compile-time warning log looks like this:

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c: In function 'vulnerableFunction':

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c:20:23: warning: iteration 5 invokes undefined behavior [-

,→Waggressive-loop-optimizations]

20 | localArray[i] = i;
| ~~~~~~~~~~~~~~^~~
/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c:19:23: note: within this loop

19 | for (int i = 0; i <= 5; ++i) {

Espressif Systems 84 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Pointers Used After Release The manifestation of using pointers after their release often occurs when a program
releases a block of memory but continues to use a pointer that points to that memory. This may result in accessing
invalid memory, leading to crashes or undefined behavior.
This issue can cause various errors that are challenging to trace through actual errors. Therefore, it is crucial to pay
special attention to pointer usage during the development process. A simple example of erroneous code is as follows:

void app_main(void)
{
int *number = (int *)malloc(sizeof(int)); // Allocate memory for an integer

if (number == NULL) {
// Handle memory allocation failure
printf("Memory allocation failed.\n");
}

*number = 42; // Assign a value to the allocated memory

printf("Value before freeing: %d\n", *number);

free(number); // Free the allocated memory

// Attempt to use the pointer after freeing

// This will result in undefined behavior
printf("Value after freeing: %d\n", *number);
}

It s worth noting that ESP-IDF can detect some of these errors during compilation and issue warnings (though the
compilation may still succeed). Compilation-time warning logs may look like this:

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c: In function 'app_main':

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c:32:5: warning: pointer 'number' used after 'free' [-Wuse-

,→after-free]

32 | printf("Value after freeing: %d\n", *number);

| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/zhengzhong/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/
,→main/hello_world_main.c:28:5: note: call to 'free' here

28 | free(number); // Free the allocated memory

Pointers Used Before Initialization The manifestation of using pointers before their initialization often occurs
when a program attempts to use an uninitialized pointer, resulting in access to unknown memory regions and causing
unstable behavior.
This issue can cause various errors that are challenging to trace through actual errors. Therefore, it is crucial to pay
special attention to pointer initialization during the development process. A simple example of erroneous code is as
follows:

void app_main(void)
{
int *number; // Pointer declared but not initialized

// Attempt to dereference the uninitialized pointer

// This will result in undefined behavior
printf("Value: %d\n", *number);

It s worth noting that ESP-IDF often detects some of these errors during compilation and issues error messages.
Compilation-time error logs may look like this:

Espressif Systems 85 Release master

Submit Document Feedback
Chapter 2. ESP Friends

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c: In function 'app_main':

/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c:21:5: error: 'number' is used uninitialized [-

,→Werror=uninitialized]

21 | printf("Value: %d\n", *number);

| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/user/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/main/
,→hello_world_main.c:17:10: note: 'number' was declared here

17 | int *number; // Pointer declared but not initialized

| ^~~~~~
cc1: some warnings being treated as errors

Double Free The manifestation of double-free often occurs when a program releases memory that has already been
freed. This can lead to memory pool corruption, resulting in program crashes or other severe issues. An example of
erroneous code is as follows:
void app_main(void)
{
// Allocate a block of memory
int *data = (int *)malloc(sizeof(int));

// Check if memory allocation is successful

if (data != NULL) {
// Assign a value to the allocated memory
*data = 42;

// First free
free(data); // Line 26

// Second free (double-free)

free(data); // Line 29, this is incorrect and may lead to undefined␣
,→behavior

}
}

It s worth noting that ESP-IDF often detects some of these errors during compilation and issues warning messages.
Compilation-time warning logs may look like this:
/home/zhengzhong/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/
,→main/hello_world_main.c: In function 'app_main':

/home/zhengzhong/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/
,→main/hello_world_main.c:29:9: warning: pointer 'data' used after 'free' [-Wuse-

,→after-free]

29 | free(data); // This is incorrect and may lead to undefined behavior

| ^~~~~~~~~~
/home/zhengzhong/github/esp-idf/rel5.1/esp-idf/examples/get-started/hello_world/
,→main/hello_world_main.c:26:9: note: call to 'free' here

26 | free(data);
| ^~~~~~~~~~

Runtime error logs may look like this:

I (285) main_task: Calling app_main()

assert failed: tlsf_free tlsf.c:1119 (!block_is_free(block) && "block already␣

,→marked as free")

Core 0 register dump:

Stack dump detected
MEPC : 0x403805d8 RA : 0x403838e8 SP : 0x3fc8f330 GP :␣
,→0x3fc8ae00
(continues on next page)

Espressif Systems 86 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

0x403805d8: panic_abort at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/
,→components/esp_system/panic.c:452

0x403838e8: __ubsan_include at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/

,→components/esp_system/ubsan.c:313

TP : 0x3fc87110 T0 : 0x37363534 T1 : 0x7271706f T2 :␣

,→ 0x33323130
S0/FP : 0x00000069 S1 : 0x00000001 A0 : 0x3fc8f36c A1 :␣
,→0x3fc8acd1

A2 : 0x00000001 A3 : 0x00000029 A4 : 0x00000001 A5 :␣

,→0x3fc8c000

A6 : 0x7a797877 A7 : 0x76757473 S2 : 0x00000009 S3 :␣

,→0x3fc8f49e

S4 : 0x3fc8acd0 S5 : 0x00000000 S6 : 0x00000000 S7 :␣

,→0x00000000

S8 : 0x00000000 S9 : 0x00000000 S10 : 0x00000000 S11 :␣

,→0x00000000

T3 : 0x6e6d6c6b T4 : 0x6a696867 T5 : 0x66656463 T6 :␣

,→0x62613938

MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL :␣

,→0x00000000

0x40380001: _vector_table at ??:?

MHARTID : 0x00000000

Backtrace:

panic_abort (details=details@entry=0x3fc8f36c "assert failed: tlsf_free tlsf.

,→c:1119 (!block_is_free(block) && \"block already marked as free\")") at /home/

,→zhengzhong/github/esp-idf/rel5.1/esp-idf/components/esp_system/panic.c:452

452 *((volatile int *) 0) = 0; // NOLINT(clang-analyzer-core.

,→NullDereference) should be an invalid operation on targets

#0 panic_abort (details=details@entry=0x3fc8f36c "assert failed: tlsf_free tlsf.

,→c:1119 (!block_is_free(block) && \"block already marked as free\")") at /home/

,→zhengzhong/github/esp-idf/rel5.1/esp-idf/components/esp_system/panic.c:452

#1 0x403838e8 in esp_system_abort (details=details@entry=0x3fc8f36c "assert␣

,→failed: tlsf_free tlsf.c:1119 (!block_is_free(block) && \"block already marked␣

,→as free\")") at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/components/esp_

,→system/port/esp_system_chip.c:84

#2 0x403890e8 in __assert_func (file=file@entry=0x3c0212f3 "",␣

,→line=line@entry=1119, func=<optimized out>, func@entry=0x3c021984 <__func__.6> "

,→", expr=expr@entry=0x3c0217ec "") at /home/zhengzhong/github/esp-idf/rel5.1/esp-

,→idf/components/newlib/assert.c:81

#3 0x40387e5e in tlsf_free (tlsf=0x3fc8c574, ptr=ptr@entry=0x3fc8ff20) at /home/

,→zhengzhong/github/esp-idf/rel5.1/esp-idf/components/heap/tlsf/tlsf.c:1119

#4 0x40387a8e in multi_heap_free_impl (heap=0x3fc8c560, p=p@entry=0x3fc8ff20) at /

,→home/zhengzhong/github/esp-idf/rel5.1/esp-idf/components/heap/multi_heap.c:231

#5 0x40380b98 in heap_caps_free (ptr=ptr@entry=0x3fc8ff20) at /home/zhengzhong/

,→github/esp-idf/rel5.1/esp-idf/components/heap/heap_caps.c:388

#6 0x4038910e in free (ptr=ptr@entry=0x3fc8ff20) at /home/zhengzhong/github/esp-

,→idf/rel5.1/esp-idf/components/newlib/heap.c:39

#7 0x4200712a in app_main () at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/

,→examples/get-started/hello_world/main/hello_world_main.c:29

#8 0x4201498a in main_task (args=<error reading variable: value has been␣

,→optimized out>) at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/components/

,→freertos/app_startup.c:208

#9 0x40385a2c in vPortTaskWrapper (pxCode=<optimized out>, pvParameters=

,→<optimized out>) at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/components/

,→freertos/FreeRTOS-Kernel/portable/riscv/port.c:202
(continues on next page)

Espressif Systems 87 Release master

Submit Document Feedback
Chapter 2. ESP Friends

(continued from previous page)

ELF file SHA256: 1df25094bc6834da

You can see from the logs that there is a block already marked as free warning and an er-
ror code location hint at app_main () at /home/zhengzhong/github/esp-idf/rel5.1/esp-idf/examples/get-
started/hello_world/main/hello_world_main.c:29. It indicates that a double-free situation occurred at line 29,
and the second call to free needs to be removed.

Using SystemView for System Analysis and Optimization

This section can be directly referred to the Application Layer Trace Library chapter in the ESP-IDF Programming
Guide.

2.2.3 Performance Optimization

The section introduces common performance optimization methods for ESP chips.

ESP Chip Startup Time Optimization

Introduction The startup time of ESP chips refers to the time it takes for the ESP chip to power on and execute the
app_main function. The unoptimized startup process usually takes a long time (generally around 300 milliseconds),
making it unable to meet the requirements of applications with high real-time requirements (such as turning on/off
lights at any time). At the same time, it also accompanies high power consumption, resulting in high average power
consumption in Deep-sleep low-power mode. To avoid these problems, fine optimization of the startup process is
necessary.

Hardware and Software Environment

• Hardware: ESP32-S3 and ESP32-C6
• Software: ESP-IDF v5.2.1

Optional Optimization Items Configuring the following options through menuconfig can significantly reduce
startup time:
1. Disable Bootloader Log Printing
• CONFIG_BOOTLOADER_LOG_LEVEL_NONE=y
• CONFIG_BOOTLOADER_LOG_LEVEL=0
2. Skip Image Validation
• CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP=y
• CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON=y
• CONFIG_BOOTLOADER_SKIP_VALIDATE_ALWAYS=y
3. Disable Boot ROM Log Printing
• CONFIG_BOOT_ROM_LOG_ALWAYS_OFF=y
In addition to this configuration, you also need to use the espefuse.py command in the terminal to con-
figure the eFuse values related to controlling ROM log output (see the Boot Log Printing Control sec-
tion of the Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-
s3_technical_reference_manual_en.pdf>`__ for details; note that writing eFuse operations is irreversible). The
specific command is as follows:

Espressif Systems 88 Release master

Submit Document Feedback
Chapter 2. ESP Friends

espefuse.py burn_efuse UART_PRINT_CONTROL 3

espefuse.py burn_efuse DIS_USB_SERIAL_JTAG_ROM_PRINT 1

After running the above two commands, you can use the espefuse.py summary command to check whether the
writing is successful. If you see the following information, it means the configuration is successful:

4. Modify SPI Flash Mode and Frequency

• CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
• CONFIG_ESPTOOLPY_FLASHFREQ_80M=y
5. Disable Boot Calibration
• CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE=y
• CONFIG_ESP_PHY_CALIBRATION_MODE=1
6. Modify FreeRTOS Configuration
• CONFIG_FREERTOS_UNICORE=y
• CONFIG_FREERTOS_HZ=1000
7. Disable Log Printing
• CONFIG_LOG_DEFAULT_LEVEL_NONE=y
• CONFIG_LOG_DEFAULT_LEVEL=0
If further optimization of the time to connect to the AP after power-on is required on the basis of optimizing the
startup time, the following operations can be performed synchronously:
1. Enable LWIP_DHCP_RESTORE_LAST_IP Configuration Option
• CONFIG_LWIP_DHCP_RESTORE_LAST_IP=y

Startup Time and Average Power Consumption During Startup Results Statistics Startup time and average
power consumption statistics of ESP32-S3 at different main frequencies:

CPU Frequency 80 M 160 M 240 M

Startup Time Before Optimization (ms) 318.8 318.7 318.7
Startup Power Consumption Before Opti- 44.1 51.4 57.3
mization (mA)
Startup Time After Optimization (ms) 26.87 26.875 26.965
Startup Power Consumption After Opti- 29.69 29.77 29.74
mization (mA)

Startup time and average power consumption statistics of ESP32-C6 at different main frequencies:

CPU Frequency 80 M 120 M 160 M

Startup Time Before Optimization (ms) 328.0 327.9 327.8
Startup Power Consumption Before Opti- 34.1 35.8 37.6
mization (mA)
Startup Time After Optimization (ms) 33.31 33.315 33.315
Startup Power Consumption After Opti- 28.23 28.19 28.16
mization (mA)

ESP Low Power Parameter Configuration

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Espressif Systems 89 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Introduction In Light Sleep mode, the RF module is turned off, and most modules, except for RTC-related ones,
are powered down or undergo dynamic frequency adjustment to achieve power reduction. Some menuconfig can be
configured as needed, and this article will introduce these configuration items. The chip s base current at this time
can refer to the power consumption on the datasheet, such as ESP32-C3 is 130 μA, ESP32-S3 is 240 μA, ESP32-C6
is 35 μA (the actual measurement is 45 μA, the subsequent datasheet will correct this item).

1. Common Power Optimization Configuration Options

1.1. Dynamic Frequency Adjustment The higher the frequency at which the CPU works, the greater the power
consumption. Through DFS (dynamic frequency scaling), the system can automatically switch the working frequency
to balance power consumption and performance. To enable this feature, you need to enable the two items shown in
Figure 2-1, so the system will switch to the maximum frequency when working, and switch to the lowest frequency
when the system is idle. The maximum frequency is the default main frequency, such as ESP32-C3 is 160 MHz, and
the lowest frequency is the frequency of the external main crystal oscillator, generally 40 MHz. The maximum and
minimum frequencies can be set by calling esp_pm_configure.

Note: If it is automatic frequency adjustment with Wi-Fi application, the minimum frequency cannot be less than
40 MHz. Below 40 MHz, the CPU processing speed will be slow, the low power consumption benefit is not high, and
C6 is not well adapted, there will be a beacon loss problem.

Figure 2-1 Dynamic Frequency Adjustment Configuration Items

• Configuration item name: PM_ENABLE
• Configuration item path: (Top) -> Component config -> Power Management -> Support
for power management
• Configuration item name: PM_DFS_INIT_AUTO
• Configuration item path: (Top) -> Component config -> Power Management -> Support
for power management -> Enable dynamic frequency scaling (DFS) at startup

1.2 Automatic light sleep If you need to further reduce power consumption after enabling dynamic frequency
adjustment, as shown in Figure 2-1, you need to enable automatic light sleep. Modem sleep mode plus automatic
light sleep is what we often call power save mode.
Figure 2-2 Automatic light sleep configuration items
• Configuration item name: FREERTOS_HZ
• Configuration item path: (Top) -> Component config -> FreeRTOS -> Tick rate (Hz)
• Configuration item name: FREERTOS_USE_TICKLESS_IDLE
• Configuration item path: (Top) -> Component config -> FreeRTOS -> Tickless idle
support
This involves two configuration items, item A is the Tick frequency of freeRTOS, the default is 100, that is, each Tick
requires 1000 / 100=10 ms. Item B is the minimum idle Tick number required to automatically enter light sleep, the
default is 3, that is, when the system detects that the idle time is more than 3 Ticks, it will automatically enter light
sleep. As shown in the figure above, when the idle time is more than 3*10=30 ms, the system will automatically enter
light sleep. By increasing item A, the system can more sensitively detect idle time and enter sleep. For example, if the
tick rate is configured as 1000, that is, if there is no task working within 3 ms, it will enter sleep, thereby achieving
lower power consumption.

Note:
1. Automatic entry into light sleep can only be configured after enabling the configuration items in 2.1.
2. After enabling automatic frequency adjustment and automatic sleep, the communication of some peripherals
will be affected. For specific details, please refer to the programming guide.

The most common question from customers is how to use LEDC and UART while maintaining power consumption.
The solutions are: - For customers who want to use UART interrupts during automatic sleep, first ask them if they

Espressif Systems 90 Release master

Submit Document Feedback
Chapter 2. ESP Friends

have any spare GPIO pins, and recommend GPIO wake-up as a priority. - Ask the customer if there is an external
32K crystal oscillator on the hardware. If there is, change the peripheral clock source to the external 32K crystal
oscillator. - Use locks, which can disable dynamic frequency adjustment during communication. See attachment 2
for an example.

1.3 Isolate GPIO During system sleep, GPIO leakage will cause current loss and increase system power consump-
tion. In esp-idf, GPIO leakage is eliminated during light sleep by floating (disabling internal pull-up and pull-down
resistors) and isolating (disconnecting pin input and output) GPIO pins. The corresponding menuconfig configuration
item is as follows.

Note: This configuration item can only be enabled after enabling automatic sleep in 2.2.

Figure 2-3 Isolate GPIO Configuration Item

• Configuration item name: PM_SLP_DISABLE_GPIO
• Configuration item path: (Top) -> Component config -> Power Management -> Disable
all GPIO when chip at sleep
When this option is enabled, all GPIO pins will be disabled during system sleep, eliminating the impact of GPIO
leakage on sleep power consumption, but also making it impossible for GPIO to input and output signals during sleep.
However, in some applications, the application layer hopes to be able to use GPIO functions (input/output/internal
pull-up and pull-down) normally during system sleep. Therefore, IDF provides a set of APIs for managing GPIO
status during sleep. For related APIs, refer to Table 2-1.
Table 2-1 Sleep Process GPIO Management API
• Set the input and output status of GPIO in sleep state:
esp_err_t gpio_sleep_set_direction(gpio_num_t gpio_num, gpio_mode_t mode);

• Set the pull-up and pull-down status of GPIO in sleep state:

esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t ␣
,→pull);

• Enable automatic GPIO status switching:

esp_err_t gpio_sleep_sel_en(gpio_num_t gpio_num);

• Disable automatic GPIO status switching:

esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num);

If you want to maintain the status of the GPIO pin during sleep, such as controlling light output and controlling switch
closure, you can use the gpio_hold_en(gpio_num_t gpio_num) and gpio_hold_dis(gpio_num_t
gpio_num) APIs to hold the GPIO that needs to maintain the level before entering sleep, and hold_dis after waking
up.

1.4 Flash Power Down ESP32 expands system storage resources through external flash and PSRAM. Flash has the
characteristic of not losing data after power loss, while PSRAM cannot retain data after power loss. When PSRAM
is not used in the system, the flash power-down function can be enabled to reduce the sleep current of the chip. The
related menuconfig options are as follows:
Figure 2-4 Flash Power Down Configuration Item
• Configuration item name: ESP_SYSTEM_PD_FLASH (release/v4.3)
• Configuration item name: ESP_SLEEP_POWER_DOWN_FLASH (4.4 and later)
• Configuration item path: (Top) -> Component config -> ESP System Settings -> PD
flash at light sleep when there is no SPIRAM (release/v4.3)
• Configuration path: (Top) -> Component config -> Hardware Settings -> Sleep
Config -> Power down flash in light sleep when there is no SPIRAM (4.4
and later)

Espressif Systems 91 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Note: In reality, the time required for flash power-off is difficult to predict. Even if the time required for complete
flash power-off can be known, it is sometimes impossible to ensure the safety of flash power-off by setting a sufficiently
long sleep time (for example, sudden asynchronous wake-up sources can make the actual sleep time uncontrollable).
At this time, the hardware behavior of re-powering before the power-off is completed may cause the flash to fail to
work normally. Therefore, the following adjustments can be made to the configuration items:

Figure 2-5 Flash Power-off Configuration Optimization

• Configuration name: ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND
• Configuration path: (Top) -> Component config -> Hardware Settings -> Sleep
Config -> Pull-up Flash CS pin in light sleep
This method is better than powering off the flash, and it increases the base current consumption by tens of μA, but
it takes into account both safety and power consumption. If a filter capacitor is added to the power supply circuit of
the flash, it should be avoided as much as possible to power off the flash.

1.5 CPU Power Down For applications with higher power consumption requirements in light sleep mode, the CPU
power-down function can be enabled during sleep to reduce the sleep current. For ESP32-C3, the sleep current is
reduced by about 100 μA, and for ESP32-S3, the sleep current is reduced by about 650 μA. Currently, it is only
available on these two chips, and ESP32 and ESP32-S2 cannot use it.
Powering down the CPU during sleep will cause the loss of CPU execution context information (dedicated, general,
and status registers, etc.), causing the CPU to execute abnormally after waking up from sleep. Therefore, it is neces-
sary to back up the context information to the retention memory before the CPU is powered down. After the system
wakes up, the CPU executes the context information from the retention memory before execution. Backing up the
CPU context information requires system memory resources. For ESP32-C3, it will consume 1.6 KB of DRAM
space, and for ESP32-S3, it will consume 8.58 KB of DRAM space.
Figure 2-6 CPU Power Down Configuration
• Configuration name: PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP
• Configuration path: (Top) -> Component config -> Power Management -> Power down
CPU in light sleep

1.6 Peripheral Power Down (light sleep) By turning off this item, the base current can be reduced by about 100
μA.
• Configuration name: PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
• Configuration path: (Top) -> Component config -> Power Management -> Power
down Digital Peripheral in light sleep (EXPERIMENTAL)
When the peripheral power domain is powered off during sleep, the IO_MUX and GPIO modules are both powered
off, which means that the state of the chip pins will not be controlled by these modules. To maintain the state of
IO during sleep, you need to call gpio_hold_dis() and gpio_hold_en() before and after configuring the
GPIO state. This operation can ensure that the IO configuration is latched, preventing IO from floating during sleep.

2. Wi-Fi/Bluetooth Low Power Optimization Configuration Espressif chips are wireless MCUs, so most of
the time, low power functions need to be used with Wi-Fi/Bluetooth functions. Here, some low power configurations
and parameters related to Wi-Fi/Bluetooth are explained.

2.1 Bluetooth Low Power Optimization Items

2.1.1 BLE sleep Currently, there are few optimization configurations available for the Bluetooth end, but BLE
modem sleep can be enabled.

Espressif Systems 92 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Configuration item name: BT_CTRL_MODEM_SLEEP and BT_LE_SLEEP_ENABLE(V5.2)

• Configuration path: - (Top) -> Component config -> Bluetooth -> Bluetooth ->
Bluetooth controller -> MODEM SLEEP Options - (Top) → Component config →
Bluetooth → Controller Options(V5.2)
If you want to enter light sleep instead of modem sleep during keep-alive, you can refer to the method in 2.2.
It should be noted that in IDF versions 4.4 and later, Bluetooth already supports using the main crystal as the sleep
clock. The cost of not using an external 32 KHz crystal is that the base current will rise during light sleep. Reference
current: - ESP32-C3: 2.3 mA - ESP32-S3: 3.3 mA

2.1.2 Nimble BLE only

• Configuration item name: BT_NIMBLE_ENABLED
• Configuration path: (Top) -> Component config -> Bluetooth -> Bluetooth ->
Host
In the BLE only scenario, this item can be configured to reduce memory consumption.

2.2 Wi-Fi Low Power Optimization There are many configuration items involved in Wi-Fi optimization, and the
following are more common:

2.2.1 Power Down Wireless Digital Circuit After enabling automatic light sleep, this option can be turned on to
power down the wireless digital circuit module when the physical layer is turned off, which can save about 100 μA
of base current.

Espressif Systems 93 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Configuration item name: ESP_PHY_MAC_BB_PD

• Configuration path: (Top) -> Component config -> PHY -> Power down MAC and
baseband of Wi-Fi and Bluetooth when PHY is disabled

2.2.2 Change Minimum Wait Time and Maximum Keep-Alive Time When the ESP32 operates as both STA
and AP, it needs to wait for a period of time before turning off the RF after receiving data once, this time is called
the Minimum active time, the default value is 50 ms. On the basis of ensuring the data throughput each time, this
waiting time can be appropriately reduced to lower power consumption.
When the ESP32 is in power save mode, it needs to periodically send a keep alive packet to the AP to tell the AP that
it is still connected. The Maximum keep alive time is the time period for sending this keep alive packet, the default
is 10 s. Power consumption can be reduced by increasing this parameter to reduce packet sending.

• Configuration item name: ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME

• Configuration path: (Top) -> Component config -> Wi-Fi -> Wi-Fi SLP IRAM speed
optimization -> Minimum active time
• Configuration item name: ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME
• Configuration path: (Top) -> Component config -> Wi-Fi -> Wi-Fi SLP IRAM speed
optimization -> Maximum keep alive time
Recommended configuration: Minimum active time = 15~20, Maximum keep alive time = 60.

2.2.3 Enable Power Management for Disconnection After enabling this configuration item, the Modem sleep
state can still be maintained when a disconnection occurs.

• Configuration item name: ESP_WIFI_STA_DISCONNECTED_PM_ENABLE

• Configuration path: (Top) → Component config → Wi-Fi → Power Management for
station at disconnected

2.2.4 Enable Beacon Lost Optimization (only for release/v4.4 and above) One of the basics of Wi-Fi keep alive
is to be able to receive the beacon packet sent by the router on time. In actual use environment, various reasons can
cause beacon loss. In versions prior to release/v4.4, after losing the beacon, the ESP32 will keep the RF on until the

Espressif Systems 94 Release master

Submit Document Feedback
Chapter 2. ESP Friends

next beacon is received. Versions after 4.4 can avoid the impact of this behavior on power consumption by enabling
beacon lost optimization.

• Configuration item name: ESP_WIFI_SLP_BEACON_LOST_OPT

• Configuration path: (Top) → Component config → Wi-Fi → Wifi sleep optimize
when beacon lost
As shown in Figure 2-6, the optimization principle is that the RF receiver will not always be on when the beacon
is lost. Instead, it will be turned on for a while and if no reception is received, it will go to sleep, then wake up to
receive packets. If it still hasn t received anything after repeating this process a few times, it will operate as usual,
keeping the RF on until it receives a position. This can greatly improve the fault tolerance rate when the beacon is
not received, thereby reducing power consumption.

Espressif Systems 95 Release master

Submit Document Feedback
Chapter 2. ESP Friends

After enabling this option, four additional configuration items will be introduced, mainly focusing on the first two
configuration items:
• Option A: Beacon loss timeout indicates how long to wait without receiving a beacon before entering sleep
mode.
• Option B: Maximum number of consecutive lost beacons allowed indicates how many times to repeat
without receiving before continuously turning on.
Note that option B should not be set too high, generally set to 3.

2.2.5 Reduce TX power After enabling this option, the PHY TX power will be reduced after detecting a brownout
reset, allowing the code to continue running.

• Configuration item name: ESP_PHY_REDUCE_TX_POWER

• Configuration path: (Top) → Component config → PHY → Reduce PHY TX power when
brownout reset

2.2.6 Optimize Sleep IRAM Speed Selecting this option will place the Wi-Fi library s TBTT process and receive
beacon function in IRAM. If this option is enabled, the average current of the Wi-Fi powersave mode will be reduced.

Espressif Systems 96 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Configuration item name: ESP_WIFI_SLP_IRAM_OPT

• Configuration path: (Top) → Component config → Wi-Fi → WiFi SLP IRAM speed
optimization

2.2.7 Optimize IRAM Speed All three of the following items can be enabled.

• Configuration item name: - ESP_WIFI_IRAM_OPT - ESP_WIFI_EXTRA_IRAM_OPT -

ESP_WIFI_RX_IRAM_OPT
• Configuration Path: (Top) → Component config → Wi-Fi → WiFi IRAM speed opti-
mization

2.2.8 Wi-Fi PHY Layer Packet Reception An optional feature of ESP32-C6, during light sleep, the PHY layer
automatically receives packets, Wi-Fi no longer needs CPU participation to receive beacons, only Wi-Fi MAC +
Baseband + RF are working, to save power consumption.

Note: Supplementary content: T/RX waveform diagram under different modes

• Configuration Item Name: - ESP_WIFI_ENHANCED_LIGHT_SLEEP -

ESP_WIFI_EXTRA_IRAM_OPT - ESP_WIFI_RX_IRAM_OPT

Espressif Systems 97 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Configuration Path: (Top) → Component config → Wi-Fi → WiFi modem automatically

receives the beacon

3. Supplementary Content

3.1. The Difference Between DTIM and Listen Interval When the chip establishes a connection as a STA with
the router, it will be informed of the router s DTIM, that is, how often the router will send a beacon. The STA
needs to wake up at this time to receive the beacon and check if there is information that needs to be processed. The
listen interval, on the other hand, is the STA telling the router how often it needs to wake up to receive the beacon,
that is, the former is determined by the router, and the latter can be configured into the chip. The time interval is the
value of DTIM or listen interval * 100 MS. If DTIM=10, the wake-up time interval is 10 * 100 ms = 1 s.

3.2. External 32KHz Crystal Using an external 32KHz crystal can achieve lower power consumption. The main
reasons are as follows:
• The internal crystal is easily interfered with, while the external crystal has higher precision and can be used in
various sleep situations.
• For applications that require high time accuracy, such as Bluetooth and Wi-Fi keep-alive, it is necessary to
wake up regularly to receive beacons. Once the clock drifts too much and misses the reception point, it will
cause the RF waiting window to lengthen, thereby greatly increasing power consumption.
Enabling the external clock source requires the following configuration:

• Configuration Item Name: - ESP32C3_RTC_CLK_SRC_EXT_CRYS -

ESP_WIFI_EXTRA_IRAM_OPT - ESP_WIFI_RX_IRAM_OPT
• Configuration Path: (Top) → Component config → ESP32XX-Specific → RTC clock
source
There are two types of external crystals:
• External 32kHz crystal: This is an external passive crystal, which is the crystal recommended most of the
time
• External 32kHz oscillator at 32K_XP pin: This is an external active crystal, which is more expensive and
will cause the base current to rise by 50 ~ 100 μA
The ESP32-C2 only supports an external active crystal oscillator as it does not have an internal passive crystal oscillator
circuit. The layout of the crystal oscillator can be referred to the hardware design guide corresponding to each chip.

3.3. T/RX waveform under different modes Modem Mode (Physical layer receives beacon): The time cost of
receiving a packet once is about 2.1 ms, and the current of receiving a packet is about 64 mA ~ 70 mA.

Espressif Systems 98 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Active Mode RX: The duration of receiving a packet once is about 5.3 ms, and the current of receiving a packet is
about 80 mA.

Espressif Systems 99 Release master

Submit Document Feedback
Chapter 2. ESP Friends

RX without receiving a packet: Compared with the situation where no packet is received, there will be no current
waveform lasting for a period of time.

Espressif Systems 100 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Active Mode TX: The duration is uncertain, and the TX current is related to the Wi-Fi channel.

Espressif Systems 101 Release master

Submit Document Feedback
Chapter 2. ESP Friends

ESP Memory Usage Optimization

Introduction Due to the hardware resource constraints of embedded chips, running complex application code may
lead to insufficient memory. Most of the default configuration items in ESP-IDF prioritize performance, but in actual
products, a good balance between performance and memory usage can be achieved through appropriate memory
configuration.

Warning: Some memory optimization methods listed in this document may reduce system performance and
stability. Sufficient performance and stability testing should be conducted after optimization to ensure the appli-
cation meets its requirements.

Obtaining Current Free Memory Before optimizing memory usage, it is necessary to know the cur-
rent memory consumption. For static memory usage, you can use the idf.py size and idf.py size-
components commands to gather statistics memory usage. For runtime memory consumption, xPort-
GetFreeHeapSize() and xPortGetMinimumEverFreeHeapSize() functions can be used to obtain the current
free memory and the minimum heap memory remaining since system startup, respectively. For more
granular memory allocation, you can enable the CONFIG_FREERTOS_USE_TRACE_FACILITY and CON-
FIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS options and then use the vTaskList() function to get the
high watermark for each task stack.

Available Optimization Options

1. Wi-Fi Memory Optimization

Espressif Systems 102 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Wi-Fi performance is affected by many parameters, with trade-offs between them. Proper configuration can not only
improve performance but also increase available memory and system stability. Configuration options vary signifi-
cantly depending on the chip, so for Wi-Fi memory optimization and throughput, please refer to the relevant chip
documentation under How to Improve Wi-Fi Performance.
2. LwIP Memory Optimization
Since RAM is allocated dynamically from the heap, most of lwIP s RAM usage is also dynamically allocated.
Therefore, changing lwIP settings to reduce RAM usage might not affect idle RAM usage but can reduce peak RAM
consumption. For LwIP memory optimization, see LwIP Minimum RAM Usage.
3. Mbed TLS Memory Optimization
Mbed TLS is a C library used to implement cryptographic primitives, X.509 certificate handling, and SSL/TLS and
DTLS protocols. When using the Mbed library for encryption and decryption, memory usage can be reduced by
adjusting its configuration. For Mbed memory optimization, see Mbed Minimum RAM Usage.
4. BLE Memory Optimization
Compared to Bluedroid, NimBLE uses less memory and a smaller firmware size. Additionally, you can disable
certain features and reduce buffer sizes to achieve optimal memory usage. For scenarios where BLE is only used for
provisioning, try the following configurations:
Reduce maximum connections and related parameters:
• CONFIG_BT_NIMBLE_MAX_CONNECTIONS=1
• CONFIG_BT_NIMBLE_MAX_BONDS=2
• CONFIG_BT_NIMBLE_MAX_CCCDS=2
• CONFIG_BT_NIMBLE_WHITELIST_SIZE=2
If there are no high-speed requirements, reduce buffer sizes and counts:
• CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT=12
• CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE=100
• CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT=4
• CONFIG_BT_NIMBLE_TRANSPORT_ACL_FROM_LL_COUNT=12
• CONFIG_BT_NIMBLE_TRANSPORT_EVT_COUNT=5
• CONFIG_BT_NIMBLE_TRANSPORT_EVT_DISCARD_COUNT=3
Disable unnecessary features:
• CONFIG_BT_NIMBLE_ROLE_CENTRAL=n
• CONFIG_BT_NIMBLE_ROLE_OBSERVER=n
• CONFIG_BT_NIMBLE_SECURITY_ENABLE=n
5. Other Configuration Optimizations
For performance and power-saving purposes, some functions are placed in IRAM by default. If needed, you can
reconfigure these functions to be placed back into Flash:
• CONFIG_SPI_SLAVE_ISR_IN_IRAM=n
• CONFIG_ESP_WIFI_IRAM_OPT=n
• CONFIG_ESP_WIFI_RX_IRAM_OPT=n
• CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH=y
• CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH=y
• CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH=y
Reduce the length of some system queues:
• CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE=16
Enable nano format options:
• NEWLIB_NANO_FORMAT=y
Disable unnecessary features:
• CONFIG_WS_TRANSPORT=n

Espressif Systems 103 Release master

Submit Document Feedback
Chapter 2. ESP Friends

6. Reduce Task Stack Sizes

In the default ESP-IDF configuration, Task Stack sizes include a large margin to accommodate different chips and
allow users to add application code. Reducing Task Stack sizes can free up memory for dynamic allocation.
Common Task Stack configuration items:
• CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE
• CONFIG_BT_LE_CONTROLLER_TASK_STACK_SIZE
• CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE
• CONFIG_ESP_TIMER_TASK_STACK_SIZE
• CONFIG_FREERTOS_IDLE_TASK_STACKSIZE
• CONFIG_LWIP_TCPIP_TASK_STACK_SIZE

Optimization Example and Result Statistics Testing the bleprph_wifi_coex example demonstrates the effect of
memory optimization by comparing memory usage before and after Wi-Fi and BLE connections.
1. Hardware and Software Environment
• Hardware: ESP32-C2
• Software: ESP-IDF 11eaf41b37267ad7709c0899c284e3683d2f0b5e (tag: v5.2)
• Example: examples/bluetooth/nimble/bleprph_wifi_coex
2. Configuration Changes
• CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE=y
• CONFIG_EXAMPLE_ESP_PING_COUNT=5
• CONFIG_BT_ENABLED=y
• CONFIG_BT_NIMBLE_ENABLED=y
• CONFIG_BT_NIMBLE_MAX_BONDS=2
• CONFIG_BT_NIMBLE_MAX_CCCDS=2
• CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE=2048
• CONFIG_BT_NIMBLE_ROLE_CENTRAL=n
• CONFIG_BT_NIMBLE_ROLE_OBSERVER=n
• CONFIG_BT_NIMBLE_SECURITY_ENABLE=n
• CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT=12
• CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE=100
• CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT=4
• CONFIG_BT_NIMBLE_TRANSPORT_ACL_FROM_LL_COUNT=12
• CONFIG_BT_NIMBLE_TRANSPORT_EVT_COUNT=5
• CONFIG_BT_NIMBLE_TRANSPORT_EVT_DISCARD_COUNT=3
• CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT=n
• CONFIG_BT_NIMBLE_WHITELIST_SIZE=2
• CONFIG_BT_LE_CONTROLLER_TASK_STACK_SIZE=2048
• CONFIG_ESP_COEX_SW_COEXIST_ENABLE=n
• CONFIG_ESP_EVENT_POST_FROM_ISR=n
• CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS=n
• CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH=y
• CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH=y
• CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE=16
• CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=1536
• CONFIG_ESP_TIMER_TASK_STACK_SIZE=2048
• CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=3
• CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=6
• CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM=6
• CONFIG_ESP_WIFI_AMPDU_TX_ENABLED=n
• CONFIG_ESP_WIFI_AMPDU_RX_ENABLED=n
• CONFIG_ESP_WIFI_IRAM_OPT=n
• CONFIG_ESP_WIFI_RX_IRAM_OPT=n
• CONFIG_ESP_WIFI_ENABLE_WPA3_SAE=n
• CONFIG_ESP_WIFI_SOFTAP_SUPPORT=n

Espressif Systems 104 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT=y
• CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM=0
• CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT=n
• CONFIG_FREERTOS_IDLE_TASK_STACKSIZE=768
• CONFIG_FREERTOS_USE_TRACE_FACILITY=y
• CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS=y
• CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH=y
• CONFIG_LWIP_L2_TO_L3_COPY=y
• CONFIG_LWIP_MAX_SOCKETS=8
• CONFIG_LWIP_SO_LINGER=y
• CONFIG_LWIP_SO_RCVBUF=y
• CONFIG_LWIP_NETBUF_RECVINFO=y
• CONFIG_LWIP_GARP_TMR_INTERVAL=30
• CONFIG_LWIP_MLDV6_TMR_INTERVAL=30
• CONFIG_LWIP_TCPIP_RECVMBOX_SIZE=16
• CONFIG_LWIP_DHCP_RESTORE_LAST_IP=y
• CONFIG_LWIP_DHCPS=n
• CONFIG_LWIP_IPV6_NUM_ADDRESSES=6
• CONFIG_LWIP_IPV6_FORWARD=y
• CONFIG_LWIP_TCP_SND_BUF_DEFAULT=6144
• CONFIG_LWIP_TCP_SACK_OUT=y
• CONFIG_LWIP_MAX_UDP_PCBS=24
• CONFIG_LWIP_UDP_RECVMBOX_SIZE=12
• CONFIG_LWIP_TCPIP_TASK_STACK_SIZE=2048
• CONFIG_LWIP_IPV6_MEMP_NUM_ND6_QUEUE=6
• CONFIG_LWIP_IPV6_ND6_NUM_NEIGHBORS=8
• CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN=6288
• CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN=2048
• CONFIG_MBEDTLS_DYNAMIC_BUFFER=y
• CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA=y
• CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE=n
• CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=n
• CONFIG_NEWLIB_TIME_SYSCALL_USE_HRT=y
3. Optimization Results
The table below shows the system s available memory before and after optimization. The results indicate that
approximately 60 KB of memory can be saved through configuration optimization.

Available Memory Before Optimiza- After Optimization Difference

tion
Current Available (bytes) 33,232 95,040 61,808
Minimum Available (bytes) 25,804 91,252 65,448

2.2.4 Template

2.3 Solution Introduction

This section will integrate related documents of Espressif application solutions.

Espressif Systems 105 Release master

Submit Document Feedback
Chapter 2. ESP Friends

2.3.1 AI Solution

Introduction to AI Solution

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

AI Solution Overview
Solution Features:
• Espressif provides a complete set of AIoT smart IoT solutions, fully integrating ESP-EYE development
board, ESP-BOX development board, ESP-WHO AI framework, ESP-IDF software SDK, to facilitate
the successful implementation of AI technology in IoT application development.
Solution Advantages:
• 1. The ESP32-S3 chip has industry-leading RF performance and integrates corresponding hardware-
level AI acceleration, supporting the joint construction and integration of AI and IoT.
• 2. Espressif s self-developed AFE algorithm has passed Amazon Alexa s far-field test and Audio
Front End certification. Working in conjunction with Espressif s self-developed WakeNet wake
word engine, it aligns with Amazon s multi-language testing requirements.
• 3. Espressif s AFE algorithm is optimized based on the AI accelerator of the ESP32-S3 SoC, consum-
ing only about 22% of CPU space, 48 KB SRAM, and 1.1 MB PSRAM, providing ample resource
space for customer applications built with ESP32-S3.
• 4. ESP-Skainet works in conjunction with the WakeNet wake word engine, the offline voice com-
mand recognition engine (MultiNet), and the front-end acoustic algorithm (AFE) to provide a voice
assistant with high accuracy and support for custom wake words.

Common AI Application Scenarios Espressif Voice Intelligent Conference Room

• Chinese Video Espressif Voice Intelligent Conference Room: The ESP32-S3-BOX integrates AI voice, touch
screen control, sensors, infrared controllers, and smart gateways, serving as the control center for all devices
in the house. It supports users to easily achieve smart home linkage through voice commands or touch screen
control. Combining ESP32-S3-BOX with Espressif s AI image processing, Wi-Fi smart gateway, Wi-Fi
human detection, Wi-Fi wireless image transmission and other technical solutions makes Espressif s meetings
smarter.
Smart Farm
• Chinese Video ESP32 Smart Farm: The smart panel of the smart farm solution is developed by the ESP32-
S3-LCD-EV-BOARD development board, integrating AI voice, touch screen control, and sensors, providing
cloud connection and voice control functions. It also supports remote control from mobile applications using
ESP RainMaker.
Smart Speaker
• Chinese Video ESP32 Smart Speaker: The smart speaker solution uses the ESP-BOX development board with
the ESP32-S3 chip, integrating Wi-Fi, dual microphones, and a touch screen, and can be used with ChatGPT
to create a smart voice assistant.

AI Reference Materials (Voice)

• AI Software References
– ESP-DL Deep Learning Framework
– ESP ChatGPT Example

Espressif Systems 106 Release master

Submit Document Feedback
Chapter 2. ESP Friends

– ESP-Skainet Voice Assistant Framework

– ESP-SR Voice Recognition Framework
• AI Related Modules/Development Board Purchase
– ESP32-S3 Chip/Module Purchase
– Purchase ESP32-S3-Korvo-2
• Module/Development Board Information and Selection Reference
– Introduction to ESP32-S3 Chip
– Introduction to Espressif Audio Development Board
– Espressif Product Selection Tool

AI Reference Materials (Image)

• AI Software Reference
– ESP-DL Deep Learning Framework
– ESP Activity Detection Example
– ESP Gesture Detection Example
– ESP Human Detection Example
– ESP-WHO Image Processing Development Platform
• AI Related Module/Development Board Purchase
– Purchase ESP32-S3 Chip/Module
– Purchase ESP32-S3-EYE
• Module/Development Board Information and Selection Reference
– Introduction to ESP32-S3 Chip
– Introduction to ESP32-S3-EYE Development Board
– Espressif Product Selection Tool

2.3.2 Brushless Motor Solution

Introduction to Brushless Motor Solution

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Overview and Advantages of BLDC Solution Espressif s Brushless Motor (BLDC) solution offers excellent
performance and stability, and can be paired with ESP master chips that support MCPWM peripherals. This solution
performs well in various application scenarios such as household appliances, industrial automation, power tools, and
medical equipment. Advantages include rotor initial phase detection, sensorless speed control, etc. In addition, it
supports back-EMF detection with hardware comparators and internal ADCs, enabling speed closed-loop control.
Here is an overview and advantages of the BLDC solution:
• Higher operating efficiency and performance: Utilizing the high-performance processing capability of the
ESP chip, it can monitor and estimate the operating status of the brushless motor in real time, achieving stable
closed-loop control.
• Rich software and hardware references: Provides comprehensive BLDC software and hardware develop-
ment materials, including detailed development documents and examples. In addition, related hardware design
files are open source, making it easy for customers to quickly build prototypes.
• Complete control scheme: Supports sensorless square wave control based on comparators or ADCs, and
sensor-based FOC. Among them, the sensor-based FOC control scheme based on SimpleFOC supports IDF
framework development, meeting the needs of different user groups.

Espressif Systems 107 Release master

Submit Document Feedback
Chapter 2. ESP Friends

In addition, Espressif also supports the following features to further expand the application scenarios of the BLDC
solution:
• RainMaker private cloud deployment: Integrated one-stop private cloud deployment, providing users with
more convenient BLDC interaction methods and remote OTA upgrade services.
• High-performance floating-point operation performance: Optimizes the trigonometric and floating-point
operations of the SimpleFOC algorithm, improving the algorithm efficiency of BLDC.

Common Application Scenarios of BLDC Espressif s BLDC solution is widely used in various fields, including
but not limited to:
• DC frequency conversion floor fan solution: Integrated with Wi-Fi, BLE, RainMaker, supports speed ad-
justment, oscillation control, natural wind speed and other functions. Typical application scenarios are small
household appliances.

• SimpleFOC single motor drive solution: Integrated with SimpleFOC algorithm, supports motor parameter
verification, speed closed-loop, angle closed-loop and torque closed-loop. Typical application scenarios are
small household appliances and industrial automation applications.

Espressif Systems 108 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• FOC knob screen solution: Integrated with SimpleFOC algorithm, supports knob screen display, ratchet hand
feel simulation, etc. Typical application scenarios are knob screen applications in small household appliances.

• Sensorless square wave ADC solution: Supports pulse method rotor initial phase detection, ADC sampling
zero-crossing detection, stall protection, etc. Suitable for small household appliances and industrial automation

Espressif Systems 109 Release master

Submit Document Feedback
Chapter 2. ESP Friends

applications.

The summary is as follows:

Espressif Systems 110 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Table 3: Overview of BLDC Solution

So- Solution Master Motor Function Com- Application
lu- Name Control po- Scenario
tion nent
Cat-
e-
gory
Floor Smart DC ESP32- Brushless DC Supports RainMaker remote Sen- Smart home
Fan Frequency S3 Motor control, speed adjustment, os- sor- appliances
Solu- Conversion cillating control, natural wind less and industrial
tion Floor Fan speed, and other functions Square automation
Wave scenarios
BLDC
Com-
po-
nent
FOC SimpleFOC ESP32- Brushless DC Supports speed closed-loop, ESP_SIMPLEFOC
Smart home
Sin- Single Mo- C3 Motor angle closed-loop, and torque Com- appliances
gle tor Drive closed-loop po- and industrial
Mo- Solution nent automation
tor scenarios
Drive
Solu-
tion
FOC FOC Smart ESP32- Brushless DC Supports boundary- ESP_SIMPLEFOC
Knob screen
Knob Knob Screen S3 Motor free/boundary-based ratchet Com- application
Screen knob tactile simulation po- scenarios in
Solu- nent small home
tion appliances

BLDC Reference Materials In addition, we currently have some public brushless motor (BLDC) github software
libraries, videos, and module materials, as follows:
• Software References
– ESP-IOT-SOLUTION ESP_SIMPLEFOC Component
– ESP-IOT-SOLUTION Sensorless Square Wave BLDC Component
– ESP-IOT-SOLUTION Smart DC Variable Frequency Floor Fan Example
– ESP-IOT-SOLUTION Smart Knob Screen Example
• Module/Development Board Materials and Option References
– Espressif Product Selection Tool

BLDC Drive Solution Summary In the brushless motor (BLDC) solution, driving the three-phase inverter circuit
is an important link. In ESP chips, the LEDC and MCPWM modules are supported for driving the three-phase
inverter circuit.

Espressif Systems 111 Release master

Submit Document Feedback
Chapter 2. ESP Friends

MCPWM Drive Solution MCPWM is a multifunctional PWM module that supports multi-channel PWM output,
external pulse width calculation, etc. Some ESP chips do not support MCPWM, such as ESP32-S2, ESP32-C3,
etc. In the MCPWM drive scheme, the control of the BLDC motor is realized by configuring the phase, duty cycle,
frequency, etc. of the MCPWM module.

Note:
1. Does it support outputting complementary waveforms to control MOS drivers?
• Yes, the MCPWM generator module supports generating independent or complementary PWM wave-
forms, which can control MOS drivers by configuring output pins.

LEDC Drive Scheme LEDC is mainly used to control LEDs, but it can also generate PWM signals for driving
BLDC motors. All ESP chips support PWM output driven by hardware LEDC.

Note:
1. What are the scenarios for using LEDC drive? Is the sensorless BLDC square wave control scheme supported?
• The ESP_SIMPLEFOC component supports configuring LEDC channels to output PWM signals for
driving BLDC motors. In the scenario of sensorless square wave control scheme, considering the accuracy
of the sampling moment, it is recommended to use the MCPWM drive scheme.

Summary of Common BLDC Questions Q: How to control the demand for Espressif chip selection?
• A: Currently, Espressif mainly promotes the BLDC control scheme based on ESP32-S3, which supports sen-
sorless BLDC control schemes based on ADC or comparator and sensor FOC control schemes. In addition,
users also need to consider the detailed parameters required by the application, such as the number of IOs,
memory and flash size, etc. You can refer to Espressif s official selection tool or consult business.
Q: Which version of ESP-IDF should be used for the development of BLDC control schemes?
• A: ESP-IDF 5.0 and above versions need to be ensured.
Q: Can you assist in the development of BLDC brushless motors?
• A: Yes. First, users need to determine the motor model according to application requirements, including
whether it is a brushless DC motor, motor parameters, etc. At the same time, users need to clarify control
requirements, including speed control, angle control, torque control, etc. Then, according to the motor type
and control requirements, assist users in brushless motor development.
Q: What is a BLDC driver? How do ESP series chips cooperate with it?

Espressif Systems 112 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• A: The drive circuit of the brushless motor (BLDC) mainly uses a three-phase inverter circuit to generate
magnetic fields in different directions to drive the motor. Among them, the ESP chip mainly controls the gate
drive chip to control the BLDC brushless motor by generating PWM signals through the MCPWM or LEDC
module.
Q: Why is the MCPWM drive scheme recommended in the BLDC scheme?
• A: MCPWM is a dedicated peripheral in ESP chips for motor and power control. Each MCPWM peripheral
includes a clock divider, three PWM timers, three PWM operators, and a capture module. By configuring the
MCPWM module, accurate sampling of the BLDC brushless motor can be achieved.
Q: What is the difference between the sensorless square wave BLDC component and the ESP_SIMPLEFOC com-
ponent?
• Answer: The Sensorless Square Wave BLDC Component is mainly used for implementing sensorless BLDC
motor control, supporting external comparators and ADC to monitor back EMF for sensorless speed closed-
loop control. The ESP_SIMPLEFOC Component is a sensor-based FOC control solution based on the Sim-
pleFOC algorithm, supporting IDF framework development, and meeting the needs of different user groups.
If there are no external sensors, it is recommended to use the Sensorless Square Wave BLDC Component.

2.3.3 Camera Solution

DVP Camera Solution Introduction

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Common Application Scenarios

1. Existing video demos
• ESP32-S3 Speeding Milliseconds High Frame Rate 125 fps : ESP32-S3 with a global shutter camera,
achieving a high frame rate of 125 FPS. It can capture the motion trajectory of moving objects, such as high
frame rate image capture of writing pens and other scenarios. Combined with the network capabilities of
ESP32-S3, it is the first choice for IoT smart camera solutions.
• ESP32-S3 Watching Cute Cats Eating High Resolution : ESP32-S3-EYE AI development board, with a 200
W pixel camera. High-resolution real-time watching of the cat master eating, the first choice for pet monitoring.
2. QR code scanning function
• Product barcode scanning, train ticket scanning, land tax invoice scanning, resource scanning download, etc.
• Auto focus + Internet
3. Wi-Fi, LCD Polaroid
• The photos taken are immediately refreshed on the webpage and displayed on the LCD.
4. Scanner, smart car auxiliary navigation
5. Face recognition
• Technology or system for identity confirmation or identity search through faces
6. Video surveillance, light-sensitive atmosphere lamp
7. AI applications
• Gesture recognition
• Number recognition

Espressif Systems 113 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Food recognition
• Posture detection

Reference Materials
• Software references
– General camera example
– Camera driver library esp32-camera, esp32-camera is a camera driver library from Espressif, providing
camera peripheral drivers for ESP32/ESP32-S2/ESP32-S3, including the underlying 8 bit DVP interface
driver, sensor driver, and image encoding and decoding.
– Face recognition solution library
– Audio and video intercom solution example
• Related modules/development boards purchase
– ESP32-S3 chip/module purchase
– ESP32-S3-EYE purchase
• Module/development board materials and selection reference
– ESP32-S3 chip introduction
– ESP32-S3-EYE development board introduction
– Espressif product selection tool

Performance Test Data Appendix Camera-related solutions mainly focus on the following performance indica-
tors:
1. Sensor initialization time (especially for projects that need to capture immediately after startup)
2. Supported resolution and data formats
3. Frame rate under specified resolution and data format
4. Transmission rate when used with Wi-Fi
5. Supported image processing functions (currently mainly performed by software for JPEG encoding and de-
coding functions)
Related test code can be referred to Test Example.

Sensor Initialization Time

Table 4: Sensor init time

Sensor Init time (ms)
OV3660, JPEG 604
OV3660, RGB565 1301
OV2640, JPEG 200
OV5640, JPEG 240

Note: Please note the following when conducting the above tests:
• A picture needs to be captured at the end of the test to verify correctness
• You can refer to More Optimization Methods to optimize the system configuration as much as possible.

Supported Resolution and Data Formats The supported resolution size depends entirely on the maximum per-
formance of the camera, but the capabilities of DVP itself and CPU DMA are limited, and too high resolution will
put pressure on data transmission:
• If the DVP camera sensor can output JPEG type pictures, the corresponding resolution is recommended not
to exceed 500 w pixels
• If the DVP camera sensor cannot output JPEG type pictures (at this time the type of picture is
YUV422/RGB565, etc.), the corresponding resolution is recommended not to exceed 100 w pixels
The data format mainly depends on the data format that the camera supports output. Mainly include:

Espressif Systems 114 Release master

Submit Document Feedback
Chapter 2. ESP Friends

1. RGB
2. YUV
3. JPEG
4. RAW Data
5. BMP
6. Only Y/Grayscale
When the camera itself does not support outputting JPEG data, it can be compressed by ESP32 to output JPEG data.

Note: Specifically, when the required resolution is too large, exceeding 1024*720, consider using a camera that
supports JPEG encoding. At the same time, it should be clarified that JPEG encoding and decoding performed by
ESP32 will put pressure on CPU and memory.

Frame Rate Under Specified Resolution and Data Format

Table 5: Sensor init time

Output format Chip model Sensor model Resolution Frame rate
YUV422RGB565 ESP32-S3 SC030IOT 640*480 30 fps
JPEG ESP32S3 OV5640 1600*1200 25 fps
Only Y/MONO ESP32-S3/ESP32- SC031GS 240*240 125 fps
S2

The speed of different cameras varies greatly. When testing the JPEG speed, you should specify the parameters of
JPEG compression, and try to shoot colorful pictures. Shooting monochrome objects will contain more low-frequency
information, resulting in a small amount of data after JPEG compression, and the generated data is not representative.
The frame rate of the same camera varies greatly when the data format, resolution, size of the main clock XCLK,
and idle interval time parameters are set differently. At the same time, to ensure the frame rate, the fb_count should
not be less than 2 when initializing the camera. Currently, most of the driver parameters connected to the camera
are not optimal, and the configuration methods of different cameras are not unified, so there is much room for
optimization and adjustment of the above performance data. ESP32-S3 has an independent CAM DVP interface,
and the peripheral interface rate is 2~3 times that of ESP32.

Transmission rate when used with Wi-Fi Usually, when the user s required data format, resolution, frame rate
and other parameters are determined, based on the test data of Wi-Fi, we can preliminarily estimate whether the
scheme is feasible.
Take JPEG@480*320@20fps as an example, usually a JPEG@480*320 picture is 30 KB ~ 50 KB, the frame rate
requirement is 20 fps, then the speed required by Wi-Fi should be 600 KB/s ~ 1000 KB/s. By checking the ESP32-S3
Wi-Fi throughput, it can be found that ESP32-S3 meets the requirements.
Currently, the esp-rtsp example running on ESP32-S3 can achieve a frame rate of about 20 fps for 720p + MJPEG
video stream.

ESP32-S3 s encoding and decoding performance ESP32-S3 does not have hardware encoding and decoding
capabilities, its driver code includes the software encoding component of TinyJPEG.

Espressif Systems 115 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Introduction to USB Camera Solution

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Common Application Scenarios

USB Host
• ESP32-S3 Host UVC LCD Display Solution: Espressif s USB audio and video transmission solution im-
plements the standard USB UVC host class, using the native USB interface to connect to a universal camera,
and simultaneously achieving USB camera data stream reading, quick start, hot plugging, automatic descriptor
parsing, MJPEG video stream transmission, bulk and synchronous two transmission modes, adaptive image
size display, switching image transmission size, Wi-Fi image transmission and other functions on a single SoC.
It can be used in scenarios such as peepholes, smart doorbells and locks, electronic endoscopes, etc.

USB Device
• ESP32-S2/S3 Device USB UVC Solution: Transmits the camera s image to the PC host through the USB
interface, can be used as a USB camera, and can also support microphone output, suitable for peepholes. -
Example code: usb camera

Reference Materials
• Document References
– USB Stream Component Description
– USB Device UVC
• Software References
– USB Stream User Guide

Espressif Systems 116 Release master

Submit Document Feedback
Chapter 2. ESP Friends

– USB Stream Example

– ESP-IDF USB Example
– USB Example in ESP-IOT-SOLUTION
• Related Modules/Development Boards Purchase
– ESP32-S3 Chip/Module Purchase
– ESP32-S3-USB-OTG Purchase
• Module/Development Board Information and Selection Reference
– ESP32-S3-USB-OTG Development Board Introduction
– Introduction to ESP32-S3 Chip
– Espressif Product Selection Tool

USB UVC Performance Test Data Appendix

• The camera must be compatible with USB1.1 Fullspeed mode
• The camera needs to come with MJPEG compression
• In synchronous transmission mode, the total bandwidth of USB transmission for image data stream should be
less than 4 Mbps (500 KB/s)
• In bulk transmission mode, the total bandwidth of USB transmission for image data stream should be less than
8.8 Mbps (1100 KB/s)
• MJPEG format, 800 x 480 @15fps under bulk transmission mode, 480 x 320 @15fps under synchronous
transmission mode

2.3.4 LCD Solution

Introduction to LCD Solution

This section can directly refer to the LCD Application Solution Introduction in the ESP-IoT-Solution document.
In addition, the ESP-IoT-Solution document also provides an LCD development guide and detailed explanations of
various LCD interfaces. For specific content, please refer to LCD Display.

2.3.5 Lighting Solution

Introduction to Lighting Solutions

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Overview and Advantages of Light Solutions Espressif s lighting solutions are renowned for their richness and
maturity. Our solutions support a variety of common lamp-related peripherals, including LEDC, SPI, I2C, MCPWM,
etc., offering a wide range of choices for your lighting needs. Combined with Espressif s mature wireless protocols
such as Wi-Fi and BLE, as well as cloud adaptation technology, you can easily implement remote control functions
and manage your lighting system anytime, anywhere.

Espressif Systems 117 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Moreover, Espressif has implemented AI voice recognition technology, allowing you to control lights through voice.
Our audio algorithm makes music rhythm lights possible, while color recognition and image rhythm algorithms pro-
vide you with a variety of cutting-edge innovative solutions. These innovative technologies will bring more possibil-
ities to your lighting system, making it smarter, richer, and more attractive. Here are the advantages of Espressif s
lighting solutions:
• Zero-code lighting solution: ESP ZeroCode Solution No need to worry about complex steps such as firmware,
mobile APP, cloud connection, certification, and production, directly build smart home devices compatible with
Matter, including lighting devices
• Rich software references: Provide comprehensive lamp-related software development materials, including
detailed guidance documents and examples

Common Application Scenarios of Light Espressif s lighting solutions are widely used in various fields, and the
types of lamps used in different fields also vary, summarized as follows:

Espressif Systems 118 Release master

Submit Document Feedback
Chapter 2. ESP Friends

ESP32 ESP32-S3 ESP32-C2 ESP32-C3 ESP32-C6

General
Lighting
Bulb/Desk LEDC/I2C LEDC/I2C LEDC/I2C LEDC/I2C LEDC/I2C
Lamp
Ad- SPI SPI/RMT SPI SPI/RMT SPI/RMT
justable
Color
Tem-
perature
Strip
Spot- LEDC LEDC LEDC LEDC LEDC
light/Downlight/Candlelight/Ceiling
Light

Ambient
Lighting
Colorful SPI SPI/RMT SPI SPI/RMT SPI/RMT
Strip/String
Lights
Copper SPI SPI SPI SPI SPI
Wire
Lights
Aroma SPI SPI/RMT SPI SPI SPI/RMT
Lamp/Splicing
Lamp

Other
Acces-
sories
Silicon MCPWM MCPWM x x MCPWM/ETM+Analog
Con- Comparator
trolled
Dimmer

Other
Func-
tions
Music √ √ √ √ √
Rhythm
ESP- √ √ √ √ √
NOW
Local
Control
CSI √ √ √ √ √
Human
Detection
Function
Infrared x √ x √ √
Remote
Control

Light Reference Materials In addition, we currently have some public light github repositories, videos, and module
materials, as follows:
• Software Reference

Espressif Systems 119 Release master

Submit Document Feedback
Chapter 2. ESP Friends

– ESP-IDF LEDC Example

– ESP-IDF RMT LED STRIP Example
– Rhythm Flowing Light Example
• Module/Development Board Materials and Option Reference
– Espressif Product Selection Tool

Light Dimming Solutions Summary

PWM Dimming Solution PWM dimming is a technique to control LED brightness by adjusting pulse width, the
core of which is to adjust by changing the duty cycle of the current pulse (i.e., the proportion of high-level time in
the entire cycle time). When the duty cycle is high, the LED gets a long current time and high brightness; conversely,
when the duty cycle is low, the LED gets a short current time and low brightness. All ESP chips support using
hardware LEDC Driver / MCPWM to output PWM, with the LEDC driver recommended for implementation first,
as it supports hardware gradient, configurable frequency duty cycle, and a maximum resolution of 20 bit.

Note:
1. Does it support outputting complementary waveforms to adjust color temperature and brightness?
• Yes, the hpoint function of LEDC can be used for phase shifting.

I2C Dimming Solution I2C Dimming sends control commands to the dimming chip through the I2C bus, adjusting
the LED brightness by changing the output current of the dimming chip. The I2C bus consists of two lines: the data
line (SDA) and the clock line (SCL). All ESP chips support using hardware I2C dimming chips, and currently, perfect
driving has been completed on common dimming chips such as SM2135EH, SM2235EGH, SM2335EGH, BP5758,
BP5758D, BP5768, BP1658CJ, KP18058.

Note:
1. How much should the pull-up resistor for the I2C driver be selected?
• Usually choose between 2.2 k-4.7 k, the signal quality can be determined by actual measurement.

Single-line Dimming Solution The single-wire dimming solution is a method of controlling LED brightness
through a single communication line, the core of which is to adjust the brightness of the LED by sending control
signals through a specific communication protocol. There are currently 2 categories:
• WS2812 and SK6812 types use a separate data bus to transmit color data through specific timing control.
• Similar to power line carrier, multiplexing VCC and modulating communication data on it, only 2 wires are
needed for the bead.
This type of solution can be implemented on the ESP chip using RMT peripherals or SPI peripherals. It is recom-
mended to use SPI for bead communication control, and RMT is mostly used for receiving infrared remote control
data.

Note:
1. What is the principle of SPI implementation?
• Taking WS2812 as an example, it has RGB three-channel data, each channel is 1 byte, the default config-
uration SPI clock is 2.4 MHz, single bit transmission, then sending a bit is a clock about 400 ns, usually
use 3 bits to represent 0 code and 1 code, that is, 0 code is composed of 2 bit high + 1 bit low, 1 code is
composed of 1 bit high + 2 bit low, so each bit of 1 byte original data needs to be expanded to 3 bits to
represent 0 and 1, so 1 byte original data needs to be expanded to 3 bytes SPI data. If we send orange,
then the conversion is as follows:

Espressif Systems 120 Release master

Submit Document Feedback
Chapter 2. ESP Friends

255 (0b11111111) -> 11011011 01101101 10110110 -> 0xDB␣

,→0x6D 0xB6

127 (0b01111111) -> 10011011 01101101 10110110 -> 0x9B␣

,→0x6D 0xB6

0 (0b00000000) -> 10010010 01001001 00100100 -> 0x92␣

,→0x49 0x24

The actual data sent by SPI is {0xDB 0x6D 0xB6},{0x9B 0x6D 0xB6},{0x92 0x49 0x24 }, the
RGB data sequence of different light strips may be different, and need to be adjusted according to the actual
situation.
2. Does SPI support connecting multiple light strips?
• Yes, changing the SPI transmission mode to 4 bit can support 4 light strips. It should be noted that the
original data conversion to SPI data also needs to be changed. At this time, 4 bits of data will be sent in
1 clock.
3. Can you provide the design idea of SPI driving light strip driver?
• If the SPI clock is 2.4 MHz, each clock is 0.4167 us, if it is sent in 8 bit mode, 1 byte is sent in 1 clock,
10 KB is also 10000 clocks, and it is sent in 4160 us. Use the STC mode of SPI, and group 10 1 KB
brush light data in one spi_multi_transaction_t. The SPI queue length is set to 1, malloc 2
10 KB buf, each time the data is grouped, use spi_device_queue_multi_trans to send, then
another buf fills the data, after filling, use spi_device_get_multi_trans_result to get the
previous result of the light strip, after returning successfully, group the data again, and 2 buf cycle fill the
data.

Silicon Controlled Dimming Solution Triac dimming is a dimming technology that controls the brightness of a
lamp by adjusting the phase of the current. It is widely used in incandescent lamps, halogen lamps, and some LED
lamps compatible with triac dimming. The core is to adjust the phase angle of the triac conduction, changing the
conduction time of the current in each AC cycle, to achieve the regulation of the lamp s power output and brightness.
There are mainly two types of phase-cutting methods for triac dimming:
• Leading edge cutting: Cutting is performed in the first half of the AC waveform, and the Triac starts to conduct
at the leading edge of each AC cycle. Suitable for incandescent lamps and some compatible LED lamps.
• Trailing edge cutting: Cutting is performed in the second half of the AC waveform, and the Triac starts
to conduct at the trailing edge of each AC cycle. Suitable for some compatible LED lamps and electronic
transformers.
The software design follows the following 3 steps:
1. Phase detection: Detect the zero-crossing point of the AC power to determine the timing of the dimming
signal. Zero-crossing detection can be achieved through optocouplers and detection circuits.
2. Phase control: Calculate the corresponding conduction delay time according to the brightness set by the user,
and control the Triac to conduct at the appropriate time.
3. Trigger control: After detecting the zero-crossing point, trigger the Triac to conduct according to the set delay
time, generally using a 50 us pulse to trigger conduction.
In ESP chips, the above functions are usually implemented using MCPWM peripherals or ETM + Analog comparator
peripherals. It is recommended to use MCPWM peripherals for implementation. The implementation principle is:
Enable 2 comparators A and B on the same timer, and operate the same IO. Comparators A and B output low levels
when the timer counter is 0. Set a comparison value x, x is the delayed conduction time, and set comparator A
to output a high level when the timer is x, and comparator B to output a low level when the timer is x + 50. Use
the synchronization function of MCPWM to capture the zero-crossing point. The timer will be automatically reset
when synchronized, thus completing a phase-cutting control. The accuracy of the zero-crossing point capture can be
controlled to less than 1 us.

Note:
1. Can it be implemented on chips such as ESP32C2 that do not have MCPWM peripherals?
• It can be implemented using a gptimer + IO simulation scheme. All control functions need to be placed in
ram. However, due to chip and software design factors, the accuracy of zero-crossing point capture will
still be affected by system interrupts. Especially after enabling Wi-Fi and Bluetooth, it usually fluctuates

Espressif Systems 121 Release master

Submit Document Feedback
Chapter 2. ESP Friends

between 4.7 us ~ 20 us, which is very unstable. This will cause poor compatibility of the dimmer,
and some LED lamps compatible with the dimmer will have intermittent flickering. If the evaluation is
acceptable, the above scheme can be used.

Light Additional Feature Components

Music Rhythm Music rhythm is a lighting control technology that analyzes music signals in real time to synchronize
the lights with the rhythm, melody, and sound effects of the music. All ESP32 platform chips support local music
rhythm, obtain audio data through ADC, and then get waterfall, jump, gradient and other lighting effect data after
FFT or loudness calculation, refresh to the bulb through the driver, and display.
• Example code
• Demo video

ESP-NOW Local Control Function ESP-NOW is a connectionless Wi-Fi communication protocol defined by
Espressif. In ESP-NOW, application data is encapsulated in the action frames of various vendors, and then transmitted
from one Wi-Fi device to another Wi-Fi device without connection. In the field of smart lighting, this technology is
often used as a random sticker switch for lamps.
• Example Code
• Demonstration Video

CSI Human Detection Function Channel State Information (CSI) is an important parameter describing the char-
acteristics of wireless channels, including signal amplitude, phase, signal delay, and other indicators. In Wi-Fi com-
munication, CSI is used to measure the state of wireless network channels. CSI is very sensitive to environmental
changes. It can not only perceive large-scale movements such as walking and running of people or animals, but also
perceive subtle movements such as breathing and chewing in a static environment. In the field of smart light bulbs,
CSI can be used as a human perception sensor to realize the function of turning on the light when someone comes
and turning off the light when someone leaves.
• Example Code
• Demonstration Video

Infrared Remote Control Infrared remote control is a technology that uses infrared light signals to transmit control
instructions, which is widely used in the remote control operation of household appliances such as televisions, air
conditioners, audio equipment, and lighting fixtures. The infrared remote control system usually consists of an infrared
transmitter (remote control) and an infrared receiver (controlled device). The infrared transmitter modulates the
infrared light signal and sends out the control instruction in the form of pulse coding. After the infrared receiver
receives the signal, it demodulates and decodes the control instruction, and then performs the corresponding operation.
In the lighting field, this technology is used as a local infrared remote control for light strips, downlights, spotlights,
and ambient lights.
• Example Code

Light Bulb Driver Component The Light Bulb Component encapsulates several common dimming schemes in
light bulbs, and adds effects, calibration, state memory, power limit and many other common functions, making it
easy for developers to integrate into their own applications. All ESP32 series chips are currently supported.

Supported dimming schemes are as follows

• PWM scheme
– RGB + C/W
– RGB + CCT/Brightness
• I2C dimming chip scheme
– SM2135EH

Espressif Systems 122 Release master

Submit Document Feedback
Chapter 2. ESP Friends

– SM2X35EGH (SM2235EGH/SM2335EGH)
– BP57x8D (BP5758/BP5758D/BP5768)
– BP1658CJ
– KP18058
• Single bus
– WS2812

Supported lamp board layouts are as follows

• Single channel: Cold or warm color temperature beads, can complete brightness control under single color
temperature.
• Dual channel: Cold and warm beads, can complete color temperature and brightness control.
• Three channels: Red, green, and blue beads, can complete any color control.
• Four channels: Red, green, blue, cold or warm beads, can complete color and single color temperature bright-
ness control, if a color mixing table is configured: it supports using these beads to mix different color temper-
atures, to achieve color temperature control.
• Five channels: Red, green, blue, cold, warm beads, can complete color and color temperature brightness con-
trol.

Gradient Principle The gradient in the light bulb component is implemented by software. Each channel records
the current value, final value, step size, number of steps, number of cycles, minimum value, the last two parameters
are used for effects. When using the API to set the color, it will sequentially change the final value, step size, and
number of steps, and enable the gradient timer. The timer triggers a callback every 12 ms. The callback function
will check the number of steps of each channel. As long as there are steps that have not been executed, it will add
or subtract the current value according to the step size and update it to the underlying driver. When the number of
steps of all channels is 0, it means that the gradient is completed, and the timer will be stopped at this time.

Low Power Implementation If the bulb is to pass power consumption certifications such as T20, after optimizing
the lamp board power supply, some low-power configurations need to be made on the software side. In addition to the
configurations mentioned in the Low Power Mode Usage Guide, some logic also needs to be done in the driver part.
The bulb component has added related content in both the PWM and I2C dimming driver schemes. The specific
logic is that when the switch is turned on, the I2C scheme calls the low-power command of the dimming chip itself
to exit or enter low power. In the PWM scheme, the ESP32 needs to manage the power lock due to the use of the
APB clock source, otherwise the light will flicker. When the light is on, take the power lock and disable dynamic
frequency adjustment. When the light is off, release it. Other chips use the XTAL clock source and do not need to
take any measures.

Maintain Color After Abnormal Restart The implementation in the bulb driver component is as follows: The
PWM scheme can use the XTAL clock source, and the software restart does not affect the LEDC driver output; The
I2C scheme needs to do software logic. After each successful operation of the lamp, the color needs to be recorded
in the flash. After an abnormal restart, the color saved in the flash is used directly to light the lamp.

Power-on Lighting Speed When using the bulb driver component to light up, the time from the lamp board power
supply to the lamp lighting is usually between 150 ~ 300 ms. The main time consumption is in the log printing and
various verifications related to chip security (Flash encryption, secure boot, etc.) in the ROM and bootloader stages.
If encryption is not enabled and all logs at the startup stage are turned off, the lighting time will be less than 100 ms.

2.3.6 Mesh Solutions

Espressif Systems 123 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Comparison of Different Mesh Solutions

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Common Espressif Mesh solutions include:

• BLE Mesh : esp-ble-mesh doc
• Thread : esp-openthread doc
• Wi-Fi Mesh : esp-mesh-lite sdk
• Zigbee : esp-zigbee sdk

Note: In addition, ESP-Now can sometimes serve as a supplementary communication solution for the above Mesh
solutions.

The following is a comparison table of key points of different Espressif Mesh solutions:

Table 6: Mesh Solution Comparison

Feature ESP BLE ESP Thread ESP-Mesh- ZigBee Mesh ESP-Now
Mesh Mesh Lite
Node count Theoretically Internal testing Internal testing Theoretical Less than 100
no more than can reach 300 can reach 100 limit of 65000, nodes
32767, internal nodes nodes internal testing
testing can can reach 300
reach 100 nodes nodes
Communica- Depends on the The distance Less than 100 The distance Recommended
tion distance packet sending to maintain the m, tested to to maintain the not more than
between nodes power, it is connection can reach 170 m connection can 150 m
recommended reach 200 m reach 300 m
that the dis-
tance between
adjacent nodes
is not more than
50 m
Throughput Low, less than 1 Low, actual test High, actual test Low, actual test Low, less than
Kbps is about 4 - 5 up to 20 Mbps, is about 16.9 0.5 Mbps
KB/s the deeper Kbps
the hierarchy,
the lower the
throughput
Single-hop Within 100 ms Average 10 ms Within 100 ms Average 16 ms Within 10 ms
delay at the limit dis-
tance of 50 m,
within 50 ms at
normal distance
(below 50 m)

The core parameters of various Espressif Mesh solutions are explained below.

ESP BLE Mesh Advantages:

• Compatible with most devices, supports direct control and provision protocol standards from mobile phones
• Can access third-party devices that support BLE Mesh

Espressif Systems 124 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Supports low-power devices

Disadvantages:
• Data throughput is low, less than 1 Kbps
Core parameters are as follows:
• The chip is required to support BLE Mesh
• Supports coexistence of Wi-Fi & BLE Mesh & BLE ADV, but the device acting as a gateway should give
as much RF time slice to BLE Mesh as possible, and the device acting as a node can relax this requirement
appropriately
• Expected node count: theoretically no more than 32767, actually depends on the capability of the provisioner
(gateway), using ESP32-S3 as the gateway, internal testing can reach 100 nodes
• Expected communication distance between nodes: depends on the packet sending power, it is recommended
that the communication distance between adjacent nodes is not more than 50 m
• Coverage range: theoretically unlimited, actually depends on the uniform distribution of nodes
• Expected throughput per node: In the smart home field, scenarios with low data volume such as control signals,
the heartbeat packet frequency of each node needs to be limited when there are many nodes
• Recommended chips: Nodes can use chips such as ESP32, ESP32-C3, ESP32-H2, and it is recommended to
use the ESP32-S3 with PSRAM version for the gateway
• Single-hop delay: The delay at the extreme distance of 50 m is within 100 ms, and the delay at the normal
distance (below 50 m) is within 50 ms

ESP Thread Mesh Advantages:

• Compatible with standard Thread devices, rich device networking functions
• IP-based communication mode (6LoWPAN and IPv6)
• Supports networking of hundreds of nodes (tested with 300 nodes)
• Fast networking speed, lower latency, self-recovery
• Supports low-power devices
Disadvantages:
• Low data throughput, 802.15.4 MAC rate is 250 Kbps, UDP layer rate is 8 KB/s, actual test is about 4 - 5
KB/s
The core parameters are as follows:
• The chip is required to support 802.15.4 MAC, currently supported are ESP32-H2 and ESP32-C6
• Networking requires a Thread Border Router (OTBR) and several Thread nodes, any OTBR that complies
with the Thread standard can be networked
• Expected number of nodes: The theoretical value can be hundreds or more, internal testing shows that 300
nodes can be networked successfully
• Expected communication distance between nodes: Depends on the packet sending power, under the condition
of H2 Rx sensitivity of -102.5 dBm, txpower 20 dBm, the distance to maintain the connection can reach about
200 m
• Coverage: Theoretically unlimited, actually depends on the uniform distribution of nodes
• Expected throughput per node: In the smart home field, scenarios with low data volume, suitable for simple
control, sensor temperature collection and other IoT fields
• Recommended chips: Nodes can use chips such as ESP32-H2 and ESP32-C6, OTBR is recommended to use
ESP32-S3 with PSRAM version + ESP32-H2 for receiving and sending 802.15.4 messages
• Sub-node communication: Each sub-node can communicate with each other, and if the OTBR can go online
and enables NAT64, the sub-node can go online through the OTBR. It has advantages for scenarios where
sub-nodes need to interact with the cloud and the throughput demand is small
• Single-hop delay: Average 10 ms

ESP-Mesh-Lite Advantages:
• High throughput, the shielded box test results show that the maximum throughput of the second layer node
interaction can reach 20 Mbps, decreasing layer by layer, with the highest at the fifth layer being 6 Mbps.
• Connection stable, supports other non-ESP devices to communicate with devices in Mesh-lite via Wi-Fi.

Espressif Systems 125 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• No need for a gateway, can directly access the Internet

Other points:
• ESP-Now function has been integrated
The core parameters are as follows:
• Expected number of nodes in a single Mesh network: less than 100
• Expected communication distance between nodes: less than 100 m, if the data throughput requirement is not
high, it can reach 170 m through testing
• Supported levels: Currently supports up to 15 levels, recommended 5 to 6 levels
• Expected range of a single Mesh network: Theoretically unlimited, the actual range is mainly limited by the
maximum number of nodes, the maximum level, and the maximum communication distance between nodes
• Single-hop delay: Within 100 ms under normal test environment

ZigBee Mesh Advantages:

• Compatible with standard ZigBee nodes
• Fast networking speed, low latency, self-recovery
• Supports low-power devices
Disadvantages:
• Low data throughput, 802.15.4 MAC rate is 250 Kbps, ZigBee rate is 16.9 Kbps
The core parameters are as follows:
• The chip is required to support 802.15.4 MAC, currently ESP32-H2 and ESP32-C6 can be chosen
• Networking requires a Coordinator and several ZigBee nodes (routers or end nodes), any that comply with the
ZigBee standard can be networked
• Expected number of nodes: The theoretical upper limit is 65000, ultimately depends on how long each node
needs to communicate on the network, and how much data loss or retransmission the application can tolerate.
Internal testing shows that 300 nodes can be stably networked, point-to-point communication
• Expected communication distance between nodes: Depends on the packet sending power, under the condition
of H2 Rx sensitivity of -102.5 dBm, txpower 20 dBm, the distance to maintain the connection can reach about
300 m
• Coverage: Theoretically unlimited, actually depends on the uniform distribution of nodes
• Expected throughput per node: In the field of smart homes, control signals and other low data volume scenarios,
it is suitable for simple control, sensor temperature collection and other IOT fields
• Recommended chips: Nodes can use chips such as ESP32-H2 and ESP32-C6, and it is recommended to use
ESP32-S3 with PSRAM version + ESP32-H2 for receiving and sending 802.15.4 messages as Coordinator
• Single hop delay: Average 16 ms

ESP-Now Advantages:
• Quick response, low power consumption
Disadvantages:
• Small throughput
The core parameters are as follows:
• Current ESP chip/module selection: All ESPs that support Wi-Fi are available
• Whether BLE function is needed at the same time: It can coexist with BLE, and there will be power consump-
tion requirements when it involves BLE coexistence
• Expected communication method: ESP-NOW has two communication methods, unicast and broadcast. Mesh
often recommends the form of broadcast, and the subsequent performance data, if not specified, are all based
on the form of broadcast
• Estimated number of nodes: Less than 100
• Estimated communication distance between nodes: Less than 150 m is relatively stable, and the limit distance
in open environment is 300 m (point-to-point test, broadcast distance is further)
• Expected throughput per node: Must be less than 0.5 Mbps

Espressif Systems 126 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Expected communication delay: Less than 10 ms within a communication distance of 150 m

• Whether there is a requirement for low power consumption: If there is a requirement for low power consump-
tion, the estimation method is consistent with the Wi-Fi auto light sleep (power save) scenario, and you can
also refer to the coin cell demo
• Whether it needs to connect to a Wi-Fi router: It involves channel switching, and it needs to confirm whether
it supports channel switching after connecting to the router according to the IDF version
• Whether it needs to coexist with upper layer communication protocols (such as TCP/UDP, etc.): The recom-
mended use scenario of ESP-NOW is LAN. If it involves upper layer transmission protocols (TCP, etc.), it is
recommended to use Thread

Introduction to ESP-Mesh-Lite Solution

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Overview of ESP-Mesh-Lite Solution ESP-Mesh-Lite is a Mesh solution built on the Wi-Fi protocol, based on the
SoftAP + Station mode, and modeled after IoT-Bridge. ESP-Mesh-Lite allows a large number of devices distributed
over a wide area (both indoors and outdoors) to connect with each other within the same WLAN (Wireless Local
Area Network). The advantages of this solution are as follows:
• ESP-Mesh-Lite is a network structure different from traditional Wi-Fi networks. In the ESP-Mesh-Lite net-
work, nodes do not need to connect to a central node, but can directly connect with neighboring nodes. This
interconnection between nodes allows for a wider network coverage area, unrestricted by the distance to the
central node.
• Traditional Wi-Fi networks usually adopt a centralized structure, where all nodes connect to a central node
(such as a router). This network structure may cause the central node to be capacity-limited, affecting the
scalability and stability of the network. However, in the ESP-Mesh-Lite network, nodes are interconnected,
allowing nodes in the network to be responsible for data forwarding of neighboring nodes, no longer limited
by the capacity of the central node.
• Since each node in the ESP-Mesh-Lite network is assigned an IP address by the parent node, nodes can ac-
cess the network as if they were individual devices connected to a router. The transmission of information is
imperceptible to the parent node, greatly reducing the difficulty of application layer development.
In summary, the ESP-Mesh-Lite network has a tree-like network structure, strong scalability, wide coverage, inter-
connected nodes, and increased network flexibility. Compared with traditional Wi-Fi networks, ESP-Mesh-Lite has
greater advantages and applicability in IoT applications.

Common Application Scenarios of ESP-Mesh-Lite

• Smart home control systems: Due to the interconnection between nodes, smart devices can communicate
directly with neighboring devices, improving response speed and stability.
• Smart agriculture: Many wireless sensors in the fields need to communicate with each other and send messages
to the cloud.
• Photovoltaic inverters: Upload collector data to the cloud.
• Smart lighting: Group control and group control of lights and data reporting.
• Environmental monitoring: Can achieve data collection and transmission of multiple environmental monitoring
devices, providing more comprehensive environmental data.
• Education and training: Connect multiple teaching devices and student terminals to achieve sharing and inter-
action of teaching resources.
• Smart security: Multiple security devices can achieve data sharing and linkage control, improving the response
speed and reliability of the security system.
• Remote device management: Perform OTA firmware upgrades for all devices in the network.

Espressif Systems 127 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Reference Materials for Getting Started with ESP-Mesh-Lite ESP-Mesh-Lite SDK

• ESP-Mesh-Lite SDK
ESP-Mesh-Lite Solution Guide Document: (Must-read, provides an introduction to the ESP-Mesh-Lite protocol)
• Chinese Document
• English Document
ESP-Mesh-Lite Basic Example Link: (It is recommended for developers to run this example to simply understand
the basic usage of ESP-Mesh-Lite and related APIs)
• Basic Example Link
ESP-Mesh-Lite + Rainmaker Example Link: (Includes provision, LAN OTA, Mesh node communication and other
advanced usage)
• Rainmaker Example Link
ESP-Mesh-Lite Component Manager Link:
• Component Manager

How to Enable ESP-Mesh-Lite Enabling ESP-Mesh-Lite is very convenient, developers only need to simply call
some API commands to enable ESP-Mesh-Lite. Refer to the mesh_local_control example:
1. Initialize the NVS partition of ESP32 to save configuration information.
2. Initialize the network interface. Call the esp_netif_init() function.
3. Create the default event loop. Call the esp_event_loop_create_default() function.
4. Create all network interfaces, including STA mode and SoftAP mode. Call the esp_bridge_create_all_netif()
function.
5. Initialize Wi-Fi functions, including initializing Wi-Fi s STA mode and SoftAP mode, first connect to the
specified Wi-Fi hotspot (STA mode), and then open the SoftAP hotspot (SoftAP mode). When connecting to
Wi-Fi and opening SoftAP, try to read the previously saved configuration from NVS. If the reading fails, use
the predefined default value.
Station:
• Define a wifi_config_t structure variable wifi_config to configure the parameters of Wi-Fi s
STA mode.
• Set the ssid (Wi-Fi hotspot name) and password (Wi-Fi hotspot password) of wifi_config.sta.
• Set the Wi-Fi mode to STA mode, and use wifi_config.sta.ssid and wifi_config.sta.password
as parameters to connect to the specified Wi-Fi hotspot. The fourth parameter is NULL,
indicating that no callback function is set. Call the esp_bridge_wifi_set function.
SoftAP:
• Clear the content of the wifi_config structure to prepare for the configuration of SoftAP mode
below.
• Define a variable to store the SSID length in SoftAP mode.
• Get the SSID in SoftAP mode from NVS. If the acquisition fails, use the de-
fault value defined by the CONFIG_BRIDGE_SOFTAP_SSID macro. Call the
esp_mesh_lite_get_softap_ssid_from_nvs function.
• Define a variable to store the password length in SoftAP mode.
• Get the password in SoftAP mode from NVS. If the acquisition fails, use the de-
fault value defined by the CONFIG_BRIDGE_SOFTAP_PASSWORD macro. Call the
esp_mesh_lite_get_softap_psw_from_nvs function.
• Set the Wi-Fi mode to SoftAP mode, and use wifi_config.ap.ssid and wifi_config.ap.password
as parameters to open the SoftAP hotspot. The fourth parameter is NULL, indicating that no
callback function is set. Call the esp_bridge_wifi_set function.
6. Provide default values for Mesh network configuration. Define the esp_mesh_lite_config_t structure variable
and initialize it with the ESP_MESH_LITE_DEFAULT_INIT() macro.
7. Initialize ESP-Mesh-Lite and start the Mesh-Lite network. Call the esp_mesh_lite_init() function and configure
it with the structure defined in the previous step.

Espressif Systems 128 Release master

Submit Document Feedback
Chapter 2. ESP Friends

ESP-Mesh-Lite Performance Reference Appendix

• Common performance indicators of ESP-Mesh-Lite
• Comparison of different Mesh solutions

2.3.7 Provisioning Solution

Provisioning Scheme Introduction

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Attention: The provisioning scheme in this document refers to the scheme for configuring and connecting ESP
devices to Wi-Fi in different ways. Other schemes such as BLE-MESH provisioning are not included in this
document.

Scheme Overview During the code development phase, Wi-Fi information (SSID and PASSWORD) is often writ-
ten directly into the program, which cannot be changed at any time to connect to the desired Wi-Fi, which is obviously
impractical. Therefore, we have developed and launched a series of provisioning schemes:
• SoftAP Provisioning
• Blufi Provisioning
• Smartconfig Provisioning
• WEB Provisioning
Taking the common application scenario of provisioning smart sockets as an example, as follows.

Allow users to configure Wi-Fi information to ESP devices through mobile phones. Different provisions have their
own advantages and disadvantages, and the next section elaborates on the details of these provisioning schemes.

Espressif Systems 129 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Common Provisioning Application Scenarios

1. Blufi Provisioning (Requires ESP chip to support BLE) The ESP device will broadcast BLE, and the nearby
mobile phone will ask the user whether to connect to the ESP device via BLE after receiving the broadcast. If the
connection is selected, the mobile phone can send the Wi-Fi information that the ESP device needs to connect to
the ESP device. In this process, the user does not need to switch Wi-Fi networks, but needs to turn on the mobile
phone s Bluetooth. The user experience is relatively better than SoftAP provisioning. However, it is necessary to add
Bluetooth-related code on the device side, which will increase the size of the firmware and occupy a certain memory
before the provisioning is completed.
Software Code & APP Reference Links:
• Blufi Provisioning Example
• Android APP & Source Code
• iOS APP
• iOS APP Source Code
• BluFi Protocol
• BluFi Provisioning Guide
• Blufi WeChat Provisioning Mini Program Corresponding Source Code

2. Smartconfig Provisioning This method does not require the establishment of any communication link. The
mobile phone sends UDP broadcast packets of different lengths to represent Wi-Fi information. The ESP device
listens to all data frames within the signal coverage range in promiscuous mode and obtains Wi-Fi information through
a certain algorithm. The disadvantage is that the success rate of provisioning is greatly affected by the environment.
Software Code & APP Reference Links:
• Smartconfig Provision Example
• Android APP & Source Code
• iOS APP
• iOS Source Code

3. SoftAP Provision The ESP device will establish a Wi-Fi hotspot, and after the user connects their phone
to this hotspot, they send the Wi-Fi information that the ESP device needs to connect to. This provisioning mode
requires the user to manually connect to the hotspot network of the ESP device, which makes the provisioning process
complicated, but this method generally has a higher success rate than Smartconfig provisioning.
Software Code & APP Reference Links:
• SoftAP Provision Example
• Android APP
• iOS APP
• Android APP Source Code
• iOS APP Source Code

4. WEB Provision (Currently not recommended, and there are no mature examples) Establish a hotspot on
the ESP device, connect with the phone, and open the configuration page in the browser to complete the provision.
This method is very reliable and allows provisioning to be completed on the computer. The disadvantage is that it
requires space on the device to embed the webpage.
This solution is currently not recommended. If you still need code references, you can refer to WEB Provision
Example. Please note that this example is very old and it is not guaranteed whether it can be executed normally on
the new version of ESP-IDF. It only has some reference value in terms of code logic.
The table below summarizes the key parameters of the four provisioning schemes mentioned above.

Espressif Systems 130 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Table 7: Provisioning Scheme Summary Table

Provisioning Need Extra Need Extra Provisioning Operation Recommen-
Scheme BLE Mobile APP Success Rate Complexity dation Level
Blufi Provision ✓ ✓ High Simple Recommended
Smartconfig × ✓ Relatively High Simple Medium
Provision
SoftAP Provi- × ✓ High Complex Medium
sion
WEB Provision × × High Complex Medium
(Currently not
recommended)

Reference Materials The brief summary of the provisioning scheme materials is as follows:
• Blufi Provision Example
• Smartconfig Provision Example
• SoftAP Provision Example

Attention: If you need more references like provision APP, please get the corresponding information in Common
Provisioning Application Scenarios.

2.3.8 Wireless Network Card Solution

Comparison of Different Wireless Network Card Solutions

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

Most Espressif SoCs can serve as Wireless Network Interface Controllers (WNICs), enabling other IoT devices
and MCUs to access the internet. The ESP-WNIC solution provides just such functionality. Users can choose
the Espressif SoC that best suits their application scenario, thereby benefiting from the low development cost, easy
maintenance, and highly scalable features offered by Espressif SoCs. Through the ESP-WNIC solution, users can
quickly join a wireless network, connect to the cloud platform, transmit data, and achieve remote control.
Common Espressif wireless network card solution SDKs include:
• esp-at
• esp-hosted
• esp-iot-bridge
• usb dongle
Below is a comparison table of different Espressif wireless network card solutions:

Espressif Systems 131 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Table 8: WNIC Solution Comparison

Network Card So- ESP-AT ESP-Hosted ESP-IoT-Bridge USB-Dongle
lution
MCU Adaptation Easy Medium Medium Easy 1
Difficulty
MCU Workload in Light Medium Medium Medium
Complete Solution
MCU Resource Re- Ability to parse Ability to run Ability to run Ability to support
quirements strings TCP/IP network TCP/IP network USB host and
stack stack TCP/IP network
protocol stack
Recommended Linux, RTOS, Non- Linux, RTOS Linux, RTOS Linux, MacOS,
MCU System OS Windows
Hardware Commu- UART, SDIO, SPI, SDIO, SPI USB, ETH, SPI, USB
nication Interface USB SDIO
Recommended 0 10 Mbps 0 20+ Mbps 0 25 Mbps 0 6 Mbps
Throughput Range
Typical Application Smart home, con- Robots, set-top Smart home, con- Robots, set-top
Scenarios sumer electronics, boxes, remote sumer electronics, boxes, etc.
POS machines, video, etc. IPC, low power
advertising screens, scenarios requiring
remote data col- MCU sleep, etc.
lection, LBS
positioning, low
power scenarios
requiring MCU
sleep, etc.
Resource Links esp-at esp-hosted esp-iot-bridge 2 usb dongle

Note:
1
• : The MCU adaptation difficulty of the USB-Dongle is easy, but please note that the MCU needs to support
systems with standard USB ECM/NCM protocol stacks such as Linux, MacOS, or Windows.
• 2 : If access to esp-iot-bridge Github is difficult, you can alternatively visit esp-iot-bridge component for further
understanding.

The complete explanation of the advantages and disadvantages of various Espressif wireless gateway solutions is as
follows.

ESP-AT Advantages:
• No development required on the ESP side
• Low MCU resource requirements
• Suitable for various MCU systems, such as Linux, RTOS, non-operating systems
Disadvantages:
• Lower data throughput (0~10 Mbps)
Reference materials:
• Official SDK: esp-at
• Official documentation: ESP-AT User Guide
• Chinese blog: Espressif ESP-WNIC Wireless Network Card Solution
• Chinese video: Espressif ESP-WNIC Wireless Network Card Solution

Espressif Systems 132 Release master

Submit Document Feedback
Chapter 2. ESP Friends

ESP-Hosted Advantages:
• Suitable for various MCU systems, such as Linux, RTOS
• High data throughput, up to 25 Mbps with ESP32-C6 and SDIO interface, for specific throughput test results,
refer to Throughput performance
Disadvantages:
• The MCU needs to have the ability to run the TCP/IP network stack
• High MCU adaptation difficulty and workload
• ESP as a peripheral of the MCU, cannot work independently and completely
Reference materials:
• Official SDK: esp-hosted
• Official documentation: ESP-Hosted Readme
• Chinese blog: Espressif ESP-WNIC Wireless Network Card Solution
• Chinese video: Espressif ESP-WNIC Wireless Network Card Solution

ESP-IOT-BRIDGE Advantages:
• Supports multiple peripherals such as ETH, SPI, SDIO, USB, and can be extended to support ESP Mesh Lite
Solution
• High data throughput, using ESP32 and SDIO interface can reach 25 Mbps
• Low development cost for ESP and main MCU
• Can independently run some application functions, providing conditions for low power scenarios such as MCU
sleep
Disadvantages:
• MCU needs to have the ability to run TCP/IP network stack
References:
• Official SDK: esp-iot-bridge
• Official documentation: ESP-IoT-Bridge Solution
• Chinese blog: Espressif ESP-IoT-Bridge Solution Supports Flexible Device Provisioning
• Chinese video: Espressif ESP-IoT-Bridge Networking Solution

USB-Dongle Advantages:
• Low adaptation difficulty on MCUs supporting USB host ECM/NCM Class (such as Linux, Windows, MacOS)
• High data transmission stability (using USB interface)
Disadvantages:
• Relatively low data throughput (0~6 Mbps)
• Limited application scenarios (such as robots, set-top boxes, etc.)
• ESP as a peripheral of MCU, cannot work independently and completely
References:
• Official example: usb dongle
• Official documentation: USB-Dongle Readme

2.4 Recommended Tools

In this section, we will introduce some common tools. Although they are not provided by ESP, they play an important
role in ESP development and debugging. These tools include but are not limited to Wireshark, Postman, etc. By
mastering the use of these tools, you will be able to carry out ESP development and debugging more efficiently,
thereby saving valuable time and improving development efficiency.

Espressif Systems 133 Release master

Submit Document Feedback
Chapter 2. ESP Friends

2.4.1 Wireshark Packet Capture Tutorial on Windows

Note: This document is automatically translated using AI. Please excuse any detailed errors. The official English
version is still in progress.

This article provides a detailed tutorial on how to use Wireshark to capture Wi-Fi wireless packets on Windows 10.

Installing Wireshark

About Wireshark Wireshark (formerly Ethereal) is a network packet analysis tool. This tool is mainly used to
capture network packets, automatically parse them, and display detailed information about the packets for user anal-
ysis. It can run on both Windows and Linux operating systems. This tool can be used to capture and analyze various
protocol packets. This article will explain how to install and use this tool.

Download and Installation The Kali Linux system comes with the Wireshark tool, but it is not installed by default
in the Windows system. Go to the Wireshark official website. Click on Get started to go to the download page.

In the Stable Release section, you can see that the latest version of Wireshark is 4.2.4, and download links for Windows
(32-bit and 64-bit), Mac OS, and source code packages are provided. You can download the appropriate software
package according to your operating system.
Here we download the 64-bit Windows installation package. Select Windows Installer(64-bit) to down-
load. The downloaded file name is Wireshark-win64-4.2.4.exe. Double-click the downloaded software
package to install it. During installation, use the default values and click the Next button. Note that Wireshark will
ask the user whether to install the Npcap plugin synchronously (selected by default).
Npcap is an advanced packet capture and network sniffing software tool created by the Nmap project. It is a lightweight
but powerful platform that allows users to perform real-time network traffic analysis and monitoring on the Windows
operating system. Pay attention to the version of Npcap during this step. The early version of Npcap-1.7.1 could not
use cmd to open the network card s monitor mode, which has been fixed in version 1.76. For more information,
refer to source. The latest downloaded Wireshark comes with version 1.78, which can be installed directly.

Attention: Npcap will pop up a second installation page, where you need to check the two options in the figure
below (not checked by default), otherwise you will not be able to capture 802.11 packets.

After installation, the Wireshark icon will appear in the Windows Start menu.

Espressif Systems 134 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 135 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Packet Capture Network Card

The primary consideration is that the packet capture network card needs to support Monitor mode, followed
by the wireless protocols and transmission rates supported by the network card.

Monitor Mode Monitor mode, or RFMON (Radio Frequency Monitor), refers to the working mode in which the
wireless network card can receive all data streams passing through it, corresponding to other modes of IEEE 802.11
network cards, such as Master (router), Managed (ordinary mode network card), Ad-hoc, etc. Monitor mode does not
distinguish the target MAC address of the received packets, which is similar to promiscuous mode. However, unlike
promiscuous mode, monitor mode does not require a connection to be established with the wireless access point
(AP) or Ad-hoc network. Monitor mode is a special mode unique to wireless network cards, while promiscuous mode
applies to both wired and wireless network cards. Monitor mode is commonly used for network discovery, traffic
monitoring, and packet analysis (source: Wikipedia).

Determine the Modes Supported by the Network Card You can use the Npcap tool to view the current mode
of the network card, the supported modes, and turn on monitor mode.
1. Press win+R or enter cmd in the start menu to open the cmd command prompt window:

2. To view the GUID of the network card, enter netsh wlan show interfaces:

3. To view the current mode, copy the GUID, then enter WIanHelper.exe + GUID + modes, for example:

wlanhelper.exe 00971d40-8f3c-426d-bab3-5a38ce789c45 modes

You can then view the modes supported by the network card. Many built-in network cards in laptops will only
have managed mode, in which case you need to purchase a wireless network card that supports monitor mode
separately.

4. To turn on monitor mode for the network card, enter WlanHelper.exe + GUID + mode monitor,
for example:

wlanhelper.exe 00971d40-8f3c-426d-bab3-5a38ce789c45 mode monitor

Success will be indicated by Success:

Espressif Systems 136 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Attention: cmd needs to be opened with administrator privileges, otherwise it will not be able to turn
on monitor mode and will report an error. You can also enter mode to view the current mode. For more
usage of WlanHelper, you can enter WlanHelper.exe -h to view.

Network Card Selection Choose a suitable wireless packet capture card according to your packet capture needs.
If you need to capture Wi-Fi 6 packets, you need to choose a wireless card that supports the 802.11 ax protocol.
Refer to the following table for the comparison of Wi-Fi protocol versions:

Generation IEEE Standard Radio Frequency (GHz)

Wi-Fi 6/6E 802.11ax 2.4, 5/6
Wi-Fi 5 802.11ac 5
Wi-Fi 4 802.11n 2.4, 5

You can search for keywords such as wireless packet capture and air packet capture card on
shopping websites. Generally, cards with packet capture capabilities support monitor mode.

If the product does not provide detailed parameters, but provides the model of the wireless chip used, you can directly
search for the model to view the detailed parameters of the chip:
This article takes the Cisco packet capture card with the Ralink RT3572 chip as an example. This chip supports the
802.11n protocol with a maximum rate of 300 Mbps and can capture empty packets of the Wi-Fi 4 protocol.

Espressif Systems 137 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Configuring the Network Card

After getting the network card, you need to install the corresponding driver. Some network cards are plug-and-play
and do not require installation. After plugging in the network card, open Control Panel - Device Manager ,
find the newly inserted network card in the Network Adapters column, double-click to view detailed information.
If the driver is not compatible, there will be a yellow triangle:

If your network card cannot be used after plugging in, this article introduces three methods to obtain the driver for
the network card:
• Use the installation method provided by the seller when purchasing the network card, including but not limited
to: the seller provides download links and installation methods, and the network card comes with a storage disk
with the corresponding driver.
• Use third-party one-click installation software such as Driver Genius or Driver Master to automatically install
the appropriate driver for the network card.
• Search for the model of the network card or the model of the wireless chip, and go to the corresponding chip
official website or third-party software to directly download the corresponding driver.
After installation, some network cards need to restart the computer to adapt. After successful installation, open
Network Adapter - WLAN in the lower right corner to search for nearby routers:

Espressif Systems 138 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Capture Packets Using Wireshark

After installing Wireshark, you can run it to capture packets. Start Wireshark:

This is the main interface of Wireshark, which displays the currently available interfaces, such as Local Con-
nection 8 , WLAN 2 , etc. To capture packets, you must first select an interface, indicating that the packets
on this interface are captured. For basic concepts of network structure and protocols, you can refer to the blog:
Understanding the Basic Principles of Wi-Fi Networks.

Capture Ethernet Packets You can use Wireshark to capture packets from your computer s network card and
analyze the captured packets.

Attention: Loopback data of localhost accessed by the local machine does not go through the network card. To
capture loopback data, you need to specify that the loopback data should be forwarded to the gateway first.
Wireshark can open and analyze packet capture files generated by other tools.

Espressif Systems 139 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Select the Ethernet 4 interface to capture packets. Click on Start Capture at the top left corner or double-click
on the interface name to begin capturing network data. While browsing the web on the local computer, Wireshark
will capture data on the Local Connection interface.

Wireshark will continue to capture data on the Local Connection . If you no longer need to capture, you can
click on the Stop Capture button at the top left corner to stop capturing.

Capture Wireless Packets

Set Capture Options The menu bar Capture-Options (shortcut Ctrl + k ) can enter the capture option
setting interface:

Select the recently configured wireless network card. View the corresponding IP address by opening the drop-down
menu:

Espressif Systems 140 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Attention: The IP address may change before and after connecting to the router. Please get the latest interface
information through Capture-Refresh Interface List (shortcut F5):

Select Capture Card The network interface names configured by different computers may be different. Confirm
the wireless network card for packet capture using the following methods:

Method 1 After connecting to a wireless network, use win+R or enter cmd in the start menu to open the cmd
command prompt window:

Enter ipconfig in the command bar and press enter, you can see the interface information of the current network,
and the corresponding IP address can determine that the wireless network card is WLAN 2:

Espressif Systems 141 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 142 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Method 2 Alternatively, unplug the network card and try capturing with WLAN 2 in Wireshark. If the system
prompts that the interface cannot be found, or Menu-Capture-Refresh Interface List, you can also
determine the interface name of this network card.

Method 3 Open the cmd command prompt window, enter netsh wlan show interfaces, and you can
view the corresponding wireless network interface information.

Determine the Capture Channel Select the Wi-Fi channel you need to capture. If you want to capture the in-
teraction information of the router under test, you can confirm the channel, bandwidth, and other information of the
router as follows:

Method 1 Open the cmd command prompt window, connect the computer to the router under test, enter netsh
wlan show interfaces, and you can view the channel of the current connection.

Method 2 Check in the router administrator settings interface, not expanded here.

Method 3 Download Wi-Fi sniffing applications on your phone, such as WiFi Magic Box, wifiman, WiFi Analyzer,
inSSIDer, WirelessMon, etc., to view the surrounding AP information and channel analysis.

Set Monitor Channel Open the cmd command prompt window, follow the method introduced in the previous
Determine the Modes Supported by the Network Card section to enable the monitor mode of the network card.

Espressif Systems 143 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Attention: After opening this mode, the connected network will be disconnected, which is a normal phe-
nomenon, because the common network card mode is managed, and it can be changed back after the subsequent
packet capture is completed.

To enable the monitor mode, enter WlanHelper.exe + GUID + mode monitor, for example:

wlanhelper.exe 00971d40-8f3c-426d-bab3-5a38ce789c45 mode monitor

Configure the channel to be monitored, enter WlanHelper.exe + GUID + channel [value], channel
60 for example:

wlanhelper.exe 00971d40-8f3c-426d-bab3-5a38ce789c45 channel 60

Configure Wireshark capture options In the input field, select the corresponding network card interface, do
not check the promiscuous mode, and check the monitor mode.
In the output field, select the path to be saved and the format to be stored.
Click Start or double-click the interface name to capture the wireless network data packets.

Usage of Wireshark Filters

Wireshark has set up two filters: capture filter and display filter.

• Capture filter
Used to set filter conditions before starting capture. After setting the filter conditions, the packet capture tool
will only capture packets that match the conditions; using the capture filter can reduce the captured network
packets, reduce the burden of packet capture software and storage space, and the final packet capture file is
also smaller, which is a necessary skill to improve efficiency;

Espressif Systems 144 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 145 Release master

Submit Document Feedback
Chapter 2. ESP Friends

• Display filter
Used to set filter conditions after capturing data. After setting the filter conditions, only packets that match
the conditions will be displayed on the display page, which helps engineers analyze packets.

Image source

Basic Usage of Capture Filter After opening the Wireshark software, the input box shown in the figure is the
place to enter the capture filter conditions:

Click on the small green tag in the above figure (or through the menu: Capture - Capture Filters) to open
commonly used capture expressions:
Note: The colon : in the capture expression usually means explanatory, without actual meaning.

Syntax of Capture Filter Expressions Wireshark capture filter expressions follow libpcap syntax. Filter expres-
sions consist of one or more primitives. Primitives are usually composed of an id (name or number) and one or more
modifiers.
1. Filter expression = Primitive 1 + Primitive 2 +
2. Primitive = id + Modifier 1 + Modifier 2 +

Espressif Systems 146 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 147 Release master

Submit Document Feedback
Chapter 2. ESP Friends

3. Primitives can be combined with logical connectors and parentheses (), including:
• And: Can be represented by the symbol && or the word and
• Or: Can be represented by the symbol ‖ or the word or
• Not: Can be represented by the symbol ! or the word not
For example, this expression captures only packets that pass through the gateway sup and belong to FTP ports or
data:
gateway snup and (port ftp or ftp-data)

This example captures no arp type packets:

not arp

This example captures only tcp or udp type packets:

tcp || udp

It s worth mentioning that this filter comes with syntax checking, and the green frame at the bottom indicates correct
syntax.

Note: For more usage and examples of capture filters, please refer to the Wireshark official explanation capture
filters wiki and capture filters Gitlab.

Basic Usage of Display Filters After entering the packet capture page, click on the tag in the figure below, or
through the menu Analyze- display filters to open commonly used display filter expressions:

Syntax of Display Filter Expressions Similar to capture filter expressions, display filter expressions can also be
seen as a combination of primitives. The difference is that the primitives of display filter expressions consist of
option + option relationship + option value. For example, in tcp.port == 80, tcp.
port is the option, == is the option relationship, and 80 is the option value. The entire expression means: only
display packets with a tcp port number (including sending and receiving) of 80.

Espressif Systems 148 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 149 Release master

Submit Document Feedback
Chapter 2. ESP Friends

A reminder once again, display filter expressions and capture filter expressions should not be confused. The form of
a capture filter expression is: tcp port80. The three parts of the expression are explained as follows:
• Option: An option can be a protocol (such as tcp, udp, http, etc.), frame, and other objects. Refer to existing
examples or directly input the protocol name to see if there are any prompts.
• Option relationship: Used to define the relationship between the option and the option value. Common option
relationships are as follows:

Table source: Wireshark Official Website

• Option value: The option value can be a number, such as a decimal number 1500, a hexadecimal num-
ber 0x5dc, a binary number 0b10111011100, a boolean value (where 1 represents true, 0 represents
false), a MAC address number (such as eth.dst == ff:ff:ff:ff:ff:ff), an IP address (such
as ip.addr == 192.168.0.1), a string (such as http.request.uri == "https://ww.
wireshark.org/"), a time (such as ntp.xmt ge "2020-07-0412:34:56"), etc.
Multiple expressions can also be connected by logical connectors to form advanced display filter expressions.
Table source: Wireshark Official Website
Here, [ ] represents the substring selector, such as eth.src[0:3] == 00:00:83 indicates that the data
of the 3 bytes starting from offset address 0 is 00:00:83. The in represents the member selector, commonly used
to form a set of option values. For example, tcp.port in {80,441,8081} means to filter the tcp packets
with ports 80, 441, 8081. It is equivalent to tcp.port == 80 ‖ tcp.port == 441 ‖ tcp.port ==
8081.

Note: For more usage methods and examples of capture filters, please refer to the Wireshark official explanation

Espressif Systems 150 Release master

Submit Document Feedback
Chapter 2. ESP Friends

capture filters wiki and capture filters Gitlab.

Packet Analysis

After mastering the packet capture method of Wireshark, you can perform preliminary analysis on the captured
packets. Here are some excellent packet analysis examples:
• Wireshark Packet Capture Analysis of WLAN Connection Process
• Using Wireshark to Analyze the Specific Process of Ping Communication
• Wireshark Packet Capture Analysis of TCP Three-Way Handshake
At the end of this article, we will share some tips on using Wireshark in packet analysis:

Tip 1 In addition to manually entering display filter expressions in the input box, you can also select an option from
the packet capture data, right-click and choose Apply as Filter, then select Selected, Not Selected,
or the more advanced and or logical operations according to your needs. The following figure filters the RTS
packets with subtype as 0x001b, which is equivalent to entering wlan.fc.type_subtype == 0x001b in
the display filter bar.

Tip 2 Use shaders to assist in analyzing various packets. Select an option from the packet capture data, right-click
and choose Apply as Filter with Coloring to color packets that meet specific conditions. The following
figure colors packets with a Receiver address of Espressif_4d:d4:ac (68:b6:b3:4d:d4:ac) as
color 3:
You can manage or reset existing rules in View - Conversation Coloring:

Tip 3 You can drag any field of interest to the list bar for display. For example, the following figure drags the
current channel field to the Packet List Pane, making it easy to view the channel information for each
packet:
Right-click the list bar to manage the settings rules for each column:
You can also choose Edit column to set:

Espressif Systems 151 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 152 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Tip 4 Sometimes we need to debug complex issues and capture multiple logs from different devices. Setting absolute
timestamps can help locate complex issues across devices. Open the column settings bar using the method
in Tip 3, select Absolute date, and you can display the absolute time for each packet:
After setting:

Chinese Reference Documents

• Network Packet Capture Tool Wireshark Download Installation & Detailed Tutorial
• Basic Use of Wireshark - Enabling Packet Capture and Filtering
• Basic Use of Wireshark - Filtering and Viewing Captured Data
• Wi-Fi Packet Capture Tutorial on Windows

Espressif Systems 153 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 154 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 155 Release master

Submit Document Feedback
Chapter 2. ESP Friends

Espressif Systems 156 Release master

Submit Document Feedback