1.x to 2.0 Migration Guide

This guide covers migration of existing 1.x applications to 2.0. The Revo3 API Specification is authoritative for the 2.0 public contract.

1. Entry Points & Lifecycle Changes

Version 2.0 completely removes the 1.x compatibility layers (including Python module-level functions, DeviceContext, as well as C DeviceHandler, manual transport initialization, global callback setters, and stark_* prefixed symbols). Applications connect through Manager and invoke capabilities through domain objects on Hand:

1.x usage	2.0 alternative	Notes
DeviceContext + slave_id (Python)	Manager -> Hand	Python object-oriented async model and context management
DeviceHandler / manual transport (C)	revo3_manager_create() / revo3_manager_connect()	C ABI lifecycle and transport sharing managed by Manager
Global or module-level revo3_* / stark_* functions	hand.motion, hand.state, hand.touch, hand.health	Unified into Hand’s 8 domain object methods
Application-managed port and slave mapping	Device identity on Hand, with Transport sharing managed by Manager	Eliminates multi-device bus conflicts and lifecycle leaks
Manual shared-context shutdown	Hand.close() / revo3_device_close() releases one hand; Manager releases ports	Clean, independent handle shutdown

2. Motion APIs

The 1.x combinations of target scope, wait style, speed, and gains map to four target-motion methods and one streaming-control entry point:

1.x method family	2.0 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	Call await handle.wait(...) on the returned OperationHandle
_with_speed variants	Use the speed= argument
_with_gains variants	Use the kp= and kd= arguments
High-rate drag or continuous target updates	Open hand.motion.open_servo(...), then call send_*()

Receiving a target-motion Handle does not mean motion has completed. Use ServoSession for frequent target updates and handle its command timeout, closure, and disconnect behavior.

3. State and Continuous Collection

State subscriptions do not use the 1.x collector or shared buffer. Each next() directly reads the current snapshot after the configured interval, and the SDK keeps no subscription history:

subscription = hand.state.subscribe(period=0.02)
try:
    while True:
        state = await subscription.next()
finally:
    subscription.close()

Applications that need history should maintain a bounded queue. Per-motor temperatures and the online bitmask remain separate reads:

temperatures = await hand.health.motor_module_temperatures_c()
online_mask = await hand.health.motor_online_mask()

4. Touch, Health, and Configuration

1.x capability	2.0 entry point
Raw Touch data and Summary	await hand.touch.snapshot() returns a typed TouchFrame
Single touch module data	await hand.touch.module_snapshot(module_id) returns one typed TouchModuleData
Continuous Touch reads	hand.touch.subscribe(); each next() pulls a snapshot
System state and electrical values	await hand.health.snapshot()
Experimental collision configuration, state, and reset	hand.experimental_collision.configure(...) / active_joints() / reset()
Device configuration	hand.config.snapshot() and named setters
Calibration and zero positions	hand.calibration
Reboot, factory reset, and DFU	hand.maintenance

The unified Touch API removes protocol-specific entry points. Python and C++ callers must migrate to the common methods on hand.touch:

Previous entry point	Unified 2.0 entry point
calibrate_touch_zero / pressure_touch_tare	hand.touch.tare(module_index=None)
matrix_touch_tare	hand.touch.tare(module_index=None); use cancel_tare() and tare_status() for cancellation and status
set/get_touch_data_mode	hand.touch.set_read_mode() / read_mode()
set/get_touch_value_type, set/get_matrix_touch_output_mode	hand.touch.set_value_mode() / value_mode()
get_matrix_touch_info	hand.touch.point_counts(); read serial numbers from hand.device_info.touch_serial_numbers
restart_matrix_touch	hand.touch.restart(module_index=None)

The C ABI now uses the unified revo3_device_touch_* names. Version 2.0 does not export link aliases for the removed symbols, so applications must be recompiled:

Removed C symbol	Replacement
revo3_device_calibrate_touch_zero, revo3_device_pressure_touch_tare, revo3_device_matrix_touch_tare	revo3_device_touch_tare
revo3_device_set_touch_data_mode, revo3_device_get_touch_data_mode	revo3_device_touch_set_read_mode, revo3_device_touch_get_read_mode
revo3_device_set_touch_value_type, revo3_device_get_touch_value_type, revo3_device_set_matrix_touch_output_mode, revo3_device_get_matrix_touch_output_mode	revo3_device_touch_set_value_mode, revo3_device_touch_get_value_mode
revo3_device_get_matrix_touch_tare_status	revo3_device_touch_get_tare_status
revo3_device_get_matrix_touch_info	revo3_device_touch_get_layout for modules[*].point_count; touch serial numbers are available from device information
revo3_device_restart_matrix_touch	revo3_device_touch_restart

Every module_index argument takes a public module_id: in pure piezoresistive-array / high-density-matrix layouts it equals the TouchLayout.modules array position (dense 0~10); in hybrid layouts it uses sparse numbering aligned with the protocol physical IDs (palm 0, fingertip force/torque fingertips 1/3/5/7/9, fingerpads 2/4/6/8/10) and no longer matches the array position. For optional C/C++ arguments, -1 applies the operation to every supported module in the current layout.

Touch consumers must account for these breaking data-model changes:

• LegacyForceSummary is the 4023 = 1 compatibility mode for secondary-calibrated data from a small number of shipped devices and is scheduled for removal. Its summary payload is written per module to TouchModuleData.regional_forces_mn instead of TouchFrame.summary. New applications should not depend on it.
• Applications read regional_forces_mn directly from each module; module layout information (module_id, region, layout_id, point_count, signals) comes from TouchLayout.modules. Do not hard-code pure-piezoresistive-array module IDs because public module IDs differ in hybrid layouts.
• The per-fingertip force/torque module normal_force field is renamed to resultant_force_mn; its capability is TouchSignal.ResultantForce, in mN.
• TouchModuleData.points is now optional. When a module is disabled, not sampled, failed, or unavailable, it is None instead of being filled with zeroes.
• After a successful LegacyForceSummary read, corresponding modules have sample_state = Valid and points = None. PointArray and this compatibility mode are mutually exclusive, and regional-force and point frames across a mode switch are not guaranteed to represent the same physical sample.
• TouchFrame no longer exposes one mode or a frame-level summary. A hybrid frame may carry tactile points, per-module regional forces, and force/torque data together; applications inspect each module’s sample_state, regional_forces_mn, and its optional signal fields.

LegacyForceSummary and ResultantForce are not synonyms: the former describes the piezoresistive-array secondary-calibrated compatibility mode, while the latter describes one fingertip force/torque module’s physical resultant-force signal.

The public TouchValueMode enum contains only Adc (0) and Force (2). piezoresistive-array register 4024 value 1 is unused and must not be migrated from a 1.x legacy name into a new public enum member.

5. Errors and Lifecycle

• Version 2.0 uses structured SdkError. When a write response is lost, inspect operation_effect; for Indeterminate, read device state before retrying.
• A reconnect invalidates old Hand, Handle, subscription, and ServoSession objects. Reconnect and obtain new objects.
• Python and C++ object methods omit a redundant revo3_ prefix. Public C ABI symbols retain the prefix.
• The Python GUI changes only its SDK adapter/API calls; its layout, styling, and product behavior remain unchanged.

6. Validation

Use mocks first for connection, state, motion parameters, Touch, Health, errors, and shutdown. Then validate fields, units, physical motion, disconnects, lost responses, firmware Watchdog behavior, Touch, and DFU on hardware. Mock tests do not replace on-device behavior validation.