HN 日本語サマリー

← 一覧へ戻る
AI・機械学習

Show HN: Strands Agents を使用した AI パワードの Big Mouth Billy Bass、BillAI Bass

Show HN: BillAI Bass, an AI-Powered Big Mouth Billy Bass Using Strands Agents (github.com)

56 pointsby mtw1425 コメント

要約

本プロジェクトは、Big Mouth Billy Bass をリアルタイム音声アシスタントに変身させる方法を解説しています。Raspberry Pi 5 と Amazon Bedrock 上の Amazon Nova 2 Sonic を Strands Agents の双方向ストリーミングエージェントと連携させ、話すと魚がそれに反応して頭を動かし、口を動かし、尻尾を振って強調する仕組みを実現します。ロボット工学やハンダ付けの経験がなくても、週末で完成させることが可能です。

全文翻訳

🐟 BillAI Bass ビルダーガイド

Strands Agents 双方向ストリーミング + Amazon Nova 2.5 Sonic 搭載

billai-bass-demo-strands.mp4[動画]

Big Mouth Billy Bassをリアルタイム音声アシスタントに変身させましょう。あなたが話すと、魚がそれに答えます。頭を振り、口は自身の声に合わせてリップシンクし、尻尾は強調のためにパタパタと動きます。この魚はRaspberry Pi 5上でStrands Agentsの双方向ストリーミングエージェント(BidiAgent)を実行し、Amazon Bedrock上のAmazon Nova 2.5 Sonicとライブオーディオを送受信します。

ロボット工学の経験は不要です。はんだ付けの経験も不要です。このガイドの基になった人物は、Raspberry Piを一度も接続したことがありませんでしたが、週末で話す魚を作り上げました。

優れたbilly-b-assistantプロジェクトに触発され、Strands上で再構築しました。

このリポジトリに含まれるもの

ファイル内容
README.mdこのガイド — ここから始めて、上から下へ作業してください
billy.py最終的な動作Pythonコード — 話す魚
billy_openai.py代替ブレイン:Nova 2.5 SonicではなくOpenAI Realtimeで動作する同じ魚
billy_tools.pyBillyのアシスタントツール — 天気、ニュースヘッドライン、(オプションで)Googleカレンダー + Gmail
google_setup.py読み取り専用スコープでの1回限りのGoogle OAuthセットアップ;トークンをAWS Secrets Managerに保存可能
motors.py独立したモーターテストリグ — billy.py の前に実行して配線を確認してください
asoundrc.exampleUSBマイク + スピーカーをデフォルトとして固定するALSA設定ファイル
requirements-frozen.txt既知の良好なPiビルドからの正確な依存関係バージョン — 確実に動作するセットアップのために pip install -r を実行してください
iot-identity/オプション 本番グレードの認証情報:X.509証明書認証のためのCloudFormationテンプレート + ウォークスルー(アクセスキーの代わりに)

AIアシスタントでこれをどう使うか

このREADMEをClaude(または他のAIアシスタント)に貼り付けて、「これを構築しています。1ステップずつ案内してください — 次のステップに進む前に、私が確認するのを待ってください。」と言ってください。それが構築された方法であり、それが最も良く構築される方法です。行き詰まった場合に送信する内容については、下のAIアシスタントと一緒にこれを構築するセクションを参照してください。


🤝 AIアシスタントと一緒にこれを構築する

このプロジェクトはClaude Codeの助けを借りて作成されました。AIアシスタントを使えば、誰でもこれを乗り越えることができます。

このガイド全体をAIに貼り付けて、「これを構築しています。1ステップずつ案内してください — 次のステップに進む前に、私が確認するのを待ってください。」と言ってください。

AIは、ビルドをあなたに合わせてペース配分し、あなたの正確なエラーメッセージをデバッグし、ハードウェアがこのガイドとわずかに異なる場合に適応します。このビルド中にAIが得意とすること:

  • 正確なエラーメッセージを貼り付ける — 恐ろしい50行のPythonトレースバックには、通常1つの意味のある行があり、AIが見つけます。
  • 写真を送信する — モーターを特定できずに困っていますか?どのピンがどれかわかりませんか?写真を撮って尋ねてください。(Mac上のClaude Codeで:画像をターミナルにドラッグするか、「~/Downloads/IMG_1234.jpgを見て」と言います。)
  • 「Xについて何も知りません」と言う — AIはバックアップして説明します。愚かな質問はありません。
  • 何かを切断/はんだ付けする前に尋ねてください。

このガイドでカバーされていないことに遭遇した場合、それはあなたの失敗ではありません。それはおそらくガイドのギャップです。AI + あなたのエラーメッセージがあなたを乗り越えさせます。


🛒 ショッピングリスト

キットを入手した場合は、この表のすべてをすでに持っています。 スクラッチから構築する場合:これは元のAmazon注文(2026年1月の価格、合計約240ドル)です。

アイテム用途約価格
Big Mouth Billy Bass (現在の「Gemmy」バージョン)魚。現代版には2つのモーターがあり、このガイドはそれを想定しています$30
Raspberry Pi 5, 8GB頭脳。4GBでも動作します$80
27W USB-C PD電源アダプター(公式PiまたはRasTech GaN)電話充電器で代用しないでください — Piは適切な供給がないとUSBポートへの電力を制限します$15
公式Raspberry Pi 5アクティブクーラーヒートシンク + ファン。これがないとPiは熱くなります$10
MicroSDカード, 64GB (例: Transcend USD340, ブランド品なら何でも)Piのハードドライブ
USBミニスピーカー (例: HONKYOB)Billyの声
USBグースネックミニマイク (例: CGS-M1)Billyの耳
MX1508デュアルHブリッジモータードライバー, 5個パック (例: Aideepen、「L298N交換」として販売)Piがモーターを安全に駆動できるようにします。1つ必要です。予備は間違いを許容します$9
デュポンジャンパーワイヤーキット, 120本オス/メス混合 (例: ELEGOO)ドライバーボードをPiに接続します。約6本のメス-メスを使用します$7
はんだごてキット, 60W調整可能(チップ付き)+ はんだ合計10箇所のはんだ付け。最も安いキットで十分です$20
フラッシュカッター (例: KATA 2個パック)ワイヤーの切断と剥ぎ取り
JST XHコネクタキットオプション — きれいな接続に便利ですが、ビルドはこれなしでも動作します$9

キットに含まれていないもの:

  • SDカードをフラッシュするためのパーソナルコンピューター(Mac/Windows/Linux) — ⚠️企業用ラップトップはUSBストレージをブロックすることがよくあります。自宅のマシンを使用してください。
  • そのコンピューターにmicroSDを接続する方法(ほとんどのカードにSDアダプターが含まれています)
  • AWSアカウント(個人のもの、雇用主のものではない)と支払い方法 — 以下の前提条件で、ロックダウンされた魚専用のIAMユーザーを作成します。
  • テープ(できれば絶縁テープ、セロハンテープでも可)、小さなプラスドライバー
  • コンピューターとPiの両方が接続できるホームWiFi

✅ 前提条件(ビルド前にこれらを完了してください)

1. AWS / Amazon Bedrock セットアップ(最小権限 — 正しく行う)

💸 まだAWSアカウントをお持ちでない場合:無料枠でこのプロジェクトはカバーされます。 新規AWSアカウントには100ドルのクレジットが付与され(アクティビティで最大200ドル)、Amazon Bedrockは無料プランでクレジットをNovaの使用量に適用して利用できます。音声チャットは安価で、会話数分あたり約1セントなので、クレジットで100時間以上の魚との会話が可能です。無料プランの注意点2つ:

  • 新規アカウントでは、Bedrock呼び出しクォータがゼロに設定されている場合があります(まだ支払い履歴がないため)。モデルアクセスは許可されていても、すべての呼び出しが ValidationException: Operation not allowed で失敗する場合、それはクォータです — (無料の)AWSサポートケースにNova Sonicオンデマンドクォータを要求するか、有料プランにアップグレードしてください(残りのクレジットは引き継がれます)。
  • 無料プランのアカウントは6ヶ月後(またはクレジットが尽きたら)に自動的に閉じられます。デモ魚としては問題ありません。Billyが永続的な同居人になる場合は、期限前に有料プランにアップグレードしてください — 未使用のクレジットはアップグレード後も有効です。

AWSキーは、魚の中のPi上のプレーンテキストファイルに保存されます。魚はデモされたり、貸し出されたり、机の上に置かれたりします。SDカードは取り外されます。したがって、キーは正確に1つのことしかできない必要があります:Nova Sonicと通信すること。漏洩した場合、最悪のシナリオは、誰かがあなたの費用で魚とチャットすることです — あなたのアカウントで仮想通貨をマイニングする人ではありません。

ステップ1 — モデルアクセスを有効にする:

  1. AWSコンソールで、リージョンをus-east-1(N. Virginia)に切り替えます — Nova Sonicはそこにあります。
  2. Amazon Bedrock → モデルアクセスに移動し、Nova 2.5 Sonic(amazon.nova-2-5-sonic)へのアクセスをリクエストします。通常は即時です。(元のNova Sonicではありません — それは2026年9月にEOLを迎えました。)

ステップ2 — 専用IAMユーザーを作成する:

  1. コンソール → IAM → ユーザー → ユーザーを作成。billy-bass のような正直な名前を付けます。
  2. 「AWSマネジメントコンソールへのユーザーアクセスを提供する」にチェックを入れないでください — このユーザーはロボット魚であり、決して何もログインしません。
  3. 権限画面で、「ポリシーを直接アタッチする」を選択しますが、AWS管理ポリシーは選択しないでください(AmazonBedrockFullAccess は魚が必要とする以上の権限を付与します)。単にクリックして、権限ゼロでユーザーを作成します。

ステップ3 — Nova Sonicのみを許可するポリシーをアタッチする:

  1. 新しいユーザーを開く → 権限 → 権限を追加 → インラインポリシーを作成 → JSONタブ。

  2. 貼り付け:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "BillyTalksToNovaSonicOnly",
          "Effect": "Allow",
          "Action": [
            "bedrock:InvokeModelWithBidirectionalStream",
            "bedrock:InvokeModel"
          ],
          "Resource": "arn:aws:bedrock:us-east-1::foundation-model/amazon.nova-2-5-sonic"
        }
      ]
    }
    
  3. billy-nova-sonic-only という名前を付け、保存します。

これは1つのリージョンにある1つのモデルです。(なぜ2つのアクションか? Nova Sonicの双方向ストリームは、両方をインバンドで承認します — ストリーミングのみを許可すると接続が開きますが、ストリーム途中で AccessDeniedException で終了します。)S3、EC2、他のBedrockモデル、アカウント内の他のものを表示または変更する能力はありません。(後でBillyにAWSに触れるツール(例:DynamoDBテーブルの読み取り)を与える場合は、その特定の権限を今すぐではなく、このポリシーに追加してください。)

ステップ4 — アクセスキーを作成する:

  1. ユーザー → セキュリティ認証情報 → アクセスキーを作成 → 「AWS外で実行されるアプリケーション」を選択します。
  2. アクセスキーID + シークレットを安全な場所にコピーします — シークレットは一度だけ表示されます。これらは後でPiに配置します(§1.6)。

ステップ5 — オプションだが賢明:請求アラームを設定する。 コンソール → 請求 → 予算 → 月額10ドルの予算を作成し、メールアラートを設定します。カジュアルなNova Sonicチャットは数セントで済みます。アラームは、応答し続ける魚(または漏洩したキー)があなたを驚かせないようにするためのものです。

キーが漏洩したり、キットの魚が行方不明になった場合:IAM → ユーザー billy-bass → セキュリティ認証情報 → アクセスキーを無効化します。ワンクリックで魚は動作不能になり、アカウントは安全です。

2. 2つの貼り付けの落とし穴を知る(これに遭遇するでしょう)

ターミナル/nanoにコードをSSH経由で貼り付けると、2つのことがうまくいかなくなります:

  • 余分なインデント:貼り付けられた各行の先頭にスペースが追加されます。ALSA設定は気にしませんが、Pythonはクラッシュします(行1の IndentationError: unexpected indent がその兆候です)。修正:sed -i 's/^ //' yourfile.py、またはnanoに注意深く再貼り付けします。
  • 失われた/破損した文字:カンマの欠落、または引用符が「スマートクォート」に変わる。

あなたを救う習慣:Pythonファイルを作成した後、実行する前に

python -m py_compile yourfile.py && echo OK

を実行します。OKと表示されない場合は、エラーをClaudeに貼り付けてください。


パート1 — 頭脳(Raspberry Pi、まだ魚なし)

戦略ノート: まず、すべての音声アシスタントをベアPiで動作させ、その後で魚を開きます。ソフトウェアの問題とハードウェアの問題は、互いに干渉できない場合にデバッグするのがはるかに簡単です。

1.1 SDカードをフラッシュする

パーソナルコンピューターで:

  1. raspberrypi.com/software からRaspberry Pi Imagerをダウンロードし、microSDカードを挿入します。

  2. 選択:デバイス = Raspberry Pi 5 · OS = Raspberry Pi OS Lite (64-bit) · ストレージ = カード。

    • ⚠️ OSバージョンが重要:Python 3.12+(Nova Sonic要件)を含むイメージが必要です。現在の「Trixie」ベースのRaspberry Pi OSは3.13 ✅を搭載しています。古い「Bookworm」イメージは3.11 ❌を搭載しています。
    • 「Lite」 = デスクトップなし。正しいです — モニターを接続することはありません。
  3. ⚠️ 「Lite」を慎重に選択してください。 OSリストで、「Raspberry Pi OS (other)」を展開し、リストの一番上にある「Raspberry Pi OS (64-bit)」ではなく、Raspberry Pi OS Lite (64-bit) を選択します。デスクトップ版は、ログインごとに~/.asoundrcを積極的に書き換えるWayfireパネルを搭載しており、原因不明のままオーディオ設定を繰り返し壊します。LiteにはGUIもパネルもありません。

    誤ってデスクトップをインストールしてしまった場合? 再フラッシュなしで修正可能です — sudo systemctl set-default multi-user.target && sudo systemctl disable lightdm.service && sudo reboot でデスクトップはLiteのように起動します。しかし、最初からLiteの方がクリーンです。

  4. OSカスタマイズについて尋ねられたら、はいと答えてください — これが魔法のステップです:

    • ホスト名:billy
    • ユーザー名とパスワード:選択して覚えておいてください
    • WiFi:ネットワーク名とパスワードを正確に入力(ここにタイプミスがあると、後で謎の応答なしになります)
    • サービスタブ:SSHを有効にする(パスワード認証)
  5. 書き込み、待機、取り出し。(「Raspberry Pi Connect」プロンプト:スキップしてください — デモをどこかで行う必要がある場合は、後で1つのコマンドでリモートアクセスを追加できます。)

1.2 初回起動

  1. MicroSDカードをPiの底面のスロットに挿入します。USB-C電源アダプターを接続します — 電源ボタンはありません。接続するとオンになります。

  2. 2〜3分待ってください(初回起動時にサイズ変更とWiFi接続が行われます)。

  3. コンピューターのターミナルから:

    ssh yourusername@billy.local
    

    フィンガープリントプロンプトで yes(小文字)を入力し、次にパスワードを入力します(パスワード入力中はカーソルは移動しません — 通常通りです)。

落とし穴:

  • フィンガープリントプロンプトの直後に Connection reset → Piはまだ初回起動セットアップを完了中です。1〜2分待ってから再試行してください。(それでも REMOTE HOST IDENTIFICATION HAS CHANGED と文句を言われたら:ssh-keygen -R billy.local を実行して再試行してください — Piはセットアップ中にキーを再生成しました。これは予期されることです。)
  • billy.local が見つからない → もう少し待ってください。次にルーターのデバイスリストで「billy」を探し、そのIPにSSHしてください。永続的に見つからない場合は、通常WiFiパスワードのタイプミスです → 再フラッシュしてください。
  • その日の作業終了時:sudo shutdown now を実行し、約20秒待ってから電源を抜いてください。単に電源を引っこ抜かないでください。

1.3 システムパッケージ

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y python3-dev portaudio19-dev swig git

(portaudio19-dev → Pythonでのマイク/スピーカーアクセス。swig → 後でGPIOライブラリをビルドするために必要です。今インストールしておくと、混乱するエラーを回避できます。)

1.4 オーディオデバイス

USBマイクとUSBスピーカーをPiに接続し、次に:

arecord -l   # マイクをリスト表示 — カード名(例:「Device」)をメモしてください
aplay -l     # スピーカーをリスト表示 — あなたのものをメモしてください(例:「UACDemoV10」)(2つのvc4hdmiエントリは無視してください)

⚠️ カード番号ではなく、カード名を使用してください — 番号は再起動ごとにシャッフルされます(これは元のビルドでつまずいた点です)。次にUSBデバイスをシステムデフォルトにします。nanoで設定ファイルを作成します(ヒアドキュメント+SSHペーストは面倒です。nanoがあなたの味方です):

nano ~/.asoundrc

貼り付け、あなたの2つのカード名を置き換えてください:

pcm.!default {
    type asym
    playback.pcm "plug:hw:UACDemoV10"
    capture.pcm "plug:hw:Device"
}
ctl.!default {
    type hw
    card UACDemoV10
}

保存(Ctrl+O、Enter)して終了(Ctrl+X)します。次に、ファイルが実際に存在することを確認してください — cat ~/.asoundrc がそれをエコーバックするはずです。(元のビルドでは、このファイルはサイレントに保存に失敗し、数日後に不可解なクラッシュとして現れました。何も信用せず、すべて cat してください。)

往復テスト — 3秒間録音して再生します:

arecord -d 3 -f S16_LE -r 16000 test.wav && aplay test.wav

自分の声が聞こえますか? 最も難しいPi固有の問題はこれで解決しました。(16000 Hzは意図的です — Nova Sonicのレートです。)

音量を設定する — amixer ではなく wpctl を使用します。 ここが落とし穴です:現在のRaspberry Pi OSはLiteでもPipeWire/WirePlumberを搭載しており、WirePlumberは起動から約15秒後に、ALSAのリストアが実行された後で、デバイスごとの音量メモリを保持し、それを再適用します。amixer または alsamixer で音量を設定すると機能し、sudo alsactl store はそれを「保存」するかもしれませんが… 次の再起動でWirePlumberが記憶していたものに静かに戻ります。(これは元のビルドで複数回の再起動デバッグセッションを費やしました。起動ログが物語を語ります:alsa-restore が完了し、14秒後に wireplumber がそれを上書きします。最後に書いたものが勝ちます。)

したがって、最後の書き込み先に話しかけます:

wpctl status        # スピーカーを「Sinks:」の下で探します(例:「59. UACDemoV1.0 Analog Stereo」)
wpctl set-volume 59 0.90    # あなたのシンク番号を使用してください;0.90 = 90%

WirePlumberはこれをデバイスごとに永続化します(~/.local/state/wireplumber/ 内)、したがって再起動後も保持されます — シンクの番号は再起動ごとに変わりますが、設定はデバイスに保持されます。次の再起動後に wpctl status | grep -i <speaker name> で確認してください。(セッション中にライブで調整するには amixer -c <card> sset PCM 90% は依然として有効ですが、永続化されないことを知っておいてください。)

1.5 Python環境 + Strands

python3 -m venv ~/billy/.venv
source ~/billy/.venv/bin/activate
pip install "strands-agents[bidi,bidi-io,bidi-pyaudio]" gpiozero lgpio

注:

  • プロンプトに (.venv) が表示される = venv がアクティブです。新しいSSHセッションごとに source 行を再実行する必要があります — Pythonが突然strandsを見つけられなくなった場合、それが理由です。
  • lgpio が swig に関するビルドエラーで失敗した場合:ステップ1.3のswigインストールをスキップしました。sudo apt install -y swig を実行して再試行してください。
  • このビルドは安定版の strands.bidi API(strands-agents 1.58以降GA)を使用しているため、アップグレードは安全であるはずです — ただし、魚はアプライアンスであり、requirements-frozen.txt は、後で必要になった場合に既知の良好なセットを記録します。
  • Nova SonicサポートにはPython 3.12以降が必要です。現在のRaspberry Pi OS(Debian 13 "Trixie")は3.13を搭載しており問題ありません。古いBookwormイメージは3.11を搭載しており、古すぎます — 最新イメージで再フラッシュしてください。

1.6 AWS認証情報 — エクスポートではなくファイルに保存

前提条件で作成した専用の billy-bass IAMユーザー(Nova Sonicにのみ呼び出し可能なもの)のキーを使用します — 個人のAWSキーやルートキーは絶対に使用しないでください。環境変数はログアウトするたびに消えるため(ビルド中にクラッシュした原因)、永続的に設定します:

mkdir -p ~/.aws
nano ~/.aws/credentials
[default]
aws_access_key_id = YOUR_KEY_ID
aws_secret_access_key = YOUR_SECRET
nano ~/.aws/config
[default]
region = us-east-1
chmod 600 ~/.aws/credentials

1.7 初めての会話 🎉

nano ~/billy/billy.py:

import asyncio
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel

model = BedrockNovaSonicModel(
    model_id="amazon.nova-2-5-sonic",
    voice="matthew",
)

agent = BidiAgent(
    model=model,
    system_prompt=(
        "You are Billy, a wisecracking animatronic singing bass mounted on a "
        "wooden plaque. Keep responses short, punchy, and conversational."
    ),
)

audio_io = AudioIO()

asyncio.run(agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()]))

(オーディオは、魚のUSBハードウェアが要求する16 kHzモノラルPCMの両方向でデフォルト設定されており、オーディオ設定は不要です。)

python -m py_compile ~/billy/billy.py && echo OK
python ~/billy/billy.py

数秒待ってから、話しかけてください。音声会話ができるはずです。 Ctrl+Cで停止します。

落とし穴:

  • 起動時の ALSA lib... の警告の壁は通常のノイズです — Pythonの Traceback 以外のものは無視してください。
  • AccessDeniedException → Bedrockモデルへのアクセスが許可されていないか、リージョンが間違っています。
  • no AWS credentials found → ステップ1.6が実行されていない(またはタイプミスがある)。
  • OSError: Invalid sample rate → ~/.asoundrc が欠落しているか、カード名が間違っています(cat ~/.asoundrc と arecord -l を実行して比較してください)。
  • Billyが途中で自分を遮る → マイクがスピーカーの音を拾い、モデルがあなたが割り込んでいると考えてしまいます。マイクをスピーカーから離し、音量を下げてください。物理的な配置でこれを解決します。(Strandsはエコーキャンセレーションを搭載していますが、マイクとスピーカーが共有クロック上にある必要があります。このハードウェアでは2つの別々のUSBデバイスがずれるため、完全なビルドでは代わりにマイクゲートを使用します。パート4を参照してください。)

パート2 — 体(魚を開く)

2.1 外科手術101

バックプレートの約6本のネジを外します。バッテリーを取り出して、そのままにしておいてください。 中には小さな黒い塊の動物園がありますが、フィールドガイドは以下の通りです:

見た目正体運命
親指サイズの銀色の円筒 + 黒いギアボックス、2本のワイヤーモーター保留
グリル穴のある丸いディスク(バックプレート上)元のスピーカー引退
コインサイズの平たい銀色のディスク、2本のワイヤーピエゾブザー(モーターではない!)引退
すべてのワイヤーが終端する小さなボード元の制御ボード引退
前面のボタンにつながるワイヤープッシュボタン保留(将来の「話しかけて」トリガー)
前面の小さな窓/センサーにつながるワイヤー光/モーションセンサー引退

モーターの数を数えてください。 現代のBilly(現在販売中)= 2つのモーター:1つは口用、もう1つは共有モーターで、片方向に回転すると頭を回転させ、もう片方向に回転すると尻尾をパタパタさせます。クラシックBilly(1999-2005)= 3つの独立したモーター(このガイドは現代版を対象としています。クラシック版については、Claudeに調整を依頼してください — 2つ目のドライバーボードとさらに1つのGPIOピンが必要になります)。

⚠️ 指でワイヤーをたどってください。色を信用しないでください。 エディションによって異なります。元のビルドでは、どちらのモーターがどちらかという「明白な」推測は逆でした — 尻尾の近くに見えるモーターがボディモーターで、口のモーターは頭の近くに埋まっていました。

オプションの確認:魚を閉じた状態でバッテリーを入れたままボタンを押すと、工場出荷時の歌とダンスで両方のモーターが動作することが証明されます。手術前に一度これを行って、安心してください。

2.2 切断とラベル付け

  1. 元のボードからモーターワイヤーとボタンワイヤーを外します — コネクタがあれば外します。そうでなければ、ボードの近くで切断します(保持する側のワイヤー長を最大化します)。
  2. すぐにテープの旗で各ペアにラベルを付けます:MOUTH、BODY、BUTTON。ボードがなくなると、色は唯一のドキュメントになります。
  3. ボード、ピエゾ、スピーカー、センサーを取り外します。ボタンは保持します。

パート3 — 頭脳と体の接続

3.1 モータードライバーについて

PiのGPIOピンはささやく(3.3V信号)ことはできますが、モーターは叫ぶ(実際の電流)必要があります — モーターをPiに直接配線するとピンが壊れます。MX1508ドライバーボードが翻訳者です:Piが入力にコマンドをささやき、モーターに5Vを叫びます。2つのチャンネル(AとB)があり、モーターごとに1つです。便利です。

ボードにはむき出しの穴があるので、ここでのはんだ付けが必要です:合計10箇所のはんだ付けで、最も簡単な種類です。はんだ付けを一度もしたことがない場合は、まず3分間の「はんだ付け方法」ビデオを見てください。ボードは5枚あるので、間違いは無料です。

3.2 ワイヤーの準備

6本のメス-メスデュポンワイヤーを6色の異なる色で用意します。それぞれについて:片方のプラスチック端を切り取り、約5mmの絶縁体を剥ぎ取ります(フラッシュカッターで軽く噛み、スリーブをスライドさせます)、撚り線をきつく撚ります。

このビルドで使用する色のマップ(あなたの色に合わせて調整してください。ただし、あなた自身の記録を書いてください):

ワイヤードライバーの穴用途
黄色+5V電源
黒−グラウンド
白IN1口(一方向)
グレーIN2口(他方向)
紫IN3ボディモーター → 頭
青IN4ボディモーター → 尻尾

3.3 はんだ付け

各ワイヤーについて:むき出しの端を穴の上から(ラベル側を上にして)差し込み、突き出た先端を少し曲げて固定し、ボードを反転させます。次に:はんだごての先端をワイヤーと金属リングの両方に触れさせ、2秒数え、はんだを流し込み、はんだを引っ込め、次に鉄を引っ込めます。ワイヤーを掴む小さな光沢のある円錐形が必要です。

次にモーターワイヤーを出力穴に差し込みます(同じように剥ぎ取り/撚り合わせ/はんだ付けします):

  • 口のモーターペア → MOTOR A の穴
  • ボディモーターペア → MOTOR B の穴
  • (ペア内では、どちらの穴でも構いません — 逆でも方向が逆になるだけで、ソフトウェアで修正できます。)

品質管理 — 各接合部で、すべて3つを確認してください:

  1. 引っ張りテスト:各ワイヤーをしっかりと引っ張ります。動いてはいけません。
  2. ぐらつきテスト:左右に押します。はんだの塊自体がボードの上で回転する場合、結合されていません — 塊とリングの両方に触れて3秒間再加熱します。
  3. ブリッジチェック:斜めからの光で、隣接する塊の間に隙間がないことを確認します — 特に+と−の間(そのブリッジは短絡です)。

元のビルドからの既知の障害モード(すべて2分で修正可能):

  • ワイヤーが抜け、穴がはんだで詰まったままになる → 塊が液体になるまで再加熱し、ワイヤーを押し戻し、2秒間保持します。
  • 「表面接着」 — ワイヤーが塊の表面に付着し、穴を通っていません。導通はしますが… 魚の中で外れます。正しくやり直してください。

3.4 Piに接続する

Piはシャットダウン(sudo shutdown now)して電源を抜いた状態で作業します。

向き、専門用語なし:Piの40ピンは2つの長い列を形成します。USB-C電源コネクタに最も近い端のピンのペアが開始点です。ボードの端に沿った列は偶数列(2、4、6…)で、内側の列は奇数列(1、3、5…)です。電源コネクタ側から位置を数えます:

ワイヤーPiピン見つけ方
黄色 (+)ピン4端の列、2番目の位置
黒 (−)ピン6端の列、3番目(黄色の隣)
白 (IN1)ピン9内側の列、5番目
グレー (IN2)ピン11内側の列、6番目
青 (IN4)ピン13内側の列、7番目
紫 (IN3)ピン15内側の列、8番目

パターンの確認:黄色のペアと黒のペアは端の列の開始近くにあり、次に白-グレー-青-紫は内側の列に途切れのない4つの連続です。電源を入れる前に写真を撮ってClaudeに確認を依頼してください — このステップで数え間違いが重要になります(ピン4は5Vを供給します)。

注意:上記の表には、テスト中に発見された修正(白を9番、グレーを11番)がすでに含まれています。口の力が弱い場合は、§3.6を参照してください — モーターは逆方向を好む可能性があり、修正はそれら2つのプラグを交換することです。

3.5 アクティブクーラーの取り付け(ついでに)

クーラーのサーマルパッドのフィルムを剥がし、大きな銀色のチップの上に合わせ、ボードの取り付け穴を通して2つのスプリングプッシュピンがクリックするまで押し込み(下からボードを支えます)、ファンケーブルをヘッダーの端近くにある小さなFANソケットに接続します。ファンは熱いときだけ回転します — 静かなのが普通です。vcgencmd measure_temp(60°C未満 = 良好)で確認してください。

3.6 電源オン + モーターテスト

電源を入れます。魚は完全に静止しているはずです。(モーターが単独で動作している = ワイヤーが間違ったピンに接続されている。電源を抜き、数え直してください。)

SSHでログインし、venvを有効にしてから nano ~/billy/motors.py:

import time

from gpiozero import OutputDevice, PWMOutputDevice

mouth = PWMOutputDevice(17)
head = OutputDevice(22)
tail = OutputDevice(27)

print("m = mouth (1s)  h = head (1s)  t = tail  b = both  q = quit")

while True:
    cmd = input("> ").strip().lower()
    if cmd == "q":
        break
    elif cmd == "m":
        mouth.value = 1.0
        time.sleep(1.0)
        mouth.value = 0
    elif cmd == "h":
        head.on()
        time.sleep(1.0)
        head.off()
    elif cmd == "t":
        tail.on()
        time.sleep(0.3)
        tail.off()
    elif cmd == "b":
        head.on()
        time.sleep(0.3)
        for _ in range(4):
            mouth.value = 1.0
            time.sleep(0.25)
            mouth.value = 0
            time.sleep(0.15)
        time.sleep(0.2)
        head.off()

mouth.value = 0
head.off()
tail.off()

それを py_compile し、実行し、m、h、t を魚を見ながら試してください。

モーターテストの落とし穴(すべて元のビルドで遭遇):

  • 間違ったものが動く → あなたのINピンの推測が現実に合いました。配線し直しなし:Claudeに各キーが何をしたか伝え、ソフトウェアのGPIO番号(17/22/27)を交換するか、Piヘッダーのプラグを交換します。
  • 「頭のモーターはどこ?口と尻尾しかない!」 → h と t は同じモーターで、逆方向です。どちらも動作しますが、同時に両方を駆動しないでください(スクリプトは決して行いません)。
  • 口の動きが弱く、尻尾は強い → ⭐定番のやつです。口は戻りバネと戦っており、これらのモーターは片方向でしか強力でないことが多いです。修正:Piの2つの口ワイヤーを交換してください(私たちのマップでは白↔グレー)。これにより、コードが強力な方向を駆動します。二次的な疑い:27W電源を使用していない。20年前のグリースが固まっている(顎を手で30回動かす)。
  • キーの1つが全く反応しない → そのワイヤーのはんだ付けを再確認してください。

b を実行してBillyが頭を持ち上げ、口を動かして話しているように見えるとき — 一時停止して楽しんでください。それが機械全体の動作です。


パート4 — 融合(話す魚)

リップシンクを機能させるトリック:Nova Sonicはオーディオを再生速度よりもはるかに速く送信します(10秒の文章が約1秒で到着するため、データが到着したときに口を動かすことができません)。代わりに、BillyBody は AudioIO とは別の出力ストリームとして登録されます — エージェントはすべてのイベントをすべての出力に送信するため、スピーカーが再生するのと同じオーディオチャンクのコピーを受け取ります。次に、ペースメーカータスクがそれらのバイトをオーディオサンプルレートと正確に同じ速度で処理するため、そのラウドネス測定値は現在スピーカーから出ているものと一致します — そしてそれが口を駆動します。頭の位置は「現在オーディオが再生されているか」から来ます。尻尾は大きな音の瞬間や会話イベントでパタパタします。

nano ~/billy/billy_final.py:

import asyncio
import base64
import math
import time
from array import array

from gpiozero import OutputDevice, PWMOutputDevice
from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel
from strands.bidi.types.events import (
    BidiAudioDeltaEvent,
    BidiBargeInEvent,
    BidiResponseStartEvent,
    BidiResponseStopEvent,
)
from strands.bidi.types.io import OutputStream

mouth = PWMOutputDevice(17)
head = OutputDevice(22)
tail = OutputDevice(27)

# ---- チューニングノブ ----
MOUTH_OPEN = 0.04   # 口が開くラウドネスのしきい値(点滅する場合は上げる)
EMPHASIS = 0.3      # 尻尾をパタパタさせるラウドネス(低いほど魚が柔らかくなる)
COOLDOWN = 1.2      # 強調パタパタ間の最小秒数
SILENCE = 1.5       # 頭が下がるまでの静寂の秒数
TICK = 0.05         # 体がラウドネスを再読み取りして動く頻度


class BillyBody(OutputStream):
    """スピーカーと同期して、体が何をすべきかを追跡します。

    AudioIOは音声を再生します。このストリームは同じチャンクのコピーを受け取り、
    リアルタイムレートで処理するため、ラウドネス測定値は実際にスピーカーから出る音と一致します。
    """

    def __init__(self):
        self.level = 0.0
        self.last_loud = 0.0
        self._tail_until = 0.0
        self._queue = bytearray()
        self._pacer = None

    async def start(self, agent):
        rate = agent.model.get_audio_config()["output"]["sample_rate"]
        self._chunk = int(rate * TICK) * 2  # 1ティックあたりの16ビットモノラルバイト
        self._pacer = asyncio.create_task(self._pace())

    async def stop(self):
        if self._pacer:
            self._pacer.cancel()
        self._queue.clear()
        self.level = 0.0

    async def __call__(self, event):
        if isinstance(event, BidiAudioDeltaEvent):
            self._queue.extend(base64.b64decode(event["audio"]))
        elif isinstance(event, BidiBargeInEvent):
            # AudioIOはバーギン時に再生を停止します。私たちのコピーもドロップします。
            self._queue.clear()
            self.flap()
        elif isinstance(event, (BidiResponseStartEvent, BidiResponseStopEvent)):
            self.flap()

    async def _pace(self):
        while True:
            samples = array("h", bytes(self._queue[: self._chunk]))
            del self._queue[: self._chunk]
            if samples:
                self.level = math.sqrt(
                    sum(s * s for s in samples) / len(samples)
                ) / 32768.0
            else:
                self.level = 0.0
            await asyncio.sleep(TICK)

    def flap(self, seconds=0.4):
        self._tail_until = time.monotonic() + seconds

    @property
    def tail_now(self):
        return time.monotonic() < self._tail_until


model = BedrockNovaSonicModel(
    model_id="amazon.nova-2-5-sonic",
    voice="matthew",
)

agent = BidiAgent(
    model=model,
    system_prompt=(
        "You are Billy, a wisecracking animatronic singing bass on a wall "
        "plaque. RULE ONE: never say more than one short sentence at a time. "
        "5 to 12 words, then stop and let the human talk. This is rapid "
        "banter, not storytelling. Never list things, never explain, never "
        "monologue. Deadpan wit over enthusiasm. Fish puns are your love "
        "language - work them in shamelessly and often."
    ),
)

audio_io = AudioIO()
body = BillyBody()


async def body_loop():
    last_flap = 0.0
    smoothed = 0.0
    while True:
        now = time.monotonic()

        # 口:平滑化されたラウドネス → モーターパワー
        smoothed = 0.6 * smoothed + 0.4 * body.level
        if smoothed > MOUTH_OPEN:
            mouth.value = min(1.0, 0.5 + smoothed * 3)
            body.last_loud = now
        else:
            mouth.value = 0

        speaking = (now - body.last_loud) < SILENCE

        # 尻尾:強調ピーク時にパタパタ(レート制限あり)
        if body.level > EMPHASIS and now - last_flap > COOLDOWN:
            body.flap()
            last_flap = now

        # 1つのモーターが頭と尻尾を駆動(逆方向):頭が優先
        if speaking:
            head.on()
            tail.off()
        elif body.tail_now:
            head.off()
            tail.on()
        else:
            head.off()
            tail.off()

        await asyncio.sleep(TICK)


async def main():
    print("Billy is ALIVE... (Ctrl+C to stop)")
    try:
        await asyncio.gather(
            agent.run(inputs=[audio_io.input()], outputs=[audio_io.output(), body]),
            body_loop(),
        )
    finally:
        mouth.value = 0
        head.off()
        tail.off()


asyncio.run(main())
python -m py_compile ~/billy/billy_final.py && echo OK
python ~/billy/billy_final.py

魚に話しかけてください。期待される振る舞い:Billyが応答すると頭が上がり → 口はすべての単語にリップシンクし → Billyが話し終えて約1.5秒後に頭が下がり → 図々しい尻尾のパタパタ → 休憩。彼を途中で割り込むと、すべてが一度に下がります。

最終段階の落とし穴:

  • 頭が上がり、下がらない → だから頭の状態はモデルの「応答完了」イベントではなく、オーディオの無音に基づいています — ライブセッションは応答を確実に終了しません。それでも表示される場合は、SILENCE を下げてください。
  • 尻尾が全くパタパタしない → EMPHASIS を下げてください(声が均一すぎるかもしれません)。モーターテストで尻尾が動作することを確認済みなので、純粋に閾値の問題です。
  • 一時停止中に口が点滅する → MOUTH_OPEN を上げてください。
  • Billyが話しすぎる → システムプロンプトが原因です。そこにあるハードルール(「一度に1つの短い文しか言わない」、「物語ではなく、早口の会話」)が彼を機敏に保つ秘訣です — 曖昧な「簡潔に」は機能しません。好みに合わせて個性を調整してください。これが楽しい部分です。

🎨 あなただけのものにする / 次のステップ

  • 個性:system_prompt はBillyの魂です。彼を海賊、不機嫌なIT担当者、チームのスタンドアップボットにしてください。
  • ツール:BidiAgent は会話中にツールを実行し、スピーチをブロックしません — Billyは口を動かしながら天気をチェックできます。このキットには3つ含まれています:🧰を参照してください。
  • ボタン(保持した黄/緑のワイヤー):GPIO 24 + グラウンドに配線し、常に聞き取るのではなく、セッションを開始/停止するために使用します。
  • 起動時に実行:systemd サービスを設定するようにClaudeに依頼してください。これにより、BillyはPiと一緒に起動します。
  • ウェイクワード:「Hey Billy」のようなPorcupineは、Pi上でローカルに実行されます — パターンについてはbilly-b-assistantプロジェクトを参照してください。
  • 再組み立て:バックプレートにケーブル用の切り欠きを入れ、元のセンサー穴の近くにマイクを取り付け、Piをプラークにベルクロで固定します。

🔁 代替実装:OpenAI Realtime

StrandsのBidiAgentはプロバイダーに依存しないため、同じ魚がAWS Bedrock(Nova 2.5 Sonic)の代わりにOpenAIのRealtime APIでも動作します — billy_openai.py がそのビルドです。billy.py との違いは、基本的にモデルコンストラクタとボイスです。OpenAIも独自のボイスラインナップを提供しています — (このファイルで使用されている)イギリス訛りのもの(ballad)などがありますので、魚に合う方を選んでください。

pip install "strands-agents[bidi-openai]"   # venv内で
export OPENAI_API_KEY=sk-...
python billy_openai.py

2つの正直なトレードオフ:OpenAIは24 kHzでオーディオをストリーミングするため、RMSチューニングノブは微調整が必要かもしれません — そしてbilly.pyからのローカルVADプライバシゲートはここでは機能しません。なぜならwebrtcvadは8/16/32/48 kHzオーディオしか理解しないからです。OpenAIビルドは元のフィードバックのみのマイクゲートを使用します。プライバシゲートがあなたにとって重要なら、Novaを使い続けてください。

🧰 Billyにツールを与える(天気、ニュース、カレンダー&メール)

billy_tools.py はBillyをノベルティから実際の(まだばかげた)パーソナルアシスタントに変えます。billy.py は設定されているものを自動的にロードします — コード変更は不要です。

天気とニュースはすぐに動作します。 Pi上のvenvで:

pip install feedparser

次に、Billyに彼の住んでいる場所と読んでいるものを伝えます。Billyはbilly.pyの隣にあるbilly.envファイルから設定を読み取るため、再起動しても~/.bashrcやsystemdユニットに触れることなく保持されます。テンプレートをコピーして、あなた自身の値を入力してください:

cp billy.env.example billy.env
nano billy.env        # 各<PLACEHOLDER>を置き換えてください

すべての変数はオプションです — 1つでも省略すると、Billyはデフォルト(シアトル、BBC + NPRフィード)を使用します。billy.env はgitignoreされているため、billy.env.example のみが提供されます:

BILLY_LATITUDE=<あなたの緯度>
BILLY_LONGITUDE=<あなたの経度>
BILLY_NEWS_FEEDS=<カンマ区切りのRSSフィードURL>

(exportした場合、実際の環境変数はファイルよりも優先されます。)

天気はOpen-Meteoから取得します — APIキーやアカウントは不要です。ニュースはプレーンなRSSです。任意のフィードURLが機能します。

カレンダーとメールはオプションで、strands-googleコミュニティ統合を使用します(1つのツール、200以上のGoogle API)。1回限りのセットアップで、ラップトップで実行するのが最も簡単です:

  1. ラップトップとPiの両方で pip install strands-google を実行します。

  2. Google Cloud Consoleで:プロジェクトを作成し、Gmail APIとGoogle Calendar APIを有効にし、デスクトップアプリタイプのOAuthクライアントIDを作成します。クライアントJSONをダウンロードし、このリポジトリの外の安全な場所に保存します — 認証情報はgitワーキングツリーに配置すべきではありません。

  3. OAuthアプリを本番環境に公開しないと、あなたのトークンは7日ごとに無効になります。 これは皆がスキップして、1週間後に代償を払うステップです。新しいOAuthアプリはテスト中モードで開始され、Googleはテストモードの更新トークンを7日後に期限切れにします — Billyのメールツールは、これを行わないと毎週サイレントに壊れます。コンソールで APIs & Services → OAuth consent screen(Googleは現在この領域を「Google Auth Platform」と呼んでいます)の下:

    • Branding ページ:必須フィールドを記入します — アプリ名、メールアドレスを2回(サポート用と開発者連絡用)。公開するには、Googleは所有しているドメイン上のアプリケーションホームページも要求します(そのドメインは承認済みドメインの下に追加されている必要があります。個人サイトやブログで十分です。GitHub URLは拒否されます。ロゴはスキップしてください — アップロードするとGoogleの正式な検証レビューに巻き込まれます。
    • Audience ページ:Publish app を選択し、Testing から In production に変更します。
    • Googleは、アプリが「検証が必要」と警告します。無視してください — あなただけがユーザーです。唯一の結果は、恐ろしい同意画面(次のステップ)が表示されることですが、それを一度だけクリックします。
    • これらのフィールドは同意画面の装飾です。記入しても、あなたのメールが公開されたり、何かが弱められたりすることはありません。トークンは、誰かが自分のアカウントにサインインしてあなたのクライアントJSONを使用して「許可」をクリックしたときにのみ発行されます。
  4. ラップトップで、このリポジトリのセットアップスクリプトを実行します — Strands-googleの組み込みランナーではありません。そのデフォルトスコープにはGmailのフル送信/変更、Drive、Photos、Contactsが含まれます。google_setup.py は読み取り専用スコープを2つだけ要求します(Gmail + カレンダー)。Billyはあなたとしてメールを送信する義務はありません:

    python google_setup.py path/to/your-downloaded-client.json
    

    ブラウザが開きます。あなたは「Googleはこのアプリを検証していません」という警告に遭遇します — 詳細設定 → (あなたのアプリ)に進む(安全ではありません) をクリックします。それはあなた自身のアプリなので、あなた自身が保証しています。2つの読み取り専用権限を承認します。これにより、クライアントファイルと同じ場所にgmail_token.jsonが書き込まれます。

  5. トークンを魚に転送します — いずれかを選択します:

    • シンプル:書き込まれたgmail_token.jsonをPiにコピーします(これもgitリポジトリの外にあります)。そして、billy.envに GOOGLE_OAUTH_CREDENTIALS=/path/to/gmail_token.json を追加します。

    • より良い(IoT資格情報付録を実行した場合に推奨):トークンをSDカードに保存しないように、AWS Secrets Managerに保存します(月額約0.40ドル):

      python google_setup.py path/to/your-downloaded-client.json --secret-id billy/google-token
      

      次にPiで、billy.envに BILLY_GOOGLE_SECRET_ID=billy/google-token を設定します。起動時にBillyはトークンを/dev/shm(RAM — 電源オフで消える)にフェッチします。読み取りアクセスを許可するには、シークレットのARN(スクリプトが正確なコマンドを表示します)でIDスタックを再デプロイします — billy-iot.yaml はそれをオプションの GoogleTokenSecretArn パラメータとして受け取るため、魚の権限はテンプレート管理された最小権限のままになります。

どちらの変数も設定されていない場合、BillyはGoogleツールを取得しません — 天気とニュースは引き続き機能します。いつものように:このセクションをClaudeに貼り付けて、一緒に作業してください。

正直な注意点:strands-googleはコミュニティによって維持されている統合です(Apache-2.0、公式Strands統合カタログに記載)。魚には最適です。関心のあるアカウントに向けた場合は、ご自身で監査してください。

🔐 付録:認証情報 — 実用的な方法 vs. 本番の方法

このガイドのメインパスは、厳密にスコープされたIAMアクセスキーをPiに配置します(1つのアクション、1つのモデル、1つのリージョン — §前提条件)。個人のアカウントの個人用魚としては、これは妥当なトレードオフです:SDカードが漏洩した場合の最悪のシナリオは、あなたの請求書での魚チャットであり、キルスイッチはワンクリック(IAMでキーを無効化)です。

本番グレードの回答は、AWS IoT Coreの認証情報プロバイダーです — 実際のデバイスフリートが使用するパターン:

  1. デバイスは、アクセスキーの代わりにX.509証明書(そのID)を取得します。
  2. 起動時に、証明書を提示して、相互TLS経由でIoT認証情報エンドポイントを呼び出します。
  3. IoTは、証明書を使用して、一時的なIAM認証情報を取得します(数分から数時間有効)。これは、ロールを引き受けることによって行われます — もちろん、Nova Sonicのみにスコープされます。
  4. その一時的な認証情報は、Strandsが使用するboto3セッション(`BidiNovaSonicModel(client_config={