Developer Guide
SDK version: 2.3.3
This guide covers the Revo3 SDK 2.x asynchronous programming model, continuous data subscriptions, servo control, operation waiting and cancellation, production error handling, and offline diagnostics. Examples use Python. See the Revo3 API Reference for the corresponding C++ interfaces and complete signatures.
Linux C/C++ Runtime Dependencies
Section titled “Linux C/C++ Runtime Dependencies”libusb and libudev are system runtime dependencies used by the SDK on Linux and can be installed through the system package manager. Default portable packages already include both libraries, so no separate installation is needed. System mode requires compatible versions installed on the system:
# Debian / Ubuntusudo apt-get install libusb-1.0-0 libudev1bash download-lib.sh --system-depsUse the download script from the examples repository. System mode checks dynamic dependencies before reusing or replacing the SDK. If dependencies are missing, it stops and preserves the existing installation without installing or overwriting system libraries. Both modes preserve SDK and third-party licenses. This option affects only C/C++ distribution, not Python wheels.
1. Asynchronous Programming with asyncio
Section titled “1. Asynchronous Programming with asyncio”All Revo3 Python 2.x device I/O APIs are asynchronous and must run in an asyncio event loop:
import asynciofrom bc_revo3_sdk import main_mod as sdk
async def main() -> None: manager = sdk.Manager() try: hand = await manager.connect_auto() state = await hand.state.snapshot() print(state.positions_deg) finally: await manager.close()
asyncio.run(main())- Wrap synchronous entry points with
asyncio.run(). Do not create an event loop directly inside callbacks or at library-module import time. - SDK waits do not block the event loop. Other coroutines, subscriptions, and controls for other hands continue to run. Use
asyncio.gather()for concurrent operations. - The
manager.discover()on_foundcallback runs synchronously on the SDK scan thread. It is not a coroutine and cannot useawait. ReturnFalseto stop scanning early. - Properties and non-I/O methods, such as
hand.device_infoandsession.state, are not coroutines. Only device I/O and wait operations requireawait.
2. State, Touch, and Health Subscriptions
Section titled “2. State, Touch, and Health Subscriptions”The Manager and Hand object APIs provide pull-based asynchronous subscriptions for State, Touch, and Health.
2.1 State Subscription
Section titled “2.1 State Subscription”from bc_revo3_sdk import main_mod as sdk
async def monitor_state(hand: sdk.Hand) -> None: subscription = hand.state.subscribe(period=0.02) try: while True: state = await subscription.next() print(state.timestamp.clock, state.positions_deg) finally: subscription.close()HandState contains operating_states, positions_deg, velocities_rpm, currents_ma, and timestamp. Read low-rate raw motor status codes through (await hand.health.snapshot()).motor_fault_codes. This compatibility field includes both fault bits and non-fault state bits.
2.2 Touch Subscription
Section titled “2.2 Touch Subscription”from bc_revo3_sdk import main_mod as sdk
async def monitor_touch(hand: sdk.Hand) -> None: subscription = hand.touch.subscribe(period=0.05) try: while True: frame = await subscription.next() for module in frame.modules: if module.sample_state != sdk.TouchSampleState.Valid: print(module.module_id, module.sample_state) continue if module.points is not None: print(module.module_id, "points:", module.points) if module.force3d is not None: print(module.module_id, "force (mN):", module.force3d) if module.torque2d is not None: print(module.module_id, "torque (Nm):", module.torque2d) finally: subscription.close()TouchFrame.modules contains the modules available for the detected layout. Depending on module capabilities, each entry can contain taxel values, calibrated regional force in regional_forces_mn, three-axis force, two-axis torque, resultant_force_mn, and status fields. Three-axis and resultant force values use mN.
Identify modules by module_id, not array position. Check sample_state before using a signal and use optional fields only when they are not None. An empty module list produces no samples; non-Valid states are not valid measurements.
The SDK reads all values from 36-point and 71-point piezoresistive-array palms. Spatial displays also need a matching coordinate map. The GUI example still uses legacy 36-point palm coordinates; see the GUI guide for the display limits with 71-point data.
2.3 Health Subscription
Section titled “2.3 Health Subscription”async def monitor_health(hand: sdk.Hand) -> None: subscription = hand.health.subscribe(period=0.2) try: while True: health = await subscription.next() print(health.safety_state, health.error_code) finally: subscription.close()2.4 Subscription Semantics
Section titled “2.4 Subscription Semantics”subscribe()returns a pull-based subscription. Callnext()to wait for the next read.- The first
next()reads the current State, Touch, or Health snapshot immediately. Each subsequent call waits for the configured interval before reading. Subscriptions do not retain historical samples or collect data in the background between calls. close()is idempotent. A closed subscription performs no further reads.- State, Touch, and Health periods are independent and must be finite positive values in seconds.
Timestamp.clockidentifies the clock domain. Compare or subtract timestamps only when theirclockvalues match.- Subscriptions are for monitoring. Start servo control through
hand.motion.open_servo().
3. Servo Control
Section titled “3. Servo Control”Use open_servo() for vision tracking, teleoperation, or algorithmic control that sends targets at a fixed period.
The following example demonstrates session lifetime and periodic position commands. Before running it, secure the hand, remove mechanical interference, configure an appropriate current limit, and keep an independent power disconnect within reach. The application remains responsible for target generation, joint-limit checks, and recovery after failures.
import asyncio
period = 0.02state = await hand.state.snapshot()target_positions = list(state.positions_deg)session = hand.motion.open_servo(command_timeout_ms=100)try: for _ in range(100): await session.send_position(target_positions) await asyncio.sleep(period)except sdk.SdkError as error: if error.operation_effect == sdk.OperationEffect.Indeterminate: state = await hand.state.snapshot() print("Servo command result is indeterminate; current positions:", state.positions_deg) raisefinally: session.close()In addition to send_position, a servo session provides send_velocity, send_current, send_impedance, and send_mit. See Hand Domain APIs for parameters and units.
command_timeout_msmonitors the interval between consecutive servo commands. It is not a background heartbeat. When omitted, the session usesRuntimeOptions.servo_command_timeout_ms.- After a timeout,
ServoSession.statebecomesExpired. The SDK releases software ownership and rejects additional commands from that session. - Session expiry does not send a stop command and does not prove that the motors stopped or released torque. Apply firmware watchdog requirements and hardware-validated recovery behavior separately.
4. Waiting for and Cancelling Operations
Section titled “4. Waiting for and Cancelling Operations”Motion calls such as move_to, move_finger, move_thumb, and move_joint return an OperationHandle that tracks the final outcome:
motion = await hand.motion.move_to(target_positions, duration=1.5)try: result = await motion.wait(timeout=5.0) if result == sdk.OperationState.Succeeded: print("Motion completed") elif result == sdk.OperationState.Indeterminate: # The device may be moving. Read the actual position before deciding what to do. state = await hand.state.snapshot() print("Result is indeterminate; current positions:", state.positions_deg)except sdk.SdkError as error: print(f"Motion failed [{error.code}]: {error.message}")wait(timeout)waits for a terminal state. A timeout only stops the application from waiting; physical motion already accepted by the device can continue.handle.stateis always readable. After a terminal state,handle.errorcontains the associatedSdkError, orNonewhen no error occurred.handle.cancel()requests cooperative cancellation. The SDK lets the active register request finish, stops sending trajectory points at the next control-cycle boundary, and releases software ownership. It does not discard an in-flight serial request. If the final physical position cannot be confirmed, the operation ends asIndeterminate.- See Waiting, Cancellation, and Motion Conflicts for the full state machine.
5. Production Error Handling and Retry
Section titled “5. Production Error Handling and Retry”Object API failures raise SdkError. In addition to code and message, the following machine-readable fields support recovery decisions:
| Field | Type | Purpose |
|---|---|---|
operation_effect |
OperationEffect |
Whether a write command may have taken effect |
retryable |
bool |
Whether the SDK considers an automatic retry safe; limited to side-effect-free reads with connection or timeout errors |
recovery_requirement |
RecoveryRequirement |
Required action: None_, Retry, Reconnect, or OperatorAction; Python uses None_ because None is a keyword, while C++ uses None |
low_level_cause |
str | None |
Original driver-level cause for diagnostic records |
For failed write commands, inspect operation_effect first:
NotApplied: the device did not execute the command, for example because validation failed before transmission.PartiallyApplied: part of the operation took effect, such as a manager close that could not release every transport.Indeterminate: the command was sent but its response was lost. Read State to determine the current physical condition. Do not automatically repeat the write.
The following pattern retries only when the SDK marks a read as retryable:
async def read_with_retry(hand: sdk.Hand, max_retries: int = 3): for attempt in range(max_retries): try: return await hand.state.snapshot() except sdk.SdkError as error: print(f"[{error.code}] {error.message}") if error.recovery_requirement == sdk.RecoveryRequirement.Reconnect: await hand.close() raise # Let the caller decide whether to reconnect. if not error.retryable or attempt + 1 >= max_retries: raise await asyncio.sleep(0.1 * (attempt + 1))Warning: Automate retries only for read operations with
retryable=True. Write operations, including motion, configuration, and firmware updates, always reportretryable=False. Recover according tooperation_effectandrecovery_requirement.
6. Diagnostics, Recording, and Offline Replay
Section titled “6. Diagnostics, Recording, and Offline Replay”After installing the public examples as described in Quickstart, run the diagnostics and capture CLI from the example repository root:
# Inspect device information and current state.python \ python/revo3/manager_cli.py --port /dev/ttyUSB0 inspect
# Record state data as JSONL.python \ python/revo3/manager_cli.py --port /dev/ttyUSB0 \ record state.jsonl --duration 10
# Replay the recording offline.python \ python/revo3/manager_cli.py replay state.jsonlOffline replay only reads and displays the recording. It does not send historical motion to a device.
6.1 Teach and Motion Replay
Section titled “6.1 Teach and Motion Replay”The manager_cli record/replay commands above record state for offline inspection. The separate teach/replay motion APIs record manual movement as a trajectory and execute that trajectory on a device:
try: trajectory = await asyncio.wait_for( hand.motion.teach_hand(duration=10.0, dt=0.02), timeout=15.0, )
# Replay produces physical motion. Complete the mechanical and power checks first. await asyncio.wait_for( hand.motion.replay_hand(trajectory, dt=0.02), timeout=15.0, )except (asyncio.TimeoutError, sdk.SdkError) as error: # A timeout or communication failure does not prove that the device did not move. state = await hand.state.snapshot() print("Teach or replay did not complete with confirmation; current positions:", state.positions_deg) raiseUse teach_joint and replay_joint for a single joint. See Hand Domain APIs for control semantics and safety boundaries.
7. Single Commands, OTA Progress, and Motor Metadata
Section titled “7. Single Commands, OTA Progress, and Motor Metadata”7.1 Low-rate or Single Commands
Section titled “7.1 Low-rate or Single Commands”For a supported 21-DOF hand, call await hand.motion.set_position(position_deg),
set_current(current_ma), or set_mit(position_deg, velocity_rpm, kp, kd, feedforward_current_ma)
to send a full-hand target once, without open_servo() or a heartbeat.
Arrays contain 21 values in logical joint order. Units are degrees, rpm, and mA;
MIT’s fifth array is feedforward current in mA. The SDK does not interpolate or
resend automatically. Success confirms the write, not motion completion.
Firmware defines target retention, mode switching, and stopping. Closing the
connection does not stop control. Writes conflict with trajectory, Servo, and
drag control; inspect state after an error or cancellation before recovery.
Python discrete_control.py and C++ discrete_control default to read-only.
With --run, they send the current pose or zero current; MIT uses kp=1, kd=0.1,
zero velocity, and zero feedforward current. These commands can change motor
behavior or hand support; clear the workspace first.
Single-command control includes set_joint_*, set_finger_*, and
set_thumb_*, matching the granularity of move_*. Each supports position,
current, and mit.
| Scope | Selector and targets | Logical joint order |
|---|---|---|
set_joint_* |
joint_index=0..20; scalar targets |
Selected joint only |
set_finger_* |
finger_index=1..4; each array has 4 values |
1=Index J12–15, 2=Middle J8–11, 3=Ring J4–7, 4=Pinky J0–3; each finger uses Abd, MCP, PIP, DIP |
set_thumb_* |
No finger selector; each array has 5 values | J16–20: Flex, MCP, IP, Abd, Rotation |
Only selected joints are written; these APIs do not read and rewrite full-hand
targets. set_* does not plan a trajectory and returns Python None / C++ void.
move_* interpolates motion and returns an OperationHandle. Scoped writes
still own the whole hand and conflict with every move_*, Servo, and drag
operation, including operations selecting other joints.
Finger and thumb targets are written sequentially in logical order, not atomically.
All arrays, values, and collision guards are checked before the first write.
On failure, subsequent writes stop; there is no automatic resend or rollback.
If earlier joints acknowledged their writes and a later joint rejects its write,
operation_effect is PartiallyApplied. A lost response is Indeterminate.
Read state before recovery. Cancelling an already-started Python await does not
withdraw targets: the worker retains ownership and handles the group’s responses
until the group finishes or fails.
7.2 OTA Progress
Section titled “7.2 OTA Progress”hand.maintenance.update_firmware(..., on_progress=callback) returns an operation
handle. handle.progress reports transfer progress from 0 to 1. C++ queries
operation.progress(). 100% means transfer completion. Wait for success, then
rediscover the device and verify its installed firmware version.
Python callbacks run synchronously on a background thread. Do not update a UI
or await directly there; use loop.call_soon_threadsafe() for asyncio notifications.
Updates are typically coalesced every 100 ms. Callback exceptions go to
sys.unraisablehook and do not cancel the update. wait() does not wait for
callback processing. Failure or cancellation preserves the last progress value.
firmware_update.py / firmware_update demonstrate progress reporting and
require --run before writing firmware.
7.3 Motor Versions and Serial Numbers
Section titled “7.3 Motor Versions and Serial Numbers”Call await hand.refresh_device_info() and await hand.refresh_firmware_info(),
then read hand.device_info.motor_serial_numbers and
hand.firmware_info.motor_firmware_versions. Successful motor reads enter the
cache immediately. A later touch read failure still raises an error but retains
the motor results. After catching it, inspect the properties for partial results;
this does not mean every field refreshed successfully. Touch firmware version
reads are not implemented yet and return an empty list; this does not indicate
missing touch hardware. Both device_operations examples demonstrate refresh,
error reporting, and cache reads.
See the API reference for signatures, capability limits, and error semantics.