Skip to content

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_31 packages 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 ​

DeviceRS-485ProtobufCANCAN FDEtherCAT
Revo 1 Basic✅✅✅❌❌
Revo 1 Advanced✅❌✅Delivery-specificDelivery-specific
Revo 2✅❌✅✅✅

Download & Installation ​

Public example repository ​

Open the brainco-hand-sdk example repository

Python SDK Installation ​

bash
# Install from PyPI
pip3 install bc-stark-sdk==2.0.9

# China mirror (Alibaba Cloud OSS)
bash install_whl.sh 2.0.9

C/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:

python
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:

bash
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.bin
Python 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:

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++ Demos ​

Compile and execute cross-platform C++ programs under c/:

bash
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:

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!

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-sdk 2.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=1 before 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++) and get_finger_max_position (Python) reading the setting register instead of the readback register. The getter now reads 952 + finger_id - 1 for 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_status and stark_calibrate_touch_sensor_with_status. These blocking C APIs return 0 for transport success and -1 for 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 void APIs 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 uses 10. Older integrations using 4 for Revo2 Touch must migrate to the named constant: 4 now 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_31 for Ubuntu 20.04+. C/C++ ZIPs include matching headers and the MIT LICENSE; 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, and uv workflows.
  • 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-sdk repository.
  • brainco-hand-sdk now contains Revo 1 / Revo 2 examples and prebuilt libraries only.
  • Python wheels upgraded to cp39-abi3 stable 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): Baudrate enum values reordered (e.g., BAUD5MBPS changed 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) via ArrayPressureTouchDataBuffer
  • C++ demos: hand_demo and hand_monitor with array_pressure mode
  • 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 touch
    • is_force3d_touch() — 3-axis force touch
    • is_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_FLAG check in SocketCAN recv_can/recv_canfd

📚 Documentation & Project Structure ​

  • Archived deprecated linux/ and windows/ folders to archive/
  • Added install_whl.sh script 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 = 0 enum 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/ and windows/ example directories deprecated, migrate to c/

📚 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_sequence for 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: set commands 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 ambiguity
    • canfd_init(uint8_t master_id) updated naming to avoid ambiguity
    • init_cfg no longer requires firmware type, automatically obtained via get_device_info interface

📚 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-gen toolchain 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_status for single-finger touch detection

🔧 Improvements ​

  • Simplified modbus_open function, 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
Help