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

2FG7 Modbus client

Low-level 2FG7 Modbus RTU client over the UR tool serial bridge. Writes width/force/speed/mode registers at 0x0000 and reads eight status registers at 0x0100. Dataclass GripperStatus holds decoded widths, busy flag, raw status and registers; no auto-connect at construction.

onrobot_2fg7_driver.modbus_client · Source

Tools and end effectors · Guide · Symbol index

How it is used

OnRobot2FG7Client is the serial transport used by the ROS driver. Construction configures the client; connect() opens the connection. Read status through read_status(), send grip commands through the mode-specific methods, and call disconnect() when finished.

Widths are in millimetres, force in newtons, and speed in percent. A successful command means the register write succeeded, not that the gripper reached its requested width. Callers must inspect status to determine completion; is_busy() alone cannot distinguish an idle gripper from a failed status read.

Start here

Callable	Purpose
OnRobot2FG7Client.connect	Delegate opening the configured serial connection to pymodbus.
OnRobot2FG7Client.read_status	Read eight holding registers and decode busy, external/internal widths and the last status register.
OnRobot2FG7Client.grip_external	Send a width/force/speed command in external (1) mode through the shared register encoder.
OnRobot2FG7Client.grip_internal	Send a width/force/speed command in internal (2) mode through the shared register encoder.
OnRobot2FG7Client.disconnect	Close the pymodbus client connection.

OnRobot2FG7Client

Encode 2FG7 commands and decode status over Modbus RTU. The caller owns connection lifetime and completion checks.

OnRobot2FG7Client.connect()

Delegate opening the configured serial connection to pymodbus.

Lifecycle · Source

connect(self) -> bool

Returns: Underlying client.connect() Boolean indicating connection success.

Errors: Underlying exceptions propagate.

Side effects: Opens the serial device/PTY.

OnRobot2FG7Client.read_status()

Read eight holding registers and decode busy, external/internal widths and the last status register.

Method · Source

read_status(self) -> 'GripperStatus | None'

Returns: GripperStatus with busy Boolean, external_width_mm/internal_width_mm floats, status integer and raw_registers list; None for a Modbus error response.

Errors: Error responses log; short register arrays and transport exceptions propagate.

Side effects: Performs a serial Modbus read.

Referenced in source (2)

• OnRobot2FG7Client.get_width — onrobot_2fg7_driver.modbus_client
• OnRobot2FG7Client.is_busy — onrobot_2fg7_driver.modbus_client

OnRobot2FG7Client.grip_external()

Send a width/force/speed command in external (1) mode through the shared register encoder.

Method · Source

grip_external(self, width_mm: float, force_n: int=40, speed_pct: int=100) -> bool

Parameter	Meaning
width_mm	Target gripper width in millimetres.
force_n	Requested newtons, clamped to 0–140 by _write_command.
speed_pct	Requested speed percent, clamped to 1–100.

Returns: Boolean command-write acceptance; does not wait for motion or grip confirmation.

Errors: Returns False for Modbus error response; conversion/transport exceptions propagate.

Side effects: Writes gripper command registers and can move fingers.

OnRobot2FG7Client.grip_internal()

Send a width/force/speed command in internal (2) mode through the shared register encoder.

Method · Source

grip_internal(self, width_mm: float, force_n: int=40, speed_pct: int=100) -> bool

Parameter	Meaning
width_mm	Target gripper width in millimetres.
force_n	Requested newtons, clamped to 0–140 by _write_command.
speed_pct	Requested speed percent, clamped to 1–100.

Returns: Boolean command-write acceptance; does not wait for motion or grip confirmation.

Errors: Returns False for Modbus error response; conversion/transport exceptions propagate.

Side effects: Writes gripper command registers and can move fingers.

OnRobot2FG7Client.disconnect()

Close the pymodbus client connection.

Lifecycle · Source

disconnect(self)

Returns: None; underlying close return value is discarded.

Errors: Underlying close errors propagate.

Side effects: Closes serial resources.

OnRobot2FG7Client.__init__()

Construct a pymodbus serial client using 8N1 on the local virtual port and retain the slave keyword and optional logger.

Lifecycle · Source

__init__(
    self,
    port = DEFAULT_PORT,
    slave_id = DEFAULT_SLAVE_ID,
    baudrate = DEFAULT_BAUD,
    timeout = 0.5,
    logger = None,
)

Parameter	Meaning
port	Serial device/PTY path, default /tmp/ttyUR.
slave_id	Modbus slave address, default 0x41 (65).
baudrate	Serial baud rate in bits per second, default 1,000,000.
timeout	Serial response timeout in seconds, default 0.5.
logger	Optional object exposing error(str) for Modbus error responses.

Returns: None; self.client is configured but not connected.

Errors: pymodbus/client option errors propagate.

Side effects: Allocates client state; opening the port is deferred to connect().

Referenced in source (1)

• OnRobot2FG7DriverNode._connect_gripper — onrobot_2fg7_driver.driver_node

OnRobot2FG7Client.release()

Send an external-mode width command with a fixed 20 N force; the caller chooses the opening width.

Method · Source

release(self, width_mm: float, speed_pct: int=100) -> bool

Parameter	Meaning
width_mm	Target external width in millimetres.
speed_pct	Speed percent clamped to 1–100.

Returns: Boolean write acceptance, not verified release completion.

Errors: Shared encoder/transport errors propagate; Modbus error responses yield False.

Side effects: Commands gripper width in external mode.

OnRobot2FG7Client.get_width()

Read status once and extract its external width.

Method · Source

get_width(self) -> 'float | None'

Returns: Float millimetres or None when the status read returns None.

Errors: Transport/decode errors propagate.

Side effects: Performs a Modbus status read.

OnRobot2FG7Client.is_busy()

Read the gripper status and return its busy flag. A failed status read also returns False, so this method alone cannot confirm that the gripper is idle.

Method · Source

is_busy(self) -> bool

Returns: Boolean busy flag; False is ambiguous between idle and failed read.

Errors: Transport/decode errors propagate despite response errors mapping to False.

Side effects: Performs a Modbus status read.

Internal callbacks and helpers

OnRobot2FG7Client._write_command()

Encode width to rounded tenths of a millimetre and write four command registers, clamping force, speed and mode.

Internal helper · Source

_write_command(self, width_mm: float, force_n: int, speed_pct: int, mode: int) -> bool

Parameter	Meaning
width_mm	Requested width in millimetres; rounded ×10 and clamped only at zero, with no upper register/physical-width bound here.
force_n	Force in newtons, int-converted and clamped to 0–140.
speed_pct	Speed percentage, int-converted and clamped to 1–100.
mode	Mode integer clamped to 1–2: external/internal grip.

Returns: True for a nonerror Modbus write response, False for result.isError(); not a motion-completion indication.

Errors: Error responses log when a logger exists; transport, invalid numeric and register-range exceptions propagate.

Side effects: Writes device registers and can initiate gripper motion.

Referenced in source (3)

• OnRobot2FG7Client.grip_external — onrobot_2fg7_driver.modbus_client
• OnRobot2FG7Client.grip_internal — onrobot_2fg7_driver.modbus_client
• OnRobot2FG7Client.release — onrobot_2fg7_driver.modbus_client