Get SDK
This page targets Revo 1. The public example repository for Revo 1 and Revo 2 is brainco-hand-sdk, while the Python wheel package is bc-stark-sdk; this page uses wheel version 2.0.9. Device IDs, default baud rates, protocols, and capabilities differ by model, so confirm the device and connection settings before running an example.
Revo 1 Basic maps to Revo1Basic in the SDK, while its capacitive-touch SKU maps to Revo1Touch. Revo 1 Advanced maps to Revo1Advanced / Revo1AdvancedTouch. See Revo 1 Advanced for identification, example selection, and Advanced APIs.
System Requirements
- Python: 3.9 ~ 3.12
- Linux Python wheels: x86_64 and aarch64 both provide
manylinux_2_31packages requiring glibc ≥ 2.31 (Ubuntu 20.04+). - macOS C/C++: 10.15+; SDK 2.0.9 does not provide a macOS Python wheel.
- Windows: 10/11
Supported Communication Protocols
| Device | RS-485 | Protobuf | CAN | CAN FD | EtherCAT |
|---|---|---|---|---|---|
| Revo 1 Basic | ✅ | ✅ | ✅ | ❌ | ❌ |
| Revo 1 Advanced | ✅ | ❌ | ✅ | Delivery-specific | Delivery-specific |
| Revo 2 | ✅ | ❌ | ✅ | ✅ | ✅ |
Download & Installation
Public example repository
Open the brainco-hand-sdk example repository
Python SDK Installation
# Install from PyPI
pip3 install bc-stark-sdk==2.0.9
# China mirror (Alibaba Cloud OSS)
bash install_whl.sh 2.0.9C/C++ prebuilt libraries
The C/C++ 2.0.9 packages use the same SDK version as Python 2.0.9. Download the library and matching header for your platform:
Each ZIP includes the matching header and MIT LICENSE. Upgrade the library and header together. These C/C++ Linux packages were validated on Ubuntu 20.04; install their system dependencies with sudo apt install libusb-1.0-0 libudev1. Python wheel requirements are listed separately above. Windows x64 includes MSVC and MinGW import libraries and requires the Microsoft Visual C++ 2015–2022 x64 Redistributable. Windows import libraries were compile/link checked; Windows runtime and full ROS2/G1 hardware integration remain unverified.
RS485 device not found during automatic discovery
Python and C/C++ SDK 2.0.7 and later fix usable FTDI RS485 channels being filtered out when they share a USB serial number. A USB serial number identifies the adapter and differs from a Windows COM port number; two usable channels can share it.
If another application connects but automatic discovery fails, close that application completely to release the port. Then replace the SDK call inside main() in python/demo/auto_detect.py:
devices = await sdk.auto_detect(port="COM5", protocol="Modbus")Replace COM5 with the working port; on Linux use a path such as /dev/ttyUSB0. Explicit port selection bypasses automatic port filtering. If discovery still fails, compare the baud rate, slave ID, and serial settings with the working application and retain the failure log. Use the SDK version reported in the runtime log to confirm the loaded version.
The default scan_all=False returns after finding the first device. Set scan_all=True to find all devices at the scanner's candidate addresses; this does not probe every possible slave ID.
Example Code
Run an example
After cloning the repository and installing the Python or C++ dependencies, run read-only discovery first. Then select a control example that matches the Revo 1 protocol.
Linux device setup
When using CAN FD or Modbus RTU on Linux hosts, verify the required device permissions and latency settings:
- CAN Network Setup: Bring up the SocketCAN interface at 1M standard / 2M data baudrate:bash
sudo ip link set can0 up type can bitrate 1000000 dbitrate 2000000 fd on - FTDI Serial Latency: If using an RS-485 serial connection, enable low latency mode when shorter query cycles are required:bash
sudo setserial /dev/ttyUSB0 low_latency
1. Python Demos
Navigate into python/demo/ to execute baseline control and multidimensional sensor collection:
cd python/demo
# Run the automated protocol & baudrate sweep scanner
python auto_detect.py
# Run the Revo 1/2 comprehensive control demo
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
# Run the real-time data monitor
python hand_monitor.py
# Run the firmware upgrade tool
python hand_dfu.py /path/to/firmware.binPython Output Excerpt
The following is a sanitized excerpt from bc-stark-sdk (v2.x) runtime logs. Port names, IDs, serial numbers, firmware versions, and sensor values vary by device:
$ 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$ 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++ Demos
Compile and execute cross-platform C++ programs under c/:
cd c
make
# Run the target Modbus register scanner
./demo/auto_detect.exe
# Run the Revo 1/2 comprehensive control demo
./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 built-in)C++ Output Excerpt
The following reflects the output structure from the c/demo example source. Port names, IDs, serial numbers, firmware versions, and sensor values vary by device:
$ ./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 ===$ ./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!Advanced Reference
Interface Definition Files
For API lookup and code completion, download the following interface definition files:
- Python type stub (.pyi): Download main_mod.pyi — type annotations for classes, enums, and functions in
bc_stark_sdk.main_mod. - C/C++ header (.h): Download stark-sdk.h — the C ABI export header matching the
bc-stark-sdk2.0.9 package; use it with the 2.0.9 library.
SDK Repository Notes
brainco-hand-sdk now targets Revo 1 / Revo 2 examples only. Revo 3 SDK support has moved to the dedicated brainco-revo3-sdk repository. The legacy linux/ and windows/ examples have been archived under archive/; new integrations should use the unified python/demo/ and c/demo/ entry points.
Release Notes
v2.0.9 (2026/10/28)
- On Linux, Modbus requests no longer wait for each serial write to drain. Set
STARK_MODBUS_DRAIN_ON_FLUSH=1before opening the port to restore the previous behavior. CAN FD, macOS, and Windows transports are unchanged.
v2.0.8 (2026/10/19)
- Fixed
stark_get_finger_max_position(C/C++) andget_finger_max_position(Python) reading the setting register instead of the readback register. The getter now reads952 + finger_id - 1for the six fingers. - Upgrade the library and matching header together. Public API signatures are unchanged.
v2.0.7 (2026/10/12)
- Automatic discovery now retains all supported FTDI RS485 channels sharing a USB serial number, fixing usable channels being skipped. Explicit port selection remains compatible.
- Linux x86_64 and ARM64 Python wheels both provide glibc 2.31 (Ubuntu 20.04+) compatibility. No macOS Python wheel is provided for this release.
- Python and C/C++ packages both include this fix. Repeat device discovery after upgrading to verify the result on your hardware.
v2.0.6 (2026/10/12)
- Added
stark_enable_touch_sensor_with_statusandstark_calibrate_touch_sensor_with_status. These blocking C APIs return0for transport success and-1for a null handle or operation failure. Native Modbus RTU waits for the write response; custom callbacks must report response and timeout failures. Transport success does not confirm physical calibration completion. Keep fingers unloaded during calibration. - Keep the device handle alive throughout either blocking call. Do not close it concurrently or call these APIs from an SDK transport callback holding the same device lock. Existing asynchronous
voidAPIs remain compatible. - Custom Modbus writes now propagate transport errors and reject incorrect FC06/FC16 response echoes.
- Revo2 Touch uses
STARK_HARDWARE_TYPE_REVO2_TOUCH(11); Revo2 Basic uses10. Older integrations using4for Revo2 Touch must migrate to the named constant:4now identifies Revo1 Advanced Touch. Historical logs may show older numeric IDs; do not copy those IDs into current code. - The Linux ARM64 Python wheel uses
manylinux_2_31for Ubuntu 20.04+. C/C++ ZIPs include matching headers and the MITLICENSE; third-party components retain their own licenses.
v2.0.3 (2026/07)
- Historical release; the Python installation instructions above now use 2.0.9.
- Added 4 Mbps and 6 Mbps baud-rate support.
- Updated Python example packaging and installation instructions for
pip, Conda, anduvworkflows. - Updated ZQWL CAN/CAN FD initialization in the public examples to use the protocol-specific initialization APIs.
v2.0.2 (2026/05)
Repository Changes
- Revo 3 SDK has moved to the standalone
brainco-revo3-sdkrepository. brainco-hand-sdknow contains Revo 1 / Revo 2 examples and prebuilt libraries only.- Python wheels upgraded to
cp39-abi3stable ABI; Python 3.8 is no longer supported.
Fixes
- Added multi-channel, multi-protocol (CAN 2.0 / CANFD) auto-detection for BrainCo USBCANFD adapters.
- Fixed manual motor calibration failure on Revo 2.
- C/C++ ABI change (since 2.0.0):
Baudrateenum values reordered (e.g.,BAUD5MBPSchanged from 6 to 7).
v1.4.0 (2026/04/15)
New Tactile Device Types
- Added ArrayPressure Touch (
Revo2TouchArrayPressure) — 3D force & torque data collection (Fx, Fy, Fz, Mx, My) viaArrayPressureTouchDataBuffer - C++ demos:
hand_demoandhand_monitorwitharray_pressuremode - Python GUI: 2D vector compass visualization for force/torque data
- Touch type detection APIs:
is_capacitive_touch()— Capacitive touch (Revo1/Revo2 Touch)is_pressure_touch()— Piezoresistive pressure touchis_force3d_touch()— 3-axis force touchis_array_pressure_touch()— Array piezoresistive touch
Python GUI
- Touch panels: heatmap visualization with capacitive/piezoresistive/Force3D/ArrayPressure/VisionTouch support
- Timing test with Revo2 workers and dynamic frequency switching
- i18n support (EN/ZH)
SDK & API Changes
- New hardware types:
Revo2TouchForce3D,Revo2TouchArrayPressure - New APIs:
uses_array_pressure_touch_api()
🐛 Bug Fixes
- Fixed CAN error frame handling and auto-detect protocol dispatch
- Added
CAN_ERR_FLAGcheck in SocketCANrecv_can/recv_canfd
📚 Documentation & Project Structure
- Archived deprecated
linux/andwindows/folders toarchive/ - Added
install_whl.shscript for Python wheel installation
v1.1.9 (2026/03/03)
🔧 Improvements
- Added 150ms warm-up delay after port open to improve Modbus auto-detection reliability on first attempt
📚 New Examples
c/demo/debug_detect.cpp— C++ debug tool for Modbus register inspection and raw Protobuf auto-detection
v1.1.6 (2026/02/28)
🚀 New Features
- Auto-detection now supports BrainCo USBCANFD adapter
v1.1.5 (2026/02/09)
🐛 Bug Fixes
- Fixed CANFD boundary check issue
- SocketCAN scan now iterates all interfaces
🚀 New Features
- SocketCAN Python bindings (
init_socketcan_canfd,close_socketcan,socketcan_scan_devices) - Device context query APIs:
stark_get_protocol_type,stark_get_port_name,stark_get_baudrate, etc. - CAN device initialization:
init_device_handler_can()/init_device_handler_can_with_hw_type() StarkProtocolType::Auto = 0enum value for auto-detecting all protocols
🔧 Example Improvements
- Runtime CAN backend selection, new communication frequency test utilities
v1.1.3 (2026/02/06)
🚀 New Features
- Built-in SocketCAN Support (Linux) - No external code required
- Protobuf Protocol Support - Revo 1 serial protocol, baud rate 115200, Slave ID 10-254
v1.1.0 (2025/02/05)
🚀 New Features
- Built-in ZQWL CAN adapter support (Linux / macOS / Windows, no extra DLL needed)
- Unified device auto-detection API:
auto_detect()→init_from_detected()→close_device_handler() - Revo 1 Advanced tactile support (RS-485 / CAN protocols)
- Cross-platform C++ examples (
c/demo/) - Python GUI debugging tools (motor control, tactile data, waveform monitoring)
⚠️ Breaking Changes
- Hardware type enum refactored, added
Revo1Advanced/Revo1AdvancedTouch - API renamed:
is_revo1()→uses_revo1_motor_api(),is_revo2()→uses_revo2_motor_api() - Initialization split:
init_config()→init_logging()+init_device_handler() - C structs prefixed with
C(e.g.,MotorStatusData→CMotorStatusData) linux/andwindows/example directories deprecated, migrate toc/
📚 Migration Guide
See CHANGELOG.md
v1.0.0 (2025/12/08)
🎉 Official Release
- Detail optimizations and official upgrade to version 1.0
v0.9.9 (2025/11/19)
🚀 New Features
- Support for Revo 1 Advanced version devices ⭐
- Unified control parameter ranges: 0~1000 for position, -1000~+1000 for speed/current/PWM
- Applicable to all Modbus, CANFD, and CAN2.0 communication protocols
⚠️ Important Notice
- Revo 1 Advanced version requires SDK v0.9.9 or higher
- Revo 1 Basic and Touch versions can use any SDK version
v0.9.8 (2025/11/04)
🚀 New Features
- CAN/CANFD Protocol: Complete Revo 2 CAN2.0/CANFD communication stack
- ZLG CAN Support: Python interface (Windows/Linux) with driver library
- CANFD Chunked R/W: Support for large data transfer (>29 registers)
- EtherCAT Tactile: Tactile sensor data collection (PDO/SDO)
- Pressure Tactile: EtherCAT/CANFD/RS-485 multi-protocol support
- Protected Current: ProtectedCurrent R/W for CAN/EtherCAT
- Action Sequence:
run_action_sequencefor CAN 2.0 - Device Type Detection: Serial number based (
get_hardware_by_sn) - Multi-Device Support: Revo1/Revo2 mixed usage
⚡ High-Frequency Communication Optimization
- C/C++ Async Calls:
setcommands now async, non-blocking - High-Freq No Retry:
get/set_finger_*, tactile reads - prevents command queue buildup - Low-Freq Retry Reduced: Device info reads reduced to 2 retries
🐛 Bug Fixes
- Fixed TurboConfig byte order, Modbus C API async calls, OTA package size handling
v0.9.0 (2025/09/20)
🐛 Bug Fixes
- Fixed known issues and improved stability
v0.8.6 (2025/08/20)
🚀 New Features
- Added CAN2.0 protocol support for first-generation dexterous hand
🔧 API Improvements
- Function naming optimization:
modbus_→stark_(more universal prefix for CANFD and EtherCAT)create_device_handler()updated naming to avoid ambiguitycanfd_init(uint8_t master_id)updated naming to avoid ambiguityinit_cfgno longer requires firmware type, automatically obtained viaget_device_infointerface
📚 Example Code
- ROS 2 examples added CAN/CANFD support
- New CAN/CANFD C++ examples
v0.7.0 (2025/07/18)
🚀 New Features
- Auto-detection of Modbus slave baud rate and device ID
- Second-generation dexterous hand tactile version interface support
🐛 Bug Fixes
- Fixed DFU firmware upgrade issues
v0.6.2 (2025/07/14)
🚀 New Features
- EtherCAT Protocol Support: Second-generation dexterous hand supports EtherCAT high-speed communication
- Extended RS485 Baud Rates: Added 1M, 2M, and 5M baud rate options for high-performance applications
- Linux Serial Port Optimization: LOW_LATENCY mode enabled by default, 400% communication frequency improvement at 460800 baud
🔧 API Improvements
- Refactored device context naming:
ModbusContext→DeviceContext(more universal device context)ModbusHandler→DeviceHandler(unified device operation interface)
🛠 Development Tools
- Integrated
python-stub-gentoolchain for automatic type stub file (.pyi) generation, enhancing IDE intellisense and type checking
⚠️ Compatibility Notice
- Please note API naming changes when migrating from older versions
v0.5.3 (2025/06/12)
🚀 New Features
- Custom Modbus read/write interfaces
- Action sequence control
- LED, buzzer, vibration motor control
🐛 Bug Fixes
- Fixed real-time position/speed/current return value errors
v0.4.5 (2025/05/14)
🚀 New Features
- Added
get_single_touch_statusfor single-finger touch detection
🔧 Improvements
- Simplified
modbus_openfunction, removed redundant parameters
v0.4.4 (2025/05/06)
🚀 New Features
- Added CANFD protocol support
� Bug Fiixes
- Fixed multiple known issues, improved stability
v0.3.6 (2025/04/16)
� Milestone
- First support for Gen 2 dexterous hand
- Established basic communication framework
v0.1.9 (2025/03/17)
📌 Initial Release
- Modbus communication protocol
- Python / C code integration
- SDK architecture