Micronic rack reader v1b1

docs/_static/devices.json

@@ -805,6 +805,21 @@
     "manager": "https://discuss.pylabrobot.org/u/rickwierenga",
     "oem": "https://www.mt.com/us/en/home/products/Industrial_Weighing_Solutions/high-precision-weigh-sensors/weigh-module-wxs205sdu-15-11121008.html"
   },
+  {
+    "id": "micronic-code-reader",
+    "vendor": "Micronic",
+    "name": "RD235",
+    "kind": "barcode scanner",
+    "capabilities": [
+      "barcode reading"
+    ],
+    "status": "full",
+    "api": "pylabrobot.micronic.MicronicRD235",
+    "api_version": "v1",
+    "code_slug": "micronic/code_reader",
+    "doc_slug": "micronic/code_reader/hello-world",
+    "oem": "https://www.micronic.com/products/code-reader/"
+  },
   {
     "id": "molecular-devices-imagexpress-micro",
     "vendor": "Molecular Devices",

docs/api/pylabrobot.micronic.rst

@@ -0,0 +1,44 @@
+.. currentmodule:: pylabrobot.micronic
+
+pylabrobot.micronic package
+===========================
+
+Direct Micronic RD235 code-reader integration.
+
+Code reader
+-----------
+
+.. currentmodule:: pylabrobot.micronic.code_reader.driver
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    MicronicRD235
+    RackScanEntry
+    RackScanResult
+
+.. 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

docs/api/pylabrobot.rst

@@ -33,6 +33,7 @@ Manufacturers
     pylabrobot.kbioscience
     pylabrobot.kbiosystems
     pylabrobot.mettler_toledo
+    pylabrobot.micronic
     pylabrobot.molecular_devices
     pylabrobot.qinstruments
     pylabrobot.sartorius

docs/user_guide/index.md

@@ -41,6 +41,7 @@ inheco/index
 kbioscience/index
 kbiosystems/index
 mettler_toledo/index
+micronic/index
 molecular_devices/index
 qinstruments/index
 sartorius/index

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

@@ -0,0 +1,221 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "micronic-intro",
+   "metadata": {},
+   "source": [
+    "# Micronic RD235 Code Reader\n",
+    "\n",
+    "The Micronic RD235 Code Reader scans the side barcode of an 8x12 tube rack, acquires an image of\n",
+    "the rack, and decodes the 96 tube DataMatrix codes locally. It does not require Micronic Code\n",
+    "Reader or IO Monitor.\n",
+    "\n",
+    "| Property | Value |\n",
+    "|---|---|\n",
+    "| Model | RD235 |\n",
+    "| Rack-ID communication | Serial trigger and response |\n",
+    "| Serial settings | 9600 baud, 7 data bits, even parity, 1 stop bit |\n",
+    "| Rack image | TWAIN helper on Windows, SANE `scanimage` on Linux, or a custom `Scanner` |\n",
+    "| Rack layout | 8 rows by 12 columns |\n",
+    "| Tube barcode | Ten-digit DataMatrix |\n",
+    "| Rack barcode | Code 128 |\n",
+    "\n",
+    "[OEM link](https://www.micronic.com/products/code-reader/)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "device-card",
+   "metadata": {},
+   "source": [
+    "```{device-card} micronic-code-reader\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-communication",
+   "metadata": {},
+   "source": [
+    "## How it talks\n",
+    "\n",
+    "The side reader uses `pylabrobot.io.Serial`. A rack-ID scan clears pending input, sends\n",
+    "`<t>` followed by CRLF, reads through the response terminator, and returns the first sequence\n",
+    "of at least six digits. It returns `NOREAD` when the response contains no rack identifier.\n",
+    "\n",
+    "Rack-image acquisition runs through PyLabRobot's command-line transport. `TwainScanner` calls\n",
+    "an operator-installed TWAIN helper; `SaneScanner` calls `scanimage`. PyLabRobot then performs\n",
+    "grid fitting and DataMatrix decoding locally."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-physical-setup",
+   "metadata": {},
+   "source": [
+    "## Physical setup\n",
+    "\n",
+    "1. Connect the rack scanner to the computer and install its operating-system driver.\n",
+    "2. Connect the side rack-ID reader and identify its serial port.\n",
+    "3. On Windows, install the local TWAIN helper and note its path and TWAIN source name. On\n",
+    "   Linux, install SANE and confirm that `scanimage --list-devices` lists the scanner.\n",
+    "4. Install the serial and decoding dependencies: `pylabrobot[serial]`, `pillow`,\n",
+    "   `opencv-python-headless`, `numpy`, and `zxing-cpp`.\n",
+    "5. Place an 8x12 Micronic tube rack in the scanner with the orientation expected by the\n",
+    "   instrument."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-connect",
+   "metadata": {},
+   "source": [
+    "## Connect\n",
+    "\n",
+    "Choose the scanner implementation for the host. This example uses a Windows TWAIN helper. On\n",
+    "Linux, replace it with `SaneScanner(sane_device=\"<device from scanimage --list-devices>\")`.\n",
+    "`setup()` resolves the scanner executable, creates the image directory, and opens the side\n",
+    "reader's serial port."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "micronic-connect-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.micronic import MicronicRD235, TwainScanner\n",
+    "\n",
+    "reader = MicronicRD235(\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",
+    ")\n",
+    "await reader.setup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-rack-id",
+   "metadata": {},
+   "source": [
+    "## Read the rack ID\n",
+    "\n",
+    "`scan_rack_id()` triggers only the side barcode reader. It returns the decoded identifier or\n",
+    "`NOREAD`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "micronic-rack-id-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rack_id = await reader.scan_rack_id(timeout=5.0)\n",
+    "print(rack_id)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-rack-resource",
+   "metadata": {},
+   "source": [
+    "## Represent the rack\n",
+    "\n",
+    "`scan_rack()` accepts a `TubeRack` with exactly 8 rows and 12 columns. Define the rack layout\n",
+    "before scanning it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "micronic-rack-resource-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.resources import ResourceHolder, TubeRack, create_ordered_items_2d\n",
+    "\n",
+    "rack = TubeRack(\n",
+    "  name=\"micronic_96_tube_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",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-scan-rack",
+   "metadata": {},
+   "source": [
+    "## Scan the rack\n",
+    "\n",
+    "`scan_rack()` reads the side rack barcode, acquires the rack image, and returns one entry for\n",
+    "each tube position. A position reports `NOREAD` when no tube barcode was decoded."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "micronic-scan-rack-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = await reader.scan_rack(rack=rack, timeout=90.0)\n",
+    "print(result.rack_id)\n",
+    "print(len([entry for entry in result.entries if entry.status == \"OK\"]))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "micronic-disconnect",
+   "metadata": {},
+   "source": [
+    "## Disconnect\n",
+    "\n",
+    "`stop()` closes the side reader's serial connection."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "micronic-disconnect-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await reader.stop()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/micronic/index.md

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

pylabrobot/micronic/__init__.py

@@ -0,0 +1,9 @@
+from pylabrobot.micronic.code_reader import (
+  MicronicError,
+  MicronicRD235,
+  RackScanEntry,
+  RackScanResult,
+  SaneScanner,
+  Scanner,
+  TwainScanner,
+)

pylabrobot/micronic/code_reader/__init__.py

@@ -0,0 +1,7 @@
+from pylabrobot.micronic.code_reader.driver import (
+  MicronicRD235,
+  RackScanEntry,
+  RackScanResult,
+)
+from pylabrobot.micronic.code_reader.errors import MicronicError
+from pylabrobot.micronic.code_reader.scanner import SaneScanner, Scanner, TwainScanner