Micronic rack reader v1b1

[alexjamesgodfrey]

Micronic provides liquid storage hardware built around barcoded vial racks. This PR adds a generic rack_reading capability and a Micronic v1b1 integration that controls the reader hardware directly through PyLabRobot, without depending on Micronic Code Reader, IO Monitor, or the IO Monitor HTTP server.

The direct path:

• acquires the rack image through an operator-installed scanner bridge:
  • Windows: TwainScanner with a local TWAIN helper path or helper on PATH
  • Linux/Ubuntu: SaneScanner through SANE scanimage
  • custom: any user-provided Scanner subclass
• decodes tube Data Matrix codes locally with Python image/decode dependencies
• reads the side rack barcode through PLR io.Serial
• returns a standard RackScanResult with PLR Barcode objects for the rack and tube barcodes

What's in this PR

• RackReader capability (rack_reading) with scan_rack and scan_rack_id
• RackReaderBackend, RackScanResult, and RackScanEntry
• RackReaderChatterboxBackend for docs/tests without physical hardware
• MicronicCodeReader device exposing the rack_reading capability
• MicronicCodeReaderDriver for direct local image acquisition and serial barcode transport
• MicronicCodeReaderRackReadingBackend for Micronic rack-reading sequencing and result construction
• Local Data Matrix image decoding for the 8x12 / 96-position Micronic rack layout
• Scanner abstractions: Scanner, TwainScanner, and SaneScanner
• Docs: generic rack-reading guide plus Micronic code-reader guide
• Unit tests for rack-reading behavior, chatterbox behavior, scanner command selection, PLR serial rack-ID reads, and device wiring
• Live smoke-tested on Micronic hardware with an 8x12 rack: rack ID read plus full 96-vial scan

Why not IO Monitor?

Micronic's IO Monitor HTTP server can trigger rack scans and return results, but relying on that server means PLR is not actually controlling the hardware. This PR keeps the v1b1 shape and moves hardware ownership into PLR itself.

PLR does not ship a TWAIN helper executable, SANE, scanner drivers, or the image-decoding packages as mandatory dependencies. The operator installs the OS-level scanner bridge, the PLR serial extra (pylabrobot[serial]), and the Python decode dependencies in the runtime environment.

Supported operations

Operation	PLR API	Implementation
Full rack scan	reader.rack_reading.scan_rack(rack)	read side rack barcode, acquire scanner image, decode tube Data Matrix codes, return RackScanResult
Rack barcode only	reader.rack_reading.scan_rack_id()	read side barcode reader over PLR io.Serial

Example

from pylabrobot.micronic import MicronicCodeReader, TwainScanner
from pylabrobot.resources import ResourceHolder, TubeRack, create_ordered_items_2d

rack = TubeRack(
  name="micronic_96_well_rack",
  size_x=85.0,
  size_y=127.0,
  size_z=20.0,
  ordered_items=create_ordered_items_2d(
    ResourceHolder,
    num_items_x=12,
    num_items_y=8,
    dx=0,
    dy=0,
    dz=0,
    item_dx=9.0,
    item_dy=9.0,
    size_x=9.0,
    size_y=9.0,
    size_z=20.0,
  ),
)

reader = MicronicCodeReader(
  scanner=TwainScanner(
    twain_scanner_path=r"C:\Tools\twain_scan.exe",
    twain_source="AVA6PlusG",
  ),
  serial_port="COM4",
  image_dir=r"C:\ProgramData\PyLabRobot\micronic-images",
  keep_images=True,
)

await reader.setup()
try:
  result = await reader.rack_reading.scan_rack(rack=rack, timeout=90.0, poll_interval=1.0)
  print(result.rack_id)
  print(len([entry for entry in result.entries if entry.tube_id]))

  rack_id = await reader.rack_reading.scan_rack_id(timeout=5.0, poll_interval=0.5)
  print(rack_id)
finally:
  await reader.stop()

Hardware validation

Live-tested with an 8x12 Micronic rack on the scanner:

• rack barcode-only read succeeded over PLR io.Serial
• full rack scan succeeded through PLR direct hardware control
• decoded all 96 tube positions
• returned physical rack ID 9500017722
• no Micronic Code Reader / IO Monitor HTTP server dependency

Latest direct-mode Alakascan dogfood run on May 21, 2026 succeeded through the local funnel service with scan ID fabda2bd-c217-4d57-a68a-ccc5a05926f9, rack 9500017722, 96 wells, one attempt.

[rickwierenga]

direct machine support is awesome

[rickwierenga]

can we use the PLR barcode class for tube or rack id?

[rickwierenga]

I think considering using Barcode and please testing if I didn't break anything by running the hello world notebook are the last things needed before merging :)

[Copilot]

Pull request overview

This PR adds a new pylabrobot.micronic manufacturer package with a direct integration for the Micronic rack code reader that does not depend on Micronic's OEM software (Code Reader / IO Monitor). A single MicronicCodeReader class reads the side rack barcode over PLR io.Serial, acquires a rack image through a pluggable Scanner (TWAIN on Windows, SANE on Linux, or custom) via CommandLineTransport, and decodes the 96 tube DataMatrix codes locally (OpenCV/NumPy/Pillow/zxing-cpp, imported lazily). It also wires the device into the docs registry and adds a hello-world notebook plus unit tests.

Changes:

• New MicronicCodeReader with scan_rack / scan_rack_id, plus RackScanResult/RackScanEntry, local grid-fitting and DataMatrix decoding, and cancellation-safe scan sequencing.
• Scanner/TwainScanner/SaneScanner abstractions built on CommandLineTransport, and a MicronicError type.
• Docs: registry entry, API rst, user-guide index, and a hello-world notebook; unit tests for scanners, serial rack-ID reads, decode helpers, and device wiring.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pylabrobot/micronic/code_reader/driver.py	Core MicronicCodeReader, result types, serial rack-ID read, and image decode/grid-fit logic.
pylabrobot/micronic/code_reader/scanner.py	Scanner/TwainScanner/SaneScanner image-acquisition helpers over CommandLineTransport.
pylabrobot/micronic/code_reader/errors.py	MicronicError exception.
pylabrobot/micronic/code_reader/__init__.py, pylabrobot/micronic/__init__.py	Public re-exports for the package.
pylabrobot/micronic/code_reader/micronic_tests.py	Unit tests for scanners, serial reads, decode helpers, and scan flow.
docs/_static/devices.json	Registry entry for the Micronic Code Reader.
docs/api/pylabrobot.micronic.rst, docs/api/pylabrobot.rst	API reference pages/toctree.
docs/user_guide/micronic/index.md, docs/user_guide/index.md, docs/user_guide/micronic/code_reader/hello-world.ipynb	User guide index and hello-world notebook.

Key review notes: the PR description's rack_reading capability/backend/chatterbox architecture and poll_interval API do not match the implemented monolithic MicronicCodeReader (comment 001); requiring all rack.num_items (96) positions to decode contradicts the documented NOREAD partial-read behavior (comment 002); and cluster_axis duplicates fitted_axis (comment 003, optional). The decode logic and cancellation handling are internally consistent and well-tested; the heavy image-processing helpers are untested but require real image/decode libraries not available in the test environment.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.