触觉数据

触觉读取必须从布局开始。不同 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。模块禁用、未采样、读取失败或当前模式不提供点阵时，不能把缺失数据当成有效的全零采样。

选择性快照

• 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）的 mt_* 或 mx_* 指腹与手掌阵列，在只读探测确认布局后，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。