Agilent plateloc serial control, target v1b1

docs/_static/devices.json

@@ -15,6 +15,20 @@
     "manager": "https://discuss.pylabrobot.org/u/rickwierenga",
     "notes": "BenchCel 4R four-stacker configuration; protocol verified with firmware 3.2.20.0."
   },
+  {
+    "id": "agilent-plateloc",
+    "vendor": "Agilent",
+    "name": "PlateLoc",
+    "kind": "sealer",
+    "capabilities": [
+      "sealing"
+    ],
+    "status": "mostly",
+    "api": "pylabrobot.agilent.PlateLoc",
+    "api_version": "v1",
+    "code_slug": "agilent/plateloc",
+    "doc_slug": "agilent/plateloc/hello-world"
+  },
   {
     "id": "agilent-vspin",
     "vendor": "Agilent",

docs/api/pylabrobot.agilent.rst

@@ -99,3 +99,19 @@ VSpin
     VSpin
     Access2
     Access2Driver
+
+
+PlateLoc
+--------
+
+.. currentmodule:: pylabrobot.agilent.plateloc
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    PlateLoc
+    PlateLocSerialProfile
+    PlateLocStatus
+    PlateLocError

docs/user_guide/agilent/index.md

@@ -4,5 +4,6 @@
 :maxdepth: 1
 
 benchcel/hello-world
+plateloc/hello-world
 vspin/index
 ```

docs/user_guide/agilent/plateloc/hello-world.ipynb

@@ -0,0 +1,266 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-intro",
+   "metadata": {},
+   "source": [
+    "# Agilent PlateLoc\n",
+    "\n",
+    "```{device-card} agilent-plateloc\n",
+    "```\n",
+    "\n",
+    "| Property | Value |\n",
+    "|---|---|\n",
+    "| Connection | RS-232 serial, 19200 8N1 |\n",
+    "| PLR extra | `serial` |\n",
+    "\n",
+    "The PlateLoc uses direct RS-232 control and does not require Agilent ActiveX, VWorks, or vendor server software. Install the optional serial dependency before connecting:\n",
+    "\n",
+    "```bash\n",
+    "pip install \"pylabrobot[serial]\"\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-create-heading",
+   "metadata": {},
+   "source": [
+    "## Create the driver\n",
+    "\n",
+    "Use the serial port connected to the PlateLoc."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-create",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.agilent import PlateLoc\n",
+    "\n",
+    "plateloc = PlateLoc(port=\"COM6\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-physical-setup",
+   "metadata": {},
+   "source": [
+    "## Physical setup\n",
+    "\n",
+    "Connect a USB-to-RS-232 adapter and the correct DB9 cable, power on the PlateLoc, and confirm that the stage is clear before opening the connection."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-setup-heading",
+   "metadata": {},
+   "source": [
+    "## Connect"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-setup",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.setup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-temperature-heading",
+   "metadata": {},
+   "source": [
+    "## Set the sealing temperature\n",
+    "\n",
+    "The accepted range is 20–235 °C."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-temperature",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.set_sealing_temperature(175)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-status-heading",
+   "metadata": {},
+   "source": [
+    "## Read status\n",
+    "\n",
+    "`request_status()` returns the last successfully written temperature target, the tracked stage position, and a live cycle-complete query. The direct protocol does not expose the actual block temperature."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-status",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "status = await plateloc.request_status()\n",
+    "print(status.target_temperature, status.stage_position, status.cycle_complete)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-seal-heading",
+   "metadata": {},
+   "source": [
+    "## Seal a plate\n",
+    "\n",
+    "Place the plate and sealing material as required by the instrument, then set the temperature and duration and wait for the cycle to finish."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-seal",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.seal(temperature=175, duration=1.5)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-open-heading",
+   "metadata": {},
+   "source": [
+    "## Open the stage\n",
+    "\n",
+    "Make sure the stage has room to move."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-open",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.open()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-close-heading",
+   "metadata": {},
+   "source": [
+    "## Close the stage\n",
+    "\n",
+    "Remove or place the plate before closing the stage."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-close",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.close()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-stop-heading",
+   "metadata": {},
+   "source": [
+    "## Disconnect"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-stop",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await plateloc.stop()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-profile-heading",
+   "metadata": {},
+   "source": [
+    "## Serial command profile\n",
+    "\n",
+    "The default profile uses `19200 8N1` and carriage-return-terminated ASCII frames. Temperature and time payloads use the firmware fractional-setpoint convention: the digits after the decimal point are the integer controller value.\n",
+    "\n",
+    "| Operation | Frame |\n",
+    "|---|---|\n",
+    "| Set sealing temperature | `ST 0.{temperature:03d}\\r` |\n",
+    "| Set sealing time | `SS 0.{seconds_x10:02d}\\r` |\n",
+    "| Start cycle | `GO 00\\r` |\n",
+    "| Stop cycle | `AC 00\\r` |\n",
+    "| Move stage out | `SO 00\\r` |\n",
+    "| Move stage in | `SI 00\\r` |\n",
+    "| Apply seal | `AS 00\\r` |\n",
+    "| Clear error | `CL 00\\r` |\n",
+    "| Check cycle complete | `CC 00\\r` |\n",
+    "\n",
+    "For example, `set_sealing_temperature(175)` writes `ST 0.175\\r`, and `seal(temperature=175, duration=1.2)` writes `SS 0.12\\r` as part of the cycle setup. Negative acknowledgements have the form `<code>NK(message)` and raise `PlateLocError`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-profile-create-heading",
+   "metadata": {},
+   "source": [
+    "Override serial settings and timing by passing a `PlateLocSerialProfile`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "plateloc-profile-create",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.agilent import PlateLoc, PlateLocSerialProfile\n",
+    "\n",
+    "profile = PlateLocSerialProfile(\n",
+    "  baudrate=19200,\n",
+    "  stage_move_delay=6,\n",
+    ")\n",
+    "plateloc = PlateLoc(port=\"COM6\", profile=profile)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "plateloc-troubleshooting",
+   "metadata": {},
+   "source": [
+    "## Troubleshooting\n",
+    "\n",
+    "The PlateLoc RS-232 connector is not VGA and is not USB TTL. Use a USB-to-RS-232 adapter plus the correct DB9 cable for the instrument. If the port opens but every command times out, verify that the PlateLoc is powered, the rear serial cable is seated, and the wiring matches the instrument requirement. Some setups require a null-modem DB9 adapter rather than a straight-through cable."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pylabrobot/agilent/__init__.py

@@ -6,4 +6,10 @@
   CytationImagingConfig,
   SynergyH1,
 )
+from .plateloc import (
+  PlateLoc,
+  PlateLocError,
+  PlateLocSerialProfile,
+  PlateLocStatus,
+)
 from .vspin import Access2, Access2Driver, VSpin

pylabrobot/agilent/plateloc/__init__.py

@@ -0,0 +1,6 @@
+from .plateloc import (
+  PlateLoc,
+  PlateLocError,
+  PlateLocSerialProfile,
+  PlateLocStatus,
+)