Python API usage guidelines

Import the Python 2.x public objects from bc_revo3_sdk.main_mod and perform domain operations through Manager and Hand. Use the official API specification for exact types and signatures.

Lifecycle and cleanup

• Await asynchronous methods inside an asyncio event loop.
• Use async with, or close Hand and Manager in a try/finally block.
• Subscriptions and ServoSession objects have independent lifecycles and must be closed on success, failure, and cancellation paths.
• After a disconnect, close the old objects and reconnect through Manager. Do not reuse old motion handles, subscriptions, or Servo sessions.
• Await cleanup before process exit so serial ports, CAN devices, and background tasks are released.

See quickstart.py for the connection and cleanup structure, and multi_hand.py for multi-device ownership.

Async operations, timeouts, and cancellation

• A returned MotionHandle does not mean physical motion is complete. Always use a bounded timeout when waiting.
• A timeout does not prove that a command was not applied. If operation_effect is Indeterminate, read State before deciding whether a retry is safe.
• Task cancellation must still run finally cleanup. Close the subscription or session instead of only cancelling its outer asyncio.Task.
• Use ServoSession for high-rate targets; do not emulate streaming by repeatedly invoking discrete motion methods.
• Define the Servo send cadence and command timeout explicitly. Application scheduling is not a fixed bus- or firmware-rate guarantee.

See trajectory_control.py for bounded motion waiting and streaming_control.py for continuous control.

Errors and recovery

• Catch SdkError and use code, operation_effect, recovery_requirement, and retryable; do not branch only on message text.
• Before retrying, determine whether the operation may already have taken effect. Read State and Health when the device outcome is uncertain.
• After reconnecting, repeat device-info, joint-layout, and health preflight checks before resuming motion.
• Do not hide persistent port ownership, resource leaks, or hardware faults behind unbounded retries.

See errors and recovery and connection, discovery, and multiple devices.

Data, concurrency, and control ownership

• Pass joint arrays as sequences and validate their lengths against the active JointLayout. Refresh the layout after reconnecting or changing devices.
• Give one application component explicit ownership of motion control for each hand. Do not let discrete motion, Servo, teaching, or replay compete concurrently.
• Subscriptions pull periodic data but do not retain history. Use a bounded queue and an explicit drop policy when forwarding samples across tasks or to storage.
• Keep blocking work out of subscription processing so event-loop cleanup, timeouts, and control tasks remain responsive.

See subscriptions.py for subscription handling. Start new integrations with the quickstart.