Micronic rack reader v1b1

[alexjamesgodfrey]

Micronic provides liquid storage solutions in the form of barcoded vials, racks for the vials, and rack readers that read all vial Data Matrix codes plus the rack barcode.

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 software, IO Monitor, or its HTTP server controlled by the software.

The direct path:

• acquires the rack image through an operator-installed scanner bridge:
  • Windows: TWAIN helper configured by path or available on PATH
  • Linux/Ubuntu: SANE scanimage
  • custom: user-provided scan_command
• decodes tube Data Matrix codes locally with open Python dependencies
• reads the side rack barcode through PLR io.Serial
• returns a standard RackScanResult

What's in this PR

• RackReader capability (rack_reading) with scan_rack, scan_rack_id, layout management, and state polling
• MicronicCodeReader device exposing the rack_reading capability
• MicronicDriver for direct local scanner + serial rack barcode control
• Local Data Matrix image decoding for the 8x12 / 96-position Micronic rack layout
• PLR io.Serial rack barcode read path for the side barcode reader
• Windows TWAIN-helper, Linux SANE, custom command, and image-input acquisition paths
• Docs: docs/user_guide/capabilities/rack-reading.md, docs/user_guide/micronic/index.md
• Unit tests for rack-reading behavior, Micronic driver state transitions, scanner command selection, serial rack-id reading, 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, but moves hardware ownership into PLR itself.

PLR does not ship a TWAIN helper executable, SANE, or scanner drivers. The operator is responsible for installing the OS-level scanner bridge and Python decode dependencies in their runtime environment. For example I hd to install a driver for the COM4 barcode scanner that came with my rack reader.

Supported operations

Operation	PLR API	Implementation
Full rack scan	reader.rack_reading.scan_rack()	acquire scanner image, decode tube Data Matrix codes, read rack barcode over serial
Rack barcode only	reader.rack_reading.scan_rack_id()	read side barcode reader over PLR io.Serial
State polling	reader.rack_reading.get_state()	local driver scan state
Layout list	reader.rack_reading.get_layouts()	currently fixed to 8x12 / 96
Current layout	get_current_layout() / set_current_layout()	accepts 8x12, 96(8x12), 96

Example

from pylabrobot.micronic import MicronicCodeReader

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

await reader.setup()
try:
  result = await reader.rack_reading.scan_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 (rd235) on the scanner:

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

[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 :)