触觉数据

触觉读取必须从布局开始。不同 Revo3 型号和 BOM 可能使用不同模组、信号和点数，应用不能把某一种布局写死为所有设备的通用结构。

推荐流程

1. 连接后读取 hand.touch.layout。
2. 确认每个模块的 module_id、区域、布局 ID、点数和信号能力。
3. 选择读取模式和数值模式。
4. 使用 snapshot()、snapshot(module_indices=[...])、module_snapshot() 或 subscribe() 读取触觉数据。
5. 对每个模块检查 sample_state，再读取可选字段。

TouchModuleData.points 可能为 None。模块禁用、未采样、读取失败或当前模式不提供点阵时，不能把缺失数据当成有效的全零采样。

SDK 2.1.0 会优先使用从完整序列号归一化得到的三位产品代号确定 Ultra Touch 拓扑：UT1 使用压阻阵列，UT2 使用高密触觉阵列。如果现场实物与自动结果不一致，先核对完整序列号和 SDK 版本。旧版压阻阵列硬件未提供运行时点数时，点数寄存器可能返回全 0；SDK 2.1.0 会回退到固定布局，不再把全 0 作为有效布局缓存。手动切换到高密触觉阵列时，SDK 会先只读验证 11 个模块的点数；探测失败或点数不合法时不会应用覆盖。界面 FPS 只表示读取循环在运行，不能单独证明触觉数值有效。

36／71 点掌心兼容

SDK 2.2.1 根据已识别的三位产品代号确定触觉拓扑；旧版或未知型号使用只读元数据探测。压阻阵列点数由运行时寄存器确定，并使用与布局匹配的数据地址，兼容旧版 36 点和新版 71 点掌心。旧固件没有提供有效点数时，保留固定布局回退。完整快照、选择性快照、单模组快照和订阅均使用该运行时布局，应用无需重复识别型号或固定读取 36 点。

从 2.2.1 起，连接成功前会读取已支持触觉阵列的运行时点数，首次获取的布局即可用于快照和订阅，无需先调用 await hand.touch.point_counts()。无阵列设备不执行该读取；旧固件继续使用既有兼容回退，点数初始化失败时连接返回错误。

Python 的 hand.touch.layout 及其 modules 是快照。显式调用 set_layout() 或再次查询点数后，重新获取布局及模组对象；之前缓存的对象不会自动更新。模组点数是 module.point_count 属性，运行时点数查询则是异步方法 await hand.touch.point_counts()。

point_count 表示数组长度，不定义物理坐标。热力图应使用与 layout_id 匹配的空间映射，不能将旧版 36 点坐标直接套用于 71 点数据。当前公开 GUI 示例仍使用 36 点掌心坐标，仅显示前 36 点数值；这不影响 SDK 读取完整的 71 点数据。具体限制见 GUI 说明。

选择性快照

• snapshot() 读取当前布局中所有已启用模组，返回 TouchFrame。
• snapshot(module_indices=[...]) 只读取指定模组，并按请求中的 module_id 顺序返回。
• module_snapshot(module_index) 读取一个模组，直接返回 TouchModuleData。

选择性读取不会修改设备的 enabled_mask。空列表、重复 ID 或当前布局不存在的 ID 会在触觉数据读取前返回参数错误。任一已选择分支读取失败时，整个操作失败，不返回部分拼接帧。

Ultra VisionTouch 独立通道说明

Ultra VisionTouch 的指尖视触觉数据通过独立的 USB/串口链路和专属 SDK 进行采集，不进入当前 SDK 的 hand.touch、TouchLayout 或 TouchFrame。若手部同时搭载了走主链路（Modbus/CAN FD）的压阻阵列或高密触觉阵列指腹与手掌模组，在只读探测确认布局后，Touch API 仅公开 module 0（手掌）及 module 2/4/6/8/10（拇指至小指指腹）。当前 SDK 不会创建缺失的指尖 module，亦不会对两路独立通道的数据进行跨链路拼接。

若阵列配置冲突或未能识别到有效布局，触觉功能将保持禁用状态以确保安全。仅在依据硬件型号与 BOM 确认真实布局后，才可通过 API 为当前连接会话显式设置完整布局；设备重新连接后需再次确认。

模组编号

公开参数使用布局提供的 module_id。组合拓扑中的 ID 可能稀疏，不保证等于 TouchLayout.modules 数组下标。始终从布局查找目标区域对应的模组。

模式与零点标定

• set_read_mode() 改变读取数据类型。
• set_value_mode() 在支持时选择 ADC 或 Force 等数值表达。
• tare() 会改变触觉零点状态，只能在无接触且满足设备要求时执行。
• tare_status() 用于确认异步标定状态。

模式切换和零点标定属于有状态操作。记录操作前后的布局、模式、固件和结果，不要在采集循环中隐式改变。完整字段见遥测 API。