feat(api): RobotContext: Add gripper commands (#16752)

api/src/opentrons/hardware_control/protocols/gripper_controller.py

@@ -14,6 +14,9 @@ async def grip(
     ) -> None:
         ...
 
+    async def home_gripper_jaw(self) -> None:
+        ...
+
     async def ungrip(self, force_newtons: Optional[float] = None) -> None:
         """Release gripped object.
 

api/src/opentrons/protocol_api/core/engine/robot.py

@@ -129,3 +129,11 @@ def move_axes_relative(self, axis_map: AxisMapType, speed: Optional[float]) -> N
         self._engine_client.execute_command(
             cmd.robot.MoveAxesRelativeParams(axis_map=axis_engine_map, speed=speed)
         )
+
+    def release_grip(self) -> None:
+        self._engine_client.execute_command(cmd.robot.openGripperJawParams())
+
+    def close_gripper(self, force: Optional[float] = None) -> None:
+        self._engine_client.execute_command(
+            cmd.robot.closeGripperJawParams(force=force)
+        )

api/src/opentrons/protocol_api/core/robot.py

@@ -41,3 +41,11 @@ def move_axes_to(
     @abstractmethod
     def move_axes_relative(self, axis_map: AxisMapType, speed: Optional[float]) -> None:
         ...
+
+    @abstractmethod
+    def release_grip(self) -> None:
+        ...
+
+    @abstractmethod
+    def close_gripper(self, force: Optional[float] = None) -> None:
+        ...

api/src/opentrons/protocol_api/robot_context.py

@@ -144,11 +144,13 @@ def move_axes_relative(
         )
         self._core.move_axes_relative(axis_map, speed)
 
-    def close_gripper_jaw(self, force: float) -> None:
-        raise NotImplementedError()
+    def close_gripper_jaw(self, force: Optional[float] = None) -> None:
+        """Command the gripper closed with some force."""
+        self._core.close_gripper(force)
 
     def open_gripper_jaw(self) -> None:
-        raise NotImplementedError()
+        """Command the gripper open."""
+        self._core.release_grip()
 
     def axis_coordinates_for(
         self,

api/src/opentrons/protocol_engine/commands/command_unions.py

@@ -416,6 +416,8 @@
         robot.MoveTo,
         robot.MoveAxesRelative,
         robot.MoveAxesTo,
+        robot.openGripperJaw,
+        robot.closeGripperJaw,
     ],
     Field(discriminator="commandType"),
 ]
@@ -499,6 +501,8 @@
     robot.MoveAxesRelativeParams,
     robot.MoveAxesToParams,
     robot.MoveToParams,
+    robot.openGripperJawParams,
+    robot.closeGripperJawParams,
 ]
 
 CommandType = Union[
@@ -580,6 +584,8 @@
     robot.MoveAxesRelativeCommandType,
     robot.MoveAxesToCommandType,
     robot.MoveToCommandType,
+    robot.openGripperJawCommandType,
+    robot.closeGripperJawCommandType,
 ]
 
 CommandCreate = Annotated[
@@ -662,6 +668,8 @@
         robot.MoveAxesRelativeCreate,
         robot.MoveAxesToCreate,
         robot.MoveToCreate,
+        robot.openGripperJawCreate,
+        robot.closeGripperJawCreate,
     ],
     Field(discriminator="commandType"),
 ]
@@ -745,6 +753,8 @@
     robot.MoveAxesRelativeResult,
     robot.MoveAxesToResult,
     robot.MoveToResult,
+    robot.openGripperJawResult,
+    robot.closeGripperJawResult,
 ]
 
 

api/src/opentrons/protocol_engine/commands/robot/__init__.py

@@ -21,6 +21,20 @@
     MoveAxesRelativeResult,
     MoveAxesRelativeCommandType,
 )
+from .open_gripper_jaw import (
+    openGripperJaw,
+    openGripperJawCreate,
+    openGripperJawParams,
+    openGripperJawResult,
+    openGripperJawCommandType,
+)
+from .close_gripper_jaw import (
+    closeGripperJaw,
+    closeGripperJawCreate,
+    closeGripperJawParams,
+    closeGripperJawResult,
+    closeGripperJawCommandType,
+)
 
 __all__ = [
     # robot/moveTo
@@ -41,4 +55,16 @@
     "MoveAxesRelativeParams",
     "MoveAxesRelativeResult",
     "MoveAxesRelativeCommandType",
+    # robot/openGripperJaw
+    "openGripperJaw",
+    "openGripperJawCreate",
+    "openGripperJawParams",
+    "openGripperJawResult",
+    "openGripperJawCommandType",
+    # robot/closeGripperJaw
+    "closeGripperJaw",
+    "closeGripperJawCreate",
+    "closeGripperJawParams",
+    "closeGripperJawResult",
+    "closeGripperJawCommandType",
 ]

api/src/opentrons/protocol_engine/commands/robot/close_gripper_jaw.py

@@ -0,0 +1,79 @@
+"""Command models for opening a gripper jaw."""
+from __future__ import annotations
+from typing import Literal, Type, Optional
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.resources import ensure_ot3_hardware
+
+from pydantic import BaseModel, Field
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+from opentrons.protocol_engine.errors.error_occurrence import ErrorOccurrence
+
+
+closeGripperJawCommandType = Literal["robot/closeGripperJaw"]
+
+
+class closeGripperJawParams(BaseModel):
+    """Payload required to close a gripper."""
+
+    force: Optional[float] = Field(
+        default=None,
+        description="The force the gripper should use to hold the jaws, falls to default if none is provided.",
+    )
+
+
+class closeGripperJawResult(BaseModel):
+    """Result data from the execution of a closeGripperJaw command."""
+
+    pass
+
+
+class closeGripperJawImplementation(
+    AbstractCommandImpl[closeGripperJawParams, SuccessData[closeGripperJawResult]]
+):
+    """closeGripperJaw command implementation."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: closeGripperJawParams
+    ) -> SuccessData[closeGripperJawResult]:
+        """Release the gripper."""
+        ot3_hardware_api = ensure_ot3_hardware(self._hardware_api)
+        await ot3_hardware_api.grip(force_newtons=params.force)
+        return SuccessData(
+            public=closeGripperJawResult(),
+        )
+
+
+class closeGripperJaw(
+    BaseCommand[closeGripperJawParams, closeGripperJawResult, ErrorOccurrence]
+):
+    """closeGripperJaw command model."""
+
+    commandType: closeGripperJawCommandType = "robot/closeGripperJaw"
+    params: closeGripperJawParams
+    result: Optional[closeGripperJawResult]
+
+    _ImplementationCls: Type[
+        closeGripperJawImplementation
+    ] = closeGripperJawImplementation
+
+
+class closeGripperJawCreate(BaseCommandCreate[closeGripperJawParams]):
+    """closeGripperJaw command request model."""
+
+    commandType: closeGripperJawCommandType = "robot/closeGripperJaw"
+    params: closeGripperJawParams
+
+    _CommandCls: Type[closeGripperJaw] = closeGripperJaw

api/src/opentrons/protocol_engine/commands/robot/open_gripper_jaw.py

@@ -0,0 +1,77 @@
+"""Command models for opening a gripper jaw."""
+from __future__ import annotations
+from typing import Literal, Type, Optional
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.resources import ensure_ot3_hardware
+
+from pydantic import BaseModel
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+from opentrons.protocol_engine.errors.error_occurrence import ErrorOccurrence
+
+
+openGripperJawCommandType = Literal["robot/openGripperJaw"]
+
+
+class openGripperJawParams(BaseModel):
+    """Payload required to release a gripper."""
+
+    pass
+
+
+class openGripperJawResult(BaseModel):
+    """Result data from the execution of a openGripperJaw command."""
+
+    pass
+
+
+class openGripperJawImplementation(
+    AbstractCommandImpl[openGripperJawParams, SuccessData[openGripperJawResult]]
+):
+    """openGripperJaw command implementation."""
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        **kwargs: object,
+    ) -> None:
+        self._hardware_api = hardware_api
+
+    async def execute(
+        self, params: openGripperJawParams
+    ) -> SuccessData[openGripperJawResult]:
+        """Release the gripper."""
+        ot3_hardware_api = ensure_ot3_hardware(self._hardware_api)
+
+        await ot3_hardware_api.home_gripper_jaw()
+        return SuccessData(
+            public=openGripperJawResult(),
+        )
+
+
+class openGripperJaw(
+    BaseCommand[openGripperJawParams, openGripperJawResult, ErrorOccurrence]
+):
+    """openGripperJaw command model."""
+
+    commandType: openGripperJawCommandType = "robot/openGripperJaw"
+    params: openGripperJawParams
+    result: Optional[openGripperJawResult]
+
+    _ImplementationCls: Type[
+        openGripperJawImplementation
+    ] = openGripperJawImplementation
+
+
+class openGripperJawCreate(BaseCommandCreate[openGripperJawParams]):
+    """openGripperJaw command request model."""
+
+    commandType: openGripperJawCommandType = "robot/openGripperJaw"
+    params: openGripperJawParams
+
+    _CommandCls: Type[openGripperJaw] = openGripperJaw

api/tests/opentrons/protocol_engine/commands/robot/test_close_gripper_jaw.py

@@ -0,0 +1,28 @@
+"""Test robot.open-gripper-jaw commands."""
+from decoy import Decoy
+
+from opentrons.hardware_control import OT3HardwareControlAPI
+
+from opentrons.protocol_engine.commands.command import SuccessData
+from opentrons.protocol_engine.commands.robot.close_gripper_jaw import (
+    closeGripperJawParams,
+    closeGripperJawResult,
+    closeGripperJawImplementation,
+)
+
+
+async def test_close_gripper_jaw_implementation(
+    decoy: Decoy,
+    ot3_hardware_api: OT3HardwareControlAPI,
+) -> None:
+    """Test the `robot.closeGripperJaw` implementation."""
+    subject = closeGripperJawImplementation(
+        hardware_api=ot3_hardware_api,
+    )
+
+    params = closeGripperJawParams(force=10)
+
+    result = await subject.execute(params=params)
+
+    assert result == SuccessData(public=closeGripperJawResult())
+    decoy.verify(await ot3_hardware_api.grip(force_newtons=10))

api/tests/opentrons/protocol_engine/commands/robot/test_open_gripper_jaw.py

@@ -0,0 +1,28 @@
+"""Test robot.open-gripper-jaw commands."""
+from decoy import Decoy
+
+from opentrons.hardware_control import OT3HardwareControlAPI
+
+from opentrons.protocol_engine.commands.command import SuccessData
+from opentrons.protocol_engine.commands.robot.open_gripper_jaw import (
+    openGripperJawParams,
+    openGripperJawResult,
+    openGripperJawImplementation,
+)
+
+
+async def test_open_gripper_jaw_implementation(
+    decoy: Decoy,
+    ot3_hardware_api: OT3HardwareControlAPI,
+) -> None:
+    """Test the `robot.openGripperJaw` implementation."""
+    subject = openGripperJawImplementation(
+        hardware_api=ot3_hardware_api,
+    )
+
+    params = openGripperJawParams()
+
+    result = await subject.execute(params=params)
+
+    assert result == SuccessData(public=openGripperJawResult())
+    decoy.verify(await ot3_hardware_api.home_gripper_jaw())