Psi-Air-Glove-SDK-docs

Appearance

PSI 手套 C++ SDK 使用手册 ​

ψ-SynGlove Air C++ SDK 完整文档。

📋 目录 ​

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

1. 硬件安装方法说明 ​

本文适用于 ψ-SynGlove Air（Air Hand V2）：22 路关节 ADC 采集，五指可选配 LRA 线性马达 触觉反馈。通信协议与 SDK Modbus 章节一致（读关节、写 0xB0 LRA）。

SDK 源码仓库路径：psi-air-glove-SDK/psi-air-glove-SDK/（含 python_sdk、cpp_sdk、ros2_sdk）。

1.1 硬件清单 ​

  • PSI 数据手套（左手/右手）
  • USB 数据线

1.2 硬件连接步骤 ​

┌────────────────┐                        ┌─────────────┐
│  PSI 数据手套  │ ──────── USB ───────→ │   计算机    │
│  (左手/右手)   │   (虚拟串口通信)       │  (运行SDK)  │
└────────────────┘                        └─────────────┘

连接步骤：

  1. 连接手套：使用 USB 数据线将数据手套直接连接到计算机 USB 接口
  2. 手套供电：手套通过 USB 接口供电
  3. 虚拟串口：计算机会自动创建虚拟串口设备用于通信
  4. 确认设备：
    • Linux: 运行 ls /dev/ttyUSB* /dev/ttyACM* 查看设备（通常为 /dev/ttyACM0）
    • Windows: 打开设备管理器查看 COM 口（如 COM31）
    • macOS: 运行 ls /dev/tty.usbmodem* 或 ls /dev/cu.usbmodem*

注意事项：

  • 手套使用 USB 供电，无需额外电源适配器
  • 首次连接时，操作系统会自动安装 USB CDC 驱动

1.3 串口权限设置（Linux） ​

bash
sudo usermod -a -G dialout $USER
newgrp dialout
ls -l /dev/ttyACM0

2. SDK安装和配置方法 ​

源码路径：psi-air-glove-SDK/psi-air-glove-SDK/cpp_sdk/ 命名空间：psi_glove 主头文件：#include <psi_glove_sdk/psi_glove.hpp>

2.1 系统要求 ​

项目要求
编译器GCC 7+ / Clang 5+（Linux 串口实现）
CMake3.10+
C++ 标准C++17
第三方库无（仅标准库）
操作系统Linux（SerialInterface 基于 POSIX termios）

WARNING

当前 C++ 串口层标注为 Linux/Unix；Windows 原生串口需自行封装 CommunicationInterface 或选用 Python / ROS2 SDK。

2.2 编译与安装 ​

bash
cd psi-air-glove-SDK/psi-air-glove-SDK/cpp_sdk
mkdir -p build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig
组件路径（默认）
头文件/usr/local/include/psi_glove_sdk/
库文件/usr/local/lib/libpsi_glove_sdk.so
CMake 包/usr/local/lib/cmake/psi_glove_sdk/

CMake 常用选项：BUILD_EXAMPLES、BUILD_SHARED_LIBS、SDK_VERSIONED_SHARED_LIBRARY、CMAKE_INSTALL_PREFIX。

2.3 在工程中使用 ​

cmake
find_package(psi_glove_sdk REQUIRED)
target_link_libraries(your_app psi_glove::psi_glove_sdk)

3. 例程编译和调用方法 ​

3.1 例程列表 ​

例程名称路径功能说明
基础用法examples/basic_usage.cpp连接、循环读取 22 路关节 ADC
高级用法examples/advanced_usage.cpp归一化、统计、CSV 记录
OpenCV 可视化examples/psi_glove_cpp_visualizer/柱状图（独立编译，需 OpenCV）

默认 cmake 不编译可视化子目录；无 Python 指尖 FK、离线 wheel、LRA 专用示例程序（API 仍提供 PlayLra）。

3.2 例程运行方法 ​

3.2.1 基础用法 ​

bash
cd build
./basic_usage /dev/ttyACM0

3.2.2 高级用法 ​

bash
./advanced_usage /dev/ttyACM0

生成 glove_data.csv（22 列关节）。

3.2.3 OpenCV 可视化 ​

bash
cd examples/psi_glove_cpp_visualizer
./build.sh
./build/psi_glove_visualizer /dev/ttyACM0

3.3 关节布局（22 路） ​

拇指 6 + 食指/中指/无名指/小指各 4 → StatusMessage 成员数组。

4. SDK接口调用说明 ​

4.1 SerialInterface ​

cpp
auto serial = std::make_unique<psi_glove::SerialInterface>(
    "/dev/ttyACM0", 115200, std::chrono::milliseconds(6));

4.2 PSIGloveController ​

方法说明
Connect() / Disconnect() / IsConnected()连接管理
Loop()读一帧并缓存
ReadJointPositions()仅读取
GetLastStatus()上次成功数据
PlayLra(cmd, slave_id)LRA 触觉

4.3 读取示例 ​

cpp
psi_glove::PSIGloveController controller(std::move(serial), 10);
if (!controller.Connect()) return 1;
while (controller.IsConnected()) {
    if (auto s = controller.Loop()) {
        // s->thumb[0] ...
    }
}

4.4 PlayLra ​

cpp
psi_glove::LraPlayCommand cmd{};
cmd[0] = {5, 32};
controller.PlayLra(cmd, 0x01);

4.5 不包含的能力 ​

  • Python FingertipPoseCalculator / MuJoCo 直连示例
  • 内置 YAML 配置加载（仅有 Config 类型定义）
  • lra_play_example 同名例程（请自行调用 PlayLra）

5. SDK打印内容说明 ​

basic_usage 每 10 帧打印五指 ADC；advanced_usage 输出角度统计与 CSV；PlayLra 无默认日志，失败时返回 false。

6. 连接状态查询与故障排查 ​

  • IsConnected() + Loop() 判读数据链路
  • 串口权限、dialout、设备占用
  • LD_LIBRARY_PATH / ldconfig 处理动态库
  • WSL+NTFS：SDK_VERSIONED_SHARED_LIBRARY=OFF

分章节阅读：安装 · 例程 · API · 输出 · 排查