枚举与结构体概览

在 ApexHand Python SDK 中，大量的参数通过 枚举类型 与 结构体 进行组织。理解这些类型，有助于编写更安全、可读性更高的控制代码。

所有这些类型都由底层 _dexcelbot_sdk 通过 pybind11 暴露，在 dexcelbot_apexhand_sdk.py 中自动导出为同名 Python 类型。

日志与连接

LogLevel

日志等级枚举（仅用于文档描述，当前 Python 包中日志等级固定为 INFO）：

• LOG_LEVEL_DEBUG：调试级日志
• LOG_LEVEL_INFO：一般信息
• LOG_LEVEL_WARN：警告
• LOG_LEVEL_ERROR：错误
• LOG_LEVEL_FATAL：严重错误

在当前实现中，set_log_path() 内部会固定使用 INFO 等级，无法通过参数更改日志等级。

ConnectionType

连接类型：

• CONNECTION_TYPE_RS485：通过 RS485 串口连接
• CONNECTION_TYPE_ETHERNET：通过以太网连接

在 DexcelBot.connect(address, connection_type) 中使用。

错误码

ErrorCode

SDK 中所有接口的返回值统一为 ErrorCode：

• ERROR_CODE_OK：操作成功
• ERROR_CODE_COMM_ERROR：通信错误
• ERROR_CODE_TIMEOUT：超时错误
• ERROR_CODE_OUT_OF_RANGE：输入参数超出允许范围
• ERROR_CODE_OTHER_ERROR：其他错误

建议在调用需要可靠性的接口时，总是检查返回值：

result = bot.move_joint(cmds)
if result != ErrorCode.ERROR_CODE_OK:
    # 根据需要进行错误处理或重试
    print("move_joint 失败:", result)

机械结构相关枚举

FingerId

五指编号：

• FINGER_ID_THUMB：拇指
• FINGER_ID_INDEX：食指
• FINGER_ID_MIDDLE：中指
• FINGER_ID_RING：无名指
• FINGER_ID_PINKY：小指

用于：

• set_finger_enabled(fingers: List[FingerId])
• set_finger_disabled(fingers: List[FingerId])
• MaxFingerTorque.finger_id

MotorId

电机编号，共 16 个：

拇指：

• MOTOR_ID_THUMB_CMC_0
• MOTOR_ID_THUMB_CMC_1
• MOTOR_ID_THUMB_CMC_2
• MOTOR_ID_THUMB_MCP

食指：

• MOTOR_ID_INDEX_MCP_0
• MOTOR_ID_INDEX_MCP_1
• MOTOR_ID_INDEX_PIP

中指：

• MOTOR_ID_MIDDLE_MCP_0
• MOTOR_ID_MIDDLE_MCP_1
• MOTOR_ID_MIDDLE_PIP

无名指：

• MOTOR_ID_RING_MCP_0
• MOTOR_ID_RING_MCP_1
• MOTOR_ID_RING_PIP

小指：

• MOTOR_ID_PINKY_MCP_0
• MOTOR_ID_PINKY_MCP_1
• MOTOR_ID_PINKY_PIP

用于电机状态读取 MotorState.motor_id。

JointId

关节编号，共 21 个。以手指和关节位置命名，例如：

• 拇指：JOINT_ID_THUMB_CMC_0, JOINT_ID_THUMB_CMC_1, JOINT_ID_THUMB_CMC_2, JOINT_ID_THUMB_MCP, JOINT_ID_THUMB_IP
• 食指：JOINT_ID_INDEX_MCP_0, JOINT_ID_INDEX_MCP_1, JOINT_ID_INDEX_PIP, JOINT_ID_INDEX_DIP
• 中指：JOINT_ID_MIDDLE_MCP_0, JOINT_ID_MIDDLE_MCP_1, JOINT_ID_MIDDLE_PIP, JOINT_ID_MIDDLE_DIP
• 无名指：JOINT_ID_RING_MCP_0, JOINT_ID_RING_MCP_1, JOINT_ID_RING_PIP, JOINT_ID_RING_DIP
• 小指：JOINT_ID_PINKY_MCP_0, JOINT_ID_PINKY_MCP_1, JOINT_ID_PINKY_PIP, JOINT_ID_PINKY_DIP

用于：

• JointState.joint_id
• JointControlParam.joint_id
• MoveJPositionFollowParam.id
• MaxJointSpeed.joint_id
• MaxJointAccel.joint_id

版本与参数结构体

VersionInfo

版本信息：

• touch_sensor_version：触觉传感器固件版本
• hand_firmware_version：机械手固件版本
• sdk_version：SDK 库版本

由 get_version_info() 返回：

info = bot.get_version_info()
print(info.touch_sensor_version, info.hand_firmware_version, info.sdk_version)

ParamInfo

参数信息：

• max_speed: List[float]：各关节最大速度（rad/s）
• max_accel: List[float]：各关节最大加速度（rad/s²）
• max_current: List[float]：各手指最大电流 / 扭矩（百分比）

由 get_parameters() 返回。

关节控制与状态

JointState

单个关节状态：

• joint_id: JointId：关节 ID
• position: float：当前位置（rad）
• velocity: float：当前速度（rad/s）
• acceleration: float：当前加速度（rad/s²）

JointStates

关节状态集合：

• timestamp：时间戳
• joint_states: List[JointState]：关节状态列表

由 get_joint_states() 返回，或在关节状态回调中使用：

def on_joint_states(states):
    print("时间戳:", states.timestamp)
    for js in states.joint_states:
        print(js.joint_id, js.position)

bot.register_joint_states_callback(on_joint_states, freq_hz=100)

JointControlParam

关节控制参数：

• joint_id: JointId
• position: float：目标位置（rad）
• velocity: float：目标速度（rad/s）
• acceleration: float：目标加速度（rad/s²）

通常不直接手动赋值，而是使用辅助函数：

from dexcelbot_apexhand_sdk import (
    JointId,
    create_joint_control_param,
)

cmd = create_joint_control_param(
    joint_id=JointId.JOINT_ID_THUMB_MCP,
    position=0.5,
    velocity=0.2,
    acceleration=0.0,
)

MoveJPositionFollowParam

跟随控制参数：

• id: JointId：关节 ID
• position: float：目标位置（rad）

与 move_j_position_follow() 搭配，用于轨迹跟随。

电机状态与安全限制

MotorState 与 MotorStates

电机状态：

• MotorState：
  • motor_id: MotorId
  • temperature: float：温度
  • current: float：电流
• MotorStates：
  • timestamp
  • motors: List[MotorState]

由 get_motor_states() 或电机状态回调获得。

MaxJointSpeed

• joint_id: JointId
• speed: float：最大速度限制（rad/s）

设置方式：

from dexcelbot_apexhand_sdk import MaxJointSpeed, JointId

limits = []
for jid in JointId:
    item = MaxJointSpeed()
    item.joint_id = jid
    item.speed = 1.0  # 示例：统一设置为 1 rad/s
    limits.append(item)

bot.set_max_joint_speed(limits)

MaxJointAccel

• joint_id: JointId
• accel: float：最大加速度限制（rad/s²）

使用方式与 MaxJointSpeed 类似，对应函数为 set_max_joint_accel()。

MaxFingerTorque

• finger_id: FingerId
• torque: float：最大扭矩限制，0–100%

from dexcelbot_apexhand_sdk import MaxFingerTorque, FingerId

torques = []
for fid in FingerId:
    t = MaxFingerTorque()
    t.finger_id = fid
    t.torque = 80.0  # 限制在 80%
    torques.append(t)

bot.set_max_finger_torque(torques)

理解以上这些枚举与结构体，将帮助你在后续章节中更方便地阅读运动控制、传感器和回调相关的示例代码。接下来建议阅读「运动控制 API 详解」，了解 move_joint、move_j_position_follow 与伺服控制回调的具体用法。