硬件方案与接线
硬件方案是这个平台里最先定下来、也最不应随意变更的部分。固件是按照它写的，接线是按照它接的。这一篇讲它怎么来的、怎么读、以及接线前要核什么。
一览
| 支持的框架 | esp-idf 与 arduino，只有这两种 |
|---|---|
| 支持的硬件 | esp-idf 的构建目标：esp32 / s2 / s3 / c2 / c3 / c6 / h2。arduino 的开发板：ESP32 与 ESP8266 系列开发板、Arduino Uno |
| 方案里有什么 | 框架、目标、器件清单、引脚连接、约束条目、记录在案的需求 |
| 方案里没有什么 | 元件的具体电气参数、PCB 布局、外壳、电源设计 |
| 谁说了算 | 你。它出方案，你确认了才生效 |
| 引脚可靠性 | 照资料推的，不是量出来的。接线前必须对实物核一遍 |
它是怎么替你选的
你描述完想做什么，它会做三件事：挑一颗主控、挑外围器件、把引脚排好。挑的依据按优先级是：
- 你手上已经有的。你说了型号，它就围着你的型号做，不会另选。
- 你的功能需求。要跑屏幕就得有足够的内存和接口，要跑蓝牙就得选带蓝牙的。
- 平台支持得好不好。它宁可给你一个稳的方案，而不是一个新颖但容易出问题的。
所以第 1 条最有价值。开头就说清楚你手上有什么，可以避免「方案里的板子我没有 / 我有的板子方案没用上」这一整轮。
提议 → 确认 → 冻结
方案有三个阶段，界面上都能看出来：
| 提议 | 它给出一版方案，在对话里展示。这时候还不算数，你可以随便让它改 |
|---|---|
| 确认 | 你在对话里说「确认」，它就不再改动这一版，准备冻结。这一步还没有生成任何固化的快照 |
| 冻结 | 方案被固化成一个带版本号的快照。之后写固件、编译，都以这个快照为准。Main 面板顶部会从「未冻结」变成「已冻结 #1」，顶栏也是到这一步才出现「硬件方案已确认」 |
冻结之后，对话里会出现一张方案卡，用三行数字说明固化了什么：几项器件、几条连接、几条约束。
为什么要冻结
因为固件必须依据一份固定不变的事实编写。如果方案边写边改，你会遇到「代码用的是旧引脚、表上写的是新引脚」这种最难查的问题。冻结的意思是：从这一刻起，写码和接线用的是同一份事实。
冻结不是永久的。需要修改时告知它即可，它会出新的一版重新走一遍确认。
冻结被拦住了怎么办
当你在对话里要求冻结时，有时会看到「冻结受阻」，下面列着几条待确认的项。这不是故障——它是在说：有些事实它没把握，怕替你做主。比如某个器件的 I²C 地址原理图上没写、某个模块的供电方式它推不出来。
两条路：
- 逐条给答案（推荐）。在对话里回答那几条，比如
那个触摸芯片的地址是 0x5A，我量过。信息补齐了自然就能冻。 - 知晓后仍然冻结。那一块的下面有这个按钮。点它会把你的决定发给助手，由助手带着这几条阻塞项重新提交冻结。代价是那几条以后可能真的是错的。
四个支持等级
顶栏一直挂着一个「硬件支持」标记。它回答的是：你现在这条路，平台有多大把握。
| 推荐 | 能为这套硬件挑出构建目标，而且硬件事实已经齐备。可以直接往下走 |
|---|---|
| 可尝试 | 构建目标挑得出来，但硬件事实还缺一块——通常是器件已经列出来了、引脚连接还没定。能做，出问题的概率高一些 |
| 信息不足 | 不是说不行，是说你给的信息还不够判断。补一句完整型号通常就变了 |
| 不支持 | 框架认出来了，但这个目标不在能力目录里，重试无用。它宁可现在说，也不假装能做然后在编译时炸掉 |
「信息不足」是最容易被误读的一个。看到它先别换板子——把板子上印的那一整串型号报给它，通常就过了。
读懂模块清单
Main 面板里的「模块清单」这一块，回答「它替我选了什么」。它是一份列表，每一行是一个器件，右边是它占用的引脚。
每行会标一个类型：
| 主控芯片 | 核心那颗芯片本身，比如 ESP32-S3 |
|---|---|
| 开发板 | 芯片焊在上面的那块成品板，比如 ESP32-S3-DevKitC-1。它右边列的引脚是这块板子上可用的脚 |
| 模块 | 外围器件：传感器、屏幕、PMU 等。右边列的是这个器件自己的引脚名（比如 SCL、SDA、RESET） |
按照这份清单采购。型号要对得上——同一个功能的模块，不同厂家引脚顺序可能完全不同。
读懂引脚连接表
模块清单下面那一块叫「引脚连接」，回答「怎么接线」。每一行是一条连接：某个模块的某个脚 → 开发板的某个脚。
| 模块 | 左边是外围器件和它自己的引脚名 |
|---|---|
| → | 连到 |
| 开发板 | 右边是开发板上的 GPIO 编号 |
| 类型 | 这条线是干什么的：电源 / 地 / 信号，或者具体的总线名（I²C、QSPI 等） |
⚠️ 板载已经连好的 vs 需要你自己接
这是最容易弄错、也最容易损坏器件的一处。
如果某个器件原本就焊在开发板上（比如板载的屏幕、板载的电源管理芯片），那么表里那些连接已经在板子内部连好了，你什么都不用接。这时候你要是按照表去外面又接一遍线，轻则不工作，重则短路。
只有那些你自己额外插上去的模块（面包板上的传感器、外接的屏幕）才需要按表接线。
怎么分辨：看模块清单里那一行是不是「开发板」自带的一部分。分不清就直接问它：
接线之前，核一遍
它给的引脚是照资料推的，不是量出来的。没做过联网核对时，界面上也写着这句话：「引脚未经联网核对，接线前请对照实物确认。」做过之后，那个位置显示的是最近一次联网核查的时间。
核什么：板子上印的丝印字。把表里的 GPIO4 和你板子上印的 4 或 D4 对上号。同一个系列不同型号的板子，引脚排布可能完全不同。
TRIG→GPIO2、ECHO→GPIO1、GND→GND，VCC 按模块自身的供电要求接。Main 面板上还有什么
往下滚还有这几块：
| 接线约束（必读） | 方案里那些会出事的地方，单独列在这里。动手之前先读这一块。接线之前也请确认手上的模块是 3.3V 还是 5V 版本，供电和信号电平要和板子对得上 |
|---|---|
| 记录在案的需求 | 它把你说过的要求逐条记下来，写固件时按这个来。可以当验收清单用 |
| 固件已实现功能 | 到目前为止固件里真的写了哪些功能。这张表是从代码里来的，不是从计划来的——它说有，就是真的有 |
| 编译产物 | 最近一次编译的结果，四行：「编译」（状态）、「框架」、「构建目标」、「大小」。失败时还会多一行「失败环节」 |
如果你熟悉软件开发
把「冻结的硬件方案」理解成一份 lockfile：它锁的不是依赖版本，是物理事实——哪颗芯片、哪几个脚、哪条总线。固件生成是以这份 lock 为输入的，改 lock 就要重新生成。
和 lockfile 不同的是：它没法验证。npm ci 会因为 lock 和 registry 对不上而失败，而这里，你把线接错了，编译仍然通过、烧录仍然成功，只有 Console 里那几行输出会告诉你不对。所以「接线前对实物核一遍」不是客套话，它是这条链路上唯一的校验环节，而且只能由你来做。
常见问题
我能指定用哪些引脚吗？
能，直接说。HC-SR04 的 TRIG 我要接 GPIO4，不要 GPIO2。它会重排方案。
方案确认之后还能改吗？
可以。说明想修改的内容，它会出新的一版。之前的版本仍然留着。
为什么不能用 GPIO6 到 GPIO11？
在经典 ESP32 上这几个脚接着 flash 芯片，占用它们板子就起不来。它一般会避开，但如果你自行指定就会遇到——所以描述需求时可以一并加上一句 不要用 GPIO6 到 GPIO11。
它给的方案我看不懂，能让它解释吗？
可以，这也是最简便的用法：解释一下为什么选这颗芯片、这几条 QSPI 的线分别是做什么的、哪些引脚还空着。你不需要看懂生成的代码，但可以随时问。