示例源码仓库：

开发环境：Ubuntu22.04(VirtualBox)

esp开发环境目录：/home/tony/esp/esp-idf

esp开发源码目录：/home/tony/esp/demo-src

一、ESP32常见开发环境

ESP32 是一款功能强大的 Wi-Fi 和蓝牙双模微控制器，常用的开发环境有以下几种，适用于不同的开发需求和编程习惯：

1. Arduino IDE

   • 最流行的入门级开发环境，操作简单，适合初学者。

   • 支持通过 Boards Manager 安装 ESP32 开发板支持包，兼容大量 Arduino 库。

   • 优点：上手快、社区资源丰富、库支持广泛。

   • 缺点：高级功能支持有限，不适合复杂项目管理。

2. ESP-IDF（Espressif IoT Development Framework）

   • 乐鑫官方推出的原生开发框架，基于 FreeRTOS，支持 ESP32 全功能开发。

   • 使用 C/C++ 编程，提供丰富的 API 和工具链，适合开发复杂物联网项目。

   • 优点：功能完整、官方支持及时、适合深度定制和优化。

   • 缺点：学习曲线较陡，需要熟悉 C 语言和 RTOS 概念。

3. PlatformIO

   • 跨平台的开源物联网开发平台，支持多种 IDE（如 VS Code、Atom）。

   • 整合了 ESP-IDF、Arduino 等框架，提供统一的项目管理和调试工具。

   • 优点：支持多框架切换、依赖管理方便、集成调试功能强大。

   • 适合有一定经验的开发者，兼顾易用性和专业性。

4. MicroPython

   • 基于 Python 的轻量级开发环境，适合快速原型开发和脚本式编程。

   • 通过固件烧录后，可直接使用 Python 语法控制 ESP32 硬件。

   • 优点：开发速度快、语法简洁、适合 Python 开发者入门。

   • 缺点：性能略低于原生 C 开发，部分底层功能支持有限。

5. Visual Studio Code + ESP-IDF 插件

   • 结合 VS Code 的强大编辑功能与 ESP-IDF 的开发能力，提供代码补全、调试、工程管理等功能。

   • 官方推荐的 ESP-IDF 开发方式之一，兼顾开发效率和功能完整性。

选择建议：

• 初学者或快速验证想法：优先用 Arduino IDE 或 MicroPython。

• 专业物联网项目开发：推荐 ESP-IDF 或 PlatformIO。

• 习惯 Python 编程：选择 MicroPython。

• 偏好现代化 IDE 体验：尝试 VS Code + ESP-IDF 插件。

二、ESP-IDF开发框架

ESP-IDF（Espressif IoT Development Framework）是乐鑫官方为 ESP32 系列芯片打造的原生开发框架，具有以下核心特性：

1. 完整的功能支持

   提供对 ESP32 全系列芯片（包括 ESP32、ESP32-S2/S3/C3 等）的原生支持，涵盖 Wi-Fi、蓝牙（经典蓝牙 / BLE）、以太网、LoRa 等硬件功能的底层驱动，可直接调用芯片全部硬件资源。

2. 基于 FreeRTOS 实时操作系统

   内置 FreeRTOS 实时内核，支持多任务调度、任务间通信（队列、信号量、事件组等）、内存管理等功能，适合开发需要实时响应的复杂物联网应用。

3. 丰富的中间件与协议栈

   集成多种物联网协议（MQTT、HTTP、CoAP、LwIP 等）、安全组件（TLS/SSL、硬件加密引擎）、文件系统（SPIFFS、FATFS）、OTA 升级等工具，简化复杂功能开发。

4. 强大的调试与诊断工具

   支持 JTAG 硬件调试、日志输出（ESP_LOG）、内存泄漏检测、性能分析（perfmon）等功能，便于定位开发中的问题。

5. 灵活的配置系统（menuconfig）

   通过交互式配置界面（menuconfig）可对芯片参数、外设功能、系统行为等进行精细化配置，无需手动修改底层代码。

6. 跨平台兼容性

   支持 Windows、macOS、Linux 等主流操作系统，提供统一的命令行工具链（idf.py），可实现编译、烧录、监控等全流程操作。

7. 官方持续更新与支持

   乐鑫官方持续维护更新，及时跟进芯片新功能和安全补丁，文档完善（包括 API 手册、开发指南），并提供活跃的社区支持。

8. 可扩展性与定制化

   允许开发者深度定制底层驱动和系统行为，支持静态库 / 动态库开发，适合构建企业级物联网解决方案。

这些特性使 ESP-IDF 成为开发 ESP32 复杂项目的首选框架，尤其适合对性能、功能完整性和系统稳定性有高要求的物联网应用。

三、Linux系统安装ESP-IDF

官方参考文档

https://docs.espressif.com/projects/esp-idf/zh_CN/stable/esp32/get-started/linux-macos-setup.html

在 ESP32 上使用 ESP-IDF，请安装以下软件：

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

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

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

1、安装ESP-IDF步骤

编译 ESP-IDF 需要以下软件包。请根据使用的 Linux 发行版本，选择合适的安装命令。

• Ubuntu 和 Debian:

1、安装各种必要的工具
sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 net-tools

2、新建esp32目录
mkdir esp32
cd esp32

3、拉取gitee工具
git clone https://gitee.com/EspressifSystems/esp-gitee-tools.git

4、执行gitee工具切换镜像脚本
cd esp-gitee-tools
./jihu-mirror.sh set

5、拉取esp-idf源码
cd ..
git clone --recursive https://github.com/espressif/esp-idf.git

6、切换esp-idf版本分支到v5.5
cd esp-idf
git checkout v5.5
git submodule update --init --recursive
如果提示失败或有错误试下这句：../esp-gitee-tools/submodule-update.sh

7、更换pip源
pip config set global.index-url http://mirrors.aliyun.com/pypi/simple
pip config set global.trusted-host mirrors.aliyun.com

8、安装编译工具
../esp-gitee-tools/install.sh

9、设置环境变量并将环境变量放到.bashrc中
source export.sh
echo "source ~/esp32/esp-idf/export.sh" >> ~/.bashrc

esp-idf环境变量设置完成后输出如下信息：

2、安装配置说明

• 下载工具备选方案

ESP-IDF 工具安装器会下载 Github 发布版本中附带的一些工具，如果访问 Github 较为缓慢，可以设置一个环境变量，从而优先选择 Espressif 的下载服务器进行 Github 资源下载。

推荐国内用户使用国内的下载服务器，以加快下载速度。

cd ~/esp/esp-idf
export IDF_GITHUB_ASSETS="dl.espressif.cn/github_assets"
./install.sh

github子模块如不能下载，可使用gitee仓库：

git config --global url."https://gitee.com/esp-submodules".insteadof https://github.com

• 下载串口权限问题：

当你使用 ESP32/ESP8266 等开发板通过 USB 连接到电脑进行编程或调试时，需要对相应的串行端口有读写权限。

在 Linux 系统中，dialout 组通常用于控制对串行端口（如 /dev/ttyUSB*、/dev/ttyACM* 等）的访问权限。

如果linux系统当前的用户名为tony。执行下述命令，作用是将用户 tony 添加到 dialout 用户组中。

 sudo usermod -aG dialout tony 

执行这个命令后，需要注意：

更改不会立即生效，需要用户 tony 重新登录系统才能应用新的组权限

如果是在 VS Code 中操作，可能需要重启 VS Code 才能识别到权限变化。

这个操作通常是 ESP-IDF 开发环境配置中的一步，用于解决开发板连接时的权限问题。

3、idf.py 常用命令

idf.py 常用指令

idf.py help：将输出指令列表和使用说明
idf.py set-target <target>：设置编译目标，<target> 请替换为 esp32s3 等
idf.py menuconfig：运行 menuconfig 终端图像化配置工具，可以选择或修改配置选项，配置结果将保存在 sdkconfig 文件
idf.py build：开始编译代码，编译产生的中间文件和最终的可执行程序，将默认保存在项目 build 目录，编译过程是增量式的，如果仅对一个源文件进行修改，下次编译将只重新编译已修改的文件
idf.py fullclean：删除整个 build 目录下的内容，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的所有文件，请谨慎使用。但项目配置文件同样不会被删除。
idf.py flash：将 build 生成的可执行程序二进制文件烧录进目标 ESP32-C3 设备中。-p <port_name> 和 -b <baud_rate> 选项可分别设置串口的设备名和烧录时的波特率，如果不指定将自动搜索串口，并使用默认波特率
idf.py monitor： 用于显示目标 ESP32-C3 设备的串口输出。同样 -p 选项可用于设置主机端串口的设备名，串口打印期间，可按下组合键 Ctrl-] 退出监视器。

四、使用ESP-IDF开发

1、ESP32开发板

ESP32-S3开发板推荐使用官方的ESP32-S3-DevKitC-1系列或其他兼容官方ESP32-S3开发板。

ESP32-S3-DevKitC-1 是一款入门级开发板，搭载 Wi-Fi + Bluetooth® LE 模组 ESP32-S3-WROOM-1、ESP32-S3-WROOM-1U 或 ESP32-S3-WROOM-2。

https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s3/esp32-s3-devkitc-1/user_guide_v1.1.html#id1

2、编译hello_world程序

从 ESP-IDF 中 examples 目录下的 get-started/hello_world 工程开始。

使用esp-idf开发框架前，首先要保证idf环境变量设置成功。

cd  ~/esp/esp-idf //切换到esp-idf目录
. ./export.sh //设置idf编译环境

esp32工程创建与编译步骤关键命令：

cd ~/esp/hello_world //切换到工程开发目录

idf.py create-project hello_esp32 //自行创建（项目名称），也可复制官方示例

idf.py set-target esp32s3 //设置开板芯片类型

idf.py menuconfig//hello_world程序可使用默认配置

idf.py build //编译

idf.py flash //下载（虚拟机中不能直接指定下载端口，不指定程序自动查找可用串口）

idf.py monitor //监控串口打印,退出方法是 ctrl+]

创建工程

（1）复制官方示例工程

ESP-IDF源码 中 examples 目录下的 get-started/hello_world 工程进行复制。

tony@tony-VirtualBox:~/esp/hello_world$ cp -r ../esp-idf/examples/get-started/hello_world/ ./

hello_world 示例工程的组成和代码功能：

项目结构解析

hello_world/
├── CMakeLists.txt       # 项目根目录的CMake配置文件，定义项目基本信息和组件依赖
├── main/                # 主程序目录
│   ├── CMakeLists.txt   # 主程序的CMake配置，指定编译源文件
│   └── hello_world_main.c  # 主程序源代码
├── pytest_hello_world.py  # 自动化测试脚本
├── README.md            # 项目说明文档
└── sdkconfig.ci         # CI构建时使用的配置文件

这是 ESP-IDF 项目的标准结构，通过 CMake 进行项目管理，符合 ESP-IDF 的构建规范。

代码功能解析（hello_world_main.c）

这段代码是 ESP32 的经典入门示例，主要功能包括：

1. 打印基本信息：

   • 输出 "Hello world!" 字符串

   • 获取并打印芯片信息（型号、CPU 核心数、支持的功能如 WiFi/BT/BLE 等）

   • 显示芯片硅版本号和闪存大小信息

   • 打印系统最小可用堆内存大小

2. 延时重启功能：

   • 使用 FreeRTOS 的 vTaskDelay() 函数实现 1 秒间隔的倒计时（10 秒）

   • 倒计时结束后调用 esp_restart() 重启设备

3. 关键 API 说明：

   • app_main()：ESP-IDF 程序入口函数（类似 C 语言的 main 函数）

   • esp_chip_info()：获取芯片硬件信息

   • esp_flash_get_size()：获取闪存大小

   • esp_get_minimum_free_heap_size()：获取系统运行过程中最小可用堆内存

   • vTaskDelay()：FreeRTOS 的任务延时函数

   • esp_restart()：ESP32 系统重启函数

这个示例展示了 ESP-IDF 开发的基本框架，包括头文件引用、系统 API 调用、FreeRTOS 任务管理等核心概念，非常适合初学者理解 ESP32 开发的基础流程。

#include <stdio.h>
#include <inttypes.h>
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"

void app_main(void)
{
    printf("Hello world!\n");
    /* Print chip information */
    esp_chip_info_t chip_info;
    uint32_t flash_size;
    esp_chip_info(&chip_info);

    printf("This is %s chip with %d CPU core(s), %s%s%s%s, ",
           CONFIG_IDF_TARGET,
           chip_info.cores,
           (chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
           (chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
           (chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
           (chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread)" : "");

    unsigned major_rev = chip_info.revision / 100;
    unsigned minor_rev = chip_info.revision % 100;
    printf("silicon revision v%d.%d, ", major_rev, minor_rev);
    if(esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
        printf("Get flash size failed");
        return;
    }

    printf("%" PRIu32 "MB %s flash\n", flash_size / (uint32_t)(1024 * 1024),
           (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");

    printf("Minimum free heap size: %" PRIu32 " bytes\n", esp_get_minimum_free_heap_size());

    for (int i = 10; i >= 0; i--) {
        printf("Restarting in %d seconds...\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }
    printf("Restarting now.\n");
    fflush(stdout);
    esp_restart();

}

（2）自行创建工程

cd ~/esp/hello_world //切换到工程开发目录

idf.py create-project hello_esp32 //自行创建（项目名称）

创建工程输出：

tony@tony-VirtualBox:~/esp/hello_world$ idf.py create-project hello_esp32

Executing action: create-project

The project was created in /home/tony/esp/hello_world/hello_esp32

工程中新创建的代码文件无内容，需自行添加内容：

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"

static const char* TAG = "main";

void app_main(void)
{
    while(1)
    {
        ESP_LOGI(TAG,"Hello world!");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

上述程序，实现了每隔 1 秒打印一次 "Hello world!" 的功能。分析一下这段代码的关键部分：

头文件引入：

• stdio.h：标准输入输出库

• freertos/FreeRTOS.h 和 freertos/task.h：FreeRTOS 实时操作系统相关头文件，用于任务管理和延时

• esp_log.h：ESP-IDF 提供的日志功能库

日志标签定义：

static const char* TAG = "main";

定义了日志输出时使用的标签，方便在日志中区分不同模块的输出。

程序入口函数：

void app_main(void)

这是 ESP-IDF 应用程序的入口函数，相当于标准 C 程序的 main() 函数。

主循环：

while(1)
{
    ESP_LOGI(TAG,"Hello world!");
    vTaskDelay(pdMS_TO_TICKS(1000));
}

• ESP_LOGI()：ESP-IDF 提供的信息级别日志输出函数，第一个参数是标签，第二个参数是日志内容

• vTaskDelay(pdMS_TO_TICKS(1000))：FreeRTOS 的任务延时函数，pdMS_TO_TICKS(1000) 将 1000 毫秒转换为 FreeRTOS 的时钟节拍数，实现 1 秒的延时

配置工程

idf.py set-target esp32s3 //设置开板芯片类型

idf.py menuconfig//hello_world程序可使用默认配置

编译工程

idf.py build //编译

linux系统根据机器性能配置编译工程需要1-2分钟。

连接设备

虚拟机USB设置中需选中USB转串口设备，如下图中选中的第一个设备。

查看当前系统中的tty设备：ttyACM0是连接的esp32设备，可以断开设备，查看设备文件是否消失。

下载镜像

idf.py flash //下载（虚拟机中不能直接指定下载端口，不指定程序自动查找可用串口）

如果下载提示权限问题，需修改串口权限。

chmod 666 /dev/ttyACM0  //修改串口权限

监视输出

idf.py flash //下载
idf.py monitor //监控串口打印,退出方法是 ctrl+]

官方示例程序输出：

自行创建程序输出：