Skip to main content

兼容性与要求

  • CPU:x86_64 (AMD64) / arm64 (aarch64)
  • Python:3.8–3.14
  • 操作系统:Ubuntu 22.04 LTS / Ubuntu 24.04 LTS

安装指南

本节介绍 wujihandpy 的安装方法和常见问题解决。

安装

wujihandpy 支持 pip 一键安装:
说明:除非对 wujihandpy 进行二次开发,否则勿将其 Git 仓库克隆至本地,可能导致 IDE 误判 .pyi 文件的位置,造成代码补全异常。
Linux 需配置 udev 以允许非 root 访问 USB:
说明:安装过程中常见报错及处理方式,参见文末的 故障排除 - 安装问题。

快速上手

本节给出最小可运行示例,快速测试灵巧手与 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 环境中:
考虑尝试升级 pip,并使用升级后的 pip 安装:
若问题未解决,请确认系统版本和 Python 版本是否符合 兼容性与要求。

使用虚拟环境

若出现 This environment is externally managed,例如在启用了系统托管 Python 的 Ubuntu 环境中:
这表示 pip 被系统包管理器接管,需要使用虚拟环境 (venv) 进行安装。

快速上手问题

灵巧手未连接

若出现以上报错,请确认灵巧手已通过 USB 连接至电脑。 可以通过 lsusb 确认设备是否正确识别,若设备已正确连接,则 lsusb 产生类似如下输出:
当使用 USB-C to USB-C 线束连接灵巧手时,部分电脑可能无法正确识别设备,请更换为 USB-A to USB-C 线束重试。

权限不足

若出现以上报错(ERROR_ACCESS),表示当前用户对 USB 设备没有读写权限。 请检查 安装 中的 Linux udev 配置部分,完成权限配置后重试。
注意:若在 Docker 镜像中开发 (DevContainer),udev 配置命令仍需在宿主机中执行。

获取日志

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 子模块的接口:
完整 API 参考与调用时机约束见 API 参考 - logging 模块。

采集详细日志

默认 info 级别只记录关键事件。当需要分析指令收发细节(如指令下发后实际状态未跟上),将级别调至 debug 获取 SDO/PDO 通信记录,或调至 trace 额外获取原始收发字节:
将复现问题时段的日志文件提供给售后支持,可显著加快定位速度。