组装指南

从头到尾把硬件装起来：不需要任何焊接经验。

这篇指南会带你从安装需要的软件开始，一路走到看见灯真正亮起来。如果你从没焊过东西也不用担心：如果用的是成品电路板，需要自己焊的部件只有一个，而且比听上去容易得多。

想先看零件清单？去看看 BOM（物料清单）。

1. 安装软件

在动手之前，先把能让电脑和板子对话的工具装好：

1. 安装 Arduino IDE（2.x 版本）。这是用来把固件（直接在板子上运行的小程序）烧录进设备的软件。
2. 让它认识这块板子用的芯片：
   • 在 Arduino IDE 的偏好设置里，把 arduino-pico 开发板包的地址加到"附加开发板管理器网址"里。
   • 打开开发板管理器，安装 "Raspberry Pi Pico/RP2040"。
   • 烧录固件时，开发板要选 "Waveshare RP2040-Zero"：这是这台设备实际用的芯片型号。
3. 安装 Adafruit NeoPixel 库（工具 → 管理库 → 搜索 "Adafruit NeoPixel" → 安装）。这是用来驱动 LED 的库：LED 需要非常精确的时序控制，普通的开关命令做不到。

2. 组装硬件

如果你手上还没有电路板，先从下面的制造流程开始，做完之后再继续看如果你有成品电路板。如果你已经有电路板了，或者只是想先测试一下、还不打算做实体板子，直接跳到接下来两节里适合你的那一节就行，两节里选一节做就够了。

想自己制造电路板

如果你已经有成品电路板了，或者只打算在面包板上试做（见下文），可以跳过这一节。

制造一块实体电路板需要的所有东西，都在 GitHub 上的硬件文件夹 里：

• KiCad 工程文件： 这块板子实际的设计文件，用设计它时用的那个免费工具（KiCad）就能打开。想自己看看或改改设计就打开它，不需要就不用管。
• Gerber 文件： 一套告诉代工厂具体要做出什么样电路板的生产文件。你不需要打开或看懂这些文件：把整个文件夹上传给一家代工厂（这个项目用的是 JLCPCB），他们就会寄回一块除了单片机之外都已经焊好的板子，跟零件清单里说的一样。
• 外壳文件： 3D 打印外壳用的、可以直接拿去打印的文件，交给 3D 打印服务商或者自己的打印机都行。

板子到手之后，回来继续往下看。

如果你有成品电路板

这是更简单的一条路，大多数人会走这条。成品电路板上的 LED 和小元件已经由厂商装好了：唯一需要自己动手的，是那块小小的单片机板（RP2040-Zero，负责运行一切的芯片）。

1. 把 RP2040-Zero 焊到板子上。它边缘有一圈半圆形的缺口（叫"castellated pad"，半孔焊盘），正好对上板子上对应的焊盘。每一个都要焊。这些连接里有的是走电源和信号的，有的纯粹是机械固定用的，但最简单的做法就是全部焊上。

给第一次焊接的朋友几个小提示：每焊完一个点，等几秒钟再去碰它；尽量别让焊锡在两个相邻焊盘之间连成一坨。万一真的连桥了，通常重新加热、补一点焊锡再把它们分开就能解决，或者用吸锡带把多余的焊锡吸走。

到这里，组装就完成了：不需要接线，也不需要跳线。芯片和 LED 之间的连接已经直接做在板子里了。焊完之后，直接跳到烧录与验证。

如果你在用面包板试做

如果你已经做完上面成品电路板的组装，可以跳过这一节。这条路是把裸的 RP2040-Zero 手工接到一条独立的 LED 灯带上，用来测试固件，适合还没拿到成品电路板，或者想先试试看的情况。

1. 给 RP2040-Zero 焊上排针。 它出厂时是没有插针的，只有裸露的半圆形缺口。至少焊三根：5V、GND，还有一根 GPIO（固件默认用 GPIO1）。焊一排公排针是最省事的做法，可以像插其他模块一样直接插上面包板；当然直接焊线也可以，只是这样接线就固定死了。

2. 接到 LED 灯带上：

    [RP2040-Zero]                    [LED 灯带，3 针接口]
      GND o---------------------------o G（地线）
      5V  o---------------------------o V（电源，不是 3V3，见下方说明）
      GP1 o---------------------------o S（信号 / 数据）
   
      USB-C 接口 -----> 数据线 -----> 你的电脑

   有几点需要注意：

   • 先接地线（G）。
   • V 要接到 5V 引脚，不是 3V3。
   • S（信号）接到你焊的那根 GPIO 引脚，要和固件里的 kDataPin 设置对上（或者干脆改固件代码去匹配你的接线）。
   • 三根线都接好之后再插 USB-C 线。半接好的状态就通电有短路的风险。
   • 可选：加一个小电阻和电容能让信号更稳定。如果遇到闪烁问题，参考 BOM（物料清单） 里的第 8、9 项。

接好线之后，继续看烧录与验证。

3. 烧录与验证

1. 用 Arduino IDE 打开 andon_light_firmware.ino（在项目源码的 device/firmware/andon_light_firmware/ 目录下）。
2. 开发板选 "Waveshare RP2040-Zero"，点击上传把固件烧进去。
3. 打开串口监视器，波特率设为 115200，换行符选 "Newline"。
4. 你应该会看到第一颗 LED 亮起微弱的白光，其余全暗：这是"设备正常运行"的常亮指示灯，不管处于哪种状态它都会一直亮着。
5. 依次输入 G、Y、R，每次输入后按回车。每输入一个，应该只有对应的那一组 3 颗 LED（第 2-4 颗、第 5-7 颗、第 8-10 颗）亮起。不是整条灯带都亮。

如果这些都顺利完成，恭喜，你的设备已经可以正常工作了。接下来，安装主机端软件，让它开始追踪你的编码 Agent 的状态：参见项目 GitHub 页面上的快速开始。

参考资料

几个术语，解释一下

LED 的排列方式

LED 1 从设备通电开始，会一直亮着微弱的白光。如果你看到全部 10 颗 LED 同时亮起同一个颜色，说明烧录的是旧版固件：用最新的源码重新烧录一次。

常见的坑

看门狗和心跳机制不是可有可无的锦上添花：正是它们让你可以放心地离开，同时信任这盏灯。

关于你的操作系统

通信协议参考

这是电脑通过 USB 发送给设备的完整单字符指令集：

如果设备 30 分钟没收到电脑的任何消息，就会认为出了问题，自动切换成缓慢闪烁的红色模式，而不是停在原来的颜色上一动不动。