Micronic rack reader v1b1

docs/api/pylabrobot.capabilities.rst

@@ -192,6 +192,38 @@ Barcode Scanning
     BarcodeScannerBackend
 
 
+Rack Reading
+------------
+
+.. currentmodule:: pylabrobot.capabilities.rack_reading.rack_reader
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    RackReader
+
+.. currentmodule:: pylabrobot.capabilities.rack_reading.backend
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    RackReaderBackend
+
+.. currentmodule:: pylabrobot.capabilities.rack_reading.standard
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    RackScanEntry
+    RackScanResult
+
+
 Microscopy
 ----------
 

docs/api/pylabrobot.micronic.rst

@@ -0,0 +1,68 @@
+.. currentmodule:: pylabrobot.micronic
+
+pylabrobot.micronic package
+===========================
+
+Micronic integrations built on the rack-reading capability.
+
+Device
+------
+
+.. currentmodule:: pylabrobot.micronic.code_reader.code_reader
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    MicronicCodeReader
+
+
+Driver
+------
+
+.. currentmodule:: pylabrobot.micronic.code_reader.driver
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    MicronicCodeReaderDriver
+
+.. currentmodule:: pylabrobot.micronic.code_reader.errors
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    MicronicError
+
+
+Scanners
+--------
+
+.. currentmodule:: pylabrobot.micronic.code_reader.scanner
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    Scanner
+    TwainScanner
+    SaneScanner
+
+
+Capabilities
+------------
+
+.. currentmodule:: pylabrobot.micronic.code_reader.rack_reading_backend
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    MicronicCodeReaderRackReadingBackend

docs/api/pylabrobot.rst

@@ -41,6 +41,7 @@ Manufacturers
     pylabrobot.inheco
     pylabrobot.liconic
     pylabrobot.mettler_toledo
+    pylabrobot.micronic
     pylabrobot.molecular_devices
     pylabrobot.opentrons
     pylabrobot.qinstruments

docs/user_guide/capabilities/index.md

@@ -55,6 +55,7 @@ loading-tray
 pumping
 weighing
 barcode-scanning
+rack-reading
 microscopy
 automated-retrieval
 absorbance

docs/user_guide/capabilities/rack-reading.ipynb

@@ -0,0 +1,107 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Rack Reading\n",
+    "\n",
+    "The `rack_reading` capability standardizes rack-scale code readers that decode a tube rack and\n",
+    "return structured per-position scan results.\n",
+    "\n",
+    "Unlike one-at-a-time code reads, rack reading is job-oriented and returns the full decoded rack map.\n",
+    "\n",
+    "## Walkthrough"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+                "from pylabrobot.capabilities.rack_reading import RackReader\n",
+                "from pylabrobot.capabilities.rack_reading.chatterbox import RackReaderChatterboxBackend\n",
+                "from pylabrobot.resources import ResourceHolder, TubeRack, create_ordered_items_2d\n",
+    "\n",
+    "reader = RackReader(backend=RackReaderChatterboxBackend())\n",
+    "await reader._on_setup()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+                "rack = TubeRack(\n",
+                "  name=\"rack\",\n",
+                "  size_x=85.0,\n",
+                "  size_y=127.0,\n",
+                "  size_z=20.0,\n",
+                "  ordered_items=create_ordered_items_2d(\n",
+                "    ResourceHolder,\n",
+                "    num_items_x=12,\n",
+                "    num_items_y=8,\n",
+                "    dx=0,\n",
+                "    dy=0,\n",
+                "    dz=0,\n",
+                "    item_dx=9.0,\n",
+                "    item_dy=9.0,\n",
+                "    size_x=9.0,\n",
+                "    size_y=9.0,\n",
+                "    size_z=20.0,\n",
+                "  ),\n",
+                ")\n",
+    "\n",
+    "result = await reader.scan_rack(rack=rack, timeout=60.0, poll_interval=1.0)\n",
+    "print(result.rack_id)\n",
+    "print(result.entries[0].position, result.entries[0].tube_id)"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "rack_id = await reader.scan_rack_id(timeout=60.0, poll_interval=1.0)\n",
+    "print(rack_id)"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Public API\n",
+    "\n",
+    "- `scan_rack(rack, timeout, poll_interval)` — scan a `TubeRack` and return a `RackScanResult`. The\n",
+    "  backend validates that the rack shape matches what the hardware supports.\n",
+    "- `scan_rack_id(timeout, poll_interval)` — read just the rack barcode (no per-position decoding)\n",
+    "  and return the rack identifier.\n",
+    "\n",
+    "## Supported hardware\n",
+    "\n",
+    "```{supported-devices} rack reading\n",
+    "```\n",
+    "\n",
+    "## API reference\n",
+    "\n",
+    "See {class}`~pylabrobot.capabilities.rack_reading.rack_reader.RackReader` and {class}`~pylabrobot.capabilities.rack_reading.backend.RackReaderBackend`."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/index.md

@@ -40,6 +40,7 @@ inheco/index
 liconic/index
 mettler_toledo/index
 molecular_devices/index
+micronic/index
 opentrons/index
 qinstruments/index
 thermo_fisher/index

docs/user_guide/machines.md

@@ -188,6 +188,12 @@ tr > td:nth-child(5) { width: 15%; }
 |--------------|---------|-------------|--------|
 | Mettler Toledo | WXS205SDU | Full | [PLR](02_analytical/scales/mettler-toledo-WXS205SDU.ipynb) / [OEM](https://www.mt.com/us/en/home/products/Industrial_Weighing_Solutions/high-precision-weigh-sensors/weigh-module-wxs205sdu-15-11121008.html) |
 
+### Rack Readers
+
+| Manufacturer | Machine | Features | PLR-Support | Links |
+|--------------|---------|----------|-------------|--------|
+| Micronic | Direct local scanner + serial control | <span class="badge badge-reading">rack reading</span> | Basics | [PLR](https://docs.pylabrobot.org/user_guide/micronic/index.html) / [OEM](https://www.micronic.com/products/code-reader/) |
+
 ---
 
 ## Understanding the Tables

docs/user_guide/micronic/code_reader/hello-world.ipynb

@@ -0,0 +1,46 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+            "source": "# Micronic\n\nPyLabRobot includes `v1b1` Micronic integrations built on the generic\n`rack_reading` capability.\n\n`MicronicCodeReader` controls the local hardware directly. The caller picks a\n`Scanner` to acquire the rack image (`TwainScanner` on Windows, `SaneScanner` on\nLinux, or a custom `Scanner` subclass for any other acquisition stack). The driver\nhandles image acquisition and side-rack serial barcode reads; the rack-reading\nbackend decodes tube DataMatrix codes locally and returns a standard\n`RackScanResult`. It does not call Micronic Code Reader or IO Monitor, and\nPyLabRobot does not package any scanner helper executable.\n\n## Supported operations\n\nRack reading (large scanner that decodes 96 tubes plus the side rack barcode):\n\n- `rack_reading.scan_rack(rack)` to trigger image acquisition, decode all 96 tube\n  positions, read the side rack barcode, and return a `RackScanResult`. The device\n  currently supports 8x12 racks; passing a different shape raises `MicronicError`.\n- `rack_reading.scan_rack_id()` for a rack-barcode-only read on the side reader\n\n## Hardware example\n\nThe operator is responsible for installing any OS-level scanner bridge\n(`twain_scan`, `scanimage`, or custom scanner integration), the PLR serial extra\n(`pylabrobot[serial]`), and the local Python decode dependencies in the runtime\nenvironment."
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+            "source": "from pylabrobot.micronic import MicronicCodeReader, TwainScanner\nfrom pylabrobot.resources import ResourceHolder, TubeRack, create_ordered_items_2d\n\nrack = TubeRack(\n  name=\"micronic_96_well_rack\",\n  size_x=85.0,\n  size_y=127.0,\n  size_z=20.0,\n  ordered_items=create_ordered_items_2d(\n    ResourceHolder,\n    num_items_x=12,\n    num_items_y=8,\n    dx=0,\n    dy=0,\n    dz=0,\n    item_dx=9.0,\n    item_dy=9.0,\n    size_x=9.0,\n    size_y=9.0,\n    size_z=20.0,\n  ),\n)\n\nreader = MicronicCodeReader(\n  scanner=TwainScanner(\n    twain_scanner_path=r\"C:\\Tools\\twain_scan.exe\",\n    twain_source=\"AVA6PlusG\",\n  ),\n  serial_port=\"COM4\",\n  image_dir=r\"C:\\ProgramData\\PyLabRobot\\micronic-images\",\n  keep_images=True,\n)\nawait reader.setup()\n\ntry:\n  rack_result = await reader.rack_reading.scan_rack(\n    rack=rack, timeout=90.0, poll_interval=1.0\n  )\n  print(rack_result.rack_id)\n  print(len([entry for entry in rack_result.entries if entry.tube_id]))\n\n  rack_id = await reader.rack_reading.scan_rack_id(timeout=5.0, poll_interval=0.5)\n  print(rack_id)\nfinally:\n  await reader.stop()",
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": "On Ubuntu/Linux, use `SaneScanner` if the scanner is exposed by a SANE backend:"
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": "from pylabrobot.micronic import MicronicCodeReader, SaneScanner\n\nreader = MicronicCodeReader(\n  scanner=SaneScanner(sane_device=\"avision:libusb:001:004\"),\n  serial_port=\"/dev/ttyUSB0\",\n)",
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+            "source": "For any other acquisition stack, subclass `Scanner` and implement `acquire` to\nwrite a rack image to the given path.\n\n## Notes\n\n- `scan_rack` reads the rack ID and every tube barcode, so it typically takes\n  tens of seconds. `scan_rack_id` only reads the rack barcode and completes in a\n  few seconds.\n- TWAIN is a Windows scanner-driver API. PyLabRobot does not ship a TWAIN\n  bridge binary and does not install one for you; pass `twain_scanner_path` to\n  `TwainScanner`, set `MICRONIC_TWAIN_SCANNER_PATH`, or put a local helper\n  named `twain_scan` / `twain_scan.exe` on `PATH`.\n- Ubuntu/Linux scanner control uses SANE `scanimage` (via `SaneScanner`).\n  PyLabRobot does not install SANE or vendor scanner drivers. Rack-ID reads use\n  `pylabrobot.io.Serial`, which is installed through the `pylabrobot[serial]`\n  extra.\n- Image decoding imports `pillow`, `opencv-python-headless`, `numpy`, and\n  `zxing-cpp` at runtime. Install them in the environment that runs PyLabRobot."
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/micronic/index.md

@@ -0,0 +1,7 @@
+# Micronic
+
+```{toctree}
+:maxdepth: 1
+
+code_reader/hello-world
+```

pylabrobot/capabilities/__init__.py

@@ -1 +1,7 @@
 from .capability import Capability, CapabilityBackend, need_capability_ready
+from .rack_reading import (
+  RackReader,
+  RackReaderBackend,
+  RackScanEntry,
+  RackScanResult,
+)

pylabrobot/capabilities/rack_reading/__init__.py

@@ -0,0 +1,4 @@
+from .backend import RackReaderBackend
+from .chatterbox import RackReaderChatterboxBackend
+from .rack_reader import RackReader
+from .standard import RackScanEntry, RackScanResult

pylabrobot/capabilities/rack_reading/backend.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+
+from pylabrobot.capabilities.capability import CapabilityBackend
+from pylabrobot.resources.tube_rack import TubeRack
+
+from .standard import RackScanResult
+
+
+class RackReaderBackend(CapabilityBackend, metaclass=ABCMeta):
+  """Abstract backend for rack readers that decode position-indexed rack contents."""
+
+  @abstractmethod
+  async def scan_rack(self, rack: TubeRack, timeout: float, poll_interval: float) -> RackScanResult:
+    """Scan ``rack`` and return its decoded contents."""
+
+  @abstractmethod
+  async def scan_rack_id(self, timeout: float, poll_interval: float) -> str:
+    """Read the rack barcode only and return the rack identifier."""

pylabrobot/capabilities/rack_reading/chatterbox.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pylabrobot.resources.barcode import Barcode
+from pylabrobot.resources.tube_rack import TubeRack
+
+from .backend import RackReaderBackend
+from .standard import RackScanEntry, RackScanResult
+
+
+class RackReaderChatterboxBackend(RackReaderBackend):
+  """Device-free rack-reading backend for tests and examples."""
+
+  async def scan_rack(self, rack: TubeRack, timeout: float, poll_interval: float) -> RackScanResult:
+    del rack, timeout, poll_interval
+    return RackScanResult(
+      rack_id="CHATTERBOX",
+      entries=[
+        RackScanEntry(
+          position="A1",
+          tube_id="SIMULATED",
+          status="OK",
+          barcode=Barcode(data="SIMULATED", symbology="DataMatrix", position_on_resource="bottom"),
+        ),
+      ],
+      rack_barcode=Barcode(
+        data="CHATTERBOX", symbology="Code 128 (Subset B and C)", position_on_resource="right"
+      ),
+    )
+
+  async def scan_rack_id(self, timeout: float, poll_interval: float) -> str:
+    del timeout, poll_interval
+    return "CHATTERBOX"