Python API usage guidelines

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

Logging initialization

sdk.init_logging(level=sdk.LogLevel.Info, enable_file_logging=True) sets the SDK log level. When file output is enabled, the SDK installs its own Python logging.FileHandler and writes to logs/revo3_<timestamp>.log. Repeated calls replace that SDK handler without removing handlers configured by the application. Pass enable_file_logging=False when only integration with the existing Python logging configuration is required.

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. await its result to obtain the final status, and 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. Follow the bounded-queue and drop-policy guidance to isolate data classes, cap capacity, and expose drop metrics.
• 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.