opentrons 8.6.0a1__py3-none-any.whl

opentrons/hardware_control/modules/mod_abc.py

@@ -0,0 +1,245 @@
+import abc
+import asyncio
+import logging
+import re
+from typing import Any, ClassVar, Mapping, Optional, TypeVar
+from packaging.version import InvalidVersion, parse, Version
+from opentrons.config import IS_ROBOT, ROBOT_FIRMWARE_DIR
+from opentrons.drivers.rpi_drivers.types import USBPort
+
+from ..execution_manager import ExecutionManager
+from .types import (
+    BundledFirmware,
+    ModuleDisconnectedCallback,
+    UploadFunction,
+    LiveData,
+    ModuleType,
+    HopperDoorState,
+)
+
+mod_log = logging.getLogger(__name__)
+
+TaskPayload = TypeVar("TaskPayload")
+
+
+def parse_fw_version(version: str) -> Version:
+    try:
+        device_version = parse(version)
+        # This is a patch for older versions of packaging - they would try and parse old
+        # kidns of versions and return a LegacyVersion object. We can't check for that
+        # explicitly because they removed it in modern versions of packaging.
+        if not isinstance(device_version, Version):
+            raise InvalidVersion()
+    except InvalidVersion:
+        device_version = parse("v0.0.0")
+    return device_version
+
+
+class AbstractModule(abc.ABC):
+    """Defines the common methods of a module."""
+
+    MODULE_TYPE: ClassVar[ModuleType]
+
+    @classmethod
+    @abc.abstractmethod
+    async def build(
+        cls,
+        port: str,
+        usb_port: USBPort,
+        hw_control_loop: asyncio.AbstractEventLoop,
+        execution_manager: Optional[ExecutionManager] = None,
+        poll_interval_seconds: Optional[float] = None,
+        simulating: bool = False,
+        sim_model: Optional[str] = None,
+        sim_serial_number: Optional[str] = None,
+        disconnected_callback: ModuleDisconnectedCallback = None,
+    ) -> "AbstractModule":
+        """Modules should always be created using this factory.
+
+        This lets the (perhaps blocking) work of connecting to and initializing
+        a module be in a place that can be async.
+        """
+
+    def __init__(
+        self,
+        port: str,
+        usb_port: USBPort,
+        hw_control_loop: asyncio.AbstractEventLoop,
+        execution_manager: Optional[ExecutionManager] = None,
+        disconnected_callback: ModuleDisconnectedCallback = None,
+    ) -> None:
+        self._port = port
+        self._usb_port = usb_port
+        self._loop = hw_control_loop
+        self._execution_manager = execution_manager
+        self._bundled_fw: Optional[BundledFirmware] = self.get_bundled_fw()
+        self._disconnected_callback = disconnected_callback
+        self._updating = False
+
+    @staticmethod
+    def sort_key(inst: "AbstractModule") -> int:
+        usb_port = inst.usb_port
+
+        primary_port = usb_port.port_number
+
+        if usb_port.hub_port is not None:
+            secondary_port = usb_port.hub_port
+        else:
+            secondary_port = 0
+
+        return primary_port * 1000 + secondary_port
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop:
+        return self._loop
+
+    @property
+    def updating(self) -> bool:
+        """The device is updating is True."""
+        return self._updating
+
+    def disconnected_callback(self) -> None:
+        """Called from within the module object to signify the object is no longer connected"""
+        if self._disconnected_callback is not None:
+            self._disconnected_callback(self.port, self.serial_number)
+
+    def get_bundled_fw(self) -> Optional[BundledFirmware]:
+        """Get absolute path to bundled version of module fw if available."""
+        if not IS_ROBOT:
+            return None
+        file_prefix = self.firmware_prefix()
+
+        MODULE_FW_RE = re.compile(f"^{file_prefix}@v(.*)[.](hex|bin|byoup)$")
+        for fw_resource in ROBOT_FIRMWARE_DIR.iterdir():  # type: ignore
+            matches = MODULE_FW_RE.search(fw_resource.name)
+            if matches:
+                return BundledFirmware(version=matches.group(1), path=fw_resource)
+
+        mod_log.info(f"no available fw file found for: {file_prefix}")
+        return None
+
+    def has_available_update(self) -> bool:
+        """Return whether a newer firmware file is available"""
+        if self.device_info and self._bundled_fw:
+            device_version = parse_fw_version(self.device_info["version"])
+            available_version = parse_fw_version(self._bundled_fw.version)
+            return available_version > device_version
+        return False
+
+    async def wait_for_is_running(self) -> None:
+        if not self.is_simulated and self._execution_manager is not None:
+            await self._execution_manager.wait_for_is_running()
+
+    def make_cancellable(self, task: "asyncio.Task[TaskPayload]") -> None:
+        if self._execution_manager is not None:
+            self._execution_manager.register_cancellable_task(task)
+
+    @abc.abstractmethod
+    async def deactivate(self, must_be_running: bool = True) -> None:
+        """Deactivate the module.
+
+        Contains an override to the `wait_for_is_running` step in cases where the
+        module must be deactivated regardless of context."""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def status(self) -> str:
+        """Return some string describing status."""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def device_info(self) -> Mapping[str, str]:
+        """Return a dict of the module's static information (serial, etc)"""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def live_data(self) -> LiveData:
+        """Return a dict of the module's dynamic information"""
+        pass
+
+    @property
+    @abc.abstractmethod
+    def is_simulated(self) -> bool:
+        """True if >this is a simulated module."""
+        pass
+
+    @property
+    def port(self) -> str:
+        """The virtual port where the module is connected."""
+        return self._port
+
+    @property
+    def usb_port(self) -> USBPort:
+        """The physical port where the module is connected."""
+        return self._usb_port
+
+    @property
+    def serial_number(self) -> Optional[str]:
+        """The usb serial number of this device."""
+        return self.device_info.get("serial")
+
+    @property
+    def hopper_door_state(self) -> Optional[HopperDoorState]:
+        """Return a Flex Stacker Hopper Module Door State"""
+        pass
+
+    @abc.abstractmethod
+    async def prep_for_update(self) -> str:
+        """Prepare for an update.
+
+        By the time this coroutine completes, the hardware should be ready
+        to take an update. This implicitly tears down the module instance;
+        it does not need to be either working or recoverable after this
+        coroutine completes.
+
+        :returns str: The port we're running on.
+        """
+        pass
+
+    @property
+    def bundled_fw(self) -> Optional[BundledFirmware]:
+        return self._bundled_fw
+
+    @abc.abstractmethod
+    def model(self) -> str:
+        """A name for this specific module, matching module defs"""
+        pass
+
+    @classmethod
+    @abc.abstractmethod
+    def name(cls) -> str:
+        """A shortname used for matching usb ports, among other things"""
+        pass
+
+    @abc.abstractmethod
+    def firmware_prefix(self) -> str:
+        """The prefix used for looking up firmware"""
+        pass
+
+    @abc.abstractmethod
+    def bootloader(self) -> UploadFunction:
+        """Method used to upload file to this module's bootloader."""
+        pass
+
+    async def cleanup(self) -> None:
+        """Clean up the module instance.
+
+        Clean up, i.e. stop pollers, disconnect serial, etc in preparation for
+        object destruction.
+        """
+        pass
+
+    def event_listener(self, event: Any) -> None:
+        """Listen for events and update the module state."""
+        pass
+
+    async def identify(self, start: bool, color_name: Optional[str] = None) -> None:
+        """Identify the module."""
+        pass
+
+    def cleanup_persistent(self) -> None:
+        """Reset any persistent data on the module that should not exist outside of a run."""
+        pass

opentrons/hardware_control/modules/module_calibration.py

@@ -0,0 +1,93 @@
+from datetime import datetime
+
+from dataclasses import dataclass
+from typing import List, Optional
+from opentrons.calibration_storage.ot3.models.v1 import CalibrationStatus
+from opentrons.calibration_storage.ot3.module_offset import (
+    get_module_offset,
+    load_all_module_offsets,
+    save_module_calibration,
+)
+from opentrons.calibration_storage.types import SourceType
+from opentrons.hardware_control.modules.types import ModuleType
+from opentrons.hardware_control.types import OT3Mount
+
+
+from opentrons.types import Point
+
+
+@dataclass
+class ModuleCalibrationOffset:
+    """Class to store module offset calibration data."""
+
+    offset: Point
+    module_id: str
+    module: ModuleType
+    source: SourceType
+    status: CalibrationStatus
+    slot: str
+    mount: Optional[OT3Mount] = None
+    instrument_id: Optional[str] = None
+    last_modified: Optional[datetime] = None
+
+
+def load_module_calibration_offset(
+    module_type: ModuleType,
+    module_id: str,
+) -> Optional[ModuleCalibrationOffset]:
+    """Loads the calibration offset for a module."""
+    module_offset_data = get_module_offset(module_type, module_id)
+    if not module_offset_data:
+        return None
+    return ModuleCalibrationOffset(
+        module=module_type,
+        module_id=module_id,
+        slot=module_offset_data.slot,
+        mount=module_offset_data.mount,
+        offset=module_offset_data.offset,
+        last_modified=module_offset_data.lastModified,
+        instrument_id=module_offset_data.instrument_id,
+        source=module_offset_data.source,
+        status=CalibrationStatus(
+            markedAt=module_offset_data.status.markedAt,
+            markedBad=module_offset_data.status.markedBad,
+            source=module_offset_data.status.source,
+        ),
+    )
+
+
+def save_module_calibration_offset(
+    offset: Point,
+    mount: OT3Mount,
+    slot: str,
+    module: ModuleType,
+    module_id: str,
+    instrument_id: Optional[str] = None,
+) -> None:
+    """Save the calibration offset for a given module."""
+    save_module_calibration(offset, mount, slot, module, module_id, instrument_id)
+
+
+def load_all_module_calibrations() -> List[ModuleCalibrationOffset]:
+    """Loads all the module calibration stored on the robot."""
+    module_calibrations: List[ModuleCalibrationOffset] = []
+    module_offset_data = load_all_module_offsets()
+    for data in module_offset_data:
+        module_calibrations.append(
+            ModuleCalibrationOffset(
+                slot=data.slot,
+                module=data.module,
+                module_id=data.module_id,
+                mount=data.mount,
+                offset=data.offset,
+                last_modified=data.lastModified,
+                instrument_id=data.instrument_id,
+                source=data.source,
+                status=CalibrationStatus(
+                    markedAt=data.status.markedAt,
+                    markedBad=data.status.markedBad,
+                    source=data.status.source,
+                ),
+            )
+        )
+    return module_calibrations

opentrons/hardware_control/modules/plate_temp_status.py

@@ -0,0 +1,61 @@
+from collections import deque
+from typing import Deque
+
+from opentrons.drivers.types import PlateTemperature
+from opentrons.hardware_control.modules.types import TemperatureStatus
+
+
+class PlateTemperatureStatus:
+
+    TEMP_THRESHOLD = 0.3
+    """The threshold under which the difference between target and temperature
+    is considered `holding`."""
+
+    MIN_SAMPLES_UNDER_THRESHOLD = 10
+    """The number of temperature samples needed before determining that the
+    temperature is `holding`"""
+
+    def __init__(self) -> None:
+        """Construct."""
+        self._temp_history: Deque[float] = deque(
+            maxlen=self.MIN_SAMPLES_UNDER_THRESHOLD
+        )
+        self._status = TemperatureStatus.ERROR
+
+    @property
+    def status(self) -> TemperatureStatus:
+        """Return the current status."""
+        return self._status
+
+    def update(self, temperature: PlateTemperature) -> TemperatureStatus:
+        """Update the status based on the temperature."""
+        # Add to history
+        self._temp_history.append(temperature.current)
+
+        if temperature.target is None:
+            _status = TemperatureStatus.IDLE
+        else:
+            diff = temperature.target - temperature.current
+            if self._is_holding_at_target(temperature.target, self._temp_history):
+                _status = TemperatureStatus.HOLDING
+            elif diff < 0:
+                _status = TemperatureStatus.COOLING
+            else:
+                _status = TemperatureStatus.HEATING
+        self._status = _status
+        return self._status
+
+    @staticmethod
+    def _is_holding_at_target(target: float, history: Deque[float]) -> bool:
+        """
+        Checks block temp history to determine if block temp has stabilized at
+        the target temperature. Returns true only if all values in history are
+        within threshold range of target temperature.
+        """
+        if len(history) < PlateTemperatureStatus.MIN_SAMPLES_UNDER_THRESHOLD:
+            # Not enough temp history
+            return False
+        else:
+            return all(
+                abs(target - t) < PlateTemperatureStatus.TEMP_THRESHOLD for t in history
+            )

opentrons/hardware_control/modules/tempdeck.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Dict, Optional
+
+from opentrons.hardware_control.modules.types import (
+    ModuleDisconnectedCallback,
+    TemperatureStatus,
+)
+from opentrons.hardware_control.poller import Reader, Poller
+from typing_extensions import Final
+from opentrons.drivers.types import Temperature
+from opentrons.drivers.temp_deck import (
+    SimulatingDriver,
+    AbstractTempDeckDriver,
+    TempDeckDriver,
+)
+from opentrons.drivers.rpi_drivers.types import USBPort
+from opentrons.hardware_control.execution_manager import ExecutionManager
+from opentrons.hardware_control.modules import update, mod_abc, types, errors
+
+log = logging.getLogger(__name__)
+
+TEMP_POLL_INTERVAL_SECS = 1.0
+SIM_TEMP_POLL_INTERVAL_SECS = TEMP_POLL_INTERVAL_SECS / 20.0
+
+
+class TempDeck(mod_abc.AbstractModule):
+    """Hardware control interface for an attached Temperature Module."""
+
+    MODULE_TYPE = types.ModuleType["TEMPERATURE"]
+    FIRST_GEN2_REVISION = 20
+
+    @classmethod
+    async def build(
+        cls,
+        port: str,
+        usb_port: USBPort,
+        hw_control_loop: asyncio.AbstractEventLoop,
+        execution_manager: Optional[ExecutionManager] = None,
+        poll_interval_seconds: Optional[float] = None,
+        simulating: bool = False,
+        sim_model: Optional[str] = None,
+        sim_serial_number: Optional[str] = None,
+        disconnected_callback: ModuleDisconnectedCallback = None,
+    ) -> "TempDeck":
+        """
+        Build a TempDeck
+
+        Args:
+            port: The port to connect to
+            usb_port: USB Port
+            hw_control_loop: The event loop running in the hardware control thread.
+            execution_manager: Execution manager.
+            poll_interval_seconds: Poll interval override.
+            simulating: whether to build a simulating driver
+            sim_model: The model name used by simulator
+            disconnected_callback: Callback to inform the module controller that the device was disconnected
+
+        Returns:
+            Tempdeck instance
+        """
+        driver: AbstractTempDeckDriver
+        if not simulating:
+            driver = await TempDeckDriver.create(port=port, loop=hw_control_loop)
+            poll_interval_seconds = poll_interval_seconds or TEMP_POLL_INTERVAL_SECS
+        else:
+            driver = SimulatingDriver(
+                sim_model=sim_model, serial_number=sim_serial_number
+            )
+            poll_interval_seconds = poll_interval_seconds or SIM_TEMP_POLL_INTERVAL_SECS
+
+        reader = TempDeckReader(driver=driver)
+        poller = Poller(reader=reader, interval=poll_interval_seconds)
+        module = cls(
+            port=port,
+            usb_port=usb_port,
+            execution_manager=execution_manager,
+            driver=driver,
+            reader=reader,
+            poller=poller,
+            device_info=await driver.get_device_info(),
+            hw_control_loop=hw_control_loop,
+            disconnected_callback=disconnected_callback,
+        )
+
+        try:
+            await poller.start()
+        except Exception:
+            log.exception(f"First read of Temperature Module on port {port} failed")
+
+        return module
+
+    def __init__(
+        self,
+        port: str,
+        usb_port: USBPort,
+        driver: AbstractTempDeckDriver,
+        reader: TempDeckReader,
+        poller: Poller,
+        device_info: Dict[str, str],
+        hw_control_loop: asyncio.AbstractEventLoop,
+        execution_manager: Optional[ExecutionManager] = None,
+        disconnected_callback: ModuleDisconnectedCallback = None,
+    ) -> None:
+        """Constructor"""
+        super().__init__(
+            port=port,
+            usb_port=usb_port,
+            hw_control_loop=hw_control_loop,
+            execution_manager=execution_manager,
+            disconnected_callback=disconnected_callback,
+        )
+        self._device_info = device_info
+        self._driver = driver
+        self._reader = reader
+        self._poller = poller
+
+    async def cleanup(self) -> None:
+        """Stop the poller task."""
+        await self._poller.stop()
+        await self._driver.disconnect()
+
+    @classmethod
+    def name(cls) -> str:
+        return "tempdeck"
+
+    def firmware_prefix(self) -> str:
+        """The prefix used for looking up firmware"""
+        return "temperature-module"
+
+    def model(self) -> str:
+        return self._model_from_revision(self._device_info.get("model"))
+
+    def bootloader(self) -> types.UploadFunction:
+        return update.upload_via_avrdude
+
+    async def start_set_temperature(self, celsius: float) -> None:
+        """Set the target temperature in degrees Celsius.
+
+        Range: 4 to 95 degrees Celsius (QA tested).
+
+        The internal temp range is -9 to 99 °C, which is limited by the two-digit
+        temperature display. Any input outside of this range will be clipped
+        to the nearest limit.
+        """
+        await self.wait_for_is_running()
+        await self._driver.set_temperature(celsius)
+        await self._reader.read()
+
+    async def await_temperature(self, awaiting_temperature: Optional[float]) -> None:
+        """Await a target temperature in degrees Celsius.
+
+        Polls Temperature Module's temperature until
+        the specified temperature is reached.
+
+        Args:
+            temperature: The temperature to wait for.
+                If `None` (recommended), the module's target will be used.
+                Specifying any value other than the current target
+                may produce unpredictable behavior.
+        """
+        if self.is_simulated:
+            return
+
+        await self.wait_for_is_running()
+        await self._reader.read()
+
+        async def _await_temperature() -> None:
+            if awaiting_temperature is None:
+                while self.status != TemperatureStatus.HOLDING:
+                    await self._poller.wait_next_poll()
+            elif self.status == TemperatureStatus.HEATING:
+                while self.temperature < awaiting_temperature:
+                    await self._poller.wait_next_poll()
+            elif self.status == TemperatureStatus.COOLING:
+                while self.temperature > awaiting_temperature:
+                    await self._poller.wait_next_poll()
+
+        t = self._loop.create_task(_await_temperature())
+        self.make_cancellable(t)
+        await t
+
+    async def deactivate(self, must_be_running: bool = True) -> None:
+        """Stop heating/cooling and turn off the fan"""
+        if must_be_running:
+            await self.wait_for_is_running()
+        await self._driver.deactivate()
+        await self._reader.read()
+
+    @property
+    def device_info(self) -> Dict[str, str]:
+        return self._device_info
+
+    @property
+    def live_data(self) -> types.LiveData:
+        data: types.TemperatureModuleData = {
+            "currentTemp": self.temperature,
+            "targetTemp": self.target,
+        }
+        return {
+            "status": self.status,
+            "data": data,
+        }
+
+    @property
+    def temperature(self) -> float:
+        return self._reader.temperature.current
+
+    @property
+    def target(self) -> Optional[float]:
+        return self._reader.temperature.target
+
+    @property
+    def status(self) -> TemperatureStatus:
+        return self._get_status(self._reader.temperature)
+
+    @property
+    def is_simulated(self) -> bool:
+        return isinstance(self._driver, SimulatingDriver)
+
+    async def prep_for_update(self) -> str:
+        model = self._device_info and self._device_info.get("model")
+        if model in ("temp_deck_v1", "temp_deck_v1.1", "temp_deck_v2"):
+            raise errors.UpdateError(
+                "This Temperature Module can't be updated."
+                "Please contact Opentrons Support."
+            )
+        await self._poller.stop()
+        await self._driver.enter_programming_mode()
+        new_port = await update.find_bootloader_port()
+        return new_port or self.port
+
+    def has_available_update(self) -> bool:
+        """Override of abc implementation to suppress update notifications
+        for v1, v1.1, and v2 temperature modules which cannot be updated"""
+        if not self._device_info:
+            model = None
+        else:
+            model = self._device_info.get("model")
+        if model in {"temp_deck_v1", "temp_deck_v1.1", "temp_deck_v2", None}:
+            return False
+        return super().has_available_update()
+
+    @staticmethod
+    def _get_status(temperature: Temperature) -> TemperatureStatus:
+        """
+        Determine the status from the temperature.
+
+        Args:
+            temperature: A Temperature instance
+
+        Returns:
+            The status
+        """
+        DELTA: Final = 0.7
+        status = TemperatureStatus.IDLE
+        if temperature.target is not None:
+            diff = temperature.target - temperature.current
+            if abs(diff) < DELTA:  # To avoid status fluctuation near target
+                status = TemperatureStatus.HOLDING
+            elif diff < 0:
+                status = TemperatureStatus.COOLING
+            else:
+                status = TemperatureStatus.HEATING
+        return status
+
+    @staticmethod
+    def _model_from_revision(revision: Optional[str]) -> str:
+        """Defines the revision -> model mapping"""
+        if not revision or "v" not in revision:
+            log.error(f"bad revision: {revision}")
+            return "temperatureModuleV1"
+        try:
+            revision_num = float(revision.split("v")[-1])
+        except (ValueError, TypeError):
+            # none or corrupt
+            log.exception("no revision")
+            return "temperatureModuleV1"
+
+        if revision_num < TempDeck.FIRST_GEN2_REVISION:
+            return "temperatureModuleV1"
+        else:
+            return "temperatureModuleV2"
+
+
+class TempDeckReader(Reader):
+    """Reads data from an attached Temperature Module."""
+
+    temperature: Temperature
+
+    def __init__(self, driver: AbstractTempDeckDriver) -> None:
+        self.temperature = Temperature(current=25, target=None)
+        self._driver = driver
+
+    async def read(self) -> None:
+        """Read the module's current and target temperatures."""
+        self.temperature = await self._driver.get_temperature()