Revo 3 SDK Quick Start

This page uses the Python and C++ quickstart examples included with Revo 3 SDK v2.x. Commands are read-only by default. Motion occurs only when --move is explicitly supplied.

Prerequisites

• Complete Installation & Environment Setup.
• Ensure the Revo 3 dexterous hand is properly powered and connected via a supported Modbus RTU (RS-485) or CAN FD adapter.
• Ensure the user account has serial/CAN device permissions on Linux (e.g. dialout group).
• Before running motion tests, verify that people and obstacles are outside the hand's workspace, and ensure power can be removed immediately.

Common serial port device paths:

Platform	Example Device Path
Linux	/dev/ttyUSB0
macOS	/dev/cu.usbserial-*
Windows	COM3

1. Discover Devices

The Python discovery example scans available bus interfaces and lists online devices without issuing motion commands:

python examples/python/revo3/discover_devices.py

Add --scan-all when multiple hands are connected. If the port is already known, specify it directly via --port.

2. Initial Connection & Read-Only Check

The default quickstart command establishes a connection and retrieves device metadata, joint layout, real-time telemetry (State), and diagnostics (Health) to verify bus communications.

Run Command

Python

python examples/python/revo3/quickstart.py --port /dev/ttyUSB0

C++

./examples/c/build/demo/quickstart --port /dev/ttyUSB0

Expected Telemetry Output

Device:   <SERIAL_NUMBER> (Left)
Slave ID: <SLAVE_ID>
Model: Revo3Ultra | Hardware revision: <HW_REV> | Firmware: <FW_VER>
Layout: revo3-ultra-v1 (21 DOF)
State timestamp: <SEC>.<NSEC> (Monotonic)
Health: safety=<SAFETY_STATE>, system_state=0, error_code=0, faulted_motor_count=0

Core Code Implementation

Python (asyncio)

import asyncio

from bc_revo3_sdk import main_mod as sdk


async def main():
    manager = sdk.Manager()
    hand = None
    try:
        # Automatically discover and connect to the device
        hand = await manager.connect_auto()
        info = hand.device_info
        state = await hand.state.snapshot()
        health = await hand.health.snapshot()

        print(f"Connected to: {info.serial_number if info else 'unknown'}")
        print("Positions (deg):", state.positions_deg)
        print("Safety State:", health.safety_state)
    except sdk.SdkError as error:
        print(
            f"SDK error: {error}; effect={error.operation_effect}; "
            f"recovery={error.recovery_requirement}"
        )
        raise
    finally:
        if hand is not None:
            await hand.close()
        await manager.close()


asyncio.run(main())

C++ (C++17 RAII)

#include <revo3/revo3.hpp>

#include <cstdio>
#include <stdexcept>

int main() {
  try {
    revo3::Manager manager;
    auto hand = manager.connect_auto();
    const auto info = hand.device_info();
    const auto layout = hand.joint_layout();
    if (!layout) {
      throw std::runtime_error("Joint layout is unavailable");
    }
    const auto state = hand.state().snapshot();
    const auto health = hand.health().snapshot();

    std::printf("Connected to %s with %zu motor values; safety=%u\n",
                info.serial_number.c_str(),
                static_cast<std::size_t>(layout->joint_count),
                static_cast<unsigned>(health.safety_state));
    return 0;
  } catch (const revo3::SdkError &error) {
    std::fprintf(stderr, "Revo 3 error: %s\n", error.what());
    return 1;
  }
}

Lifecycle Management

• Python: Always call hand.close() and manager.close() inside a finally block to release underlying bus resources.
• C++: Hand and Manager follow RAII; they will automatically close and release resources upon exiting scope.

3. First Motion Test

Verify device model, 21-joint layout, State, and Health before enabling motion:

Python

python examples/python/revo3/quickstart.py --port /dev/ttyUSB0 --move

C++

./examples/c/build/demo/quickstart --port /dev/ttyUSB0 --move

Safety & Motion Notes

• Health preflight protection: Examples reject motion commands if an active hardware error or emergency stop state is detected. Do not use --allow-unhealthy during normal development.
• Asynchronous motion handles: A motion call returns a MotionHandle, which indicates command dispatch rather than physical motion completion. Always use bounded timeouts when awaiting results.
• Indeterminate error handling: If an error reports operation_effect = Indeterminate, the command may already be executing on the hardware. Query state.snapshot() to verify the physical position before blindly retrying.

Continue

• API Navigation
• Complete API Reference
• Migrate from Revo 3 SDK v1.x to v2.x
• Python examples: examples/python/revo3/ in the SDK package
• C/C++ examples: examples/c/ in the SDK package