トラブルシューティング
うまく動かない時は、直そうとする前に、まず問題がどこにあるかを順番に確認しましょう。
何かがうまく動かない時、一番の近道は「直そうとする」前に「問題が実際どこにあるのか」を絞り込むことです：ボード自体なのか、パソコン側のソフトウェアなのか、それとも両者をつなぐ接続なのか。以下は前のステップを踏まえて次に進む構成になっているので、原因の見当がついている場合でも、順番通りに確認していくのがおすすめです。
どこから始めればいい？
| 症状 | 確認する場所 |
|---|---|
| ライトが完全に消えていて、何も反応しない | ステップ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（と常時点灯の1個）だけです。テープの大部分が消えたまま緑色が点灯していても、それは正常な動作です。詳しくはLEDの並び方を参照してください。以下で扱う問題はそれとは違うものです：点灯しているはずのグループの中のLEDがおかしい、またはどの正常な状態にも当てはまらないパターンになっている、というケースです。
完成済み基板では、チップとLEDが同じ基板上にあるためケーブルを調べる必要がなく、「信号の問題」といえばほぼハンダ付けの不具合です。ブレッドボードでの組み立てでは、たいてい配線が原因です。以下、両方について説明します。
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| 点灯しているはずのグループの中で、一部のLEDが消えている・おかしい | データラインの接続が不安定：途中の接続が弱いと、そこから先のLEDが同期を失うことがあります | 完成済み基板： チップのピンにハンダ付けの不具合がないか確認してください。ブレッドボード： 信号線を短くする、コネクタの圧着を確認する、または部品表の任意項目にあるレベルシフターを追加してみてください。 |
| 色が薄い、色がおかしい、またはライトが点灯すると基板がリセットしているように見える | LEDへの電力が足りていません | 完成済み基板： USB-Cケーブルがデータ通信と電源供給の両方に対応しているか、電源系統のハンダ付けに問題がないか確認してください。ブレッドボード： V が 3V3 ではなく 5V ピンに接続されているか確認してください：組み立てガイドを参照してください。 |
何も点灯しない（1番目のLEDすら点かない）それでも andon-light set idle は正常終了する | ファームウェアが想定しているデータピンと、実際の配線が一致していません | 完成済み基板： kDataPin が基板の設計通りのトレースと一致しているか確認してください：通常は初期設定の GPIO1 です。ブレッドボード： 配線したピンが kDataPin と一致しているか確認してください。1番目のLEDは点くのに2番目以降が反応しない場合は、これではなくステップ3の内容です。 |
| 点灯する色が想定と違うLEDに出る（例：「作業中」で本来と違うグループが点灯する） | LEDテープが逆側の端から配線されています | 完成済み基板： これは製造上の問題である可能性が高いです：正常に動作している別の個体と比較してください。ブレッドボード： テープのどちら側の端がデータ入力用と印字されているか確認し、その端に S を配線しているか確認してください。 |
それでも解決しない場合は、Arduino IDEにAdafruit NeoPixelライブラリが実際にインストールされているか確認してください（ツール → ライブラリを管理 → 「Adafruit NeoPixel」で検索）。ライブラリが入っていない場合、通常は上記のような症状ではなくコンパイルエラーとして表示されますが、念のため確認する価値はあります。
ステップ4：Claude Codeのフック設定は正しいですか？
cat ~/.claude/settings.json以下を順に確認してください。
-
有効なJSONになっていますか？ 次を実行します。
python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json'))); print('VALID JSON')"エラーが表示される場合は、ファイルのどこかに小さな構文ミス（カンマや括弧の閉じ忘れなど）があります。修正されるまで、Claude Codeはフック設定全体を無視する可能性が高いです。
-
すべてのフックコマンドが
|| trueで終わっていますか？ これがないと、ボードが抜けているなどのちょっとした不具合が、Claude Code内で目立つエラー表示として現れてしまいます。本来、静かに背後で動くはずのステータスライトとしてはよろしくありません。ひとつ注意点があります。Claude Code自身のフックログは、実際には裏側のandon-lightの呼び出しが失敗していても「正常に完了しました」と表示することがあります：この挙動が疑わしい場合は、|| trueを外した状態でコマンドを直接実行し、本当の終了コードを確認してください。 -
フックコマンドに
"async": trueが付いていないことを確認してください。非同期で実行すると、コマンドの完了順序が入れ替わることがあり、ライトが古い色のまま固まってしまう可能性があります。 -
このファイルを編集した後、Claude Codeを再起動しましたか？ フックの設定は、セッション開始時にしか読み込まれません：すでに起動しているセッションは、設定変更に気づきません。「何も変わらない」という場合の原因として、これが最も多いです。
ステップ5：手動で試してみる
問題が「ライト・CLI側」にあるのか「Claude Codeのフック側」にあるのかを切り分けるのに役立つ方法です。フックが実行するのと同じコマンドを、自分の手で実行してみます。
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で順次点灯パターンこの4つが手動では正しく動くのに、実際のClaude Codeセッション中はライトが反応しない場合、原因はフック設定（ステップ4）にあるか、Claude Codeが設定変更をまだ読み込んでいない（再起動してみてください）可能性が高く、ハードウェアやCLI自体の問題ではありません。
Linux特有の注意点
ポートを開く際の権限エラー
ls -la /dev/ttyACM0グループの欄を確認してください：dialout と表示されているはずです。
groups $USER ではなく id で確認してください。 この2つは結果が食い違うことがあり、実際に動いているプログラムの権限を反映しているのは 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 によって PC が保護されました」という警告
インストーラーもツール本体も、デジタル署名がされていません。そのため、どちらを実行してもWindowsが初回にこの警告を表示し、一部のセキュリティソフトが反応することもあります。
これは、このような小規模で未署名のツールがパッケージ化される際によく起こる副作用で、一部のマルウェアの挙動と似て見えてしまうことが原因です。何かが壊れているわけではありません。
そのまま続行するには： 「詳細情報」をクリックし、続けて「実行」をクリックします。
インストール後に andon-light が見つからない
新しいターミナルウィンドウを開いてください（インストール前から開いていたターミナルは、更新後のPATHを認識しません）。
アンインストール後もPATHに残ってしまう
この修正が入る前の古いバージョンをインストールしていた場合、アンインストーラーが古いエントリを削除しないことがあります。手動で確認するには：システムのプロパティ → 環境変数 → Path（ユーザー環境変数） → AndonLight の項目が残っていないか確認し、あれば削除してください。
パソコン側のソフトウェアがLEDハードウェアについて何も知らなくていい理由
コマンドラインツールは、それぞれの状態を1文字にマッピングしているだけです（作業中なら G、対応待ちなら Y、というように）。そして、その1文字を、見つかったポートに向けて送るだけです。LEDが何個接続されているか、どう配線されているか、そもそもアドレサブルLEDなのかどうかさえ、ツール側は関知していません：そうした処理はすべて、USB接続の向こう側にあるファームウェアの中で完結しています。デバイスの自動検出が、LEDハードウェアのバージョンが変わっても同じように機能するのもこのためです：検出しているのはマイコンボード自体であり、その先につながっているものではないからです。