組み立てガイド

ハードウェアを最初から最後まで組み立てます：ハンダ付けの経験がなくても大丈夫です。

このページでは、必要なソフトウェアのインストールから、実際にライトが点灯するのを確認するところまでを順番に説明します。ハンダ付けをしたことがなくても心配いりません：完成済みの基板を使う場合、自分でハンダ付けする部品はひとつだけで、見た目ほど難しくありません。

部品表を先に見たい方はBOM（部品表）へどうぞ。

1. ソフトウェアをインストールする

ハードウェアに触れる前に、パソコンとボードを通信させるためのツールをインストールします。

  1. Arduino IDE（バージョン2.x）をインストールします。これは、ファームウェア（ボード上で直接動くプログラム）を書き込むために使うアプリです。
  2. このボードのチップに対応させます。
    • Arduino IDEの環境設定で「追加のボードマネージャのURL」に arduino-pico のボードパッケージURLを追加します。
    • ボードマネージャを開き、「Raspberry Pi Pico/RP2040」をインストールします。
    • ファームウェアを書き込む際は、ボードとして 「Waveshare RP2040-Zero」 を選びます：これがこのデバイスで使われている実際のチップです。
  3. Adafruit NeoPixel ライブラリをインストールします（ツール → ライブラリを管理 → 「Adafruit NeoPixel」で検索してインストール）。これはLEDと通信するためのライブラリです：LEDには非常に精密なタイミング制御が必要で、単純なオン・オフの命令だけでは動きません。

2. ハードウェアを組み立てる

まだ基板を持っていない場合は、まず下記で基板を製造するところから始め、その後完成済み基板をお持ちの場合に進んでください。すでに基板を持っている場合や、まだ基板を用意せずに動作確認だけしたい場合は、次の2つのセクションのどちらか一方に直接進んでください。どちらか一方だけで構いません。

自分で基板を製造したい場合

すでに完成済み基板をお持ちの場合や、ブレッドボードで試作するだけの場合（下記参照）は、このセクションは飛ばして構いません。

実際に基板を製造するために必要なものは、すべてGitHub上のハードウェアフォルダにあります。

  • KiCadプロジェクト： このボードの設計そのものに使われた無料のツール（KiCad）で開ける、実際の設計データです。自分で設計内容を確認したり変更したりしたい場合に開いてください。そうでなければ開く必要はありません。
  • ガーバーファイル： 基板製造サービスに「何を作るか」を正確に伝えるための製造用データ一式です。中身を開いたり理解したりする必要はありません。フォルダごと基板製造サービス（このプロジェクトではJLCPCBを利用しました）にアップロードすれば、部品表で説明されている通り、マイコン以外のすべてがハンダ付け済みの基板が届きます。
  • 筐体データ： 3Dプリントケース用の、そのまま出力できるデータです。3Dプリントサービスや自分のプリンターに使えます。

基板が届いたら、続けて下記に進んでください。

完成済み基板をお持ちの場合

こちらが簡単な方法で、ほとんどの方はこちらになります。完成済みの基板にはメーカーによってLEDや小さな部品がすでに実装済みです。自分で取り付けるのは、小さなマイコンボード（すべての処理を行うチップ、RP2040-Zero）だけです。

  1. RP2040-Zeroをボードにハンダ付けします。ボードの縁には半円形の切り欠き（「キャステレーションパッド」と呼ばれます）が並んでおり、基板側の対応するパッドと合わせて使います。それぞれをハンダ付けしてください。これらの接続の中には電源やデータを流すものもあれば、単にチップを機械的に固定するためだけのものもありますが、まとめて全部ハンダ付けしてしまうのが一番簡単です。
RP2040-Zeroを基板にハンダ付けした状態を角度を付けて見たCAD図。半円形の切り欠き（ハンダ付け箇所）を矢印で示しており、小さな上面図も添えられている

ハンダ付けに慣れていない方へ、いくつかコツを紹介します。ハンダ付けした直後は数秒待ってから触ること、そして隣り合う2つのパッドをひとつのハンダの塊でつなげてしまわないこと。もしブリッジしてしまっても、再加熱してハンダをもう少し足してから分離させたり、ハンダ吸い取り線で余分なハンダを取り除いたりすれば直せます。

これで組み立ては完了です：ケーブルの接続も配線作業も必要ありません。チップとLEDの間の接続は、基板自体にすでに組み込まれています。ハンダ付けが終わったら、書き込みと確認に進んでください。

ブレッドボードで試作する場合

上の完成済み基板での組み立てをすでに終えた方は、このセクションは読み飛ばしてください。この方法は、むき出しのRP2040-Zeroを別売りのLEDテープに手作業で配線して、ファームウェアを試すためのものです。完成済み基板をまだお持ちでない場合や、購入前に試してみたい場合に便利です。

  1. RP2040-Zeroにピンヘッダをハンダ付けします。 購入時はピンが付いていない状態で、半円形の切り欠きが並んでいるだけです。少なくとも3本：5V、GND、そしてGPIOピン1本（ファームウェアの初期設定では 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ケーブルは、3本すべての配線が終わってから接続してください。配線が半端な状態で電源を入れると、ショートのリスクがあります。
    • 任意ですが、小さな抵抗とコンデンサを追加すると信号が安定しやすくなります。ちらつきが気になる場合はBOM（部品表）の項目8〜9を参照してください。

3V3 ピンでは10個のLEDに十分な電流を供給できません。V を 5V ではなく 3V3 に接続してしまうのは、この組み立てで最もよくある配線ミスです。

配線が終わったら、書き込みと確認に進んでください。

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 と入力し、それぞれエンターキーを押します。入力するたびに、対応する3個ずつのLEDグループ（2-4番目、5-7番目、8-10番目）だけが点灯するはずです。テープ全体が光るわけではありません。

ここまでうまくいけば、デバイスは正常に動作しています。次は、コーディングエージェントの状態を追いかけられるように、ホスト側のソフトウェアをインストールしましょう。プロジェクトのGitHubページにあるクイックスタートをご覧ください。

リファレンス

用語の説明

用語意味
MCU（マイコン）実際にファームウェアを動かす小さなチップのことです。このボードでは、RP2040-Zeroに内蔵されているRP2040がそれにあたります。
ファームウェアMCU自体の上で動くプログラムです。パソコン上で動くものではありません。
開発ボードチップ、USBポート、電源まわりの回路があらかじめ組み込まれた、すぐに使える小さな基板のことです。RP2040-Zeroもそのひとつです。
アドレサブルLED（WS2812）たくさん数珠つなぎにしても、1本の信号線だけでLEDそれぞれに個別の色を指定できるLEDです。これによって、3個ずつのLEDグループごとに異なる色を独立して表示できます。
NeoPixelこのLEDファミリーにAdafruitが付けた名前で、それを制御するライブラリの名前でもあります。
ウォッチドッグファームウェアに組み込まれた安全装置用のタイマーです。しばらくパソコンから応答がないと、ライトを「何か問題が起きている」状態に切り替えます。詳しくは下記の通信プロトコルのリファレンスを参照してください。
PCBA「PCBアセンブリ」の略で、部品がすべてハンダ付けされた状態の基板のことです。

LEDの並び方

LED意味点灯させるコマンド
1常時点灯する「起動中」のサインなし：常に薄い白色で点灯しています
2–4作業中G コマンド
5–7あなたの対応待ちY コマンド
8–10アイドルR コマンド、または接続が途切れた場合
状態見た目
作業中（G）LED 2-4が緑色に点灯
対応待ち（Y）LED 5-7が黄色に点灯
アイドル（R）LED 8-10が赤色に点灯
接続が途切れた状態LED 8-10が赤色でゆっくり明滅（点灯したままではなく）
コンパクト中（C）順次点灯パターン：LED 10からLED 2へ向かって1個ずつ点灯していき、最後にリセットして繰り返します

LED 1は、デバイスの電源が入っている間、常に薄い白色で点灯し続けます。もし10個すべてのLEDが同時に同じ色で点灯した場合は、古いバージョンのファームウェアが書き込まれているサインです：最新のソースから書き込み直してください。

よくある間違い

症状原因
V を 3V3 に接続してしまっている（5V ではなく）ブレッドボード配線の場合のみ。これは最もよくある配線ミスです：10個のLEDには 3V3 が想定している以上の電流が必要です。
電源投入直後にちらつく、または色がおかしいファームウェアの不具合ではなく、たいていは接続が不安定なことが原因です。完成済み基板の場合は、ハンダ付けが冷えて固まりきっていない箇所がないか確認してください。ブレッドボードの場合は、トラブルシューティングページの信号関連の項目を参照してください。
配線が違う穴に刺さっているブレッドボード配線の場合のみ。写真やこのガイドを鵜呑みにせず、LEDテープのコネクタ自体に印刷されている小さなラベルを確認してください。必ずお手元の基板の実際の表記と照らし合わせましょう。
USB接続しても何も起きない一部のUSB-Cケーブルは電源専用で、データ通信に対応していません。まずは別のケーブルを試してください。
シリアルモニタでの確認を省略してしまうひと手間に感じるかもしれませんが、やっておく価値があります。ソフトウェア側の問題を追加する前に、ファームウェア側の問題かパソコン側の問題かを切り分けられます。
ライトが固まって動かない・更新されないClaude Codeとの連携は決まったタイミングでしか状態を確認しないため、ツール呼び出しのない思考だけの時間が長く続くと、ウォッチドッグが一時的に更新されないことがあります。これは想定内の動作で、自然に解消します。詳しくは上記の通信プロトコルの表を参照してください。

ウォッチドッグとハートビートは、単なるおまけ機能ではありません：安心してその場を離れられる、信頼できるライトにするための土台です。

お使いのOSについて

OS動作
Windows追加のドライバなしで、自動的にCOMポートとして認識されます。
Linux/dev/ttyACM0（または似た名前）として認識されます。アクセスするには、ユーザーアカウントを dialout グループに追加する必要があります。権限エラーが出た場合はトラブルシューティングページを参照してください。

通信プロトコルのリファレンス

パソコンからデバイスへUSB経由で送られる、1文字だけのコマンド一覧です。

コマンド効果意味
G緑色に点灯エージェントが作業中
Y黄色に点灯権限確認や入力など、あなたの対応待ち
R赤色に点灯アイドル、停止、または新しいセッションの開始直後
C順次点灯パターン内部整理中（「コンパクト中」）：ライトは点いたまま、片付け作業をしているだけです
H見た目の変化なしハートビート：ウォッチドッグタイマーをリセットするだけです

30分間パソコンから応答がない場合、デバイスは接続に問題が起きたと判断し、それまでの色のまま固まるのではなく、自動的にゆっくり明滅する赤色のパターンに切り替わります。