ApexHand Python SDK 简介

dexcelbot_apexhand_sdk 提供了用于控制 DexcelBot ApexHand 机械手 的官方 Python 接口，封装了底层 C++/pybind11 SDK，并对常用的控制与回调做了高层封装，便于在科研、教学与工业应用中快速集成。

SDK 能力概览

• 连接管理：通过以太网或 RS485 建立与 ApexHand 的稳定连接。
• 状态获取：实时获取关节状态 JointStates、电机状态 MotorStates 以及触觉传感图像 HandSensorImage。
• 运动控制：
  • 阻塞式关节位置控制 move_joint
  • 非阻塞式关节跟随控制 move_j_position_follow
  • 高级伺服控制回调 register_servo_joint_control_callback
• 安全与限制：
  • 关节最大速度 MaxJointSpeed
  • 关节最大加速度 MaxJointAccel
  • 手指最大扭矩 MaxFingerTorque
• 事件与回调：
  • 硬件错误事件回调 register_hardware_error_event_callback
  • 关节状态、电机状态、传感图像回调

所有底层枚举与结构体（例如 LogLevel、ConnectionType、ErrorCode、JointId 等）都通过 pybind11 从原生 _dexcelbot_sdk 动态导出，可直接在 Python 中查看与使用。

快速了解使用流程

典型的 ApexHand 控制流程如下：

1. 创建 SDK 实例
2. 建立连接（以太网 / RS485）
3. 配置日志与安全参数（可选）
4. 使能手指
5. 发送关节或跟随控制命令
6. （可选）注册状态 / 传感器 / 错误回调
7. 断开连接并释放资源

from dexcelbot_apexhand_sdk import (
    DexcelBot,
    ConnectionType,
    ErrorCode,
    JointId,
    create_joint_control_param,
)

bot = DexcelBot()

# 1. 连接机械手
result = bot.connect("192.168.0.102", ConnectionType.CONNECTION_TYPE_ETHERNET)
if result != ErrorCode.ERROR_CODE_OK:
    raise RuntimeError(f"Connect failed: {result}")

# 2. 使能所有手指
bot.set_all_fingers_enabled()

# 3. 控制一个关节
cmd = create_joint_control_param(
    joint_id=JointId.JOINT_ID_THUMB_MCP,
    position=0.5,
    velocity=0.1,
    acceleration=0.0,
)
bot.move_joint([cmd])

# 4. 断开连接
bot.disconnect()

在接下来的章节中，你将看到：

• 安装与环境准备：如何配置 Python 环境与原生库路径。
• 基础用法：连接、启停、关节控制与常用读取接口。
• 进阶主题：回调机制、触觉图像、伺服联合控制的推荐用法。