Quickstart

This guide helps first-time Revo3 SDK 2.0 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.

1. Prerequisites

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.

2. Get the Examples

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.

3. Python Quickstart

3.1 Install the SDK

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 ./python

On Windows PowerShell, create the environment with py -3.10 -m venv .venv and activate it with .venv\Scripts\Activate.ps1. The python/pyproject.toml package installs bc-revo3-sdk>=2.1.0,<3 and the required example dependencies.

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

3.2 Run the Read-Only Checks

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

3.3 Python Example

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()
        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.

4. C++ Quickstart

4.1 Build the Example

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.

4.2 Run the Read-Only Checks

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

4.3 C++ Example

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");
}
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.

5. Motion and Safety Rules

5.1 Motion and Target Angle

• 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.

5.2 Health Preflight

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.

5.3 Expected Output

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.

6. Next Steps

• 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