# 让 AI 协助开发 ESP32 Arduino：用 PowerShell 实现一键编译、上传与串口调试

HH_330

289人浏览 · 2026-06-21 16:36:18

HH_330 · 2026-06-21 16:36:18 发布

在使用 Arduino IDE 开发 ESP32 项目时，最常见的操作通常是：编译程序、选择串口、上传固件，然后打开串口监视器查看日志。如果需要频繁切换多个 Sketch，重复执行这些步骤会比较繁琐，也不利于自动化验证，更不方便 AI 编码助手直接参与开发。

AI 可以阅读和修改 Arduino 代码，但要真正协助嵌入式开发，还必须能够验证代码是否编译成功、固件能否上传，以及开发板运行时输出了什么日志。只修改代码而不执行这些验证，AI 很难发现编译错误、串口配置错误和硬件运行异常。

build.ps1 正是为解决这个问题而编写的。它是一个面向 Windows PowerShell 的 Arduino 构建脚本，以 arduino-cli 为基础，将编译、上传、串口识别和日志监视整合为一条命令。开发者或具备本地终端执行能力的 AI 编码代理，都可以通过相同命令完成 ESP32-C3 项目的开发和验证。

本文以如下环境为例：

开发板：ESP32-C3
Arduino FQBN：esp32:esp32:AirM2M_CORE_ESP32C3
示例串口：COM58
串口波特率：115200
PowerShell 脚本：build.ps1

FQBN 和串口都可以通过命令行参数修改，因此脚本并不局限于上述开发板和端口。

一、脚本解决了什么问题

build.ps1 主要提供以下功能：

调用 arduino-cli 编译 Arduino Sketch。
编译成功后自动上传固件。
支持手工指定串口，也支持自动识别上传串口。
支持只编译、不上传，便于快速检查代码。
支持清理构建缓存和输出详细日志。
支持列出当前检测到的串口设备。
上传完成后可直接打开串口监视器。
支持限时读取串口日志，防止 AI 或自动化任务一直占用终端。
使用明确的退出码和错误信息，便于 AI 判断编译或上传是否成功。

脚本默认的执行流程如下：

检查 Arduino Sketch
        ↓
调用 arduino-cli 编译
        ↓
识别或使用指定串口
        ↓
上传固件
        ↓
按需读取串口日志

为什么它适合 AI 协助开发

Arduino IDE 主要依赖图形界面操作。开发者可以手工点击“验证”“上传”和“串口监视器”，但 AI 编码代理通常更适合调用稳定、可重复的命令行工具。build.ps1 将这些图形界面操作转换为标准 PowerShell 命令，使 AI 不仅可以编写代码，还能执行下面的完整验证闭环：

读取项目约定和源代码
        ↓
修改 Arduino 程序
        ↓
执行编译并分析错误
        ↓
上传固件到指定串口
        ↓
限时读取开发板日志
        ↓
根据日志继续定位和修改

这种工作方式的关键不在于让 AI “猜测代码是否能用”，而是给 AI 提供真实的编译结果和设备日志，让后续修改建立在可验证的反馈之上。

其中，几个参数对 AI 协作尤其重要：

-CompileOnly：先做低风险编译检查，不连接或改写开发板。
-Port：明确指定目标设备，避免多串口环境下选错开发板。
-MonitorSeconds：只读取固定时间的日志，命令能够自动结束。
-CliVerbose：在失败时提供更完整的信息，方便分析工具链问题。
-Clean：怀疑缓存干扰时执行一次干净构建。

AI 编码代理必须具备执行本地 PowerShell 命令的权限，才能实际完成编译、上传和串口验证。只能进行文本对话的 AI 仍然可以帮助分析代码，但无法直接操作本机开发板。

二、使用前准备

1. 安装 Arduino IDE 或 arduino-cli

脚本需要调用 arduino-cli.exe。如果已经安装 Arduino IDE 2.x，可以使用 IDE 自带的 arduino-cli.exe；也可以单独安装 Arduino CLI。

脚本当前的默认路径为：

D:\Program Files\Arduino IDE\resources\app\lib\backend\resources\arduino-cli.exe

如果你的安装位置不同，有两种处理方式。

第一种方式是在执行脚本时通过 -CliPath 指定实际路径：

.\build.ps1 `
  -Sketch Master_Node `
  -CompileOnly `
  -CliPath "C:\Program Files\Arduino IDE\resources\app\lib\backend\resources\arduino-cli.exe"

第二种方式是修改 build.ps1 中 $CliPath 参数的默认值。

可以先运行下面的命令确认路径是否有效：

& "D:\Program Files\Arduino IDE\resources\app\lib\backend\resources\arduino-cli.exe" version

2. 安装 ESP32 开发板支持包

本文示例使用的 FQBN 为：

esp32:esp32:AirM2M_CORE_ESP32C3

请先在 Arduino IDE 的开发板管理器中安装对应的 ESP32 开发板支持包，并确认能够在 Arduino IDE 中正常编译目标开发板。

如果使用其他开发板，可以通过 -Fqbn 覆盖默认值：

.\build.ps1 -Sketch MySketch -CompileOnly -Fqbn "厂商:架构:板卡ID"

3. 确认 Sketch 目录结构

Arduino Sketch 的目录名必须与主 .ino 文件名一致。例如：

项目根目录/
├── build.ps1
├── AGENTS.md
├── Master_Node/
│   └── Master_Node.ino
└── Slave_Node/
    └── Slave_Node.ino

如果指定 -Sketch Master_Node，脚本会检查以下文件是否存在：

Master_Node\Master_Node.ino

目录名与 .ino 文件名不一致时，脚本会直接报错，不会继续编译。

4. 允许 PowerShell 执行本地脚本

如果系统提示禁止运行脚本，可以仅对当前 PowerShell 进程临时调整执行策略：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

该设置只在当前 PowerShell 窗口中生效，关闭窗口后自动失效。

三、快速开始

打开 PowerShell，进入 build.ps1 所在目录。

编译并上传 Master_Node

.\build.ps1 -Sketch Master_Node -Port COM58

编译并上传 Slave_Node

.\build.ps1 -Sketch Slave_Node -Port COM58

只编译，不上传

.\build.ps1 -Sketch Master_Node -CompileOnly

在 -CompileOnly 模式下，脚本完成编译后会直接退出，不会检测串口，也不会上传固件。

上传后持续查看串口日志

.\build.ps1 -Sketch Master_Node -Port COM58 -Monitor

默认使用 115200 波特率持续读取串口输出，按 Ctrl+C 停止。

上传后只读取 8 秒日志

.\build.ps1 -Sketch Master_Node -Port COM58 -MonitorSeconds 8

-MonitorSeconds 大于 0 时会自动启用串口监视，无需再添加 -Monitor。读取时间结束后，脚本会关闭串口并自动退出。

该模式特别适合自动化测试，因为它不会一直占用终端。

四、完整参数说明

参数	类型	默认值	作用
`-Sketch`	字符串	`.`	指定 Sketch 目录，可使用相对路径或绝对路径
`-Port`	字符串	未指定	指定上传串口，例如 `COM58`；省略时尝试自动识别
`-CompileOnly`	开关	关闭	只编译，不上传
`-Clean`	开关	关闭	编译前清理构建缓存
`-CliVerbose`	开关	关闭	输出 `arduino-cli` 的详细编译或上传日志
`-ListPorts`	开关	关闭	列出可用串口及板卡探测信息，不编译和上传
`-Monitor`	开关	关闭	上传后持续读取串口日志，直到按 `Ctrl+C`
`-MonitorSeconds`	整数	`0`	上传后读取串口日志的秒数，范围为 `0` 到 `86400`
`-BaudRate`	整数	`115200`	串口监视器波特率，范围为 `1` 到 `4000000`
`-Fqbn`	字符串	`esp32:esp32:AirM2M_CORE_ESP32C3`	指定 Arduino 完全限定板卡名称
`-CliPath`	字符串	Arduino IDE 内置 CLI 路径	指定 `arduino-cli.exe` 的完整路径

当前版本会在处理 -ListPorts 之前检查 Sketch 是否有效。因此，在脚本所在目录本身不是 Arduino Sketch 时，请同时传入一个有效目录，例如 .\build.ps1 -Sketch Master_Node -ListPorts。

五、常用命令示例

1. 自动识别串口并上传

.\build.ps1 -Sketch Master_Node

如果脚本能够唯一确定目标串口，就会自动上传；否则会显示串口列表，并提示使用 -Port COMx 手工指定。

2. 查看当前串口设备

.\build.ps1 -Sketch Master_Node -ListPorts

输出中会包含端口地址、端口标签、协议类型、开发板名称和 FQBN。未识别出具体板卡时，开发板名称会显示为 Unknown。

3. 清理缓存后重新编译

.\build.ps1 -Sketch Master_Node -CompileOnly -Clean

当代码已经修改但编译结果疑似受到旧缓存影响时，可以使用 -Clean。

4. 输出详细日志

.\build.ps1 -Sketch Master_Node -Port COM58 -CliVerbose

该参数会把 --verbose 传给 arduino-cli，适合排查编译参数、工具链或上传失败问题。

5. 修改串口波特率

.\build.ps1 `
  -Sketch Master_Node `
  -Port COM58 `
  -MonitorSeconds 10 `
  -BaudRate 9600

波特率必须与固件中的 Serial.begin(...) 保持一致，否则串口输出可能出现乱码。

6. 使用其他开发板

.\build.ps1 `
  -Sketch MySketch `
  -Port COM12 `
  -Fqbn "esp32:esp32:你的板卡ID"

可通过 Arduino CLI 查询已安装的板卡：

arduino-cli board listall

六、串口自动识别规则

未传入 -Port 时，脚本会调用：

arduino-cli board list --format json

随后按以下优先级选择串口：

优先选择 arduino-cli 已识别为目标 FQBN 的唯一串口。
如果没有唯一匹配项，则选择具有 USB 特征的唯一串口，并排除常见的 COM1 和 COM2。
如果系统中只有一个串口设备，则直接使用该端口。
如果仍然无法唯一确定，列出设备并要求使用 -Port COMx 手工指定。

在连接多个串口设备时，建议显式传入 -Port，避免把固件上传到错误的设备。

七、串口监视器的工作方式

脚本使用 PowerShell/.NET 的 System.IO.Ports.SerialPort 读取串口，而不是再次启动 Arduino IDE。

串口配置如下：

数据位：8
校验位：None
停止位：1
DTR：关闭
RTS：关闭
默认波特率：115200
单次读取超时：500 ms

上传结束后，某些串口驱动可能不会立即释放端口。脚本会在最多 10 秒内重复尝试打开串口，减少刚上传完成时出现端口占用错误的概率。

八、配合 AGENTS.md 让 AI 参与固件开发

build.ps1 解决了“怎样执行”的问题，仓库中的 AGENTS.md 则解决了“AI 应该执行什么”的问题。它用于记录项目级开发约定，例如目标板卡、默认串口、波特率、调试引脚以及推荐的验证命令。

支持读取 AGENTS.md 的 AI 编码代理进入仓库后，可以先获取这些固定上下文，不必反复询问开发板型号、FQBN 或串口参数。完成代码修改后，它还可以按照文档约定执行统一的编译和串口检查流程。

例如，在修改 Master_Node 固件后，可以使用下面的限时验证命令：

.\build.ps1 -Sketch Master_Node -Port COM58 -MonitorSeconds 8

一次命令即可完成：

编译固件。
上传到 COM58。
以 115200 波特率读取 8 秒日志。
自动关闭串口并退出。

因此，一个适合 AI 协作的 ESP32 仓库可以同时包含：

项目根目录/
├── AGENTS.md       # 告诉 AI 板卡、串口和验证规则
├── build.ps1       # 为 AI 提供可执行的构建与调试入口
├── Master_Node/
│   └── Master_Node.ino
└── Slave_Node/
    └── Slave_Node.ino

需要注意的是，AGENTS.md 只描述操作约定；真正执行编译、上传和串口读取的是 build.ps1。两者配合后，AI 才能从单纯的代码生成工具，进一步参与可编译、可烧录、可观察的固件开发流程。

九、常见问题

1. 提示“未找到 arduino-cli”

原因： -CliPath 指向的文件不存在。

处理方法： 找到本机的 arduino-cli.exe，然后通过参数传入正确路径：

.\build.ps1 `
  -Sketch Master_Node `
  -CompileOnly `
  -CliPath "你的路径\arduino-cli.exe"

2. 提示“指定目录不是有效 Arduino sketch”

原因： Sketch 目录不存在，或者目录名与 .ino 主文件名不一致。

例如，目录为 Master_Node 时，必须存在：

Master_Node\Master_Node.ino

3. 提示“无法唯一确定上传串口”

原因： 电脑连接了多个串口设备，脚本无法安全判断目标端口。

处理方法： 先列出端口，再手工指定：

.\build.ps1 -Sketch Master_Node -ListPorts
.\build.ps1 -Sketch Master_Node -Port COM58

4. 上传时提示串口被占用

关闭 Arduino IDE 串口监视器、其他串口工具以及可能占用该端口的终端程序，然后重新执行上传命令。

5. 串口日志乱码

确认 -BaudRate 与程序中的串口初始化波特率一致。例如固件使用：

Serial.begin(115200);

则脚本应使用默认值或显式指定：

.\build.ps1 -Sketch Master_Node -Port COM58 -Monitor -BaudRate 115200

6. 编译或上传失败，但看不到足够信息

增加 -CliVerbose 获取 Arduino CLI 的详细日志：

.\build.ps1 -Sketch Master_Node -Port COM58 -CliVerbose

如果怀疑缓存异常，可以同时增加 -Clean：

.\build.ps1 -Sketch Master_Node -Port COM58 -Clean -CliVerbose

十、适用范围与注意事项

脚本面向 Windows PowerShell，串口名称按 COMx 形式处理。
默认 FQBN 与默认 Arduino CLI 路径是本项目配置，其他环境通常需要覆盖。
串口监视器按行读取日志。固件最好使用 Serial.println() 或输出换行符，以便及时显示内容。
-Monitor 和 -MonitorSeconds 仅在上传成功后执行；与 -CompileOnly 同时使用时不会打开串口监视器。
自动识别串口虽然方便，但多设备环境仍建议显式指定 -Port。
开源发布时建议同时添加合适的 LICENSE 文件，并在仓库 README 中说明支持的平台和测试环境。

十一、总结

编写 build.ps1 的主要目的，是为 AI 协助 ESP32 Arduino 开发提供一个稳定的命令行入口。AI 完成代码修改后，可以继续执行编译、上传和限时串口监视，根据真实结果判断修改是否有效，而不是停留在“代码看起来应该可以运行”的阶段。

对于开发者，这个脚本也减少了手工选择板卡、串口和监视器的重复操作；对于 AI 编码代理或自动化测试，AGENTS.md 提供项目约定，build.ps1 提供具体执行能力，两者共同构成可重复、可观察、能够自动结束的固件验证流程。

最常用的三条命令如下：

# 只编译
.\build.ps1 -Sketch Master_Node -CompileOnly

# 编译并上传
.\build.ps1 -Sketch Master_Node -Port COM58

# 编译、上传并读取 8 秒串口日志
.\build.ps1 -Sketch Master_Node -Port COM58 -MonitorSeconds 8