API 参考
from xenseglovesdk import XenseGlove, get_glove_layout
使用 XenseGlove.open() 或 XenseGlove.open_ble() 创建连接。读取接口返回 Frame，设备信息等记录支持属性和字典两种访问方式，例如 info.serial_number 与 info["serial_number"]。
除另有说明外，timeout 的单位均为秒。设置类方法成功返回 None。
发现与连接
| 方法 | 说明 |
|---|---|
XenseGlove.list_ports(probe=True, timeout=0.5) | 返回串口记录列表。默认识别手套，通过 is_glove 筛选；timeout 为每个端口的查询等待时间。probe=False 时仅列出端口 |
XenseGlove.scan_ble(timeout=5.0) | 扫描 BLE 设备并返回记录列表；timeout 范围为大于 0、至多 120 秒 |
XenseGlove.is_bluetooth_enabled(timeout=2.0) | 查询系统第一个蓝牙适配器是否开启，返回 bool；timeout 范围为大于 0、至多 120 秒 |
XenseGlove.open(port) | 通过串口名连接，如 COM5 或 /dev/ttyACM0，返回已连接的 XenseGlove |
XenseGlove.open_ble(address, timeout=10.0) | 使用扫描结果中的 address 连接 BLE；timeout 范围为大于 0、至多 120 秒 |
list_ports() 返回所有串口。每条记录的字段如下：
| 字段 | 说明 |
|---|---|
port | 串口名，用于 open() |
description | 设备描述，可能为空 |
hardware_id | USB 设备标识，可能为空 |
is_glove | 是否已成功识别为手套 |
info | 已识别手套的设备信息，否则为 None |
error | 连接或查询失败的原因；无错误时为 None |
端口被占用或查询超时时也可能无法识别。probe=False 时，is_glove=False 表示未执行识别。
BLE 扫描记录包含 name（设备名称）、address（连接地址）、serial_number（扫描时的设备标识）和 rssi（信号强度，单位 dBm，可能为 None）。准确序列号通过连接后的 info() 获取。
设备信息与设置
| 方法 | 参数与返回值 |
|---|---|
info(timeout=1.0) | 查询设备信息和当前设置，返回记录 |
query_version(timeout=1.0) | 返回固件版本字符串 |
query_battery(timeout=1.0) | 返回电池电压整数，单位 mV |
set_output_mode(mode, timeout=1.0) | mode 为 "adc"、"raw" 或 "tare_adc"，含义见输出模式 |
set_frequency(hz, target=None, timeout=1.0) | hz 为 10～120 的整数；target 为 "serial" 或 "ble"，省略时设置当前连接通道的帧率；设备会保存该设置 |
set_channel(channel, timeout=1.0) | channel 为 "serial" 或 "ble"，选择设备输出通道 |
tare(timeout=2.0) | 在无负载状态下执行去皮并切换至 tare_adc；仅串口支持 |
set_config_mode(enabled, timeout=1.0) | True 进入配置模式并暂停设备采样，False 退出；仅串口支持 |
BLE 操作的可用性取决于设备和固件支持。query_battery() 返回电压，例如 3900 表示 3.9 V。
tare() 返回后，设备可能仍在执行去皮。请保持无负载，待读数稳定后再开始测量。
设备信息字段
| 字段 | 含义 |
|---|---|
serial_number | 设备序列号，设备未提供时可能为空 |
version | 固件版本；SDK 版本通过 xenseglovesdk.__version__ 获取 |
rows / cols | 压力矩阵尺寸，63 / 39 |
hand | 0 右手、1 左手、None 未提供 |
frequency / ble_frequency | 串口 / BLE 输出帧率，单位 Hz；不支持 BLE 时其帧率可能为 0 |
output_mode / output_mode_name | 模式编号及名称：0 / adc、1 / raw、3 / tare_adc |
channel | 当前输出通道：0 串口、1 BLE |
with_ble | 是否支持 BLE |
board_kind | 设备类型标识：ble 或 mcu |
切换连接方式
set_channel() 选择手套发送数据的通道。需要从 USB 改为 BLE 连接时，应停止当前读取、关闭原连接，再通过 open_ble() 建立新连接并设置 set_channel("ble")；反向切换时使用 open() 和 set_channel("serial")。
打开连接和调用 reload() 都会保留设备当前的数据模式、帧率和输出通道。请按应用需要显式设置这些参数。
读取与连接管理
| 方法或属性 | 说明 |
|---|---|
read_frame(timeout=1.0, data_cmd=None) | 返回最新压力帧 Frame。data_cmd=None 接受任意模式，也可传入 "adc"、"raw" 或 "tare_adc" 进行筛选；没有匹配帧时等待，超时抛出 TimeoutError |
read_gyro(timeout=1.0, latest=True) | 返回一个 IMU 样本。默认取最新样本并丢弃更早的待取样本；latest=False 按时间顺序取最早样本；超时抛出 TimeoutError |
read_available_gyro_samples(limit=None) | 立即返回当前可取的 IMU 样本列表，按时间从早到晚排列。limit 为非负整数；0 返回空列表，None 最多取 4096 条 |
is_connected | 只读 bool 属性，表示当前连接状态 |
stop_stream() / start_stream() | 暂停 / 恢复 SDK 数据读取，并清空待取的压力和 IMU 数据；设备继续采样，设备查询和设置仍可使用 |
reload() | 无参数。关闭旧连接，按原连接方式和原串口名或 BLE 地址重新连接，恢复数据读取；成功返回 None，失败时抛出异常并保持关闭状态 |
close() | 关闭连接并释放资源，可重复调用 |
压力帧保留最新一帧，重复读取不会移除数据。已返回的帧不随后续采集变化。没有新数据时，read_frame() 仍可能立即返回先前的帧，连续采集的处理方式见快速开始。
压力和 IMU 读取的 timeout=0 表示不等待。独立 IMU 待读列表最多保留 128 条样本，达到容量后最早样本被移除。
切换模式或输出通道、执行去皮、切换配置模式，以及暂停或恢复读取后，需要等待新数据。连接关闭后无法继续读取，但已取得的 Frame 仍可使用。
需要重建连接时，待原端口或蓝牙设备恢复可用后调用 glove.reload()，再重新读取设备信息和数据帧。该方法保留设备设置，使用原连接地址；更换连接方式或地址时，请关闭旧连接并使用 open() 或 open_ble() 建立新连接。
推荐使用上下文管理器关闭连接：
with XenseGlove.open("COM5") as glove:
print(glove.info().serial_number)
示例端口名应替换为扫描到的实际端口。
Frame 属性与方法
Frame 由 read_frame() 返回。
| 属性 | 含义 |
|---|---|
serial_number | 设备序列号；尚未读取到设备信息时可能为空 |
timestamp / timestamp_ms / sequence | 主机时间、设备时间和帧序号，见时间与帧序号 |
mode | 当前帧的数据模式：adc、raw 或 tare_adc |
rows / cols | 矩阵行、列数 |
values / value_map / data_bytes | 一维列表、二维列表和字节数据，见压力矩阵 |
gyro | 当前帧附带的 IMU 样本，没有时为 None |
| 方法 | 返回值与说明 |
|---|---|
get_point(row, col) | 指定位置的 ADC 整数或 None；行范围 0～62，列范围 0～38，越界抛出 IndexError |
region_values(name) | 返回区域内有效数据的字典，键为完整矩阵中的一维索引；name 为 thumb、index、middle、ring、little 或 palm |
total_value() | 有效 ADC 总和 |
max_value() | 最大有效 ADC，无有效值时返回 0 |
mean_value() | 有效 ADC 平均值，无有效值时返回 0.0 |
valid_points() | 有效点数，包含读数为 0 的位置 |
by_region() / by_finger() | 区域或手指统计字典，字段见区域统计 |
contacts(threshold=1) | 满足阈值的接触点列表，ADC 从高到低排列 |
contact_uv(threshold=1) | 最大接触点的归一化坐标 [u, v]，没有满足阈值的点时返回 None |
to_text() | 返回帧信息和矩阵的文本，无效位置显示为 * |
to_dict() | 返回可用于 JSON 导出的字典，字段见导出数据 |
布局查询
XenseGlove.regions() 返回六个区域的记录，每条记录包含 name、row_start、row_end、col_start、col_end。起始索引包含在区域内，结束索引不包含在内，适合直接用于 Python 切片。
get_glove_layout(rows=63, cols=39) 返回完整布局记录，支持的尺寸为 63 × 39：
| 字段 | 含义 |
|---|---|
rows / cols / name | 行数、列数和布局名称 |
active_indices / empty_indices | 手部区域 / 空白区域的一维索引列表 |
palm_indices | 手掌索引列表 |
finger_indices | 从手指名称到索引列表的映射 |
index_region | 从索引到 empty、finger 或 palm 的映射 |
index_finger | 从索引到手指名称的映射，非手指位置为空字符串 |
布局描述各区域的位置。单帧数据是否有效，应检查对应读数是否为 None。
异常处理
| 异常 | 处理建议 |
|---|---|
ValueError / TypeError / OverflowError | 检查参数内容、类型与范围 |
IndexError | 检查访问的矩阵坐标是否越界 |
TimeoutError | 检查数据输出通道、模式和设备状态；设置操作超时后，应先查询状态再决定是否重试 |
ConnectionError | 检查连接、端口占用、驱动和访问权限 |
NotImplementedError | 确认当前设备及连接方式支持所调用的功能 |
RuntimeError | 根据异常信息检查设备状态与固件支持情况 |
设置操作超时不代表设置一定失败。恢复连接前，应先确认设备状态，避免反复执行去皮等操作。