bug: Aspirating with "/runs/{run_id}/commands" does not lower the tip to proper location

[Xanngo]

Overview

When utilizing the "/runs/{run_id}/commands" to aspirate from a well, the tip is positioned just beneath the top of the well, rather than the anticipated location, which is directly above the well's bottom.

Steps to reproduce

1. Create a new run with POST /runs
2. Get pipettes with /pipettes
3. Load those pipettes to the run with POST f"/runs/{run_id}/commands"

  { 
    "data": {
      "commandType": "loadPipette",
      "params": {
        "pipetteName" : "...", // redacted
        "mount" : "...", // redacted
      },
      "intent": "setup"
    }
  }

4. Add TipRack labware definition and 96 well plate with:
   4.1 POST f"/runs/{run_id}/labware_definitions"
   4.2 POST f"/runs/{run_id}/labware_offsets"
   4.3 POST f"/runs/{run_id}/commands"

   {      
     "data": {
       "commandType": "loadLabware",
       "params": { /* redacted */ },
       "intent": "setup"
     }
   }
   

5. Pick up tip from tip rack with POST f"/runs/{run_id}/commands"

{
  "data": {
    "commandType": "pickUpTip",
    "intent": "protocol"
    "params": {
      "labwareId": tipRackLabwareId,
      "wellName": "A1",
      "wellLocation": {
        "origin": "top",
        "offset": {
          "x": 0,
          "y": 0,
          "z": 0
        }
      },
      "pipetteId": right_pipette_id
    }
  }
}

6. Aspirate Liquid with POST f"/runs/{run_id}/commands"

  {
    "data": {
      "commandType": "aspirate",
      "intent": "protocol",
      "params:" {
        "labwareId": wellPlateLabwareId,
        "wellName": "A1",
        "flowRate": 46.43,
        "volume": 200,
        "pipetteId": right_pipette_id
      }
    }
  }

7. Add dispense and drop tip, if needed

8. Start run execution with POST f"/runs/{run_id}/actions"

  {
    "data": {
      "actionType": "play"
    }
  }

Current behavior

When aspirating the tip's position is 1mm below the top of the well, so it doesn't reach the liquid.

Further inspection of the aspirate command using GET f"/runs/{run_id}/commands/{command_id}" gives this result:

{
  "data": {
    "id": "ff68ee95-5754-4406-a4ce-e061c68c6d2b",
    "createdAt": "2024-03-11T15:52:08.757723+00:00",
    "commandType": "aspirate",
    "key": "9faf61495fefb7bdc50f2353a6970c84",
    "status": "succeeded",
    "params": {
      "labwareId": "Greiner 96 well-plate 0.3mL, for UV spectroscopy",
      "wellName": "A1",
      "wellLocation": {
        "origin": "top",
        "offset": {
          "x": 0,
          "y": 0,
          "z": 0
        }
      },
      "flowRate": 46.43,
      "volume": 200,
      "pipetteId": "9c88e162-776c-4433-8ed5-b8038be1cb75"
    },
    "result": {
      "position": {
        "x": 146.3,
        "y": 165.60000000000002,
        "z": 12.4
      },
      "volume": 200
    },
    "startedAt": "2024-03-11T15:52:34.027359+00:00",
    "completedAt": "2024-03-11T15:52:40.808236+00:00",
    "intent": "protocol"
  }
}

Inspection of the same command, but executed from a protocol created from the opentron app gives this result:

{
  "data": {
    "id": "command.ASPIRATE-0",
    "createdAt": "2024-03-11T14:16:08.329171+00:00",
    "commandType": "aspirate",
    "key": "command.ASPIRATE-0",
    "status": "succeeded",
    "params": {
      "labwareId": "labware-0",
      "wellName": "A1",
      "wellLocation": {
        "origin": "top",
        "offset": {
          "x": 0,
          "y": 0,
          "z": 0
        }
      },
      "flowRate": 46.43,
      "volume": 50,
      "pipetteId": "pipette-1"
    },
    "result": {
      "position": {
        "x": 0,
        "y": 0,
        "z": 0
      },
      "volume": 50
    },
    "startedAt": "2024-03-11T14:16:08.329171+00:00",
    "completedAt": "2024-03-11T14:16:12.338906+00:00"
  }
}

showing that the request params are the same, but the results are the ones expected.

Expected behavior

According to https://docs.opentrons.com/v2/robot_position.html#default-positions:

By default, your robot will aspirate and dispense 1 mm above the bottom of wells

So we expect that the tip will aspirate from that position.

Operating system

None

System and robot setup or anything else?

No response

[SyntaxColoring]

Thanks for the detailed report.

When utilizing the "/runs/{run_id}/commands" to aspirate from a well, the tip is positioned just beneath the top of the well, rather than the anticipated location, which is directly above the well's bottom.

This is expected behavior when working with Protocol Engine commands, including the POST /runs/{id}/commands endpoint (docs). There, the default is top. This is different from the Python Protocol API, where the default is near the bottom, as you're expecting.

Inspection of the same command, but executed from a protocol created from the opentron app gives this result:
[...]
showing that the request params are the same, but the results are the ones expected.

Hm, yeah. I suspect that's a bug or limitation in the way we're translating old protocols (Python Protocol API v≤2.13, JSONv≤5) into the new command shapes. I suspect if you looked at the output of a new protocol, it would have the correct wellLocation.