Migrate from Revo 3 SDK v1.x to v2.x

This guide uses the Python stub and C header from the officially released Revo 3 SDK v1.5.1 as the verified v1.x baseline. Applications on earlier releases must first identify the symbols they actually use. Revo 3 SDK v2.x removes the v1.x Python module-level API, DeviceContext, and old C connection interface; migration changes ownership, async calls, motion waiting, subscriptions, and error recovery.

Entry point and lifecycle

1.x	2.x	Required change
Python DeviceContext + slave_id	Manager -> Hand	Move identity and operations into Hand
C DeviceHandler * and manual transport	Revo3ManagerHandle * / Revo3DeviceHandle *	Let Manager own connections and transport reuse
Module-level revo3_* / stark_*	hand.motion, hand.state, and other domains	Migrate by capability domain
Repeated slave_id arguments	Identity stored by Hand	Remove the ID from domain calls
Manual shared-transport shutdown	Close Hand, then Manager	Cover every normal and exceptional exit

Motion

1.x family	2.x API
revo3_move_hand*	await hand.motion.move_to(...)
revo3_move_joint*	await hand.motion.move_joint(...)
revo3_move_finger*	await hand.motion.move_finger(...)
revo3_move_thumb*	await hand.motion.move_thumb(...)
_wait variants	await handle.wait(timeout=...)
_with_speed variants	speed= parameter
_with_gains variants	kp= and kd= parameters
Continuous high-rate targets	open_servo() and session.send_*()

A target-motion call returns a handle before completion. Do not loop over move_to() for streaming control; use a Servo session and close it explicitly.

speed= applies to move_to() and move_joint() only. Finger and thumb motion continue to use duration and must not inherit the hand/joint speed migration mechanically.

State and subscriptions

2.x does not use the 1.x collector or shared buffer. Use snapshot() for one value and subscribe() for periodic pull-based acquisition. The SDK does not retain subscription history; applications that need history must use a bounded queue or external storage.

Touch, Health, and device operations

1.x capability	2.x entry point
Touch raw data and summaries	await hand.touch.snapshot()
Continuous touch reads	hand.touch.subscribe()
System and electrical state	await hand.health.snapshot()
Device configuration	hand.config.snapshot() and setters
Calibration and zero position	hand.calibration
Reboot, factory reset, and firmware update	hand.maintenance

Read module IDs, regions, point counts, and signal capabilities from TouchLayout.modules. Do not keep hard-coded assumptions from a 1.x homogeneous touch layout.

Verified v1.5.1 mappings include:

1.x Python	2.x Python
revo3_calibrate_touch_zero* / revo3_calibrate_pressure_touch_zero*	hand.touch.tare(module_index=None)
revo3_set_touch_data_type / revo3_get_touch_data_type	hand.touch.set_read_mode() / read_mode()
revo3_set_touch_module_value_type / revo3_get_touch_module_value_type	hand.touch.set_value_mode() / value_mode()
revo3_get_all_matrix_touch_module_point_counts	hand.touch.point_counts()
revo3_get_all_matrix_touch_module_serial_numbers	hand.device_info.touch_serial_numbers
revo3_restart_matrix_touch_modules*	hand.touch.restart(module_index=None)

The 1.x secondary-calibration operations revo3_set_pressure_touch_force_tare and revo3_set_pressure_touch_module_force_tare have no public 2.x replacement and are not equivalent to tare(). Treat applications that use them as blocked until the device or firmware owner defines a maintenance path.

Recompile C applications with the 2.x header. A 1.x shared library and 2.x header are not ABI-compatible.

Errors and reconnection

• Handle structured SdkError, operation_effect, and recovery_requirement.
• For Indeterminate, read State before retrying a write.
• After reconnecting, old Hand, MotionHandle, subscriptions, and Servo sessions are invalid.
• Python and C++ object methods omit revo3_; C ABI symbols retain the prefix.

Validation order

1. Connect and read device information, State, and Health only.
2. Verify units, joint count, and layout.
3. Exercise timeout, cancellation, disconnect, and cleanup paths.
4. Enable a small, explicit motion test.
5. Validate optional Touch, Servo, calibration, and firmware-maintenance flows.

Mock tests validate application flow but cannot replace validation against the target device and firmware. Use the API navigation to locate interfaces and the complete API manual for the complete contract.