兼容性与要求
- CPU:x86_64 (AMD64) / arm64 (aarch64)
- Python:3.8–3.14
- 操作系统:Ubuntu 22.04 LTS / Ubuntu 24.04 LTS
安装指南
本节介绍 wujihandpy 的安装方法和常见问题解决。安装
wujihandpy 支持pip 一键安装:
说明:安装过程中常见报错及处理方式,参见文末的 故障排除 - 安装问题。
快速上手
本节给出最小可运行示例,快速测试灵巧手与 wujihandpy 库。说明:快速上手阶段常见的连接与权限问题,参见文末的 故障排除 - 快速上手问题。
核心概念
本节介绍 wujihandpy 的设备模型和数据模型,帮助理解库的整体架构和使用方式。设备模型
wujihandpy 拥有三层设备模型,分别为 Hand, Finger, Joint。其层级关系为:Hand.finger(i) -> Finger,Finger.joint(j) -> Joint。其中,
- Hand 表示完整的灵巧手设备,可通过 wujihandpy.Hand() 创建。
- Finger 是对 Hand 的轻量引用,不持有独立状态,可多次构造和销毁。Finger 对象可由
hand.finger(i)(0 ≤ i < 5) 构造,i 与实际手指的具体对应关系如下:- 0:拇指
- 1:食指
- 2:中指
- 3:无名指
- 4:小指
- Joint 也是对 Hand 的轻量引用,不持有独立状态,可多次构造和销毁。Joint 对象可由
finger.joint(j)(0 ≤ j < 4) 构造,j 与实际关节的对应关系大致如下:- 0:近端关节
- …
- 3:远端关节
数据模型
数据是可读/可写的对象,与设备类似,数据也存在层级关系:说明:此处仅列举部分数据字段作为示例,完整 API Reference 参见 字段列表。
-
Hand 层:整手唯一的数据位于该层,例如:
handedness: 手性(左/右手)firmware_version: 固件版本system_time: 上电时间
- Finger 层:每手指持有一个独立副本的数据位于该层,目前该层无数据。
-
Joint 层:每关节持有一个独立副本的数据位于该层,例如:
joint_enabled: 关节是否使能joint_actual_position: 关节当前位置joint_target_position: 关节目标位置joint_temperature: 关节当前温度joint_error_code: 关节错误码
说明:属于 Joint 层的所有数据,在命名上均以
joint 开头。故障排除
安装问题
升级 pip
若出现Could not find a version that satisfies the requirement,例如在较旧的 Python 或 pip 环境中:
使用虚拟环境
若出现This environment is externally managed,例如在启用了系统托管 Python 的 Ubuntu 环境中:
快速上手问题
灵巧手未连接
lsusb 确认设备是否正确识别,若设备已正确连接,则 lsusb 产生类似如下输出:
权限不足
获取日志
SDK 运行日志默认位于~/.wuji/log/,文件名 {timestamp}_{pid}.log,单文件 10 MB 滚动,最多保留 5 个历史文件。遇到问题时将最近的日志发送给售后支持即可协助定位。
自定义路径与级别
通过环境变量配置(推荐,零代码) SDK 在 logger 初始化时一次性读取(常见Hand 流程下即首个 Hand 构造时),之后不再生效:
取值匹配大小写不敏感。
WUJI_LOG_LEVEL 还接受常见别名 error(=err)、warning(=warn)、information(=info)、crit(=critical)。两个布尔变量也接受 1/0、on/off、yes/no。
通过代码配置
在创建 Hand 之前调用 wujihandpy.logging 子模块的接口:
采集详细日志
默认info 级别只记录关键事件。当需要分析指令收发细节(如指令下发后实际状态未跟上),将级别调至 debug 获取 SDO/PDO 通信记录,或调至 trace 额外获取原始收发字节: