opentrons 8.6.0a1__py3-none-any.whl

opentrons/drivers/flex_stacker/types.py

@@ -0,0 +1,367 @@
+from enum import Enum
+from dataclasses import dataclass, fields
+from typing import List, Dict, Optional
+
+from opentrons.drivers.command_builder import CommandBuilder
+
+
+class GCODE(str, Enum):
+
+    MOVE_TO = "G0"
+    MOVE_TO_SWITCH = "G5"
+    HOME_AXIS = "G28"
+    STOP_MOTORS = "M0"
+    ENABLE_MOTORS = "M17"
+    GET_ESTOP_ENGAGED = "M112"
+    GET_RESET_REASON = "M114"
+    DEVICE_INFO = "M115"
+    GET_LIMIT_SWITCH = "M119"
+    GET_MOVE_PARAMS = "M120"
+    GET_PLATFORM_SENSOR = "M121"
+    GET_DOOR_SWITCH = "M122"
+    GET_INSTALL_DETECTED = "M123"
+    GET_STALLGUARD_THRESHOLD = "M911"
+    GET_MOTOR_DRIVER_REGISTER = "M920"
+    GET_TOF_SENSOR_STATUS = "M215"
+    GET_TOF_DRIVER_REGISTER = "M222"
+    GET_TOF_MEASUREMENT = "M226"
+    ENABLE_TOF_SENSOR = "M224"
+    MANAGE_TOF_MEASUREMENT = "M225"
+    SET_TOF_CONFIGURATION = "M227"
+    GET_TOF_CONFIGURATION = "M228"
+    SET_LED = "M200"
+    SET_SERIAL_NUMBER = "M996"
+    SET_RUN_CURRENT = "M906"
+    SET_IHOLD_CURRENT = "M907"
+    SET_STALLGUARD = "M910"
+    SET_MOTOR_DRIVER_REGISTER = "M921"
+    SET_TOF_DRIVER_REGISTER = "M223"
+    ENTER_BOOTLOADER = "dfu"
+
+    def build_command(self) -> CommandBuilder:
+        """Build command."""
+        return CommandBuilder().add_gcode(self)
+
+
+STACKER_VID = 0x483
+STACKER_PID = 0xEF24
+STACKER_FREQ = 115200
+
+
+class HardwareRevision(Enum):
+    """Hardware Revision."""
+
+    NFF = "nff"
+    EVT = "a1"
+    DVT = "b1"
+    PVT = "b2"
+
+
+@dataclass
+class StackerInfo:
+    """Stacker Info."""
+
+    fw: str
+    hw: HardwareRevision
+    sn: str
+    rr: int = 0
+
+    def to_dict(self) -> Dict[str, str]:
+        """Build command."""
+        return {
+            "serial": self.sn,
+            "version": self.fw,
+            "model": self.hw.value,
+            "reset_reason": str(self.rr),
+        }
+
+
+class StackerAxis(str, Enum):
+    """Stacker Axis."""
+
+    X = "X"
+    Z = "Z"
+    L = "L"
+
+
+class TOFSensor(str, Enum):
+    """Stacker TOF sensor."""
+
+    X = "X"
+    Z = "Z"
+
+
+class LEDColor(Enum):
+    """Stacker LED Color."""
+
+    WHITE = 0
+    RED = 1
+    GREEN = 2
+    BLUE = 3
+    YELLOW = 4
+
+    @classmethod
+    def from_name(cls, name: str) -> "LEDColor":
+        match (name.lower()):
+            case "red":
+                return cls.RED
+            case "green":
+                return cls.GREEN
+            case "blue":
+                return cls.BLUE
+            case "yellow":
+                return cls.YELLOW
+            case _:
+                return cls.WHITE
+
+    def to_name(self) -> "str":
+        return self.name.lower()
+
+
+class LEDPattern(Enum):
+    """Stacker LED Pattern."""
+
+    STATIC = 0
+    FLASH = 1
+    PULSE = 2
+    CONFIRM = 3
+
+
+class Direction(Enum):
+    """Direction."""
+
+    RETRACT = 0  # negative
+    EXTEND = 1  # positive
+
+    def __str__(self) -> str:
+        """Convert to tag for clear logging."""
+        return self.name.lower()
+
+    def polarity(self) -> str:
+        """Convert to polarity tag for testing."""
+        return "positive" if self == Direction.EXTEND else "negative"
+
+    def opposite(self) -> "Direction":
+        """Get opposite direction."""
+        return Direction.EXTEND if self == Direction.RETRACT else Direction.RETRACT
+
+    def distance(self, distance: float) -> float:
+        """Get signed distance, where retract direction is negative."""
+        return distance * -1 if self == Direction.RETRACT else distance
+
+
+class TOFSensorState(Enum):
+    """TOF Sensor state."""
+
+    DISABLED = 0
+    INITIALIZING = 1
+    IDLE = 2
+    MEASURING = 3
+    ERROR = 4
+
+
+class TOFSensorMode(Enum):
+    """The mode the sensor is in."""
+
+    UNKNOWN = 0
+    MEASURE = 0x03
+    BOOTLOADER = 0x80
+
+
+@dataclass
+class LimitSwitchStatus:
+    """Stacker Limit Switch Statuses."""
+
+    XE: bool
+    XR: bool
+    ZE: bool
+    ZR: bool
+    LR: bool
+
+    @classmethod
+    def get_fields(cls) -> List[str]:
+        """Get fields."""
+        return [f.name for f in fields(cls)]
+
+    def get(self, axis: StackerAxis, direction: Direction) -> bool:
+        """Get limit switch status."""
+        if axis == StackerAxis.X:
+            return self.XE if direction == Direction.EXTEND else self.XR
+        if axis == StackerAxis.Z:
+            return self.ZE if direction == Direction.EXTEND else self.ZR
+        if direction == Direction.EXTEND:
+            raise ValueError("Latch does not have extent limit switch")
+        return self.LR
+
+
+@dataclass
+class PlatformStatus:
+    """Stacker Platform Statuses."""
+
+    E: bool
+    R: bool
+
+    @classmethod
+    def get_fields(cls) -> List[str]:
+        """Get fields."""
+        return [f.name for f in fields(cls)]
+
+    def get(self, direction: Direction) -> bool:
+        """Get platform status."""
+        return self.E if direction == Direction.EXTEND else self.R
+
+    def to_dict(self) -> Dict[str, bool]:
+        """Dict of the data."""
+        return {
+            "extent": self.E,
+            "retract": self.R,
+        }
+
+
+@dataclass
+class TOFSensorStatus:
+    """Stacker TOF sensor status."""
+
+    sensor: TOFSensor
+    state: TOFSensorState
+    mode: TOFSensorMode
+    ok: bool
+
+
+@dataclass
+class MoveParams:
+    """Move Parameters."""
+
+    max_speed: float
+    acceleration: float
+    max_speed_discont: float
+
+    @classmethod
+    def get_fields(cls) -> List[str]:
+        """Get parsing fields."""
+        return ["V", "A", "D"]
+
+    def update(
+        self,
+        max_speed: Optional[float] = None,
+        acceleration: Optional[float] = None,
+        max_speed_discont: Optional[float] = None,
+    ) -> "MoveParams":
+        """Update the move parameters and return a new object."""
+        return MoveParams(
+            max_speed=max_speed if max_speed is not None else self.max_speed,
+            acceleration=acceleration
+            if acceleration is not None
+            else self.acceleration,
+            max_speed_discont=max_speed_discont
+            if max_speed_discont is not None
+            else self.max_speed_discont,
+        )
+
+
+@dataclass
+class AxisParams:
+    """Axis Parameters."""
+
+    run_current: float
+    hold_current: float
+    move_params: MoveParams
+
+
+@dataclass
+class StallGuardParams:
+    """StallGuard Parameters."""
+
+    axis: StackerAxis
+    enabled: bool
+    threshold: int
+
+
+class MoveResult(str, Enum):
+    """The result of a move command."""
+
+    NO_ERROR = "ok"
+    STALL_ERROR = "stall"
+    UNKNOWN_ERROR = "unknown"
+
+
+class MeasurementKind(Enum):
+    """The kind of measurement to request."""
+
+    HISTOGRAM = 0
+
+
+class SpadMapID(Enum):
+    """The spad map id for the TOF sensor."""
+
+    SPAD_MAP_ID_1 = 1
+    # 3x3 macro 1 mode 33°x47° FoV off center
+    SPAD_MAP_ID_2 = 2
+    # 3x3 macro 2 mode 33°x47° FoV
+    SPAD_MAP_ID_3 = 3
+    # 3x3 wide mode 41°x52° FoV
+    SPAD_MAP_ID_6 = 6
+    # 3x3 mode 33°x32° FoV, checkerboard
+    SPAD_MAP_ID_11 = 11
+    # 3x3 mode 33°x32° FoV, inverted checkerboard
+    SPAD_MAP_ID_12 = 12
+    # User defined mode, single measurement mode
+    SPAD_MAP_ID_14 = 14
+
+
+class ActiveRange(Enum):
+    """The active range for the TOF sensor."""
+
+    NOT_SUPPORTED = 0
+    SHORT_RANGE = 0x6E
+    LONG_RANGE = 0x6F
+
+
+@dataclass
+class TOFMeasurement:
+    """The start measurement data."""
+
+    sensor: TOFSensor
+    kind: MeasurementKind
+    cancelled: bool
+    total_bytes: int
+
+
+@dataclass
+class TOFMeasurementFrame:
+    """Stacker TOF measurement frame."""
+
+    sensor: TOFSensor
+    frame_id: int
+    data: bytes
+
+
+@dataclass
+class TOFMeasurementResult:
+    """Stacker TOF measurement result."""
+
+    sensor: TOFSensor
+    kind: MeasurementKind
+    bins: Dict[int, List[float]]
+
+
+@dataclass
+class TOFDetection:
+    """Labware detection parameters."""
+
+    sensor: TOFSensor
+    zones: List[int]
+    bins: list[int]
+    threshold: int
+
+
+@dataclass
+class TOFConfiguration:
+    """Stacker TOF configuration."""
+
+    sensor: TOFSensor
+    spad_map_id: SpadMapID
+    active_range: Optional[ActiveRange]
+    kilo_iterations: Optional[int]
+    report_period_ms: Optional[int]
+    histogram_dump: Optional[bool]

opentrons/drivers/flex_stacker/utils.py

@@ -0,0 +1,19 @@
+NUMBER_OF_ZONES = 10
+NUMBER_OF_BINS = 128
+
+
+def validate_histogram_frame(data: bytes, next_frame_id: int) -> bool:
+    """Validate Histogram frame, Raise error if invalid."""
+    start_delimn = data[0]
+    assert (
+        start_delimn == 0x81  # histogram start byte
+    ), f"Invalid delimn, {hex(start_delimn)} != 0x81."
+    frame_id = data[4]
+    assert (
+        next_frame_id == frame_id
+    ), f"Invalid frame id, expected {next_frame_id} got {frame_id}."
+    frame_len = data[5]
+    assert (
+        frame_len == 128  # len is always 128
+    ), f"Invalid frame length, expected 128 got {frame_len}."
+    return True

opentrons/drivers/heater_shaker/__init__.py

@@ -0,0 +1,5 @@
+from .driver import HeaterShakerDriver
+from .simulator import SimulatingDriver
+from .abstract import AbstractHeaterShakerDriver
+
+__all__ = ["HeaterShakerDriver", "SimulatingDriver", "AbstractHeaterShakerDriver"]

opentrons/drivers/heater_shaker/abstract.py

@@ -0,0 +1,76 @@
+from abc import ABC, abstractmethod
+from typing import Dict
+
+from opentrons.drivers.types import Temperature, RPM, HeaterShakerLabwareLatchStatus
+
+
+class AbstractHeaterShakerDriver(ABC):
+    @abstractmethod
+    async def connect(self) -> None:
+        """Connect to heater-shaker"""
+        ...
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Disconnect from heater-shaker"""
+        ...
+
+    @abstractmethod
+    async def is_connected(self) -> bool:
+        """Check connection to heater-shaker"""
+        ...
+
+    @abstractmethod
+    async def open_labware_latch(self) -> None:
+        """Send open-labware-latch command"""
+        ...
+
+    @abstractmethod
+    async def close_labware_latch(self) -> None:
+        """Send close-labware-latch command"""
+        ...
+
+    @abstractmethod
+    async def set_temperature(self, temperature: float) -> None:
+        """Send set-temperature command"""
+        ...
+
+    @abstractmethod
+    async def get_temperature(self) -> Temperature:
+        """Send get-temperature command"""
+        ...
+
+    @abstractmethod
+    async def set_rpm(self, rpm: int) -> None:
+        """Send set-rpm command"""
+        ...
+
+    @abstractmethod
+    async def get_rpm(self) -> RPM:
+        """Send get-rpm command"""
+        ...
+
+    @abstractmethod
+    async def get_labware_latch_status(self) -> HeaterShakerLabwareLatchStatus:
+        """Send get-labware-latch-status command"""
+        ...
+
+    @abstractmethod
+    async def home(self) -> None:
+        """Send deactivate shaker command"""
+        ...
+
+    @abstractmethod
+    async def deactivate_heater(self) -> None:
+        """Send deactivate heater command"""
+        ...
+
+    @abstractmethod
+    async def get_device_info(self) -> Dict[str, str]:
+        """Send get device info command"""
+        ...
+
+    @abstractmethod
+    async def enter_programming_mode(self) -> None:
+        """Reboot into programming mode"""
+        ...

opentrons/drivers/heater_shaker/driver.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from enum import Enum
+import asyncio
+
+from typing import Optional, Dict
+from opentrons.drivers import utils
+from opentrons.drivers.command_builder import CommandBuilder
+from opentrons.drivers.asyncio.communication import (
+    AsyncResponseSerialConnection,
+    UnhandledGcode,
+)
+from opentrons.drivers.heater_shaker.abstract import AbstractHeaterShakerDriver
+from opentrons.drivers.types import Temperature, RPM, HeaterShakerLabwareLatchStatus
+
+
+class GCODE(str, Enum):
+    SET_RPM = "M3"
+    GET_RPM = "M123"
+    SET_TEMPERATURE = "M104"
+    GET_TEMPERATURE = "M105"
+    HOME = "G28"
+    ENTER_BOOTLOADER = "dfu"
+    GET_VERSION = "M115"
+    OPEN_LABWARE_LATCH = "M242"
+    CLOSE_LABWARE_LATCH = "M243"
+    GET_LABWARE_LATCH_STATE = "M241"
+    DEACTIVATE_HEATER = "M106"
+    GET_RESET_REASON = "M114"
+
+
+HS_BAUDRATE = 115200
+DEFAULT_HS_TIMEOUT = 40
+HS_COMMAND_TERMINATOR = "\n"
+HS_ACK = "OK" + HS_COMMAND_TERMINATOR
+HS_ERROR_KEYWORD = "err"
+HS_ASYNC_ERROR_ACK = "async"
+DEFAULT_COMMAND_RETRIES = 0
+
+
+class HeaterShakerDriver(AbstractHeaterShakerDriver):
+    @classmethod
+    async def create(
+        cls, port: str, loop: Optional[asyncio.AbstractEventLoop]
+    ) -> HeaterShakerDriver:
+        """
+        Create a heater-shaker driver.
+
+        Args:
+            port: port or url of heater shaker
+            loop: optional event loop
+
+        Returns: driver
+        """
+        connection = await AsyncResponseSerialConnection.create(
+            port=port,
+            baud_rate=HS_BAUDRATE,
+            timeout=DEFAULT_HS_TIMEOUT,
+            ack=HS_ACK,
+            loop=loop,
+            error_keyword=HS_ERROR_KEYWORD,
+            async_error_ack=HS_ASYNC_ERROR_ACK,
+        )
+        return cls(connection=connection)
+
+    def __init__(self, connection: AsyncResponseSerialConnection) -> None:
+        """
+        Constructor
+
+        Args:
+            connection: SerialConnection to the heater-shaker
+        """
+        self._connection = connection
+
+    async def connect(self) -> None:
+        """Connect to heater-shaker"""
+        await self._connection.open()
+
+    async def disconnect(self) -> None:
+        """Disconnect from heater-shaker"""
+        await self._connection.close()
+
+    async def is_connected(self) -> bool:
+        """Check connection"""
+        return await self._connection.is_open()
+
+    async def open_labware_latch(self) -> None:
+        """Send open-plate-lock command.
+
+        Note: Labware latch is referred to as 'plate lock' in firmware.
+        """
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.OPEN_LABWARE_LATCH
+        )
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)
+
+    async def close_labware_latch(self) -> None:
+        """Send close-plate-lock command.
+
+        Note: Labware latch is referred to as 'plate lock' in firmware.
+        """
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.CLOSE_LABWARE_LATCH
+        )
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)
+
+    async def set_temperature(self, temperature: float) -> None:
+        """Set temperature"""
+        c = (
+            CommandBuilder(terminator=HS_COMMAND_TERMINATOR)
+            .add_gcode(gcode=GCODE.SET_TEMPERATURE)
+            .add_float(
+                prefix="S",
+                value=temperature,
+                precision=utils.HS_GCODE_ROUNDING_PRECISION,
+            )
+        )
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)
+
+    async def get_temperature(self) -> Temperature:
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.GET_TEMPERATURE
+        )
+        response = await self._connection.send_command(
+            command=c, retries=DEFAULT_COMMAND_RETRIES
+        )
+        return utils.parse_temperature_response(
+            temperature_string=response, rounding_val=utils.HS_GCODE_ROUNDING_PRECISION
+        )
+
+    async def set_rpm(self, rpm: int) -> None:
+        """Set RPM"""
+        c = (
+            CommandBuilder(terminator=HS_COMMAND_TERMINATOR)
+            .add_gcode(gcode=GCODE.SET_RPM)
+            .add_int(prefix="S", value=int(rpm))
+        )
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)
+
+    async def get_rpm(self) -> RPM:
+        """Get RPM"""
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.GET_RPM
+        )
+        response = await self._connection.send_command(
+            command=c, retries=DEFAULT_COMMAND_RETRIES
+        )
+        return utils.parse_rpm_response(rpm_string=response)
+
+    async def get_labware_latch_status(self) -> HeaterShakerLabwareLatchStatus:
+        """Send get-labware-latch-status command.
+
+        Note: Labware latch is referred to as 'plate lock' in firmware.
+        """
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.GET_LABWARE_LATCH_STATE
+        )
+        response = await self._connection.send_command(
+            command=c, retries=DEFAULT_COMMAND_RETRIES
+        )
+        return utils.parse_labware_latch_status_response(status_string=response)
+
+    async def home(self) -> None:
+        """Send home command.
+
+        Note: Homing also stops the shaking motion if applicable.
+        """
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(gcode=GCODE.HOME)
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)
+
+    async def get_device_info(self) -> Dict[str, str]:
+        """Send get-device-info command"""
+        device_info = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.GET_VERSION
+        )
+        response = await self._connection.send_command(
+            command=device_info, retries=DEFAULT_COMMAND_RETRIES
+        )
+
+        reset_reason = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.GET_RESET_REASON
+        )
+        try:
+            await self._connection.send_command(
+                command=reset_reason, retries=DEFAULT_COMMAND_RETRIES
+            )
+        except UnhandledGcode:
+            pass
+
+        return utils.parse_hs_device_information(device_info_string=response)
+
+    async def enter_programming_mode(self) -> None:
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.ENTER_BOOTLOADER
+        )
+        await self._connection.send_dfu_command(command=c)
+        await self._connection.close()
+
+    async def deactivate_heater(self) -> None:
+        """Send deactivate-heater command"""
+        c = CommandBuilder(terminator=HS_COMMAND_TERMINATOR).add_gcode(
+            gcode=GCODE.DEACTIVATE_HEATER
+        )
+        await self._connection.send_command(command=c, retries=DEFAULT_COMMAND_RETRIES)