Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(api): new behavior for Labware.set_offset() in PAPI 2.18 #14967

Merged
merged 3 commits into from
Apr 30, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
move table from article to ref
ecormany committed Apr 24, 2024
commit e47f9b245aa2791b8fa66df9b378cb1f26199930
19 changes: 2 additions & 17 deletions api/docs/v2/new_advanced_running.rst
Original file line number Diff line number Diff line change
@@ -134,24 +134,9 @@ Keep in mind that ``set_offset()`` commands will override any labware offsets se
Labware Offset Behavior
^^^^^^^^^^^^^^^^^^^^^^^

The effects of ``set_offset()`` vary depending on the API level of your protocol.
How the API applies labware offsets varies depending on the API level of your protocol. This section describes the latest behavior. For details on how offsets work in earlier API versions, see the API reference entry for :py:meth:`.set_offset`.

.. list-table::
:header-rows: 1

* - API version
- Offset behavior
* - 2.12–2.13
- Offsets only apply to the exact :py:class:`.Labware` instance.
* - 2.14–2.17
- ``set_offset()`` is not available, and the API raises an error.
* - 2.18 and newer
-
- Offsets apply to any labware of the same type, in the same on-deck location.
- Offsets can't be set on labware that is currently off-deck.
- Offsets do not follow a labware instance when using :py:meth:`.move_labware`.

For example, in the latest API version, if you use ``set_offset()`` on a tip rack, use all the tips, and replace the rack with a fresh one of the same type in the same location, the offsets will apply to the fresh tip rack::
In the latest API version, offsets apply to labware type–location combinations. For example, if you use ``set_offset()`` on a tip rack, use all the tips, and replace the rack with a fresh one of the same type in the same location, the offsets will apply to the fresh tip rack::

tiprack = protocol.load_labware(
load_name="opentrons_flex_96_tiprack_1000ul", location="D3"
23 changes: 14 additions & 9 deletions api/src/opentrons/protocol_api/labware.py
Original file line number Diff line number Diff line change
@@ -581,15 +581,20 @@ def set_offset(self, x: float, y: float, z: float) -> None:
How the motion system applies the offset depends on the API level of the protocol.
- In API level 2.13 and earlier, the offset applies only to the labware
instance that ``set_offset()`` is called on.
- In API levels 2.14–2.17, ``set_offset()`` is not available, and the API
raises an error.
- In API level 2.18 and newer, the offset applies to any labware of the
same type, in the same on-deck location. Labware type is defined as the
combination of the ``loadName``, ``namespace``, and ``version`` parameters
of :py:meth:`~.ProtocolContext.load_labware`.
See :ref:`labware-offset-behavior` for examples.
.. list-table::
:header-rows: 1
* - API level
- Offset behavior
* - 2.12–2.13
- Offsets only apply to the exact :py:class:`.Labware` instance.
* - 2.14–2.17
- ``set_offset()`` is not available, and the API raises an error.
* - 2.18 and newer
-
- Offsets apply to any labware of the same type, in the same on-deck location.
- Offsets can't be set on labware that is currently off-deck.
- Offsets do not follow a labware instance when using :py:meth:`.move_labware`.
.. note::