跳到主要内容

快速开始

开始前请完成安装，并连接手套。以下示例在扫描到多只手套时选择第一只；连接多设备时，请先核对端口、设备名称和序列号。

通过 USB 读取第一帧​

from xenseglovesdk import XenseGlove

gloves = [port for port in XenseGlove.list_ports() if port.is_glove]
if not gloves:
    raise RuntimeError("未发现手套，请检查 USB 连接和串口占用情况")

with XenseGlove.open(gloves[0].port) as glove:
    info = glove.info()
    print("序列号:", info.serial_number)
    print("固件版本:", info.version)

    glove.set_channel("serial")
    glove.set_output_mode("adc")

    frame = glove.read_frame(timeout=2.0)
    matrix = frame.value_map
    print("矩阵尺寸:", frame.rows, frame.cols)
    print("最大 ADC:", frame.max_value())
    print("手掌位置 (24, 8) 的读数:", matrix[24][8])

value_map 是 63 行、39 列的二维列表，读数为整数，无效位置为 None。with 代码块结束时会自动关闭连接，包括发生异常的情况。

通过 BLE 读取第一帧​

from xenseglovesdk import XenseGlove

if not XenseGlove.is_bluetooth_enabled():
    raise RuntimeError("请先开启计算机蓝牙")

devices = XenseGlove.scan_ble(timeout=5.0)
if not devices:
    raise RuntimeError("未发现蓝牙手套，请确认设备已开机并靠近计算机")

for device in devices:
    print(device.name, device.address)

with XenseGlove.open_ble(devices[0].address) as glove:
    print("序列号:", glove.info().serial_number)
    glove.set_channel("ble")
    glove.set_output_mode("adc")

    frame = glove.read_frame(timeout=2.0)
    print("最大 ADC:", frame.max_value())

扫描结果中的 address 用于连接，设备序列号以连接后 glove.info().serial_number 的结果为准。连接 BLE 后应显式设置 set_channel("ble")，确保手套向蓝牙通道输出数据。

连续读取​

read_frame() 返回最新一帧。两次读取之间没有新数据时，会返回相同的时间戳和序号。下面的示例持续运行 10 秒，仅处理更新后的帧：

import time

from xenseglovesdk import XenseGlove

gloves = [port for port in XenseGlove.list_ports() if port.is_glove]
if not gloves:
    raise RuntimeError("未发现手套")

with XenseGlove.open(gloves[0].port) as glove:
    glove.info()
    glove.set_channel("serial")
    glove.set_output_mode("adc")

    last_frame_key = None
    deadline = time.monotonic() + 10.0

    while time.monotonic() < deadline:
        try:
            frame = glove.read_frame(timeout=1.0)
        except TimeoutError:
            print("暂未收到数据")
            time.sleep(0.01)
            continue

        frame_key = (frame.timestamp, frame.sequence)
        if frame_key != last_frame_key:
            last_frame_key = frame_key
            print(frame.sequence, frame.max_value(), frame.valid_points())

        time.sleep(0.01)

轮询间隔决定应用读取数据的频率。SDK 提供最新帧，应用可能跳过两次读取之间的其他采样；需要保存历史时，应在循环中自行记录。

按区域分析数据​

以下代码使用前面读取到的 frame，查询各手指读数和满足阈值的接触点：

for finger, summary in frame.by_finger().items():
    print(finger, summary["max"], summary["mean"])

palm = frame.by_region()["palm"]
print("手掌 ADC 总和:", palm["total"])

for point in frame.contacts(threshold=10)[:5]:
    print(point.row, point.col, point.value)

接触点按 ADC 从高到低排列。这里的阈值 10 是示例值，请根据实际读数选择。完整矩阵布局和各字段含义见数据说明。

设置帧率与去皮​

以下操作在已打开的 USB 连接中执行：

glove.set_frequency(60, target="serial")

# 保持手套无负载，再执行去皮。
glove.tare()

帧率设置范围为 10～120 Hz，设备会保存该设置。tare() 会重新测量零偏并切换到 tare_adc 模式，仅支持 USB 串口连接。调用返回后仍应保持无负载，待读数稳定再开始测量。

如果只需要使用已有的去皮结果，可调用 glove.set_output_mode("tare_adc")。数据模式的区别见输出模式。