opentrons 8.8.0a6__tar.gz → 8.8.0a11__tar.gz

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opentrons
-Version: 8.8.0a6
+Version: 8.8.0a11
 Summary: The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.
 Project-URL: opentrons.com, https://www.opentrons.com
 Project-URL: Source Code On Github, https://github.com/Opentrons/opentrons/tree/edge/api
@@ -24,7 +24,7 @@ Requires-Dist: click<9,>=8.0.0
 Requires-Dist: importlib-metadata>=1.0; python_version < '3.8'
 Requires-Dist: jsonschema<4.18.0,>=3.0.1
 Requires-Dist: numpy<2,>=1.20.0
-Requires-Dist: opentrons-shared-data==8.8.0a6
+Requires-Dist: opentrons-shared-data==8.8.0a11
 Requires-Dist: packaging>=21.0
 Requires-Dist: pydantic-settings<3,>=2
 Requires-Dist: pydantic<3,>=2.0.0
@@ -32,6 +32,6 @@ Requires-Dist: pyserial>=3.5
 Requires-Dist: pyusb==1.2.1
 Requires-Dist: typing-extensions<5,>=4.0.0
 Provides-Extra: flex-hardware
-Requires-Dist: opentrons-hardware[flex]==8.8.0a6; extra == 'flex-hardware'
+Requires-Dist: opentrons-hardware[flex]==8.8.0a11; extra == 'flex-hardware'
 Provides-Extra: ot2-hardware
-Requires-Dist: opentrons-hardware==8.8.0a6; extra == 'ot2-hardware'
+Requires-Dist: opentrons-hardware==8.8.0a11; extra == 'ot2-hardware'

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '8.8.0a6'
-__version_tuple__ = version_tuple = (8, 8, 0, 'a6')
+__version__ = version = '8.8.0a11'
+__version_tuple__ = version_tuple = (8, 8, 0, 'a11')
 
 __commit_id__ = commit_id = None

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/drivers/asyncio/communication/serial_connection.py

@@ -12,6 +12,8 @@ from .errors import (
     ErrorResponse,
     BaseErrorCode,
     DefaultErrorCodes,
+    UnhandledGcode,
+    GCodeCacheFull,
 )
 from .async_serial import AsyncSerial
 
@@ -555,6 +557,23 @@ class AsyncResponseSerialConnection(SerialConnection):
                 # A read timeout, end
                 yield "empty-unknown", data
 
+    def _raise_on_parser_error(self, data: str, response: bytes) -> None:
+        """Raise an exception if this response contains an error from the gcode parser on the module.
+
+        This has to be treated specially because multiack commands won't get multiple acks if the command
+        fails at the parse stage. The errors handled here should be kept in sync with the module gcode
+        parse code.
+        """
+        try:
+            str_response = self.process_raw_response(
+                command=data, response=response.replace(self._ack, b"").decode()
+            )
+            self.raise_on_error(response=str_response, request=data)
+        except (UnhandledGcode, GCodeCacheFull):
+            raise
+        except Exception:
+            pass
+
     async def _send_one_retry(self, data: str, acks: int) -> list[str]:
         data_encode = data.encode("utf-8")
         log.debug(f"{self._name}: Write -> {data_encode!r}")
@@ -567,8 +586,10 @@ class AsyncResponseSerialConnection(SerialConnection):
         async for response_type, response in self._consume_responses(acks):
             if response_type == "error":
                 async_errors.append(response)
+                self._raise_on_parser_error(data, response)
             elif response_type == "response":
                 command_acks.append(response)
+                self._raise_on_parser_error(data, response)
             else:
                 break
 

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/hardware_control/ot3api.py

@@ -52,6 +52,7 @@ from opentrons_shared_data.errors.exceptions import (
     InvalidActuator,
     FirmwareUpdateFailedError,
     PipetteLiquidNotFoundError,
+    PipetteOverpressureError,
 )
 
 from .util import use_or_initialize_loop, check_motion_bounds
@@ -3088,6 +3089,7 @@ class OT3API(
         volume: float,
         rate: float = 1.0,
         movement_delay: Optional[float] = None,
+        end_critical_point: Optional[CriticalPoint] = None,
     ) -> None:
         """
         Aspirate a volume of liquid (in microliters/uL) while moving the z axis synchronously.
@@ -3107,7 +3109,7 @@ class OT3API(
         end_position = target_position_from_absolute(
             realmount,
             end_point,
-            self.critical_point_for,
+            partial(self.critical_point_for, cp_override=end_critical_point),
             top_types.Point(*self._config.left_mount_offset),
             top_types.Point(*self._config.right_mount_offset),
             top_types.Point(*self._config.gripper_mount_offset),
@@ -3122,6 +3124,9 @@ class OT3API(
         delay: Optional[Tuple[List[Axis], float]] = None
         if movement_delay is not None:
             delay = ([Axis.X, Axis.Y, Axis.Z_L, Axis.Z_R], movement_delay)
+        self._log.info(
+            f"aspirate_while_tracking: end at {end_point} {end_critical_point}, machine pos {end_position}, with plunger {target_pos}, delay {delay}"
+        )
         try:
             await self._backend.set_active_current(
                 {aspirate_spec.axis: aspirate_spec.current}
@@ -3136,6 +3141,11 @@ class OT3API(
                     home_flagged_axes=False,
                     delay=delay,
                 )
+        except PipetteOverpressureError:
+            self._log.exception("Aspirate failed with overpressure")
+            # refresh positions during an over pressure here so we know where the gantry stopped.
+            await self.refresh_positions()
+            raise
         except Exception:
             self._log.exception("Aspirate failed")
             aspirate_spec.instr.set_current_volume(0)
@@ -3152,6 +3162,7 @@ class OT3API(
         rate: float = 1.0,
         is_full_dispense: bool = False,
         movement_delay: Optional[float] = None,
+        end_critical_point: Optional[CriticalPoint] = None,
     ) -> None:
         """
         Dispense a volume of liquid (in microliters/uL) while moving the z axis synchronously.
@@ -3171,7 +3182,7 @@ class OT3API(
         end_position = target_position_from_absolute(
             realmount,
             end_point,
-            self.critical_point_for,
+            partial(self.critical_point_for, cp_override=end_critical_point),
             top_types.Point(*self._config.left_mount_offset),
             top_types.Point(*self._config.right_mount_offset),
             top_types.Point(*self._config.gripper_mount_offset),
@@ -3186,7 +3197,9 @@ class OT3API(
         delay: Optional[Tuple[List[Axis], float]] = None
         if movement_delay is not None:
             delay = ([Axis.X, Axis.Y, Axis.Z_L, Axis.Z_R], movement_delay)
-
+        self._log.info(
+            f"dispense_while_tracking: end at {end_point} {end_critical_point}, machine pos {end_position}, with plunger {target_pos}, delay {delay}"
+        )
         try:
             await self._backend.set_active_current(
                 {dispense_spec.axis: dispense_spec.current}
@@ -3201,6 +3214,11 @@ class OT3API(
                     home_flagged_axes=False,
                     delay=delay,
                 )
+        except PipetteOverpressureError:
+            self._log.exception("Aspirate failed with overpressure")
+            # refresh positions during an over pressure here so we know where the gantry stopped.
+            await self.refresh_positions()
+            raise
         except Exception:
             self._log.exception("dispense failed")
             dispense_spec.instr.set_current_volume(0)

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/hardware_control/protocols/liquid_handler.py

@@ -129,15 +129,17 @@ class LiquidHandler(
         volume: float,
         flow_rate: float = 1.0,
         movement_delay: Optional[float] = None,
+        end_critical_point: Optional[CriticalPoint] = None,
     ) -> None:
         """
         Aspirate a volume of liquid (in microliters/uL) while moving the z axis synchronously.
 
         :param mount: A robot mount that the instrument is on.
-        :param z_distance: The distance the z axis will move during apsiration.
+        :param end_point: The deck coordinate point to move the tip to during the aspirate.
         :param volume: The volume of liquid to be aspirated.
         :param flow_rate: The flow rate to aspirate with.
         :param movement_delay: Time to wait after the pipette starts aspirating before x/y/z movement.
+        :param end_critical_point: The critical point for the end_point position.
         """
         ...
 
@@ -172,15 +174,17 @@ class LiquidHandler(
         flow_rate: float = 1.0,
         is_full_dispense: bool = False,
         movement_delay: Optional[float] = None,
+        end_critical_point: Optional[CriticalPoint] = None,
     ) -> None:
         """
         Dispense a volume of liquid (in microliters/uL) while moving the z axis synchronously.
 
         :param mount: A robot mount that the instrument is on.
-        :param z_distance: The distance the z axis will move during dispensing.
+        :param end_point: The deck coordinate point to move the tip to during the dispense.
         :param volume: The volume of liquid to be dispensed.
         :param flow_rate: The flow rate to dispense with.
         :param movement_delay: Time to wait after the pipette starts dispensing before x/y/z movement.
+        :param end_critical_point: The critical point for the end_point position.
         """
         ...
 

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/protocol_api/core/engine/pipette_movement_conflict.py

@@ -1,8 +1,8 @@
 """A Protocol-Engine-friendly wrapper for opentrons.motion_planning.deck_conflict."""
+
 from __future__ import annotations
 import logging
 from typing import (
-    Optional,
     Tuple,
     Union,
     List,
@@ -12,7 +12,6 @@ from opentrons_shared_data.errors.exceptions import MotionPlanningFailureError
 from opentrons.protocol_engine.errors import LocationIsStagingSlotError
 from opentrons_shared_data.module import FLEX_TC_LID_COLLISION_ZONE
 
-from opentrons.hardware_control import CriticalPoint
 from opentrons.motion_planning import adjacent_slots_getters
 
 from opentrons.protocol_engine import (
@@ -101,7 +100,9 @@ def check_safe_for_pipette_movement(  # noqa: C901
     )
     primary_nozzle = engine_state.pipettes.get_primary_nozzle(pipette_id)
 
-    destination_cp = _get_critical_point_to_use(engine_state, labware_id)
+    destination_cp = engine_state.motion.get_critical_point_for_wells_in_labware(
+        labware_id
+    )
     pipette_bounds_at_well_location = (
         engine_state.pipettes.get_pipette_bounds_at_specified_move_to_position(
             pipette_id=pipette_id,
@@ -189,21 +190,6 @@ def check_safe_for_pipette_movement(  # noqa: C901
             )
 
 
-def _get_critical_point_to_use(
-    engine_state: StateView, labware_id: str
-) -> Optional[CriticalPoint]:
-    """Return the critical point to use when accessing the given labware."""
-    # TODO (spp, 2024-09-17): looks like Y_CENTER of column is the same as its XY_CENTER.
-    #   I'm using this if-else ladder to be consistent with what we do in
-    #   `MotionPlanning.get_movement_waypoints_to_well()`.
-    #   We should probably use only XY_CENTER in both places.
-    if engine_state.labware.get_should_center_column_on_target_well(labware_id):
-        return CriticalPoint.Y_CENTER
-    elif engine_state.labware.get_should_center_pipette_on_target_well(labware_id):
-        return CriticalPoint.XY_CENTER
-    return None
-
-
 def _slot_has_potential_colliding_object(
     engine_state: StateView,
     pipette_bounds: Tuple[Point, Point, Point, Point],

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/protocol_api/instrument_context.py

@@ -242,14 +242,14 @@ class InstrumentContext(publisher.CommandPublisher):
         :param flow_rate: The absolute flow rate in µL/s. If ``flow_rate`` is specified,
                           ``rate`` must not be set.
         :type flow_rate: float
-        :param end_location: Tells the robot to move between location and end_location
-            while aspirating liquid. When this argument is used the location and
-            end_location must both be :py:class:`.Location`.
+        :param end_location: Tells the robot to move from the specified ``location`` to the specified ``end_location``
+            while aspirating liquid. When this argument is used, the ``location`` and
+            ``end_location`` must both be a :py:class:`.Location`.
         :type end_location: :py:class:`.Location`
-        :param movement_delay: Delay the x/y/z movement during a dynamic aspirate.
-            This option is only valid when using end_location. When this argument
-            is used, the x/y/z movement will wait movement_delay seconds after the pipette
-            starts to aspirate before moving. This may help when dispensing very viscous liquids
+        :param movement_delay: Time in seconds to delay after the pipette starts aspirating and before it begins moving from  ``location`` to ``end_location``.
+            This option is only valid when using ``end_location``. When this argument
+            is used, the pipette will wait the specified time after the pipette
+            starts to aspirate before moving. This may help when aspirating very viscous liquids
             that need to build up some pressure before liquid starts to flow.
         :type movement_delay: float
         :returns: This instance.
@@ -263,6 +263,8 @@ class InstrumentContext(publisher.CommandPublisher):
 
         .. versionchanged:: 2.24
             Added the ``flow_rate`` parameter.
+        .. versionchanged:: 2.27
+            Added the ``end_location`` and ``movement_delay`` parameters.
         """
         if flow_rate is not None:
             if self.api_version < APIVersion(2, 24):
@@ -479,13 +481,13 @@ class InstrumentContext(publisher.CommandPublisher):
                           ``rate`` must not be set.
         :type flow_rate: float
 
-        :param end_location: Tells the robot to move between location and end_location
-            while dispensing liquid held in the pipette. When this argument is used
-            the location and end_location must both be a :py:class:`.Location`.
+        :param end_location: Tells the robot to move from the specified ``location`` to the specified ``end_location``
+            while dispensing liquid held in the pipette. When this argument is used,
+            the ``location`` and ``end_location`` must both be a :py:class:`.Location`.
         :type end_location: :py:class:`.Location`
-        :param movement_delay: Delay the x/y/z movement during a dynamic dispense.
-            This option is only valid when using end_location. When this argument
-            is used, the x/y/z movement will wait movement_delay seconds after the pipette
+        :param movement_delay: Time in seconds to delay after the pipette starts dispensing and before it begins moving from  ``location`` to ``end_location``.
+            This option is only valid when using ``end_location``. When this argument
+            is used, the pipette will wait the specified time after the pipette
             starts to dispense before moving. This may help when dispensing very viscous liquids
             that need to build up some pressure before liquid starts to flow.
         :type movement_delay: float
@@ -510,6 +512,9 @@ class InstrumentContext(publisher.CommandPublisher):
         .. versionchanged:: 2.24
             ``location`` is no longer required if the pipette just moved to, dispensed, or blew out
             into a trash bin or waste chute.
+
+        .. versionchanged:: 2.27
+            Added the ``end_location`` and ``movement_delay`` parameters.
         """
         if self.api_version < APIVersion(2, 15) and push_out:
             raise APIVersionError(
@@ -849,7 +854,7 @@ class InstrumentContext(publisher.CommandPublisher):
         """
         Mix a volume of liquid by repeatedly aspirating and dispensing it in a multiple locations.
 
-        See :ref:`dynamic_mix` for examples.
+        See :ref:`dynamic-mix` for examples.
 
         :param repetitions: Number of times to mix (default is 1).
         :param volume: The volume to mix, measured in µL. If unspecified, defaults
@@ -860,13 +865,13 @@ class InstrumentContext(publisher.CommandPublisher):
                        it will behave the same as a volume of ``None``/unspecified: mix
                        the full working volume of the pipette. On API levels at or above 2.16,
                        no liquid will be mixed.
-        :param aspirate_start_location: The :py:class:`~.types.Location` where the pipette will aspirate from.
-        :param aspirate_end_location: The :py:class:`~.types.Location` If this argument is supplied
-                    the pipette will move between aspirate_start_location and aspirate_end_location
+        :param aspirate_start_location: The :py:class:`~.types.Location` where the pipette will start aspirating from.
+        :param aspirate_end_location: A :py:class:`~.types.Location`. If specified,
+                    the pipette will move between the ``aspirate_start_location`` and the ``aspirate_end_location``
                     while performing the aspirate.
-        :param dispense_start_location: The :py:class:`~.types.Location` where the pipette will dispense to.
-        :param dispense_end_location: The :py:class:`~.types.Location` If this argument is supplied
-                    the pipette will move between dispense_start_location and dispense_end_location
+        :param dispense_start_location: The :py:class:`~.types.Location` where the pipette will start dispensing to.
+        :param dispense_end_location: A :py:class:`~.types.Location`. If specified,
+                    the pipette will move between the ``dispense_start_location`` and the ``dispense_end_location``
                     while performing the dispense.
         :param rate: How quickly the pipette aspirates and dispenses liquid while
                      mixing. The aspiration flow rate is calculated as ``rate``
@@ -884,10 +889,10 @@ class InstrumentContext(publisher.CommandPublisher):
                                pipette will not push out after earlier repetitions. If
                                not specified or ``None``, the pipette will push out the
                                default non-zero amount. See :ref:`push-out-dispense`.
-        :param movement_delay: Delay the x/y/z movement during a dynamic mix.
-            This option is only valid when using aspirate_end_location or dispense_end_location.
-            When this argument is used, the x/y/z movement will wait movement_delay seconds
-            after the pipette starts to aspirate/dispense before moving. This may help when mixing
+        :param movement_delay: Time in seconds to delay after the pipette starts aspirating or dispensing and before it begins moving from the ``aspirate_start_location`` or ``dispense_start_location`` to the ``aspirate_end_location`` or ``dispense_end_location``.
+            This option is only valid when using ``aspirate_end_location`` or ``dispense_end_location``.
+            When this argument is used, the pipette will wait the specified time
+            after the pipette starts to aspirate or dispense before moving. This may help when mixing
             very viscous liquids that need to build up some pressure before liquid starts to flow.
         :type movement_delay: float
         :raises: ``UnexpectedTipRemovalError`` -- If no tip is attached to the pipette.
@@ -895,10 +900,7 @@ class InstrumentContext(publisher.CommandPublisher):
 
         .. note::
 
-            All the arguments of ``mix`` are optional. However, if you omit one of them,
-            all subsequent arguments must be passed as keyword arguments. For instance,
-            ``pipette.mix(1, location=wellplate['A1'])`` is a valid call, but
-            ``pipette.mix(1, wellplate['A1'])`` is not.
+            The ``aspirate_start_location`` and ``dispense_start_location`` arguments of ``dynamic_mix`` are required.
 
         """
         _log.debug(
@@ -2267,9 +2269,11 @@ class InstrumentContext(publisher.CommandPublisher):
                 trash_location=transfer_args.trash_location,
                 return_tip=return_tip,
                 keep_last_tip=verified_keep_last_tip,
-                tips=[tip._core for tip in transfer_args.tips]
-                if transfer_args.tips is not None
-                else None,
+                tips=(
+                    [tip._core for tip in transfer_args.tips]
+                    if transfer_args.tips is not None
+                    else None
+                ),
             )
 
         return self
@@ -2441,9 +2445,11 @@ class InstrumentContext(publisher.CommandPublisher):
                 trash_location=transfer_args.trash_location,
                 return_tip=return_tip,
                 keep_last_tip=verified_keep_last_tip,
-                tips=[tip._core for tip in transfer_args.tips]
-                if transfer_args.tips is not None
-                else None,
+                tips=(
+                    [tip._core for tip in transfer_args.tips]
+                    if transfer_args.tips is not None
+                    else None
+                ),
             )
 
         return self
@@ -2615,9 +2621,11 @@ class InstrumentContext(publisher.CommandPublisher):
                 trash_location=transfer_args.trash_location,
                 return_tip=return_tip,
                 keep_last_tip=verified_keep_last_tip,
-                tips=[tip._core for tip in transfer_args.tips]
-                if transfer_args.tips is not None
-                else None,
+                tips=(
+                    [tip._core for tip in transfer_args.tips]
+                    if transfer_args.tips is not None
+                    else None
+                ),
             )
 
         return self

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/protocol_api/labware.py

@@ -822,8 +822,8 @@ class Labware:
     def set_offset(self, x: float, y: float, z: float) -> None:
         """Set the labware's position offset.
 
-        The offset is an x, y, z vector in deck coordinates
-        (see :ref:`protocol-api-deck-coords`).
+        An offset of `(x=0, y=0, z=0)` means the labware's uncalibrated position before
+        any offset from Labware Position Check is applied.
 
         How the motion system applies the offset depends on the API level of the protocol.
 
@@ -882,6 +882,9 @@ class Labware:
     def calibrated_offset(self) -> Point:
         """The front-left-bottom corner of the labware, including its labware offset.
 
+        The offset is an x, y, z vector in deck coordinates
+        (see :ref:`protocol-api-deck-coords`).
+
         When running a protocol in the Opentrons App or on the touchscreen, Labware
         Position Check sets the labware offset.
         """

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/protocol_api/module_contexts.py

@@ -456,13 +456,14 @@ class TemperatureModuleContext(ModuleContext):
     @publish(command=cmds.tempdeck_set_temp)
     @requires_version(2, 3)
     def start_set_temperature(self, celsius: float) -> Task:
-        """Set the target temperature without waiting for the target to be hit.
+        """Sets the Temperature Module's target temperature and returns immediately without waiting for the module to reach the target. Allows the protocol to proceed while the Temperature Module heats.
 
         .. versionchanged:: 2.27
-            Returns a task object that represents concurrent preheating.
-            Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the preheat to complete.
+            Returns a :py:class:`Task` object that represents concurrent heating.
+            Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the module to finish heating.
+
+        In API version 2.26 or below, this function returns ``None``.
 
-        On version 2.26 or below, this function returns ``None``.
         :param celsius: A value between 4 and 95, representing the target temperature in °C.
         """
         task = self._core.set_target_temperature(celsius)
@@ -715,9 +716,9 @@ class ThermocyclerContext(ModuleContext):
         ramp_rate: Optional[float] = None,
         block_max_volume: Optional[float] = None,
     ) -> Task:
-        """Starts to set the target temperature for the well block, in °C.
+        """Sets the target temperature for the Thermocycler Module's well block, in °C.
 
-        Returns a task object that represents concurrent preheating.
+        Returns a :py:class:`Task` object that represents concurrent heating.
         Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for
         the preheat to complete.
 
@@ -726,10 +727,10 @@ class ThermocyclerContext(ModuleContext):
         :param block_max_volume: The greatest volume of liquid contained in any
                                  individual well of the loaded labware, in µL.
                                  If not specified, the default is 25 µL.
-                                 After API version 2.27 it will attempt to use
-                                 the liquid tracking of the labware first and
-                                 then fall back to the 25 if there is no probed
-                                 or loaded liquid.
+                                 In API version 2.27 and newer, the API will first attempt to use
+                                 the liquid tracking in labware,
+                                 then default to 25 µL if the protocol lacks probed
+                                 or loaded liquid information.
         """
 
         if block_max_volume is None:
@@ -746,10 +747,6 @@ class ThermocyclerContext(ModuleContext):
     def set_lid_temperature(self, temperature: float) -> None:
         """Set the target temperature for the heated lid, in °C.
 
-        Returns a task object that represents concurrent preheating.
-        Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for
-        the preheat to complete.
-
         :param temperature: A value between 37 and 110, representing the target
                             temperature in °C.
 
@@ -765,20 +762,14 @@ class ThermocyclerContext(ModuleContext):
     @publish(command=cmds.thermocycler_start_set_lid_temperature)
     @requires_version(2, 27)
     def start_set_lid_temperature(self, temperature: float) -> Task:
-        """Set the target temperature for the heated lid, in °C.
+        """Sets a target temperature to heat the Thermocycler Module's lid, in °C. Returns a :py:class:`Task` object that represents concurrent heating.
 
-        Returns a task object that represents concurrent preheating.
         Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for
-        the preheat to complete.
+        the lid to reach the target temperature.
 
         :param temperature: A value between 37 and 110, representing the target
                             temperature in °C.
 
-        .. note::
-
-            The Thermocycler will proceed to the next command immediately after
-            ``temperature`` is reached.
-
         """
         task = self._core.start_set_target_lid_temperature(celsius=temperature)
         return Task(api_version=self._api_version, core=task)
@@ -824,11 +815,10 @@ class ThermocyclerContext(ModuleContext):
         repetitions: int,
         block_max_volume: Optional[float] = None,
     ) -> Task:
-        """Start a Thermocycler profile and return a :py:class:`Task` representing its execution.
+        """Starts a defined Thermocycler Module profile and return a :py:class:`Task` representing its concurrent execution.
         Profile is defined as a cycle of ``steps``, for a given number of ``repetitions``.
 
-        Returns a task object that represents concurrent execution of the profile.
-        Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the preheat to complete.
+        Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the profile run to complete.
 
         :param steps: List of steps that make up a single cycle.
                       Each list item should be a dictionary that maps to the parameters
@@ -1104,17 +1094,17 @@ class HeaterShakerContext(ModuleContext):
         """Set target temperature and return immediately.
 
         Sets the Heater-Shaker's target temperature and returns immediately without
-        waiting for the target to be reached. Does not delay the protocol until
-        target temperature has reached.
+        waiting for the target to be reached. Allows the protocol to proceed while the module
+        reaches the target temperature.
         Use :py:meth:`~.HeaterShakerContext.wait_for_temperature` to delay
-        protocol execution for api levels below 2.27.
+        protocol execution for API levels below 2.27.
 
         .. versionchanged:: 2.25
             Removed the minimum temperature limit of 37 °C. Note that temperatures under ambient are
             not achievable.
         .. versionchanged:: 2.27
-            Returns a task object that represents concurrent preheating.
-            Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the preheat to complete.
+            Returns a :py:class:`Task` object that represents concurrent heating.
+            Pass the task object to :py:meth:`ProtocolContext.wait_for_tasks` to wait for the module to reach the target temperature.
 
         :param celsius: A value under 95, representing the target temperature in °C.
                         Values are automatically truncated to two decimal places,
@@ -1158,11 +1148,11 @@ class HeaterShakerContext(ModuleContext):
     @requires_version(2, 27)
     @publish(command=cmds.heater_shaker_set_shake_speed)
     def set_shake_speed(self, rpm: int) -> Task:
-        """Set a shake speed in rpm to run in the background.
+        """Sets the Heater-Shaker's shake speed in RPM and returns a :py:class:`Task` that represents concurrent shaking.
 
         .. note::
 
-            Before shaking, this command will retract the pipettes upward if they are parked adjacent to the Heater-Shaker.
+            Before shaking, this command retracts pipettes upward if they are adjacent to the Heater-Shaker Module.
 
         :param rpm: A value between 200 and 3000, representing the target shake speed in revolutions per minute.
         """

{opentrons-8.8.0a6 → opentrons-8.8.0a11}/src/opentrons/protocol_api/protocol_context.py

@@ -1289,7 +1289,7 @@ class ProtocolContext(CommandPublisher):
     def wait_for_tasks(self, tasks: list[Task]) -> None:
         """Wait for a list of tasks to complete before executing subsequent commands.
 
-        :param list Task: tasks: A list of Task objects to wait for.
+        :param list Task: tasks: A list of :py:class:`Task` objects to wait for.
 
         Task objects can be commands that are allowed to run concurrently.
         """
@@ -1299,7 +1299,7 @@ class ProtocolContext(CommandPublisher):
     @publish(command=cmds.create_timer)
     @requires_version(2, 27)
     def create_timer(self, seconds: float) -> Task:
-        """Create a timer task that runs in the background.
+        """Create a timer :py:class:`Task` that runs in the background.
 
         :param float seconds: The time to delay in seconds.
 
@@ -1833,17 +1833,15 @@ class ProtocolContext(CommandPublisher):
         brightness: Optional[float] = None,
         saturation: Optional[float] = None,
     ) -> None:
-        """Capture an image using the camera. Captured images get saved as a result of the protocol run.
-
-        :param home_before: Boolean to home the pipette before capturing an image.
-        :param filename: Filename to use when saving the captured image as a file.
-        :param resolution: Width/height tuple to determine the resolution to use when capturing an image.
-        :param zoom: Optional zoom level, with minimum/default of 1x zoom and maximum of 2x zoom.
-        :param contrast: Contrast level to be applied to an image, range is 0% to 100%.
-        :param brightness: Brightness level to be applied to an image, range is 0% to 100%.
-        :param saturation: Saturation level to be applied to an image, range is 0% to 100%.
-
-        .. versionadded:: 2.27
+        """Capture an image using the camera. Captured images are saved as during the protocol run.
+
+        :param home_before: If ``True``, homes the pipette before capturing an image.
+        :param filename: Custom name to use when saving the captured image as a file. The custom name is added as the beginning of the filename, followed by the robot and protocol name, a timestamp for the protocol run, the step number, and a timestamp for the command running when the image was captured.
+        :param resolution: Accepts a width and height (as a tuple) to determine the camera's resolution when capturing the image.
+        :param zoom: Zoom level the camera will use. Defaults to the minimum of 1x zoom (``1.0``) and has a maximum of 2x zoom (``2.0``).
+        :param contrast: The contrast level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (``0.0`` to ``100.0``).
+        :param brightness: The brightness level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (``0.0`` to ``100.0``).
+        :param saturation: The saturation level to be applied to the image. The acceptable range is from 0 to 100; provided as a percentage (``0.0`` to ``100.0``).
 
         """
         if home_before is True: