Claude CodeはRaspberry Piで動く?GPIOでLEDとボタンを制御する手順

Claude CodeでRaspberry PiのGPIOを制御するとは

Claude CodeはRaspberry Pi(ラズパイ)上でも動きます。条件は4GB以上のRAMと64bit版のOSで、Raspberry Pi 4・Raspberry Pi 5の4GB以上のモデルが対象です。ハードウェア要件はx64またはARM64プロセッサーと4GB以上のRAMで、対応OSにはDebian 10+とUbuntu 20.04+が含まれます。Raspberry Pi OSはDebianをベースにしているため、64bit版を使っていればOSの要件は満たします。

この記事では、Raspberry Pi公式が使い方を案内しているPythonライブラリ「GPIO Zero」を使います。Claude CodeにLED点灯・ボタン入力・両者の組み合わせを書かせる手順に加えて、実際に手を動かすとつまずく3点を扱います。Claudeには配線が見えないこと、コールバック式のスクリプトはそのままだと即終了すること、Pi実機がなくても動作を確かめられることです。

Raspberry Pi 5・4で動く条件と対象モデル

Claude Codeのハードウェア要件は、4GB以上のRAMとARM64プロセッサーです。これを満たすのは、主にRaspberry Pi 4 Model BとRaspberry Pi 5のうち、RAMが4GB以上のモデルです。どちらも64bit対応のARMプロセッサーを積んでおり、64bit版Raspberry Pi OSと組み合わせれば要件を満たします。32bit版のRaspberry Pi OS(armhf)はARM64ではないため、Claude Codeの対象外です。RAMが4GB未満のモデル(Pi 3以前、Pi Zero、2GB版のPi 4・5)も要件を下回ります。

GPIO Zeroは、Raspberry Pi OSのデスクトップ版とLite版のどちらにも標準で入っています。入っていない環境ではsudo apt install python3-gpiozeroを実行します。pipで入れる場合、Raspberry Pi OS Bookworm以降ではシステム全体へのインストールがエラーになります。そのため仮想環境(venv)の中でpip install gpiozeroを実行します。

手順1: Claude CodeをRaspberry Piにインストールする

Raspberry Pi OSはDebianベースのLinuxなので、公式のネイティブインストーラーが使えます。

curl -fsSL https://claude.ai/install.sh | bash

ネイティブインストールはバックグラウンドで自動更新される点が特徴です。apt・dnf・apkによるLinuxパッケージマネージャー経由のインストールも選べます。ただしその場合は自動更新されないため、claude updateまたは各パッケージマネージャーのアップグレードコマンドで手動更新します。インストール方法ごとの違いやnpm経由のインストール手順はClaude Code install完全ガイドにまとめています。

インストール後、GPIO制御スクリプトを置くディレクトリでターミナルを開いてclaudeを起動します。

claude

配線を先に決めてからClaudeに伝える

Claude Codeにはブレッドボード上の配線が見えません。指示文にピン番号と部品のつなぎ方を書かないと、コード中のピンが実際の配線と一致する保証はありません。この記事の例では、次の配線を前提にしています。

GPIO2はI2Cのデータ線でもあります。I2C接続のセンサーと同時に使う設計では、ボタンを別のGPIOへ移します。

手順2: LEDを点灯させるスクリプトを書かせる

まずは動作確認を兼ねて、GPIO17に接続したLEDを1秒間隔で点滅させるスクリプトをClaude Codeに書かせます。「GPIO Zeroを使ってGPIO17のLEDを1秒間隔で点滅させるPythonスクリプトを書いて」と指示すると、次のようなコードが返ってきます。

from gpiozero import LED
from time import sleep
 
led = LED(17)
 
while True:
    led.on()
    sleep(1)
    led.off()
    sleep(1)

LEDオブジェクトにはon()・off()・toggle()・blink()のメソッドがあります。ThonnyのようなIDEと組み合わせなくても、python3 blink.pyとターミナルから直接実行できます。

手順3: ボタンの状態を読み取るスクリプトを書かせる

次はGPIO2に接続したボタンの状態を読み取るスクリプトです。「GPIO2のボタンが押されたかどうかを1秒ごとに表示するスクリプトを書いて」と指示すると、次のようなコードになります。

from gpiozero import Button
from time import sleep
 
button = Button(2)
 
while True:
    if button.is_pressed:
        print("Pressed")
    else:
        print("Released")
    sleep(1)

Buttonオブジェクトはis_pressed・is_heldのプロパティを持ちます。加えてwhen_pressed・when_released・when_heldのコールバックや、wait_for_press()・wait_for_release()のメソッドも使えます。ポーリングでなくイベント駆動で書きたい場合は、次の手順のようにコールバックを使う形に書き換えられます。

手順4: ボタンでLEDを制御する

LEDとボタンを組み合わせ、ボタンが押されている間だけLEDを点灯させるスクリプトです。「GPIO2のボタンを押している間だけGPIO17のLEDを光らせるスクリプトを、コールバックを使って書いて」と指示します。返ってきたコードに次のpause()の2行がなければ、足すよう伝えます。

from gpiozero import LED, Button
from signal import pause
 
led = LED(17)
button = Button(2)
 
button.when_pressed = led.on
button.when_released = led.off
 
pause()

ポーリングループを自分で書かずに、ボタンの状態変化をコールバックとしてLEDのメソッドへ直接割り当てるだけで動きます。コードはwait_for_press()で待つ書き方より短く、他のセンサーを同時に扱う構成にも広げやすくなります。

pause()が要るのは、Pythonスクリプトが最後の行に達するとプロセスが終了し、GPIOがリセットされることがあるためです。GPIO Zeroのレシピ集も、signal.pause()でスクリプトを生かし続けるよう注記しています。Raspberry Pi公式のコールバック例はpause()を含まないため、同じコードをpython3で実行すると、コールバックを登録した直後に終了します。pause()が省かれたコードが返ってくることもあるので、実行前に末尾を確認します。

Pi実機なしでスクリプトを検証する

配線前のコードや、Pi以外のマシンで書いたコードは、GPIO Zeroのモックピン(MockFactory)で動作を確かめられます。環境変数GPIOZERO_PIN_FACTORY=mockを付けて実行すると、偽のピンが使われます。Claude Codeに「GPIOZERO_PIN_FACTORY=mockで実行して、ボタンを押したときのLEDの状態を確かめて」と頼めば、実機をつながなくてもコールバックの結線ミスを先に拾えます。

手順4と同じコールバックに、button.pin.drive_low()でボタンを押した状態を作るテストコードを足します。

button.pin.drive_low()   # GPIO2がGNDにつながった状態
print(button.is_pressed, led.is_lit)
button.pin.drive_high()  # ボタンを離した状態

Claude Code v2.1.287を入れたmacOSで、GPIO Zero 2.0.1の仮想環境を作って実行した出力です。

GPIOZERO_PIN_FACTORY=mock python3 test_button_led.py

pull_up: True | 起動直後 is_pressed: False led: False
押下後   is_pressed: True led: True
解放後   is_pressed: False led: False
pin factory: MockFactory

ボタンを押した状態(ピンがLow)でis_pressedがTrueになり、LEDが点灯し、離すと消えることが分かります。上のプルアップの説明と同じ挙動です。

モックを付けずに同じスクリプトをPi以外で実行すると、次のエラーで止まります。gpiozero.exc.BadPinFactory: Unable to load any default pin factory!

GPIO Zeroはlgpioなどのピンドライバーを介してピンを扱います。優先のドライバーを読み込めないと警告を出し、順に別のドライバーを試します。

モックでは電気的な挙動(電流・チャタリング)までは再現されません。LEDの明るさやボタンのバウンスは、実機で確認します。

配線と電圧で気をつけること

GPIOピンは出力に設定すると3.3Vまたは0Vになり、入力に設定すると同じく3.3Vまたは0Vとして読み取られます。5Vピンと3.3Vピンは2本ずつあり、残りの汎用ピンはすべて3.3V仕様で、入力は3.3V耐性です。5V出力の部品を直接つなぐと仕様を超えるので、レベル変換を挟みます。モーターのような大電流の部品もGPIOピンに直結せず、Hブリッジ回路やモータードライバーを経由させます。

GPIOポートを使うには、ユーザーがgpioグループに所属している必要があります。デフォルトユーザーは最初から所属していますが、別ユーザーで作業する場合は次のコマンドを実行します。

sudo usermod -a -G gpio <username>

反映には、一度ログアウトしてログインし直します。Claude Codeにこの種の管理系コマンドを実行させる場合、Manualモードでは、読み取り専用の組み込みコマンド以外のシェルコマンドに確認プロンプトが挟まります。sudoのパスワード入力はClaudeのシェルからは対話できないため、このコマンドは自分のターミナルで実行するほうが確実です。複合コマンドの権限判定の仕組みはClaude CodeのBash権限ルールは複合コマンドをどう評価するかで扱っています。

ピン番号は物理的な並び順になっていません。GPIO0とGPIO1は物理ピン27・28に実在しますが、上級者向けの用途に予約されています(I2C EEPROM用の線です)。「GPIO17」のような番号は40ピンヘッダーの位置とは別の論理番号なので、pinoutコマンドで配置図を表示して物理位置を確かめます。pinoutはGPIO Zeroが提供するコマンドです。

世代で変わる電流とプルの抵抗値

出力電流の目安は、モデルの世代で変わります。旧世代(BCM2835・BCM2836・BCM2837・RP3A0、Raspberry Pi Zeroや3+など)と、BCM2711の4シリーズを並べます。公式ページが対象にしているのはこの2系統だけで、Raspberry Pi 5の値は載っていません。Pi 5にこの値をそのまま当てはめないでください。

上の2つの枠の電流値は「その電流までは出力電圧が仕様を満たす」という保証値です。パッド側が電流を制限するわけではなく、ピンを短絡すると内部抵抗で決まる電流まで流れます。公式の「GPIO pads control」ページは、電気部品は16mAを前提に設計されていて、16mA以内なら破損しないとしています。16mAを超えた場合の安全な最大電流は保証されていません。同じページには、3.3V電源は1ピンあたり最大約3mAを想定して設計されているとも書かれています。全ピンに16mAを流すと合計272mAになり、電源が不安定になってSDカードやSDRAMの動作に干渉するおそれがあるとも説明されています。LEDを何本も直接駆動する設計では、この点に注意します。

代替機能のピン

GPIO12・GPIO13・GPIO18・GPIO19はハードウェアPWMに対応しており、GPIO ZeroのPWMLEDと組み合わせるとLEDの明るさを0〜1の値で変えられます。lgpioなどのピンドライバーが入っていれば、ソフトウェアPWMは全ピンで使えます。I2CはGPIO2(データ)とGPIO3(クロック)に割り当てられています。SPI0はGPIO10(MOSI)・GPIO9(MISO)・GPIO11(SCLK)・GPIO8(CE0)・GPIO7(CE1)です。

対話セッションと-pモードの使い分け

配線やコードを試行錯誤しているあいだは対話セッションのままで十分ですが、GPIO制御スクリプトをRaspberry Pi上で常時稼働させる自動化まで進めると、用途によって向くモードが変わってきます。

-pモードでcronから定期実行する場合の例です。

claude -p "gpio_check.pyを実行してセンサー値をログに追記して" \
  --permission-mode dontAsk \
  --allowedTools "Bash(python3 gpio_check.py)"

-pで権限モードを指定しないと、開始時の権限モードは環境に依存します。公式ドキュメントでは、機能フラグを取得するセッションはdefault(Manual)とされています。取得しないセッション(サードパーティープロバイダーやテレメトリー無効の環境)では、v2.1.285以降がauto、それ以前はdefaultです。無人実行で結果を固定したいなら、--permission-modeを毎回明示します。

claude --help(v2.1.287)には、--permission-modeの選択肢が6つ表示されます。acceptEdits・auto・bypassPermissions・manual・dontAsk・planです。manualはdefaultの別名で、v2.1.200以降で使えます。

-pモードのフラグや終了コードの扱いはClaude Code -pモードでスクリプトやパイプラインを自動化する基本にまとめています。--permission-mode自体の値と優先順位はClaude Codeの--permission-modeで起動モードを指定するで扱っています。

よくあるつまずき

PinFactoryFallbackの警告が出て、PWMが使えない: 仮想環境にlgpioなどのピンドライバーを入れ忘れると、GPIO Zeroは警告を出して別のドライバーへ切り替えます。最後はGPIO Zero内蔵のnative実装になり、PWMは使えず、処理も一部が遅くなります。仮想環境の中でpip install lgpioを実行します。

ボタンを一度押しただけで複数回反応する: Buttonのbounce_timeの既定値はNoneで、ソフトウェアによるバウンス補正が無効です。反応が重なるときは、Button(2, bounce_time=0.05)のように秒数を指定します。

when_heldがすぐには呼ばれない: when_heldが呼ばれるのは、押してからhold_time秒(既定1秒)が過ぎた後です。hold_repeatが既定のFalseなら、押し続けても1回だけです。押している間は繰り返したいときはhold_repeat=Trueを指定します。

まとめ

Claude CodeにGPIOのコードを書かせるときは、ピン番号の体系と配線を指示文に含めたかどうかで、返ってくるコードの当たり外れが決まります。コールバックの結線はモックピンで先に確かめられ、実機で見るのは電流と配線に絞れます。無人で動かす段階に進むなら、-pモードでは権限モードを毎回明示します。