FAQ

这里整理了 XenseGloveSDK 安装、设备连接和数据读取过程中常见的问题。单击问题即可展开答案。

安装

安装时提示 wheel 与当前平台不兼容怎么办？

确认使用 Python 3.9 或更高版本的 CPython，并核对安装包与操作系统、CPU 架构是否匹配。Windows x64、Linux x64 和 Linux ARM64 使用不同的安装包；Linux 还需要 glibc 2.31 或更高版本。详见安装。

USB 扫描没有发现手套怎么办？

确认 USB 线支持数据传输，关闭可能占用串口的应用，再重新扫描。设备出现两个串口时，应使用数据端口（CDC0）。Linux 上还需确认当前用户具有串口访问权限。

可以查看各端口的识别结果和失败原因：

from xenseglovesdk import XenseGlove

for port in XenseGlove.list_ports():
    print(port.port, port.is_glove, port.error)

扫描失败可能与端口占用或查询超时有关。使用 probe=False 时只列出端口，不执行手套识别。

Windows 找不到手套串口，设备管理器显示黄色感叹号怎么办？

首次连接手套时，如果 Windows 尚未识别串口，请先确认计算机已联网并稍等片刻，系统通常会自动下载并安装驱动。

如果等待后仍未识别，且设备管理器中对应设备显示黄色感叹号，可搜索 CH340 或 CH341 驱动，从芯片厂商官网下载适用于当前 Windows 系统的驱动并手动安装。安装完成后重新插拔手套，再检查串口是否出现。

Linux 下手套串口偶尔无法识别或连接后消失怎么办？

部分 Linux 系统中的 brltty 服务可能将手套使用的 CH340 串口芯片误识别为盲文设备并抢占 USB 接口，导致手套串口偶尔无法识别或连接后消失。这是系统服务与 CH340 芯片的兼容性冲突。

如果确认是 brltty 占用接口，可禁用该服务，或调整其 udev 规则，排除手套对应的 CH340 设备。需要继续使用盲文设备时，可选择调整 udev 规则。使配置生效后，重新插拔手套并再次扫描串口，通常即可恢复识别。

BLE 扫描不到设备或连接失败怎么办？

确认手套支持 BLE 且已开机，计算机已开启蓝牙，并将手套靠近计算机。Linux 上请确认 BlueZ 和 D-Bus 服务可用。SDK 使用系统第一个蓝牙适配器。

使用最新扫描结果中的 address 建立连接。连接成功后，通过 info() 核对序列号，再调用 set_channel("ble") 开始向 BLE 通道输出数据。

已经连接，为什么读取压力帧仍然超时？

先确认输出通道与连接方式一致：USB 使用 set_channel("serial")，BLE 使用 set_channel("ble")。如果指定了 data_cmd，还需确认它与设备当前输出模式一致。

例如，在已打开的 USB 连接中：

glove.set_channel("serial")
glove.set_output_mode("adc")
frame = glove.read_frame(timeout=2.0, data_cmd="adc")

如果此前调用过 stop_stream()，请调用 start_stream() 恢复读取；如果通过 USB 进入过配置模式，请调用 set_config_mode(False) 恢复采样。

切换输出通道后，为什么原连接不再收到数据？

手套同一时刻仅通过一个输出通道发送数据。例如通过串口调用 set_channel("ble") 后，压力数据将发送到 BLE。

需要切换应用的连接方式时，应停止原读取流程、关闭连接，再用 open_ble() 或 open() 重新连接，并设置对应的输出通道。

为什么多次读取的序号和数值相同？

read_frame() 返回最新可用帧。读取速度高于设备更新速度时，可能多次得到同一帧。应用可结合 timestamp 和 sequence 去重，并设置合适的轮询间隔，参见连续读取示例。

timeout 只控制没有可用帧时的等待时间。已有帧时，即使设备暂时没有更新，读取也可能立即返回。需要判断数据是否持续更新时，请检查时间戳。

矩阵中的 None 和 0 有什么区别？

None 表示该位置没有有效数据，0 是有效 ADC 读数。两者在统计和可视化时应区别处理。使用 data_bytes 时，无效位置表示为 255。

设置 tare_adc 后，为什么没有重新归零？

set_output_mode("tare_adc") 选择应用已有去皮结果的数据模式。需要重新测量零偏时，请通过 USB 连接、保持手套无负载，再调用 tare()。待读数稳定后开始测量。去皮结果不作为永久校准保存。

左右手是否需要不同的矩阵解析方式？

左右手都使用 63 × 39 的同一布局。使用 info().hand 区分右手（0）和左手（1）；返回 None 表示设备未提供该信息。显示时如需镜像效果，由应用调整，见压力矩阵。