Run the R2C (Robot-to-Cloud) data-plane client — start the robot-side edge client (Zenoh pub/sub with mTLS credential bundle, hardware adapter, translator, control loop). The credential bundle is produced by the robot skill's export-certificate command. This skill does NOT cover robot registration or certificate export (use the robot skill). Triggers include: r2c client, robot edge client, Zenoh, mTLS, credential bundle, hardware adapter, robot config, dry_run, observation recording, custom adapter, robot-to-cloud, 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.
--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."
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:
bash
If the private key is encrypted, you will be prompted for a password (or use
--private-key-password / --private-key-password-env).
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.
Verify observation publishing — Check logs for observation publish events. On the
cloud side, verify observations are received.
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).
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).
Review the guide — See references/custom-adapter-guide.md for the full development guide.
Implement adapter class — Create a class implementing IRobotHardwareAdapter
(connect(), disconnect(), get_observation(), send_action()).
Implement factory function — Create a factory function that returns an adapter instance:
def create_my_adapter(config, **kwargs) -> IRobotHardwareAdapter.
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".
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).
Configure — Set hardware.type: "my_robot" (matching the entry_point name) in the
robot config YAML. No --hardware-class CLI override needed.
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.
Configure translator — Use ConfigurableDeviceTranslator with device_to_r2c and
r2c_to_device mapping sections in the robot config YAML.
Test with dry_run — Validate config → start client with dry_run: true → verify
observation publishing and action logging.
Test real execution — Disable dry_run and verify the robot moves correctly.
Implement adapter class — Same as above, but no entry_point registration needed.
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.
Test with dry_run — Validate config → start client with dry_run: true → verify
observation publishing and action logging.
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."
Prompt for password only when encrypted key detected
--no-prompt-password
False
Never prompt; fail if password required
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:
Adapter
Description
dummy
Simulated robot for testing and development
a1z
A1Z + G1Z gripper (6-DOF arm, GALAXEA-A1Z SDK via SocketCAN)
lerobot
LeRobot-compatible robots (SO-101, etc.)
ros2
ROS 2 based robots
raw_sdk
Vendor SDK via VendorSDKHardwareAdapter
jaka
Jaka robotic arms
ur5e_rtde
Universal Robots UR5e via RTDE
zenoh_ros1
ROS 1 robots via Zenoh bridge
flexiv
Flexiv robotic arms
playback
Replay recorded observations
moz1
MOZ1 robot
q25
Q25 robot (direct SDK)
q25_ros2
Q25 robot via ROS 2
tsd
TSD robot
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 参数确认
Parameter
Source
Required
Confirmation Needed
--bundle
User (from robot skill export-certificate)
Yes (recommended)
Verify file exists and is readable
--robot-config
User
Yes
Ensure YAML is valid before starting
--client-config
User
No (fallback to bundle)
If omitted and no bundle, falls back to SDK built-in config/client_config.yaml (endpoints tcp/127.0.0.1:7447); provide one, a bundle, or explicit parameters
--project-id / --device-id
User
Yes (if no bundle)
Required to connect via client-config instead of a bundle
--endpoints
User or bundle
No (from bundle)
Verify Zenoh router is reachable
--hardware-class
User
No
Verify class implements IRobotHardwareAdapter
--duration
User
No
0 = run forever; set a value for timed tests
--record
User
No
Ensure output path is writable
--private-key-password
User
No (only if key encrypted)
Masked; never echo back
Starting the client is a long-running, externally visible operation.
Confirm the credential bundle, robot config, and endpoint reachability before launching.
With no bundle and no client-config, client silently falls back to SDK built-in config/client_config.yaml (endpoints tcp/127.0.0.1:7447); the connection fails and retries indefinitely in background (--duration is not honored). Provide --bundle, a --client-config, or explicit --project-id/--device-id/reachable --endpoints
Encrypted private key
Prompt for password (default), or use --private-key-password / --private-key-password-env; --no-prompt-password fails if password required
Invalid robot config
Client startup fails with ValidationError details listing all schema errors
Unknown hardware adapter type
Use custom type with --hardware-class for unlisted robots; see built-in adapters list above
Third-party adapter not found after install
Verify entry_point is registered in pyproject.toml under [project.entry-points."r2c_sdk.adapters"]; reinstall with pip install -e .
Zenoh connection failure
Client fails with R2CConnectionError; check endpoints, TLS certificates, and network
dry_run mode
Observations are published normally; received actions are logged but not executed on hardware
Duration 0
Client runs indefinitely until Ctrl+C or process termination
Robot config missing required fields
Client startup fails with ValidationError for missing hardware.type, translator.type, or mapping sections
Heartbeat disabled
Set runtime.heartbeat.enabled: false in robot config; no heartbeat messages sent
Observation recording
--record path must be writable; observations saved as .pkl (pickle format)
Config directory resolution
_config_dir is injected into robot_config for relative path resolution (e.g., custom adapter modules)
Keyboard control
Enabled via runtime.keyboard_control.enabled: true; space=pause/resume, h=go_home (when paused), e=graceful exit
Action timeout
runtime.action_response_timeout_s controls wait time; backoff configured via _initial_s and _backoff