opentrons 8.6.0__py3-none-any.whl

opentrons/hardware_control/modules/types.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+from enum import Enum
+from dataclasses import dataclass
+from typing import (
+    Dict,
+    List,
+    NamedTuple,
+    Callable,
+    Any,
+    Tuple,
+    Awaitable,
+    Union,
+    Optional,
+    cast,
+    TYPE_CHECKING,
+    TypeGuard,
+)
+from typing_extensions import TypedDict
+from pathlib import Path
+
+from opentrons.drivers.flex_stacker.types import (
+    LimitSwitchStatus,
+    PlatformStatus,
+    StackerAxis,
+)
+from opentrons.drivers.rpi_drivers.types import USBPort
+
+if TYPE_CHECKING:
+    from opentrons_shared_data.module.types import (
+        ThermocyclerModuleType,
+        MagneticModuleType,
+        TemperatureModuleType,
+        HeaterShakerModuleType,
+        MagneticBlockType,
+        AbsorbanceReaderType,
+        FlexStackerModuleType,
+    )
+
+
+class ThermocyclerStepBase(TypedDict):
+    temperature: float
+
+
+class ThermocyclerStep(ThermocyclerStepBase, total=False):
+    hold_time_seconds: float
+    hold_time_minutes: float
+
+
+class ThermocyclerCycle(TypedDict):
+    steps: List[ThermocyclerStep]
+    repetitions: int
+
+
+UploadFunction = Callable[[str, str, Dict[str, Any]], Awaitable[Tuple[bool, str]]]
+
+
+ModuleDisconnectedCallback = Optional[Callable[[str, str | None], None]]
+
+
+class MagneticModuleData(TypedDict):
+    engaged: bool
+    height: float
+
+
+class TemperatureModuleData(TypedDict):
+    currentTemp: float
+    targetTemp: float | None
+
+
+class HeaterShakerData(TypedDict):
+    temperatureStatus: str
+    speedStatus: str
+    labwareLatchStatus: str
+    currentTemp: float
+    targetTemp: float | None
+    currentSpeed: int
+    targetSpeed: int | None
+    errorDetails: str | None
+
+
+class ThermocyclerData(TypedDict):
+    lid: str
+    lidTarget: float | None
+    lidTemp: float
+    lidTempStatus: str
+    currentTemp: float | None
+    targetTemp: float | None
+    holdTime: float | None
+    rampRate: float | None
+    currentCycleIndex: int | None
+    totalCycleCount: int | None
+    currentStepIndex: int | None
+    totalStepCount: int | None
+
+
+class AbsorbanceReaderData(TypedDict):
+    uptime: int
+    deviceStatus: str
+    lidStatus: str
+    platePresence: str
+    measureMode: str
+    sampleWavelengths: List[int]
+    referenceWavelength: int
+
+
+class FlexStackerData(TypedDict):
+    latchState: str
+    platformState: str
+    hopperDoorState: str
+    installDetected: bool
+    errorDetails: str | None
+
+
+ModuleData = Union[
+    Dict[Any, Any],  # This allows an empty dict as module data
+    MagneticModuleData,
+    TemperatureModuleData,
+    HeaterShakerData,
+    ThermocyclerData,
+    AbsorbanceReaderData,
+    FlexStackerData,
+]
+
+
+class ModuleDataValidator:
+    @classmethod
+    def is_magnetic_module_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[MagneticModuleData]:
+        return data is not None and "engaged" in data.keys()
+
+    @classmethod
+    def is_temperature_module_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[TemperatureModuleData]:
+        return data is not None and "targetTemp" in data.keys()
+
+    @classmethod
+    def is_heater_shaker_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[HeaterShakerData]:
+        return data is not None and "labwareLatchStatus" in data.keys()
+
+    @classmethod
+    def is_thermocycler_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[ThermocyclerData]:
+        return data is not None and "lid" in data.keys()
+
+    @classmethod
+    def is_absorbance_reader_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[AbsorbanceReaderData]:
+        return data is not None and "uptime" in data.keys()
+
+    @classmethod
+    def is_flex_stacker_data(
+        cls, data: ModuleData | None
+    ) -> TypeGuard[FlexStackerData]:
+        return data is not None and "platformState" in data.keys()
+
+
+class LiveData(TypedDict):
+    status: str
+    data: ModuleData | None
+
+
+class ModuleType(str, Enum):
+    THERMOCYCLER: ThermocyclerModuleType = "thermocyclerModuleType"
+    TEMPERATURE: TemperatureModuleType = "temperatureModuleType"
+    MAGNETIC: MagneticModuleType = "magneticModuleType"
+    HEATER_SHAKER: HeaterShakerModuleType = "heaterShakerModuleType"
+    MAGNETIC_BLOCK: MagneticBlockType = "magneticBlockType"
+    ABSORBANCE_READER: AbsorbanceReaderType = "absorbanceReaderType"
+    FLEX_STACKER: FlexStackerModuleType = "flexStackerModuleType"
+
+    @classmethod
+    def from_model(cls, model: ModuleModel) -> ModuleType:
+        if isinstance(model, MagneticModuleModel):
+            return cls.MAGNETIC
+        if isinstance(model, TemperatureModuleModel):
+            return cls.TEMPERATURE
+        if isinstance(model, ThermocyclerModuleModel):
+            return cls.THERMOCYCLER
+        if isinstance(model, HeaterShakerModuleModel):
+            return cls.HEATER_SHAKER
+        if isinstance(model, MagneticBlockModel):
+            return cls.MAGNETIC_BLOCK
+        if isinstance(model, AbsorbanceReaderModel):
+            return cls.ABSORBANCE_READER
+        if isinstance(model, FlexStackerModuleModel):
+            return cls.FLEX_STACKER
+
+    @classmethod
+    def to_module_fixture_id(cls, module_type: ModuleType) -> str:
+        if module_type == ModuleType.THERMOCYCLER:
+            # Thermocyclers are "loaded" in B1 only
+            return "thermocyclerModuleV2Front"
+        if module_type == ModuleType.TEMPERATURE:
+            return "temperatureModuleV2"
+        if module_type == ModuleType.HEATER_SHAKER:
+            return "heaterShakerModuleV1"
+        if module_type == ModuleType.MAGNETIC_BLOCK:
+            return "magneticBlockV1"
+        if module_type == ModuleType.ABSORBANCE_READER:
+            return "absorbanceReaderV1"
+        if module_type == ModuleType.FLEX_STACKER:
+            return "flexStackerModuleV1"
+        else:
+            raise ValueError(
+                f"Module Type {module_type} does not have a related fixture ID."
+            )
+
+
+class MagneticModuleModel(str, Enum):
+    MAGNETIC_V1: str = "magneticModuleV1"
+    MAGNETIC_V2: str = "magneticModuleV2"
+
+
+class TemperatureModuleModel(str, Enum):
+    TEMPERATURE_V1: str = "temperatureModuleV1"
+    TEMPERATURE_V2: str = "temperatureModuleV2"
+
+
+class ThermocyclerModuleModel(str, Enum):
+    THERMOCYCLER_V1: str = "thermocyclerModuleV1"
+    THERMOCYCLER_V2: str = "thermocyclerModuleV2"
+
+
+class HeaterShakerModuleModel(str, Enum):
+    HEATER_SHAKER_V1: str = "heaterShakerModuleV1"
+
+
+class MagneticBlockModel(str, Enum):
+    MAGNETIC_BLOCK_V1: str = "magneticBlockV1"
+
+
+class AbsorbanceReaderModel(str, Enum):
+    ABSORBANCE_READER_V1: str = "absorbanceReaderV1"
+
+
+class FlexStackerModuleModel(str, Enum):
+    FLEX_STACKER_V1: str = "flexStackerModuleV1"
+
+
+def module_model_from_string(model_string: str) -> ModuleModel:
+    for model_enum in {
+        MagneticModuleModel,
+        TemperatureModuleModel,
+        ThermocyclerModuleModel,
+        HeaterShakerModuleModel,
+        MagneticBlockModel,
+        AbsorbanceReaderModel,
+        FlexStackerModuleModel,
+    }:
+        try:
+            return cast(ModuleModel, model_enum(model_string))
+        except ValueError:
+            pass
+    raise ValueError(f"No such module model {model_string}")
+
+
+@dataclass(kw_only=True)
+class ModuleAtPort:
+    port: str
+    name: str
+    serial: Optional[str] = None
+    usb_port: USBPort = USBPort(name="", port_number=0)
+
+
+@dataclass(kw_only=True)
+class SimulatingModule:
+    serial_number: str
+    model: Optional[str]
+
+
+@dataclass(kw_only=True)
+class SimulatingModuleAtPort(ModuleAtPort, SimulatingModule):
+    pass
+
+
+class BundledFirmware(NamedTuple):
+    """Represents a versioned firmware file, generally bundled into the fs"""
+
+    version: str
+    path: Path
+
+    def __repr__(self) -> str:
+        return f"<BundledFirmware {self.version}, path={self.path}>"
+
+
+class ModuleInfo(NamedTuple):
+    model: str  # A module model such as "magneticModuleV2"
+    fw_version: str  # The version of the firmware
+    hw_revision: str  # the revision of the hardware
+    serial: str  # the serial number
+
+
+# TODO(mc, 2022-01-18): replace with enum
+ModuleModel = Union[
+    MagneticModuleModel,
+    TemperatureModuleModel,
+    ThermocyclerModuleModel,
+    HeaterShakerModuleModel,
+    MagneticBlockModel,
+    AbsorbanceReaderModel,
+    FlexStackerModuleModel,
+]
+
+
+class MagneticStatus(str, Enum):
+    ENGAGED = "engaged"
+    DISENGAGED = "disengaged"
+
+
+class TemperatureStatus(str, Enum):
+    HOLDING = "holding at target"
+    COOLING = "cooling"
+    HEATING = "heating"
+    IDLE = "idle"
+    ERROR = "error"
+
+
+class SpeedStatus(str, Enum):
+    HOLDING = "holding at target"
+    ACCELERATING = "speeding up"
+    DECELERATING = "slowing down"
+    IDLE = "idle"
+    ERROR = "error"
+
+
+class HeaterShakerStatus(str, Enum):
+    IDLE = "idle"
+    RUNNING = "running"
+    ERROR = "error"
+
+
+class AbsorbanceReaderStatus(str, Enum):
+    IDLE = "idle"
+    MEASURING = "measuring"
+    ERROR = "error"
+
+
+class LidStatus(str, Enum):
+    ON = "on"
+    OFF = "off"
+    UNKNOWN = "unknown"
+    ERROR = "error"
+
+
+class FlexStackerStatus(str, Enum):
+    IDLE = "idle"
+    DISPENSING = "dispensing"
+    STORING = "storing"
+    ERROR = "error"
+
+
+class PlatformState(str, Enum):
+    UNKNOWN = "unknown"
+    EXTENDED = "extended"
+    RETRACTED = "retracted"
+    MISSING = "missing"
+
+    @classmethod
+    def from_status(cls, status: PlatformStatus) -> "PlatformState":
+        """Get the state from the platform status."""
+        if status.E and not status.R:
+            return cls.EXTENDED
+        if status.R and not status.E:
+            return cls.RETRACTED
+        return cls.UNKNOWN
+
+
+class StackerAxisState(str, Enum):
+    UNKNOWN = "unknown"
+    EXTENDED = "extended"
+    RETRACTED = "retracted"
+
+    @classmethod
+    def from_status(
+        cls, status: LimitSwitchStatus, axis: StackerAxis
+    ) -> "StackerAxisState":
+        """Get the axis state from the limit switch status."""
+        match axis:
+            case StackerAxis.X:
+                if status.XE and not status.XR:
+                    return cls.EXTENDED
+                if status.XR and not status.XE:
+                    return cls.RETRACTED
+            case StackerAxis.Z:
+                if status.ZE and not status.ZR:
+                    return cls.EXTENDED
+                if status.ZR and not status.ZE:
+                    return cls.RETRACTED
+            case StackerAxis.L:
+                return cls.EXTENDED if status.LR else cls.RETRACTED
+        return cls.UNKNOWN
+
+
+class LatchState(str, Enum):
+    CLOSED = "closed"
+    OPENED = "opened"
+
+    @classmethod
+    def from_state(cls, state: StackerAxisState) -> "LatchState":
+        """Get the latch state from the axis state."""
+        return cls.CLOSED if state == StackerAxisState.EXTENDED else cls.OPENED
+
+
+class HopperDoorState(str, Enum):
+    CLOSED = "closed"
+    OPENED = "opened"
+
+    @classmethod
+    def from_state(cls, state: bool) -> "HopperDoorState":
+        """Get the hopper door state from the door state boolean."""
+        return cls.CLOSED if state else cls.OPENED

opentrons/hardware_control/modules/update.py

@@ -0,0 +1,255 @@
+import asyncio
+import logging
+import os
+from pathlib import Path
+from glob import glob
+from typing import Any, AsyncGenerator, Dict, Tuple, Union
+
+from .errors import UpdateError
+from .mod_abc import AbstractModule
+from opentrons.hardware_control.threaded_async_lock import ThreadedAsyncLock
+from contextlib import asynccontextmanager
+
+log = logging.getLogger(__name__)
+
+_update_transition_lock = ThreadedAsyncLock()
+
+
+@asynccontextmanager
+async def protect_update_transition() -> AsyncGenerator[None, None]:
+    async with _update_transition_lock.lock():
+        yield
+
+
+async def update_firmware(
+    module: AbstractModule,
+    firmware_file: Union[str, Path],
+) -> None:
+    """Apply update of given firmware file to given module.
+
+    raises an UpdateError with the reason for the failure.
+    """
+    async with protect_update_transition():
+        flash_port_or_dfu_serial = await module.prep_for_update()
+        kwargs: Dict[str, Any] = {
+            "stdout": asyncio.subprocess.PIPE,
+            "stderr": asyncio.subprocess.PIPE,
+            "module": module,
+        }
+        successful, res = await module.bootloader()(
+            flash_port_or_dfu_serial, str(firmware_file), kwargs
+        )
+        if not successful:
+            log.info(f"Bootloader reponse: {res}")
+            raise UpdateError(res)
+
+
+async def find_bootloader_port() -> str:
+    """
+    Finds the port of an Opentrons Module that has entered its bootloader.
+    The bootloader port shows up as 'ot_module_(avrdude|samba)_bootloader'
+    on the pi; return found port.
+    """
+
+    for attempt in range(3):
+        bootloader_ports = glob("/dev/ot_module_*_bootloader*")
+        if bootloader_ports:
+            if len(bootloader_ports) == 1:
+                log.info(f"Found bootloader at port {bootloader_ports[0]}")
+                return bootloader_ports[0]
+            elif len(bootloader_ports) > 1:
+                raise OSError("Multiple new bootloader ports" "found on mode switch")
+        await asyncio.sleep(2)
+    raise Exception("No ot_module bootloaders found in /dev. Try again")
+
+
+async def find_dfu_device(pid: str, expected_device_count: int) -> str:
+    """
+    Find the dfu device and return its serial number (separate from module serial).
+
+    Args:
+        - pid: The USB Product ID of the device
+        - expected_device_count: The expected number of "devices" for dfu-util
+        to find for this PID. This is necessary because most STM32 MCU's
+        will enumerate with multiple DFU devices, representing the
+        separate programmable memory regions on the device. If more than
+        this many devices are found, it is assumed that either the wrong
+        module is in DFU mode *or* multiple modules are in DFU mode.
+    """
+    retries = 5
+    log.info(f"Searching for a dfu device with PID {pid}")
+    while retries != 0:
+        retries -= 1
+        await asyncio.sleep(1)
+        proc = await asyncio.create_subprocess_exec(
+            "dfu-util",
+            "-l",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        await proc.wait()
+        stdout, stderr = await proc.communicate()
+
+        if stdout is None and stderr is None:
+            continue
+        if stderr:
+            raise RuntimeError(f"Error finding dfu device: {stderr.decode()}")
+
+        result = stdout.decode()
+        if pid not in result:
+            # It could take a few seconds for the device to show up
+            continue
+        devices_found = 0
+        for line in result.splitlines():
+            if pid in line:
+                log.info(f"Found device with PID {pid}")
+                devices_found += 1
+                serial = line[(line.find("serial=") + 7) :]
+        if devices_found == expected_device_count:
+            # Heater-Shaker has 2 unique endpoints, Thermocycler has 3
+            return serial
+        elif devices_found > expected_device_count:
+            raise OSError("Multiple new bootloader devices" "found on mode switch")
+
+    raise RuntimeError(
+        "Could not update firmware via dfu. Possible issues- dfu-util"
+        " not working or specified dfu device not found"
+    )
+
+
+async def upload_via_avrdude(
+    port: str, firmware_file_path: str, kwargs: Dict[str, Any]
+) -> Tuple[bool, str]:
+    """
+    Run firmware upload command for hardware module with avrdude bootloader.
+
+    Returns tuple of success boolean and message from bootloader.
+    """
+    # avrdude_options
+    PART_NO = "atmega32u4"
+    PROGRAMMER_ID = "avr109"
+    BAUDRATE = "57600"
+
+    config_file_path = Path("/etc/avrdude.conf")
+    proc = await asyncio.create_subprocess_exec(
+        "avrdude",
+        "-C{}".format(config_file_path),
+        "-v",
+        "-p{}".format(PART_NO),
+        "-c{}".format(PROGRAMMER_ID),
+        "-P{}".format(port),
+        "-b{}".format(BAUDRATE),
+        "-D",
+        "-Uflash:w:{}:i".format(firmware_file_path),
+        stdout=kwargs["stdout"],
+        stderr=kwargs["stderr"],
+    )
+    await proc.wait()
+
+    _result = await proc.communicate()
+    result = _result[1].decode()
+    avrdude_res = _format_avrdude_response(result)
+    if avrdude_res[0]:
+        log.debug(result)
+    else:
+        log.error(
+            "Failed to update module firmware for {}: {}".format(port, avrdude_res[1])
+        )
+    return avrdude_res
+
+
+def _format_avrdude_response(raw_response: str) -> Tuple[bool, str]:
+    avrdude_log = ""
+    for line in raw_response.splitlines():
+        if "avrdude:" in line and line != raw_response.splitlines()[1]:
+            avrdude_log += line.lstrip("avrdude:") + ".."
+            if "flash verified" in line:
+                return True, line.lstrip("avrdude: ")
+    return False, avrdude_log
+
+
+async def upload_via_bossa(
+    port: str, firmware_file_path: str, kwargs: Dict[str, Any]
+) -> Tuple[bool, str]:
+    """
+    Run firmware upload command for hardware module with SAMBA bootloader.
+
+    Returns tuple of success boolean and message from bootloader.
+    """
+    # bossac -p/dev/ttyACM1 -e -w -v -R --offset=0x2000
+    #   modules/thermo-cycler/production/firmware/thermo-cycler-arduino.ino.bin
+    # NOTE: bossac cannot traverse symlinks to port,
+    # so we resolve to real path
+    resolved_symlink = os.path.realpath(port)
+    log.info(
+        f"device at symlinked port: {port} " f"resolved to path: {resolved_symlink}"
+    )
+    bossa_args = [
+        "bossac",
+        f"-p{resolved_symlink}",
+        "-e",
+        "-w",
+        "-v",
+        "-R",
+        "--offset=0x2000",
+        f"{firmware_file_path}",
+    ]
+    proc = await asyncio.create_subprocess_exec(
+        *bossa_args, stdout=kwargs["stdout"], stderr=kwargs["stderr"]
+    )
+    stdout, stderr = await proc.communicate()
+    res = stdout.decode()
+    if "Verify successful" in res:
+        log.debug(res)
+        return True, res
+    elif stderr:
+        log.error(f"Failed to update module firmware for {port}: {res}")
+        log.error(f"Error given: {stderr.decode()}")
+        return False, res
+    return False, ""
+
+
+async def upload_via_dfu(
+    dfu_serial: str, firmware_file_path: str, kwargs: Dict[str, Any]
+) -> Tuple[bool, str]:
+    """Run firmware upload command for DFU.
+
+    Unlike other firmware upload methods, this one doesn't take a `port` argument since
+    the module isn't recognized as a cdc device in dfu mode and hence doesn't get
+    a port. The firmware upload utility, dfu-util, looks for the specific module
+    by searching for available dfu devices. Since we check beforehand that only one
+    dfu device is available during the upload process, this check is sufficient for us.
+
+    In the future, if we want to make sure that the dfu device available is in fact
+    the one we seek, then we can ask dfu-util to check for available dfu devices with
+    a specific serial number (unrelated to Opentrons' module serial numbers).
+    Hence, this method takes a `dfu_serial` argument instead.
+
+    Returns tuple of success boolean and message from bootloader
+    """
+    log.info("Starting firmware upload via dfu util")
+    dfu_args = [
+        "dfu-util",
+        "-a 0",
+        "-s 0x08000000:leave",
+        f"-D{firmware_file_path}",
+        "-R",
+    ]
+    proc = await asyncio.create_subprocess_exec(
+        *dfu_args, stdout=kwargs["stdout"], stderr=kwargs["stderr"]
+    )
+    stdout, stderr = await proc.communicate()
+    res = stdout.decode()
+
+    if "File downloaded successfully" in res:
+        log.debug(res)
+        log.info("Firmware upload successful")
+        return True, res
+    else:
+        log.error(
+            f"Failed to update module firmware for {dfu_serial}. "
+            # It isn't easy to decipher the issue from stderror alone
+            f"stdout: {res} \n"
+            f"stderr: {stderr.decode()}"
+        )
+        return False, res