End effectors

EROBS combines each tool’s geometry, working-tip frame, and device driver. The selected tool determines how the arm plans motion and how gripper or pipettor commands reach the hardware.

This page explains the CMS tool integration and its limits. For task steps and tool exchange, use Tools and end effectors.

Tool integration

The active beamline YAML defines each tool under grippers.<tool>, including its model, tip frame, payload, center of gravity, voltage, command states, and launch settings.

On real hardware, startup sends the tool’s payload and center of gravity to the UR controller and stops if that call fails. Selecting a tool model in MoveIt does not change these values.

Tool	How EROBS controls it
Hand-E (`hande`)	Named states `hande_closed` and `hande_open` reach the imported Hand-E driver through MoveIt and its gripper controller.
ePick (`epick`)	Named states `vacuum_on` and `vacuum_off` reach the imported ePick driver through MoveIt and its vacuum controller.
2FG7 (`2fg7`)	Named states `2fg7_closed` and `2fg7_open` reach a local ROS action server, which sends Modbus commands.
Pipettor (`pipettor`)	A dedicated task forwards operations to the imported pipettor driver. It has no gripper planning group.
No tool (`none`)	The model retains the arm, camera, and tool exchanger, with no gripper controller.

Under src/end_effectors/, EROBS owns epick_config, onrobot_2fg7_description, and onrobot_2fg7_driver. Hand-E, ePick, pipettor, and serial dependencies are imported through end_effectors.repos. Changes inside those imported repositories must be tracked separately from the EROBS revision.

See Robot models and controllers for model loading and controller routing.

Hand-E

CMS uses the hande_gripper planning group and robotiq_hande_end working tip. Its gripper controller uses ParallelGripperCommand, configured in cms_moveit_config/config/hande_controllers.yaml and config/hande/moveit_controllers.yaml.

The controller’s goal_tolerance is 0.01 m. A gripper step can report success before the fingers have fully settled, so the next arm move may begin early. Action success alone does not confirm a secure grasp.

ePick cup geometry

src/end_effectors/epick_config/config/suction_cups.yaml defines five profiles: pen_vacuum, 7mm_dia, 3mm_dia, 3mm_dia_external_air, and default. Each sets extension and cup dimensions in meters.

CMS defaults to 3mm_dia_external_air. Bringup forwards the selected profile to both MoveIt and the UR driver:

Model	Where the cup profile comes from
MoveIt	The orchestrator passes the active beamline’s `cup_profile` to CMS bringup, unless an explicit override is set.
UR driver / robot transforms	CMS bringup sets `BEAMBOT_EPICK_CUP_PROFILE` before starting the driver. `ur_with_zivid_epick.xacro` reads it when no explicit Xacro argument is supplied.
GUI 3D view	The already-expanded URDF selected by `grippers.epick.urdf_file`.

Direct CMS bringup also defaults to 3mm_dia_external_air. Set cup_profile:=<profile> when selecting another cup. Standalone Xacro expansion falls back to that same profile if neither an argument nor BEAMBOT_EPICK_CUP_PROFILE is supplied.

After changing a cup:

Set the beamline profile or explicit launch override to match the attached cup.
Regenerate the GUI URDF and rebuild the affected packages.
Restart the runtime and GUI, then compare their tool geometry and working tip.

CMS also sets grippers.epick.z_offset to −0.007 m to compensate for coupling geometry in the current model. Recheck this compensation when correcting the model or changing the assembly.

Continuous vacuum monitoring and loss-triggered aborts are disabled in the orchestrator. A successful vacuum command does not confirm that a sample remains attached; see ePick status and limits.

The local 2FG7 driver

onrobot_2fg7_driver/onrobot_2fg7_driver/driver_node.py, under src/end_effectors/, provides a GripperCommand action at gripper_action_controller/gripper_cmd and publishes finger positions on /joint_states.

It converts one finger’s joint position in meters to the full external grip width in millimeters:

width_mm = clamp(1.0 + joint_position_m × 2000, 1.0, 73.0)

For example, a joint position of 0.020 m requests a width of 41 mm. The driver clamps requests to 1–73 mm; the Modbus client encodes them in tenths of a millimeter.

The serial defaults are /tmp/ttyUR, slave 0x41, and 1 Mbaud. The host’s virtual serial port uses no parity; CMS configures even parity on the UR tool connection. Force, speed, publish rate, and mock mode are driver parameters.

Mock-mode limitation: CMS bringup passes use_fake_hardware, but this driver reads use_mock_hardware. Selecting mock UR hardware therefore does not enable this driver’s mock mode, and it can attempt a serial connection. The first-task ePick demo avoids the 2FG7 driver. The standalone 2FG7 driver must receive its own use_mock_hardware setting.

Action status also needs care: the driver can report SUCCEEDED with reached_goal: false when the requested width is not reached. Neither value independently proves that an object was grasped.

The package’s test_scripts/ contains hardware exercise programs, including direct Modbus commands, that act on a connected gripper.

Pipettor

Pipettor tasks send PipettorOperation goals to pipettor_operation without planning arm motion. Positioning and retreat are separate task steps.

EROBS forwards volume_pct, but the imported driver ignores it and uses fixed SUCK and EXPEL actuator sequences. Changing the value does not set a metered liquid volume. See pipettor operations and the task fields.

Tool changes and state

A tool exchange updates the selected model and relaunches the MoveIt/UR stack when required. A reported tool name represents software state; it does not independently confirm mechanical seating.

Before starting the new model, EROBS stops the old MoveIt process group and waits for its trajectory action to leave ROS discovery. See tool-change recovery.