错误处理与事件回调
使用 ApexHand SDK 进行硬件错误检测与事件回调处理。
本节聚焦 错误检测与事件回调，包括：
- 硬件错误码检测：
get_hardware_error_code - 硬件错误事件回调：
register_hardware_error_event_callback - 配合日志配置的排查建议
硬件错误码 get_hardware_error_code
get_hardware_error_code() 用于查询当前设备硬件错误状态：
check_hw_error.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
# 省略 connect() ...
code = bot.get_hardware_error_code()
if code == ErrorCode.ERROR_CODE_OK:
print("当前无硬件错误")
elif code == ErrorCode.ERROR_CODE_OTHER_ERROR:
print("检测到硬件错误，详见错误事件回调或日志")
else:
print("get_hardware_error_code 调用失败，错误码:", code)
说明：
- 返回
ERROR_CODE_OK：表示当前未检测到硬件错误。 - 返回
ERROR_CODE_OTHER_ERROR：表示检测到某种硬件错误，具体信息可通过事件回调或日志中获取。
硬件错误事件回调
注册与取消注册
hw_error_callback.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
HardwareErrorCodes,
ErrorCode,
)
bot = DexcelBot()
# 省略 connect() ...
def on_hardware_error(err: HardwareErrorCodes):
# 这里的 err 为 SDK 定义的错误码集合结构体
print("设备错误码:", err.device_error)
print("各手指错误码:", err.finger_errors)
result = bot.register_hardware_error_event_callback(on_hardware_error)
if result != ErrorCode.ERROR_CODE_OK:
raise RuntimeError("注册硬件错误事件回调失败")
# ... 运行任务 ...
bot.unregister_hardware_error_event_callback()
在底层检测到硬件错误（例如电机过流、传感器异常等）时，SDK 会自动触发回调，将 HardwareErrorCodes 结构体传入。
HardwareErrorCodes的具体字段由底层 SDK 定义，你可以在 Python 交互环境中通过help(HardwareErrorCodes)或dir(HardwareErrorCodes())查看。
与状态/传感回调联动
一个常见实践是同时：
- 使用 电机状态回调 做温度与电流的软监控。
- 使用 硬件错误回调 捕获底层固件检测到的故障。
safe_monitor.py
from dexcelbot_apexhand_sdk import (
DexcelBot,
MotorStates,
HardwareErrorCodes,
ErrorCode,
)
bot = DexcelBot()
# 省略 connect() ...
def on_motor_states(states: MotorStates):
for m in states.motors:
if m.temperature > 70.0:
print("[软监控] 电机过热:", m.motor_id, m.temperature)
def on_hardware_error(err: HardwareErrorCodes):
print("[固件错误] 设备错误码:", err.device_error)
print("[固件错误] 手指错误码:", err.finger_errors)
bot.register_motor_states_callback(on_motor_states, freq_hz=20)
bot.register_hardware_error_event_callback(on_hardware_error)
# ... 运行任务 ...
bot.unregister_motor_states_callback()
bot.unregister_hardware_error_event_callback()
日志配置与排查建议
设置日志路径
log_path.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
result = bot.set_log_path("./logs")
if result != ErrorCode.ERROR_CODE_OK:
print("设置日志路径失败:", result)
else:
print("日志将输出到 ./logs 目录")
注意：
- Python SDK 中日志等级固定为 INFO，无法修改。
- 建议在排查硬件问题时，总是配置一个单独的日志目录，方便后续分析。
启用 / 关闭日志
enable_logging.py
from dexcelbot_apexhand_sdk import DexcelBot
bot = DexcelBot()
bot.enable_logging(True) # 打开日志
# ... 运行任务 ...
bot.enable_logging(False) # 若不再需要，可关闭
故障恢复流程建议
当检测到错误时，推荐遵循如下流程：
- 停止发送新的运动指令（如
move_joint/ 伺服控制回调）。 - 调用
get_hardware_error_code()确认错误状态。 - 根据错误类型决定是否：
- 调用
clean_faults()清除故障。 - 降低速度 / 扭矩限制后重试任务。
- 调用
- 若错误持续复现：
- 保留日志文件与相关配置。
- 将错误码与日志一同提供给 Dexcel 技术支持。
recover_example.py
from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode
bot = DexcelBot()
code = bot.get_hardware_error_code()
if code == ErrorCode.ERROR_CODE_OTHER_ERROR:
print("检测到硬件错误，尝试清除故障...")
clr = bot.clean_faults()
if clr == ErrorCode.ERROR_CODE_OK:
print("故障清除成功，可以根据需要重新配置限幅后再尝试任务。")
else:
print("清除故障失败，建议停止使用并导出日志进行排查。")
通过本节你可以构建较为完备的错误检测与恢复机制，结合前几节的控制与状态接口，可以在实际项目中实现稳定、安全的 ApexHand 控制程序。