Skip to content
简体中文

Quickstart

SDK version: 2.3.5

This guide helps first-time Revo3 SDK users connect a hand and run an initial check with Python or C++. All examples use the SDK 2.x Manager and Hand object model and demonstrate state reads, error handling, and resource cleanup.

Before you begin, confirm the following:

  • Python 3.10 or later, or a C++17 or later compiler.
  • The Revo3 hand is powered and connected through a supported Modbus RTU or CANFD adapter.
  • This guide does not cover EtherCAT. For EtherCAT integration, use the separate IgH EtherCAT example and documentation.
  • On Linux, your account can read and write the serial or CAN device, for example through the dialout group.
  • Before the first motion test, keep people and structures outside the hand’s range of motion and keep an independent power disconnect within reach.

Common port names include:

System Example port
Linux /dev/ttyUSB0
macOS /dev/cu.usbserial-*
Windows COM3

The commands below use /dev/ttyUSB0. Replace it with the actual port. When only one supported device is connected, you can omit the port and let the SDK discover it automatically.

CPython wheels use cp310-abi3 and require Python 3.10 or later:

Operating system Wheel architectures Package compatibility floor
Linux x86_64, aarch64 glibc 2.31+, such as Ubuntu 20.04
macOS Apple Silicon arm64 macOS 11+
Windows x86_64 64-bit CPython

This table describes package coverage, not hardware validation of every device, adapter, and firmware combination. Intel macOS builds are compatibility-only and are not part of formal macOS release validation.

C++ examples require a C++17 compiler, GNU Make, Bash, curl or wget, and unzip. Use GCC/Clang on Linux or Xcode Command Line Tools on macOS. On Windows, run the Bash/Make commands below in MSYS2/MinGW, not directly in PowerShell. Headers and shared libraries must come from the same SDK version and match the process architecture.

Clone the examples repository:

终端窗口
git clone https://github.com/BrainCoTech/brainco-revo3-sdk.git
cd brainco-revo3-sdk

You can also select Code > Download ZIP on the repository page, extract the archive, and enter the repository root. Run the remaining commands from that directory.

Create and activate a Python 3.10 or later virtual environment, then install the SDK and example dependencies:

终端窗口
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "bc-revo3-sdk==2.3.5" ./python
python -c "from bc_revo3_sdk import main_mod as sdk; print(sdk.get_sdk_version())"

On Windows PowerShell, create the environment with py -3.10 -m venv .venv and activate it with .venv\Scripts\Activate.ps1. The public examples repository’s python/pyproject.toml allows bc-revo3-sdk>=2.3.5,<3; the command above pins the SDK to this guide’s 2.3.5 and installs the example dependencies. The version query should print 2.3.5.

If the SDK installation fails or no prebuilt package supports the required platform architecture, contact technical support.

Run device discovery first. This command does not send motion commands:

终端窗口
python python/revo3/discover_devices.py

By default, scanning stops after the first recognizable device is found. Add --scan-all when multiple devices are connected.

Connect to the target device and read device information, firmware versions, joint layout, touch-layout availability, State, and Health:

终端窗口
python python/revo3/quickstart.py --port /dev/ttyUSB0

Without a motion option, the command performs read-only checks. A successful connection produces output similar to:

Device: <SERIAL_NUMBER> (Left)
Slave ID: <SLAVE_ID>
Product code: <PRODUCT_CODE> | Hardware revision: <HW_REV> | Firmware: <FW_VER>
Layout: <LAYOUT_ID> (21 DOF)
Touch layout: not available
State timestamp: <SEC>.<NSEC> (Monotonic)
Health: safety=<SAFETY_STATE>, system_state=0, error_code=0, faulted_motor_count=0

After confirming that the device has a supported 21-joint layout and the State and Health preflight reports no fault, run the four-finger flexion test:

终端窗口
python python/revo3/quickstart.py --port /dev/ttyUSB0 --move

The following example shows the core flow. See Basic Usage for the complete API contract.

import asyncio
from bc_revo3_sdk import main_mod as sdk
async def main():
manager = sdk.Manager()
hand = None
try:
hand = await manager.connect_auto()
layout = hand.joint_layout
if layout is None or layout.joint_count != 21:
raise RuntimeError("Motion requires a supported 21-joint layout")
state = await hand.state.snapshot()
health = await hand.health.snapshot()
if health.system_state or health.error_code or health.faulted_motor_count:
raise RuntimeError("Health preflight rejected motion")
target = list(state.positions_deg)
# Flex the MCP and PIP joints for Pinky through Index.
for joint in (1, 2, 5, 6, 9, 10, 13, 14):
target[joint] = 45.0
motion = await hand.motion.move_to(target, duration=1.5)
result = await motion.wait(timeout=5.0)
print(result)
finally:
if hand is not None:
await hand.close()
await manager.close()
asyncio.run(main())

[!TIP] For single-joint, single-finger, and thumb motion options, run python python/revo3/quickstart.py --help.

Download the SDK library and public headers for your platform, then build the C++ examples:

终端窗口
bash download-lib.sh
make -C c

download-lib.sh installs SDK artifacts under dist/. The example repository does not contain the SDK core sources; no SDK build is required.

Run the quickstart example for discovery and read-only checks:

终端窗口
./c/build/demo/quickstart --port /dev/ttyUSB0

By default, scanning stops after the first recognizable device is found. Without a motion option, the command reads device information, firmware versions, joint layout, State, and Health without moving the hand.

After confirming that the device has a supported 21-joint layout and the State and Health preflight reports no fault, run the four-finger flexion test:

终端窗口
./c/build/demo/quickstart --port /dev/ttyUSB0 --move

The following example shows the core flow. See Basic Usage for the complete API contract.

#include <revo3/revo3.hpp>
#include <stdexcept>
#include <vector>
using namespace std::chrono_literals;
revo3::Manager manager;
auto hand = manager.connect_auto();
const auto state = hand.state().snapshot();
const auto health = hand.health().snapshot();
if (health.system_state != 0 || health.system_error_code != 0 ||
health.faulted_motor_count != 0) {
throw std::runtime_error("Health preflight rejected motion");
}
const auto layout = hand.joint_layout();
if (!layout) {
throw std::runtime_error("Joint layout is unavailable");
}
if (layout->joint_count != 21) {
throw std::runtime_error("Motion requires a supported 21-joint layout");
}
std::vector<float> target(state.motors.positions_deg,
state.motors.positions_deg + layout->joint_count);
for (int joint : {1, 2, 5, 6, 9, 10, 13, 14}) {
target[static_cast<std::size_t>(joint)] = 45.0F;
}
auto motion = hand.motion().move_to(target, 1500ms);
const auto result = motion.wait(5s);
hand.close();
manager.close();

[!TIP] The C++ example also supports single-joint, single-finger, and thumb motion. Run ./c/build/demo/quickstart --port /dev/ttyUSB0 --move-finger.

  • Motion sequence (--move): keeps the thumb and other joints unchanged, flexes the four fingers to the target angle, and then returns them to the initial position.
  • Target angle (--angle): defaults to 45 degrees. Use, for example, --angle 60 to set a different target.
  • Reference zero: zero positions and positive directions follow the device joint-layout and calibration definitions.
  • Units: position uses degrees, velocity uses rpm, and current uses mA.

Note: The examples check State and Health before motion. They reject motion when a fault is detected. Use --allow-unhealthy only after confirming that proceeding is safe.

A successful run reports:

  1. Device model, hardware and firmware versions, joint layout, and touch-layout availability.
  2. State and Health without unresolved hardware faults.
  3. Motion-stage results:
    • Motion 1 (Flex): Succeeded
    • Motion 2 (Return): Succeeded

Note: For motion and other write commands, Indeterminate means that the command was sent but no acknowledgement arrived before the deadline. The command may have taken effect. Read State before deciding whether to issue another command. A motion.wait() timeout only stops the application from waiting; physical motion already accepted by the device can continue.

  • Developer Guide: asynchronous programming, subscriptions, servo control, operation waiting and cancellation, error handling, and diagnostics
  • API Reference: method signatures, data models, parameters, and failure behavior
  • 1.x to 2.0 Migration Guide: API changes and upgrade instructions

Additional examples:

Python

  • Multiple hands: python python/revo3/multi_hand.py --help
  • Touch data: python python/revo3/touch_sensor.py --help
  • Device configuration and maintenance: python python/revo3/device_operations.py --help

C++

  • Multiple hands: make -C c build/demo/multi_hand
  • Touch data: make -C c build/demo/touch_sensor
  • Device configuration and maintenance: make -C c build/demo/device_operations

The single-command position, current, and MIT example defaults to read-only; add --run to write. It requires a supported 21-DOF hand. See the developer guide for units and stopping semantics. OTA examples report transfer progress; reconnect after 100% to verify the installed version.

终端窗口
python python/revo3/discrete_control.py --mode mit --help
./c/build/demo/discrete_control --mode mit --help
python python/revo3/firmware_update.py --help
./c/build/demo/firmware_update --help