BrainCo Hand
帮助

简体中文

English

简体中文

English

获取 SDK ​

灵巧手 SDK（Software Development Kit）是专为 BrainCo Revo 3 系列设备开发的跨平台软件开发包，提供 21 电机独立关节控制、状态读取（位置、速度、电流、电机状态）与固件 OTA 升级接口。

系统要求 ​

宿主机环境需满足以下规格要求：

  • Python: 3.9 ~ 3.12 运行环境
  • Linux: Ubuntu 20.04/22.04 LTS 及以上 (支持 x86_64 / aarch64 架构)
  • macOS: 10.15+ 系统版本
  • Windows: Windows 10/11 系统环境
  • 通讯接口: 支持 5M 波特率的 RS485 串口模块或总线卡

下载与安装 ​

1. 示例代码与 SDK 集成 ​

运行示例前，请先拉取 SDK 仓库代码：

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

2. Python 依赖包安装 ​

建议使用虚拟环境（推荐 Conda）安装 Revo 3 SDK：

bash
# 创建并激活 Conda 虚拟环境（推荐 Python 3.10）
conda create -n revo3_env python=3.10 -y
conda activate revo3_env

# 安装 Revo 3 核心 SDK 包
pip3 install bc-revo3-sdk==1.1.4

💡 Linux 系统权限与低时延调优说明

在 Linux 系统下运行串口程序时，需要关注以下串口读写权限及通信延迟配置：

  • 串口设备访问权限（非 root 通用要求）：Linux 系统下非 root 用户默认不具备串口设备（如 /dev/ttyUSB0）的直接读写权限。为了能够正常打开并使用串口，请确保在运行示例前将当前 Linux 用户永久加入 dialout 用户组（修改后需注销并重新登录以生效）：
    bash
    sudo usermod -a -G dialout $USER
  • 自动低时延配置（SDK 默认处理）：SDK 在 Linux 下打开串口时，已自动将 FTDI 硬件延迟降低至 1ms（通过 ioctl 设置 ASYNC_LOW_LATENCY），使用 SDK 时无需手动配置。
  • 手动串口优化（非 SDK 或独立诊断场景）：若开发者未使用官方 SDK（例如直接通过第三方通用 Modbus 库控制串口进行高频控制），或是作为独立的通信延迟诊断调试手段，仍可手动执行以下命令将指定 USB 串口调优为最低延迟：
    bash
    # 使用 setserial 工具配置
sudo setserial /dev/ttyUSB0 low_latency
    或者直接将延迟定时器（Latency Timer）通过 sysfs 写入最低的 1ms：
    bash
    echo 1 | sudo tee /sys/class/tty/ttyUSB0/device/latency_timer

运行示例 ​

仓库 python/ 和 c/ 目录下包含 Revo 3 灵巧手的演示示例。设备默认通信波特率为 5M (5000000 bps)，左手从机 ID 为 126，右手为 127。

1. Python 示例 ​

进入 python/ 目录并安装依赖后，即可运行演示脚本：

bash
cd python
pip install -r requirements.txt

# 运行自动检测串口与 ID
python revo3/auto_detect.py
# 运行灵巧手基础运动控制演示
python revo3/hand_demo.py
# 运行轨迹规划与示教演示
python revo3/hand_trajectory.py
# 运行 OTA 固件在线升级
python revo3/hand_dfu.py /path/to/firmware.bin
# 启动图形化 Qt 调试面板（含 Mock 模式）
python gui/main.py --mock
💡 预期 Python 控制台输出日志 (Expected Python Console Output)
python
$ python revo3/hand_demo.py
[2026-05-27 10:10:02.124] [INFO] Stark SDK version 1.1.0 initialized.
[2026-05-27 10:10:02.125] [INFO] Scanning serial port: /dev/ttyUSB0 (Baudrate: 5000000 bps)
[2026-05-27 10:10:02.341] [INFO] Found Revo 3 Dexterous Hand [Right Hand, ID: 127]
[2026-05-27 10:10:02.342] [INFO] Performing initial joint origin calibration sweep...
[2026-05-27 10:10:04.512] [INFO] Calibration complete. All 21 motors successfully zeroed.
[2026-05-27 10:10:04.513] [INFO] Sending command: Move thumb flexion to 50.0°, index to 60.0°
[2026-05-27 10:10:05.102] [INFO] Feedback: Position[Thumb]=49.8°, Current[Thumb]=84mA | Status: MOTOR_RUNNING
[2026-05-27 10:10:05.612] [INFO] Feedback: Position[Thumb]=50.0°, Current[Thumb]=12mA | Status: MOTOR_IDLE
[2026-05-27 10:10:06.000] [INFO] Demo completed. Closing serial port.
  • auto_detect.py：自动扫描系统串口，发现并检测绑定的 Revo 3 灵巧手 ID 和波特率。
  • hand_demo.py：关节位置控制与状态反馈示例。
  • hand_trajectory.py：多指轨迹规划与协调抓取示例。
  • hand_dfu.py：固件在线升级（OTA）脚本。
  • gui/main.py：图形化调试工具，支持控制下发与实时波形观测。

2. C++ 示例 ​

在 C++ 环境下编译并执行示例程序：

bash
# 1. 下载核心动态依赖库
sh download-lib.sh
# 2. 编译 C++ 示例项目
make -C c

# 3. 运行对应可执行程序
# 自动检测设备
./c/demo/auto_detect
# 运行基本控制演示
./c/demo/hand_demo
# 运行轨迹演示
./c/demo/hand_trajectory
# 运行固件 OTA 升级
./c/demo/hand_dfu firmware.bin
💡 预期 C++ 控制台输出日志 (Expected C++ Console Output)
bash
$ ./c/demo/hand_demo
[STARK INFO] Serial port successfully opened on /dev/ttyUSB0 at 5000000 bps.
[STARK INFO] Connecting to device ID: 127...
[STARK INFO] Device acknowledged. Firmware version: v3.2.14
[STARK INFO] Launching motor sweep calibration...
[STARK SUCCESS] Joint calibration completed in 2.18s.
[STARK INFO] Write [Target: Position] | ID 127 -> Motor[0]=12000, Motor[1]=15000
[STARK INFO] Read [Feedback] | Motor[0]: Pos=12000, Vel=0, Cur=10 | Status=0x01
[STARK INFO] Execution successful. Terminating connection.
  • auto_detect：RS485 通道自动扫描检测工具。
  • hand_demo：电机读写控制与反馈监控示例。
  • hand_trajectory：多关节平滑轨迹规划示例。
  • hand_dfu：固件 OTA 升级工具。

快速开始 ​

以下代码展示了从零开始控制灵巧手的最小流程：打开串口 → 写入目标角度 → 读取状态反馈。

python
# 1. Open serial connection
from bc_revo3_sdk import modbus_open
ctx = modbus_open("/dev/ttyUSB0", 5000000)
slave_id = 1

# 2. Write target angles (degrees) for 21 joints
target_positions = [0.0] * 21
target_positions[0] = 45.5  # Thumb joint
ctx.revo3_set_all_motor_positions(slave_id, target_positions)

# 3. Read 21-joint status feedback
positions = ctx.revo3_get_all_motor_positions(slave_id)
currents = ctx.revo3_get_all_motor_currents(slave_id)
print(f"Thumb pos: {positions[0]} deg, current: {currents[0]} mA")
cpp
#include "revo3-sdk.h"

// 1. Open RS485 serial port
DeviceHandler* handle = modbus_open("/dev/ttyUSB0", 5000000);
if (!handle) return -1;

// 2. Write target angles for 21 joints
float target_positions[21] = {0.0f};
target_positions[0] = 45.5f;
revo3_set_all_motor_positions(handle, 1, target_positions);

// 3. Read 21-joint status feedback
CRevo3MotorStatusData* status = revo3_get_motor_status_data(handle, 127);
if (status) {
    printf("Thumb pos: %f deg, current: %f mA\n", status->positions[0], status->currents[0]);
    free_revo3_motor_status_data(status);
}

modbus_close(handle);

💡 生产开发建议：优先使用轨迹规划 API

直接下发阶跃目标位置（如 revo3_set_all_motor_positions）会产生瞬时电流冲击，长期使用会加速减速箱与传动机构磨损。

在实际应用中，建议优先使用以下高级 API：

  • 五次多项式轨迹控制：revo3_move_finger_trajectory / revo3_move_thumb_trajectory — SDK 内部自动计算平滑插值，消除物理冲击。
  • 轨迹录制与回放：revo3_replay_hand — 支持高频回放录制好的 21 轴轨迹，可通过 Kp、Kd 增益调节实现柔顺抓握。

控制模式速览 ​

SDK 内部已自动处理所有 Modbus 寄存器的 x100 缩放编解码。调用 API 时直接传入标准物理量浮点数（角度 45.5 度、速度 50.0 RPM、电流 120.0 mA），无需手动换算。

模式值模式名称控制参数说明
0位置控制 (Position)目标角度 (deg)控制关节移动到指定角度。
1速度控制 (Speed)目标转速 (RPM)控制关节以指定转速持续转动。(1 RPM = 6 °/s)
2电流控制 (Current)目标电流 (mA)控制关节输出指定力矩。
4阻抗控制 (Impedance)刚度系数 (Kp)简易力-位混合控制，仅激活位置刚度。
5阻尼控制 (Damping)阻尼系数 (Kd)简易力-位混合控制，仅激活速度阻尼。

SDK 还提供完整的 MIT 力-位混合控制（Kp + Kd + 前馈力矩的五参数联合控制）和手指级轨迹控制接口。详细参数范围与公式定义参见 电机控制协议文档。

⚠️ 触觉传感器零点校准

灵巧手配备 11 个触觉阵列模块（手掌 + 每指指尖/指腹），长时间使用可能产生基准漂移。建议定期在无外力状态下调用 revo3_calibrate_touch_zero() 执行零点校准。各模块的物理位置与通道数参见 触觉阵列协议文档。

深入参考 ​

接口定义文件 ​

API 查阅与代码自动补全可参考以下接口定义文件：

  • Python 类型存根 (.pyi): main_mod.pyi — 包含所有类、枚举、函数的类型注解。
  • C/C++ 头文件 (.h): revo3-sdk.h — 由 cbindgen 自动生成的 C ABI 导出头文件。

协议与硬件参考文档 ​

以下文档定义了 SDK API 背后的 Modbus 寄存器映射与硬件规格，适合需要深入理解底层控制逻辑的开发者：

Copyright © 2018-present BrainCo Inc.