Psi-Air-Glove-SDK-docs

Appearance

2. SDK安装和配置方法 ​

📋 目录 ​

  1. 硬件安装方法说明
  2. SDK安装和配置方法
  3. 例程编译和调用方法
  4. SDK接口调用说明
  5. SDK打印内容说明
  6. 连接状态查询与故障排查

完整手册

本文档对应 ψ-SynGlove Air Python SDK，源码位于：

psi-air-glove-SDK/psi-air-glove-SDK/python_sdk/

安装后通过 import psi_glove_sdk 使用，当前版本 0.1.5（以 psi_glove_sdk/VERSION 为准）。

2.1 系统要求 ​

项目要求
Python3.7+（离线 wheel 推荐 3.10）
操作系统Linux / Windows / macOS
基础依赖pyserial >= 3.5
可选依赖numpy（平滑加速）、mujoco / ruamel.yaml（指尖 FK 与可视化）

2.2 从源码安装 ​

bash
# 进入 Python SDK 目录
cd psi-air-glove-SDK/psi-air-glove-SDK/python_sdk

# 可编辑安装（自动安装 requirements.txt 中的依赖）
pip install -e .

# 验证
python -c "import psi_glove_sdk; print('OK', psi_glove_sdk.__version__)"

开发态资源路径（不在 psi_glove_sdk/resources/ 源码副本中）：

  • 默认配置：python_sdk/configs/
  • URDF 模型：仓库内 SynGlove_Air_URDF/（与 python_sdk 同级）

2.3 离线Wheel包安装 ​

适用于目标机无法访问 PyPI、需一次性打包配置与 URDF 的场景。

bash
cd psi-air-glove-SDK/psi-air-glove-SDK/python_sdk

# 默认按本机架构生成 manylinux 标签（x86_64 / aarch64）
python scripts/package_offline_wheel.py

# 指定 Python 标签与平台（示例）
python scripts/package_offline_wheel.py --python-tag cp310 --plat-name manylinux_2_17_x86_64

# 安装
pip install ./build/dist/psi_air_glove-*.whl

说明：

  • Wheel 包名：psi-air-glove（import 名仍为 psi_glove_sdk）。
  • 构建时会把 configs/ 与 SynGlove_Air_URDF/ 打入 wheel 内的 psi_glove_sdk/resources/。
  • 平台标签须与目标 Linux 匹配，否则 pip install 会拒绝安装。

2.3.1 使用已有离线包安装 ​

若已拿到 psi_air_glove-<version>-cp<py>-none-linux_<arch>.whl（例如 psi_air_glove-0.1.5-cp310-none-linux_x86_64.whl），无需在目标机上重新执行 package_offline_wheel.py，按下列步骤安装即可。

1. 确认环境匹配

检查项说明
Python 版本文件名中的 cp310 表示需 Python 3.10；cp311 对应 3.11，以此类推
操作系统当前 wheel 为 Linux x86_64 / aarch64 manylinux 标签，不支持 Windows / macOS 直接安装
架构linux_x86_64 与 aarch64 不可混用，须与目标机 uname -m 一致

2. 安装

bash
# 进入 wheel 所在目录（路径按实际修改）
cd /path/to/dist

# 建议在虚拟环境中安装（可选）
python3 -m venv .venv
source .venv/bin/activate

# 安装离线包（将文件名换成你手里的 wheel）
python3 -m pip install ./psi_air_glove-0.1.5-cp310-none-linux_x86_64.whl

# 若曾装过旧版，可强制覆盖
# python3 -m pip install --force-reinstall ./psi_air_glove-0.1.5-cp310-none-linux_x86_64.whl

3. 验证安装

bash
python3 -c "import psi_glove_sdk; print('OK', psi_glove_sdk.__version__)"

python3 -c "
from psi_glove_sdk.config_loader import get_resources_root, get_synglove_urdf_root
print('resources:', get_resources_root())
print('urdf_root:', get_synglove_urdf_root())
"

get_resources_root() 非 None 且 urdf_root 下存在 SynGlove_Air_URDF/，说明配置与 URDF 已随 wheel 安装完整。

4. 指尖位姿 / MuJoCo 可视化（可选）

离线 wheel 仅包含 pyserial 与包内 resources；运行 test_fingertip_visualizer.py 或 FingertipPoseCalculator 还需额外安装：

bash
pip install mujoco numpy ruamel.yaml

安装完成后即可运行 examples/ 下示例（见 §3 例程）。

2.4 可配置参数 ​

SerialInterface ​

参数类型默认说明
portstr必填串口路径，如/dev/ttyACM0、COM3
baudrateint115200波特率，常用115200、500000、921600
timeoutfloat0.006读超时（秒）
auto_connectboolFalse构造时是否自动连接
mockboolFalse模拟模式（无硬件测试）

LRA 连续下发时，写超时默认放宽为 max(1s, 读超时×10)，减轻 Write timeout。

PSIGloveController ​

参数类型默认说明
communication_interfaceCommunicationInterface必填如SerialInterface 实例
smoothing_window_sizeint10移动平均窗口；越大越平滑、延迟越高
adc_calibrationADCCalibrationParams内置默认可选 ADC 三次多项式校准

2.5 典型配置示例 ​

python
from psi_glove_sdk import PSIGloveController, SerialInterface

serial = SerialInterface(
    port="/dev/ttyACM0",
    baudrate=115200,
    timeout=0.006,
)
controller = PSIGloveController(serial, smoothing_window_size=10)

if not controller.connect():
    raise RuntimeError("连接失败")