huawei-cloud-cloudrobo-r2c

Windows / PowerShell: Examples use bash syntax. To run on Windows PowerShell:

• Flatten \ line continuations to a single line, or end lines with a backtick.
• Set env vars with $env:NAME="value" instead of export NAME="value".
• Single-quoted JSON '{"a":"b"}' works as-is.

Overview 概述

The cloudrobo-r2c skill operates the R2C (Robot-to-Cloud) data-plane SDK. Unlike other cloudrobo skills that call REST APIs via cloudrobo-service, this skill runs long-lived data-plane processes that use Zenoh pub/sub with Protobuf serialization and mTLS authentication. It covers one CLI command: r2c client (robot edge client).

Applicable scenarios:

• Robot edge client — Start the robot-side process that bridges physical hardware to the cloud via Zenoh. Reads sensor observations from a hardware adapter, translates to R2C Protobuf messages, publishes to Zenoh, subscribes to cloud actions, translates back, and executes on hardware.
• Custom adapter development — Guide developers through implementing custom IRobotHardwareAdapter classes and ConfigurableDeviceTranslator mappings for robots not in the built-in adapter list.

Architecture:

                          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 accepts the access-config zip directly (or an extracted directory); the SDK resolves the certificate paths inside zenoh.json (which references a certs/-style layout) automatically. Do not manually rename the cert files.

The R2C data plane is decoupled from the CloudRobo REST API. The platform's cloudrobo-service handles robot registration and certificate export (covered by the robot skill); the R2C SDK consumes the exported credential bundle to establish mTLS-authenticated Zenoh sessions.

Prerequisites 前置条件

• See references/cli-installation-guide.md for CLI installation, R2C package extras, and credential bundle preparation.
• A valid credential bundle — produced by cloudrobo robot export-certificate (robot skill). The bundle contains device_info.json, zenoh.json, ca.pem, server_cert.pem, and server_key.pem.
• A robot config YAML — defines the hardware adapter, translator, and device-to-R2C field mappings.
• The robot must be registered on the CloudRobo platform (use the robot skill: create → export-certificate). The robot_id in the credential bundle identifies the robot.

Workflow 工作流

Robot Edge Client Startup Workflow 机器人边缘客户端启动

Scenario: "Start the R2C client on the robot to stream observations and execute cloud actions."

1. Start the client — Launch the edge client with the credential bundle and robot config. export-certificate writes cert_config_<robot-name>_<timestamp>.zip into the output directory — pass that zip path to --bundle:

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

   If the private key is encrypted, you will be prompted for a password (or use --private-key-password / --private-key-password-env).
2. Verify connection — Check log output for "Heartbeat auto publish started" and "Starting cloudroboclient" messages. The client publishes observations and subscribes to actions in a control loop.
3. Stop — Press Ctrl+C for graceful shutdown (hardware disconnect → session close).

Dry-Run Testing Workflow 干运行测试

Scenario: "Test the R2C client without moving the real robot."

1. Set dry_run — In the robot config YAML, set runtime.dry_run: true. This publishes real observations but does not execute received actions (logs only).
2. Start client — Launch with the dummy adapter or real hardware:

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

3. Verify observation publishing — Check logs for observation publish events. On the cloud side, verify observations are received.
4. Test action receiving — From the cloud adapter or a test publisher, send a test action. Verify the action is logged but not executed (dry_run mode).
5. Disable dry_run — Set runtime.dry_run: false and restart for real execution.

Custom Adapter Development Workflow 自定义适配器开发

Scenario: "My robot is not in the built-in adapter list. How do I add support?"

The R2C SDK provides two approaches for custom adapters: entry_point registration (recommended for reusable, shareable adapters) and CLI override (for quick prototyping).

Approach A: Entry-Point Registration (Recommended) 入口点注册（推荐）

1. Review the guide — See references/custom-adapter-guide.md for the full development guide.
2. Implement adapter class — Create a class implementing IRobotHardwareAdapter (connect(), disconnect(), get_observation(), send_action()).
3. Implement factory function — Create a factory function that returns an adapter instance: def create_my_adapter(config, **kwargs) -> IRobotHardwareAdapter.
4. Register via entry_point — In your package's pyproject.toml, register under [project.entry-points."r2c_sdk.adapters"]: my_robot = "my_adapter_module:create_my_adapter".
5. Install package — pip install . registers the adapter under the r2c_sdk.adapters entry-point group, making it discoverable by the SDK's AdapterRegistry (used by RobotFactory and robot-config schema validation).
6. Configure — Set hardware.type: "my_robot" (matching the entry_point name) in the robot config YAML. No --hardware-class CLI override needed.
7. Optionally register commands — Use register_command_class() in __post_init__ for custom commands (e.g., go_home), then reference them in hardware.config.commands in the robot config.
8. Configure translator — Use ConfigurableDeviceTranslator with device_to_r2c and r2c_to_device mapping sections in the robot config YAML.
9. Test with dry_run — Validate config → start client with dry_run: true → verify observation publishing and action logging.
10. Test real execution — Disable dry_run and verify the robot moves correctly.

Approach B: CLI Override (Quick Prototyping) CLI 覆盖（快速原型）

1. Implement adapter class — Same as above, but no entry_point registration needed.
2. Configure — Set hardware.type: "custom" and hardware.class_path to the dotted import path of your adapter class in the robot config YAML. Alternatively, use --hardware-class my_pkg.my_module.MyAdapter on the CLI.
3. Test with dry_run — Validate config → start client with dry_run: true → verify observation publishing and action logging.
4. Test real execution — Disable dry_run and verify the robot moves correctly.

When to use which: Use entry_point registration when the adapter will be reused across projects or shared with other teams. Use CLI override for one-off testing or when you cannot create a separate package.

Observation Recording Workflow 观测录制

Scenario: "Record observations for later playback analysis."

1. Start with --record — cloudrobo r2c client --bundle <bundle> --robot-config <config> --record ./observations.pkl
2. Operate — Run the robot normally; observations are serialized to the .pkl file.
3. Playback — Use the playback adapter type with the recorded file for replay.

CLI Command Format Standard CLI命令格式标准

cloudrobo r2c client [OPTIONS]

Core Commands 核心命令

Start Robot Edge Client

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]

Alternative (without bundle, using client config + explicit parameters):

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

Connection priority: --bundle (recommended) > --client-config > explicit CLI params (requires --project-id and --device-id).

Lifecycle: load_yaml(robot_config) → build_session(args) → _maybe_start_heartbeats(session, robot_config) → build_sync_robot_client(...) → hardware_adapter.connect() → robot_client.start() → wait (duration or Ctrl+C) → robot_client.stop() → hardware_adapter.disconnect() → session.close().

Built-in Hardware Adapters

The following hardware adapter types are registered via r2c_sdk.adapters entry points and can be used by setting hardware.type in the robot config YAML:

The a1z adapter is registered in pyproject.toml but requires the [a1z] extra (python-can, pin) and the GALAXEA-A1Z SDK. Installing cloudrobo-r2c[all] includes it.

Custom adapters can also be loaded via --hardware-class (dotted import path) or hardware.type: "custom" + hardware.class_path in the robot config. See references/custom-adapter-guide.md for details.

Parameter Confirmation 参数确认

Starting the client is a long-running, externally visible operation. Confirm the credential bundle, robot config, and endpoint reachability before launching.

Reference Documents 参考文档

• CLI Installation Guide — cloudrobo CLI installation, R2C package extras, credential bundle preparation
• Authentication & Access Control — mTLS credential bundle model, Zenoh security
• Dataflow Diagram — Mermaid data flow diagrams for R2C data plane
• Verification Method — Verification method details
• Acceptance Criteria — Acceptance criteria
• Client Config Reference — client_config.yaml field mapping, Zenoh QoS settings
• Robot Config Reference — Robot config YAML schema (v2.1), hardware/translator/mapping sections
• Custom Adapter Guide — IRobotHardwareAdapter interface, ConfigurableDeviceTranslator, dry_run testing

Edge Cases 边界情况

Verification Method 验证方法

Specification Compliance Verification 规范合规验证

bash scripts/test-cli-commands.sh

Functional Testing 功能测试

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

Test Cases 测试用例

See templates/test-vars.json for the full test case list covering client startup, dry_run scenarios, and observation recording.

Verification Checklist 验证清单

• r2c client with --bundle and a valid robot config starts and logs heartbeat/connection messages
• r2c client with dry_run: true publishes observations but does not execute actions
• Encrypted private key triggers password prompt (or fails with --no-prompt-password)
• --duration N stops the client after N seconds
• --record produces a non-empty .pkl file
• --log-file produces a rotating log file

Best Practices 最佳实践

• Verify your robot config YAML is valid before starting the client to catch configuration errors early
• Use --bundle (recommended) instead of explicit --project-id/--device-id for simpler setup
• Refer to the built-in adapters list above to identify which robot types are supported
• Start with dry_run: true to verify observation publishing without risking robot movement
• Use the dummy adapter for development and testing when real hardware is unavailable
• Set --duration for timed tests instead of running indefinitely during development
• Use --log-level DEBUG and --log-file for detailed troubleshooting
• Use --private-key-password-env instead of --private-key-password to avoid secrets in shell history
• For custom adapters, implement all four IRobotHardwareAdapter methods and test with dry_run first
• Use ConfigurableDeviceTranslator (config-driven mapping) instead of writing a custom translator class when possible
• Record observations with --record for offline analysis and playback testing
• Keep heartbeat enabled (default) for connection health monitoring; disable only for debugging
• The credential bundle is produced by the robot skill — do not attempt to create one manually