feat(api): add optional user_grip_force param to LabwareMovementHandl…

[caleb-lindgren]

…er.move_labware_with_gripper

The user_grip_force parameter allows the grip force to be set based off a user-specified parameter, instead of the default value for the labware.

Overview

This pull request is not complete--I'm opening it because this is a feature I'd like to have, and I want to start a discussion to see how feasible it would be before I get too far in the weeds with implementing it.

I would like to be able to manually specify the gripping force the gripper uses when moving labware. I'm not too familiar with the codebase, but it looks like the core of this change would be to add a user_grip_force parameter to the LabwareMovementHandler.move_labware_with_gripper function, so I've gone ahead and done that.

Test Plan and Hands on Testing

Because this is just an initial idea, I have not yet tested this change.

Changelog

• Added user_grip_force parameter to LabwareMovementHandler.move_labware_with_gripper

Review requests

• Before I spend more time on this, I'd like to hear if this looks feasible, and if I'm on the right track.
• Additionally, I'm not familiar with the structure of how the LabwareMovementHandler class is translated into the ProtocolContext.move_labware function in the Python API, so I'd appreciate some pointers on how to propagate the feature up to that level.
• In my code, I limit the grip force from being set to too high of a value. I couldn't find any specifications online as to what the upper limit is of the force the gripper can exert, but looking through the gripForce parameter for the labware definitions in opentrons/tree/edge/shared-data/labware/definitions/, the highest value I saw was 21 N, so I guessed and set a limit of 25 N in my code. If you have an official value for that limit, that would be good to know.

Risk assessment

For users who don't use this new parameter, this feature would not change anything, because the default is just to execute the command in the way it's currently done.

The user-specified grip force needs to be limited from being set to too high of a value. I have included a structure for such a limitation into my code.

[sfoster1]

@caleb-lindgren thanks for the PR!

I'm definitely not against adding this; we never added it because we didn't really see the utility at the time, but with sane defaults I think it makes sense.

It'll be a bit of work to add it; the change has to mostly go up the stack like you pointed out though.

• Max force: the max force a gripper can exert is stored in our shared-data configuration files, like here:

  opentrons/shared-data/gripper/definitions/1/gripperV1.3.json

  Line 16 in e4b1716

  "max": 30.0

  . That data value doesn't have a path to checking it in the engine, which is pretty annoying because we'd like there to be an analysis failure if you ask for too high a force, so your path makes sense; however, in my opinion that check should live in the move_labware command here: https://github.com/Opentrons/opentrons/blob/edge/api/src/opentrons/protocol_engine/commands/move_labware.py
• to plumb a new argument down through the stack, you need to define it as a protocol engine command parameter. The protocol engine is the underlying implementation for executing protocols, and its commands are the atomic bits of work that make up a protocol. Calls to the python protocol API create and execute protocol engine commands. Protocol engine commands are data that get executed, and define their own arguments.
  • So you'd add grip_force (and I would recommend calling it grip_force as a command parameter - that it is user grip force is apparent just from it being a command parameter) to the MoveLabwareParameters, and then in execute() access it from the params object and pass it to the equipment method
  • Then you would add it to the protocol API core, which is an adapter that connects a python protocol API to either the engine (for recent API versions) or legacy implementations for (older API versions). There's an abstract class; the actual engine adapter; and the [legacy version](https://github.com/Opentrons/opentrons/blob/e4b1716ecb77b687ffb505e4a3ff718075815c3c/api/src/opentrons/protocol_api/core/legacy/legacy_protocol_core.py#L290) which will need the argument added for type compliance but doesn't actually do anything
  • Now you can add it to the protocol API. You'd add the parameter, add it to the docstring, and pass it down to the core. You should also make sure to force its value to be None if the api version is below 2.23.

It's a lot, especially the first time, but it doesn't require changing any of the hardware interaction code or really much behavior, and I'm happy to help out and get it integrated and tested. Again, thank you for the pull request!