組裝指南

從頭到尾把硬體組起來：不需要任何焊接經驗。

這篇指南會帶你從安裝需要的軟體開始，一路走到親眼看見燈真正亮起來。如果你從沒焊過東西也不用擔心：如果用的是成品電路板，需要自己焊的零件只有一個，而且比看起來容易得多。

想先看零件清單？去看看 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，每次輸入後按 Enter。每輸入一個，應該只有對應的那一組 3 顆 LED（第 2-4 顆、第 5-7 顆、第 8-10 顆）亮起。不是整條燈條都亮。

如果這些都順利完成，恭喜，你的裝置已經可以正常運作了。接下來，安裝主機端軟體，讓它開始追蹤你的 Coding Agent 的狀態：參見專案 GitHub 頁面上的快速開始。

參考資料

幾個名詞，說明一下

LED 的排列方式

LED 1 從裝置通電開始，會一直亮著微弱的白光。如果你看到全部 10 顆 LED 同時亮起同一個顏色，代表燒錄的是舊版韌體：用最新的原始碼重新燒錄一次。

常見的坑

看門狗和心跳機制不是可有可無的附加功能：正是它們讓你可以放心離開，同時信任這盞燈。

關於你的作業系統

通訊協定參考

這是電腦透過 USB 傳送給裝置的完整單一字元指令集：

如果裝置 30 分鐘沒收到電腦的任何訊息，就會判定連線出了問題，自動切換成緩慢閃爍的紅色模式，而不是停在原本的顏色上一動不動。