Arduino-ESP32

Arduino-ESP32 是乐鑫维护的 Arduino 核心（core），让你用熟悉的 setup() / loop() 和海量 Arduino 库给 ESP32 写程序。适合创客、初学者，以及想快速出原型的人。

概览

如果还不熟悉 Arduino 的开发板、IDE 和程序结构，请先阅读 Arduino 入门。

它在 GitHub 的仓库是 espressif/arduino-esp32，由乐鑫官方维护，LGPL-2.1 许可。核心 3.x 系列构建在 ESP-IDF 5.x 之上，即 Arduino API 是 IDF 的一层封装；需要时也可以在 Arduino 代码里直接调用 esp_*、xTaskCreate 之类的 IDF 与 FreeRTOS API。

截至 2026-10-14，从发布页看到：

版本	状态	基于的 ESP-IDF
3.3.12	稳定版（标为 Latest）	v5.5.5
4.0.0-RC1	预发布	v6.1
4.0.0-alpha1	预发布	v6.0 系列

4.0 的 alpha 说明提到它与 3.3.9 的核心基本相同，只是换成 IDF v6.0 的库，并缺少 Matter、RainMaker 等部分组件。4.0 正式版的时间表官方尚未公布，现阶段稳定项目请使用 3.3.x。

关键信息

安装

方式一：Arduino IDE 2.x 的板管理器。

打开文件 → 首选项，在「附加开发板管理器网址」中加入： https://espressif.github.io/arduino-esp32/package_esp32_index.json
打开开发板管理器，搜索 esp32，安装 Espressif Systems 发布的 esp32 包（注意不要装成 Arduino 官方的 Arduino ESP32 Boards，那是另一个用于 Nano ESP32 的包）。
在工具 → 开发板里选择对应型号，例如 ESP32S3 Dev Module。

方式二：PlatformIO，见 PlatformIO 一文里关于社区分支的说明。

方式三：把 Arduino 作为 ESP-IDF 组件使用，见下文。

点灯示例

以下代码在 Arduino IDE 里编译并烧录到 ESP32 开发板上运行：

cpp

// 运行于 ESP32 开发板（Arduino-ESP32 核心）
#ifndef LED_BUILTIN
#define LED_BUILTIN 2   // 不同板子的板载灯引脚不同，请按原理图修改
#endif

void setup() {
  Serial.begin(115200);
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(500);
  digitalWrite(LED_BUILTIN, LOW);
  delay(500);
  Serial.println("tick");
}

注意不少新板（如带 RGB 灯珠的 S3 / C6 开发板）板载的是可寻址 LED，需要用 neopixelWrite() 之类的函数，而不是简单的 digitalWrite。

与 Wi-Fi 联网

cpp

#include <WiFi.h>

void setup() {
  Serial.begin(115200);
  WiFi.begin("你的SSID", "你的密码");
  while (WiFi.status() != WL_CONNECTED) { delay(300); Serial.print('.'); }
  Serial.println(WiFi.localIP());
}
void loop() {}

作为 ESP-IDF 组件

当 Arduino 的便利性和 IDF 的完整控制都需要时，可以把 Arduino-ESP32 作为组件放进 IDF 项目：在 main/idf_component.yml 里添加 espressif/arduino-esp32 依赖，然后在 app_main 中调用 initArduino()。这样可以使用 menuconfig 调整 FreeRTOS、分区、蓝牙等，同时继续使用 Arduino 库。具体写法与版本约束请看官方文档的 "Arduino as an ESP-IDF component" 章节。

常见限制

Arduino IDE 默认使用预编译好的 IDF 库，改 sdkconfig 选项不方便；需要深度定制时，要用 IDF 组件方式或 Arduino 官方提供的 lib-builder 工具自行构建。
部分老 Arduino 库依赖 AVR 寄存器，不能在 ESP32 上直接使用。
核心 2.x 升级到 3.x 时，LEDC、I2S、ADC 等 API 有不兼容变化，旧教程的代码需要改。
ESP32-C2、C61 等芯片在官方包中的支持程度不同，请查文档的芯片支持表。

找库

Arduino 库管理器、PlatformIO 注册表和 IDF 组件注册表都有大量 ESP32 可用的库。选库时看最近更新时间和是否声明支持 esp32 架构。

适合谁 / 不适合谁

适合已经会 Arduino 的人、教学场景、以及需要在短时间内验证想法的原型。不适合对内存、功耗和启动时间极度敏感，或需要长期深度定制底层配置的产品固件，这类场景推荐 ESP-IDF。

参考资料

Arduino-ESP32 文档：https://docs.espressif.com/projects/arduino-esp32/en/latest/
Arduino-ESP32 仓库与发布页：https://github.com/espressif/arduino-esp32
安装指南（板管理器）：https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html

Arduino-ESP32 ​

概览 ​

关键信息 ​

安装 ​

点灯示例 ​

与 Wi-Fi 联网 ​

作为 ESP-IDF 组件 ​

常见限制 ​

适合谁 / 不适合谁 ​

参考资料 ​