获取 SDK
本页适用于 Revo 2。Revo 1 与 Revo 2 的对外示例仓库名为 brainco-hand-sdk,Python wheel 包名为 bc-stark-sdk;本文使用 wheel 版本 2.0.9。设备 ID、默认波特率、协议和可用功能因型号而异,运行示例前请先确认设备型号与连接参数。
系统要求
- 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-485 | Protobuf | CAN | CAN FD | EtherCAT |
|---|---|---|---|---|---|
| Revo 1 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Revo 2 | ✅ | ❌ | ✅ | ✅ | ✅ |
下载与安装
对外示例仓库
Python SDK 安装
# 从 PyPI 安装
pip3 install bc-stark-sdk==2.0.9
# 国内镜像(阿里云 OSS)
bash install_whl.sh 2.0.9C/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 调用改为:
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 2 协议匹配的控制示例。
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 串口延迟设置:Linux SDK 会尝试启用低延迟,运行时应核对实际读回值。需要手动设置且驱动支持时,可在停止其他串口访问后执行:bash
sudo setserial /dev/ttyUSB0 low_latencyttyAMA硬件 UART 通常没有 FTDI 的latency_timer参数。诊断命令、频率定义和原始串口对照工具见串口性能排查。
1. Python 示例运行
进入仓库的 python/demo/ 目录运行基础控制与多传感器时序采集:
cd python/demo
# 运行串口与协议自动扫频发现工具
python auto_detect.py
# 运行 Revo 1/2 综合控制演示
python hand_demo.py
python hand_demo.py -m /dev/ttyUSB0 460800 127 # Modbus
python hand_demo.py -c /dev/cu.usbmodem14201 1000000 1 # ZQWL CAN 2.0
python hand_demo.py -f /dev/cu.usbmodem14201 1000000 5000000 127 # ZQWL CANFD
python hand_demo.py -B can0 127 # SocketCAN CANFD (Linux, SDK 内置)
# 运行实时数据监控
python hand_monitor.py
# 运行固件升级工具
python hand_dfu.py /path/to/firmware.binPython 输出节选
以下为 SDK 运行日志的脱敏节选,端口、ID、序列号、固件版本和传感器数值会随设备而变化:
$ python auto_detect.py
2026-03-26T11:22:15.993405Z [INFO] 🔍 Auto-detect: scan_all=false, port=None, protocol=None
2026-03-26T11:22:16.006330Z [INFO] 🔍 Trying Modbus on /dev/tty.usbserial-21100...
2026-03-26T11:22:16.006417Z [INFO] 🔍 Trying Modbus on /dev/tty.usbserial-21100 at Baud460800...
2026-03-26T11:22:16.343617Z [INFO] TouchVendor for slave 127: ArrayPressure
2026-03-26T11:22:16.344213Z [INFO] DeviceInfo: "{\"sku_type\":\"MediumRight\",\"hardware_type\":\"Revo2TouchArrayPressure\",\"serial_number\":\"<device serial>\",\"firmware_version\":\"<firmware version>\"}"
2026-03-26T11:22:16.344343Z [INFO] ✅ Found Modbus device: port=/dev/tty.usbserial-21100, ID=0x7F, baudrate=Baud460800, hw=Revo2TouchArrayPressure
2026-03-26T11:22:16.848082Z [INFO] ✅ Auto-detect: Found 1 device(s)
2026-03-26T11:22:16.867287Z [INFO] Initialized context for Revo2TouchArrayPressure device (slave 0x7F)
Found 1 device(s)
----------------------------------------------------------------------
[Device 1] Revo2 Touch Array Pressure
Protocol: Modbus
Port: /dev/tty.usbserial-21100
Slave ID: 0x7F (127)
Baudrate: 460800
Serial: <device serial>
Firmware: <firmware version>
SKU: MediumRight$ python hand_demo.py
[Init] Revo2Touch
Protocol: StarkProtocolType.Modbus
Port: /dev/tty.usbserial-21100
Slave ID: 0x7F (127)
Serial: <device serial>
Firmware: <firmware version>
=== Demo 3: Advanced Control (Position + Time/Speed) ===
Position with duration (1000ms)...
Position with speed...
Final positions: [0, 0, 0, 0, 0, 0]2. C++ 示例编译与运行
在 c/ 目录下编译并运行跨平台 C++ 示例:
cd c
make
# 运行自动探测连接设备
./demo/auto_detect.exe
# 运行 Revo 2 综合控制演示
./demo/hand_demo.exe
./demo/hand_demo.exe -m /dev/ttyUSB0 460800 127 # Modbus
./demo/hand_demo.exe -c /dev/cu.usbmodem14201 1000000 1 # ZQWL CAN 2.0
./demo/hand_demo.exe -f /dev/cu.usbmodem14201 1000000 5000000 127 # ZQWL CANFD
./demo/hand_demo.exe -B can0 127 # SocketCAN CANFD (Linux, SDK 内置)以下为历史输出摘录。Revo2Touch (6) 来自旧版 SDK;SDK 2.0.6 使用 Revo2Touch = 11。
C++ 输出节选
以下为 c/demo 示例源码对应的输出结构,端口、ID、序列号、固件版本和传感器数值会随设备而变化:
$ ./demo/auto_detect.exe
=== Stark Auto-Detect Example ===
[INFO] Auto-detecting devices...
[INFO] Found devices:
[1] Revo2Touch
Protocol: CANFD
Port: /dev/ttyUSB0
Slave ID: 0x7F (127)
Serial Number: <device serial>
Firmware: <firmware version>
[INFO] Using the only available device
Slave[127] Serial Number: <device serial>, FW: <firmware version>
Hardware Type: Revo2Touch (6)
Slave[127] Baudrate: 460800
=== Testing Finger Control ===
Closing pinky...
Opening pinky...
Final positions: 0, 0, 0, 0, 0, 0
=== Example completed ===$ ./demo/hand_demo.exe -f /dev/ttyUSB0 1000000 5000000 127 3
=== Universal Motor Control - Complete Demo ===
[Init] Mode: ZQWL CANFD
Port: /dev/ttyUSB0, Arb: 1000000, Data: 5000000, Slave ID: 127
Slave[127] Serial Number: <device serial>, FW: <firmware version>
Hardware Type: Revo2Touch (6)
[INFO] Motor API: Revo2
[INFO] Touch type: Revo2Touch
=== Demo 3: Advanced Control (Revo2 Only) ===
[Demo] Setting unit mode to Normalized...
Current mode: Normalized
[Demo] Position + time control (single finger)...
[Demo] Position + speed control (single finger)...
[Demo] Position + duration control (all fingers)...
[INFO] Done!进阶参考
接口定义文件
API 查阅与代码自动补全可参考以下接口定义文件:
- Python 类型存根 (.pyi): 下载 main_mod.pyi — 包含
bc_stark_sdk.main_mod中的类、枚举、函数类型注解。 - C/C++ 头文件 (.h): 下载 stark-sdk.h — 与
bc-stark-sdk2.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 通信逻辑未变。 - 双手共用 RS485 总线时,完整控制与反馈频率仍需在目标设备上实测;本版不保证 100 Hz。
v2.0.8 (2026/10/19)
- 修复 C/C++
stark_get_finger_max_position和 Pythonget_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 传输回调中调用。原有异步
voidAPI 保持兼容。 - 自定义 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 包含配套头文件和 MITLICENSE;第三方组件保留各自许可证。
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.6 (2025/01/26)
🚀 新增功能
- 新硬件支持: Revo1Advanced(
BCMEL/BCMER)、Revo1AdvancedTouch(BCMTL2/BCMTR2) - 序列号自动识别: 根据序列号前缀自动判断硬件类型
- 状态读取优化: 多线程异步采集,应用层被动读取,性能大幅提升
- SocketCAN 支持: Linux 平台新增 SocketCAN 后端
- 自动检测增强: 多端口遍历、协议自动识别、Quick/Full 扫描模式
🐛 问题修复
- 修复物理量模式下参数 1000 倍缩放问题
- 修复 RS-485 固件升级波特率检测问题
📚 示例更新
- 新增
revo2_touch_collector.py马达/触觉状态读取示例 - 新增
revo2_timing_test_gui.py时序测试 GUI 工具
⚠️ 注意
- Revo1Advanced 系列设备请使用
revo2目录下的示例代码
v1.0.1 (2025/12/23)
🚀 新增功能
- 支持 EtherCAT 多从站通信
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 或更高版本
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)
🚀 新增功能
- 新增二代灵巧手 CAN2.0 协议支持
- 新增二代灵巧手触觉版 EtherCAT 协议支持
🐛 问题修复
- 修复已知问题,提升稳定性
v0.8.8 (2025/09/02)
🚀 新增功能
- 新增二代灵巧手 CAN2.0 协议支持
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.8 (2025/07/31)
🚀 新增功能
- EtherCAT 固件增加 DC 同步功能
v0.7.3 (2025/07/28)
🐛 问题修复
- 修复 CANFD 通信中协议 MasterID 配置问题
- 修复 EtherCAT 通信中 PDO 读取位置问题
- 修复 MotorStatusData 中 description 字段错误
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 基础架构