huawei-cloud-cloudrobo-r2c

Windows / PowerShell： 例では bash 構文を使用しています。Windows PowerShell で実行するには：

• \ による行継続を1行にまとめるか、行末にバッククォートを付けます。
• export NAME="value" の代わりに $env:NAME="value" で環境変数を設定します。
• シングルクォートで囲んだ JSON '{"a":"b"}' はそのまま使用できます。

概要

cloudrobo-r2c スキルは、R2C（Robot-to-Cloud）データプレーン SDK を操作します。cloudrobo-service 経由で REST API を呼び出す他の cloudrobo スキルとは異なり、このスキルは Zenoh pub/sub、Protobuf シリアライゼーション、mTLS 認証を使用する長時間稼働するデータプレーンプロセスを実行します。対象となる CLI コマンドは1つです：r2c client（ロボット側エッジクライアント）。

適用シナリオ：

• ロボットエッジクライアント — 物理ハードウェアとクラウドを Zenoh 経由で接続するロボット側プロセスを起動します。ハードウェアアダプターからセンサーの観測データを読み取り、R2C Protobuf メッセージに変換して Zenoh にパブリッシュし、クラウドからのアクションをサブスクライブして元の形式に戻し、ハードウェアで実行します。
• カスタムアダプターの開発 — 組み込みアダプター一覧にないロボット向けに、カスタムの IRobotHardwareAdapter クラスと ConfigurableDeviceTranslator マッピングを実装する方法を開発者に案内します。

アーキテクチャ：

                          Zenoh pub/sub (mTLS)
  ┌─────────────┐  observations  ┌──────────────────┐
  │ Robot Edge  │ ─────────────► │                  │
  │ Client      │                │  Zenoh Router    │
  │ (r2c client)│ ◄───────────── │                  │
  └──────┬──────┘     actions    └──────────────────┘
         │
  ┌──────▼──────┐
  │ Hardware     │
  │ Adapter      │
  │ (robot arm,  │
  │  gripper...) │
  └─────────────┘

  Credential Bundle (from robot skill export-certificate)
  ├── device_info.json   (account_id, robot_id, permission_role)
  ├── zenoh.json         (mode, endpoints, mTLS config)
  ├── ca.pem             (CA certificate)
  ├── server_cert.pem    (client certificate — note: named server_cert.pem in the exported bundle)
  └── server_key.pem     (private key, optionally encrypted)

--bundle にはアクセス設定の zip ファイルを直接（または展開済みディレクトリを）指定できます。SDK は zenoh.json 内の証明書パス（certs/ 形式のレイアウトを参照）を自動的に解決します。 証明書ファイルの名前を手動で変更しないでください。

R2C データプレーンは CloudRobo REST API から分離されています。プラットフォームの cloudrobo-service はロボットの登録と証明書のエクスポートを処理し（robot スキルで説明）、R2C SDK はエクスポートされた認証情報バンドルを使用して、mTLS 認証済みの Zenoh セッションを確立します。

前提条件

• CLI のインストール、R2C パッケージの追加機能、認証情報バンドルの準備については、references/cli-installation-guide.md を参照してください。
• 有効な認証情報バンドル — cloudrobo robot export-certificate（robot スキル）で生成されます。バンドルには device_info.json、zenoh.json、ca.pem、server_cert.pem、server_key.pem が含まれます。
• ロボット設定 YAML — ハードウェアアダプター、トランスレーター、デバイスから R2C へのフィールドマッピングを定義します。
• ロボットは CloudRobo プラットフォームに登録済みである必要があります（robot スキルを使用：作成 → export-certificate）。認証情報バンドル内の robot_id はロボットを識別します。

ワークフロー

ロボットエッジクライアントの起動ワークフロー

シナリオ：「ロボット上で R2C クライアントを起動し、観測データをストリーミングしてクラウドのアクションを実行する。」

1. クライアントを起動する — 認証情報バンドルとロボット設定を指定してエッジクライアントを起動します。export-certificate は出力ディレクトリに cert_config_<robot-name>_<timestamp>.zip を書き込みます。この zip ファイルのパスを --bundle に指定します：

   cloudrobo r2c client --bundle <path/to/cert_config_*.zip> --robot-config config/robot_dummy_config.yaml
   

   秘密鍵が暗号化されている場合は、パスワードの入力を求められます（または --private-key-password / --private-key-password-env を使用します）。
2. 接続を確認する — ログ出力に「Heartbeat auto publish started」と「Starting cloudroboclient」のメッセージがあることを確認します。クライアントは制御ループ内で観測データをパブリッシュし、アクションをサブスクライブします。
3. 停止する — Ctrl+C を押すと正常にシャットダウンします（ハードウェアの切断 → セッションの終了）。

ドライランテストワークフロー

シナリオ：「実際のロボットを動かさずに R2C クライアントをテストする。」

1. dry_run を設定する — ロボット設定 YAML で runtime.dry_run: true を設定します。実際の観測データはパブリッシュされますが、受信したアクションは実行されず、ログにのみ記録されます。
2. クライアントを起動する — ダミーアダプターまたは実際のハードウェアを使用して起動します：

   cloudrobo r2c client --bundle <bundle> --robot-config config/robot_dummy_config.yaml
   

3. 観測データのパブリッシュを確認する — 観測データのパブリッシュイベントがログに記録されていることを確認します。クラウド側で観測データが受信されていることを確認します。
4. アクションの受信をテストする — クラウドアダプターまたはテスト用パブリッシャーからテストアクションを送信します。アクションが実行されず、ログにのみ記録されること（dry_run モード）を確認します。
5. dry_run を無効にする — runtime.dry_run: false を設定し、実際の実行に向けて再起動します。

カスタムアダプターの開発ワークフロー

シナリオ：「使用するロボットが組み込みアダプターの一覧にありません。対応させるにはどうすればよいですか？」

R2C SDK では、カスタムアダプターを追加する方法が 2 つあります。entry_point による登録 （再利用や共有が可能なアダプターに推奨）と CLI によるオーバーライド（迅速なプロトタイピング向け）です。

方法 A：entry_point による登録（推奨）

1. ガイドを確認する — 詳細な開発ガイドについては、references/custom-adapter-guide.md を参照してください。
2. アダプタークラスを実装する — IRobotHardwareAdapter を実装するクラスを作成します （connect()、disconnect()、get_observation()、send_action()）。
3. ファクトリー関数を実装する — アダプターのインスタンスを返すファクトリー関数を作成します： def create_my_adapter(config, **kwargs) -> IRobotHardwareAdapter.
4. entry_point で登録する — パッケージの pyproject.toml で、次の項目に登録します： [project.entry-points."r2c_sdk.adapters"]：my_robot = "my_adapter_module:create_my_adapter".
5. パッケージをインストールする — pip install . を実行すると、アダプターが r2c_sdk.adapters entry-point グループに登録され、SDK の AdapterRegistry （RobotFactory とロボット設定のスキーマ検証で使用）から検出できるようになります。
6. 設定する — ロボット設定 YAML で hardware.type: "my_robot"（entry_point 名と一致）を指定します。 --hardware-class による CLI オーバーライドは不要です。
7. 必要に応じてコマンドを登録する — カスタムコマンド（例：go_home）には、 __post_init__ で register_command_class() を使用し、ロボット設定の hardware.config.commands で参照します。
8. トランスレーターを設定する — ロボット設定 YAML の device_to_r2c と r2c_to_device マッピングセクションで ConfigurableDeviceTranslator を使用します。
9. dry_run でテストする — 設定を検証し、dry_run: true でクライアントを起動して、 オブザベーションの公開とアクションのログ記録を確認します。
10. 実際の実行をテストする — dry_run を無効にし、ロボットが正しく動作することを確認します。

方法 B：CLI によるオーバーライド（迅速なプロトタイピング）

1. アダプタークラスを実装する — 上記と同様ですが、entry_point による登録は不要です。
2. 設定する — ロボット設定 YAML で hardware.type: "custom" を指定し、 hardware.class_path にアダプタークラスのドット区切りのインポートパスを設定します。 代わりに、CLI で --hardware-class my_pkg.my_module.MyAdapter を使用することもできます。
3. dry_run でテストする — 設定を検証し、dry_run: true でクライアントを起動して、 オブザベーションの公開とアクションのログ記録を確認します。
4. 実際の実行をテストする — dry_run を無効にし、ロボットが正しく動作することを確認します。

どちらを使うべきか： アダプターを複数のプロジェクトで再利用する場合や、他のチームと共有する場合は、entry_point による登録を使用してください。単発のテストや、別のパッケージを作成できない場合は、CLI によるオーバーライドを使用してください。

オブザベーション記録ワークフロー

シナリオ：「後で再生して分析できるように、オブザベーションを記録します。」

1. --record を指定して起動する — cloudrobo r2c client --bundle <bundle> --robot-config <config> --record ./observations.pkl
2. 操作する — 通常どおりロボットを動かすと、オブザベーションが .pkl ファイルにシリアライズされます。
3. 再生する — 記録したファイルを指定して、playback アダプタータイプを使用します。

CLI コマンド形式の標準

cloudrobo r2c client [OPTIONS]

機能	説明	例
コマンドグループ	r2c（エントリーポイント経由で登録）	cloudrobo r2c
サブコマンド	client	cloudrobo r2c client
認証情報バンドル	--bundle <path>（zip またはディレクトリ、推奨）	--bundle ./cert.zip
クライアント設定	--client-config <path>（デフォルトは config/client_config.yaml）	--bundle の代わりに使用
ロボット設定	--robot-config <path>（デフォルトは config/robot_dummy_config.yaml）	--robot-config config/robot_jaka_sdk_config.yaml
エンドポイント	--endpoints tls/127.0.0.1:7447（カンマ区切り）	Zenoh ルーターアドレス
出力形式	ログを stdout/stderr に出力	構造化ログ
長時間実行	Ctrl+C または --duration が指定されるまで実行	--duration 60

コアコマンド

ロボットエッジクライアントを起動する

cloudrobo r2c client --bundle <path/to/cert_config_*.zip> --robot-config config/robot_dummy_config.yaml [--client-config config/client_config.yaml] [--duration 0] [--log-level INFO] [--log-file ./r2c.log] [--record ./observations.pkl] [--hardware-class my_pkg.my_module.MyAdapter] [--translator-class my_pkg.my_module.MyTranslator] [--private-key-password <password>] [--private-key-password-env <ENV_VAR>] [--no-prompt-password]

代替方法（バンドルを使わず、クライアント設定と明示的なパラメーターを使用）：

cloudrobo r2c client --client-config config/client_config.yaml --project-id <project-id> --device-id <device-id> --endpoints tls/127.0.0.1:7447 --mode peer --robot-config config/robot_dummy_config.yaml

接続の優先順位： --bundle（推奨） > --client-config > 明示的な CLI パラメーター （--project-id と --device-id が必要です）。

ライフサイクル： load_yaml(robot_config) → build_session(args) → _maybe_start_heartbeats(session, robot_config) → build_sync_robot_client(...) → hardware_adapter.connect() → robot_client.start() → 待機（指定時間または Ctrl+C） → robot_client.stop() → hardware_adapter.disconnect() → session.close()。

パラメーター	デフォルト	説明
--bundle	None	認証情報バンドルの zip／ディレクトリへのパス（推奨。client-config より優先されます）
--client-config	config/client_config.yaml	R2C クライアント設定 YAML へのパス
--project-id	None	プロジェクト ID（bundle と client-config のどちらも指定しない場合に必須）
--device-id	None	デバイス ID（bundle と client-config のどちらも指定しない場合に必須）
--client-id	None	クライアント ID（デフォルトは sync-robot-client）
--endpoints	""	カンマ区切りの Zenoh エンドポイント。例：tls/127.0.0.1:7447
--mode	peer	Zenoh モード：peer または client
--endpoint-role	None	connect（アクティブ、デフォルト）または listen（パッシブ）
--robot-config	config/robot_dummy_config.yaml	ロボット設定 YAML へのパス
--hardware-class	None	カスタム IRobotHardwareAdapter のドット区切りクラスパス
--translator-class	None	カスタム IDeviceTranslator のドット区切りクラスパス
--duration	0.0	実行時間（秒）。0 = 無期限に実行
--log-level	INFO	ログレベル：CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET
--log-file	None	ローテーションするログファイルのパス（最大 100 MB、バックアップ 5 個）
--record	None	記録した観測データ（.pkl）の保存先パス
--private-key-password	None	暗号化された server_key.pem のパスワード
--private-key-password-env	None	パスワードを格納する環境変数名
--prompt-password	True（デフォルト）	暗号化されたキーが検出された場合にのみパスワードを求めます
--no-prompt-password	False	パスワードを求めず、パスワードが必要な場合は失敗します

組み込みハードウェアアダプター

次のハードウェアアダプタータイプは r2c_sdk.adapters エントリーポイント経由で登録されており、 ロボット設定 YAML で hardware.type を設定すると使用できます。

アダプター	説明
dummy	テストと開発向けのシミュレートされたロボット
a1z	A1Z + G1Z グリッパー（6 自由度アーム、SocketCAN 経由の GALAXEA-A1Z SDK）
lerobot	LeRobot 互換ロボット（SO-101 など）
ros2	ROS 2 ベースのロボット
raw_sdk	VendorSDKHardwareAdapter 経由のベンダー SDK
jaka	Jaka ロボットアーム
ur5e_rtde	RTDE 経由の Universal Robots UR5e
zenoh_ros1	Zenoh ブリッジ経由の ROS 1 ロボット
flexiv	Flexiv ロボットアーム
playback	記録した観測データを再生
moz1	MOZ1 ロボット
q25	Q25 ロボット（直接 SDK）
q25_ros2	ROS 2 経由の Q25 ロボット
tsd	TSD ロボット

a1z アダプターは pyproject.toml で登録されていますが、[a1z] extra （python-can、pin）と GALAXEA-A1Z SDK が必要です。cloudrobo-r2c[all] をインストールすると含まれます。

カスタムアダプターは --hardware-class（ドット区切りのインポートパス）または ロボット設定の hardware.type: "custom" + hardware.class_path からも読み込めます。 詳細は references/custom-adapter-guide.md を参照してください。

パラメーターの確認

パラメーター	ソース	必須	確認事項
--bundle	ユーザー（robot skill export-certificate から）	はい（推奨）	ファイルが存在し、読み取り可能であることを確認します
--robot-config	ユーザー	はい	開始前に YAML が有効であることを確認します
--client-config	ユーザー	いいえ（bundle にフォールバック）	—
--project-id / --device-id	ユーザー	はい（bundle がない場合）	プラットフォームへの登録情報と照合します
--endpoints	ユーザーまたは bundle	いいえ（bundle から取得）	Zenoh ルーターに到達できることを確認します
--hardware-class	ユーザー	いいえ	クラスが IRobotHardwareAdapter を実装していることを確認します
--duration	ユーザー	いいえ	0 = 無期限で実行。時間制限付きのテストでは値を設定します
--record	ユーザー	いいえ	出力パスに書き込み可能であることを確認します
--private-key-password	ユーザー	いいえ（キーが暗号化されている場合のみ）	マスクされます。決してそのまま表示しないでください

クライアントの起動は、長時間にわたり外部から確認できる操作です。 起動前に、認証情報バンドル、ロボット設定、エンドポイントへの到達性を確認してください。

参考ドキュメント

• CLI インストールガイド — cloudrobo CLI のインストール、R2C パッケージの追加機能、認証情報バンドルの準備
• 認証とアクセス制御 — mTLS 認証情報バンドルモデル、Zenoh セキュリティ
• データフロー図 — R2C データプレーンの Mermaid データフロー図
• 検証方法 — 検証方法の詳細
• 受け入れ基準 — 受け入れ基準
• クライアント設定リファレンス — client_config.yaml のフィールドマッピング、Zenoh QoS 設定
• ロボット設定リファレンス — ロボット設定 YAML スキーマ（v2.1）、ハードウェア／トランスレーター／マッピングの各セクション
• カスタムアダプターガイド — IRobotHardwareAdapter インターフェース、ConfigurableDeviceTranslator、dry_run テスト

エッジケース

シナリオ	対応
認証情報バンドルがない	クライアントはエラーで終了します。cloudrobo robot export-certificate を使ってバンドルを生成してください
暗号化された秘密鍵	パスワードの入力を求めます（デフォルト）。または --private-key-password / --private-key-password-env を使ってください。パスワードが必要な場合、--no-prompt-password を指定すると失敗します
無効なロボット設定	クライアントの起動に失敗し、すべてのスキーマエラーの詳細を示す ValidationError が表示されます
不明なハードウェアアダプターの種類	リストにないロボットには、--hardware-class とともに custom タイプを使用してください。上記の組み込みアダプター一覧を参照してください
インストール後にサードパーティ製アダプターが見つからない	pyproject.toml の [project.entry-points."r2c_sdk.adapters"] に entry_point が登録されていることを確認してください。pip install -e . で再インストールしてください
Zenoh 接続の失敗	クライアントは R2CConnectionError で終了します。エンドポイント、TLS 証明書、ネットワークを確認してください
dry_run モード	観測データは通常どおり公開されます。受信したアクションはログに記録されますが、ハードウェアでは実行されません
Duration が 0	Ctrl+C またはプロセスの終了まで、クライアントは無期限に実行されます
ロボット設定に必須フィールドがない	hardware.type、translator.type、またはマッピングセクションがない場合、クライアントの起動に失敗し、ValidationError が表示されます
ハートビートが無効	ロボット設定で runtime.heartbeat.enabled: false を設定してください。ハートビートメッセージは送信されません
観測データの記録	--record のパスは書き込み可能である必要があります。観測データは .pkl（pickle 形式）として保存されます
設定ディレクトリの解決	相対パスを解決するため、_config_dir が robot_config に挿入されます（例：カスタムアダプターモジュール）
キーボード操作	runtime.keyboard_control.enabled: true で有効になります。space＝一時停止／再開、h＝ホーム位置へ移動（一時停止中）、e＝正常終了
アクションのタイムアウト	runtime.action_response_timeout_s で待機時間を制御します。バックオフは _initial_s と _backoff で設定します
アクションチャンクの位置合わせ	runtime.enable_action_chunk_alignment は軌道のジャンプを防ぎます。デフォルトは false です
非同期リクエストの融合	runtime.async_request で観測データの融合戦略（replace/weighted_average/nearest_neighbor）を設定します
スキル間の依存関係	このスキルは認証情報バンドルの生成に robot スキルを依存先とします。robot スキルを直接呼び出すことはありません
API パス	このスキルは REST API を呼び出しません。Protobuf シリアライゼーションを使用した Zenoh pub/sub を利用します
状態を変更する操作	r2c client の起動は長時間実行されるプロセスです。起動前にパラメーターを確認してください
obs:// パス	このスキルには該当しません。R2C はオブジェクトストレージではなく Zenoh トピックを使用します

検証方法

仕様準拠の検証

bash scripts/test-cli-commands.sh

機能テスト

# CLI (optionally scope workspace tests: bash scripts/test-cli-commands.sh -w <workspace-id>)
bash scripts/test-cli-commands.sh

テストケース

クライアントの起動、dry_run のシナリオ、観測データの記録を網羅したテストケースの全一覧については、templates/test-vars.json を参照してください。

検証チェックリスト

• --bundle と有効なロボット設定を指定した r2c client が起動し、ハートビート／接続メッセージをログに記録する
• dry_run: true を指定した r2c client は観測データを公開しますが、アクションを実行しない
• 暗号化された秘密鍵ではパスワードの入力が求められる（または --no-prompt-password を指定すると失敗する）
• --duration N を指定すると、N 秒後にクライアントが停止する
• --record によって空でない .pkl ファイルが生成される
• --log-file によってローテーションされるログファイルが生成される

ベストプラクティス

• 設定エラーを早期に検出できるよう、クライアントを起動する前にロボットの設定 YAML が有効であることを確認します
• 設定を簡単にするため、明示的な --project-id／--device-id の代わりに --bundle（推奨）を使用します
• 対応しているロボットの種類を確認するには、上記の組み込みアダプターの一覧を参照します
• ロボットを動かすリスクを避けながら観測データの公開を確認するには、まず dry_run: true を設定します
• 実機が利用できない場合は、開発とテストに dummy アダプターを使用します
• 開発中に無期限で実行するのではなく、時間を指定したテストには --duration を設定します
• 詳細なトラブルシューティングには、--log-level DEBUG と --log-file を使用します
• シェルの履歴にシークレットが残らないよう、--private-key-password の代わりに --private-key-password-env を使用します
• カスタムアダプターでは、IRobotHardwareAdapter の 4 つのメソッドすべてを実装し、まず dry_run でテストします
• 可能な場合は、カスタムのトランスレータークラスを書く代わりに、ConfigurableDeviceTranslator（設定主導のマッピング）を使用します
• オフライン分析や再生テストのために、--record で観測データを記録します
• 接続の健全性を監視するため、ハートビートは有効（デフォルト）のままにします。デバッグ時に限り無効にします
• 認証情報バンドルは robot スキルによって生成されます。手動で作成しようとしないでください