huawei-cloud-cloudrobo-r2c

Windows / PowerShell： 示例使用 bash 语法。在 Windows PowerShell 中运行时：

• 将 \ 续行符合并为一行，或在行尾使用反引号。
• 使用 $env:NAME="value" 设置环境变量，而不是 export NAME="value"。
• 单引号括起来的 JSON '{"a":"b"}' 可直接使用。

概述 概述

cloudrobo-r2c 技能用于操作 R2C（Robot-to-Cloud）数据平面 SDK。与其他通过 cloudrobo-service 调用 REST API 的 cloudrobo 技能不同，此技能会运行长时间运行的数据平面进程，这些进程使用 Zenoh pub/sub、Protobuf 序列化和 mTLS 身份验证。它涵盖一条 CLI 命令：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 为自定义适配器提供两种方式：入口点注册 （推荐用于可复用、可共享的适配器）和 CLI 覆盖（适用于快速原型开发）。

方式 A：入口点注册（推荐）

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 入口点组，使 SDK 的 AdapterRegistry 能够发现它（RobotFactory 和机器人配置架构验证会使用该注册表）。
6. 配置 — 在机器人配置 YAML 中设置 hardware.type: "my_robot"（与 entry_point 名称一致）。无需使用 --hardware-class CLI 覆盖。
7. 可选：注册命令 — 在 __post_init__ 中使用 register_command_class() 注册自定义命令（例如 go_home），然后在 机器人配置的 hardware.config.commands 中引用它们。
8. 配置转换器 — 使用 ConfigurableDeviceTranslator，并在机器人配置 YAML 中设置 device_to_r2c 和 r2c_to_device 映射部分。
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

核心命令

启动 Robot Edge 客户端

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]

替代方式（不使用 bundle，通过客户端配置和显式参数）：

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	凭证 bundle 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 (default)	仅在检测到加密密钥时提示输入密码
--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	用户	否（仅当密钥已加密时）	已屏蔽；绝不回显

启动客户端是一项长时间运行且对外可见的操作。 启动前，请确认凭据 bundle、机器人配置和端点的可访问性。

参考文档

• CLI 安装指南 — cloudrobo CLI 安装、R2C 软件包 extras、凭据 bundle 准备
• 身份验证与访问控制 — mTLS 凭据 bundle 模型、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 详细列出所有架构错误
未知硬件适配器类型	对于列表中没有的机器人，使用 custom 类型和 --hardware-class；参见上方的内置适配器列表
安装后找不到第三方适配器	确认 pyproject.toml 中的 [project.entry-points."r2c_sdk.adapters"] 已注册 entry_point；使用 pip install -e . 重新安装
Zenoh 连接失败	客户端报错，提示 R2CConnectionError；检查端点、TLS 证书和网络
dry_run 模式	按常规发布观测结果；接收到的动作会记录日志，但不会在硬件上执行
时长为 0	客户端会一直运行，直到按下 Ctrl+C 或进程终止
机器人配置缺少必填字段	客户端启动失败，并针对缺少的 hardware.type、translator.type 或映射部分提示 ValidationError
禁用心跳	在机器人配置中设置 runtime.heartbeat.enabled: false；不发送心跳消息
观测记录	--record 路径必须可写；观测结果以 .pkl（pickle 格式）保存
配置目录解析	将 _config_dir 注入 robot_config，以解析相对路径（例如，自定义适配器模块的路径）
键盘控制	通过 runtime.keyboard_control.enabled: true 启用；空格键=暂停/恢复，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；使用 Zenoh pub/sub 和 Protobuf 序列化
会产生变更的操作	启动 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

测试用例

完整的测试用例列表请参见 templates/test-vars.json，涵盖客户端启动、dry_run 场景和观测记录。

验证清单

• 使用 --bundle 和有效的机器人配置运行 r2c client，客户端应启动并记录心跳/连接消息
• 使用 dry_run: true 运行 r2c client，客户端应发布观测结果，但不执行动作
• 加密的私钥会触发密码提示（或在使用 --no-prompt-password 时失败）
• --duration N 会在 N 秒后停止客户端
• --record 会生成非空的 .pkl 文件
• --log-file 会生成轮转日志文件

最佳实践

• 启动客户端前，验证机器人配置 YAML 是否有效，以便及早发现配置错误
• 使用 --bundle（推荐），而不是显式指定 --project-id/--device-id，以简化设置
• 参考上方内置适配器列表，确认支持哪些机器人类型
• 从 dry_run: true 开始，在不冒机器人移动风险的情况下验证观测数据发布
• 没有可用实体硬件时，使用 dummy 适配器进行开发和测试
• 进行定时测试时设置 --duration，不要在开发期间无限期运行
• 使用 --log-level DEBUG 和 --log-file 进行详细故障排查
• 使用 --private-key-password-env，而不是 --private-key-password，以避免机密信息留在 shell 历史记录中
• 对于自定义适配器，实现全部四个 IRobotHardwareAdapter 方法，并先使用 dry_run 进行测试
• 尽可能使用 ConfigurableDeviceTranslator（由配置驱动的映射），而不是编写自定义转换器类
• 使用 --record 记录观测数据，以便进行离线分析和回放测试
• 保持心跳启用（默认设置），用于监控连接状态；仅在调试时禁用
• 凭据包由 robot 技能生成——请勿尝试手动创建