A MADSci node module for integrating Opentrons liquid handlers (OT-2 and Flex) into an automated/autonomous laboratory.
All configuration is done via environment variables (prefixed NODE_), a settings.yaml file, or a .env file. See docs/Configuration.md for the full reference and .env.example for a commented template.
The most important settings to configure:
| Variable | Default | Purpose |
|---|---|---|
NODE_OT2_IP |
(required) | IP address of the Opentrons robot |
NODE_URL |
http://127.0.0.1:2000/ |
URL the node binds to and advertises |
NODE_NODE_NAME |
(class name) | Human-readable name registered with MADSci |
NODE_NODE_ID |
(auto-generated) | Stable node identifier (ULID); set to persist identity across restarts |
Configuration is loaded in priority order: environment variables > .env file > settings.yaml. A minimal settings.yaml might look like:
node_name: ot2_beta
node_description: OT-2 Beta liquid handler in the RPL workcell
node_id: 01JPNMZF3SPK48EWA1VXMVYHWV
ot2_ip: 192.168.1.100
node_url: "http://127.0.0.1:2000/"Devbox provides a reproducible shell with Python 3.12, pdm, uv, ruff, pre-commit, and just pre-installed. direnv integration via .envrc activates the environment automatically when you cd into the directory.
devbox shell # enter the reproducible environment (or let direnv handle it)
just init # install dependencies + pre-commit hookspdm install -G:all # install all dependencies including dev extrasPDM automatically uses uv as the resolver/installer when PDM_USE_UV=True is set (set in devbox.json).
# Standard pip
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install .
# Or with uv (faster)
uv venv
source .venv/bin/activate
uv pip install .python -m ot2_rest_nodeThe node reads all settings from settings.yaml, environment variables, or .env. The Opentrons robot HTTP API must be reachable at the configured NODE_OT2_IP.
| Tool | Purpose |
|---|---|
| devbox | Reproducible dev shell (Python 3.12, pdm, uv, ruff, just, pre-commit) |
| pdm | Dependency management and virtual environment |
| uv | Fast pip-compatible installer (used by pdm via PDM_USE_UV) |
| just | Task runner (just --list to see all commands) |
| ruff | Linter and formatter |
| pre-commit | Git hooks for linting, formatting, and config generation |
just checks # ruff lint + format + config checks (auto-fixes then re-checks)
just test # pytest (skip hardware tests with: pytest -m "not hardware")
just dcb # docker compose buildPre-commit also runs pydantic-settings-export to keep docs/Configuration.md and .env.example up to date whenever src/ot2_rest_node.py changes.
A pre-built image is available at ghcr.io/ad-sdl/ot2_module. To run with Docker Compose:
# Copy and edit the example settings and env files
cp .env.example .env
# Edit settings.yaml with your robot's IP and node identity
docker compose upThe container uses network_mode: host so it can reach the Opentrons robot on the local network. The settings.yaml and .madsci/ directory are bind-mounted from the project root.
Set USER_ID and GROUP_ID to match your host user to avoid file permission issues:
USER_ID=$(id -u) GROUP_ID=$(id -g) docker compose upSSH access is not required for the HTTP driver used by this module.
If you need SSH access for debugging, see the Opentrons documentation: