Touch data

Begin with TouchLayout. Revo3 models and BOM variants can expose different modules, signals, and point counts; a single hard-coded layout is not portable.

1. Read hand.touch.layout.
2. Inspect module ID, region, layout ID, point count, and signals.
3. Select read and value modes when required.
4. Use snapshot(), snapshot(module_indices=[...]), module_snapshot(), or subscribe() to read tactile data.
5. Check each module's SampleState before optional fields.

TouchModuleData.points can be absent when a module is disabled, unavailable, not sampled, failed, or not represented as a point array in the current mode. Missing data is not a valid all-zero sample.

Selective snapshots

• snapshot() reads every enabled module in the current layout and returns a TouchFrame.
• snapshot(module_indices=[...]) reads only the requested modules and returns them in requested module_id order.
• module_snapshot(module_index) reads one module and returns TouchModuleData directly.

Selective reads do not change the device enabled_mask. An empty list, duplicate ID, or ID absent from the current layout fails before tactile data is requested. If any selected branch fails, the whole operation fails without returning a partially stitched frame.

Ultra VisionTouch independent channels

Ultra VisionTouch fingertip vision-tactile data is acquired through a separate USB/serial link and dedicated SDK. It is not routed into hand.touch, TouchLayout, or TouchFrame. When a hand also includes primary-link mt_* or mx_* finger-pad and palm arrays, the Touch API exposes module 0 (palm) and modules 2/4/6/8/10 (Thumb to Pinky finger pads) after read-only discovery confirms the layout. The SDK does not synthesize missing fingertip modules or merge data across the two independent channels.

If array configurations conflict or no valid layout is detected, the tactile interface remains uninitialized for safety. Explicitly configure a layout for the current connection only after verifying the hardware model and BOM; re-verify after reconnecting.

Public operations use the layout's module_id, which may be sparse and need not equal the array index. Taring changes calibration state and must run only under confirmed no-contact conditions. See the telemetry API.

Modes and taring

• set_read_mode() changes the data representation returned by the device.
• set_value_mode() selects ADC or Force values when supported.
• tare() changes tactile zero state and must run only when the sensor is unloaded as required by the device.
• tare_status() reports progress for asynchronous taring.

Mode changes and taring are stateful operations. Record the layout, mode, firmware version, and result before and after the operation; do not change them implicitly inside an acquisition loop.