added tests and changed error code

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

@@ -179,13 +179,12 @@ class OverpressureError(ErrorOccurrence):
 
 
 class MustHomeError(ErrorOccurrence):
-    """Returned when sensors detect an overpressure error while moving liquid.
+    """Returned when the plunger position is unknown.
 
     The pipette plunger motion is stopped at the point of the error.
 
     The next thing to move the plunger must account for the robot not having a valid
-    estimate of its position. It should be a `home`, `unsafe/updatePositionEstimators`,
-    `unsafe/dropTipInPlace`, or `unsafe/blowOutInPlace`.
+    estimate of its position. It should be a `home`.
     """
 
     isDefined: bool = True

api/tests/opentrons/protocol_engine/commands/test_drop_tip_in_place.py

@@ -6,16 +6,18 @@
 
 from opentrons.protocol_engine.commands.pipetting_common import (
     TipPhysicallyAttachedError,
+    MustHomeError as Defined_MustHomeError,
 )
 from opentrons.protocol_engine.commands.command import DefinedErrorData, SuccessData
 from opentrons.protocol_engine.commands.drop_tip_in_place import (
     DropTipInPlaceParams,
     DropTipInPlaceResult,
     DropTipInPlaceImplementation,
 )
-from opentrons.protocol_engine.errors.exceptions import TipAttachedError
+from opentrons.protocol_engine.errors.exceptions import TipAttachedError, MustHomeError
 from opentrons.protocol_engine.execution import TipHandler, GantryMover
 from opentrons.protocol_engine.resources.model_utils import ModelUtils
+from opentrons.protocol_engine.state import update_types
 from opentrons.protocol_engine.state.update_types import (
     PipetteTipStateUpdate,
     StateUpdate,
@@ -76,7 +78,7 @@ async def test_tip_attached_error(
     mock_model_utils: ModelUtils,
     mock_gantry_mover: GantryMover,
 ) -> None:
-    """A DropTip command should have an execution implementation."""
+    """Should handle a tip not attached error."""
     subject = DropTipInPlaceImplementation(
         tip_handler=mock_tip_handler,
         model_utils=mock_model_utils,
@@ -111,3 +113,43 @@ async def test_tip_attached_error(
             pipette_tip_state=PipetteTipStateUpdate(pipette_id="abc", tip_geometry=None)
         ),
     )
+
+
+async def test_must_home_error(
+    decoy: Decoy,
+    mock_tip_handler: TipHandler,
+    mock_model_utils: ModelUtils,
+    mock_gantry_mover: GantryMover,
+) -> None:
+    """Should handle a must home error."""
+    subject = DropTipInPlaceImplementation(
+        tip_handler=mock_tip_handler,
+        model_utils=mock_model_utils,
+        gantry_mover=mock_gantry_mover,
+    )
+
+    params = DropTipInPlaceParams(pipetteId="abc", homeAfter=False)
+
+    decoy.when(await mock_gantry_mover.get_position(pipette_id="abc")).then_return(
+        Point(9, 8, 7)
+    )
+    decoy.when(
+        await mock_tip_handler.drop_tip(pipette_id="abc", home_after=False)
+    ).then_raise(MustHomeError("Egads!"))
+
+    decoy.when(mock_model_utils.generate_id()).then_return("error-id")
+    decoy.when(mock_model_utils.get_timestamp()).then_return(
+        datetime(year=1, month=2, day=3)
+    )
+
+    result = await subject.execute(params)
+    state_update_false_positive = StateUpdate(pipette_location=update_types.CLEAR)
+    assert result == DefinedErrorData(
+        public=Defined_MustHomeError.construct(
+            id="error-id",
+            createdAt=datetime(year=1, month=2, day=3),
+            wrappedErrors=[matchers.Anything()],
+        ),
+        state_update=StateUpdate(),
+        state_update_if_false_positive=state_update_false_positive,
+    )

shared-data/errors/definitions/1/errors.json

@@ -130,6 +130,10 @@
       "detail": "Tip Hit Well Bottom",
       "category": "roboticsControlError"
     },
+    "2019": {
+      "detail": "Must Home Plunger",
+      "category": "roboticsControlError"
+    },
     "3000": {
       "detail": "A robotics interaction error occurred.",
       "category": "roboticsInteractionError"

shared-data/python/opentrons_shared_data/errors/codes.py

@@ -62,6 +62,7 @@ class ErrorCodes(Enum):
     MOTOR_DRIVER_ERROR = _code_from_dict_entry("2016")
     PIPETTE_LIQUID_NOT_FOUND = _code_from_dict_entry("2017")
     TIP_HIT_WELL_BOTTOM = _code_from_dict_entry("2018")
+    MUST_HOME_ERROR = _code_from_dict_entry("2019")
     ROBOTICS_INTERACTION_ERROR = _code_from_dict_entry("3000")
     LABWARE_DROPPED = _code_from_dict_entry("3001")
     LABWARE_NOT_PICKED_UP = _code_from_dict_entry("3002")
@@ -93,7 +94,6 @@ class ErrorCodes(Enum):
     MISSING_CONFIGURATION_DATA = _code_from_dict_entry("4009")
     RUNTIME_PARAMETER_VALUE_REQUIRED = _code_from_dict_entry("4010")
     INCORRECT_API_VERSION = _code_from_dict_entry("4011")
-    MUST_HOME_ERROR = _code_from_dict_entry("4012")
 
     @classmethod
     @lru_cache(25)