3. 例程编译和调用方法

📋 目录

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

完整手册

---

SDK 提供四个示例程序，位于 psi-air-glove-SDK/psi-air-glove-SDK/python_sdk/examples/ 目录。

3.1 例程列表

例程名称	文件	功能说明
基础用法	basic_usage.py	演示连接、读取 22 路关节数据、断开连接
高级用法	advanced_usage.py	归一化与角度换算、统计信息、CSV 数据记录
LRA触觉反馈	lra_play_example.py	线性马达波形与振幅控制（Modbus0xB0）
指尖可视化	test_fingertip_visualizer.py	MuJoCo 实时显示指尖位姿与坐标系

3.2 例程运行方法

运行前建议已在 python_sdk 目录执行 pip install -e .。

3.2.1 基础用法示例

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

# 运行基础示例（指定串口）
python3 basic_usage.py /dev/ttyACM0

# 自定义波特率
python3 basic_usage.py /dev/ttyACM0 500000

# Windows 系统
python basic_usage.py COM31

输出示例：

==================================================
PSI Glove SDK - 基础使用示例
==================================================
串口: /dev/ttyACM0
波特率: 115200
==================================================

[INFO] 正在连接到设备...
[INFO] 连接成功!

[INFO] 开始读取数据 (按Ctrl+C退出)...

--- 帧 #0 ---
拇指: 2048, 1856, 2304, 1792, 2176, 1920
食指: 1920, 2240, 1664, 2112
中指: 2304, 1856, 2048, 1792
无名指: 1920, 2176, 1664, 2048
小指: 2240, 1856, 2304, 1920

--- 帧 #10 ---
拇指: 2052, 1860, 2308, 1796, 2180, 1924
...

拇指为 6 路关节，其余四指各 4 路；数值为 12 位 ADC（0–4095）。按 Ctrl+C 退出后打印帧率统计。

3.2.2 高级用法示例

# 运行高级示例
python3 advanced_usage.py /dev/ttyACM0

# 自定义波特率
python3 advanced_usage.py /dev/ttyACM0 500000

# 启用 CSV 数据记录（第三个参数为 --log）
python3 advanced_usage.py /dev/ttyACM0 115200 --log

输出示例：

==================================================
PSI Glove SDK - 高级使用示例
==================================================
串口: /dev/ttyACM0
波特率: 115200
数据记录: 启用
==================================================

[INFO] 正在连接...
[INFO] 连接成功!

--- 帧 #0 ---
拇指关节角度:
  关节 0:   45.2° (归一化: 0.512, 原始: 2048)
  关节 1:   38.1° (归一化: 0.431, 原始: 1856)
  ...

==================================================
统计信息 (拇指指尖关节):
  样本数: 1200 | 最小: 1800 | 最大: 2300 | 平均: 2050.3
==================================================

启用 --log 时，会在当前目录生成 psi_glove_data_YYYYMMDD_HHMMSS.csv。

3.2.3 LRA 触觉示例

python3 lra_play_example.py COM3 115200
python3 lra_play_example.py /dev/ttyACM0 921600

可选参数：--slave（Modbus 从机地址）、--step-sec（每档保持时间）、--amp-max（振幅上限，默认 64）。

示例逻辑：拇指出厂波形，振幅从 1 递增到 amp_max；mode=0 关闭该指马达。

3.2.4 指尖可视化示例

依赖：mujoco、numpy、ruamel.yaml，以及 URDF（开发态在 SynGlove_Air_URDF/，离线 wheel 在 psi_glove_sdk/resources/）。

pip install mujoco numpy ruamel.yaml

python3 test_fingertip_visualizer.py -p /dev/ttyACM0 -b 115200 -H right

启动 MuJoCo 窗口，实时显示五指指尖坐标系；终端周期性打印 URDF 关节角与指尖位姿矩阵。

效果展示：

3.3 关节数据说明（22 路）

StatusMessage 包含 22 个关节 ADC 值（12 位，0–4095）：

手指	关节数	joints 索引	属性访问
拇指	6	0–5	status.thumb
食指	4	6–9	status.index
中指	4	10–13	status.middle
无名指	4	14–17	status.ring
小指	4	18–21	status.pinky

拇指 6 路顺序：tip, mid, back, back2, side, rotate。其余四指：tip, mid, back, side。

---