Create behaviors to be used in the MoveIt Pro environment. These can be used to create an Objective by receiving input from the uSPr2F Taxel, performing the necessary calculations, and using the results as behaviors in the robot control sequence.
The behaviors targeted for this development are as follows:

Name	Description
ComputeTactileBaseline	Compute and store tactile baseline for 2F grasp behaviors.
SetTelemetryPhase	Publish global telemetry phase/event for objective-level tracing.
GraspWithForceStop	Slow-close gripper, stop on broad or point tactile contact, or continue after full close if no contact.
SlipMonitor	Monitor slip and tighten gripper while main motion runs.
RapidOpen	Open gripper rapidly for release.

Functional Specification Document : xela_2f_bebaviors¶

1. Introduction¶

This package provides custom MoveIt Pro behaviors for tactile 2F grasping, transport slip monitoring, and event telemetry using Xela uSPr2F sensors.

2. System Overview¶

• tactile input: xela_taxel_msgs/msg/XTaxelSensorTArray
• gripper target: control_msgs/action/GripperCommand
• runtime style: MoveIt Pro BT action plugins
• target hardware path: Robotiq 2F gripper with Xela 2F tactile modules

3. Functional Requirements¶

3.1. Baseline¶

• FR-01: shall compute a tactile baseline from /x_taxel_2f
• FR-02: shall store and reuse external baseline data through a named baseline_key

3.2. Grasp¶

• FR-03: shall support tactile stop grasping from broad force contact or sparse point contact
• FR-04: shall support optional dual-contact confirmation across both 2F tactile sides
• FR-05: shall track measured gripper joint state from /joint_states during grasp hold
• FR-06: shall maintain a post-contact hold phase before reporting grasp success
• FR-07: shall support configurable hold bias, hold reassert period, and settle thresholds

3.3. Slip Monitoring¶

• FR-08: shall support slip monitoring during transport
• FR-09: shall support sharp, thick, and wide slip-detection modes
• FR-10: shall tighten the gripper on detected slip using configured position and effort increments
• FR-11: shall support bounded monitoring windows through monitor_duration

3.4. Telemetry¶

• FR-12: shall publish grasp telemetry samples during tactile grasp execution
• FR-13: shall publish explicit JSON grasp/slip events on /x_telemetry_2f/grasp_event
• FR-14: shall provide enough metadata for sidecar analysis tooling, including phase/event names and slip mode/reason

4. Interfaces¶

4.1. Inputs¶

• /x_taxel_2f
• /joint_states
• /x_telemetry_2f/grasp_metric/close_pos

4.2. Outputs¶

• /x_telemetry_2f/grasp_telemetry
• /x_telemetry_2f/grasp_event
• /x_telemetry_2f/grasp_metric/force_total
• /x_telemetry_2f/grasp_metric/force_peak
• /x_telemetry_2f/grasp_metric/force_fz
• /x_telemetry_2f/grasp_metric/point_peak
• /x_telemetry_2f/grasp_metric/point_topk
• /x_telemetry_2f/grasp_metric/point_sigma
• /x_telemetry_2f/grasp_metric/active_taxels
• /x_telemetry_2f/grasp_metric/point_sparse
• /x_telemetry_2f/grasp_metric/close_pos
• /x_telemetry_2f/grasp_metric/gripper_vel

4.3. Action Target¶

• /robotiq_gripper_controller/gripper_cmd

5. Non-Functional Requirements¶

• NFR-01: shall avoid blocking executor work inside BT ticks
• NFR-02: shall keep callback-driven state in mutex-protected storage
• NFR-03: shall expose MoveIt Pro node metadata via tree_nodes_model.xml
• NFR-04: shall allow profile-driven tuning without requiring C++ changes for common object classes

6. Assumptions¶

• a runtime config package provides the actual gripper controller tuning
• /joint_states contains a finger_joint entry or a namespaced equivalent ending in finger_joint
• sidecar/UI consumers expect JSON payloads but are not required for behavior execution itself

---

xela_2f_bebaviors¶

1. Architecture¶

xela_2f_bebaviors implements stateful MoveIt Pro BT actions around a Robotiq 2F gripper and Xela tactile input.

/x_taxel_2f ------------------------------> ComputeTactileBaseline
/x_taxel_2f ------------------------------> GraspWithForceStop
/joint_states ----------------------------> GraspWithForceStop
GraspWithForceStop -----------------------> /x_telemetry_2f/grasp_telemetry
GraspWithForceStop -----------------------> /x_telemetry_2f/grasp_event
/x_telemetry_2f/grasp_telemetry ---------> SlipMonitor
/x_taxel_2f ------------------------------> SlipMonitor
SlipMonitor ------------------------------> /robotiq_gripper_controller/gripper_cmd
RapidOpen --------------------------------> /robotiq_gripper_controller/gripper_cmd
SetTelemetryPhase ------------------------> /x_telemetry_2f/grasp_event

2. Behavior Responsibilities¶

2.1. ComputeTactileBaseline¶

• samples /x_taxel_2f for a configured duration
• stores baseline data in a shared baseline store by baseline_key
• supports explicit target model filtering through model_name and model_config_yaml

2.2. GraspWithForceStop¶

• slow-closes the gripper in discrete steps
• evaluates force and point-contact metrics from the tactile stream
• supports optional dual-contact confirmation across left/right 2F sensor modules
• uses /joint_states to track finger_joint position and velocity
• after contact, transitions into a hold-confirm phase:
  • latches measured close position
  • adds a small close bias
  • periodically re-sends the hold goal
  • waits for tactile continuity plus measured joint settling before SUCCESS
• emits telemetry and explicit contact_detected / no_contact_full_close events

2.3. SlipMonitor¶

• runs in parallel with transport motion
• uses the latest close_pos metric as its entry grasp position
• supports three slip modes:
  • sharp: sparse point-contact slip priority
  • thick: mixed shear + point slip
  • wide: shear-dominant slip
• on slip detection:
  • increments close target
  • increments target effort
  • publishes slip_warning with mode, reason, close_pos, and target_effort

2.4. RapidOpen¶

• sends a simple gripper open goal and returns after a short wait

2.5. SetTelemetryPhase¶

• publishes objective-level phase/event markers into the same grasp event stream used by the sidecar

3. Profiles¶

Profiles are loaded from config/grasp_profiles.yaml.

• general: broad default behavior
• origami: sharp-contact grasp and slip tuning for crane-like objects
• origami_safe: more conservative transport profile
• egg: low-force fragile-object tuning
• plastic: wider contact profile
• heavy: higher-force wider-object profile

Each profile can override:

• tactile thresholds
• close speed
• hold bias and hold settle parameters
• baseline behavior
• slip thresholds and re-close increments

4. Integration Contract¶

4.1. MoveIt Pro¶

• behavior plugins are registered through xela_2f_bebaviors_plugin_description.xml
• node metadata is exposed through config/tree_nodes_model.xml
• objectives may redeclare local models, but the package-level model list is the source of truth

4.2. Sidecar / Telemetry¶

• Sidecar UI relies on /x_telemetry_2f/grasp_event and /x_telemetry_2f/grasp_telemetry
• current event payloads are designed to support:
  • explicit contact markers
  • slip markers with reason/mode
  • tooltip inspection of close target and effort target

4.3. Controller Assumptions¶

• gripper control is issued through /robotiq_gripper_controller/gripper_cmd
• current package behavior assumes a single active finger_joint and a GripperActionController-compatible command path
• final grasp stability depends on both behavior-side hold-confirm logic and controller-side stall/goal tolerance tuning in the runtime config package