Psi-glove-sdk-docs

Appearance

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

6.1 如何查询连接状态 ​

6.1.1 使用 is_connected() 方法 ​

python
from psi_glove_sdk import PSIGloveController, SerialInterface

serial = SerialInterface("/dev/ttyACM0", 115200)
controller = PSIGloveController(serial)

# 连接前检查
print(f"连接状态: {controller.is_connected()}")  # 输出: False

# 尝试连接
if controller.connect():
    print("连接成功")
    print(f"连接状态: {controller.is_connected()}")  # 输出: True
else:
    print("连接失败")

# 运行时检查
while controller.is_connected():
    status = controller.loop()
    # 处理数据...

6.1.2 检查数据是否有效 ​

python
# 方法 1: 检查 loop() 返回值
status = controller.loop()
if status is None:
    print("错误: 数据读取失败")
else:
    print("数据读取成功")

# 方法 2: 使用缓存数据
last_status = controller.get_last_status()
if last_status is None:
    print("警告: 从未成功读取过数据")
else:
    print(f"最后一次成功读取: {last_status.thumb}")

6.2 如何确认程序正常运行 ​

6.2.1 连接成功的标志 ​

✅ 正常运行的特征：

  1. 日志输出:

    [INFO] 正在连接到设备...
[INFO] 连接成功!
[INFO] 开始读取数据 (按Ctrl+C退出)...

  2. 数据持续更新:

    • 帧计数持续增加
    • 关节数值在合理范围内变化（0-4095）
    • 无频繁的 "读取失败" 警告

  3. 帧率稳定:

    平均帧率: 99.93 Hz  # 接近目标频率（100 Hz）

6.2.2 性能检查脚本 ​

python
#!/usr/bin/env python3
from psi_glove_sdk import PSIGloveController, SerialInterface
import time

serial = SerialInterface("/dev/ttyACM0", 115200)
controller = PSIGloveController(serial)

if not controller.connect():
    print("❌ 连接失败")
    exit(1)

print("✅ 连接成功，开始性能测试...")

# 性能测试（10秒）
success_count = 0
failure_count = 0
start_time = time.time()

while time.time() - start_time < 10:
    status = controller.loop()
    if status:
        success_count += 1
    else:
        failure_count += 1
    time.sleep(0.01)

duration = time.time() - start_time
success_rate = success_count / (success_count + failure_count) * 100

print(f"\n性能报告:")
print(f"  成功读取: {success_count} 帧")
print(f"  失败次数: {failure_count} 次")
print(f"  成功率: {success_rate:.2f}%")
print(f"  实际帧率: {success_count / duration:.2f} Hz")

if success_rate > 95:
    print("✅ 性能良好")
elif success_rate > 80:
    print("⚠️ 性能一般，可能存在干扰")
else:
    print("❌ 性能不佳，需要检查连接")

controller.disconnect()

6.3 常见故障排查 ​

故障 1: 连接失败 ​

症状：

[ERROR] 错误: 无法连接到设备

排查步骤：

  1. 检查设备是否通电

    bash
    # 查看 LED 指示灯是否亮起

  2. 检查串口是否存在

    bash
    # Linux
ls -l /dev/ttyUSB* /dev/ttyACM*

# Windows
# 打开设备管理器 > 端口 (COM和LPT)

# macOS
ls /dev/tty.usbserial-* /dev/cu.usbserial-*

  3. 检查串口权限（Linux）

    bash
    # 查看当前用户组
groups

# 如果没有 dialout 组，添加用户
sudo usermod -a -G dialout $USER

# 注销后重新登录，或立即生效
newgrp dialout

  4. 检查串口是否被占用

    bash
    # Linux
lsof /dev/ttyACM0

# 如果被占用，杀死进程
sudo killall python3

  5. 尝试不同的串口路径

    bash
    # 列出所有可能的串口
ls /dev/tty*

# 尝试不同的端口
python3 basic_usage.py /dev/ttyUSB0
python3 basic_usage.py /dev/ttyACM1

故障 2: 导入模块失败 ​

症状：

ModuleNotFoundError: No module named 'psi_glove_sdk'

解决方法：

bash
# 方法 1: 安装 SDK
cd psi-glove-SDK/python_sdk
pip3 install -e .

# 验证安装
python3 -c "import psi_glove_sdk; print('安装成功')"

# 方法 2: 检查 pip 安装路径
pip3 show psi-glove-sdk

# 方法 3: 手动添加到 PYTHONPATH
export PYTHONPATH=/path/to/psi-glove-SDK/python_sdk:$PYTHONPATH

故障 3: 数据读取频繁失败 ​

症状：

[WARNING] 读取失败，使用缓存数据
[WARNING] 读取失败，使用缓存数据
...

排查步骤：

  1. 检查数据线质量

    • 更换 USB 数据线
    • 使用较短的数据线（< 1.5m）
    • 避免使用 USB 集线器

  2. 调整超时时间

    python
    serial = SerialInterface(
    port="/dev/ttyACM0",
    baudrate=115200,
    timeout=0.010  # 增加到 10ms
)

  3. 降低波特率

    python
    serial = SerialInterface(
    port="/dev/ttyACM0",
    baudrate=115200  # 从 500000 降低到 115200
)

  4. 检查电源供应

    • 确保电源适配器正常工作
    • 检查电源线连接

  5. 减少电磁干扰

    • 远离大功率电器
    • 使用带屏蔽的数据线

故障 4: 帧率过低 ​

症状：

平均帧率: 45.23 Hz  # 远低于 100 Hz

解决方法：

  1. 减少打印输出

    python
    # 不要每帧都打印
if frame_count % 100 == 0:  # 每 100 帧打印一次
    print(...)

  2. 优化平滑窗口

    python
    controller = PSIGloveController(
    communication_interface=serial,
    smoothing_window_size=5  # 从 10 减少到 5
)

  3. 减少 sleep 时间

    python
    time.sleep(0.005)  # 从 0.01 减少到 0.005

  4. 使用更快的波特率

    python
    serial = SerialInterface(
    port="/dev/ttyACM0",
    baudrate=500000  # 从 115200 提升到 500000
)

故障 5: 数据值异常 ​

症状：

拇指: 4095, 4095, 4095, 4095, 4095  # 全是最大值
或
拇指: 0, 0, 0, 0, 0  # 全是最小值

排查步骤：

  1. 检查传感器连接

    • 确保传感器电缆连接牢固
    • 检查是否有断线或损坏

  2. 校准手套

    python
    # 记录手指伸直时的数值
print("请伸直手指...")
status = controller.loop()
min_values = status.to_list()

# 记录手指弯曲时的数值
print("请弯曲手指...")
status = controller.loop()
max_values = status.to_list()

print(f"范围: {min_values} ~ {max_values}")

  3. 重启设备

    • 断开电源
    • 等待 10 秒
    • 重新上电

6.4 调试工具和技巧 ​

6.4.1 启用调试日志 ​

python
import logging

# 启用详细调试日志
logging.basicConfig(level=logging.DEBUG)

# 或者只针对 SDK
logging.getLogger('psi_glove_sdk').setLevel(logging.DEBUG)

6.4.2 串口监控工具 ​

bash
# Linux: 使用 minicom 监控串口
sudo apt-get install minicom
sudo minicom -D /dev/ttyACM0 -b 115200

# 或使用 screen
screen /dev/ttyACM0 115200

# Windows: 使用 PuTTY 或 RealTerm

6.4.3 性能分析 ​

python
import time
from psi_glove_sdk import PSIGloveController, SerialInterface

serial = SerialInterface("/dev/ttyACM0", 115200)
controller = PSIGloveController(serial)
controller.connect()

# 测量读取延迟
latencies = []
for _ in range(100):
    start = time.time()
    status = controller.loop()
    end = time.time()
    if status:
        latencies.append((end - start) * 1000)  # 转换为毫秒

print(f"平均延迟: {sum(latencies) / len(latencies):.2f} ms")
print(f"最小延迟: {min(latencies):.2f} ms")
print(f"最大延迟: {max(latencies):.2f} ms")

controller.disconnect()

6.5 获取技术支持 ​

如果以上方法无法解决问题，请：

  1. 收集诊断信息

    bash
    # 系统信息
uname -a
python3 --version

# SDK 版本
python3 -c "import psi_glove_sdk; print(psi_glove_sdk.__version__)"

# 串口信息
ls -l /dev/ttyACM*
dmesg | grep tty

  2. 运行诊断脚本

    bash
    cd psi-glove-SDK/python_sdk/examples
python3 advanced_usage.py /dev/ttyACM0 --diagnostic

  3. 查看详细文档

    • Python SDK README: python_sdk/README_CN.md
    • 示例说明: python_sdk/examples/README_CN.md

  4. 联系技术支持

    • 提供诊断信息和错误日志
    • 描述复现步骤

📊 附录：快速参考 ​

常用命令 ​

bash
# 安装 SDK
pip3 install -e .

# 运行基础示例
python3 examples/basic_usage.py /dev/ttyACM0

# 运行可视化
python3 examples/psi_glove_direct_visualizer.py --left /dev/ttyACM0

# 检查串口
ls /dev/ttyACM*

# 添加串口权限
sudo usermod -a -G dialout $USER

性能参数参考 ​

场景波特率超时平滑窗口预期帧率
标准配置1152006ms1090-100 Hz
高速配置5000003ms5100-150 Hz
稳定配置11520010ms1550-80 Hz

数据范围 ​

  • ADC 值: 0-4095 (12-bit)
  • 关节数量: 21 个
  • 拇指: 5 个关节
  • 其他手指: 各 4 个关节

版本: 1.0.0
更新日期: 2025-01-15
版权所有: © 2025 PSI 机器人团队