Skip to content

获取 SDK ​

本页适用于 Revo 1。Revo 1 与 Revo 2 的对外示例仓库名为 brainco-hand-sdk,Python wheel 包名为 bc-stark-sdk;本文使用 wheel 版本 2.0.9。设备 ID、默认波特率、协议和可用功能因型号而异,运行示例前请先确认设备型号与连接参数。

Revo 1 基础版在 SDK 中对应 Revo1Basic,带电容触觉的 SKU 对应 Revo1Touch。Revo 1 进阶版对应 Revo1Advanced / Revo1AdvancedTouch。进阶版的识别、示例选择和专用 API 说明见 Revo 1 进阶版。

系统要求 ​

  • Python: 3.9 ~ 3.12
  • Linux Python wheel:x86_64 和 aarch64 均提供 manylinux_2_31 包,要求 glibc ≥ 2.31(Ubuntu 20.04+)。
  • macOS C/C++:10.15+;SDK 2.0.9 未提供 macOS Python wheel。
  • Windows: 10/11

支持的通信协议 ​

设备RS-485ProtobufCANCAN FDEtherCAT
Revo 1 基础版✅✅✅❌❌
Revo 1 进阶版✅❌✅取决于交付配置取决于交付配置
Revo 2✅❌✅✅✅

下载与安装 ​

对外示例仓库 ​

打开 brainco-hand-sdk 示例仓库

Python SDK 安装 ​

bash
# 从 PyPI 安装
pip3 install bc-stark-sdk==2.0.9

# 国内镜像(阿里云 OSS)
bash install_whl.sh 2.0.9

C/C++ 预编译库 ​

C/C++ 2.0.9 下载包与 Python 2.0.9 使用同版 SDK。按平台下载库与配套头文件:

每个 ZIP 包含匹配的头文件和 MIT LICENSE,升级时请同时替换库与头文件。上述 Linux C/C++ 包已在 Ubuntu 20.04 验证,系统依赖可通过 sudo apt install libusb-1.0-0 libudev1 安装;Python wheel 的系统要求见上文。Windows x64 包含 MSVC 和 MinGW 导入库,需要安装 Microsoft Visual C++ 2015–2022 x64 运行库。Windows 导入库仅完成编译链接检查,Windows 运行时及完整 ROS2/G1 真机集成尚未验证。

自动发现未找到 RS485 设备 ​

Python 和 C/C++ SDK 2.0.7 及后续版本修复了 FTDI 多通道适配器因共用 USB 序列号而被误过滤的问题。USB 序列号是模块的身份标识,与 Windows 的 COM 端口号不同;两个有效通道可能共用同一 USB 序列号。

若上位机能连接但自动发现失败,先完全退出上位机以释放串口,再将 python/demo/auto_detect.py 中 main() 内的 SDK 调用改为:

python
devices = await sdk.auto_detect(port="COM5", protocol="Modbus")

将 COM5 换成上位机能连接的实际端口;Linux 使用 /dev/ttyUSB0 等路径。指定端口会绕过自动端口筛选。若仍失败,请对照上位机的波特率、设备 ID 和串口参数,并保留失败日志。以运行日志显示的 SDK 版本确认实际加载版本。

默认 scan_all=False 找到首个设备后即返回;需要查找扫描候选地址中的全部设备时,设置 scan_all=True。这不会遍历所有可能的设备 ID。

示例代码 ​


运行示例 ​

克隆仓库并安装 Python 或 C++ 依赖后,先运行只读设备发现,再选择与 Revo 1 协议匹配的控制示例。

Linux 设备配置

在 Linux 宿主机上使用 CAN FD 或 RS-485 串口时,请确认设备权限与延迟配置:

  • CAN 接口使能权限:请确保 SocketCAN 接口已配置为 1M 或 2M 波特率:
    bash
    sudo ip link set can0 up type can bitrate 1000000 dbitrate 2000000 fd on
  • FTDI 串口延迟设置:若使用 RS485 串口,并且需要较短查询周期,请启用 low_latency:
    bash
    sudo setserial /dev/ttyUSB0 low_latency

1. Python 示例运行 ​

进入仓库的 python/demo/ 目录运行基础控制与多传感器时序采集:

bash
cd python/demo

# 运行串口与协议自动扫频发现工具
python auto_detect.py

# 运行 Revo 1/2 综合控制演示
python hand_demo.py
python hand_demo.py -m /dev/ttyUSB0 115200 1           # Modbus
python hand_demo.py -p /dev/ttyUSB0 10                 # Protobuf
python hand_demo.py -c /dev/cu.usbmodem14201 1000000 1 # ZQWL CAN 2.0

# 运行实时数据监控
python hand_monitor.py

# 运行固件升级工具
python hand_dfu.py /path/to/firmware.bin
Python 输出节选

以下为 bc-stark-sdk (v2.x) 运行日志的脱敏节选,端口、ID、序列号、固件版本和传感器数值会随设备而变化:

text
$ python auto_detect.py
2026-05-29T20:25:46.134386Z [INFO] bc_stark_sdk version: 2.0.3
2026-05-29T20:25:46.699072Z [INFO] 🔍 Auto-detect: scan_all=false, port=None, protocol=None
2026-05-29T20:25:46.800163Z [INFO] 🔍 Trying Modbus on /dev/tty.usbserial-21101...
2026-05-29T20:25:47.688335Z [INFO] 🔍 Trying Modbus on /dev/tty.usbserial-21101 at Baud115200...
2026-05-29T20:25:47.918838Z [INFO] DeviceInfo: "{\"sku_type\":\"MediumLeft\",\"hand_type\":\"Left\",\"hardware_type\":\"Revo1Basic\",\"serial_number\":\"<device serial>\",\"firmware_version\":\"<firmware version>\",\"hardware_version\":\"\"}"
2026-05-29T20:25:47.919086Z [INFO] ✅ Found Modbus device: port=/dev/tty.usbserial-21101, ID=0x01, baudrate=Baud115200, hw=Revo1Basic
2026-05-29T20:25:48.423103Z [INFO] ✅ Auto-detect: Found 1 device(s)
2026-05-29T20:25:48.438205Z [INFO] Initialized context for Revo1Basic device (slave 0x01)

Found 1 device(s)
----------------------------------------------------------------------

[Device 1] Revo1 Basic
  Protocol:     Modbus
  Port:         /dev/tty.usbserial-21101
  Slave ID:     0x01 (1)
  Baudrate:     115200
  Serial:       <device serial>
  Firmware:     <firmware version>
  SKU:          MediumLeft
text
$ python hand_demo.py
[Init] Revo1Basic
  Protocol: StarkProtocolType.Modbus
  Port: /dev/tty.usbserial-21101
  Slave ID: 0x01 (1)
  Serial: <device serial>
  Firmware: <firmware version>

=== Demo 1: Position Control ===
Opening all fingers...
Closing Thumb...
Closing ThumbAux...
Closing Index...
Closing Middle...
Closing Ring...
Closing Pinky...
Making fist...
Opening all fingers...
Final positions: [0, 0, 0, 0, 0, 0]

2. C++ 示例编译与运行 ​

在 c/ 目录下编译并运行跨平台 C++ 示例:

bash
cd c
make

# 运行自动探测连接设备
./demo/auto_detect.exe

# 运行 Revo 1/2 综合控制演示
./demo/hand_demo.exe
./demo/hand_demo.exe -m /dev/ttyUSB0 115200 1                 # Modbus
./demo/hand_demo.exe -p /dev/ttyUSB0 10                       # Protobuf
./demo/hand_demo.exe -c /dev/cu.usbmodem14201 1000000 1       # ZQWL CAN 2.0
./demo/hand_demo.exe -b can0 1                                # SocketCAN CAN 2.0 (Linux, SDK 内置)
C++ 输出节选

以下为 c/demo 示例源码对应的输出结构,端口、ID、序列号、固件版本和传感器数值会随设备而变化:

text
$ ./demo/auto_detect.exe
=== Stark Auto-Detect Example ===

[INFO] Auto-detecting devices...

[INFO] Found devices:

[1] Revo1Basic
    Protocol: Modbus
    Port: /dev/ttyUSB0
    Slave ID: 0x01 (1)
    Serial Number: <device serial>
    Firmware: <firmware version>

[INFO] Using the only available device
Slave[1] Serial Number: <device serial>, FW: <firmware version>
Hardware Type: Revo1Basic (1)
Slave[1] Baudrate: 115200

=== Testing Finger Control ===
Closing pinky...
Opening pinky...
Final positions: 0, 0, 0, 0, 0, 0

=== Example completed ===
text
$ ./demo/hand_demo.exe 1
=== Universal Motor Control - Complete Demo ===

[INFO] Auto-detecting devices...

[INFO] Found devices:

[1] Revo1Basic
    Protocol: Modbus
    Port: /dev/ttyUSB0
    Slave ID: 0x01 (1)

[INFO] Using the only available device
Slave[1] Serial Number: <device serial>, FW: <firmware version>
Hardware Type: Revo1Basic (1)

[INFO] Motor API: Revo1
[INFO] Touch type: None

=== Demo 1: Basic Position Control ===
[Demo] Performing fist gesture...
[Demo] Performing open hand...
[Demo] Moving single finger (middle)...
[Demo] Reading motor status...
  Positions: 0, 0, 0, 0, 0, 0
  Speeds: 0, 0, 0, 0, 0, 0
  Currents: 0, 0, 0, 0, 0, 0
  States: 0, 0, 0, 0, 0, 0

[INFO] Done!

进阶参考 ​

接口定义文件 ​

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

  • Python 类型存根 (.pyi): 下载 main_mod.pyi — 包含 bc_stark_sdk.main_mod 中的类、枚举、函数类型注解。
  • C/C++ 头文件 (.h): 下载 stark-sdk.h — 与 bc-stark-sdk 2.0.9 发布包相同的 C ABI 导出头文件,须与 2.0.9 库配套使用。

SDK 仓库说明 ​

brainco-hand-sdk 现仅面向 Revo 1 / Revo 2 系列示例;Revo 3 SDK 已迁移到独立的 brainco-revo3-sdk 仓库。旧版 linux/、windows/ 示例已归档至 archive/,新项目建议使用 python/demo/ 与 c/demo/ 统一示例入口。


更新日志 ​

v2.0.9 (2026/10/28) ​

  • Linux Modbus 请求写入后不再逐次等待串口发送完成。如需恢复原行为,请在打开串口前设置 STARK_MODBUS_DRAIN_ON_FLUSH=1。CAN FD、macOS 和 Windows 通信逻辑未变。

v2.0.8 (2026/10/19) ​

  • 修复 C/C++ stark_get_finger_max_position 和 Python get_finger_max_position 误读设置寄存器的问题。getter 现按 952 + finger_id - 1 读取六个手指的最大位置回读值。
  • 请同时升级库和配套头文件;公开 API 签名不变。

v2.0.7 (2026/10/12) ​

  • 自动发现保留共用 USB 序列号的所有受支持 FTDI RS485 通道,修复有效通道被跳过的问题;显式指定端口的接口保持兼容。
  • Linux x86_64、ARM64 Python wheel 均提供 glibc 2.31(Ubuntu 20.04+)兼容包。本次未提供 macOS Python wheel。
  • Python 和 C/C++ 下载包均包含此修复;现场设备的识别结果需升级后复测确认。

v2.0.6 (2026/10/12) ​

  • 新增 stark_enable_touch_sensor_with_status 和 stark_calibrate_touch_sensor_with_status。两个阻塞式 C API 在传输成功时返回 0,句柄为空或操作失败时返回 -1。原生 Modbus RTU 等待写响应;自定义回调须报告响应错误和超时。传输成功不表示物理标定已完成,标定时请保持手指空载。
  • 阻塞调用期间须保持设备句柄有效,不得并发关闭句柄,也不得从持有同一设备锁的 SDK 传输回调中调用。原有异步 void API 保持兼容。
  • 自定义 Modbus 写操作现在会传递传输错误,并拒绝 FC06/FC16 回显不匹配的响应。
  • Revo2 Touch 使用 STARK_HARDWARE_TYPE_REVO2_TOUCH(11),Revo2 Basic 使用 10。旧集成若用 4 表示 Revo2 Touch,请改用具名常量;当前 4 表示 Revo1 Advanced Touch。历史日志可能显示旧编号,请勿将其复制到当前代码。
  • Linux ARM64 Python wheel 使用 manylinux_2_31,适用于 Ubuntu 20.04+。C/C++ ZIP 包含配套头文件和 MIT LICENSE;第三方组件保留各自许可证。

v2.0.3 (2026/07) ​

  • 历史版本;本页 Python 安装说明现使用 2.0.9。
  • 新增 4 Mbps 和 6 Mbps 波特率支持。
  • 更新 Python 示例的打包与安装说明,覆盖 pip、Conda 和 uv 工作流。
  • 对外示例中的 ZQWL CAN/CAN FD 初始化改用对应协议的专用初始化接口。

v2.0.2 (2026/05) ​

仓库变更 ​

  • Revo 3 SDK 已迁移至独立仓库 brainco-revo3-sdk。
  • brainco-hand-sdk 现仅包含 Revo 1 / Revo 2 示例与预编译库。
  • Python Wheel 升级至 cp39-abi3 稳定 ABI,不再支持 Python 3.8。

修复 ​

  • BrainCo USBCANFD 适配器新增多通道、多协议(CAN 2.0 / CANFD)自动检测。
  • 修复 Revo 2 手动电机校准失败的问题。
  • C/C++ ABI 变更(自 2.0.0 起):Baudrate 枚举值顺序调整(如 BAUD5MBPS 由 6 → 7)

v1.4.0 (2026/04/15) ​

新增触觉设备类型 ​

  • 新增 阵列压阻触觉版 (Revo2TouchArrayPressure) — 3D 力与力矩数据采集(Fx, Fy, Fz, Mx, My),通过 ArrayPressureTouchDataBuffer
  • C++ 示例:hand_demo 和 hand_monitor 新增 array_pressure 模式
  • Python GUI:力/力矩数据 2D 矢量罗盘可视化
  • 触觉类型判断 API:
    • is_capacitive_touch() — 电容触觉(Revo1/Revo2 Touch)
    • is_pressure_touch() — 压阻触觉
    • is_force3d_touch() — 三维力触觉
    • is_array_pressure_touch() — 阵列压阻触觉

Python GUI ​

  • 触觉面板:热力图可视化,支持电容/压阻/三维力/阵列压阻/视触觉
  • 时序测试:Revo2 Worker,动态频率切换
  • 国际化支持(中/英)

SDK & API 变更 ​

  • 新增硬件类型:Revo2TouchForce3D、Revo2TouchArrayPressure
  • 新增 API:uses_array_pressure_touch_api()

🐛 问题修复 ​

  • 修复 CAN 错误帧处理和自动检测协议分发
  • SocketCAN recv_can/recv_canfd 新增 CAN_ERR_FLAG 检查

📚 文档与项目结构 ​

  • 弃用的 linux/ 和 windows/ 目录归档至 archive/
  • 新增 install_whl.sh 脚本用于 Python Wheel 安装

v1.1.9 (2026/03/03) ​

🔧 改进 ​

  • 串口打开后新增 150ms 预热延迟,提升 Modbus 自动检测首次成功率

📚 新增示例 ​

  • c/demo/debug_detect.cpp — C++ 调试工具,用于 Modbus 寄存器检查和原始 Protobuf 自动检测

v1.1.6 (2026/02/28) ​

🚀 新增功能 ​

  • 自动检测新增 BrainCo USBCANFD 适配器支持

v1.1.5 (2026/02/09) ​

🐛 问题修复 ​

  • 修复 CANFD 边界检查问题
  • SocketCAN 扫描改为遍历所有接口

🚀 新增功能 ​

  • SocketCAN Python 绑定(init_socketcan_canfd、close_socketcan、socketcan_scan_devices)
  • 设备上下文查询 API:stark_get_protocol_type、stark_get_port_name、stark_get_baudrate 等
  • CAN 设备初始化:init_device_handler_can() / init_device_handler_can_with_hw_type()
  • StarkProtocolType::Auto = 0 枚举值,支持自动检测所有协议

🔧 示例改进 ​

  • 运行时 CAN 后端选择,新增通信频率测试工具

v1.1.3 (2026/02/06) ​

🚀 新增功能 ​

  • SocketCAN 内置支持 (Linux) - 无需外部代码
  • Protobuf 协议支持 - Revo 1 串口协议,波特率 115200,Slave ID 10-254

v1.1.0 (2025/02/05) ​

🚀 新增功能 ​

  • ZQWL CAN 适配器内置支持(Linux / macOS / Windows,无需额外 DLL)
  • 统一设备自动检测 API:auto_detect() → init_from_detected() → close_device_handler()
  • Revo 1 进阶版 触觉能力支持(RS-485 / CAN 协议)
  • 跨平台 C++ 示例(c/demo/)
  • Python GUI 调试工具(电机控制、触觉数据、波形监控)

⚠️ Breaking Changes ​

  • 硬件类型枚举重构,新增 Revo1Advanced / Revo1AdvancedTouch
  • API 重命名:is_revo1() → uses_revo1_motor_api(),is_revo2() → uses_revo2_motor_api()
  • 初始化拆分:init_config() → init_logging() + init_device_handler()
  • C 结构体添加 C 前缀(如 MotorStatusData → CMotorStatusData)
  • linux/ 和 windows/ 示例目录已弃用,请迁移至 c/

📚 迁移指南 ​

详见 CHANGELOG.md


v1.0.0 (2025/12/08) ​

🎉 正式版本 ​

  • 细节优化,正式升级到 1.0 版本

v0.9.9 (2025/11/19) ​

🚀 新增功能 ​

  • 支持 Revo 1 进阶版设备 ⭐
  • 统一控制参数范围:位置控制 0~1000,速度/电流/PWM 控制 -1000~+1000
  • 适用于 Modbus、CANFD 和 CAN2.0 所有通信协议

⚠️ 重要提示 ​

  • Revo 1 进阶版设备需要 SDK v0.9.9 或更高版本
  • Revo 1 基础版和触觉版可使用任意版本

v0.9.8 (2025/11/04) ​

🚀 新增功能 ​

  • CAN/CANFD 协议: 完整的 Revo 2 CAN2.0/CANFD 通信协议栈
  • ZLG CAN 支持: Python 接口(Windows/Linux),含驱动库封装
  • CANFD 分块读写: 支持超过 29 个寄存器的大数据传输
  • EtherCAT 触觉: 触觉传感器数据采集(PDO/SDO)
  • 压力触觉支持: EtherCAT/CANFD/RS-485 多协议通信
  • 保护电流接口: ProtectedCurrent 读写,支持 CAN/EtherCAT
  • 动作序列执行: run_action_sequence 支持 CAN 2.0
  • 设备类型判断: 基于序列号判断(get_hardware_by_sn)
  • 多设备混用: 支持 Revo1/Revo2 同时使用

⚡ 高频通信优化 ​

  • C/C++ 异步调用: set 类指令改为异步执行,避免阻塞主线程
  • 高频接口禁用重试: get/set_finger_*、触觉读取等,避免指令堆积
  • 低频接口重试优化: 设备信息读取等降至 2 次重试

🐛 问题修复 ​

  • 修复 TurboConfig 字节序、Modbus C API 异步调用、OTA 升级包大小处理等问题

v0.9.0 (2025/09/20) ​

🐛 问题修复 ​

  • 修复已知问题,提升稳定性

v0.8.6 (2025/08/20) ​

🚀 新增功能 ​

  • 新增一代灵巧手 CAN2.0 协议支持

🔧 API 改进 ​

  • 函数命名优化:
    • modbus_ → stark_(更通用的前缀,适用于 CANFD 和 EtherCAT)
    • create_device_handler() 更新命名,避免歧义
    • canfd_init(uint8_t master_id) 更新命名,避免歧义
    • init_cfg 不再需要传递固件类型,通过 get_device_info 接口自动获取

📚 示例代码 ​

  • ROS 2 示例增加 CAN/CANFD 支持
  • 新增 CAN/CANFD C++ 示例

v0.7.0 (2025/07/18) ​

🚀 新增功能 ​

  • 自动检测 Modbus 从机波特率和设备 ID
  • 二代灵巧手触觉版接口支持

🐛 问题修复 ​

  • 修复 DFU 固件升级问题

v0.6.2 (2025/07/14) ​

🚀 新增功能 ​

  • EtherCAT 协议支持:二代灵巧手支持 EtherCAT 高速通信协议
  • 扩展 RS485 波特率:新增 1M、2M 和 5M 波特率选项,满足高性能应用需求
  • Linux 串口性能优化:默认启用 LOW_LATENCY 模式,460800 波特率下通信频率提升 400%

🔧 API 改进 ​

  • 重构设备上下文命名:
    • ModbusContext → DeviceContext(更通用的设备上下文)
    • ModbusHandler → DeviceHandler(统一设备操作接口)

🛠 开发工具 ​

  • 集成 python-stub-gen 工具链,自动生成类型存根文件(.pyi),提升 IDE 智能提示和类型检查体验

⚠️ 兼容性提示 ​

  • 从旧版本迁移时,请注意 API 命名变更

v0.5.3 (2025/06/12) ​

🚀 新增功能 ​

  • 自定义 Modbus 读写接口
  • 动作序列控制
  • LED、蜂鸣器、震动马达控制接口

🐛 问题修复 ​

  • 修复实时位置/速度/电流返回值错误

v0.4.5 (2025/05/14) ​

🚀 新增功能 ​

  • 新增 get_single_touch_status 单指触控状态检测

🔧 改进 ​

  • 简化 modbus_open 函数,移除冗余参数

v0.4.4 (2025/05/06) ​

🚀 新增功能 ​

  • 新增 CANFD 协议支持

🐛 问题修复 ​

  • 修复多个已知问题,提升稳定性

v0.3.6 (2025/04/16) ​

🎉 里程碑 ​

  • 首次支持二代灵巧手
  • 建立基础通信框架

v0.1.9 (2025/03/17) ​

📌 初始版本 ​

  • Modbus 通信协议
  • Python / C 代码集成
  • SDK 基础架构
帮助