疑難排解
東西不太對勁？按順序一步步來，先搞清楚問題到底出在哪裡。
東西不太對勁的時候，最快解決問題的方法不是急著去「修」，而是先搞清楚問題到底出在哪：是板子本身、電腦上的軟體，還是兩者之間的連線。下面每一步都是建立在前一步的基礎上，所以就算你大概猜到問題出在哪，還是建議按順序走一遍。
不知道從哪開始？
| 你看到的情況 | 去看 |
|---|---|
| 燈完全不亮，沒有任何反應 | 第 1 步 |
| 顏色不對、閃爍，或者亮的 LED 不對 | 第 3.5 步 |
| 燈亮著，但卡在錯誤的顏色上 | 第 4 步 |
andon-light 指令本身就報錯 | 第 2 步 |
| 之前好好的，拔插一次之後就壞了 | 第 1 步 |
第 1 步：板子在執行韌體嗎？
在終端機裡執行：
lsusb | grep -i "2e8a"| 你看到的內容 | 意義 | 怎麼辦 |
|---|---|---|
2e8a:0003 Raspberry Pi RP2 Boot | 板子處於「開機載入器」模式：這是專門用來燒錄新韌體的特殊模式，不是正常使用時的狀態，這個模式下 LED 不會有反應。 | 打開 Arduino IDE 點擊上傳：它會自動辨識這個狀態並完成燒錄。 |
出現包含 Waveshare 或 RP2040 Zero 的一行 | 很好：韌體正在正常運作。 | 繼續看第 2 步。 |
| 什麼都沒顯示 | 板子沒插上，或者傳輸線不支援傳資料。 | 換一條 USB-C 傳輸線試試，確認有插緊。 |
也可以直接檢查開機載入器模式下出現的那個檔案傳輸磁碟：
find /media /run/media /mnt -maxdepth 3 -iname "*RPI*" 2>/dev/null如果印出了路徑，代表板子處於開機載入器模式：解決辦法同上。
第 2 步：電腦上的軟體能看到板子嗎？
andon-light doctor| 你看到的內容 | 意義 |
|---|---|
Found device on /dev/ttyACM0（或類似內容） | 軟體能看到板子，權限也沒問題。繼續看第 3 步。 |
No device found | 板子沒有在執行韌體。回到第 1 步。 |
[Errno 13] Permission denied | 權限問題，僅出現在 Linux 上：參見下面的開啟連接埠時提示權限被拒。 |
第 3 步：是不是有別的東西佔用著這個連線？
andon-light set idle| 你看到的內容 | 意義 |
|---|---|
| 沒有任何輸出，正常結束 | 電腦和板子之間的連線是通的。如果 LED 還是沒變化，去看第 3.5 步，或試試重新燒錄（第 1 步）。 |
andon-light: serial error: ... Device or resource busy | 有別的程式佔用著這個連線：幾乎都是背景還開著的 Arduino IDE 序列埠監控視窗。關掉它再試一次。 |
如果不確定指令到底成功了沒，直接看結束代碼：
andon-light set idle; echo "exit code: $?"結束代碼是 0 就代表成功了。
第 3.5 步：閃爍、顏色不對，或者部分點亮看起來怪怪的
可定址 LED 既需要資料訊號的精確時序，也需要足夠的供電。連線不穩定就可能導致看得見的異常，即使「技術上」其實是通的。
先排除一個不算問題的情況： 按設計，同一時間只會有 3 顆 LED 亮起（加上那顆常亮的狀態燈）。看到大部分燈條是暗的、只有綠色那組亮著，這是正常現象。詳細內容見 LED 的排列方式。下面要講的問題不一樣：是應該亮的那一組裡面有 LED 不對，或者亮起的樣子完全不符合任何一種正常狀態。
在成品電路板上，晶片和 LED 在同一塊板子上，沒有線材可以檢查，所以「訊號問題」幾乎都代表虛焊。在麵包板上，通常是接線的問題。下面兩種情況都會講到。
| 你看到的情況 | 可能的原因 | 可以試試 |
|---|---|---|
| 該亮的那組裡，有些 LED 暗著或不對，其他的正常 | 資料線連接不穩定：某處連接不牢，會導致後面的 LED 失去同步 | 成品電路板： 檢查晶片接腳有沒有虛焊。麵包板： 把訊號線剪短一點，檢查連接器壓接是否牢固，或者加一個物料清單裡可選的電位轉換器。 |
| 顏色偏暗、顏色不對，或者燈一亮板子就像重新開機一樣 | 供給 LED 的電力不夠 | 成品電路板： 確認 USB-C 傳輸線既能傳資料又能供電，檢查電源部分有沒有虛焊。麵包板： 確認 V 接的是 5V 而不是 3V3：見組裝指南。 |
完全不亮（連第 1 顆都不亮）但 andon-light set idle 執行成功 | 韌體預期的資料接腳和實際接線對不上 | 成品電路板： 確認 kDataPin 和板子設計的走線一致：預設應該是 GPIO1。麵包板： 檢查你接的那根接腳是不是和 kDataPin 一致。如果第 1 顆 LED 能亮，但 2-10 號完全沒反應，那是第 3 步的問題，不是這裡。 |
| 亮的顏色對不上該亮的 LED（比如「工作中」點亮了不該亮的那組） | LED 燈條是從錯誤的一端接入資料的 | 成品電路板： 這種情況通常代表板子設計或生產有問題：先和一塊正常運作的板子比較看看。麵包板： 檢查燈條上哪一端印著是資料輸入端，確認 S 接的是那一端。 |
如果還是沒解決，確認 Arduino IDE 裡確實裝了 Adafruit NeoPixel 函式庫（工具 → 管理函式庫 → 搜尋「Adafruit NeoPixel」）。函式庫沒裝通常會出現編譯錯誤，而不是上面這些症狀，但還是值得排查一下。
第 4 步：Claude Code 的 hook 設定對嗎？
cat ~/.claude/settings.json按下面的清單逐項檢查：
-
是合法的 JSON 嗎？ 執行：
python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json'))); print('VALID JSON')"如果報錯，代表檔案裡某處有個小的語法錯誤（通常是漏了逗號或括號）。在修好之前，Claude Code 很可能會直接忽略整個 hooks 設定。
-
每條 hook 指令是不是都以
|| true結尾？ 如果沒有，任何小問題（比如板子被拔掉了）都會在 Claude Code 裡以顯眼的錯誤形式冒出來。這和「安靜地待在背景」的狀態燈設計初衷不符。有一點要注意：Claude Code 自己的 hook 記錄有時會顯示「執行成功」，即使背後真正呼叫的andon-light其實失敗了：如果懷疑是這種情況，把|| true拿掉直接執行指令，看看真實的結束代碼。 -
hook 指令是不是沒有標記
"async": true？ 非同步執行可能導致指令完成的順序被打亂，讓燈卡在一個過時的顏色上。 -
編輯完這個檔案之後，重新啟動 Claude Code 了嗎？ hook 設定只在工作階段開始時讀取：已經在執行的工作階段不會感知到設定變化。這是「改了卻沒反應」最常見的原因。
第 5 步：手動試一遍
這個方法能幫你分清楚問題是出在「燈和 CLI 這邊」，還是「Claude Code 的 hook 這邊」。自己手動執行一遍 hook 會執行的那些指令：
andon-light set working # LED 2-4 常亮綠色（除 1 號外其餘熄滅）
andon-light set waiting # LED 5-7 常亮黃色（除 1 號外其餘熄滅）
andon-light set idle # LED 8-10 常亮紅色（除 1 號外其餘熄滅）
andon-light set compacting # LED 2-10 依序點亮模式如果這四條手動執行都正常，但實際 Claude Code 工作階段中燈沒有反應，問題出在 hook 設定（第 4 步），或者 Claude Code 還沒讀到最新的設定（試試重新啟動它）。不是硬體或 CLI 的問題。
Linux 專屬說明
開啟連接埠時提示權限被拒
ls -la /dev/ttyACM0看一下群組那一欄：應該顯示 dialout。
用 id 檢查，不要用 groups $USER。 這兩個指令給出的答案可能不一樣，而真正反映「正在執行的程式實際擁有什麼權限」的是 id。
id這裡有個不太直觀的地方：不帶參數的 id 顯示的是目前這個終端機實際擁有的群組權限，這正是 andon-light 開啟連接埠時系統會檢查的東西。而 groups $USER 每次都是重新查一遍帳號本身的設定，跟目前有沒有程式在執行沒關係。所以可能出現這種情況：groups $USER 顯示已經有 dialout 了，但包括新開的終端機在內，所有終端機的 id 裡都還沒有。因為群組權限是在工作階段最初啟動的那一刻就固定下來的，單純在桌面環境裡登出重新登入一次，並不保證能讓所有程序都重新整理這個狀態。
如果 id 裡沒有 dialout：
| 解決辦法 | 有效範圍 | 指令 |
|---|---|---|
| 馬上能用 | 僅目前終端機 | newgrp dialout |
| 徹底解決 | 所有程式，保證生效 | sudo reboot |
| 臨時應急 | 每次拔插都要重新執行 | sudo chmod 666 /dev/ttyACM0 |
從終端機啟動 Arduino IDE 失敗
Arduino IDE 的 AppImage 有時會因為 FUSE 相關的錯誤（dlopen(): error loading libfuse.so.2 或 Cannot mount AppImage）啟動失敗。如果雙擊打不開，可以試試從終端機啟動，能完全繞開 FUSE 掛載這一步：
cd ~/Downloads
./arduino-ide_2.3.10_Linux_64bit.AppImage --appimage-extract-and-run（檔名依照你下載的實際版本調整。）解壓縮啟動需要幾秒鐘，之前開啟的專案和分頁應該會自動還原。
一切正常時應該是什麼樣子
$ lsusb | grep 2e8a
Bus 005 Device 010: ID 2e8a:0003 Raspberry Pi RP2 Boot # 這一行代表開機載入器模式（如果不是剛燒錄完看到這個，要留意）
# 韌體正常運作時，lsusb 不會單獨顯示「RP2 Boot」這一行。
# 改用 udevadm 檢查：
$ udevadm info -a -n /dev/ttyACM0 | grep -iE "manufacturer|product"
ATTRS{manufacturer}=="Waveshare"
ATTRS{product}=="RP2040 Zero"
$ andon-light doctor
Found device on /dev/ttyACM0
$ andon-light set working; echo "exit=$?"
exit=0Windows 專屬說明
「Windows 已保護您的電腦」警告
安裝程式和這個工具本身都沒有數位簽章，所以不管執行哪一個，Windows 第一次都會跳出這個警告，某些防毒軟體也可能會反應。
這是這類小型未簽章工具打包方式的副作用，恰好和某些惡意軟體的行為有點像。這不代表任何東西壞了。
要繼續執行： 點「其他資訊」，然後點「仍要執行」。
安裝完之後找不到 andon-light
打開一個新的終端機視窗（安裝之前就開著的終端機感知不到更新後的 PATH）。
解除安裝之後 PATH 裡還留著東西
如果你裝的是修正這個問題之前的舊版本，它的解除安裝程式可能不會清掉自己加的那條 PATH。手動檢查方法：系統內容 → 環境變數 → Path（使用者變數）→ 看看有沒有殘留的 AndonLight 項目，有的話刪掉。
為什麼電腦上的軟體完全不需要知道 LED 硬體長什麼樣
命令列工具只是把每種狀態對應成一個字元（工作中是 G，等待是 Y，依此類推），然後把這一個字元傳到找到的那個連接埠上。它根本不知道另一端接了幾顆 LED、怎麼接的，甚至不知道那是不是可定址 LED：所有這些邏輯完全在韌體裡處理，在 USB 連線的另一端。這也是為什麼裝置的自動偵測不管接的是哪個版本的 LED 硬體都一樣好用：它認的是單晶片板本身，不是後面接的東西。