Espressif ESP32-S2

To Next Page

To Previous Page

Chapter 11

Switch Between Languages

The ESP-IDF Programming Guide is now available in two languages. Please refer to the English version if there is

any discrepancy.

• English

• Chinese

You can easily change from one language to another by clicking the language link you can ﬁnd at the top of every

document that has a translation.

• genindex

1601

Main Page

Table of Contents2
Get Started14
Introduction14
What You Need14
Development Board Overviews15
ESP32-S2-Saola-115
ESP32-S2-Devkitm-1(U)20
ESP32-S2-Devkitc-126
ESP32-S2-Kaluga-1 Kit V1.331
Installation Step by Step65
Setting up Development Environment65
Creating Your First Project65
Step 1. Install Prerequisites65
Standard Setup of Toolchain for Windows65
Standard Setup of Toolchain for Linux70
Standard Setup of Toolchain for Mac os71
Step 2. Get ESP-IDF73
Linux and Macos73
Windows73
Step 3. Set up the Tools73
Alternative File Downloads74
Customizing the Tools Installation Path74
Step 4. Set up the Environment Variables74
Windows75
Linux and Macos75
Step 5. Start a Project75
Step 6. Connect Your Device76
Step 7. Configure76
Linux and Macos76
Windows76
Step 8. Build the Project77
Step 9. Flash Onto the Device77
Encountered Issues While Flashing78
Normal Operation78
Step 10. Monitor79
Updating ESP-IDF80
Related Documents80
Establish Serial Connection with ESP32-S280
Build and Flash with Eclipse IDE86
Getting Started with VS Code IDE86
IDF Monitor87
Customized Setup of Toolchain91
API Reference98
Networking Apis98
Wi-Fi98
ESP_OK: Succeed104
ESP_ERR_WIFI_NOT_INIT: Wifi Is Not Initialized by Esp_Wifi_Init104
ESP_ERR_WIFI_NOT_INIT: Wifi Is Not Initialized by Esp_Wifi_Init107
ESP_ERR_WIFI_NOT_STARTED: Wifi Is Not Started by Esp_Wifi_Start110
Esp_Err_T110
ESP_OK: Succeed110
ESP_ERR_WIFI_NOT_INIT: Wifi was Not Initialized by Esp_Wifi_Init110
ESP_ERR_WIFI_NOT_INIT: Wifi Is Not Initialized by Esp_Wifi_Init110
ESP_ERR_INVALID_ARG: Invalid Argument112
Ethernet180
Thread203
IP Network Layer208
Application Layer225
Peripherals API225
Analog to Digital Converter (ADC)225
Digital to Analog Converter (DAC)246
General Purpose Timer250
Gpio & Rtc Gpio260
Dedicated GPIO278
Hash-Based Message Authentication Code (HMAC)283
Digital Signature (DS)287
Inter-Integrated Circuit (I2C)291
Inter-IC Sound (I2S)307
Lcd317
LED Control (LEDC)326
Pulse Counter (PCNT)340
Remote Control (RMT)349
SD SPI Host Driver368
Sigma-Delta Modulation372
SPI Master Driver375
SPI Slave Driver393
SPI Slave Half Duplex399
Temperature Sensor405
Touch Sensor408
Touch Element429
Two-Wire Automotive Interface (TWAI)453
Universal Asynchronous Receiver/Transmitter (UART)469
USB Device Driver491
USB Host498
Application Protocols518
ASIO Port518
Esp-Mqtt519
Esp-Tls530
Openssl-Apis540
ESP HTTP Client568
HTTP Server582
HTTPS Server604
ICMP Echo606
ESP Local Control611
Mdns Service619
ESP-Modbus632
ESP Websocket Client653
ESP Serial Slave Link660
ESP X509 Certificate Bundle673
IP Network Layer675
Provisioning API675
Protocol Communication675
Unified Provisioning685
Wi-Fi Provisioning689
Storage API706
FAT Filesystem Support706
Manufacturing Utility711
Non-Volatile Storage Library716
NVS Partition Generator Utility736
SD/SDIO/MMC Driver742
SPI Flash API750
SPIFFS Filesystem775
Virtual Filesystem Component779
Wear Levelling API792
System API796
App Image Format796
Application Level Tracing801
The Async Memcpy API805
Console808
Efuse Manager816
Error Codes and Helper Functions836
Esp Https Ota837
POSIX Threads Support841
Event Loop Library845
Freertos861
Freertos Additions966
Heap Memory Allocation983
Heap Memory Debugging994
High Resolution Timer1004
Call Function with External Stack1009
Interrupt Allocation1011
Logging Library1016
Miscellaneous System Apis1022
Over the Air Updates (OTA)1027
Performance Monitor1039
Power Management1041
Random Number Generation1046
Sleep Modes1049
Watchdogs1058
System Time1061
Internal and Unstable Apis1065
API Conventions1066
Error Handling1066
Configuration Structures1066
Private Apis1067
Components in Example Projects1067
API Stability1068
Project Configuration1069
Introduction1069
Project Configuration Menu1069
Using Sdkconfig.defaults1069
Kconfig Formatting Rules1069
Backward Compatibility of Kconfig Options1070
Configuration Options Reference1070
Customisations1253
Error Codes Reference1253
ESP32-S2 Hardware Reference1260
Chip Series Comparison1260
Related Documents1262
API Guides1264
Application Level Tracing Library1264
Overview1264
Modes of Operation1264
Configuration Options and Dependencies1265
How to Use this Library1266
Application Startup Flow1274
First Stage Bootloader1274
Second Stage Bootloader1275
Application Startup1275
Bootloader1277
Bootloader Compatibility1277
Log Level1277
Factory Reset1277
Boot from Test Firmware1278
Rollback1278
Watchdog1278
Bootloader Size1279
Fast Boot from Deep Sleep1279
Custom Bootloader1279
Build System1280
Overview1280
Using the Build System1281
Example Project1284
Project Cmakelists File1285
Component Cmakelists Files1286
Component Configuration1289
Preprocessor Definitions1289
Component Requirements1289
Overriding Parts of the Project1293
Configuration-Only Components1293
Debugging Cmake1294
Example Component Cmakelists1294
Custom Sdkconfig Defaults1298
Flash Arguments1298
Building the Bootloader1299
Selecting the Target1299
Writing Pure Cmake Components1300
Using Third-Party Cmake Projects with Components1300
Using Prebuilt Libraries with Components1301
Using ESP-IDF in Custom Cmake Projects1301
ESP-IDF Cmake Build System API1302
File Globbing & Incremental Builds1305
Build System Metadata1306
Build System Internals1306
Migrating from ESP-IDF GNU Make System1308
Deep Sleep Wake Stubs1310
Rules for Wake Stubs1310
Implementing a Stub1310
Loading Code into RTC Memory1310
Loading Data into RTC Memory1311
CRC Check for Wake Stubs1312
Device Firmware Upgrade through USB1312
Building the DFU Image1312
Flashing the Chip with the DFU Image1312
Error Handling1314
Overview1314
Error Codes1314
Converting Error Codes to Error Messages1314
ESP_ERROR_CHECK Macro1315
ESP_ERROR_CHECK_WITHOUT_ABORT Macro1315
ESP_RETURN_ON_ERROR Macro1315
ESP_GOTO_ON_ERROR Macro1315
ESP_RETURN_ON_FALSE Macro1315
ESP_GOTO_ON_FALSE Macro1316
CHECK MACROS Examples1316
Error Handling Patterns1316
C++ Exceptions1317
Esp-Wifi-Mesh1317
Overview1317
Introduction1318
ESP-WIFI-MESH Concepts1319
Building a Network1324
Managing a Network1329
Data Transmission1332
Channel Switching1334
Performance1337
Further Notes1338
Core Dump1338
Overview1338
Configurations1338
Save Core Dump to Flash1339
Print Core Dump to UART1339
ROM Functions in Backtraces1339
Dumping Variables on Demand1340
Running Espcoredump.py1340
Event Handling1341
Wi-Fi, Ethernet, and IP Events1341
Mesh Events1342
Bluetooth Events1343
Support for External RAM1343
Introduction1343
Hardware1343
Configuring External RAM1344
Restrictions1345
Failure to Initialize1345
Encryption1345
Fatal Errors1345
Overview1346
Panic Handler1346
Register Dump and Backtrace1348
GDB Stub1349
Guru Meditation Errors1349
Other Fatal Errors1351
Flash Encryption1353
Introduction1353
Relevant Efuses1354
Flash Encryption Process1355
Flash Encryption Configuration1355
Possible Failures1362
ESP32-S2 Flash Encryption Status1363
Reading and Writing Data in Encrypted Flash1364
Updating Encrypted Flash1365
Disabling Flash Encryption1365
Key Points about Flash Encryption1365
Limitations of Flash Encryption1366
Flash Encryption and Secure Boot1366
Advanced Features1366
External RAM1368
Technical Details1368
ESP-IDF Freertos (SMP)1368
Overview1369
Symmetric Multiprocessing1369
Tasks1370
SMP Scheduler1371
Critical Sections1375
Misc1376
Hardware Abstraction1377
Architecture1377
LL (Low Level) Layer1378
HAL (Hardware Abstraction Layer)1379
High-Level Interrupts1380
Interrupt Levels1380
Notes1380
JTAG Debugging1381
Introduction1381
How It Works1382
Selecting JTAG Adapter1382
Setup of Openocd1383
Configuring ESP32-S2 Target1383
Launching Debugger1388
Debugging Examples1389
Building Openocd from Sources1389
Tips and Quirks1393
Related Documents1397
Linker Script Generation1422
Overview1422
Quick Start1422
Linker Script Generation Internals1425
Memory Types1432
DRAM (Data RAM)1432
IRAM (Instruction RAM)1432
IROM (Code Executed from Flash)1433
RTC Fast Memory1433
DROM (Data Stored in Flash)1434
RTC Slow Memory1434
DMA Capable Requirement1434
DMA Buffer in the Stack1435
Lwip1435
Supported Apis1435
BSD Sockets API1435
Netconn API1439
Lwip Freertos Task1439
Ipv6 Support1440
Esp-Lwip Custom Modifications1440
Performance Optimization1441
Openthread1443
Mode of the Openthread Stack1443
How to Write an Openthread Application1444
The Openthread Border Router1444
Partition Tables1445
Overview1445
Built-In Partition Tables1445
Creating Custom Tables1445
Generating Binary Partition Table1448
Partition Size Checks1448
Flashing the Partition Table1448
Partition Tool (Parttool.py)1449
Performance1450
How to Optimize Performance1450
Guides1450
RF Calibration1466
Partial Calibration1466
Full Calibration1466
No Calibration1466
PHY Initialization Data1466
Secure Boot V21467
Background1467
Advantages1467
Secure Boot V2 Process1467
Signature Block Format1468
Verifying a Signature Block1468
Verifying an Image1469
Bootloader Size1469
Efuse Usage1469
How to Enable Secure Boot V21469
Restrictions after Secure Boot Is Enabled1470
Generating Secure Boot Signing Key1470
Remote Signing of Images1471
Secure Boot Best Practices1471
Key Management1471
Multiple Keys1471
Key Revocation1472
Technical Details1472
Secure Boot & Flash Encryption1473
Signed App Verification Without Hardware Secure Boot1473
Advanced Features1473
Thread Local Storage1474
Overview1474
Freertos Native API1474
Pthread API1474
C11 Standard1474
Tools1475
Downloadable Tools1475
IDF Docker Image1483
IDF Windows Installer1485
IDF Component Manager1486
ULP Coprocessor Programming1487
ESP32-S2 ULP Coprocessor Instruction Set1487
Programming ULP Coprocessor Using C Macros (Legacy)1502
Installing the Toolchain1507
Compiling the ULP Code1507
Accessing the ULP Program Variables1508
Starting the ULP Program1509
ESP32-S2 ULP Program Flow1510
ULP-RISC-V Coprocessor Programming1511
Installing the ULP-RISC-V Toolchain1511
Compiling the ULP-RISC-V Code1511
Accessing the ULP-RISC-V Program Variables1512
Starting the ULP-RISC-V Program1512
ULP-RISC-V Program Flow1513
Unit Testing in ESP32-S21513
Normal Test Cases1514
Multi-Device Test Cases1514
Multi-Stage Test Cases1515
Tests for Different Targets1516
Building Unit Test App1517
Running Unit Tests1517
Timing Code with Cache Compensated Timer1518
Mocks1519
Unit Testing on Linux1521
Embedded Software Tests1521
IDF Unit Tests on Linux Host1521
USB OTG Console1522
Hardware Requirements1522
Software Configuration1522
Uploading the Application1523
Limitations1523
Wi-Fi Driver1524
ESP32-S2 Wi-Fi Feature List1524
How to Write a Wi-Fi Application1524
ESP32-S2 Wi-Fi API Error Code1525
ESP32-S2 Wi-Fi API Parameter Initialization1526
ESP32-S2 Wi-Fi Programming Model1526
ESP32-S2 Wi-Fi Event Description1526
ESP32-S2 Wi-Fi Station General Scenario1529
ESP32-S2 Wi-Fi AP General Scenario1532
ESP32-S2 Wi-Fi Scan1532
ESP32-S2 Wi-Fi Station Connecting Scenario1539
ESP32-S2 Wi-Fi Station Connecting When Multiple Aps Are Found1543
Wi-Fi Reconnect1543
Wi-Fi Beacon Timeout1543
ESP32-S2 Wi-Fi Configuration1543
Wi-Fi Easy Connect™ (DPP)1549
Wireless Network Management1549
Radio Resource Measurement1549
Wi-Fi Location1550
ESP32-S2 Wi-Fi Power-Saving Mode1550
ESP32-S2 Wi-Fi Throughput1551
Wi-Fi 80211 Packet Send1551
Wi-Fi Sniffer Mode1554
Wi-Fi Multiple Antennas1554
Wi-Fi Channel State Information1555
Wi-Fi Channel State Information Configure1556
Wi-Fi HT20/401557
Wi-Fi Qos1557
Wi-Fi AMSDU1558
Wi-Fi Fragment1558
WPS Enrollee1558
Wi-Fi Buffer Usage1558
How to Improve Wi-Fi Performance1559
Wi-Fi Menuconfig1562
Troubleshooting1565
Wi-Fi Security1569
ESP32-S2 Wi-Fi Security Features1571
Protected Management Frames (PMF)1571
WPA3-Personal1572
Libraries and Frameworks1574
Cloud Frameworks1574
ESP Rainmaker1574
AWS Iot1574
Azure Iot1574
Google Iot Core1574
Aliyun Iot1574
Joylink Iot1574
Tencent Iot1575
Tencentyun Iot1575
Baidu Iot1575
Espressif's Frameworks1575
Espressif Audio Development Framework1575
Esp-Csi1575
Espressif DSP Library1575
ESP-WIFI-MESH Development Framework1576
Esp-Who1576
ESP Rainmaker1576
ESP-Iot-Solution1576
Contributions Guide1578
How to Contribute1578
Before Contributing1578
Pull Request Process1578
Legal Part1579
Related Documents1579
Espressif Iot Development Framework Style Guide1579
Install Pre-Commit Hook for ESP-IDF Project1586
Documenting Code1587
Creating Examples1592
API Documentation Template1593
Contributor Agreement1595
ESP-IDF Versions1598
Releases1598
Which Version Should I Start with1598
Versioning Scheme1598
Support Periods1599
Checking the Current Version1600
Git Workflow1601
Updating ESP-IDF1601
Updating to Stable Release1602
Updating to a Pre-Release Version1602
Updating to Master Branch1602
Updating to a Release Branch1603
Resources1604
Platformio1604
What Is Platformio1604
Installation1604
Configuration1605
Tutorials1605
Project Examples1605
Next Steps1605
Useful Links1605
Copyrights and Licenses1606
Software Copyrights1606
Firmware Components1606
Build Tools1607
Documentation1607
ROM Source Code Copyrights1607
Xtensa Libhal mit License1608
Tinybasic Plus mit License1608
Tjpgdec License1608

Espressif ESP32-S2 - Page 1612

Table of Contents