这里是乐鑫 IoT 开发框架 (esp-idf) 的文档中心。ESP-IDF 是 ESP32 和 ESP32-S2 系列芯片的官方开发框架。

本文档仅包含针对 ESP32 芯片的 ESP-IDF 使用。如需了解其他芯片，请点击页面左下方的 “Switch Version”。

ESP-IDF 是 ESP32 芯片的官方开发框架。

快速入门

[English]

本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。

注解

这是ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 Stable version 的文档，以及其他版本的文档 ESP-IDF 版本简介 供参考。

概述

ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用场景和不同功耗需求。

乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。

准备工作

硬件：

• 一款 ESP32 开发板

• USB 数据线 (A 转 Micro-B)

• PC（Windows）

软件：

• 设置 工具链，用于编译 ESP32 代码；

• 编译工具 —— CMake 和 Ninja 编译工具，用于编译 ESP32 应用程序；

• 获取 ESP-IDF 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 工具链 的脚本；

• 安装 C 语言编程（工程）的 文本编辑器，例如 Eclipse。

ESP32 应用程序开发

开发板简介

请点击下方连接，了解有关具体开发板的详细信息。

• ESP32-DevKitC
• ESP-WROVER-KIT
• ESP32-PICO-KIT
• ESP32-Ethernet-Kit
• ESP32-DevKit-S(-R)

详细安装步骤

请根据下方详细步骤，完成安装过程。

设置开发环境

• 第一步：安装准备（Windows）

• 第二步：获取 ESP-IDF

• 第三步：设置工具

• 第四步：设置环境变量

创建您的第一个工程

• 第五步：开始创建工程

• 第六步：连接设备

• 第七步：配置

• 第八步：编译工程

• 第九步：烧录到设备

• 第十步：监视器

安装准备

在正式开始创建工程前，请先完成工具的安装，具体步骤见下：

Windows 平台工具链的标准设置

[English]

注解

目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 传统 GNU Make 构建系统 中的介绍进行操作。

概述

ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。

在本入门指南中，我们通过 命令提示符 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 Eclipse 或其他支持 CMake 的图形化工具 IDE。

注解

较早 ESP-IDF 版本使用 传统 GNU Make 编译系统 和 MSYS2 Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。

使用命令提示符

等待这个命令执行结束，再执行下一条命令，不要开多个终端同时执行！

开始创建工程

现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 examples 目录下的 get-started/hello_world 工程开始。

将 get-started/hello_world 复制至您本地的 ~/esp 目录下

Windows 操作系统

cd %userprofile%\esp\hello_world
idf.py menuconfig

如果有这个错误

则根据提示来

如果有这个错误：

也是根据提示来

总之，就是出什么问题都会有提示，根据提示，一步一步操作就OK，接下来

Windows 操作系统

Windows 下命令提示符窗口使用 ESP-IDF，请使用下方代码：

进入esp\esp-idf目录执行export.bat添加环境变量，再开始创建工程，拷贝hello目录只esp目录，执行

idf.py menuconfig

如果之前的步骤都正确，则会显示下面的菜单

进入这个界面：

工程配置 — 主窗口

menuconfig 工具的常见操作见下。

• 上下箭头：移动

• 回车：进入子菜单

• ESC 键：返回上级菜单或退出

• 英文问号：调出帮助菜单（退出帮助菜单，请按回车键）。

• 空格``或 ``Y 键：选择 [*] 配置选项；N 键：禁用 [*] 配置选项

• 英文问号 （查询配置选项）：调出有关该选项的帮助菜单

• / 键：寻找配置工程

注意

如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 menuconfig 中使能单核模式（CONFIG_FREERTOS_UNICORE）。

SDK tool configuration	配置SDK 开发工具链的信息，一般未编译自己工具链时不用修改
Bootloader config	配置BootLoader 启动时的日志打印级别
Serial flasher config	配置串口下载时使用的端口、波特率、Flash 模式、Flash 频率、是否压缩上传等
Partition Table	配置分区信息，可选择默认分区配置或自定义分区配置
Component config	组件配置 包含ESP32的特殊配置、WiFi配置、BLE配置、FreeRTOS配置、LWIP配置、日志配置、SPI配置、用户程序自定义配置等

SDK tool configuration

Compiler toolchain path/prefix	xtensa-esp32-elf-	该配置项一般无需配置，除非自己编译交叉编译链时，且使用了跟 xtensa-esp32-elf- 不同的名字。
Python 2 interpreter	python	python 2 解释器的名称，一般默认都是python。

Bootloader config

Bootloader log verbosity

Warning

这里可以配置BootLoader的日志打印级别，级别越高，打印出的日志信息量越多,可以根据自己的需要选择合适的级别。 级别排序为：No output < Error < Warning < Info < Debug < Verbose 。

Serial flasher config

项目	默认值	备注
Default serial port	/dev/ttyUSB0	windows 下的 COM1 对应 cygwin 下的/dev/ttyS0 ，COM2 对应 ttyS1，以此类推。
Default baud rate	921600	您可以选择 230400/921600/2M/Other baud rate ,如果您选择了 Other baud rate，则需要在下面手动输入您认为可用的下载速率，ESP32 目前最大的下载速率为 1152000.
Use compressed upload	是	是否选择压缩上传，可以提升固件下载时的速度。
Flash SPI mode	DIO	SPI运行模式，推荐DIO方式
Flash SPI speed	40MHZ	SPI 速率，需要根据自己的 Flash 型号进行配置，部分型号的Flash不支持过高的速率。

Partition Table

项目	默认值	可选值	备注
Partition Table	Single factory app, no OTA	Single factory app, no OTA Factory app, two OTA definitions Custom partition table CSV	默认分区文件地址为:components/partition_table 一般使用Single factory app, no OTA 。 自定义分区可以参考下面的示例

如何修改自定义分区表

下面以 NodeMCU 的 spiffs 分区为例：

1 勾选 Custom partition table CSV

2 在 Custom partition table CSV 中输入自定义的分区信息文件名：partitions-2MB.csv

3 在工程的根目录下建立 partitions-2MB.csv文件（参考 components/platform/partitions-2MB.csv）

# Espressif ESP32 Partition Table
# Name	Type	SubType	Offset	Size
factory	app	factory	0x10000	1M
rfdata	data	rf	0x110000	256K
wifidata	data	wifi	0x150000	256K
# 0xC2 ⇒ NodeMCU 0x0 ⇒ Spiffs
spiffs	0xC2	0x0		448K

4 编译下载。

具体的分区使用详情可以参考 https://github.com/espressif/esp-idf/blob/master/docs/partition-tables.rst

编译工程

请使用以下命令，编译烧录工程：:

idf.py build

编译好了如下

如果一切正常，编译完成后将生成 .bin 文件。

烧录到设备

请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板：

idf.py -p PORT [-b BAUD] flash

请将 PORT 替换为 ESP32 开发板的串口名称

您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 460800。

更多有关 idf.py 参数的详情，请见 idf.py：

https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/build-system.html#idf-py

输入：

idf.py -p COM11 -b 460800 flash

如果一切顺利，烧录完成后，开发板将会复位，应用程序 “hello_world” 开始运行。

监视器

您可以使用 idf.py -p PORT monitor 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。

运行该命令后，IDF 监视器 应用程序将启动：:

$ idf.py -p /dev/ttyUSB0 monitor
Running idf_monitor in directory [...]/esp/hello_world/build
Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun  8 2016 00:22:57rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun  8 2016 00:22:57
...

此时，您就可以在启动日志和诊断日志之后，看到打印的 “Hello world!” 了。

...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...

您可使用快捷键 Ctrl+]，退出 IDF 监视器。

如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。

此时，您可以：

1. 退出监视器。

2. 打开 menuconfig。

3. 进入 Component config –> ESP32-specific –> Main XTAL frequency 进行配置，将 CONFIG_ESP32_XTAL_FREQ_SEL 设置为 26 MHz。

4. 然后，请重新 编译和烧录 应用程序。

注解

您也可以运行以下命令，一次性执行构建、烧录和监视过程：

idf.py -p PORT flash monitor

更新 ESP-IDF

根据https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html 教程更新

 

乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 esp-idf 文件夹，然后按照 第二步：获取 ESP-IDF 中的指示，重新完成克隆。

此外，您可以仅更新变更部分。具体方式，请前往 更新 章节查看。

注意，更新完成后，请执行 install.sh （Windows 系统中为 install.bat）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 第三步：设置工具。

一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 第四步：设置环境变量。