opentrons 8.6.0__py3-none-any.whl

opentrons/hardware_control/protocols/motion_controller.py

@@ -0,0 +1,243 @@
+from typing import Dict, List, Optional, Mapping
+from typing_extensions import Protocol
+
+from opentrons.types import Point
+from ..types import Axis, CriticalPoint, MotionChecks
+from .types import MountArgType
+
+
+class MotionController(Protocol[MountArgType]):
+    """Protocol specifying fundamental motion controls."""
+
+    def get_deck_from_machine(
+        self, machine_pos: Dict[Axis, float]
+    ) -> Dict[Axis, float]:
+        """Convert machine coordinates to deck coordinates."""
+        ...
+
+    async def halt(self, disengage_before_stopping: bool = False) -> None:
+        """Immediately stop motion.
+
+        Calls to stop through the synch adapter while other calls
+        are ongoing will typically wait until those calls are done, since most
+        of the async calls here in fact block the loop while they talk to
+        smoothie. To provide actual immediate halting, call this method which
+        does not require use of the loop.
+
+        If disengage_before_stopping is True, the motors will disengage first and then
+        stop in place. Disengaging creates a smoother halt but requires homing after
+        in order to resume movement.
+        """
+        ...
+
+    async def stop(self, home_after: bool = True) -> None:
+        """
+        Stop motion as soon as possible, reset, and optionally home.
+
+        This will cancel motion (after the current call to :py:meth:`move`;
+        see :py:meth:`pause` for more detail), then home and reset the
+        robot.
+        """
+        ...
+
+    async def reset(self) -> None:
+        """Reset the stored state of the system.
+
+        This will re-scan instruments and models, clearing any cached
+        information about their presence or state.
+        """
+        ...
+
+    # Gantry/frame (i.e. not pipette) action API
+    async def home_z(
+        self,
+        mount: Optional[MountArgType] = None,
+        allow_home_other: bool = True,
+    ) -> None:
+        """Home a selected z-axis, or both if not specified."""
+        ...
+
+    async def home_plunger(self, mount: MountArgType) -> None:
+        """
+        Home the plunger motor for a mount, and then return it to the 'bottom'
+        position.
+
+        mount: the mount associated with the target plunger
+        """
+        ...
+
+    async def home(self, axes: Optional[List[Axis]] = None) -> None:
+        """Home a list of axes and initialize current position.
+
+        axes A list of axes to home. Default is `None`, which will
+             home everything.
+        """
+        ...
+
+    async def current_position(
+        self,
+        mount: MountArgType,
+        critical_point: Optional[CriticalPoint] = None,
+        refresh: bool = False,
+        # TODO(mc, 2021-11-15): combine with `refresh` for more reliable
+        # position reporting when motors are not homed
+        fail_on_not_homed: bool = False,
+    ) -> Dict[Axis, float]:
+        """Return the postion (in deck coords) of the critical point of the
+        specified mount.
+
+        This returns cached position to avoid hitting the smoothie driver
+        unless ``refresh`` is ``True``.
+
+        If `critical_point` is specified, that critical point will be applied
+        instead of the default one. For instance, if
+        `critical_point=CriticalPoints.MOUNT` then the position of the mount
+        will be returned. If the critical point specified does not exist, then
+        the next one down is returned - for instance, if there is no tip on the
+        specified mount but `CriticalPoint.TIP` was specified, the position of
+        the nozzle will be returned.
+
+        If `fail_on_not_homed` is `True`, this method will raise a `PositionUnknownError`
+        if any of the relavent axes are not homed, regardless of `refresh`.
+        """
+        ...
+
+    async def gantry_position(
+        self,
+        mount: MountArgType,
+        critical_point: Optional[CriticalPoint] = None,
+        refresh: bool = False,
+        # TODO(mc, 2021-11-15): combine with `refresh` for more reliable
+        # position reporting when motors are not homed
+        fail_on_not_homed: bool = False,
+    ) -> Point:
+        """Retrieve the position of just the currently-active pipette.
+
+        While current_position returns the position of every actuator on the system,
+        this function just returns the x, y, and z of the critical point of whichever
+        pipette is currently active (last moved).
+        """
+        ...
+
+    async def move_to(
+        self,
+        mount: MountArgType,
+        abs_position: Point,
+        speed: Optional[float] = None,
+        critical_point: Optional[CriticalPoint] = None,
+        max_speeds: Optional[Dict[Axis, float]] = None,
+    ) -> None:
+        """Move the critical point of the specified mount to a location
+        relative to the deck, at the specified speed. 'speed' sets the speed
+        of all robot axes to the given value. So, if multiple axes are to be
+        moved, they will do so at the same speed
+
+        The critical point of the mount depends on the current status of
+        the mount:
+        - If the mount does not have anything attached, its critical point is
+          the bottom of the mount attach bracket.
+        - If the mount has a pipette attached and it is not known to have a
+          pipette tip, the critical point is the end of the nozzle of a single
+          pipette or the end of the backmost nozzle of a multipipette
+        - If the mount has a pipette attached and it is known to have a
+          pipette tip, the critical point is the end of the pipette tip for
+          a single pipette or the end of the tip of the backmost nozzle of a
+          multipipette
+
+        :param mount: The mount to move
+        :param abs_position: The target absolute position in
+                             deck coordinates to move the
+                             critical point to
+        :param speed: An overall head speed to use during the move
+        :param critical_point: The critical point to move. In most situations
+                               this is not needed. If not specified, the
+                               current critical point will be moved. If
+                               specified, the critical point must be one that
+                               actually exists - that is, specifying
+                               :py:attr:`.CriticalPoint.NOZZLE` when no pipette
+                               is attached or :py:attr:`.CriticalPoint.TIP`
+                               when no tip is applied will result in an error.
+        :param max_speeds: An optional override for per-axis maximum speeds. If
+                           an axis is specified, it will not move faster than
+                           the given speed. Note that this does not make that
+                           axis move precisely at the given speed; it only
+                           it if it was going to go faster. Direct speed
+                           is still set by ``speed``.
+        """
+        ...
+
+    async def move_axes(
+        self,
+        position: Mapping[Axis, float],
+        speed: Optional[float] = None,
+        max_speeds: Optional[Dict[Axis, float]] = None,
+        expect_stalls: bool = False,
+    ) -> None:
+        """Moves the effectors of the specified axis to the specified position.
+        The effector of the x,y axis is the center of the carriage.
+        The effector of the pipette mount axis are the mount critical points but only in z.
+        """
+        ...
+
+    async def move_rel(
+        self,
+        mount: MountArgType,
+        delta: Point,
+        speed: Optional[float] = None,
+        max_speeds: Optional[Dict[Axis, float]] = None,
+        check_bounds: MotionChecks = MotionChecks.NONE,
+        fail_on_not_homed: bool = False,
+    ) -> None:
+        """Move the critical point of the specified mount by a specified
+        displacement in a specified direction, at the specified speed.
+        'speed' sets the speed of all axes to the given value. So, if multiple
+        axes are to be moved, they will do so at the same speed.
+
+        If fail_on_not_homed is True (default False), if an axis that is not
+        homed moves it will raise a PositionUnknownError. Otherwise, it will home the axis.
+        """
+        ...
+
+    def get_engaged_axes(self) -> Dict[Axis, bool]:
+        """Which axes are engaged and holding."""
+        ...
+
+    @property
+    def engaged_axes(self) -> Dict[Axis, bool]:
+        """Which axes are engaged and holding"""
+        return self.get_engaged_axes()
+
+    async def disengage_axes(self, which: List[Axis]) -> None:
+        """Disengage some axes."""
+        ...
+
+    async def engage_axes(self, which: List[Axis]) -> None:
+        """Engage some axes."""
+        ...
+
+    async def retract(self, mount: MountArgType, margin: float = 10) -> None:
+        """Pull the specified mount up to its home position.
+
+        Works regardless of critical point or home status.
+        """
+        ...
+
+    async def retract_axis(self, axis: Axis) -> None:
+        """Retract the specified axis to its home position."""
+        ...
+
+    def is_movement_execution_taskified(self) -> bool:
+        """Get whether move functions are being executed inside cancellable tasks."""
+        ...
+
+    def should_taskify_movement_execution(self, taskify: bool) -> None:
+        """Specify whether move functions should be executed inside cancellable tasks."""
+        ...
+
+    async def cancel_execution_and_running_tasks(self) -> None:
+        """Cancel all tasks and set execution manager state to Cancelled."""
+        ...
+
+    async def prepare_for_mount_movement(self, mount: MountArgType) -> None:
+        """Retract the other mount if necessary."""
+        ...

opentrons/hardware_control/protocols/position_estimator.py

@@ -0,0 +1,45 @@
+from typing import Protocol, Sequence
+
+from ..types import Axis
+
+
+class PositionEstimator(Protocol):
+    """Position-control extensions for harwdare with encoders."""
+
+    async def update_axis_position_estimations(self, axes: Sequence[Axis]) -> None:
+        """Update the specified axes' position estimators from their encoders.
+
+        This will allow these axes to make a non-home move even if they do not currently have
+        a position estimation (unless there is no tracked position from the encoders, as would be
+        true immediately after boot).
+
+        Axis encoders have less precision than their position estimators. Calling this function will
+        cause absolute position drift. After this function is called, the axis should be homed before
+        it is relied upon for accurate motion.
+
+        This function updates only the requested axes. If other axes have bad position estimation,
+        moves that require those axes or attempts to get the position of those axes will still fail.
+        Axes that are not currently available (like a plunger for a pipette that is not connected)
+        will be ignored.
+        """
+        ...
+
+    def motor_status_ok(self, axis: Axis) -> bool:
+        """Return whether an axis' position estimator is healthy.
+
+        The position estimator is healthy if the axis has
+        1) been homed
+        2) not suffered a loss-of-positioning (from a cancel or stall, for instance) since being homed
+
+        If this function returns false, getting the position of this axis or asking it to move will fail.
+        """
+        ...
+
+    def encoder_status_ok(self, axis: Axis) -> bool:
+        """Return whether an axis' position encoder tracking is healthy.
+
+        The encoder status is healthy if the axis has been homed since booting up.
+
+        If this function returns false, updating the estimator from the encoder will fail.
+        """
+        ...

opentrons/hardware_control/protocols/simulatable.py

@@ -0,0 +1,10 @@
+from typing_extensions import Protocol
+
+
+class Simulatable(Protocol):
+    """Protocol specifying ability to simulate"""
+
+    @property
+    def is_simulator(self) -> bool:
+        """`True` if this is a simulator; `False` otherwise."""
+        ...

opentrons/hardware_control/protocols/stoppable.py

@@ -0,0 +1,9 @@
+from typing_extensions import Protocol
+
+
+class Stoppable(Protocol):
+    """Protocol specifying controllability of teardown"""
+
+    async def clean_up(self) -> None:
+        """Get the API ready to stop cleanly."""
+        ...

opentrons/hardware_control/protocols/types.py

@@ -0,0 +1,27 @@
+"""Types that are common across protocols."""
+
+from typing import TypeVar, Union, Type
+from opentrons.hardware_control.types import OT3Mount
+from opentrons.types import Mount
+from opentrons.config.types import RobotConfig, OT3Config
+
+
+class OT2RobotType:
+    pass
+
+
+class FlexRobotType:
+    pass
+
+
+CalibrationType = TypeVar("CalibrationType")
+
+MountArgType = TypeVar(
+    "MountArgType", Mount, Union[OT3Mount, Mount], contravariant=True
+)
+
+ConfigType = TypeVar("ConfigType", RobotConfig, OT3Config)
+
+ProtocolRobotType = TypeVar(
+    "ProtocolRobotType", Type[FlexRobotType], Type[OT2RobotType], covariant=True
+)

opentrons/hardware_control/robot_calibration.py

@@ -0,0 +1,224 @@
+from functools import lru_cache
+import logging
+import numpy as np
+from datetime import datetime
+from dataclasses import dataclass
+from typing import Optional, List, Any, cast
+from numpy.typing import NDArray
+
+from opentrons import config
+
+from opentrons.config.robot_configs import (
+    get_legacy_gantry_calibration,
+    default_ot2_deck_calibration,
+)
+from opentrons.calibration_storage import (
+    types,
+    save_robot_deck_attitude,
+    get_robot_deck_attitude,
+)
+from opentrons.util import linal
+
+from .util import DeckTransformState
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class DeckCalibration:
+    attitude: types.AttitudeMatrix
+    source: types.SourceType
+    status: types.CalibrationStatus
+    belt_attitude: Optional[types.AttitudeMatrix] = None
+    last_modified: Optional[datetime] = None
+    pipette_calibrated_with: Optional[str] = None
+    tiprack: Optional[str] = None
+
+
+@dataclass
+class RobotCalibration:
+    deck_calibration: DeckCalibration
+
+
+def validate_attitude_deck_calibration(
+    deck_cal: DeckCalibration,
+) -> DeckTransformState:
+    """
+    This function determines whether the deck calibration is valid
+    or not based on the following use-cases:
+
+    TODO(lc, 8/10/2020): As with the OT2, expand on this method, or create
+    another method to diagnose bad instrument offset data
+    """
+    curr_cal: linal.DoubleMatrix = np.array(deck_cal.attitude)
+    row, _ = curr_cal.shape
+    rank: int = np.linalg.matrix_rank(curr_cal)
+    if row != rank:
+        # Check that the matrix is non-singular
+        return DeckTransformState.SINGULARITY
+    elif not deck_cal.last_modified:
+        # Check that the matrix is not an identity
+        return DeckTransformState.IDENTITY
+    else:
+        # Transform as it stands is sufficient.
+        return DeckTransformState.OK
+
+
+def validate_gantry_calibration(gantry_cal: List[List[float]]) -> DeckTransformState:
+    """
+    This function determines whether the gantry calibration is valid
+    or not based on the following use-cases:
+    """
+    curr_cal: linal.DoubleMatrix = np.array(gantry_cal)
+    row, _ = curr_cal.shape
+
+    rank: int = np.linalg.matrix_rank(curr_cal)
+
+    id_matrix = linal.identity_deck_transform()
+
+    z = abs(curr_cal[2][-1])
+
+    outofrange = z < 16 or z > 34
+    if row != rank:
+        # Check that the matrix is non-singular
+        return DeckTransformState.SINGULARITY
+    elif np.array_equal(curr_cal, id_matrix):
+        # Check that the matrix is not an identity
+        return DeckTransformState.IDENTITY
+    elif outofrange:
+        # Check that the matrix is not out of range.
+        return DeckTransformState.BAD_CALIBRATION
+    else:
+        # Transform as it stands is sufficient.
+        return DeckTransformState.OK
+
+
+def migrate_affine_xy_to_attitude(
+    gantry_cal: List[List[float]],
+) -> types.AttitudeMatrix:
+    masked_transform: NDArray[np.bool_] = np.array(
+        [
+            [True, True, True, False],
+            [True, True, True, False],
+            [False, False, False, False],
+            [False, False, False, False],
+        ]
+    )
+    masked_array: np.ma.MaskedArray[
+        Any, np.dtype[np.float64]
+    ] = np.ma.masked_array(  # type: ignore
+        gantry_cal, ~masked_transform
+    )
+    attitude_array: linal.DoubleMatrix = np.zeros((3, 3))
+    np.put(attitude_array, [0, 1, 2], masked_array[0].compressed())
+    np.put(attitude_array, [3, 4, 5], masked_array[1].compressed())
+    np.put(attitude_array, 8, 1)
+    return cast(List[List[float]], attitude_array.tolist())
+
+
+def save_attitude_matrix(
+    expected: linal.SolvePoints,
+    actual: linal.SolvePoints,
+    pipette_id: str,
+    tiprack_hash: str,
+) -> None:
+    attitude = linal.solve_attitude(expected, actual)
+    save_robot_deck_attitude(
+        attitude,
+        pipette_id,
+        tiprack_hash,
+    )
+
+
+def load_attitude_matrix() -> DeckCalibration:
+    calibration_data = get_robot_deck_attitude()
+    gantry_cal = get_legacy_gantry_calibration()
+    if not calibration_data and gantry_cal:
+        if validate_gantry_calibration(gantry_cal) == DeckTransformState.OK:
+            log.debug(
+                "Attitude deck calibration matrix not found. Migrating "
+                "existing affine deck calibration matrix to {}".format(
+                    config.get_opentrons_path("robot_calibration_dir")
+                )
+            )
+            attitude = migrate_affine_xy_to_attitude(gantry_cal)
+            save_robot_deck_attitude(
+                transform=attitude,
+                pip_id=None,
+                lw_hash=None,
+                source=types.SourceType.legacy,
+            )
+            calibration_data = get_robot_deck_attitude()
+
+    if calibration_data:
+        return DeckCalibration(
+            attitude=calibration_data.attitude,
+            source=calibration_data.source,
+            status=types.CalibrationStatus(**calibration_data.status.model_dump()),
+            last_modified=calibration_data.last_modified,
+            pipette_calibrated_with=calibration_data.pipette_calibrated_with,
+            tiprack=calibration_data.tiprack,
+        )
+    else:
+        # load default if deck calibration data do not exist
+        return DeckCalibration(
+            attitude=default_ot2_deck_calibration(),
+            source=types.SourceType.default,
+            status=types.CalibrationStatus(),
+        )
+
+
+def load() -> RobotCalibration:
+    return RobotCalibration(deck_calibration=load_attitude_matrix())
+
+
+class RobotCalibrationProvider:
+    def __init__(self) -> None:
+        self._robot_calibration = load()
+
+    @lru_cache(1)
+    def _validate(self) -> DeckTransformState:
+        return validate_attitude_deck_calibration(
+            self._robot_calibration.deck_calibration
+        )
+
+    @property
+    def robot_calibration(self) -> RobotCalibration:
+        return self._robot_calibration
+
+    def reset_robot_calibration(self) -> None:
+        self._validate.cache_clear()
+        self._robot_calibration = load()
+
+    def reset_deck_calibration(self) -> None:
+        self._robot_calibration = load()
+
+    def load_deck_calibration(self) -> None:
+        self._robot_calibration = load()
+
+    def set_robot_calibration(self, robot_calibration: RobotCalibration) -> None:
+        self._validate.cache_clear()
+        self._robot_calibration = robot_calibration
+
+    def validate_calibration(self) -> DeckTransformState:
+        """
+        The lru cache decorator is currently not supported by the
+        ThreadManager. To work around this, we need to wrap the
+        actual function around a dummy outer function.
+
+        Once decorators are more fully supported, we can remove this.
+        """
+        return self._validate()
+
+    def build_temporary_identity_calibration(self) -> RobotCalibration:
+        """
+        Get a temporary identity deck cal suitable for use during
+        calibration
+        """
+        return RobotCalibration(
+            deck_calibration=DeckCalibration(
+                attitude=default_ot2_deck_calibration(),
+                source=types.SourceType.default,
+                status=types.CalibrationStatus(),
+            )
+        )

opentrons/hardware_control/scripts/README.md

@@ -0,0 +1,28 @@
+# Hardware Control Scripts
+
+## Repl Script
+
+### Overview
+
+This script gives you access to a hardware controller object in a python shell. 
+
+### Running on an OT-3
+
+The script is installed to path by using the `make push-ot3` command. When you are ssh-ed in the robot, you can run `ot3repl` from anywhere.
+
+
+### Running on a computer
+
+Please review [the setup for a simulated CAN connection](https://github.com/Opentrons/opentrons/tree/edge/hardware#can-bus-simulation) to see how to run OT-3 simulators on your computer. Once you have a simulated CAN connection and firmware, you can run the following:
+
+`OPENTRONS_SIMULATION=true OT_API_FF_enableOT3HardwareController=true OT3_CAN_DRIVER_INTERFACE=opentrons_sock pipenv run python -m opentrons.hardware_control.scripts.repl`
+
+## Gripper Script
+
+### Overview
+
+Gripper test script only for the OT-3.
+
+### Running on an OT-3
+
+Install the script using `make push-ot3` command and run `ot3gripper` after you ssh-ed into the updated robot.

opentrons/hardware_control/scripts/__init__.py

@@ -0,0 +1 @@
+"""Scripts for the hardware controller."""