コマンドラインツール

デバイスと通信するandon-lightコマンド：インストール方法、コマンド一覧、ボードの見つけ方。

andon-light は、パソコン上で動き、USB経由でデバイスと通信する小さなプログラムです。Pythonで書かれていて、Claude CodeとCodex CLIのフックが裏側でライトを自動的に切り替える際に呼び出しているのもこれです。もちろん、自分で直接実行することもできます。

インストール

日常的に使う場合は、ソースからビルドするのではなく、公開済みのバージョンをインストールしてください。LinuxまたはWindowsのインストールガイドを参照してください。macOSはまだテスト・対応していません。

このツール自体のソースコードを開発している場合は、プロジェクトの host/ フォルダの中で「編集可能」モードでインストールします。

cd host
pipx install --editable .

これによりソースファイルへ直接リンクされるため、再インストールしなくてもコードの変更がすぐに反映されます。

パソコンのPATHに追加せず、専用の隔離された環境に入れたい場合は次のようにします。

cd host
python3 -m venv .venv
.venv/bin/pip install -e .

使い方

andon-light doctor                              # デバイスを認識できているか確認する
andon-light set working                         # 緑色に点灯
andon-light set waiting                         # 黄色に点灯
andon-light set idle                             # 赤色に点灯
andon-light set compacting                       # 順次点灯パターン（内部整理中）
andon-light heartbeat                            # ウォッチドッグをリセットするだけ、色は変わらない
andon-light --port /dev/ttyACM0 set working      # 自動検出が違うポートを選んでしまう場合に、手動でポートを指定する
andon-light install-hooks                        # Claude Codeとの連携をセットアップする（デフォルト）
andon-light install-hooks --agent codex          # 代わりにCodex CLIとの連携をセットアップする
andon-light install-hooks --yes --scope global   # 同上、確認プロンプトなしで実行する

install-hooks は、何かを変更する前に必ず変更内容をそのまま表示し、確認を求めます。適用範囲もグローバルか、プロジェクト単位かを選べます。すでにカスタマイズ済みのフックを上書きしてしまいそうな場合は、事前に警告が表示されます。--agent で、どちらの連携を設定するか選べます。

どちらのエージェントも、同じファームウェアと同じ通信プロトコルで動いています。違うのはパソコン側で動くソフトだけで、デバイス側には何の違いもありません。

デバイスの見つけ方

このツールは、特定のUSBベンダーID（0x2E8A）に一致するデバイスを探します。これはこのボードのチップファミリーが使っているIDなので、通常はポートを意識しなくても自動的にデバイスを見つけられます。

違うデバイスが選ばれてしまう場合や、何も見つからない場合は、--port フラグまたは ANDON_LIGHT_PORT 環境変数で上書きできます。

「device or resource busy（デバイスまたはリソースがビジー状態）」というエラーが出た場合、たいていは他のプログラムがすでに接続を開いたままにしていることが原因です：特に多いのが、バックグラウンドで起動したままのArduino IDEのシリアルモニタです。接続は同時に1つのプログラムしか使えません。このツールは失敗するまで約0.5秒間自動的に再試行し、それでも失敗した場合は、生のエラー表示ではなく短い1行のメッセージと0以外の終了コードを返します。