4. SDK接口调用说明

4.1 核心类和方法

4.1.1 SerialInterface 类

串口通信接口类，处理底层硬件通信。

from psi_glove_sdk import SerialInterface

# 创建串口接口
serial = SerialInterface(
    port="/dev/ttyACM0",  # 串口路径
    baudrate=115200,       # 波特率
    timeout=0.006,         # 超时 (秒)
    auto_connect=False,    # 是否自动连接
    mock=False             # 是否使用模拟数据
)

4.1.2 PSIGloveController 类

主控制器类，管理数据读取、解析和平滑处理。

from psi_glove_sdk import PSIGloveController

# 创建控制器
controller = PSIGloveController(
    communication_interface=serial,  # 通信接口
    smoothing_window_size=10         # 平滑窗口大小
)

核心方法：

方法名称	返回类型	功能说明
connect()	bool	连接设备，成功返回 True
disconnect()	None	断开设备连接
is_connected()	bool	检查是否已连接
loop()	Optional[StatusMessage]	读取并返回关节数据，失败返回 None
get_last_status()	Optional[StatusMessage]	获取最后一次成功读取的数据

4.2 读取主手数据的完整流程

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

# 步骤 1: 创建串口接口
serial = SerialInterface(
    port="/dev/ttyACM0",
    baudrate=115200,
    timeout=0.006
)

# 步骤 2: 创建控制器
controller = PSIGloveController(
    communication_interface=serial,
    smoothing_window_size=10
)

# 步骤 3: 连接设备
if not controller.connect():
    print("错误: 无法连接到设备")
    exit(1)

print("连接成功!")

# 步骤 4: 循环读取数据
try:
    while True:
        # 读取数据（自动解析和平滑）
        status: StatusMessage = controller.loop()
        
        if status:
            # 成功读取数据
            print(f"拇指关节: {status.thumb}")
            print(f"食指关节: {status.index}")
            print(f"中指关节: {status.middle}")
            print(f"无名指关节: {status.ring}")
            print(f"小指关节: {status.pinky}")
            
            # 或者获取所有关节的扁平列表（21个值）
            all_joints = status.to_list()
            print(f"所有关节 (21个): {all_joints}")
        else:
            # 读取失败，使用缓存数据
            last_status = controller.get_last_status()
            if last_status:
                print("使用缓存数据")
        
        # 控制循环频率（100 Hz）
        time.sleep(0.01)

except KeyboardInterrupt:
    print("\n用户中断")

finally:
    # 步骤 5: 断开连接
    controller.disconnect()
    print("已断开连接")

4.3 数据格式和单位

StatusMessage 数据结构

from dataclasses import dataclass
from typing import List

@dataclass
class StatusMessage:
    thumb: List[int]   # 拇指 5 个关节位置
    index: List[int]   # 食指 4 个关节位置
    middle: List[int]  # 中指 4 个关节位置
    ring: List[int]    # 无名指 4 个关节位置
    pinky: List[int]   # 小指 4 个关节位置
    
    def to_list(self) -> List[int]:
        """返回所有 21 个关节值的扁平列表"""
        return self.thumb + self.index + self.middle + self.ring + self.pinky

关节索引映射

手指	关节数量	索引范围	访问方式
拇指	5	0-4	status.thumb[0-4]
食指	4	5-8	status.index[0-3]
中指	4	9-12	status.middle[0-3]
无名指	4	13-16	status.ring[0-3]
小指	4	17-20	status.pinky[0-3]

数据单位和范围

• 数据类型: int (整数)
• 数值范围: 0 - 4095 (12位 ADC)
• 物理含义: 关节传感器的电压值（经过模数转换）
• 数值对应:
  • 0: 传感器最小值（手指完全伸直）
  • 2048: 传感器中间值
  • 4095: 传感器最大值（手指完全弯曲）

数据处理示例：

# 归一化到 0.0 - 1.0 范围
def normalize_joint(value: int) -> float:
    """将 ADC 值归一化到 [0.0, 1.0]"""
    return value / 4095.0

# 映射到角度（需要校准）
def adc_to_angle(value: int, min_adc: int, max_adc: int, min_angle: float, max_angle: float) -> float:
    """将 ADC 值映射到角度"""
    normalized = (value - min_adc) / (max_adc - min_adc)
    return min_angle + normalized * (max_angle - min_angle)

# 使用示例
status = controller.loop()
if status:
    # 归一化拇指第一关节
    normalized = normalize_joint(status.thumb[0])
    print(f"归一化值: {normalized:.3f}")
    
    # 映射到角度（假设校准范围）
    angle = adc_to_angle(status.thumb[0], 500, 3500, 0.0, 90.0)
    print(f"关节角度: {angle:.2f}°")

4.4 高级用法示例

4.4.1 批量数据采集

import time
from psi_glove_sdk import PSIGloveController, SerialInterface

# 初始化
serial = SerialInterface("/dev/ttyACM0", 115200)
controller = PSIGloveController(serial, smoothing_window_size=10)
controller.connect()

# 采集 1000 帧数据
data_buffer = []
for i in range(1000):
    status = controller.loop()
    if status:
        data_buffer.append(status.to_list())
    time.sleep(0.01)

# 保存到 CSV
import csv
with open('glove_data.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerow([f'joint_{i}' for i in range(21)])  # 表头
    writer.writerows(data_buffer)

print(f"已保存 {len(data_buffer)} 帧数据到 glove_data.csv")
controller.disconnect()

4.4.2 多手套同时使用

from psi_glove_sdk import PSIGloveController, SerialInterface

# 左手
left_serial = SerialInterface("/dev/ttyACM0", 115200)
left_controller = PSIGloveController(left_serial)
left_controller.connect()

# 右手
right_serial = SerialInterface("/dev/ttyACM1", 115200)
right_controller = PSIGloveController(right_serial)
right_controller.connect()

# 同时读取双手数据
while True:
    left_status = left_controller.loop()
    right_status = right_controller.loop()
    
    if left_status and right_status:
        print(f"左手拇指: {left_status.thumb[0]}, 右手拇指: {right_status.thumb[0]}")
    
    time.sleep(0.01)

---