十分钟入门

本文面向首次接触 Revo3 SDK 2.0 的开发者，提供 Python 与 C++ 两种语言的入门指南。示例统一采用 2.0 的 Manager / Hand 架构，演示状态读取、错误处理及资源关闭规范。

1. 前置准备

开始前请确认：

• Python 3.10 或更高版本；C++17 或更高版本的编译器。
• Revo3 已正常供电，并已连接受支持的 Modbus RTU 或 CANFD 适配器。
• 本指南不适用于 EtherCAT 协议；EtherCAT 开发者请参阅独立的 IgH EtherCAT 示例与文档。
• Linux 用户已获取串口或 CAN 设备的读写权限（如 dialout 组权限）。
• 首次运动调试时，确认机械手活动范围内无人员与结构干涉，并确保具备随时切断动力电源的能力。

常见端口名称如下：

系统	端口示例
Linux	/dev/ttyUSB0
macOS	/dev/cu.usbserial-*
Windows	COM3

本文命令以 /dev/ttyUSB0 为例，请替换为实际端口。若仅连接单台设备，也可省略端口参数由 SDK 自动识别与连接。

2. 获取示例代码

可以直接克隆 examples 仓库：

git clone https://github.com/BrainCoTech/brainco-revo3-sdk.git
cd brainco-revo3-sdk

也可以在 examples 仓库 页面选择 Code > Download ZIP，解压后进入仓库根目录。以下命令均在该目录执行。

3. Python 快速入门

3.1 安装 SDK

建议先创建并启用 Python 3.10 或更高版本的虚拟环境，然后安装 SDK 和 examples 所需依赖：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install ./python

Windows PowerShell 使用 py -3.10 -m venv .venv 创建环境，并运行 .venv\Scripts\Activate.ps1 激活。python/pyproject.toml 会安装 bc-revo3-sdk>=2.1.0,<3 及配套 examples 依赖。

注：若 SDK 安装失败或预编译包未覆盖您所需的目标系统架构，请联系技术支持。

3.2 运行测试示例

先运行设备发现示例，该示例不会发送运动指令：

python python/revo3/discover_devices.py

默认扫描找到首个可识别接口上的设备即停止；若连接多台设备可添加 --scan-all。

连接目标设备，读取设备信息、固件版本、关节布局、触觉布局可用性，以及系统状态 (State) 与健康诊断 (Health)：

python python/revo3/quickstart.py --port /dev/ttyUSB0

该命令仅执行只读检查，不会触发机械手运动。成功连接后的输出日志示例如下：

Device:   <SERIAL_NUMBER> (Left)
Slave ID: <SLAVE_ID>
Product code: <PRODUCT_CODE> | Hardware revision: <HW_REV> | Firmware: <FW_VER>
Layout: <LAYOUT_ID> (21 DOF)
Touch layout: not available
State timestamp: <SEC>.<NSEC> (Monotonic)
Health: safety=<SAFETY_STATE>, system_state=0, error_code=0, faulted_motor_count=0

确认设备采用当前支持的 21 关节布局且 State/Health 预检无故障后，执行四指开合测试动作：

python python/revo3/quickstart.py --port /dev/ttyUSB0 --move

3.3 示例代码

Python 示例代码如下（完整 API 说明见 API 参考手册 - 基础用法）：

import asyncio
from bc_revo3_sdk import main_mod as sdk


async def main():
    manager = sdk.Manager()
    hand = None
    try:
        hand = await manager.connect_auto()
        state = await hand.state.snapshot()
        health = await hand.health.snapshot()
        if health.system_state or health.error_code or health.faulted_motor_count:
            raise RuntimeError("Health preflight rejected motion")
        target = list(state.positions_deg)
        # Flex MCP (1, 5, 9, 13) and PIP (2, 6, 10, 14) joints for 4 fingers (Pinky..Index)
        for joint in (1, 2, 5, 6, 9, 10, 13, 14):
            target[joint] = 45.0
        motion = await hand.motion.move_to(target, duration=1.5)
        result = await motion.wait(timeout=5.0)
        print(result)
    finally:
        if hand is not None:
            await hand.close()
        await manager.close()


asyncio.run(main())

[!TIP] 单关节、单手指和 Thumb 的运动命令见示例帮助：python python/revo3/quickstart.py --help

4. C++ 快速入门

4.1 构建示例

下载对应平台的 SDK 动态库与公共头文件，再构建 C++ 示例：

bash download-lib.sh
make -C c

download-lib.sh 将 SDK 制品放入 dist/；示例仓库不包含 SDK 核心源码，无需构建 SDK。

4.2 运行测试示例

运行 quickstart 进行设备发现和只读检查：

./c/build/demo/quickstart --port /dev/ttyUSB0

默认扫描找到首个可识别接口上的设备即停止。未提供运动参数时，该命令只读取设备信息、固件版本、关节布局、State 与 Health，不会触发机械手运动。

确认设备采用当前支持的 21 关节布局且 State/Health 预检无故障后，执行四指开合测试动作：

./c/build/demo/quickstart --port /dev/ttyUSB0 --move

4.3 示例代码

C++ 示例代码如下（完整 API 说明见 API 参考手册 - 基础用法）：

#include <revo3/revo3.hpp>

#include <stdexcept>
#include <vector>

using namespace std::chrono_literals;

revo3::Manager manager;
auto hand = manager.connect_auto();

const auto state = hand.state().snapshot();
const auto health = hand.health().snapshot();
if (health.system_state != 0 || health.system_error_code != 0 ||
    health.faulted_motor_count != 0) {
  throw std::runtime_error("Health preflight rejected motion");
}
const auto layout = hand.joint_layout();
if (!layout) {
  throw std::runtime_error("Joint layout is unavailable");
}
std::vector<float> target(state.motors.positions_deg,
                          state.motors.positions_deg + layout->joint_count);
for (int joint : {1, 2, 5, 6, 9, 10, 13, 14}) {
  target[static_cast<std::size_t>(joint)] = 45.0F;
}

auto motion = hand.motion().move_to(target, 1500ms);
const auto result = motion.wait(5s);

hand.close();
manager.close();

[!TIP] C++ 示例同样支持单关节、单手指及拇指运动控制：./c/build/demo/quickstart --port /dev/ttyUSB0 --move-finger

5. 动作控制与安全规则

完成 Python 或 C++ 首次运行后，请参考以下动作控制与安全规则：

5.1 动作过程与目标角度

• 运动过程 (--move)：保持拇指与其他关节不变，先将四指屈曲至目标角度，完成后自动复位。
• 目标角度 (--angle)：默认屈曲角度为 45°，也可传入 --angle 60 指定自定义目标角度。
• 参考零位：零位与正方向以设备关节布局和标定定义为准。
• 控制单位：位置角度单位为度 (°)，转速单位为 rpm，电流单位为 mA。

5.2 健康度预检

注意： 示例会在运动前自动检查设备状态 (State) 和健康度 (Health)。若检测到异常，默认拒绝运动；确认无安全风险后，可通过传入 --allow-unhealthy 参数覆盖该保护。

5.3 验证与预期输出

运行成功后，终端将依次输出设备信息与运动结果：

1. 设备信息：输出设备型号、硬件与固件版本、关节布局及触觉布局可用性。
2. 状态与健康度：State 与 Health 确认正常，无未解除的硬件故障。
3. 运动阶段日志：
   • 屈曲阶段：Motion 1 (Flex): Succeeded
   • 复位阶段：Motion 2 (Return): Succeeded

注意： 运动指令与结果说明：

• 结果为 Indeterminate：仅针对运动/写控制指令（如 move_to()），表示写指令下发后未在时限内收到 Ack 确认包。此时指令可能已在硬件生效，建议先读取 State 确认实际关节位置，避免直接重复下发控制指令。
• 等待超时 motion.wait()：超时仅代表示例程序停止等待响应，硬件已接收的物理运动仍会继续执行。

6. 进阶指引

完成首次运动后，可继续查阅：

• 开发者指南：异步模型、数据订阅、流式控制 (Servo)、运动等待与取消、错误重试与数据诊断
• API 参考手册：方法签名、数据结构与参数说明
• 1.x 到 2.0 迁移指南：接口变更与升级说明

6.1 进阶示例命令

Python 示例：

• 多手连接控制：python python/revo3/multi_hand.py --help
• 触觉传感器读取：python python/revo3/touch_sensor.py --help
• 设备配置与运维：python python/revo3/device_operations.py --help

C++ 示例：

• 多手连接控制：make -C c build/demo/multi_hand
• 触觉传感器读取：make -C c build/demo/touch_sensor
• 设备配置与运维：make -C c build/demo/device_operations