opentrons 8.7.0a9__py3-none-any.whl → 8.8.0a8__py3-none-any.whl

opentrons/drivers/vacuum_module/driver.py

@@ -0,0 +1,208 @@
+import asyncio
+import re
+from typing import Optional
+
+from opentrons.drivers.asyncio.communication import AsyncResponseSerialConnection
+from .abstract import AbstractVacuumModuleDriver
+from .types import LEDColor, LEDPattern, GCODE, VacuumModuleInfo, HardwareRevision
+from .errors import VacuumModuleErrorCodes
+
+
+VM_BAUDRATE = 115200
+DEFAULT_VM_TIMEOUT = 5
+VM_ACK = "OK\n"
+VM_ERROR_KEYWORD = "err"
+VM_ASYNC_ERROR_ACK = "async"
+DEFAULT_COMMAND_RETRIES = 2
+GCODE_ROUNDING_PRECISION = 2
+
+# LED animation range values
+MIN_DURATION_MS = 25  # 25ms
+MAX_DURATION_MS = 10000  # 10s
+MAX_REPS = 10
+
+
+class VacuumModuleDriver(AbstractVacuumModuleDriver):
+    """Driver for Opentrons Vacuum Module."""
+
+    @classmethod
+    def parse_device_info(cls, response: str) -> VacuumModuleInfo:
+        """Parse vacuum module info."""
+        _RE = re.compile(
+            f"^{GCODE.GET_DEVICE_INFO} FW:(?P<fw>\\S+) HW:Opentrons-vacuum-module-(?P<hw>\\S+) SerialNo:(?P<sn>\\S+)$"
+        )
+        m = _RE.match(response)
+        if not m:
+            raise ValueError(f"Incorrect Response for device info: {response}")
+        return VacuumModuleInfo(
+            m.group("fw"), HardwareRevision(m.group("hw")), m.group("sn")
+        )
+
+    @classmethod
+    def parse_reset_reason(cls, response: str) -> int:
+        """Parse the reset reason"""
+        _RE = re.compile(rf"^{GCODE.GET_RESET_REASON} R:(?P<R>\d)$")
+        match = _RE.match(response)
+        if not match:
+            raise ValueError(f"Incorrect Response for reset reason: {response}")
+        return int(match.group("R"))
+
+    @classmethod
+    async def create(
+        cls, port: str, loop: Optional[asyncio.AbstractEventLoop]
+    ) -> "VacuumModuleDriver":
+        """Create a Vacuum Module driver."""
+        connection = await AsyncResponseSerialConnection.create(
+            port=port,
+            baud_rate=VM_BAUDRATE,
+            timeout=DEFAULT_VM_TIMEOUT,
+            number_of_retries=DEFAULT_COMMAND_RETRIES,
+            ack=VM_ACK,
+            loop=loop,
+            error_keyword=VM_ERROR_KEYWORD,
+            async_error_ack=VM_ASYNC_ERROR_ACK,
+            reset_buffer_before_write=True,
+            error_codes=VacuumModuleErrorCodes,
+        )
+        return cls(connection)
+
+    def __init__(self, connection: AsyncResponseSerialConnection) -> None:
+        """
+        Constructor
+
+        Args:
+            connection: connection to the vacuum module
+        """
+        self._connection = connection
+
+    async def connect(self) -> None:
+        """Connect to vacuum module."""
+        await self._connection.open()
+
+    async def disconnect(self) -> None:
+        """Disconnect from vacuum module."""
+        await self._connection.close()
+
+    async def is_connected(self) -> bool:
+        """Check connection to vacuum module."""
+        return await self._connection.is_open()
+
+    async def reset_serial_buffers(self) -> None:
+        """Reset the input and output serial buffers."""
+        self._connection._serial.reset_input_buffer()
+        self._connection._serial.reset_output_buffer()
+
+    async def get_device_info(self) -> VacuumModuleInfo:
+        """Get Device Info."""
+        response = await self._connection.send_command(
+            GCODE.GET_DEVICE_INFO.build_command()
+        )
+        device_info = self.parse_device_info(response)
+        reason_resp = await self._connection.send_command(
+            GCODE.GET_RESET_REASON.build_command()
+        )
+        reason = self.parse_reset_reason(reason_resp)
+        device_info.rr = reason
+        return device_info
+
+    async def enter_programming_mode(self) -> None:
+        """Reboot into programming mode"""
+        command = GCODE.ENTER_BOOTLOADER.build_command()
+        await self._connection.send_dfu_command(command)
+        await self._connection.close()
+
+    async def set_serial_number(self, sn: str) -> None:
+        """Set Serial Number."""
+        if not re.match(r"^VM[\w]{1}[\d]{2}[\d]{8}[\d]+$", sn):
+            raise ValueError(
+                f"Invalid serial number: ({sn}) expected format: VMA1020250119001"
+            )
+        resp = await self._connection.send_command(
+            GCODE.SET_SERIAL_NUMBER.build_command().add_element(sn)
+        )
+        if not re.match(rf"^{GCODE.SET_SERIAL_NUMBER}$", resp):
+            raise ValueError(f"Incorrect Response for set serial number: {resp}")
+
+    async def set_led(
+        self,
+        power: float,
+        color: Optional[LEDColor] = None,
+        external: Optional[bool] = None,
+        pattern: Optional[LEDPattern] = None,
+        duration: Optional[int] = None,
+        reps: Optional[int] = None,
+    ) -> None:
+        """Set LED Status bar color and pattern.
+
+        :param power: Power of the LED (0-1.0), 0 is off, 1 is full power
+        :param color: Color of the LED
+        :param external: True if external LED, False if internal LED
+        :param pattern: Animation pattern of the LED status bar
+        :param duration: Animation duration in milliseconds (25-10000), 10s max
+        :param reps: Number of times to repeat the animation (-1 - 10), -1 is forever.
+        """
+        power = max(0, min(power, 1.0))
+        command = GCODE.SET_LED.build_command().add_float(
+            "P", power, GCODE_ROUNDING_PRECISION
+        )
+        if color is not None:
+            command.add_int("C", color.value)
+        if external is not None:
+            command.add_int("K", int(external))
+        if pattern is not None:
+            command.add_int("A", pattern.value)
+        if duration is not None:
+            duration = max(MIN_DURATION_MS, min(duration, MAX_DURATION_MS))
+            command.add_int("D", duration)
+        if reps is not None:
+            command.add_int("R", max(-1, min(reps, MAX_REPS)))
+        resp = await self._connection.send_command(command)
+        if not re.match(rf"^{GCODE.SET_LED}$", resp):
+            raise ValueError(f"Incorrect Response for set led: {resp}")
+
+    async def enable_pump(self) -> None:
+        """Enables the vacuum pump, does not turn it on."""
+        ...
+
+    async def disable_pump(self) -> None:
+        """Disable the vacuum pump, doesn't just turn it off."""
+        ...
+
+    async def get_pump_motor_register(self) -> None:
+        """Get the register value of the pump motor driver."""
+        ...
+
+    async def get_pressure_sensor_register(self) -> None:
+        """Get the register value of the pressure sensor driver."""
+        ...
+
+    async def get_pressure_sensor_reading_psi(self) -> float:
+        """Get a reading from the pressure sensor."""
+        return 0.0
+
+    async def get_gage_pressure_reading_mbarg(self) -> float:
+        """Read each pressure sensor and return the pressure difference."""
+        return 0.0
+
+    async def set_vacuum_chamber_pressure(
+        self,
+        gage_pressure_mbarg: float,
+        duration: Optional[float],
+        rate: Optional[float],
+    ) -> None:
+        """Engage or release the vacuum until a desired internal pressure is reached."""
+        ...
+
+    # TODO: change pump power to be more specific when we find out how were gonna operate that
+    async def engage_vacuum(self, pump_power: Optional[float] = None) -> None:
+        """Engage the vacuum without regard to chamber pressure."""
+        ...
+
+    async def disengage_vacuum_pump(self) -> None:
+        """Stops the vacuum pump, doesn't vent air or disable the motor."""
+        ...
+
+    # turns off motor, then releases, takes a timeout for buffer between turn off and vent
+    async def vent(self) -> None:
+        """Release the vacuum in the module chamber."""
+        ...

opentrons/drivers/vacuum_module/errors.py

@@ -0,0 +1,39 @@
+"""Vacuum Module-specific errors and exceptions."""
+
+from opentrons.drivers.asyncio.communication.errors import (
+    BaseErrorCode,
+    ErrorResponse,
+    GCodeCacheFull,
+    TaskNotReady,
+    UnhandledGcode,
+)
+
+
+class EStopTriggered(ErrorResponse):
+    """Raised when the estop is triggered during a module action."""
+
+    def __init__(self, port: str, response: str, command: str) -> None:
+        super().__init__(port, response, command)
+
+
+class PumpMotorError(ErrorResponse):
+    """Raised when pump motor error is received."""
+
+    def __init__(self, port: str, response: str, command: str) -> None:
+        super().__init__(port, response, command)
+
+
+class StopRequested(ErrorResponse):
+    """Raised when a stop is requested during a module action."""
+
+    def __init__(self, port: str, response: str, command: str) -> None:
+        super().__init__(port, response, command)
+
+
+class VacuumModuleErrorCodes(BaseErrorCode):
+    """Vacuum Module Error Codes."""
+
+    UNHANDLED_GCODE = ("ERR003", UnhandledGcode)
+    GCODE_CACHE_FULL = ("ERR004", GCodeCacheFull)
+    TASK_NOT_READY = ("ERR007", TaskNotReady)
+    STOP_REQUESTED = ("ERR504", StopRequested)

opentrons/drivers/vacuum_module/simulator.py

@@ -0,0 +1,85 @@
+from typing import Optional
+
+from .abstract import AbstractVacuumModuleDriver
+from .types import VacuumModuleInfo, HardwareRevision, LEDPattern, LEDColor
+from opentrons.util.async_helpers import ensure_yield
+
+
+class SimulatingDriver(AbstractVacuumModuleDriver):
+    def __init__(self, serial_number: str) -> None:
+        self._serial_number = serial_number
+        self.vacuum_on = False
+        self.pump_enabled = False
+        self.pressure_sensor_enabled = False
+
+    @ensure_yield
+    async def connect(self) -> None:
+        pass
+
+    @ensure_yield
+    async def disconnect(self) -> None:
+        pass
+
+    @ensure_yield
+    async def is_connected(self) -> bool:
+        return True
+
+    async def get_device_info(self) -> VacuumModuleInfo:
+        return VacuumModuleInfo(
+            fw="vacuum-fw", hw=HardwareRevision.NFF, sn=self._serial_number
+        )
+
+    async def set_serial_number(self, sn: str) -> None:
+        self._serial_number = sn
+
+    async def enable_pump(self) -> None:
+        self.pump_enabled = True
+
+    async def disable_pump(self) -> None:
+        self.pump_enabled = False
+
+    async def get_pump_motor_register(self) -> None:
+        """Get the register value of the pump motor driver."""
+        pass
+
+    async def get_pressure_sensor_register(self) -> None:
+        """Get the register value of the pressure sensor driver."""
+        pass
+
+    async def get_pressure_sensor_reading(self) -> float:
+        """Get a reading from the pressure sensor."""
+        return 0.0
+
+    # TODO: update the pressure arg with the units when we find out which unit
+    async def set_vacuum_chamber_pressure(
+        self,
+        guage_pressure_mbar: float,
+        duration: Optional[float],
+        rate: Optional[float],
+        vent_after: bool = False,
+    ) -> None:
+        """Engage or release the vacuum until a desired internal pressure is reached."""
+        pass
+
+    async def engage_vacuum(self, pump_power: Optional[float] = None) -> None:
+        self.vacuum_on = True
+
+    async def vent(self, delay_s: float = 0.0) -> None:
+        self.vacuum_on = False
+
+    async def set_led(
+        self,
+        power: float,
+        color: Optional[LEDColor] = None,
+        external: Optional[bool] = None,
+        pattern: Optional[LEDPattern] = None,
+        duration: Optional[int] = None,  # Default firmware duration is 500ms
+        reps: Optional[int] = None,  # Default firmware reps is 0
+    ) -> None:
+        pass
+
+    async def enter_programming_mode(self) -> None:
+        pass
+
+    async def reset_serial_buffers(self) -> None:
+        pass

opentrons/drivers/vacuum_module/types.py

@@ -0,0 +1,79 @@
+from enum import Enum
+from dataclasses import dataclass
+from typing import Dict
+
+from opentrons.drivers.command_builder import CommandBuilder
+
+
+class GCODE(str, Enum):
+
+    GET_RESET_REASON = "M114"
+    GET_DEVICE_INFO = "M115"
+    SET_SERIAL_NUMBER = "M996"
+    ENTER_BOOTLOADER = "dfu"
+    SET_LED = "M200"
+
+    def build_command(self) -> CommandBuilder:
+        """Build command."""
+        return CommandBuilder().add_gcode(self)
+
+
+class HardwareRevision(Enum):
+    """Hardware Revision."""
+
+    NFF = "nff"
+
+
+@dataclass
+class VacuumModuleInfo:
+    """Vacuum module info."""
+
+    fw: str
+    hw: HardwareRevision
+    sn: str
+    rr: int = 0
+
+    def to_dict(self) -> Dict[str, str]:
+        """Build vacuum module info."""
+        return {
+            "serial": self.sn,
+            "version": self.fw,
+            "model": self.hw.value,
+            "reset_reason": str(self.rr),
+        }
+
+
+class LEDColor(Enum):
+    """Vacuum Module 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):
+    """Vacuum Module LED Pattern."""
+
+    STATIC = 0
+    FLASH = 1
+    PULSE = 2
+    CONFIRM = 3

opentrons/execute.py

@@ -555,6 +555,7 @@ def _create_live_context_pe(
             load_fixed_trash=should_load_fixed_trash_labware_for_python_protocol(
                 api_version
             ),
+            camera_provider=None,
         )
     )
 
@@ -644,6 +645,7 @@ def _run_file_pe(
             hardware_api=hardware_api_wrapped,
         )
 
+        # todo (chb, 2025-09-30): The Camera Provider is provided in to a run by the robot server, no analog exists for execute
         orchestrator = RunOrchestrator(
             hardware_api=hardware_api_wrapped,
             protocol_engine=protocol_engine,
@@ -657,6 +659,7 @@ def _run_file_pe(
             protocol_live_runner=LiveRunner(
                 protocol_engine=protocol_engine, hardware_api=hardware_api_wrapped
             ),
+            camera_provider=None,
         )
 
         unsubscribe = protocol_runner.broker.subscribe(

opentrons/hardware_control/api.py

@@ -44,6 +44,7 @@ from .execution_manager import ExecutionManagerProvider
 from .pause_manager import PauseManager
 from .module_control import AttachedModulesControl
 from .types import (
+    AsynchronousModuleErrorNotification,
     Axis,
     CriticalPoint,
     DoorState,
@@ -51,6 +52,7 @@ from .types import (
     ErrorMessageNotification,
     HardwareEventHandler,
     HardwareAction,
+    HardwareEvent,
     MotionChecks,
     PauseType,
     StatusBarState,
@@ -167,6 +169,18 @@ class API(
             except Exception:
                 mod_log.exception("Errored during door state event callback")
 
+    def _send_module_notification(self, event: HardwareEvent) -> None:
+        if not isinstance(event, AsynchronousModuleErrorNotification):
+            return
+        mod_log.info(
+            f"Forwarding module event {event.event} for {event.module_model} {event.module_serial} at {event.port}"
+        )
+        for cb in self._callbacks:
+            try:
+                cb(event)
+            except Exception:
+                mod_log.exception("Errored during module asynchronous callback")
+
     def _reset_last_mount(self) -> None:
         self._last_moved_mount = None
 
@@ -247,7 +261,9 @@ class API(
             )
             await api_instance.cache_instruments()
             module_controls = await AttachedModulesControl.build(
-                api_instance, board_revision=backend.board_revision
+                api_instance,
+                board_revision=backend.board_revision,
+                event_callback=api_instance._send_module_notification,
             )
             backend.module_controls = module_controls
             checked_loop.create_task(backend.watch(loop=checked_loop))
@@ -306,7 +322,9 @@ class API(
         )
         await api_instance.cache_instruments()
         module_controls = await AttachedModulesControl.build(
-            api_instance, board_revision=backend.board_revision
+            api_instance,
+            board_revision=backend.board_revision,
+            event_callback=api_instance._send_module_notification,
         )
         backend.module_controls = module_controls
         await backend.watch()
@@ -1312,9 +1330,10 @@ class API(
             self.is_simulator
         ), "Cannot build simulating module from non-simulating hardware control API"
 
-        return await self._backend.module_controls.build_module(
-            port="",
-            usb_port=USBPort(name="", port_number=1, port_group=PortGroup.MAIN),
+        return await self._backend.module_controls.register_simulated_module(
+            simulated_usb_port=USBPort(
+                name="", port_number=1, port_group=PortGroup.MAIN
+            ),
             type=modules.ModuleType.from_model(model),
             sim_model=model.value,
         )

opentrons/hardware_control/backends/controller.py

@@ -360,13 +360,19 @@ class Controller:
         """Run a probe and return the new position dict"""
         return await self._smoothie_driver.probe_axis(axis, distance)
 
-    async def clean_up(self) -> None:
+    async def clean_up(self) -> None:  # noqa: C901
         try:
             loop = asyncio.get_event_loop()
         except RuntimeError:
             return
+        if hasattr(self, "_module_controls") and self._module_controls is not None:
+            await self._module_controls.clean_up()
         if hasattr(self, "_event_watcher"):
-            if loop.is_running() and self._event_watcher:
+            if (
+                loop.is_running()
+                and self._event_watcher
+                and not self._event_watcher.closed
+            ):
                 self._event_watcher.close()
         if hasattr(self, "gpio_chardev"):
             try:

opentrons/hardware_control/backends/flex_protocol.py

@@ -176,6 +176,7 @@ class FlexBackend(Protocol):
         speed: float,
         stop_condition: HWStopCondition = HWStopCondition.none,
         nodes_in_moves_only: bool = True,
+        delay: Optional[Tuple[List[Axis], float]] = None,
     ) -> None:
         """Move to a position.
 

opentrons/hardware_control/backends/ot3controller.py

@@ -49,6 +49,7 @@ from .ot3utils import (
     gripper_jaw_state_from_fw,
     get_system_constraints,
     get_system_constraints_for_plunger_acceleration,
+    add_delay_to_move_group,
 )
 from .tip_presence_manager import TipPresenceManager
 
@@ -657,11 +658,17 @@ class OT3Controller(FlexBackend):
         speed: float,
         stop_condition: HWStopCondition,
         nodes_in_moves_only: bool,
+        delay: Optional[Tuple[List[Axis], float]] = None,
     ) -> Tuple[Optional[MoveGroupRunner], bool]:
         if not target:
             return None, False
-        move_target = MoveTarget.build(position=target, max_speed=speed)
+        # Create a target that doesn't incorporate the plunger into a joint axis with the gantry
+        plunger_axes = [Axis.P_L, Axis.P_R]
+
         try:
+            move_target = self._move_manager.devectorize_axes(
+                origin, target, speed, plunger_axes
+            )
             _, movelist = self._move_manager.plan_motion(
                 origin=origin, target_list=[move_target]
             )
@@ -683,6 +690,28 @@ class OT3Controller(FlexBackend):
         move_group, _ = create_move_group(
             origin, moves, ordered_nodes, MoveStopCondition[stop_condition.name]
         )
+
+        if delay is not None:
+            delay_axes, delay_time = delay
+            delay_nodes = [axis_to_node(ax) for ax in delay_axes]
+            move_group = add_delay_to_move_group(
+                move_group, ordered_nodes, (delay_nodes, delay_time)
+            )
+
+        (
+            plunger_slowed,
+            error_str,
+        ) = self._move_manager.ensure_pipette_flow_rate_unchanged(
+            [node_to_axis(node) for node in ordered_nodes],
+            origin,
+            target,
+            speed,
+            move_group,
+            [(ax, axis_to_node(ax)) for ax in plunger_axes],
+        )
+        if plunger_slowed:
+            log.error(error_str)
+
         return (
             MoveGroupRunner(
                 move_groups=[move_group],
@@ -728,6 +757,7 @@ class OT3Controller(FlexBackend):
         speed: float,
         stop_condition: HWStopCondition = HWStopCondition.none,
         nodes_in_moves_only: bool = True,
+        delay: Optional[Tuple[List[Axis], float]] = None,
     ) -> None:
         """Move to a position.
 
@@ -750,7 +780,7 @@ class OT3Controller(FlexBackend):
 
         maybe_runners = (
             self._build_move_node_axis_runner(
-                origin, target, speed, stop_condition, nodes_in_moves_only
+                origin, target, speed, stop_condition, nodes_in_moves_only, delay
             ),
             self._build_move_gear_axis_runner(
                 possible_q_axis_origin,
@@ -1398,6 +1428,9 @@ class OT3Controller(FlexBackend):
         except RuntimeError:
             return
 
+        if hasattr(self, "_module_controls") and self._module_controls is not None:
+            await self._module_controls.clean_up()
+
         if hasattr(self, "_event_watcher"):
             if (
                 loop.is_running()

opentrons/hardware_control/backends/ot3simulator.py

@@ -367,6 +367,7 @@ class OT3Simulator(FlexBackend):
         speed: Optional[float] = None,
         stop_condition: HWStopCondition = HWStopCondition.none,
         nodes_in_moves_only: bool = True,
+        delay: Optional[Tuple[List[Axis], float]] = None,
     ) -> None:
         """Move to a position.
 
@@ -728,7 +729,8 @@ class OT3Simulator(FlexBackend):
     @ensure_yield
     async def clean_up(self) -> None:
         """Clean up."""
-        pass
+        if hasattr(self, "_module_controls") and self._module_controls is not None:
+            await self._module_controls.clean_up()
 
     @staticmethod
     def _get_home_position() -> Dict[Axis, float]:

opentrons/hardware_control/backends/ot3utils.py

@@ -1,4 +1,5 @@
 """Shared utilities for ot3 hardware control."""
+import copy
 from typing import Dict, Iterable, List, Set, Tuple, TypeVar, cast, Sequence, Optional
 from typing_extensions import Literal
 from logging import getLogger
@@ -57,6 +58,8 @@ from opentrons_hardware.hardware_control.motion import (
     MoveStopCondition,
     create_gripper_jaw_step,
     create_tip_action_step,
+    SingleMoveStep,
+    MoveGroupSingleAxisStep,
 )
 from opentrons_hardware.hardware_control.constants import interrupts_per_sec
 
@@ -376,6 +379,40 @@ def motor_nodes(devices: Set[FirmwareTarget]) -> Set[NodeId]:
     return {NodeId(target) for target in motor_nodes if target in NodeId}
 
 
+def add_delay_to_move_group(
+    group: MoveGroup,
+    present_nodes: Iterable[NodeId],
+    delay: Tuple[List[NodeId], float],
+) -> MoveGroup:
+    delay_nodes, delay_time = delay
+    if delay_time == 0.0:
+        return group
+
+    as_single_moves: Dict[NodeId, List[SingleMoveStep]] = {}
+    for node in present_nodes:
+        as_single_moves[node] = [step[node] for step in group]
+
+    delay_step = MoveGroupSingleAxisStep(
+        distance_mm=np.float64(0),
+        velocity_mm_sec=np.float64(0),
+        duration_sec=np.float64(delay_time),
+    )
+    for node in present_nodes:
+        if node in delay_nodes:
+            # Add the delay at the beginning
+            as_single_moves[node] = [copy.deepcopy(delay_step)] + as_single_moves[node]
+        else:
+            # Add the delay at the end.
+            as_single_moves[node] = as_single_moves[node] + [copy.deepcopy(delay_step)]
+
+    new_move_group: MoveGroup = []
+    for i in range(len(group) + 1):
+        new_move_group.append(
+            {node: as_single_moves[node][i] for node in present_nodes}
+        )
+    return new_move_group
+
+
 def create_move_group(
     origin: Coordinates[Axis, CoordinateValue],
     moves: List[Move[Axis]],