基础用法（连接、控制与状态）
通过示例了解 ApexHand SDK 的基础使用流程。
本节展示从 建立连接、使能手指、发送运动命令 到 读取状态 的完整基础流程，并给出推荐的错误处理方式。
1. 创建实例与连接机械手
connect.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
ConnectionType,
ErrorCode,
)
bot = DexcelBot()
# 使用以太网连接
address = "192.168.0.102" # 替换为你的机械手 IP 或串口地址
result = bot.connect(address, ConnectionType.CONNECTION_TYPE_ETHERNET)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError(f"连接失败，错误码: {result}")
print("连接成功:", bot.is_connected())
常用连接模式：
- 以太网：
ConnectionType.CONNECTION_TYPE_ETHERNET - RS485：
ConnectionType.CONNECTION_TYPE_RS485
2. 使能 / 禁用手指
fingers_enable.py
from dexcelbot_apexhand_sdk import DexcelBot, FingerId, ErrorCode
bot = DexcelBot()
# ... 先调用 connect() ...
# 使能所有手指
bot.set_all_fingers_enabled()
# 仅使能食指与中指
bot.set_finger_enabled([
FingerId.FINGER_ID_INDEX,
FingerId.FINGER_ID_MIDDLE,
])
# 禁用无名指和小指
bot.set_finger_disabled([
FingerId.FINGER_ID_RING,
FingerId.FINGER_ID_PINKY,
])
# 一键禁用全部手指
bot.set_all_fingers_disabled()
若机械手进入故障状态，可调用：
bot.clean_faults()
3. 关节位置控制 move_joint
move_joint 为 阻塞式 位置控制，会等待机械手到达目标后返回。
推荐使用 SDK 提供的快捷构造函数 create_joint_control_param：
move_joint.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
JointId,
create_joint_control_param,
ErrorCode,
)
bot = DexcelBot()
# ... 先连接并使能手指 ...
# 目标：同时控制拇指 MCP 与食指 PIP 关节
cmds = [
create_joint_control_param(
joint_id=JointId.JOINT_ID_THUMB_MCP,
position=0.5, # rad
velocity=0.2, # rad/s
acceleration=0.0,
),
create_joint_control_param(
joint_id=JointId.JOINT_ID_INDEX_PIP,
position=0.8,
velocity=0.3,
acceleration=0.0,
),
]
result = bot.move_joint(cmds)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError(f"move_joint 失败: {result}")
4. 跟随控制 move_j_position_follow
move_j_position_follow 适用于连续目标点的跟随控制（非固定周期），SDK 内部会对相邻目标做插值规划：
follow.py
import time
from dexcelbot_apexhand_sdk import (
DexcelBot,
JointId,
create_move_j_position_follow_param,
)
bot = DexcelBot()
# ... 先连接并使能手指 ...
for i in range(50):
position = 0.2 + 0.3 * (i / 49) # 从 0.2 逐步到 0.5
params = [
create_move_j_position_follow_param(
joint_id=JointId.JOINT_ID_INDEX_MCP_0,
position=position,
)
]
bot.move_j_position_follow(params)
time.sleep(0.02) # 以非固定周期发送目标
5. 读取关节 / 电机状态
states.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# ... 已连接 ...
joint_states = bot.get_joint_states()
print("Joint timestamp:", joint_states.timestamp)
for js in joint_states.joint_states:
print(js.joint_id, js.position, js.velocity, js.acceleration)
motor_states = bot.get_motor_states()
print("Motor timestamp:", motor_states.timestamp)
for ms in motor_states.motors:
print(ms.motor_id, ms.temperature, ms.current)
6. 基本清理与断开连接
建议在程序结束前始终调用 disconnect()：
cleanup.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
# ... 使用完毕 ...
bot.set_all_fingers_disabled()
bot.disconnect()
print("已断开与 ApexHand 的连接")
完成以上基础步骤后，你已经可以用 ApexHand 完成基本的关节控制。下一部分“进阶与 API 详解”将进一步介绍：安全限制参数、回调注册、触觉图像采集与伺服控制等高级能力。