🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

2FG7 ROS driver

Expose the 2FG7 gripper through a ROS action and joint-state publisher, with hardware and mock modes.

onrobot_2fg7_driver.driver_node · Source

Tools and end effectors · Guide · Symbol index

How it is used

This node connects the ROS GripperCommand interface to the 2FG7 Modbus client, or uses mock state when configured. main() owns the ROS executor; ROS invokes the action and timer callbacks. Constructing OnRobot2FG7DriverNode can open the hardware connection.

ROS positions represent one finger’s travel in metres, while the hardware uses the full external width in millimetres. Check both the action status and reached_goal in the result: a succeeded action can report reached_goal=False. Accepted cancellation does not send a hardware stop.

Start here

Callable	Purpose
main	Initialize ROS, build driver and multithreaded executor, spin until interrupted, then clean up node/executor and ROS.
joint_pos_to_width_mm	Compute 1 + 2000×joint position and clamp external width to the physical 1–73 mm interval.
width_mm_to_joint_pos	Subtract the 1 mm minimum external width, halve the remainder and convert millimetres to metres, clamping only below zero.
OnRobot2FG7DriverNode._execute_gripper_command	Handle a GripperCommand goal by converting finger position to external width, sending the grip command, and polling hardware status. Use a positive requested effort or the configured default force; compare final width against a strict 5 mm tolerance. Poll every 0.1 seconds, allowing at least 0.3 seconds before accepting an idle reading and roughly five seconds of nominal polling overall.

Example

The conversion includes a 1 mm minimum external width:

One-finger ROS position	Full external width
0.0 m	1.0 mm
0.036 m	73.0 mm

joint_pos_to_width_mm() clamps the result to the physical 1–73 mm interval.

Functions

main()

Initialize ROS, build driver and multithreaded executor, spin until interrupted, then clean up node/executor and ROS.

Entry point · Source

main(args=None)

Parameter	Meaning
args	Optional ROS initialization argument list; None uses process arguments.

Returns: None, including when startup/runtime Exception is printed.

Errors: KeyboardInterrupt during spin is swallowed; other Exceptions in the outer try are printed as failed startup. rclpy.init is outside that try and final shutdown errors can propagate.

Side effects: Starts hardware driver and ROS executor; normal finally paths release node/executor/context.

joint_pos_to_width_mm()

Compute 1 + 2000×joint position and clamp external width to the physical 1–73 mm interval.

Function · Source

joint_pos_to_width_mm(joint_pos_m: float) -> float

Parameter	Meaning
joint_pos_m	One-sided finger prismatic travel in metres.

Returns: Clamped float external width in millimetres; 0.036 m reaches 73 mm.

Errors: Invalid numeric types propagate; no explicit NaN/infinity validation.

Side effects: Pure arithmetic.

Example

assert joint_pos_to_width_mm(0) == 1.0
assert joint_pos_to_width_mm(0.0365) == 73.0

Referenced in source (1)

• OnRobot2FG7DriverNode._execute_gripper_command — onrobot_2fg7_driver.driver_node

width_mm_to_joint_pos()

Subtract the 1 mm minimum external width, halve the remainder and convert millimetres to metres, clamping only below zero.

Function · Source

width_mm_to_joint_pos(width_mm: float) -> float

Parameter	Meaning
width_mm	Full external opening in millimetres.

Returns: Nonnegative one-finger travel in metres; no upper bound is applied.

Errors: Invalid numeric inputs propagate; no finite-value validation.

Side effects: Pure arithmetic.

Example

assert width_mm_to_joint_pos(1) == 0.0
assert abs(width_mm_to_joint_pos(73) - 0.036) < 1e-12

Referenced in source (2)

• OnRobot2FG7DriverNode._execute_gripper_command — onrobot_2fg7_driver.driver_node
• OnRobot2FG7DriverNode._publish_joint_states — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode

Serve gripper actions and publish the two finger joint positions. Real mode polls Modbus status; mock mode updates the simulated width.

Inherits from: Node.

OnRobot2FG7DriverNode._execute_gripper_command()

Handle a GripperCommand goal by converting finger position to external width, sending the grip command, and polling hardware status. Use a positive requested effort or the configured default force; compare final width against a strict 5 mm tolerance. Poll every 0.1 seconds, allowing at least 0.3 seconds before accepting an idle reading and roughly five seconds of nominal polling overall.

Callback · Source

_execute_gripper_command(self, goal_handle)

Parameter	Meaning
goal_handle	Accepted GripperCommand handle. request.command.position is one-sided metres; max_effort >0 becomes integer newtons, otherwise default_force is used.

Returns: GripperCommand.Result with position in metres, zero effort, and reached_goal reflecting final width tolerance. Mock mode sleeps 0.5 seconds and reports success/reached_goal=True using the original position. Real missing connection/write failure aborts; cancellation returns reached_goal=False; final mismatch or unreadable status still calls succeed().

Errors: Read/write exceptions propagate. Nominal timeout excludes serial blocking duration. Cancellation is checked only in real polling and issues no hardware stop; the driver has no explicit lock around cached width or Modbus access.

Side effects: Commands physical fingers, reads status, updates width cache, publishes action feedback and sets terminal action status.

Referenced in source (1)

• OnRobot2FG7DriverNode.__init__ — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode.__init__()

Read serial, force, speed, publication-rate and mock parameters; connect real hardware unless mocked; create the gripper action server and joint-state timer.

Lifecycle · Source

__init__(self)

Returns: None; initial cached width is 60 mm until a hardware read or command changes it.

Errors: Connection exhaustion only logs and still starts the server; construction errors propagate. Invalid publish_rate can cause division/timer errors.

Side effects: Registers onrobot_2fg7_driver, may open/poll serial hardware, starts gripper_action_controller/gripper_cmd and /joint_states publication.

Referenced in source (1)

• main — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode.destroy_node()

Log shutdown, disconnect the gripper if present, then invoke ROS node destruction.

Lifecycle · Source

destroy_node(self)

Returns: None; superclass return value is discarded.

Errors: Disconnect error can prevent node cleanup; no local catch.

Side effects: Closes serial hardware and destroys ROS entities.

Internal callbacks and helpers

OnRobot2FG7DriverNode._connect_gripper()

Create a client per attempt, require both connection and status read, cache initial width on success and leave gripper=None after exhausted attempts.

Internal helper · Source

_connect_gripper(self, max_retries=10, retry_delay=2.0)

Parameter	Meaning
max_retries	Number of connection attempts; zero makes no attempt.
retry_delay	Seconds slept between unsuccessful attempts, not after the last one.

Returns: None whether connected or exhausted; inspect self.gripper for outcome.

Errors: Expected failed connect/status responses log; successful connection with no status is disconnected. Transport exceptions propagate and are not retried by this method.

Side effects: Opens/reads/closes serial connections, sleeps and logs; updates hardware handle and cached width.

Referenced in source (1)

• OnRobot2FG7DriverNode.__init__ — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode._publish_joint_states()

Read current hardware width when available, otherwise reuse cache, then publish equal left/right finger positions with zero velocity/effort.

Callback · Source

_publish_joint_states(self)

Returns: None.

Errors: A failed status response retains cache; transport errors propagate. There is no freshness marker or disconnected-state suppression.

Side effects: May read Modbus, update cached width and publish twofg7_left_finger_joint/twofg7_right_finger_joint on /joint_states.

Referenced in source (1)

• OnRobot2FG7DriverNode.__init__ — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode._goal_callback()

Log requested finger position and effort and accept every GripperCommand goal.

Callback · Source

_goal_callback(self, goal_request)

Parameter	Meaning
goal_request	GripperCommand goal with command.position in metres and max_effort in newtons.

Returns: GoalResponse.ACCEPT unconditionally.

Errors: No range, finite-value, connection or concurrent-goal validation.

Side effects: Logs requested values; no direct motion here.

Referenced in source (1)

• OnRobot2FG7DriverNode.__init__ — onrobot_2fg7_driver.driver_node

OnRobot2FG7DriverNode._cancel_callback()

Accept any cancellation request and log it; execution checks the request during real-hardware polling.

Callback · Source

_cancel_callback(self, goal_handle)

Parameter	Meaning
goal_handle	Action goal handle; not inspected.

Returns: CancelResponse.ACCEPT.

Errors: No explicit error handling; accepting does not itself stop hardware.

Side effects: Logs cancellation only.

Referenced in source (1)

• OnRobot2FG7DriverNode.__init__ — onrobot_2fg7_driver.driver_node