Psi-glove-sdk-docs

Appearance

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

6.1 如何查询连接状态 ​

6.1.1 使用 IsConnected() 方法 ​

cpp
#include <psi_glove_sdk/psi_glove.hpp>
#include <iostream>

int main() {
    auto serial = std::make_unique<psi_glove::SerialInterface>("/dev/ttyACM0", 115200);
    psi_glove::PSIGloveController controller(std::move(serial), 10);
    
    // 连接前检查
    std::cout << "连接状态: " << (controller.IsConnected() ? "已连接" : "未连接") << std::endl;
    // 输出: 连接状态: 未连接
    
    // 尝试连接
    if (controller.Connect()) {
        std::cout << "连接成功" << std::endl;
        std::cout << "连接状态: " << (controller.IsConnected() ? "已连接" : "未连接") << std::endl;
        // 输出: 连接状态: 已连接
    } else {
        std::cout << "连接失败" << std::endl;
    }
    
    // 运行时检查
    while (controller.IsConnected()) {
        auto status = controller.Loop();
        // 处理数据...
    }
    
    return 0;
}

6.1.2 检查数据是否有效 ​

cpp
// 方法 1: 检查 Loop() 返回值
auto status = controller.Loop();
if (!status.has_value()) {
    std::cerr << "错误: 数据读取失败" << std::endl;
} else {
    std::cout << "数据读取成功" << std::endl;
}

// 方法 2: 使用缓存数据
auto last_status = controller.GetLastStatus();
if (!last_status.has_value()) {
    std::cerr << "警告: 从未成功读取过数据" << std::endl;
} else {
    std::cout << "最后一次成功读取: " << last_status->thumb[0] << std::endl;
}

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

6.2.1 连接成功的标志 ​

✅ 正常运行的特征：

  1. 输出显示:

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

  2. 数据持续更新:

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

  3. 帧率稳定:

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

6.2.2 性能检查程序 ​

cpp
#include <psi_glove_sdk/psi_glove.hpp>
#include <iostream>
#include <thread>
#include <chrono>

int main() {
    auto serial = std::make_unique<psi_glove::SerialInterface>("/dev/ttyACM0", 115200);
    psi_glove::PSIGloveController controller(std::move(serial), 10);
    
    if (!controller.Connect()) {
        std::cerr << "❌ 连接失败" << std::endl;
        return 1;
    }
    
    std::cout << "✅ 连接成功，开始性能测试..." << std::endl;
    
    // 性能测试（10秒）
    int success_count = 0;
    int failure_count = 0;
    auto start_time = std::chrono::steady_clock::now();
    
    while (std::chrono::steady_clock::now() - start_time < std::chrono::seconds(10)) {
        auto status = controller.Loop();
        if (status.has_value()) {
            success_count++;
        } else {
            failure_count++;
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
    
    auto duration = std::chrono::duration_cast<std::chrono::duration<double>>(
        std::chrono::steady_clock::now() - start_time
    );
    double success_rate = 100.0 * success_count / (success_count + failure_count);
    
    std::cout << "\n性能报告:" << std::endl;
    std::cout << "  成功读取: " << success_count << " 帧" << std::endl;
    std::cout << "  失败次数: " << failure_count << " 次" << std::endl;
    std::cout << "  成功率: " << success_rate << "%" << std::endl;
    std::cout << "  实际帧率: " << (success_count / duration.count()) << " Hz" << std::endl;
    
    if (success_rate > 95) {
        std::cout << "✅ 性能良好" << std::endl;
    } else if (success_rate > 80) {
        std::cout << "⚠️ 性能一般，可能存在干扰" << std::endl;
    } else {
        std::cout << "❌ 性能不佳，需要检查连接" << std::endl;
    }
    
    controller.Disconnect();
    return 0;
}

6.3 常见故障排查 ​

故障 1: 编译错误 ​

症状：

error: 'optional' is not a member of 'std'

解决方法：

bash
# 检查编译器版本（需要支持 C++17）
g++ --version  # 应该 >= 7.0
clang++ --version  # 应该 >= 5.0

# 确保使用 C++17 标准
g++ -std=c++17 your_program.cpp -lpsi_glove_sdk

# 或在 CMakeLists.txt 中指定
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

故障 2: 链接错误 ​

症状：

undefined reference to 'psi_glove::PSIGloveController::Connect()'

解决方法：

bash
# 方法 1: 确保库已安装
sudo make install
sudo ldconfig

# 方法 2: 指定库路径
g++ your_program.cpp -L/usr/local/lib -lpsi_glove_sdk

# 方法 3: 设置环境变量
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

故障 3: 运行时找不到库 ​

症状：

error while loading shared libraries: libpsi_glove_sdk.so: 
cannot open shared object file: No such file or directory

解决方法：

bash
# 方法 1: 更新库缓存
sudo ldconfig

# 方法 2: 设置 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# 方法 3: 永久添加到配置
echo "/usr/local/lib" | sudo tee -a /etc/ld.so.conf.d/psi_glove.conf
sudo ldconfig

故障 4: 连接失败 ​

症状：

错误: 无法连接到设备

排查步骤：（参考 Python SDK 故障 1 的排查步骤，内容相同）

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

症状：

警告: 读取失败，使用缓存数据

排查步骤：（参考 Python SDK 故障 3 的排查步骤）

故障 6: 性能问题（帧率低） ​

症状：

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

解决方法：

  1. 优化编译选项

    bash
    cmake -DCMAKE_BUILD_TYPE=Release ..  # 使用优化编译

  2. 减少打印输出

    cpp
    if (frame_count % 100 == 0) {  // 每 100 帧打印一次
    std::cout << ...;
}

  3. 使用更小的平滑窗口

    cpp
    psi_glove::PSIGloveController controller(std::move(serial), 5);

  4. 提高波特率

    cpp
    auto serial = std::make_unique<psi_glove::SerialInterface>(
    "/dev/ttyACM0",
    500000  // 从 115200 提升到 500000
);

6.4 调试工具和技巧 ​

6.4.1 使用 GDB 调试 ​

bash
# 编译调试版本
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

# 使用 GDB 运行
gdb ./examples/basic_usage

# GDB 命令
(gdb) break main
(gdb) run /dev/ttyACM0
(gdb) next
(gdb) print controller.IsConnected()

6.4.2 性能分析 ​

bash
# 使用 valgrind 检查内存泄漏
valgrind --leak-check=full ./examples/basic_usage /dev/ttyACM0

# 使用 perf 分析性能
perf record ./examples/basic_usage /dev/ttyACM0
perf report

6.4.3 日志重定向 ​

bash
# 将输出保存到文件
./basic_usage /dev/ttyACM0 > output.log 2>&1

# 只保存错误
./basic_usage /dev/ttyACM0 2> error.log

# 同时显示和保存
./basic_usage /dev/ttyACM0 2>&1 | tee output.log

6.5 获取技术支持 ​

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

  1. 收集诊断信息

    bash
    # 系统信息
uname -a
g++ --version
cmake --version

# SDK 版本
pkg-config --modversion psi_glove_sdk

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

  2. 查看详细文档

    • C++ SDK README: cpp_sdk/README_CN.md
    • 示例说明: cpp_sdk/examples/README_CN.md

  3. 联系技术支持

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

📊 附录：快速参考 ​

常用命令 ​

bash
# 编译和安装 SDK
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig

# 编译示例
cmake -DBUILD_EXAMPLES=ON ..
make -j$(nproc)

# 运行示例
./examples/basic_usage /dev/ttyACM0
./examples/advanced_usage /dev/ttyACM0 500000
./examples/psi_glove_cpp_visualizer/psi_glove_cpp_visualizer --left /dev/ttyACM0

# 手动编译程序
g++ -std=c++17 your_program.cpp -lpsi_glove_sdk -o your_program

性能参数参考 ​

场景波特率超时平滑窗口预期帧率
标准配置1152006ms10100-120 Hz
高速配置5000003ms5150-200 Hz
嵌入式配置11520010ms350-80 Hz

数据范围 ​

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

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