opentrons 8.6.0__py3-none-any.whl

opentrons/hardware_control/pause_manager.py

@@ -0,0 +1,31 @@
+from typing import List
+
+from .types import PauseType
+
+
+class PauseManager:
+    """This class determines whether or not the hardware controller should
+    pause or resume by evaluating the pause and resume types. The use of two
+    pause types are used to separate the delay resume (triggered when the delay
+    timer runs out) and the pause resume (trigged by user via the app).
+    """
+
+    def __init__(self) -> None:
+        self.queue: List[PauseType] = []
+
+    @property
+    def should_pause(self) -> bool:
+        return bool(self.queue)
+
+    def resume(self, pause_type: PauseType) -> None:
+        try:
+            self.queue.remove(pause_type)
+        except ValueError:
+            pass
+
+    def pause(self, pause_type: PauseType) -> None:
+        if pause_type not in self.queue:
+            self.queue.append(pause_type)
+
+    def reset(self) -> None:
+        self.queue = []

opentrons/hardware_control/poller.py

@@ -0,0 +1,112 @@
+import asyncio
+import contextlib
+import logging
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, List, Optional
+from opentrons.hardware_control.modules.errors import AbsorbanceReaderDisconnectedError
+from opentrons_shared_data.errors.exceptions import ModuleCommunicationError
+
+
+log = logging.getLogger(__name__)
+
+
+class Reader(ABC):
+    @abstractmethod
+    async def read(self) -> None:
+        """Read some data from an external source."""
+
+    def on_error(self, exception: Exception) -> None:
+        """Handle an error from calling `read`."""
+
+
+class Poller:
+    """A poller to call a given reader on an interval.
+
+    Args:
+        reader: An interface to read data.
+        interval: The poll interval, in seconds.
+    """
+
+    interval: float
+
+    def __init__(self, reader: Reader, interval: float) -> None:
+        self.interval = interval
+        self._reader = reader
+        self._read_lock: Optional["asyncio.Lock"] = None
+        self._poll_waiters: List["asyncio.Future[None]"] = []
+        self._poll_forever_task: Optional["asyncio.Task[None]"] = None
+
+    async def start(self) -> None:
+        if self._poll_forever_task is None:
+            self._poll_forever_task = asyncio.create_task(self._poll_forever())
+            await self.wait_next_poll()
+
+    async def stop(self) -> None:
+        """Stop polling."""
+        task = self._poll_forever_task
+        if task is not None:
+            async with self._use_read_lock():
+                task.cancel()
+                await asyncio.gather(task, return_exceptions=True)
+            for waiter in self._poll_waiters:
+                waiter.cancel(msg="Module was removed")
+            self._poll_forever_task = None
+
+    async def wait_next_poll(self) -> None:
+        """Wait for the next poll to complete.
+
+        If called in the middle of a read, it will not return until
+        the next complete read. If a read raises an exception,
+        it will be passed through to `wait_next_poll`.
+        """
+        if not self._poll_forever_task or self._poll_forever_task.done():
+            raise ModuleCommunicationError(message="Module was removed")
+
+        poll_future = asyncio.get_running_loop().create_future()
+        self._poll_waiters.append(poll_future)
+        await poll_future
+
+    @contextlib.asynccontextmanager
+    async def _use_read_lock(self) -> AsyncGenerator[None, None]:
+        self._read_lock = self._read_lock or asyncio.Lock()
+
+        async with self._read_lock:
+            yield
+
+    async def _poll_forever(self) -> None:
+        """Polling loop."""
+        while True:
+            await self._poll_once()
+            await asyncio.sleep(self.interval)
+
+    @staticmethod
+    def _set_waiter_complete(
+        waiter: "asyncio.Future[None]", e: Optional[Exception] = None
+    ) -> None:
+        try:
+            waiter.set_result(None) if e is None else waiter.set_exception(e)
+        except asyncio.InvalidStateError:
+            log.warning("Poller waiter was already cancelled")
+
+    async def _poll_once(self) -> None:
+        """Trigger a single read, notifying listeners of success or error."""
+        previous_waiters = self._poll_waiters
+        self._poll_waiters = []
+
+        try:
+            async with self._use_read_lock():
+                await self._reader.read()
+        except asyncio.CancelledError:
+            raise
+        except AbsorbanceReaderDisconnectedError as e:
+            for waiter in previous_waiters:
+                Poller._set_waiter_complete(waiter, None)
+            self._reader.on_error(e)
+        except Exception as e:
+            log.exception("Polling exception")
+            self._reader.on_error(e)
+            for waiter in previous_waiters:
+                Poller._set_waiter_complete(waiter, e)
+        else:
+            for waiter in previous_waiters:
+                Poller._set_waiter_complete(waiter)

opentrons/hardware_control/protocols/__init__.py

@@ -0,0 +1,106 @@
+"""Typing protocols describing a hardware controller."""
+from typing_extensions import Protocol, Type
+
+from .module_provider import ModuleProvider
+from .hardware_manager import HardwareManager
+from .chassis_accessory_manager import ChassisAccessoryManager
+from .event_sourcer import EventSourcer
+from .liquid_handler import LiquidHandler
+from .calibratable import Calibratable
+from .configurable import Configurable
+from .motion_controller import MotionController
+from .instrument_configurer import InstrumentConfigurer
+from .execution_controllable import ExecutionControllable
+from .asyncio_configurable import AsyncioConfigurable
+from .stoppable import Stoppable
+from .simulatable import Simulatable
+from .identifiable import Identifiable
+from .gripper_controller import GripperController
+from .flex_calibratable import FlexCalibratable
+from .flex_instrument_configurer import FlexInstrumentConfigurer
+from .position_estimator import PositionEstimator
+
+from .types import (
+    CalibrationType,
+    MountArgType,
+    ConfigType,
+    OT2RobotType,
+    FlexRobotType,
+)
+
+
+class HardwareControlInterface(
+    ModuleProvider,
+    ExecutionControllable,
+    LiquidHandler[CalibrationType, MountArgType, ConfigType],
+    ChassisAccessoryManager,
+    HardwareManager,
+    AsyncioConfigurable,
+    Stoppable,
+    Simulatable,
+    Identifiable[Type[OT2RobotType]],
+    Protocol[CalibrationType, MountArgType, ConfigType],
+):
+    """A mypy protocol for a hardware controller.
+
+    This class provides an protocol for the basic hardware controller class,
+    with at least two implementations: one for the OT-2, and one for the
+    OT-3. While the two classes have the same API, fundamental architectural
+    decisions in the OT-2 hardware controller (specifically the data types used
+    in the HardwareControl/backend split) make it unsuitable for the OT-3.
+
+    This is a protocol rather than an ABC because of the use of wrapping adapters
+    such as ThreadManager and SynchAdapter. Because those classes work via
+    getattr, they can't inherit from an ABC that requires specific methods;
+    however, they can satisfy protocols.
+    """
+
+    def get_robot_type(self) -> Type[OT2RobotType]:
+        return OT2RobotType
+
+
+class FlexHardwareControlInterface(
+    PositionEstimator,
+    ModuleProvider,
+    ExecutionControllable,
+    LiquidHandler[CalibrationType, MountArgType, ConfigType],
+    ChassisAccessoryManager,
+    HardwareManager,
+    AsyncioConfigurable,
+    Stoppable,
+    Simulatable,
+    GripperController,
+    FlexCalibratable,
+    FlexInstrumentConfigurer[MountArgType],
+    Identifiable[Type[FlexRobotType]],
+    Protocol[CalibrationType, MountArgType, ConfigType],
+):
+    """A mypy protocol for a hardware controller with Flex-specific extensions.
+
+    The interface for the Flex controller is mostly in-line with the OT-2 interface,
+    with some additional functionality and parameterization not supported on the OT-2.
+    """
+
+    def get_robot_type(self) -> Type[FlexRobotType]:
+        return FlexRobotType
+
+
+__all__ = [
+    "HardwareControlInterface",
+    "FlexHardwareControlInterface",
+    "Simulatable",
+    "Stoppable",
+    "AsyncioConfigurable",
+    "ExecutionControllable",
+    "InstrumentConfigurer",
+    "MotionController",
+    "Configurable",
+    "Calibratable",
+    "LiquidHandler",
+    "EventSourcer",
+    "ChassisAccessoryManager",
+    "HardwareManager",
+    "ModuleProvider",
+    "Identifiable",
+    "FlexCalibratable",
+]

opentrons/hardware_control/protocols/asyncio_configurable.py

@@ -0,0 +1,11 @@
+from asyncio import AbstractEventLoop
+from typing_extensions import Protocol
+
+
+class AsyncioConfigurable(Protocol):
+    """Protocol specifying controllability of asyncio behavior"""
+
+    @property
+    def loop(self) -> AbstractEventLoop:
+        """The event loop used by this instance."""
+        ...

opentrons/hardware_control/protocols/calibratable.py

@@ -0,0 +1,45 @@
+from typing_extensions import Protocol
+from .types import CalibrationType
+
+from ..util import DeckTransformState
+
+
+class Calibratable(Protocol[CalibrationType]):
+    """Protocol specifying calibration information"""
+
+    @property
+    def robot_calibration(self) -> CalibrationType:
+        """The currently-active robot calibration of the machine."""
+        ...
+
+    def reset_robot_calibration(self) -> None:
+        """Reset the active robot calibration to the machine default.
+
+        This may be an identity on some machines but not on others; this
+        method is therefore preferred to using set_robot_calibration() with a
+        caller-constructed identity.
+        """
+        ...
+
+    def reset_deck_calibration(self) -> None:
+        """Resets only deck calibration data."""
+        ...
+
+    def load_deck_calibration(self) -> None:
+        """Loads only any deck calibration data that is stored."""
+        ...
+
+    def set_robot_calibration(self, robot_calibration: CalibrationType) -> None:
+        """Set the current robot calibration from stored data."""
+        ...
+
+    def validate_calibration(self) -> DeckTransformState:
+        """Check whether the current calibration is valid."""
+        ...
+
+    def build_temporary_identity_calibration(self) -> CalibrationType:
+        """
+        Get temporary default calibration data suitable for use during
+        calibration
+        """
+        ...

opentrons/hardware_control/protocols/chassis_accessory_manager.py

@@ -0,0 +1,90 @@
+from typing import Dict, Optional
+from typing_extensions import Protocol
+from ..types import (
+    DoorState,
+    StatusBarState,
+    EstopState,
+    StatusBarUpdateListener,
+    StatusBarUpdateUnsubscriber,
+)
+from .event_sourcer import EventSourcer
+
+
+class ChassisAccessoryManager(EventSourcer, Protocol):
+    """Protocol specifying control of non-motion peripherals on the robot."""
+
+    @property
+    def door_state(self) -> DoorState:
+        """The current state of the machine's door."""
+        ...
+
+    @property
+    def module_door_serial(self) -> str | None:
+        """The serial number of a module with an open door."""
+        ...
+
+    async def set_lights(
+        self,
+        button: Optional[bool] = None,
+        rails: Optional[bool] = None,
+    ) -> None:
+        """Control the robot lights.
+
+        button If specified, turn the button light on (`True`) or
+               off (`False`). If not specified, do not change the
+               button light.
+        rails: If specified, turn the rail lights on (`True`) or
+               off (`False`). If not specified, do not change the
+               rail lights.
+        """
+        ...
+
+    async def get_lights(self) -> Dict[str, bool]:
+        """Return the current status of the robot lights.
+
+        :returns: A dict of the lights: `{'button': bool, 'rails': bool}`
+        """
+        ...
+
+    async def identify(self, duration_s: int = 5) -> None:
+        """Run a routine to identify the robot.
+
+        duration_s: The duration to blink for, in seconds.
+        """
+        ...
+
+    async def set_status_bar_state(self, state: StatusBarState) -> None:
+        """Control the status bar to indicate robot state.
+
+        state: The state to set the robot to. Some states are transient
+        and will implicitly revert back to the previous state after a short
+        action, while others"""
+        ...
+
+    async def set_status_bar_enabled(self, enabled: bool) -> None:
+        """Enable or disable the status bar entirely.
+
+        enabled: True to turn the status bar on, false to turn it off."""
+
+    def get_status_bar_state(self) -> StatusBarState:
+        """Get the current status bar state.
+
+        :returns: The current status bar state enumeration."""
+        ...
+
+    def add_status_bar_listener(
+        self, listener: StatusBarUpdateListener
+    ) -> StatusBarUpdateUnsubscriber:
+        """Add a listener to the status bar state.
+
+        listener: The listener to add.
+        :returns: A callback function that removes the listener."""
+        ...
+
+    def get_estop_state(self) -> EstopState:
+        """Get the current Estop state.
+
+        If the Estop is not supported on this robot, this will always return Disengaged.
+
+        :returns: The current Estop state."""
+        ...

opentrons/hardware_control/protocols/configurable.py

@@ -0,0 +1,48 @@
+from typing import Dict, Any
+from typing_extensions import Protocol
+
+from .types import ConfigType
+from opentrons.hardware_control.types import HardwareFeatureFlags
+
+
+class Configurable(Protocol[ConfigType]):
+    """Protocol specifying hardware control configuration."""
+
+    def get_config(self) -> ConfigType:
+        """Get the robot's configuration object.
+
+        :returns .RobotConfig: The object.
+        """
+        ...
+
+    def set_config(self, config: ConfigType) -> None:
+        """Replace the currently-loaded config"""
+        ...
+
+    @property
+    def hardware_feature_flags(self) -> HardwareFeatureFlags:
+        ...
+
+    @hardware_feature_flags.setter
+    def hardware_feature_flags(self, feature_flags: HardwareFeatureFlags) -> None:
+        """Replace the currently-configured hardware feature flags."""
+        ...
+
+    @property
+    def config(self) -> ConfigType:
+        ...
+
+    @config.setter
+    def config(self, config: ConfigType) -> None:
+        ...
+
+    async def update_config(self, **kwargs: Dict[str, Any]) -> None:
+        """Update values of the robot's configuration.
+
+        `kwargs` should contain keys of the robot's configuration. For
+        instance, `update_config(log_level='debug)` would change the API
+        server log level to logging.DEBUG.
+
+        Documentation on keys can be found in the documentation for RobotConfig.
+        """
+        ...

opentrons/hardware_control/protocols/event_sourcer.py

@@ -0,0 +1,18 @@
+from typing import Callable
+from typing_extensions import Protocol
+
+from ..types import HardwareEventHandler
+
+
+class EventSourcer(Protocol):
+    """Protocol specifying how to react to events."""
+
+    def register_callback(self, cb: HardwareEventHandler) -> Callable[[], None]:
+        """Register a callback that will be called when an event occurs.
+
+        The events may be asynchronous, from various things that can happen
+        to the hardware (for instance, the door opening or closing).
+
+        The returned callable removes the callback.
+        """
+        ...

opentrons/hardware_control/protocols/execution_controllable.py

@@ -0,0 +1,33 @@
+from typing_extensions import Protocol
+from ..types import PauseType
+
+
+class ExecutionControllable(Protocol):
+    """A protocol specifying run control (pause, resume)."""
+
+    def pause(self, pause_type: PauseType) -> None:
+        """
+        Pause motion of the robot after a current motion concludes.
+
+        Individual calls to move
+        (which aspirate and dispense and other calls may depend on) are
+        considered atomic and will always complete if they have been called
+        prior to a call to this method. However, subsequent calls to move that
+        occur when the system is paused will not proceed until the system is
+        resumed with resume.
+        """
+        ...
+
+    def pause_with_message(self, message: str) -> None:
+        """Pause motion of the robot as with pause, but specify a message."""
+        ...
+
+    def resume(self, pause_type: PauseType) -> None:
+        """
+        Resume motion after a call to pause.
+        """
+        ...
+
+    async def delay(self, duration_s: float) -> None:
+        """Delay execution by pausing and sleeping."""
+        ...

opentrons/hardware_control/protocols/flex_calibratable.py

@@ -0,0 +1,96 @@
+from typing import Optional, Tuple, List, AsyncIterator, Union
+import contextlib
+from typing_extensions import Protocol
+
+from opentrons import types as top_types
+from opentrons.config.types import (
+    CapacitivePassSettings,
+)
+from opentrons.hardware_control.types import (
+    Axis,
+    OT3Mount,
+    InstrumentProbeType,
+    GripperProbe,
+)
+from opentrons.hardware_control.instruments.ot3.instrument_calibration import (
+    GripperCalibrationOffset,
+    PipetteOffsetSummary,
+)
+from opentrons.hardware_control.modules.module_calibration import (
+    ModuleCalibrationOffset,
+)
+
+
+class FlexCalibratable(Protocol):
+    """Calibration extensions for Flex hardware."""
+
+    async def capacitive_probe(
+        self,
+        mount: OT3Mount,
+        moving_axis: Axis,
+        target_pos: float,
+        pass_settings: CapacitivePassSettings,
+        retract_after: bool = True,
+        probe: Optional[InstrumentProbeType] = None,
+    ) -> Tuple[float, bool]:
+        """Determine the position of something using the capacitive sensor.
+
+        This function orchestrates detecting the position of a collision between the
+        capacitive probe on the tool on the specified mount, and some fixed element
+        of the robot.
+
+        When calling this function, the mount's probe critical point should already
+        be aligned in the probe axis with the item to be probed.
+
+        It will move the mount's probe critical point to a small distance behind
+        the expected position of the element (which is target_pos, in deck coordinates,
+        in the axis to be probed) while running the tool's capacitive sensor. When the
+        sensor senses contact, the mount stops.
+
+        This function moves away and returns the sensed position.
+
+        This sensed position can be used in several ways, including
+        - To get an absolute position in deck coordinates of whatever was
+        targeted, if something was guaranteed to be physically present.
+        - To detect whether a collision occured at all. If this function
+        returns a value far enough past the anticipated position, then it indicates
+        there was no material there.
+        """
+        ...
+
+    async def capacitive_sweep(
+        self,
+        mount: OT3Mount,
+        moving_axis: Axis,
+        begin: top_types.Point,
+        end: top_types.Point,
+        speed_mm_s: float,
+    ) -> List[float]:
+        ...
+
+    # Note that there is a default implementation of this function to allow for
+    # the asynccontextmanager decorator to propagate properly.
+    @contextlib.asynccontextmanager
+    async def restore_system_constrants(self) -> AsyncIterator[None]:
+        yield
+
+    async def reset_instrument_offset(
+        self, mount: Union[top_types.Mount, OT3Mount], to_default: bool = True
+    ) -> None:
+        ...
+
+    def add_gripper_probe(self, probe: GripperProbe) -> None:
+        ...
+
+    def remove_gripper_probe(self) -> None:
+        ...
+
+    async def save_instrument_offset(
+        self, mount: Union[top_types.Mount, OT3Mount], delta: top_types.Point
+    ) -> Union[GripperCalibrationOffset, PipetteOffsetSummary]:
+        ...
+
+    async def save_module_offset(
+        self, module_id: str, mount: OT3Mount, slot: str, offset: top_types.Point
+    ) -> Optional[ModuleCalibrationOffset]:
+        ...

opentrons/hardware_control/protocols/flex_instrument_configurer.py

@@ -0,0 +1,52 @@
+"""Flex-specific extensions to instrument configuration."""
+from typing import Union, Optional
+from typing_extensions import Protocol
+
+from .types import MountArgType
+
+from opentrons.hardware_control.dev_types import (
+    PipetteStateDict,
+)
+from opentrons.hardware_control.types import (
+    TipStateType,
+    InstrumentProbeType,
+)
+from opentrons.hardware_control.instruments.ot3.instrument_calibration import (
+    PipetteOffsetSummary,
+    GripperCalibrationOffset,
+)
+
+
+class FlexInstrumentConfigurer(Protocol[MountArgType]):
+    """A protocol specifying Flex-specific extensions to instrument configuration."""
+
+    async def get_instrument_state(
+        self,
+        mount: MountArgType,
+    ) -> PipetteStateDict:
+        ...
+
+    def get_instrument_offset(
+        self, mount: MountArgType
+    ) -> Union[GripperCalibrationOffset, PipetteOffsetSummary, None]:
+        ...
+
+    async def get_tip_presence_status(
+        self,
+        mount: MountArgType,
+    ) -> TipStateType:
+        """Check tip presence status.
+
+        If a high throughput pipette is present,
+        move the tip motors down before checking the sensor status.
+        """
+        ...
+
+    async def verify_tip_presence(
+        self,
+        mount: MountArgType,
+        expected: TipStateType,
+        follow_singular_sensor: Optional[InstrumentProbeType] = None,
+    ) -> None:
+        """Check tip presence status and raise if it does not match `expected`."""
+        ...