从一句描述到可运行的板子
我们来完成一个真实的项目：一台超声波测距仪——每秒测一次前方障碍物的距离，把读数打到串口上。走完这一篇，你手上会有一块正在跑你自己固件的板子。这个项目在「公开共享」里有一个完整的发布版本，本篇的每一步都围绕它展开。
一览
| 屏幕前的时间 | 大约 30–60 分钟 |
|---|---|
| 要花的钱 | 大约 10 元 |
| 需要的软件 | Chrome 或 Edge。不用装 IDE，不用装编译器 |
| 做完你会有 | 一块跑着你自己固件的板子，和一份可以继续改的工程 |
手上已经有板子了？直接跳到 Step 1 开说，只要在描述里点名你的板子型号即可。
Step 0 | 先备齐这些
先把下面这些备齐，后面每一步都要用到。
必须有的
| 一块开发板 | 本篇用 ESP32-S3-DevKitC-1。ESP32-C3 的开发板也可以，只是引脚编号要跟着改。不要买 STM32、树莓派 Pico 这类——它们编不出固件 |
|---|---|
| 一根能传数据的 USB 线 | 最容易踩的一处。充电线插上去板子电源灯照亮，但电脑完全认不出它，而且没有任何报错。用一根你确定给手机传过文件的线 |
| Chrome 或 Edge 浏览器 | Firefox 和 Safari 没有浏览器烧录的能力 |
| 一个传感器 | 本篇用 HC-SR04 超声波测距模块。如果想先验证整条流程，这一项可以稍后采购 |
| 杜邦线和一块面包板 | HC-SR04 和开发板之间要接四根线（VCC、GND、TRIG、ECHO）。本篇照片里用的就是面包板加杜邦线 |
不需要的
不用装 Arduino IDE，不用装 ESP-IDF，不用配交叉编译环境，不用会写 C++。编译在云端做，烧录在浏览器里做。
Step 1 | 说出你想做什么
打开 WhispBuild，首页中间就是一个输入框。
把这段复制进去（如果你已经买了其他板子，把型号换掉）：
这句为什么管用：它点名了板子和模块（不用替你推测型号）、给了两个引脚（省一轮来回）、交代了供电和共地的方式、也说清了这一轮不做什么。想知道怎么写出这样的描述，看 如何准确描述你要的设备。
发出去之后，它会先跟你聊，确认要不要建一个项目。创建项目要你亲自确认——名字可能已经替你填好了，核对一遍再点。
看到什么算成功：浏览器进入了项目页面，左边是对话，右边是一个空的 Main 面板，上面写着「在左侧对话里描述你要做的设备」。
Step 2 | 看它给的硬件方案
进了项目之后，把你的需求再说一遍（或者它已经带过来了），它会开始出硬件方案。这一轮通常要一两分钟。
方案出来之后，对话里会列出它选了哪些器件、每个脚接哪里、有哪些约束。注意其中那条提醒——它给的引脚是照资料推的，接线前你要对着实物核一遍。
右边的 Main 面板会同步出现两块内容：模块清单（它替你选了什么，是一份列表）和引脚连接（按照这个接线，是一张表）。这两块是你之后接线的依据。怎么读它们 →
看下来觉得没问题，就回一句确认；不满意就直接说哪里不对，比如 换成我手上的 ESP32-C3、ECHO 我打算加一个分压电阻，帮我在方案里写上。
看到什么算成功：它在对话里给出了完整的器件清单和引脚安排，Main 面板同步出现了模块清单和引脚连接。顶栏的「硬件方案已确认」要等方案冻结之后才亮，冻结是怎么回事 →
Step 3 | 按清单采购
方案定了，按照模块清单去采购。
这些可以先做：
- 让它先把固件写出来并编译通过。编译不需要板子在手，见 Step 5；板子到手后直接烧即可。
- 把 Chrome 或 Edge 装好。
- 浏览一遍按现象查故障那一页。不用记住，只要知道有这么一页、大概有哪些条目。板子到手后真卡住的时候，你会知道去哪找。
- 读一遍 如何准确描述你要的设备。这是投入产出比最高的半小时。
板子到手后，先做一件事：把板子上印的型号和你在方案里说的那个对一遍。同一个系列下的不同板子引脚可能完全不同；型号不符时，接线、烧录、串口都可能出问题，而报错不会指向型号。
Step 4 | 插上，让电脑认出它
先不要接传感器。第一次只插板子和线，把最基础的链路验通。
- 用那根能传数据的线，把板子直接插到电脑上（不要经过集线器）。
- 板子上的电源灯应该亮起来。
- 确认电脑认出了它：Windows 打开设备管理器看「端口 (COM 和 LPT)」；macOS 在终端里敲
ls /dev/cu.*；Linux 敲ls /dev/ttyUSB* /dev/ttyACM*。
看到什么算成功：系统的端口列表里多出来一条，名字里带 USB、CH340、CP210 或 usbserial 之类的字样。
什么都没多出来？先别怀疑板子坏了。先换一根线——充电线是这一步最常见的原因。还是不行，去 板子插上了，端口列表里没有它，那里有一个能分辨故障在哪一侧的测试。
Step 5 | 让它写固件并编译
回到对话，输入：
接下来它会写代码、编译。这一轮要几分钟。界面上不会有百分比进度条——那个数字会是编的。取而代之的是它现在在做哪一步：分析需求、准备工具、生成固件并编译。
编译成功后，它会在对话里说清楚做了什么、构建配置是什么。顶栏右边的下载 / 烧录 / 打包发布三个按钮也是这时候才亮起来——没编译出固件之前它们是灰的。
看到什么算成功：对话里的进度标记走到 📦 编译通过，顶栏的「烧录」按钮从灰变成可点。
编译失败不是死路——它会读编译器报错、改代码，再编一轮。要是连着几轮都不过，看 编译一直不通过，那里有一张表告诉你哪几类需要你介入、哪几类不需要。
Step 6 | 烧进去
⚠️ 先做一件事：如果你开着 Console，去点「断开设备」。一个串口一次只能被一个程序占着。本页 Console 连着的时候「烧录」是灰的、点不动；被 Arduino IDE 或另一个标签页占着的时候按钮还亮着，但烧录会失败，而且报错完全看不出是这个原因。
- 确认板子插着。
- 点顶栏的 烧录。
- 弹出的窗口里，等它把固件下载到浏览器（会显示
Firmware ready和字节数），然后点 开始烧录。 - 浏览器会弹出一个端口选择框——这是 Chrome 自己的窗口，不是我们的界面。选中你的板子，点「连接」。
- 等进度条走完。
看到什么算成功：进度条走到 100%，进度旁边的状态变成「烧录完成」；日志最后一行是一句英文 Flash completed with … for ….（中英文界面都是英文）。板子上的灯通常会闪一下——那是它在重启。
端口选择框是空的？那说明电脑根本没认出这块板子，问题不在烧录这一步，在 Step 4。去 板子插上了，端口列表里没有它。
烧录会覆盖板子上原来的程序，不会弄坏板子。
Step 7 | 查看设备输出
固件已开始运行，但你还看不见它在干什么。接上串口就能看见。
- 切到 Console 面板。
- 点「连接设备」，波特率选
115200——默认约定就是这个，选错了读出来就是乱码；遇到乱码就点「断开设备」，重新连一次并把波特率选成115200，仍然乱码看 串口连上了，但打出来的全是乱码。 - 浏览器又会弹一次端口选择框，选同一个端口。
- 按一下板子上的 RST 键（复位键，丝印写的就是 RST），让它从头启动一次。
看到什么算成功：每秒输出一行 Distance: 45 cm。把手掌放到模块前面再移开，数字会跟着变。
调不通的时候，把日志回传给它
这是整个平台最有用的一个循环：Console 里选中日志 → 复制 → 粘到对话框 → 说明你希望它关注什么。它会依据日志修改代码、重新编译，你再烧一次。
界面导览
到这里你已经用过整个界面了。回过头给你一张地图：左边永远是对话，所有事情都从那里发起；右边是四个可切换的面板，各回答一个问题。
| Main | 「它替我定了什么？」模块清单、引脚连接、固件已实现的功能、编译产物。详解 → |
|---|---|
| 资料 | 「我给了它什么？」原理图、datasheet 这类长期工程资料。详解 → |
| 源码 | 「它写了什么？」完整的工程目录树。看不看得懂都行，不看也能做完整个流程。详解 → |
| Console | 「板子在说什么？」实时串口日志。日志只留在你浏览器本地，不会上传。详解页里那张 Console 截图取自这个项目的联网版本，所以多出 Wi-Fi 和 IP 那几行；本篇第一轮不联网，读数那几行是一样的。详解 → |
顶栏右边那三个按钮——下载拿固件文件，烧录直接烧进板子，打包发布把整个工程分享出去。它们要等编译出固件之后才会亮。它们左边还有一个高级，目前是灰的、不可点。
如果你熟悉软件开发
这一整套的心智模型是：对话 → 工程变更 → 编译 → 固件产物 → 烧录 → 设备。前四环在云端、有状态、可查；最后一环在你的桌子上，平台完全看不见。
所以「编译通过」只证明代码层面 OK，不证明它在你板子上能跑——引脚接错、模块型号不符、供电不足，编译器一个都发现不了。真正的验收永远是 Console 里那几行输出。
接下来
你已经完整走通了整条流程。往下可以：