Skip to content

Korobka¤

Korobka is a Python library for orchestrating equipment in automated chemistry laboratories. It provides a unified interface to control a range of hardware (balances, pumps, robotic arms, NMR spectrometers, and liquid handlers) and to compose them into higher-level automated workflows.

Status: Active development. API may change between versions. Requires Python 3.12+.

What it does¤

Modern self-driving labs use many pieces of equipment that each ship with their own proprietary software and communication protocols. Korobka brings them under a single, consistent Python API, so you can write workflows that span multiple instruments without worrying about serial protocols, Modbus registers, or TCP socket framing.

At the lowest level, Korobka handles the communication details — serial, Modbus RTU, and TCP/IP. On top of that, each instrument class exposes a domain-specific interface. At the highest level, station classes orchestrate several instruments together to automate common lab tasks like gravimetric liquid calibration or sample weighing.

Supported hardware¤

Category Device
Balances Ohaus (serial), Mettler XPR204 (Web Service Interface / SOAP/HTTP)
Pumps Peristaltic pump (Modbus RTU / RS485)
Robotic arms Dobot MG400 (TCP/IP), UFACTORY xArm 850
Robotic auxiliaries Gripper, Rotary Gripper, Actuator
Liquid handlers Opentrons OT-2 (SSH)
Spectrometers Magritek Spinsolve benchtop NMR (TCP/IP)
Optimisation WebBO Bayesian optimisation service

Architecture¤

korobka/
├── connections/    # Communication base classes (Serial, Modbus, TCP/IP)
├── balances/       # Balance drivers
├── pumps/          # Pump drivers
├── robots/         # Robotic arm drivers and auxiliary tools
├── opentrons/      # Opentrons liquid handler integration
├── spectral/       # NMR spectrometer driver
├── stations/       # High-level orchestrated workflows
├── webbo/          # Bayesian optimisation client
└── utils/          # Logging, configuration loading, port auto-detection

All instrument classes inherit from the appropriate communication base class (BaseSerial, BaseModbus, or BaseTCPIP) and add device-specific command methods on top. Station classes take instrument instances and coordinate them to carry out multi-step experiments.

Installation¤

Korobka uses Poetry for dependency management.

# 1. Clone the repository
git clone https://github.com/imperial-college-london/korobka.git
cd korobka

# 2. Install dependencies
poetry install

# 3. Activate the virtual environment
eval $(poetry env activate)

To also install documentation and development dependencies:

poetry install --with dev,docs

Quick start¤

Controlling a balance¤

from korobka.balances.balance_ohaus import Balance

# Port is auto-detected if not specified
balance = Balance()
weight = balance.weigh()
print(f"Sample weight: {weight} g")

Moving a robotic arm¤

from korobka.robots.Dobot.dobot import Dobot

dobot = Dobot(ip_address="192.168.1.6")
dobot.initiate()

# Move to a named position defined in positions.json
dobot.move("safe_position")

# Pick up a vial from a specific well on a plate
dobot.pickup_vial("plate1", "A1")

Configuration¤

Equipment parameters, plate layouts, and experiment settings can be stored in YAML or JSON files and passed to the relevant classes at initialisation. Many devices have a default config file which is taken if a custom one is not provided. See the inline docstrings in each module for the expected configuration schema.

Example configuration files:

  • liquid_calibr_config.yml — parameters for LiquidCalibrator
  • webbo_config.yaml — settings for the WebBO optimisation client
  • positions.json (Dobot) — named positions and plate/well coordinate maps

Serial ports are auto-detected by default; you can also specify them explicitly (e.g. Balance(port="COM3") or Balance(port="/dev/ttyUSB0")).

Running tests¤

# Run the full test suite
poetry run pytest

# Run tests for a specific module
poetry run pytest tests/test_balances/

# Generate an HTML coverage report (saved to htmlcov/)
poetry run pytest --cov=korobka --cov-report=html

Hardware is mocked in all tests so no physical devices are required.

Documentation¤

API documentation is generated from docstrings using MkDocs.

# Install doc dependencies
poetry install --with docs

# Serve locally at http://127.0.0.1:8000
poetry run mkdocs serve

# Build static site to site/
poetry run mkdocs build

Contributing¤

We welcome contributions. Please read CONTRIBUTING.md for details on the development workflow, code style, and how to add support for new hardware.

Authors¤

Korobka was created at Imperial College London by:

  • Aleksandr Ostudin
  • Daniel Davies
  • Sean Gurung

License¤

BSD 3-Clause. See LICENSE.