BLEA

BLEA

BLEA（Bluetooth Low Energy Automation）は、安全で予測可能な BLE 作業を実現する汎用エージェントプラグインです。AI エージェントが利用できるポータブルなスキル、機械可読な CLI、ローカル MCP サーバー、安全策を備えた自動化機能、オフラインでの証拠の取得・差分比較・再生機能を提供します。

このプロジェクトは、エージェントが繰り返し必要とする BLE 作業向けに設計されています。OS の Bluetooth アクセスを確認し、近くの適切なデバイスを見つけ、GATT サービスを検出し、生のバイトデータの証拠を保存・比較し、状態を変更する前に読み取りとサブスクリプションを行い、明示的な承認を得てから書き込みを行います。

インターフェース	役割
Agent Plugin 1.0.0	ポータブルな識別情報、スキル、MCP 宣言をパッケージ化します。
Agent Skill	BLE のワークフロー、安全上の境界、復旧ルールをエージェントに教えます。
CLI	スクリプト、ターミナル、シェルアクセスを持つあらゆるエージェント向けに、決定的な JSON/JSONL を出力します。
MCP	同じランタイムを、BLE セッションを管理するローカルの構造化ツールとして公開します。

ble 実行ファイルが共有ランタイムです。通常のサブコマンドは CLI インターフェースを使用し、ble mcp は stdio MCP サーバーを起動します。したがって、MCP プロトコルは第一級のインターフェースであり、無関係な CLI 製品に隠された別のツールではありません。

インストール

BLEA には Python 3.10 以降が必要です。Bluetooth へのアクセスは、Bleak を通じてオペレーティングシステムから提供されます。

エージェントプロンプトですばやくインストール

シェルアクセスを持つエージェントに、このプロンプトを渡してください。

Read https://github.com/Nitmi/blea and follow its README to install BLEA for me.

手動でインストールする場合は、以下の詳しい手順を使用してください。

PyPI から公開済みの最新 Python ランタイムをインストールします。

uv tool install blea
ble --help

Codex の場合は、ランタイムのインストール後に公開 Git マーケットプレイスパッケージをインストールします。

codex plugin marketplace add Nitmi/blea
codex plugin add blea@blea

Skills CLI でポータブルな Agent Skill のみをインストールするには、次のコマンドを実行します。

npx skills add Nitmi/blea --skill ble

OpenClaw の場合は、公開 ClawHub リストから同じポータブルスキルをインストールします。

openclaw skills install @nitmi/blea
# Or use the registry CLI directly:
clawhub install @nitmi/blea

スキルはワークフローと安全ポリシーを教えるものであり、Python ランタイムはインストールしません。エージェントに実際の Bluetooth ハードウェアへのアクセスやローカル MCP サーバーの起動を依頼する前に、上記のとおり PyPI から blea をインストールしてください。スキルのソースは skills/ble/SKILL.md、公開 ClawHub リリースは @nitmi/blea です。

インストール後に新しいエージェントタスクを開始してください。マーケットプレイスパッケージは BLE スキルと MCP 宣言を提供しますが、Python ランタイムやオペレーティングシステムの Bluetooth 権限はインストールしません。リリースタグ、従来の 0.6.0 ブリッジ、更新手順については、docs/installation.md を参照してください。

チェックアウトから、作業ツリーを直接使ってコマンドランタイムをインストールします。

uv tool install --editable .
ble --version

リポジトリの開発用：

uv sync --extra dev
uv run ble --help

スタンドアロンの Windows リリース

0.6.5 以降、各リリースには、単一ファイルの ble.exe と、SHA-256、バージョン、ターゲット、ソースコミットを紐付けるマニフェストを含む ble-<version>-windows-x86_64.zip が含まれます。実行時に Python は不要です。タグのワークフローでは、1 台の GitHub ホスト Windows ランナー上で 2 回ビルドし、ZIP のハッシュが一致しない場合は拒否します。また、ble --version とアダプターを使わないエビデンスの再生を実行し、GitHub アーティファクトの来歴を作成します。doctor の実行、スキャン、Bluetooth ハードウェアへのアクセスは行いません。

使用前にアーカイブを検証してください。

gh attestation verify blea-0.7.0-windows-x86_64.zip `
  --repo Nitmi/blea `
  --source-ref refs/tags/v0.7.0 `
  --signer-workflow Nitmi/blea/.github/workflows/binary-release.yml `
  --deny-self-hosted-runners

アテステーションは、リポジトリでビルドされた来歴を証明するものであり、Windows Authenticode 署名ではありません。また、Bluetooth アダプター、周辺機器、ファームウェアの識別情報を証明するものでもありません。

Python ランタイムと Agent Plugin は、関連する 2 つのインストール単位です。PyPI は ble 実行ファイルをインストールし、Agent Plugins 1.0.0 クライアントは、このリポジトリのディレクトリを読み込んで plugin.json、mcp.json、skills/ble を検出します。プラグインのローカル stdio MCP サーバーが PATH 上の ble を見つけられるよう、先にランタイムをインストールしてください。ソース、プラグイン、更新、権限、検証の各手順については、docs/installation.md を参照してください。

CLI

ble doctor --json
ble scan --timeout 8 --json
ble inspect --device "id:AA:BB:CC:DD:EE:FF" --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --read-offset 16 --json
ble read --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a19 --json
ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble subscribe --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a37 --duration 15 --jsonl
ble observe --device "id:AA:BB:CC:DD:EE:FF" --duration 10 --jsonl
ble diff before.blea.jsonl after.blea.jsonl --json
ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble exchange \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --write-characteristic 12345678-1234-1234-1234-1234567890ab \
  --notify-characteristic 87654321-4321-4321-4321-ba0987654321 \
  --text ping --duration 5 --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" --jsonl

デバイス名を使用できるのは、その名前を持つデバイスが観測されたものの中でちょうど1台の場合に限られます。scan が返すプラットフォーム識別子を優先してください。macOS では通常、MAC アドレスではなく UUID です。

すべてのバイナリ値には、length、hex、base64、置換処理に安全な UTF-8 表現が含まれます。 JSON エラーでは、エージェントが復旧する際に利用できる、安定した理由と終了コードを使用します。

probe はページネーションに対応しています。next_read_offset が null になるまで、後続の値をたどってください。ページの件数と特性レベルの失敗は read_page の下に含まれます。ok=true はページが実行されたことを示し、read_page.has_failures は特性のいずれかで失敗が発生したかどうかを示します。すべての結果には、簡潔な profile_summary が含まれます。CLI ではデフォルトで GATT プロファイル全体が含まれ、--no-include-profile にも対応しています。MCP ツールでは、ページを繰り返し取得する際のデータ量を抑えるため、デフォルトでは省略されます。

接続コマンドでは timeout_scope=per_backend_operation が報告されます。タイムアウトはコマンド全体の所要時間を制限するのではなく、デバイスの検出、接続、各 GATT 操作にそれぞれ適用されます。 GATT エントリーには uuid_namespace が含まれます。BLEA は、先頭バイトからカスタムの128ビット UUID に標準名を誤って推定しないよう、正規の Bluetooth Base UUID に対してのみライブラリの説明を報告します。

observe は通知／表示特性を検出し、1つの接続を使用して、指定した上限時間内で監視します。すべてのイベント対応特性を選択するには --characteristic を省略し、明示的に選択するには複数回指定します。結果では、サブスクリプションの失敗、クリーンアップの失敗、通知イベントがそれぞれ分けて示されます。イベントのない期間は、そのサンプル期間についての証拠に限られます。

診断後、読み取り専用の完全な証拠パッケージを保存します。

ble capture \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --output capture.blea.jsonl \
  --max-reads 128 \
  --observe-duration 10 \
  --redact-identifiers \
  --json

capture は、アドバタイズメント、正規化された GATT プロファイル、各読み取り可能な特性の結果、上限付きの通知、操作エラー、検証済みの最終サマリーを記録します。書き込み、ペアリング、設定変更は行わず、アトミックにクローズした後にのみ保存先を置き換えます。JSONL ファイルが正式な成果物であり、コマンドの JSON 結果は簡潔なサマリーです。 Evidence Format v1 の仕様と決定論的なバリデーターは docs/evidence-format-v1.md にあります。

Bluetooth アダプターやデバイスを使わずに、2つの完全な証拠パッケージを比較します。

ble diff before.blea.jsonl after.blea.jsonl --json
ble diff before.blea.jsonl after.blea.jsonl --fail-on-change --json

diff は両方の Evidence Format v1 入力を検証し、安定した BLE セマンティクスに変換して、ソート済みの JSON Pointer 形式の差分を出力します。デフォルトでは、キャプチャ ID、タイムスタンプ、実行時メタデータ、サンプリング期間、5 dBm 以内の RSSI の変動を無視します。RSSI を厳密に比較するには --strict-rssi を使用します。意図的なデバイス間比較で --allow-different-devices を使用しない限り、デバイス識別子は一致している必要があります。バイナリペイロードはアトミックな変更として扱われるため、値が1つ変わっても Hex、Base64、UTF-8 の個別の差分は発生しません。通常の差分では正常終了します。CI で完全な結果を出力した後にコード 3 を返すには、--fail-on-change を使用します。仕様は docs/diff-format-v1.md にあります。

Bluetooth アダプターや物理デバイスを使わずに、完全な証拠パッケージを再生します。

ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl probe --max-reads 32 --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble replay capture.blea.jsonl observe --duration 10 --jsonl
ble replay capture.blea.jsonl run examples/replay-read-only.yaml --json

Replay は、ライブデバイスに使用されるものと同じ読み取り専用バックエンドインターフェースを通じて、アドバタイズメント、GATT、読み取り、記録された失敗、サブスクリプションの結果、通知のタイムラインを再構成します。デフォルトの --speed 0 モードは即時かつ決定論的です。記録された通知間隔を指定した倍率で再現するには、操作の前に正の値の --speed を指定してください。観測結果がない場合は、値や成功を捏造せず、安定した replay_miss 理由を返します。Replay は実際のアダプターにアクセスせず、書き込みや交換の送信またはシミュレーションも行いません。仕様の全文は docs/replay-format-v1.md にあります。

ペアリング

Windows と Linux では、OS の明示的なペアリングとペアリング解除は、個別のガード付き単発操作です。 どちらの操作にも、最新の id: セレクター、--allow-pairing、および解決された識別子と一致する --confirm-device が必要です。デバイスの検出時間は既定で 5 秒（--scan-timeout）であり、 ペアリングの操作ごとのタイムアウトである 60 秒とは別です。ペアリングを解除すると OS のボンドが削除され、 他のクライアントが切断される可能性があるため、先にアクティブな BLEA セッションを終了してください。どちらの操作も 自動再試行されず、構造化された JSON の結果を返します。macOS では Bleak を通じた明示的なペアリング／ペアリング解除は利用できません。 代わりに、保護された GATT へのアクセス時に OS がペアリングを求めます。ペアリング用フラグを指定しても、 リプレイは読み取り専用のままです。

ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble unpair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --json

6 桁の PIN が必要な Windows デバイスでは、プロセスローカルの環境変数を設定し、--pin-env でその名前を 渡してください。PIN は CLI 引数や BLEA の結果フィールドには含まれません。 たとえば、ローカルで BLEA_PAIR_PIN を設定した後、次のように実行します。

ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --pin-env BLEA_PAIR_PIN --json

この方法では Windows のカスタムペアリングで ProvidePin を使用し、暗号化と認証を必要とします。 OS のボンド状態を更新し、paired_before、paired_after、pin_used、および authentication_verified を報告します。既存のボンドがある場合は、指定された PIN をテストしたとは示さずに already_paired を報告します。保護レベルへのフォールバックや数値比較の自動承認はありません。 使用後は環境変数を削除してください。MCP の ble_pair は同じ PIN を pin として受け付けます。 BLEA の結果には PIN が含まれませんが、MCP ホストがツール引数を履歴に保持する場合があります。

PIN を指定しない場合、ペアリングでは Bleak のプラットフォームごとの動作が使用されます。固定されている Bleak 1.1.1 の Windows バックエンドは 確認のみのペアリングにしか対応しておらず、PIN を受け付けません。Linux では設定済みの BlueZ ペアリングエージェントが使用されます。 BLEA の明示的な PIN パラメーターは、現在 Windows でのみ使用できます。一般的なペアリング／ペアリング解除の結果が成功を示す場合、 バックエンドの処理完了を報告するものであり、OS のボンドストアを個別に証明するものではありません。 ペアリング解除によってホストのボンドは削除されますが、ペリフェラル自体が保存済みの鍵を消去したことを証明するものではありません。 Windows PIN acceptance には、テスト済みの構成が記載されています。

ガード付き書き込み

書き込みには、--allow-write と、解決された識別子との完全一致を確認する指定の両方が必要です。

ble write \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --characteristic 12345678-1234-1234-1234-1234567890ab \
  --hex 01 \
  --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" \
  --read-back \
  --json

YAML の書き込みとエクスチェンジには、さらに 2 つのガードが必要です。ワークフローで書き込みを有効にし、 状態を変更する各ステップで dangerous: true と、前提条件となるステップの成功を宣言する必要があります。 ポリシーには、識別子と完全一致する confirm_device も含める必要があります。examples/guarded-write.yaml と examples/esp32-burst-exchange.yaml を参照してください。

書き込みによって通知が発生するプロトコルでは、exchange を使用してください。ガード付き書き込みを実行する前に 通知のサブスクリプションを有効にし、その後、指定した時間内にイベントを収集します。 書き込み用と通知用のキャラクターリスティックには、同じものでも別のものでも指定できます。これにより、 スタンドアロンのセッションサブスクライブ操作と書き込み操作を同時に開始したときに発生する競合を避けられます。

再現可能なチェックを行うには、exchange ステップで通知の件数、UTF-8 または Hex の内容、最後の通知、 サブスクリプションのクリーンアップを検証できます。独立した実行ゲートを使って、ガード付き YAML ワークフローを実行します。

ble run examples/esp32-burst-exchange.yaml --allow-write --json

実行前に、例のデバイス識別子と確認値を、最新のスキャンで返された値と完全に一致するものに置き換えてください。

MCP とエージェントプラグイン

ローカルの stdio サーバーを直接起動します。

ble mcp

MCP の機能には、ワンショットツール、オフラインの ble_diff 比較ツール、オフラインの ble_replay 実行ツール、およびステートフルなセッションツールが含まれます。セッションを使うと、 エージェントは一度接続するだけで、調査、読み取り、監視、購読、保護されたリクエスト／通知の交換または書き込みを行い、 その後切断できます。ble_exchange と ble_session_exchange は、書き込みの前にアトミックに購読します。 ble_pair と ble_unpair は、CLI と同じ厳密なデバイス指定のペアリング保護を提供します。これらは ワンショット操作であり、既存の GATT セッションに対する操作ではありません。 ble_session_list はアクティブなリースを表示し、ble_session_close_all は明示的な復旧手段を提供します。 MCP クライアントの終了時にサーバーはすべてのセッションを切断し、デフォルトでは非アクティブなセッションを 120 秒後に破棄します。BLEA_SESSION_IDLE_SECONDS を別の正の秒数に設定するか、0 に設定すると、 シャットダウン時のクリーンアップを維持したまま、アイドル状態のセッションの破棄を無効にできます。

既知のセッションを閉じるには ble_session_close を使用します。ble_session_close_all は、 不明なセッション ID、明示的なクローズの失敗、または状態が残存していることが確認された場合の復旧に限って使用してください。

ハードウェアの代わりに、1 つのキャプチャに対して通常の MCP BLE ツールを公開するには、専用の リプレイサーバーを起動します。

ble replay capture.blea.jsonl mcp

リプレイを利用したすべての BLE 操作の結果には、証拠が特定され、replay.read_only=true が含まれます。 クライアントが既存の書き込みツールや交換ツールをライブデバイス認可フィールド付きで呼び出しても、 ReplayBackend は拒否します。

このリポジトリ自体が Agent Plugins 1.0.0 パッケージです。

blea/
├── plugin.json                        portable plugin identity
├── mcp.json                           portable local stdio MCP declaration
├── skills/ble/SKILL.md                portable Agent Skill
├── .codex-plugin/plugin.json          root ChatGPT/Codex package metadata
├── .mcp.json                          root ChatGPT/Codex MCP declaration
├── .agents/plugins/marketplace.json   public Git marketplace catalog
└── plugins/blea/                      installable Codex distribution mirror

プラグイン設定では、ble 実行ファイルが PATH にインストールされていることを想定しています。ポータブルな 仕様では Skill と MCP のメタデータが配布されます。ネイティブ Bluetooth ランタイムのインストールと OS の 権限設定は、引き続き各プラットフォームの責任です。

このリポジトリには、PyPI 配布用の公式 MCP Registry パッケージメタデータである server.json も含まれています。これはローカルの stdio サーバーと mcp パッケージの 引数を宣言しており、ホスト型またはリモートの BLE サービスを公開するものではありません。リリースでは、 対応する PyPI バージョンの公開が成功した後、短期間有効な GitHub OIDC 認証情報を使って、 このメタデータを公式 MCP Registryに公開します。Registry の 認証とパッケージ所有権マーカーでは大文字と小文字が区別されるため、名前空間では GitHub ログイン名の 正規の大文字・小文字表記が保持されます。

ルートのDockerfileは、MCP プロトコルのイントロスペクションとアダプター不要のツール向けの レジストリサンドボックスです。バージョンが揃ったリリースチェックアウトをビルドし、ble mcp を起動します。 これにより、そのバージョンが PyPI に存在する前でも、リリース候補の CI を実行できます。コンテナから ホストの Bluetooth アダプターにアクセスできることを保証するものではありません。ライブ BLE 操作には、 上記のネイティブホストへのインストールを使用してください。

OpenAI Plugins Directory への申請では、ポータブルな Skill のみを使用します。ライブ BLE にはユーザーの ネイティブホストとアダプターが必要なため、BLEA の MCP サーバーはローカルにとどまり、公開リモート MCP エンドポイントとしては提供されません。申請用の説明、制限事項、スタータープロンプト、レビューケースは docs/openai-plugin-submission.md に記載されています。

公開 Codex 配布は、インストールセクションに示された変更不可能な Git ref で登録され、 codex plugin add blea@blea でインストールされます。固定された ref は、マーケットプレイスのスナップショットが 更新されても別のリリースには進みません。リリースを変更するには、設定済みのマーケットプレイスを削除し、 新しい v<version> タグで再度追加して、プラグインを再インストールし、新しい Agent タスクを開始してください。 Python パッケージをインストールしただけで、Agent Skill や MCP 宣言もインストールされたと見なさないでください。

プラットフォームのステータス

Windows 11 は、ESP32-S3 BLEA テストサーバーを使用したハードウェア検証に合格しており、検出、GATT、 通知、ガード付き交換、キャプチャ、リプレイが対象です。macOS と Linux は現在、ユニットテストスイートに合格し、 CI で同じ実機のエビデンスをリプレイしていますが、ネイティブ Bluetooth アダプターの経路は実機ホストで テストされていません。公開済みの受け入れレポートで明示されるまでは、これら 2 つのプラットフォームを CI + replay verified; native BLE hardware unverified として扱ってください。

正確なサポートレベル、プライバシー要件、ハードウェア受け入れ手順、現在のエビデンスマトリックスについては、 docs/platform-acceptance.md を参照してください。

開発

uv sync --extra dev
uv run python scripts/sync_codex_plugin.py --check
uv run python scripts/check_agent_package.py
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build --clear --no-create-gitignore
uv run python scripts/check_distribution.py dist

ユニットテストでは BLE のフェイクバックエンドを使用するため、近くにハードウェアがなくても実行できます。CI は Windows、macOS、 Linux で実行されます。各 CI ジョブでは、チェックイン済みの完全なエビデンスフィクスチャに対して examples/replay-read-only.yaml も実行します。これにより、アダプター不要でエンドツーエンドの CLI と Workflow のスモークテストを行えます。

ルートにある .codex-plugin、.mcp.json、および skills の各パスが、Codex Plugin の信頼できる唯一の情報源です。これらを 変更した後は、uv run python scripts/sync_codex_plugin.py を実行してください。CI では --check を使用して差分を拒否します。 リポジトリ内の Agent パッケージチェッカーは、メンテナー個人の Skill ディレクトリに依存せず、両方の Codex Plugin ルート、MCP 宣言、 Skill メタデータ、agents/openai.yaml を検証します。 配布物チェッカーは、sdist 内のマーケットプレイスファイルの欠落と、Python wheel 内の Plugin メタデータの欠落も拒否します。

実際のアダプターのサポート状況は CI とは別に管理されています。CI の成功は、ネイティブハードウェアのサポートを意味するものではありません。

リリース履歴は CHANGELOG.md にあります。メンテナーは、アーティファクト、Trusted Publishing、Plugin、 公開後の確認事項について、docs/releasing.md に従ってください。

関連プロジェクト

シリアル、UART、COM ポート、USB-to-TTL、ファームウェアコンソールのワークフローについては、 baud-cli を参照してください。ガード付き YAML 自動化、構造化出力、アーカイブされた生バイトのエビデンスを備えた、 エージェント向けの baud CLI とポータブル Skill を提供しています。