fix(api, app): thermocycler hold time on API v2.14 (#12814)

* added holdTimeSeconds param to TC setTargetBlockTemperature, wired up to TC module context in API
* updated setTargetBlockTemperature in v7 schema
* updated app run log command text for setTargetBlockTemperature & waitForBlockTemperature
---------

Co-authored-by: Brian Cooper <[email protected]>

Author: sanni-t

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

@@ -225,7 +225,10 @@ def set_target_block_temperature(
     ) -> None:
         """Set the target temperature for the well block, in °C."""
         self._engine_client.thermocycler_set_target_block_temperature(
-            module_id=self.module_id, celsius=celsius, block_max_volume=block_max_volume
+            module_id=self.module_id,
+            celsius=celsius,
+            block_max_volume=block_max_volume,
+            hold_time_seconds=hold_time_seconds,
         )
 
     def wait_for_block_temperature(self) -> None:

api/src/opentrons/protocol_engine/clients/sync_client.py

@@ -465,12 +465,19 @@ def thermocycler_set_target_lid_temperature(
         return cast(commands.thermocycler.SetTargetLidTemperatureResult, result)
 
     def thermocycler_set_target_block_temperature(
-        self, module_id: str, celsius: float, block_max_volume: Optional[float]
+        self,
+        module_id: str,
+        celsius: float,
+        block_max_volume: Optional[float],
+        hold_time_seconds: Optional[float],
     ) -> commands.thermocycler.SetTargetBlockTemperatureResult:
         """Execute a `thermocycler/setTargetLidTemperature` command and return the result."""
         request = commands.thermocycler.SetTargetBlockTemperatureCreate(
             params=commands.thermocycler.SetTargetBlockTemperatureParams(
-                moduleId=module_id, celsius=celsius, blockMaxVolumeUl=block_max_volume
+                moduleId=module_id,
+                celsius=celsius,
+                blockMaxVolumeUl=block_max_volume,
+                holdTimeSeconds=hold_time_seconds,
             )
         )
         result = self._transport.execute_command(request=request)

api/src/opentrons/protocol_engine/commands/thermocycler/set_target_block_temperature.py

@@ -25,6 +25,12 @@ class SetTargetBlockTemperatureParams(BaseModel):
         description="Amount of liquid in uL of the most-full well"
         " in labware loaded onto the thermocycler.",
     )
+    holdTimeSeconds: Optional[float] = Field(
+        None,
+        description="Amount of time, in seconds, to hold the temperature for."
+        " If specified, a waitForBlockTemperature command will block until"
+        " the given hold time has elapsed.",
+    )
 
 
 class SetTargetBlockTemperatureResult(BaseModel):
@@ -71,13 +77,19 @@ async def execute(
             )
         else:
             target_volume = None
+        hold_time: Optional[float]
+        if params.holdTimeSeconds is not None:
+            hold_time = thermocycler_state.validate_hold_time(params.holdTimeSeconds)
+        else:
+            hold_time = None
+
         thermocycler_hardware = self._equipment.get_module_hardware_api(
             thermocycler_state.module_id
         )
 
         if thermocycler_hardware is not None:
             await thermocycler_hardware.set_target_block_temperature(
-                target_temperature, volume=target_volume
+                target_temperature, volume=target_volume, hold_time_seconds=hold_time
             )
 
         return SetTargetBlockTemperatureResult(

api/src/opentrons/protocol_engine/errors/__init__.py

@@ -39,6 +39,7 @@
     InvalidTargetSpeedError,
     InvalidTargetTemperatureError,
     InvalidBlockVolumeError,
+    InvalidHoldTimeError,
     CannotPerformModuleAction,
     PauseNotAllowedError,
     ProtocolCommandFailedError,
@@ -90,6 +91,7 @@
     "InvalidTargetTemperatureError",
     "InvalidTargetSpeedError",
     "InvalidBlockVolumeError",
+    "InvalidHoldTimeError",
     "CannotPerformModuleAction",
     "PauseNotAllowedError",
     "ProtocolCommandFailedError",

api/src/opentrons/protocol_engine/errors/exceptions.py

@@ -180,6 +180,10 @@ class InvalidBlockVolumeError(ProtocolEngineError):
     """An error raised when attempting to set an invalid block max volume."""
 
 
+class InvalidHoldTimeError(ProtocolEngineError):
+    """An error raised when attempting to set an invalid temperature hold time."""
+
+
 class InvalidTargetSpeedError(ProtocolEngineError):
     """An error raised when attempting to set an invalid target speed."""
 

api/src/opentrons/protocol_engine/state/module_substates/thermocycler_module_substate.py

@@ -6,6 +6,7 @@
     InvalidTargetTemperatureError,
     InvalidBlockVolumeError,
     NoTargetTemperatureSetError,
+    InvalidHoldTimeError,
 )
 
 # TODO(mc, 2022-04-25): move to module definition
@@ -79,6 +80,26 @@ def validate_max_block_volume(volume: float) -> float:
             f" {BLOCK_VOL_MIN} and {BLOCK_VOL_MAX}, but got {volume}."
         )
 
+    @staticmethod
+    def validate_hold_time(hold_time: float) -> float:
+        """Validate a given temperature hold time.
+
+        Args:
+            hold_time: The requested hold time in seconds.
+
+        Raises:
+            InvalidHoldTimeError: The given time is invalid
+
+        Returns:
+            The validated time in seconds
+        """
+        if hold_time < 0:
+            raise InvalidHoldTimeError(
+                "Thermocycler target temperature hold time must be a positive number,"
+                f" but received {hold_time}."
+            )
+        return hold_time
+
     @staticmethod
     def validate_target_lid_temperature(celsius: float) -> float:
         """Validate a given target lid temperature.

api/tests/opentrons/protocol_api/core/engine/test_thermocycler_core.py

@@ -94,6 +94,7 @@ def test_set_target_block_temperature(
             module_id="1234",
             celsius=42.0,
             block_max_volume=3.4,
+            hold_time_seconds=1.2,
         ),
         times=1,
     )

api/tests/opentrons/protocol_engine/clients/test_sync_client.py

@@ -637,15 +637,21 @@ def test_thermocycler_set_target_block_temperature(
     """It should execute a Thermocycler's set target block temperature command."""
     request = commands.thermocycler.SetTargetBlockTemperatureCreate(
         params=commands.thermocycler.SetTargetBlockTemperatureParams(
-            moduleId="module-id", celsius=45.6, blockMaxVolumeUl=12.3
+            moduleId="module-id",
+            celsius=45.6,
+            blockMaxVolumeUl=12.3,
+            holdTimeSeconds=123.4,
         )
     )
     response = commands.thermocycler.SetTargetBlockTemperatureResult(
         targetBlockTemperature=45.6
     )
     decoy.when(transport.execute_command(request=request)).then_return(response)
     result = subject.thermocycler_set_target_block_temperature(
-        module_id="module-id", celsius=45.6, block_max_volume=12.3
+        module_id="module-id",
+        celsius=45.6,
+        block_max_volume=12.3,
+        hold_time_seconds=123.4,
     )
 
     assert result == response

api/tests/opentrons/protocol_engine/commands/thermocycler/test_set_target_block_temperature.py

@@ -27,6 +27,7 @@ async def test_set_target_block_temperature(
         moduleId="input-thermocycler-id",
         celsius=12.3,
         blockMaxVolumeUl=50.2,
+        holdTimeSeconds=123456,
     )
     expected_result = tc_commands.SetTargetBlockTemperatureResult(
         targetBlockTemperature=45.6
@@ -43,14 +44,15 @@ async def test_set_target_block_temperature(
         ThermocyclerModuleId("thermocycler-id")
     )
 
-    # Stub temperature validation from hs module view
+    # Stub temperature validation from TC module view
     decoy.when(tc_module_substate.validate_target_block_temperature(12.3)).then_return(
         45.6
     )
 
-    # Stub volume validation from hs module view
+    # Stub volume validation from TC module view
     decoy.when(tc_module_substate.validate_max_block_volume(50.2)).then_return(77.6)
-
+    # Stub hold time validation from TC module view
+    decoy.when(tc_module_substate.validate_hold_time(123456)).then_return(654321)
     # Get attached hardware modules
     decoy.when(
         equipment.get_module_hardware_api(ThermocyclerModuleId("thermocycler-id"))
@@ -59,7 +61,9 @@ async def test_set_target_block_temperature(
     result = await subject.execute(data)
 
     decoy.verify(
-        await tc_hardware.set_target_block_temperature(celsius=45.6, volume=77.6),
+        await tc_hardware.set_target_block_temperature(
+            celsius=45.6, volume=77.6, hold_time_seconds=654321
+        ),
         times=1,
     )
     assert result == expected_result

api/tests/opentrons/protocol_engine/state/test_module_view.py

@@ -1393,6 +1393,38 @@ def test_thermocycler_validate_target_block_temperature(
     assert result == input_temperature
 
 
+@pytest.mark.parametrize(
+    argnames=["input_time", "validated_time"],
+    argvalues=[(0.0, 0.0), (0.123, 0.123), (123.456, 123.456), (1234567, 1234567)],
+)
+def test_thermocycler_validate_hold_time(
+    module_view_with_thermocycler: ModuleView,
+    input_time: float,
+    validated_time: float,
+) -> None:
+    """It should return a valid hold time."""
+    subject = module_view_with_thermocycler.get_thermocycler_module_substate(
+        "module-id"
+    )
+    result = subject.validate_hold_time(input_time)
+
+    assert result == validated_time
+
+
+@pytest.mark.parametrize("input_time", [-0.1, -123])
+def test_thermocycler_validate_hold_time_raises(
+    module_view_with_thermocycler: ModuleView,
+    input_time: float,
+) -> None:
+    """It should raise on invalid hold time."""
+    subject = module_view_with_thermocycler.get_thermocycler_module_substate(
+        "module-id"
+    )
+
+    with pytest.raises(errors.InvalidHoldTimeError):
+        subject.validate_hold_time(input_time)
+
+
 @pytest.mark.parametrize("input_temperature", [-0.001, 99.001])
 def test_thermocycler_validate_target_block_temperature_raises(
     module_view_with_thermocycler: ModuleView,