ハードウェア周辺機器設計: ZeroClaw

ZeroClawは、マイクロコントローラー(MCU)およびシングルボードコンピューター(SBC)が自然言語コマンドを動的に解釈し、ハードウェア固有のコードを生成し、ペリフェラル相互作用をリアルタイムで実行できるようにします。

1. ビジョン

目標: ZeroClawはハードウェア認識AI エージェントとして機能します:

チャネル(WhatsApp、Telegram)経由で自然言語トリガーを受け取ります(例:「Xアームを動かす」、「LEDをオンにする」)
正確なハードウェアドキュメント(データシート、レジスタマップ)を取得します
LLM(Gemini、ローカルオープンソースモデル)を使用してRustコード/ロジックを合成します
ロジックを実行してペリフェラル(GPIO、I2C、SPI)を操作します
最適化されたコードを将来の再利用のために保持します

メンタルモデル: ZeroClaw = ハードウェアを理解するブレーン。ペリフェラル = 制御する腕と脚。

2. 2つの動作モード

モード 1: エッジネイティブ(スタンドアロン)

ターゲット: Wi-Fi対応ボード(ESP32、Raspberry Pi)。

ZeroClawはデバイス上で直接実行されます。ボードはgRPC/nanoRPCサーバーをスピンアップし、ローカルでペリフェラルと通信します。

ZeroClaw on ESP32 / Raspberry Pi (Edge-Native)

  Channels (WhatsApp, Telegram)
        │
        ▼
  Agent Loop (LLM calls) ──► RAG: datasheets, register maps ──► LLM context
        │
        ▼
  Code synthesis ──► Wasm / dynamic exec ──► GPIO / I2C / SPI ──► persist
        │
        ▼
  gRPC/nanoRPC server ◄──► Peripherals (GPIO, I2C, SPI, sensors, actuators)

ワークフロー:

ユーザーがWhatsAppを送信: 「ピン13のLEDをオンにする」
ZeroClawはボード固有のドキュメント(例:ESP32 GPIOマッピング)を取得します
LLMはRustコードを合成します
コードはサンドボックス(WasmまたはダイナミックリンキングL)で実行されます
GPIOが切り替わり、結果がユーザーに返されます
最適化されたコードは、将来の「LEDをオンにする」リクエストのために保持されます

すべてオンデバイスで行われます。 ホストは不要です。

モード 2: ホスト仲介(開発/デバッグ)

ターゲット: USB / J-Link 経由でホスト（macOS、Linux）に接続されたハードウェア。

ZeroClawはホスト上で実行され、ターゲットへのハードウェア認識リンクを維持します。開発、内省、およびフラッシング用に使用されます。

  ZeroClaw on Mac (host)              STM32 Nucleo-F401RE (or other MCU)
  ─────────────────────              ──────────────────────────────────
  - Channels                         - Memory map
  - LLM                              - Peripherals (GPIO, ADC, I2C)
  - Hardware probe        ◄────────► - Flash / RAM
  - Flash / debug
                       USB / J-Link
                       VID/PID discovery

ワークフロー:

ユーザーがTelegramを送信: 「このUSBデバイスで読み取り可能なメモリアドレスは何ですか?」
ZeroClawは接続されたハードウェア(VID/PID、アーキテクチャ)を識別します
メモリマッピングを実行し、利用可能なアドレス空間を提案します
結果をユーザーに返します

または:

ユーザー: 「このファームウェアをNucleoにフラッシュする」
ZeroClawはOpenOCDまたはprobe-rs経由で書き込み/フラッシュします
成功を確認します

または:

ZeroClawは自動検出: 「/dev/ttyACM0上のSTM32 Nucleo、ARM Cortex-M4」
提案: 「GPIO、ADC、フラッシュを読み書きできます。何をしたいですか?」

モード比較

アスペクト	エッジネイティブ	ホスト仲介
ZeroClaw は以下で実行されます	デバイス (ESP32、RPi)	ホスト (Mac、Linux)
ハードウェアリンク	ローカル (GPIO、I2C、SPI)	USB, J-Link
LLM	オンデバイスまたはクラウド (Gemini)	ホスト (クラウドまたはローカル)
ユースケース	本番環境、スタンドアロン	開発、デバッグ、イントロスペクション
チャンネル	WhatsApp など (WiFi 経由)	Telegram、CLI など

3. レガシー / より簡単なモード (LLM-on-Edge 前)

WiFi がないボードまたは完全な Edge-Native の準備ができていない場合:

モード A: ホスト + リモート周辺機器 (シリアル経由の STM32)

ホストで ZeroClaw を実行します。周辺機器は最小限のファームウェアを実行します。シリアル経由でシンプルな JSON。

モード B: RPi をホストとして (ネイティブ GPIO)

Pi 上の ZeroClaw。rppal または sysfs 経由の GPIO。別のファームウェアはありません。

4. 技術要件

要件	説明
言語	純粋な Rust。組み込みターゲット (STM32、ESP32) では `no_std` が該当する場合。
通信	低遅延コマンド処理用の軽量 gRPC または nanoRPC スタック。
動的実行	LLM 生成ロジックを安全にその場で実行: 分離用の Wasm ランタイム、またはサポートされている動的リンク。
ドキュメント取得	RAG (Retrieval-Augmented Generation) パイプラインでデータシートスニペット、レジスタマップ、およびピンアウトを LLM コンテキストにフィードします。
ハードウェア検出	USB デバイスの VID/PID ベース識別。アーキテクチャ検出 (ARM Cortex-M、RISC-V など)。

RAG パイプライン (データシート取得)

インデックス: データシート、リファレンスマニュアル、レジスタマップ（事前変換済みの .md / .txt → チャンク、エンベディング）。
取得: ユーザークエリで (「LED をオンにする」)、関連するスニペット (対象ボードの GPIO セクションなど) を取得します。
注入: LLM システムプロンプトまたはコンテキストに追加します。
結果: LLM が正確なボード固有のコードを生成します。

動的実行オプション

オプション	利点	欠点
Wasm	サンドボックス化、ポータブル、FFI なし	オーバーヘッド。Wasm からの HW アクセスが制限されています
動的リンク	ネイティブ速度、完全な HW アクセス	プラットフォーム固有。セキュリティの懸念
解釈型 DSL	安全、監査可能	遅い; 表現力が限定的
プリコンパイル済みテンプレート	高速で安全	柔軟性が低い; テンプレートライブラリが必須

推奨: プリコンパイル済みテンプレート + パラメータ化から始める; 安定化後、ユーザー定義ロジック用に Wasm に発展させる。

5. CLI とコンフィグ

CLI リファレンスの zeroclaw hardware / zeroclaw peripheral サブコマンドとコンフィグリファレンスの [peripherals] および [[peripherals.boards]] フィールドを参照してください。

6. アーキテクチャ: 拡張ポイントとしてのペリフェラル

新しいトレイト: `Peripheral`

#![allow(unused)]
fn main() {
/// 機能をツールとして公開するハードウェアペリフェラル。
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;  // 例: "nucleo-f401re", "rpi-gpio"
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    /// このペリフェラルが提供するツール (gpio_read, gpio_write, sensor_read など)
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}
}

フロー

起動: ZeroClaw はコンフィグを読み込み、peripherals.boards を確認します。
接続: 各ボードについて、Peripheral 実装を作成し、connect() を呼び出します。
ツール: すべての接続されたペリフェラルからツールを収集し、デフォルトツールとマージします。
エージェントループ: エージェントは gpio_write や sensor_read などを呼び出すことができ、これらはペリフェラルに委譲されます。
シャットダウン: 各ペリフェラルで disconnect() を呼び出します。

ボードサポート

正規レジストリでは、ボードは USB VID/PID によって識別されます:

ボード	アーキテクチャ	USB VID:PID
`nucleo-f401re`	ARM Cortex-M4	`0x0483`:`0x374b`
`nucleo-f411re`	ARM Cortex-M4	`0x0483`:`0x3748`
`arduino-uno`	AVR ATmega328P	`0x2341`:`0x0043`
`arduino-uno`	Arduino Uno Q / ATmega328P	`0x2341`:`0x0078`
`arduino-mega`	AVR ATmega2560	`0x2341`:`0x0042`
`cp2102`	USB-UARTブリッジ	`0x10c4`:`0xea60`
`cp2102n`	USB-UARTブリッジ	`0x10c4`:`0xea70`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x7523`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x55d4`

接続された各ボードは、いずれかのサブシステムトランスポートを介して駆動されます。

トランスポート	説明
`serial`	USB CDC シリアル経由の改行区切り JSON
`swd`	SWD デバッグプローブ (probe-rs)
`uf2`	UF2 マスストレージファームウェアフラッシュ
`native`	Linux GPIO/I2C/SPIへの直接アクセス（rppal、sysfs）

すべてのボードが提供する基本ツールは、ハードウェアサブシステム → ランタイムツールに一覧表示されています。

7. 通信プロトコル

gRPC / nanoRPC (エッジネイティブ、ホスト仲介)

ZeroClaw とペリフェラル間の低遅延、型付き RPC の場合:

nanoRPC または tonic (gRPC): Protobuf 定義サービス。
メソッド: GpioWrite、GpioRead、I2cTransfer、SpiTransfer、MemoryRead、FlashWrite など。
.proto ファイルからのストリーミング、双方向呼び出し、コード生成を有効にします。

シリアルトランスポート（ホスト仲介、レガシー）

gRPC をサポートしないボード用の .proto ファイルを使用した単純な JSON:

リクエスト (ホスト → ペリフェラル):

{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}

レスポンス (周辺機器 → ホスト):

{"id":"1","ok":true,"result":"done"}

8. ファームウェア (別のリポジトリまたはクレート)

zeroclaw-firmware または zeroclaw-peripheral: 別個のクレート/ワークスペース。
ターゲット: thumbv7em-none-eabihf (STM32)、armv7-unknown-linux-gnueabihf (RPi) など。
embassy または STM32 用の Zephyr を使用します。
上記のプロトコルを実装します。
ユーザーがボードにフラッシュします。ZeroClaw は接続して機能を検出します。

9. 機能レイヤー

サブシステムはレイヤー構造で構築されており、各レイヤーは独立して使用できます。ここでフェーズの状態を追跡する（作業が完了するにつれてずれていく）のではなく、レイヤーは以下のとおりです。

スケルトン。 Peripheral トレイト、設定スキーマ、zeroclaw peripheral CLI。--peripheral フラグはボードをエージェントに接続します。
ホスト経由のディスカバリー。 zeroclaw hardware discover は USB デバイスを VID/PID で列挙し、ボードレジストリがそれらをアーキテクチャと名前にマッピングします。zeroclaw hardware introspect <path> はメモリマップとペリフェラル一覧を報告します。
シリアル / プローブトランスポート。 SerialPeripheral は USB CDC 経由で JSON プロトコルを伝送します。probe 機能は、フラッシュ、メモリマップ、メモリ読み取り用に probe-rs SWD を追加します（hardware_* ツールを参照）。
RAG パイプライン。 データシートはインデックス化され、ハードウェアのクエリ時に LLM コンテキストへ注入されます。

使用方法: zeroclaw config set peripherals.datasheet-dir docs/datasheets。ボード名で命名された .md または .txt ファイル（例: nucleo-f401re.md, rpi-gpio.md）を配置します。_generic/ ディレクトリ内のファイルや generic.md という名前のファイルは、すべてのボードに適用されます。チャンクはキーワードマッチによって取得され、ユーザーメッセージのコンテキストに挿入されます。
エッジネイティブ（Raspberry Pi）。 ZeroClaw は rppal によるネイティブ GPIO を介して Pi 上で動作します（peripheral-rpi 機能）。
ESP32。 シリアルトランスポート経由でホストを介在し、STM32 と同じ JSON プロトコルを使用します。ESP32 開発ボードは、CH340 USB VID/PID によってレジストリに登録されています。

使用方法: firmware/esp32 を ESP32 に書き込み、設定に board = "esp32"、transport = "serial"、path = "/dev/ttyUSB0" を追加します。
動的実行。 LLM が生成したロジックはパラメーター化されたテンプレートを通じて実行され、ユーザー定義ロジックの長期的な方向性としてサンドボックス化された Wasm ランタイムを採用します。

10. セキュリティに関する考慮事項

シリアルパス: path がアローリスト内にあることを検証します (例: /dev/ttyACM*、/dev/ttyUSB*)。任意のパスは禁止。
GPIO: 公開されるピンを制限します。電源/リセットピンを回避します。
周辺機器にシークレットなし: ファームウェアは API キーを保存しないでください。ホストが認証を処理します。

11. 非目標 (現在のところ)

フル ZeroClaw をベア STM32 上で実行する場合（WiFi なし、RAM 制限あり）は、代わりに Host-Mediated を使用してください
リアルタイム保証: 周辺機器はベストエフォート
LLM からの任意ネイティブコード実行: Wasm またはテンプレートを推奨

12. 関連ドキュメント

adding-boards-and-tools.md: ボードとデータシートの追加方法
network-deployment.md: RPi とネットワークデプロイメント

13. 参考資料

Zephyr RTOS Rust support
Embassy: 非同期組み込みフレームワーク
rppal: Rust による Raspberry Pi GPIO
STM32 Nucleo-F401RE
tonic: Rust 向け gRPC
probe-rs: ARM デバッグプローブ、フラッシュ、メモリアクセス
nusb: USB デバイスの列挙 (VID/PID)

14. Raw Prompt Summary

ESP、Raspberry Pi、またはWiFi搭載のボードのようなボードは、LLM（Geminiまたはオープンソース）に接続できます。ZeroClawはデバイス上で動作し、独自のgRPCを作成して起動し、周辺機器と通信します。ユーザーはWhatsApp経由で「Xアームを動かして」や「LEDを点灯して」とリクエストします。ZeroClawは正確なドキュメントを取得し、コードを記述して実行し、最適な形で保存して実行し、LEDを点灯させます。これらすべてが開発ボード上で行われます。

STM NucleoをUSB/J-Link経由でMacに接続した場合: Mac上のZeroClawがハードウェアにアクセスし、デバイスに必要なものをインストールまたは書き込み、結果を返します。例: ‘Hey ZeroClaw、このUSBデバイスで利用可能／読み取り可能なアドレスは何ですか?’ 接続されているものとその接続先を把握し、提案できます。

Keyboard shortcuts

ZeroClaw Docs