chore: mergeback_chore-release_8.4.0 into edge

.github/workflows/hardware-lint-test.yaml

@@ -41,7 +41,7 @@ jobs:
   lint-test:
     name: 'hardware package linting and tests'
     timeout-minutes: 20
-    runs-on: 'ubuntu-20.04'
+    runs-on: 'ubuntu-24.04'
     steps:
       - name: Checkout opentrons repo
         uses: 'actions/checkout@v4'

.github/workflows/hardware-testing-protocols.yaml

@@ -35,7 +35,7 @@ jobs:
   lint-test:
     name: 'hardware-testing protocols'
     timeout-minutes: 20
-    runs-on: 'ubuntu-20.04'
+    runs-on: 'ubuntu-24.04'
     steps:
       - name: Checkout opentrons repo
         uses: 'actions/checkout@v4'

.github/workflows/hardware-testing.yaml

@@ -40,7 +40,7 @@ jobs:
   lint-test:
     name: 'hardware--testing package linting and tests'
     timeout-minutes: 20
-    runs-on: 'ubuntu-20.04'
+    runs-on: 'ubuntu-24.04'
     steps:
       - name: Checkout opentrons repo
         uses: 'actions/checkout@v4'

api/docs/v2/conf.py

@@ -445,6 +445,7 @@
     ("py:class", r".*protocol_api\.config.*"),
     ("py:class", r".*opentrons_shared_data.*"),
     ("py:class", r".*protocol_api._parameters.Parameters.*"),
+    ("py:class", r".*protocol_api._liquid_properties.TransferProperties*"),
     ("py:class", r".*RobotContext"),  # shh it's a secret (for now)
     ("py:class", r".*FlexStackerContext"),  # ssh it's a secret (for now)
     (

api/docs/v2/new_protocol_api.rst

@@ -48,6 +48,9 @@ Wells and Liquids
 
 .. autoclass:: opentrons.protocol_api.Liquid
 
+.. autoclass:: opentrons.protocol_api.LiquidClass
+   :members:
+
 .. _protocol-api-modules:
 
 Modules

api/src/opentrons/hardware_control/backends/subsystem_manager.py

@@ -58,7 +58,7 @@ class SubsystemManager:
     _expected_core_targets: Set[FirmwareTarget]
     _present_tools: tools.types.ToolSummary
     _tool_task_condition: asyncio.Condition
-    _tool_task_state: Union[bool, Exception]
+    _tool_task_state: Union[bool, BaseException]
     _updates_required: Dict[FirmwareTarget, FirmwareUpdateRequirements]
     _updates_ongoing: Dict[SubSystem, UpdateStatus]
     _update_bag: FirmwareUpdate
@@ -370,7 +370,8 @@ def update_state(status: UpdateStatus) -> None:
     async def _tool_detection_task_main(self) -> None:
         try:
             await self._tool_detection_task_protected()
-        except Exception as e:
+        except BaseException as e:
+            log.exception("Tool reader task failed")
             async with self._tool_task_condition:
                 self._tool_task_state = e
                 self._tool_task_condition.notify_all()
@@ -414,9 +415,7 @@ async def _tool_detection_task_protected(self) -> None:
             )
             self._present_tools = await self._tool_detector.resolve(to_resolve, 10.0)
             log.info(f"Present tools are now {self._present_tools}")
-            await network.log_motor_usage_data(
-                self._can_messenger, list(set(base_can_nodes + [t for t in tool_nodes]))
-            )
+            await network.log_motor_usage_data(self._can_messenger)
             async with self._tool_task_condition:
                 self._tool_task_state = True
                 self._tool_task_condition.notify_all()

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

@@ -1141,7 +1141,7 @@ def get_next_tip(
             result.nextTipInfo if isinstance(result.nextTipInfo, NextTipInfo) else None
         )
 
-    def transfer_liquid(  # noqa: C901
+    def transfer_with_liquid_class(  # noqa: C901
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1335,7 +1335,7 @@ def _pick_up_tip() -> WellCore:
             _drop_tip()
 
     # TODO(spp, 2025-02-25): wire up return tip
-    def distribute_liquid(  # noqa: C901
+    def distribute_with_liquid_class(  # noqa: C901
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1417,7 +1417,7 @@ def distribute_liquid(  # noqa: C901
                 tip_working_volume=working_volume,
             )
         ):
-            self.transfer_liquid(
+            self.transfer_with_liquid_class(
                 liquid_class=liquid_class,
                 volume=volume,
                 source=[source for _ in range(len(dest))],
@@ -1657,7 +1657,7 @@ def _tip_can_hold_volume_for_multi_dispensing(
             <= tip_working_volume
         )
 
-    def consolidate_liquid(  # noqa: C901
+    def consolidate_with_liquid_class(  # noqa: C901
         self,
         liquid_class: LiquidClass,
         volume: float,

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

@@ -359,7 +359,7 @@ def configure_nozzle_layout(
         ...
 
     @abstractmethod
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -374,7 +374,7 @@ def transfer_liquid(
         ...
 
     @abstractmethod
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -392,7 +392,7 @@ def distribute_liquid(
         ...
 
     @abstractmethod
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,

api/src/opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -624,7 +624,7 @@ def configure_nozzle_layout(
         """This will never be called because it was added in API 2.16."""
         pass
 
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -638,7 +638,7 @@ def transfer_liquid(
         """This will never be called because it was added in API 2.23"""
         assert False, "transfer_liquid is not supported in legacy context"
 
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -652,7 +652,7 @@ def distribute_liquid(
         """This will never be called because it was added in API 2.23"""
         assert False, "distribute_liquid is not supported in legacy context"
 
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,

api/src/opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -513,7 +513,7 @@ def configure_nozzle_layout(
         """This will never be called because it was added in API 2.15."""
         pass
 
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -527,7 +527,7 @@ def transfer_liquid(
         """This will never be called because it was added in API 2.23."""
         assert False, "transfer_liquid is not supported in legacy context"
 
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -541,7 +541,7 @@ def distribute_liquid(
         """This will never be called because it was added in API 2.23."""
         assert False, "distribute_liquid is not supported in legacy context"
 
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,

api/src/opentrons/protocol_api/instrument_context.py

@@ -1509,7 +1509,7 @@ def _execute_transfer(self, plan: v1_transfer.TransferPlan) -> None:
             getattr(self, cmd["method"])(*cmd["args"], **cmd["kwargs"])
 
     @requires_version(2, 23)
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1526,11 +1526,32 @@ def transfer_liquid(
         return_tip: bool = False,
         visit_every_well: bool = False,
     ) -> InstrumentContext:
-        """Transfer liquid from source to dest using the specified liquid class properties.
+        """Move a particular type of liquid from one well or group of wells to another.
 
-        TODO: Add args description.
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
 
-        :meta private:
+        :param volume: The amount, in µL, to aspirate from each source and dispense to
+                       each destination.
+        :param source: A single well or a list of wells to aspirate liquid from.
+        :param dest: A single well or a list of wells to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
+
+              - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"per source"``: Use one tip for each source well, even if
+                :ref:`tip refilling <complex-tip-refilling>` is required.
+              - ``"never"``: Do not pick up or drop tips at all.
+
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
         """
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
@@ -1552,7 +1573,7 @@ def transfer_liquid(
                 " to transfer liquid onto one destinations from many sources, use 'consolidate_liquid'."
             )
 
-        self._core.transfer_liquid(
+        self._core.transfer_with_liquid_class(
             liquid_class=liquid_class,
             volume=volume,
             source=[
@@ -1574,7 +1595,7 @@ def transfer_liquid(
         return self
 
     @requires_version(2, 23)
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1590,12 +1611,30 @@ def distribute_liquid(
         visit_every_well: bool = False,
     ) -> InstrumentContext:
         """
-        Distribute liquid from a single source to multiple destinations
-        using the specified liquid class properties.
+        Distribute a particular type of liquid from one well to a group of wells.
 
-        TODO: Add args description.
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
 
-        :meta private:
+        :param volume: The amount, in µL, to aspirate from the source and dispense to
+                       each destination.
+        :param source: A single well to aspirate liquid from.
+        :param dest: A list of wells to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
+
+              - ``"once"`` or ``"per source"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"never"``: Do not pick up or drop tips at all.
+
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
         """
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
@@ -1621,7 +1660,7 @@ def distribute_liquid(
             )
 
         verified_source = transfer_args.sources_list[0]
-        self._core.distribute_liquid(
+        self._core.distribute_with_liquid_class(
             liquid_class=liquid_class,
             volume=volume,
             source=(
@@ -1643,7 +1682,7 @@ def distribute_liquid(
         return self
 
     @requires_version(2, 23)
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1659,12 +1698,31 @@ def consolidate_liquid(
         visit_every_well: bool = False,
     ) -> InstrumentContext:
         """
-        Consolidate liquid from multiple sources to a single destination
-        using the specified liquid class properties.
+        Consolidate a particular type of liquid from a group of wells to one well.
 
-        TODO: Add args description.
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
 
-        :meta private:
+        :param volume: The amount, in µL, to aspirate from the source and dispense to
+                       each destination.
+        :param source: A list of wells to aspirate liquid from.
+        :param dest: A single well to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
+
+              - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"per source"``: Not available when consolidating.
+              - ``"never"``: Do not pick up or drop tips at all.
+
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
         """
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
@@ -1690,7 +1748,7 @@ def consolidate_liquid(
             )
 
         verified_dest = transfer_args.destinations_list[0]
-        self._core.consolidate_liquid(
+        self._core.consolidate_with_liquid_class(
             liquid_class=liquid_class,
             volume=volume,
             source=[