Skip to content

feat: add dispensing module with Formulatrix Mantis backend#987

Open
xbtu2 wants to merge 2 commits intoPyLabRobot:mainfrom
xbtu2:feat/dispensing-mantis
Open

feat: add dispensing module with Formulatrix Mantis backend#987
xbtu2 wants to merge 2 commits intoPyLabRobot:mainfrom
xbtu2:feat/dispensing-mantis

Conversation

@xbtu2
Copy link
Copy Markdown
Contributor

@xbtu2 xbtu2 commented Apr 4, 2026

Summary

Adds a new pylabrobot/dispensing/ module for chip-based contactless liquid dispensers, following PLR's Machine/Backend architecture pattern. The Formulatrix Mantis is the first backend implementation.

New Module Structure

pylabrobot/dispensing/
├── __init__.py                    # Exports: Dispenser, DispenserBackend, DispenseOp
├── backend.py                     # ABC: DispenserBackend
├── standard.py                    # Dataclass: DispenseOp
├── dispenser.py                   # Front-end: Dispenser(Machine)
├── chatterbox.py                  # ChatterboxBackend for testing
├── dispenser_tests.py             # Front-end unit tests (6 tests)
└── mantis/
    ├── __init__.py                # Exports: MantisBackend
    ├── mantis_backend.py          # MantisBackend(DispenserBackend)
    ├── fmlx_driver.py             # Low-level FMLX protocol driver
    ├── mantis_kinematics.py       # Kinematics + map generator
    ├── mantis_constants.py        # Constants, chip paths, PPI sequences
    ├── mantis_sequence_parser.py  # Sequence file parser
    └── mantis_tests.py            # Mantis-specific unit tests (22 tests)

Design Highlights

  • Dispenser(Machine) front-end with @need_setup_finished decorator
  • DispenserBackend ABC with setup(), stop(), dispense(ops) interface
  • DispenseOp frozen dataclass (resource, volume, chip)
  • MantisBackend — full init sequence, chip lifecycle (attach/prime/dispense/detach), pressure control
  • FmlxDriver — accepts PLR's pylabrobot.io.ftdi.FTDI via dependency injection
  • Proper enumsMotorStatusCode(IntFlag) with error_mask(), PEP 8 naming
  • Configurable chip_type_map per instrument instance
  • 28 unit tests all passing
  • Chatterbox backend for device-free testing

Usage Example

from pylabrobot.dispensing import Dispenser
from pylabrobot.dispensing.mantis import MantisBackend

d = Dispenser(backend=MantisBackend(
    serial_number="M-000438",
    chip_type_map={3: "high_volume", 4: "high_volume", 5: "low_volume"},
))
await d.setup()
await d.dispense(plate["A1:H12"], volume=5.0, chip=3)
await d.stop()

Testing

28 passed in 0.14s

All pre-commit hooks pass (ruff format, ruff check, typos).

Add a new pylabrobot/dispensing/ module for chip-based contactless liquid
dispensers, following PLR's Machine/Backend architecture pattern.

New module structure:
- Dispenser front-end (Machine subclass)
- DispenserBackend ABC with setup/stop/dispense interface
- DispenseOp frozen dataclass for operation parameters
- ChatterboxBackend for device-free testing

Mantis backend (pylabrobot/dispensing/mantis/):
- MantisBackend implementing DispenserBackend
- FmlxDriver for Formulatrix FMLX protocol over FTDI
- MantisKinematics (inverse/forward kinematics for dual-arm SCARA)
- MantisMapGenerator (homography-corrected plate coordinate mapping)
- Sequence file parser for Mantis .seq files
- Constants with proper IntFlag/IntEnum types

28 unit tests (all passing).
@rickwierenga
Copy link
Copy Markdown
Member

sweet! thanks for the PR!

mind if I rebase this onto the v1b1 architecture?

- Fix isort I001: remove extra blank line in mantis_sequence_parser.py
- Fix mypy arg-type: use explicit MantisMapGenerator construction instead
  of **dict unpacking (rows/cols need int, not float)
- Fix mypy arg-type: cast coord dict values to float explicitly
- Fix mypy no-any-return: cast dict.get() results to int in motor status
  helpers
- Change get_well_coordinate return type from Dict[str, object] to
  Dict[str, Any] for correct downstream typing
- Add 'Occured' to _typos.toml (firmware protocol string, not a typo)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants