{
    "format": "skill/v1",
    "skill_id": "ericsun787-esp32-arduino-development-skill-md",
    "name": "esp32-arduino-development",
    "version": "1.0.0",
    "description": "ESP32 Arduino框架完整开发指南。涵盖Arduino CLI工具链配置、ESP32项目编译、\n固件烧录、串口调试等全流程。适用于ESP32-WROOM-32等常见开发板，解决环境配置、\n库依赖管理、上传失败、串口通信等常见问题。支持Windows/Linux/macOS跨平台开发。",
    "category": [
        "开发编程"
    ],
    "trigger_words": [],
    "tags": [],
    "source": "DeepseekModel",
    "source_url": "https://deepseekmodel.com/skill?id=ericsun787-esp32-arduino-development-skill-md",
    "exported_at": "2026-09-16T23:27:10+08:00",
    "system_prompt": "name esp32-arduino-development description ESP32 Arduino框架完整开发指南。涵盖Arduino CLI工具链配置、ESP32项目编译、 固件烧录、串口调试等全流程。适用于ESP32-WROOM-32等常见开发板，解决环境配置、 库依赖管理、上传失败、串口通信等常见问题。支持Windows/Linux/macOS跨平台开发。 author EricSun version 1.0.0 date 2026-02-27T00:00:00.000Z ESP32 Arduino 开发完整指南 问题 ESP32开发环境配置复杂，涉及工具链安装、板级支持包配置、库依赖管理、烧录端口选择等多个环节，容易出现编译失败、上传超时、串口无法识别等问题。 上下文 / 触发条件 新建ESP32项目需要搭建开发环境 编译时出现\" Board not found\"或库缺失错误 上传固件时提示\"Failed to connect to ESP32\" 串口无法识别或通信失败 需要批量编译和烧录多个ESP32设备 解决方案 1. 工具链安装与配置 1.1 安装 Arduino CLI Windows (PowerShell): # 下载最新版 Invoke-WebRequest -Uri \"https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip\" -OutFile \"arduino-cli.zip\" Expand-Archive -Path \"arduino-cli.zip\" -DestinationPath \"$env:USERPROFILE\\bin\" [Environment]::SetEnvironmentVariable(\"Path\", $env:Path + \";$env:USERPROFILE\\bin\", \"User\") Linux/macOS: curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh sudo mv bin/arduino-cli /usr/local/bin/ 1.2 初始化配置 # 创建默认配置文件 arduino-cli config init # 查看当前配置 arduino-cli config dump # 添加ESP32板级支持包地址 arduino-cli config add board_manager.additional_urls https://dl.espressif.com/dl/package_esp32_index.json 1.3 安装ESP32核心 # 更新板级支持包索引 arduino-cli core update-index # 安装ESP32核心 (包含所有ESP32系列) arduino-cli core install esp32:esp32 # 验证安装 arduino-cli core list 2. 项目结构 2.1 标准Arduino项目结构 project-name/ ├── project-name.ino # 主程序文件（必须与目录同名） ├── config.h # 配置文件（可选） ├── src/ # 额外源文件目录 │ ├── utils.cpp │ └── utils.h ├── lib/ # 本地库目录（可选） │ └── MyLibrary/ │ ├── MyLibrary.h │ └── MyLibrary.cpp └── sketch.yaml # 项目配置文件（Arduino CLI 1.0+） 2.2 sketch.yaml 项目配置 # sketch.yaml - 放在项目根目录 profiles: default: fqbn: esp32:esp32:esp32 # 完全限定板子名称 platforms: - platform: esp32:esp32 (2.0.14) libraries: - ArduinoJson (6.21.3) - PubSubClient (2.8) 3. 编译流程 3.1 基本编译命令 # 进入项目目录 cd project-name/ # 编译（自动检测当前目录的.ino文件） arduino-cli compile --fqbn esp32:esp32:esp32 # 详细输出（调试用） arduino-cli compile --fqbn esp32:esp32:esp32 --verbose # 指定输出目录 arduino-cli compile --fqbn esp32:esp32:esp32 --output-dir ./build 3.2 常见FQBN（完全限定板子名称） 开发板型号 FQBN ESP32 Dev Module esp32:esp32:esp32 ESP32-S2 esp32:esp32:esp32s2 ESP32-S3 esp32:esp32:esp32s3 ESP32-C3 esp32:esp32:esp32c3 ESP32-C6 esp32:esp32:esp32c6 NodeMCU-32S esp32:esp32:nodemcu-32s ESP32-CAM esp32:esp32:esp32cam 3.3 编译选项 # 指定分区表（大程序需要） arduino-cli compile --fqbn esp32:esp32:esp32:PartitionScheme=huge_app # 指定Flash大小 arduino-cli compile --fqbn esp32:esp32:esp32:FlashSize=4MB # 指定CPU频率 arduino-cli compile --fqbn esp32:esp32:esp32:CPUFreq=240 # 调试级别 arduino-cli compile --fqbn esp32:esp32:esp32:DebugLevel=debug 4. 烧录固件 4.1 识别串口 # 列出所有可用串口 arduino-cli board list # 示例输出： # Port Protocol Type Board Name FQBN Core # /dev/ttyUSB0 (Linux) serial Serial Port (USB) ESP32 Dev... esp32:esp32:... esp32:esp32 # COM11 (Windows) serial Serial Port (USB) ESP32 Dev... esp32:esp32:... esp32:esp32 4.2 上传命令 # 基本上传（指定端口和FQBN） arduino-cli upload --fqbn esp32:esp32:esp32 -p COM11 # 或 /dev/ttyUSB0 (Linux) arduino-cli upload --fqbn esp32:esp32:esp32 -p /dev/ttyUSB0 # 上传前自动编译 arduino-cli upload --fqbn esp32:esp32:esp32 -p COM11 --verify 4.3 进入下载模式 ESP32上传需要进入下载模式，不同板子操作不同： 带自动下载电路的板子（如NodeMCU-32S）: 直接上传，无需手动操作 需要手动进入下载模式的板子: 按住 BOOT 按钮 按一下 EN (Reset) 按钮 松开 BOOT 按钮 立即执行上传命令 Windows一键上传脚本: # upload.ps1 $port = \"COM11\" $fqbn = \"esp32:esp32:esp32\" Write-Host \"Uploading to $port...\" arduino-cli upload --fqbn $fqbn -p $port --verify if ($LASTEXITCODE -eq 0) { Write-Host \"Upload successful!\" -ForegroundColor Green } else { Write-Host \"Upload failed! Try manually entering download mode.\" -ForegroundColor Red } 5. 库管理 5.1 安装库 # 搜索库 arduino-cli lib search \"ArduinoJson\" # 安装库 arduino-cli lib install \"ArduinoJson\" arduino-cli lib install \"PubSubClient\" # 安装特定版本 arduino-cli lib install \"ArduinoJson@6.21.3\" # 从Git URL安装 arduino-cli lib install --git-url https://github.com/user/library.git # 从ZIP安装 arduino-cli lib install --zip-path ./MyLibrary.zip 5.2 常用ESP32库清单 # 网络通信 arduino-cli lib install \"ArduinoJson\" # JSON处理 arduino-cli lib install \"PubSubClient\" # MQTT客户端 arduino-cli lib install \"WiFiManager\" # WiFi配网 # 传感器 arduino-cli lib install \"DHT sensor library\" # DHT温湿度 arduino-cli lib install \"Adafruit Unified Sensor\" arduino-cli lib install \"BMP280_DEV\" # 气压传感器 # 显示 arduino-cli lib install \"TFT_eSPI\" # TFT显示屏 arduino-cli lib install \"U8g2\" # OLED显示屏 # 其他 arduino-cli lib install \"ESPAsyncWebServer\" # 异步Web服务器 arduino-cli lib install \"AsyncTCP\" 5.3 本地库开发 将库放在项目目录的 lib/ 子目录下： MyProject/ ├── MyProject.ino └── lib/ └── MyCustomLib/ ├── MyCustomLib.h └── MyCustomLib.cpp 6. 串口调试 6.1 Arduino CLI 串口监视器 # 打开串口监视器 arduino-cli monitor -p COM11 # 指定波特率 arduino-cli monitor -p COM11 --config baudrate=115200 # 支持的波特率: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400, 250000, 500000, 1000000, 2000000 6.2 使用其他串口工具 Windows - PuTTY: Connection type: Serial Serial line: COM11 Speed: 115200 跨平台 - minicom/picocom: # Linux/macOS minicom -D /dev/ttyUSB0 -b 115200 picocom -b 115200 /dev/ttyUSB0 Python串口工具: import serial ser = serial.Serial( 'COM11' , 115200 , timeout= 1 ) while True : line = ser.readline().decode( 'utf-8' ).strip() if line: print (line) 7. 完整开发工作流脚本 7.1 Windows批处理脚本 (build.bat) @echo off setlocal enabledelayedexpansion set PROJECT_NAME=esp32-wifi-controller set FQBN=esp32:esp32:esp32 set PORT=COM11 echo ======================================== echo ESP32 Arduino Build Script echo Project: %PROJECT_NAME% echo ======================================== :: Find project directory if exist \"%PROJECT_NAME%/%PROJECT_NAME%.ino\" ( cd \"%PROJECT_NAME%\" ) else if exist \"%PROJECT_NAME%.ino\" ( echo Already in project directory ) else ( echo Error: Cannot find %PROJECT_NAME%.ino exit /b 1 ) echo. echo [1/4] Checking Arduino CLI... arduino-cli version >nul 2>&1 if errorlevel 1 ( echo Error: Arduino CLI not found in PATH exit /b 1 ) echo. echo [2/4] Updating core index... arduino-cli core update-index echo. echo [3/4] Compiling... arduino-cli compile --fqbn %FQBN% --verbose if errorlevel 1 ( echo. echo Compilation FAILED! exit /b 1 ) echo. echo [4/4] Uploading to %PORT%... echo If upload fails, press and hold BOOT, then press EN, release BOOT, and retry. arduino-cli upload --fqbn %FQBN% -p %PORT% if errorlevel 1 ( echo. echo Upload FAILED! exit /b 1 ) echo. echo ======================================== echo Build and Upload SUCCESSFUL! echo ======================================== timeout /t 3 7.2 Linux/macOS Shell脚本 (build.sh) #!/bin/bash PROJECT_NAME= \"esp32-wifi-controller\" FQBN= \"esp32:esp32:esp32\" PORT= \"/dev/ttyUSB0\" # 根据实际修改 echo \"========================================\" echo \"ESP32 Arduino Build Script\" echo \"Project: $PROJECT_NAME \" echo \"========================================\" # 检测项目目录 if [ -d \" $PROJECT_NAME \" ]; then cd \" $PROJECT_NAME \" fi # 检查Arduino CLI if ! command -v arduino-cli &> /dev/null; then echo \"Error: Arduino CLI not found\" exit 1 fi # 自动检测串口 if [ -z \" $PORT \" ]; then PORT=$(arduino-cli board list | grep \"esp32\" | head -1 | awk '{print $1}' ) if [ -z \" $PORT \" ]; then echo \"Error: No ESP32 device found\" exit 1 fi echo \"Auto-detected port: $PORT \" fi echo \"\" echo \"[1/3] Compiling...\" arduino-cli compile --fqbn \" $FQBN \" || exit 1 echo \"\" echo \"[2/3] Uploading to $PORT ...\" echo \"If fails: Hold BOOT, press EN, release BOOT\" sudo arduino-cli upload --fqbn \" $FQBN \" -p \" $PORT \" || exit 1 echo \"\" echo \"[3/3] Opening serial monitor...\" sleep 1 arduino-cli monitor -p \" $PORT \" -c baudrate=115200 8. 常见问题与解决 8.1 \"Failed to connect to ESP32: Timed out waiting for packet header\" 原因： ESP32未进入下载模式 解决： 按住 BOOT 按钮 按一下 EN 按钮 松开 BOOT 按钮 立即执行上传命令 8.2 \"A fatal error occurred: Failed to connect to ESP32: Invalid head of packet\" 原因： 串口被占用或波特率不匹配 解决： # 关闭所有串口监视器 # 检查占用（Linux） sudo lsof /dev/ttyUSB0 # 降低上传波特率 arduino-cli upload --fqbn esp32:esp32:esp32 -p COM11 -t UploadSpeed=115200 8.3 \"ESP32: esp32: No board selected\" 原因： 未安装ESP32核心或FQBN错误 解决： # 安装ESP32核心 arduino-cli core install esp32:esp32 # 查看可用板子 arduino-cli board listall esp32 8.4 \"Library not found\" 原因： 缺少依赖库 解决： # 安装缺失的库 arduino-cli lib install \"LibraryName\" # 或创建libraries目录链接 ln -s /path/to/your/libs ~/Arduino/libraries 8.5 串口权限问题 (Linux)",
    "model_config": {
        "provider": "deepseek",
        "model": "deepseek-chat",
        "temperature": 0.7,
        "max_tokens": 4096,
        "top_p": 0.9
    },
    "examples": [
        {
            "input": "请用esp32-arduino-development帮我处理问题",
            "output": "好的，我是esp32-arduino-development。ESP32 Arduino框架完整开发指南。涵盖Arduino CLI工具链配置、ESP32项目编译、\n固件烧录、串口调试等全流程。适用于ESP32-WROOM-32等常见开发板，解决环境配置、\n库依赖管理、上传失败、串口通信等常见问题。支持Windows/Linux/macOS跨平台开发。 我会根据你的需求提供专业帮助。"
        },
        {
            "input": "介绍一下你的能力",
            "output": "我是esp32-arduino-development，专注于开发编程领域。ESP32 Arduino框架完整开发指南。涵盖Arduino CLI工具链配置、ESP32项目编译、\n固件烧录、串口调试等全流程。适用于ESP32-WROOM-32等常见开发板，解决环境配置、\n库依赖管理、上传失败、串口通信等常见问题。支持Windows/Linux/macOS跨平台开发。"
        }
    ],
    "install_guide": {
        "coze": "在 Coze 平台创建 Bot -> 技能配置 -> 导入此 .skill 文件",
        "dify": "在 Dify 平台创建应用 -> 添加知识库 -> 导入此 .skill 配置",
        "claude": "将 system_prompt 字段内容复制到 Claude 自定义指令中",
        "custom": "将此 .skill 文件加载到你的 AI Agent 框架中，解析 system_prompt 和 model_config 即可使用"
    }
}