韌體概覽

裝置上實際執行的是什麼，以及一個字元是怎麼變成光的。

韌體是直接執行在裝置晶片（一塊 Waveshare RP2040-Zero）上的小程式。不是執行在你電腦上的。它用 C++ 寫成，基於 Arduino 框架，工作內容很單純：透過 USB 監聽一個字元，然後點亮對應的 LED。

這台裝置的早期版本用的是 3 顆獨立的彩色 LED，而不是燈條。那版韌體還留著做參考，但目前持續開發的是燈條這一版。下面的內容都是圍繞現行這版燈條方案來說的。

這篇只講韌體本身（程式碼、依賴項目、怎麼燒錄和測試）。至於物理層面的部分（焊接、接線）請看組裝指南，那才是硬體組裝方面最權威的說明。

它依賴什麼

WS2812 系列的可定址 LED 需要極其精確的訊號時序，精確到一般的「接腳開關」指令根本做不到的程度。Adafruit_NeoPixel 是驅動這類 LED 的標準函式庫，這份韌體用的就是它。它對這顆晶片的時序硬體有原生支援，讓訊號更可靠。

環境設置

Arduino IDE 2.x，裝好 arduino-pico 開發板套件。
透過 Arduino Library Manager 安裝 Adafruit NeoPixel 函式庫。
打開 andon_light_firmware.ino：Arduino IDE 會自動把相關的 led_controller.h/.cpp 和 watchdog.h 當作額外分頁一起載入進來。

如果還沒組裝好實體裝置，先去完成那一步。參見組裝指南的第二部分，弄好之後再回來燒錄和測試。

燒錄與測試

開發板選「Waveshare RP2040-Zero」，然後燒錄。
打開序列埠監控視窗，鮑率 115200，換行符號選「Newline」。
應該能看到第一顆 LED 亮起微弱的白光，其餘全暗。這是剛通電時的正常狀態。
依序輸入 G、Y、R，每次輸入後按 Enter。每輸入一次，應該只有對應狀態的那 3 顆 LED 亮起，其餘保持熄滅。
輸入 C，確認能看到下面說明的依序點亮模式。
如果想不等滿 30 分鐘就看到「連線中斷」的閃爍效果：把程式碼裡的 kWatchdogTimeoutMs 暫時改成 15000，燒錄後確認能看到紅色緩慢閃爍，然後改回 1800000 再燒錄一次。

再深入一點

關於功率

亮度被刻意限制了上限（led_controller.cpp 裡的 kBrightness = 130/255），一是為了控制耗電，二是避免直視時太刺眼。如果燈光是透過擴散罩之類的東西再看到的，可以適當調高。如果出現閃爍或顏色不對，那是硬體問題（具體是焊接還是接線，取決於你用的哪種組裝方式）。參見組裝指南裡的常見坑，這不是靠改韌體設定能解決的。

LED 的排列方式

LED	角色	顏色
1	常亮的「裝置正常」指示燈	微弱的白光
2-4	工作中	綠色（`G`）
5-7	等待你處理	黃色（`Y`）
8-10	閒置	紅色（`R`）；連線中斷時會緩慢閃爍

幾個細節補充：

LED 1 在所有狀態下都保持微弱白光常亮，包括裝置剛關閉的那一刻：它只是一個「板子通電、韌體在執行」的獨立指示燈，和 G/Y/R 這些狀態顏色沒有關係。
每種狀態只點亮自己對應的那一組 3 顆：除了 LED 1，其他所有組都保持熄滅。
連線中斷的閃爍效果只作用在 8-10 號這一組上，使用和依序點亮模式一樣的漸變曲線。
依序點亮模式（整理中）會用到全部 9 顆非狀態燈（2-10 號）：一顆點亮的 LED 從第 10 顆往第 2 顆方向移動，移到哪裡就固定在哪裡；下一輪會固定它旁邊那一顆，依此類推，直到全部 9 顆都亮起，然後重置重新開始。

如果你想知道確切數值，可以看 led_controller.cpp 裡的 kGreenStart/kYellowStart/kRedStart/kStatusPixel。

通訊協定參考

指令	效果	意義
`G`	LED 2-4 常亮綠色	Agent 正在工作
`Y`	LED 5-7 常亮黃色	等待你輸入或授權
`R`	LED 8-10 常亮紅色	閒置、已停止，或連線已中斷
`C`	LED 2-10 依序點亮模式	內部整理中（「整理中」）：Agent 仍然活著，只是在收尾
`H`	沒有視覺變化	心跳訊號：不改變顏色，只重置看門狗

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