labmcp-cavro 0.1.0__tar.gz

labmcp_cavro-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+*.jsonl
+!**/fixtures/*.jsonl
+.idea/
+.vscode/
+
+CLAUDE.md

labmcp_cavro-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: labmcp-cavro
+Version: 0.1.0
+Summary: MCP server for Tecan Cavro syringe pumps (XLP 6000, XMP 6000, XCalibur) over the DT protocol: initialize, aspirate/dispense µL, switch valve ports, terminate.
+Project-URL: Homepage, https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/biology/tecan-cavro-pump
+Author: K-Dense and LabMCP contributors
+License-Expression: Apache-2.0
+Keywords: cavro,lab-instrument,liquid-handling,mcp,syringe-pump,tecan,xcalibur,xlp6000
+Requires-Python: >=3.10
+Requires-Dist: labmcp<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# Tecan Cavro Syringe Pump — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-cavro -->
+
+Let an AI agent initialize, aspirate and dispense microlitre volumes at set flow rates, switch valve ports and stop **Tecan Cavro OEM syringe pumps** through the documented **Cavro Data Terminal (DT) protocol**.
+
+| | |
+|---|---|
+| **Package** | `labmcp-cavro` |
+| **Instruments** | Cavro XLP 6000, Cavro XMP 6000, Cavro XCalibur (with 3-port, 4-port or distribution valves, or valveless) |
+| **Interfaces** | RS-232, RS-485 (with an RS-485 adapter), serial-to-Ethernet adapters |
+| **Protocol** | Cavro DT protocol ([XLP 6000 Operating Manual, 734237-C, chapter 3 and appendix G](https://www.manualslib.com/manual/1214060/Tecan-Cavro-Xlp-6000.html)); step resolution per [Tecan XCalibur](https://partnering.tecan.com/cavro-xcalibur-pump-for-oem-liquid-handling) / [XMP 6000](https://partnering.tecan.com/cavro-xmp-6000-pump-for-oem-liquid-handling) specifications |
+| **Status** | 🧪 **simulated**: tested against a wire-level simulator, not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-cavro --simulate --check
+```
+
+The simulator is an XLP 6000 with a 1 mL syringe and a 3-port valve. Moves take real time; add `--option sim_speed=10` to speed it up.
+
+## Connect your pump
+
+1. **Pump setup:** set the **address switch** (switch 0 is DT address `1`, switch 1 is `2`, … switch 8 is `9`, switches 9–E are `:` `;` `<` `=` `>` `?`). The pump detects DT versus OEM protocol from the first message after power-up. The default is **9600 baud, 8N1**; 38400 baud is selected with the `U47` configuration command.
+2. **Tell the server what is installed.** The pump cannot report its syringe, so these options are **required** on real hardware:
+   - `--option syringe_ul=1000`: syringe volume in µL.
+   - `--option model=xlp6000` (or `xmp6000`, 6000 increments per stroke; `xcalibur`, 3000). For another DT-compatible pump, give `--option steps_per_stroke=<increments per full stroke in standard mode>` instead.
+   - Optional: `--option resolution=fine` (N1, 8× finer volume steps; applied by `initialize`) and `--option pump_address=2`.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-cavro --address /dev/ttyUSB0 --option syringe_ul=1000 --option model=xcalibur --check
+   uvx labmcp-cavro --address COM3 --option syringe_ul=500 --option model=xlp6000 --check
+   ```
+   Non-default baud rates go in the address: `serial://COM3?baudrate=38400`.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add cavro -- uvx labmcp-cavro --address /dev/ttyUSB0 --option syringe_ul=1000 --option model=xcalibur
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "cavro": {
+      "command": "uvx",
+      "args": ["labmcp-cavro", "--address", "/dev/ttyUSB0",
+               "--option", "syringe_ul=1000", "--option", "model=xcalibur"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow status reads but block every move.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `aspirate_ul` | ⚠️ hazard | Draw `volume_ul` into the syringe at `flow_ul_s` through the current (or given) valve port, and wait until the move has finished. The pump must be initialized and have room for the volume. |
+| `dispense_ul` | ⚠️ hazard | Push `volume_ul` out of the syringe at `flow_ul_s` through the current (or given) valve port, and wait until the move has finished. The syringe must contain at least that volume. |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_status` | 👁 read | Report whether the pump is ready or busy, any error (decoded), the plunger position as the volume in the syringe, the valve position, resolution mode and current top speed. |
+| `initialize` | ⚠️ hazard | Initialize the pump: drive the plunger to the top of the syringe (expelling its contents through the valve), set that as position 0 and home the valve. Needed after power-up, a plunger overload or `terminate`. Route the valve output to waste first. Takes a few seconds. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `set_valve` | ⚠️ hazard | Turn the valve to a named position (3/4-port valves) or to a numbered port (distribution valves). In bypass the plunger cannot move. Returns the new status. |
+| `terminate` | 🛑 safety | Stop any plunger move, loop or delay immediately (DT command T). A valve move in progress still completes. Re-initialize afterwards: the plunger may have lost steps. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_volume_ul` | 5000 µL | Largest volume one `aspirate_ul`/`dispense_ul` may move |
+| `max_flow_ul_s` | 500 µL/s | Highest plunger flow rate an agent may use |
+
+Override at launch: `--limit max_flow_ul_s=50`. Independently of the limits, the server refuses moves that would overfill or over-empty the syringe, and flows the pump cannot produce with the installed syringe (top speed 5–6000 pulses/s).
+
+## Example prompts
+
+- "Initialize the pump, then prime it: aspirate 1 mL from the input port and dispense it to the output port, three times."
+- "Aspirate 150 µL of sample slowly (20 µL/s) from port 3 and dispense 50 µL into port 5."
+- "How much liquid is in the syringe right now and which port is the valve on?"
+- "The pump reported a plunger overload. What does that mean and what should I check?"
+- "Stop the pump now."
+
+## Notes
+
+- **Conversion.** Steps = volume × steps-per-stroke ÷ syringe volume, where steps-per-stroke is 6000 (XLP/XMP) or 3000 (XCalibur) in standard mode and 8× that in fine-positioning mode (N1). The mode is read from the pump (`?28`) before every move. Top speed `V` = flow × 6000 ÷ syringe volume: on all three models a full stroke is 6000 speed pulses in N0/N1. For the XCalibur this is derived from Tecan's published 1.2 s–20 min per stroke, not from its operating manual; please confirm on hardware.
+- **Busy/ready** is read only from `Q`, as the manual requires. Invalid commands are reported immediately; invalid operands (e.g. a move past the end of the syringe) are reported by the next `Q`, and the server turns both into clear errors.
+- **Initialization force** is chosen from the syringe size (full ≥ 1 mL, half for 250/500 µL, third for 50/100 µL; manual table 3-6) unless you pick one.
+- **`terminate`** sends `T` without `R`: in the DT command set `R` resumes a terminated string. `T` does not stop a valve move in progress. Re-initialize after terminating.
+- The server does not use microstep mode (N2), the OEM protocol (checksums, sequence numbers) or CAN.
+- **Cavro Centris** has a different resolution (181,490 increments per stroke) and volume-based firmware commands that we could not verify, so it is not supported. XE 1000 and older XL/XP 3000 pumps may work with `--option steps_per_stroke=…`, but they are untested.
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_cavro-0.1.0/README.md

@@ -0,0 +1,106 @@
+# Tecan Cavro Syringe Pump — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-cavro -->
+
+Let an AI agent initialize, aspirate and dispense microlitre volumes at set flow rates, switch valve ports and stop **Tecan Cavro OEM syringe pumps** through the documented **Cavro Data Terminal (DT) protocol**.
+
+| | |
+|---|---|
+| **Package** | `labmcp-cavro` |
+| **Instruments** | Cavro XLP 6000, Cavro XMP 6000, Cavro XCalibur (with 3-port, 4-port or distribution valves, or valveless) |
+| **Interfaces** | RS-232, RS-485 (with an RS-485 adapter), serial-to-Ethernet adapters |
+| **Protocol** | Cavro DT protocol ([XLP 6000 Operating Manual, 734237-C, chapter 3 and appendix G](https://www.manualslib.com/manual/1214060/Tecan-Cavro-Xlp-6000.html)); step resolution per [Tecan XCalibur](https://partnering.tecan.com/cavro-xcalibur-pump-for-oem-liquid-handling) / [XMP 6000](https://partnering.tecan.com/cavro-xmp-6000-pump-for-oem-liquid-handling) specifications |
+| **Status** | 🧪 **simulated**: tested against a wire-level simulator, not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-cavro --simulate --check
+```
+
+The simulator is an XLP 6000 with a 1 mL syringe and a 3-port valve. Moves take real time; add `--option sim_speed=10` to speed it up.
+
+## Connect your pump
+
+1. **Pump setup:** set the **address switch** (switch 0 is DT address `1`, switch 1 is `2`, … switch 8 is `9`, switches 9–E are `:` `;` `<` `=` `>` `?`). The pump detects DT versus OEM protocol from the first message after power-up. The default is **9600 baud, 8N1**; 38400 baud is selected with the `U47` configuration command.
+2. **Tell the server what is installed.** The pump cannot report its syringe, so these options are **required** on real hardware:
+   - `--option syringe_ul=1000`: syringe volume in µL.
+   - `--option model=xlp6000` (or `xmp6000`, 6000 increments per stroke; `xcalibur`, 3000). For another DT-compatible pump, give `--option steps_per_stroke=<increments per full stroke in standard mode>` instead.
+   - Optional: `--option resolution=fine` (N1, 8× finer volume steps; applied by `initialize`) and `--option pump_address=2`.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-cavro --address /dev/ttyUSB0 --option syringe_ul=1000 --option model=xcalibur --check
+   uvx labmcp-cavro --address COM3 --option syringe_ul=500 --option model=xlp6000 --check
+   ```
+   Non-default baud rates go in the address: `serial://COM3?baudrate=38400`.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add cavro -- uvx labmcp-cavro --address /dev/ttyUSB0 --option syringe_ul=1000 --option model=xcalibur
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "cavro": {
+      "command": "uvx",
+      "args": ["labmcp-cavro", "--address", "/dev/ttyUSB0",
+               "--option", "syringe_ul=1000", "--option", "model=xcalibur"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow status reads but block every move.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `aspirate_ul` | ⚠️ hazard | Draw `volume_ul` into the syringe at `flow_ul_s` through the current (or given) valve port, and wait until the move has finished. The pump must be initialized and have room for the volume. |
+| `dispense_ul` | ⚠️ hazard | Push `volume_ul` out of the syringe at `flow_ul_s` through the current (or given) valve port, and wait until the move has finished. The syringe must contain at least that volume. |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_status` | 👁 read | Report whether the pump is ready or busy, any error (decoded), the plunger position as the volume in the syringe, the valve position, resolution mode and current top speed. |
+| `initialize` | ⚠️ hazard | Initialize the pump: drive the plunger to the top of the syringe (expelling its contents through the valve), set that as position 0 and home the valve. Needed after power-up, a plunger overload or `terminate`. Route the valve output to waste first. Takes a few seconds. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `set_valve` | ⚠️ hazard | Turn the valve to a named position (3/4-port valves) or to a numbered port (distribution valves). In bypass the plunger cannot move. Returns the new status. |
+| `terminate` | 🛑 safety | Stop any plunger move, loop or delay immediately (DT command T). A valve move in progress still completes. Re-initialize afterwards: the plunger may have lost steps. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_volume_ul` | 5000 µL | Largest volume one `aspirate_ul`/`dispense_ul` may move |
+| `max_flow_ul_s` | 500 µL/s | Highest plunger flow rate an agent may use |
+
+Override at launch: `--limit max_flow_ul_s=50`. Independently of the limits, the server refuses moves that would overfill or over-empty the syringe, and flows the pump cannot produce with the installed syringe (top speed 5–6000 pulses/s).
+
+## Example prompts
+
+- "Initialize the pump, then prime it: aspirate 1 mL from the input port and dispense it to the output port, three times."
+- "Aspirate 150 µL of sample slowly (20 µL/s) from port 3 and dispense 50 µL into port 5."
+- "How much liquid is in the syringe right now and which port is the valve on?"
+- "The pump reported a plunger overload. What does that mean and what should I check?"
+- "Stop the pump now."
+
+## Notes
+
+- **Conversion.** Steps = volume × steps-per-stroke ÷ syringe volume, where steps-per-stroke is 6000 (XLP/XMP) or 3000 (XCalibur) in standard mode and 8× that in fine-positioning mode (N1). The mode is read from the pump (`?28`) before every move. Top speed `V` = flow × 6000 ÷ syringe volume: on all three models a full stroke is 6000 speed pulses in N0/N1. For the XCalibur this is derived from Tecan's published 1.2 s–20 min per stroke, not from its operating manual; please confirm on hardware.
+- **Busy/ready** is read only from `Q`, as the manual requires. Invalid commands are reported immediately; invalid operands (e.g. a move past the end of the syringe) are reported by the next `Q`, and the server turns both into clear errors.
+- **Initialization force** is chosen from the syringe size (full ≥ 1 mL, half for 250/500 µL, third for 50/100 µL; manual table 3-6) unless you pick one.
+- **`terminate`** sends `T` without `R`: in the DT command set `R` resumes a terminated string. `T` does not stop a valve move in progress. Re-initialize after terminating.
+- The server does not use microstep mode (N2), the OEM protocol (checksums, sequence numbers) or CAN.
+- **Cavro Centris** has a different resolution (181,490 increments per stroke) and volume-based firmware commands that we could not verify, so it is not supported. XE 1000 and older XL/XP 3000 pumps may work with `--option steps_per_stroke=…`, but they are untested.
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_cavro-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "labmcp-cavro"
+version = "0.1.0"
+description = "MCP server for Tecan Cavro syringe pumps (XLP 6000, XMP 6000, XCalibur) over the DT protocol: initialize, aspirate/dispense µL, switch valve ports, terminate."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "K-Dense and LabMCP contributors" }]
+keywords = ["mcp", "lab-instrument", "syringe-pump", "tecan", "cavro", "xcalibur", "xlp6000", "liquid-handling"]
+dependencies = ["labmcp>=0.1,<0.2"]
+
+[project.scripts]
+labmcp-cavro = "labmcp_cavro.server:main"
+
+[project.urls]
+Homepage = "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/biology/tecan-cavro-pump"
+
+[tool.labmcp]
+name = "Tecan Cavro Syringe Pump"
+domain = "biology"
+category = "Liquid handling"
+vendor = "Tecan"
+models = ["Cavro XLP 6000", "Cavro XMP 6000", "Cavro XCalibur"]
+interfaces = ["RS-232", "RS-485 (via adapter)", "Serial-to-Ethernet"]
+protocol = "Cavro Data Terminal (DT) protocol"
+summary = "Initialize, aspirate and dispense microlitre volumes at set flow rates, switch valve ports, read plunger/valve status, terminate moves."
+status = "simulated"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labmcp_cavro"]

labmcp_cavro-0.1.0/server.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.K-Dense-AI/labmcp-cavro",
+  "title": "Tecan Cavro Syringe Pump",
+  "description": "MCP server for Tecan Cavro syringe pumps (XLP 6000, XMP 6000, XCalibur) over the DT protocol: initia",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/K-Dense-AI/lab-instrument-mcps",
+    "source": "github",
+    "subfolder": "servers/biology/tecan-cavro-pump"
+  },
+  "websiteUrl": "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/biology/tecan-cavro-pump",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "labmcp-cavro",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "LABMCP_ADDRESS",
+          "description": "Instrument address, e.g. serial:///dev/ttyUSB0 or tcp://192.168.1.50:5025",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_SIMULATE",
+          "description": "Set to 1 to use the built-in simulator (no hardware)",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_READ_ONLY",
+          "description": "Set to 1 to disable all state-changing tools",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_LIMITS",
+          "description": "Safety limit overrides, e.g. max_temperature_c=80",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

labmcp_cavro-0.1.0/src/labmcp_cavro/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for Tecan Cavro syringe pumps (XLP 6000, XMP 6000, XCalibur; DT protocol)."""

labmcp_cavro-0.1.0/src/labmcp_cavro/driver.py

@@ -0,0 +1,276 @@
+"""Tecan Cavro syringe-pump driver (Data Terminal "DT" protocol over RS-232/RS-485).
+
+Command set, framing, status byte and error codes as documented in the
+"Cavro XLP 6000 Modular Syringe Pump Operating Manual", Tecan Systems, document 734237-C
+(October 2005), chapter 3 "Software Communication" and appendix G "Command Quick Reference":
+https://www.manualslib.com/manual/1214060/Tecan-Cavro-Xlp-6000.html
+
+Wire format (DT protocol, 9600 baud 8N1 by default)::
+
+    to pump:    "/" <address> <commands> CR          e.g. "/1ZR\\r"  (switch 0 = address "1")
+    from pump:  "/" "0" <status> [<data>] ETX CR LF   e.g. "/0`3000\\x03\\r\\n"
+
+Status byte: ``0 1 X 0 e3 e2 e1 e0`` - bit 5 (X) is 1 when the pump is ready and 0 when busy;
+bits 0-3 hold the error code. Only the ``Q`` reply's busy bit is authoritative (manual 3.6.1);
+the error bits are valid in every reply.
+
+Resolution (manual 3.3.2 "N" command, appendix E): N0 = standard mode, positions in
+half-steps; N1 = fine positioning, positions in microsteps (x8) with speeds still in half-steps/s;
+N2 = microstep mode (x8 positions and speeds). Full stroke is 6000 / 48000 increments on the
+XLP 6000 and XMP 6000, 3000 / 24000 on the XCalibur (Tecan product specifications). Speeds
+``V`` (5-6000 pulses/s) span 6000 pulses per full stroke in N0/N1 on all three models, which
+gives the documented 1.2 s - 20 min per stroke.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+import time
+from dataclasses import dataclass
+
+from labmcp import InstrumentProtocolError, InstrumentTimeout, Transport
+
+#: DT address characters for address-switch positions 0..E (manual table 3-1/3-2).
+ADDRESSES = "123456789:;<=>?"
+
+#: Pump families with a verified number of plunger increments per full stroke in N0.
+MODELS: dict[str, tuple[str, int]] = {
+    "xlp6000": ("Cavro XLP 6000", 6000),
+    "xmp6000": ("Cavro XMP 6000", 6000),
+    "xcalibur": ("Cavro XCalibur", 3000),
+}
+
+#: Speed pulses per full stroke in N0/N1 (V is in half-steps/s): V5 = 20 min/stroke, V6000 ~ 1 s.
+SPEED_PULSES_PER_STROKE = 6000
+TOP_SPEED_MIN, TOP_SPEED_MAX = 5, 6000
+
+ERROR_CODES: dict[int, str] = {
+    0: "no error",
+    1: "initialization error: the pump failed to initialize (check for blockages and loose "
+    "connections, then initialize again)",
+    2: "invalid command",
+    3: "invalid operand (parameter out of range, e.g. a move beyond the end of the syringe)",
+    6: "EEPROM failure (contact Tecan service)",
+    7: "device not initialized: run `initialize` first",
+    8: "internal failure (contact Tecan service)",
+    9: "plunger overload: plunger movement blocked by excessive back-pressure; the pump must be "
+    "re-initialized",
+    10: "valve overload: the valve drive is blocked; re-initialize (or send a valve command)",
+    11: "plunger move not allowed: the valve is in the bypass/throughput position",
+    12: "internal failure (contact Tecan service)",
+    14: "A/D converter failure (contact Tecan service)",
+    15: "command overflow: a command was sent while the pump was still busy",
+}
+
+#: Initialization force codes (manual table 3-6): 0 full (>= 1 mL), 1 half (250/500 µL), 2 third (50/100 µL).
+FORCE_CODES = {"full": 0, "half": 1, "third": 2}
+
+
+def force_for_syringe(syringe_ul: float) -> int:
+    """Recommended initialization force code for a syringe size (manual table 3-6)."""
+    if syringe_ul >= 1000:
+        return 0
+    if syringe_ul >= 250:
+        return 1
+    return 2
+
+
+class CavroError(InstrumentProtocolError):
+    """The pump reported a non-zero error code in its status byte."""
+
+    def __init__(self, code: int, context: str) -> None:
+        self.code = code
+        meaning = ERROR_CODES.get(code, "unknown error (see your pump's operating manual)")
+        super().__init__(f"Pump reported error {code} {context}: {meaning}.")
+
+
+@dataclass
+class Reply:
+    status: int
+    data: str
+
+    @property
+    def ready(self) -> bool:
+        return bool(self.status & 0x20)
+
+    @property
+    def error(self) -> int:
+        return self.status & 0x0F
+
+
+@dataclass
+class MoveResult:
+    steps: int
+    top_speed: int
+    position_steps: int
+    terminated: bool
+
+
+class CavroPump:
+    """One Cavro pump addressed with the DT protocol."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        *,
+        address: str = "1",
+        syringe_ul: float = 1000.0,
+        model: str = "xlp6000",
+        standard_steps: int | None = None,
+        resolution_mode: int = 0,
+    ) -> None:
+        if address not in ADDRESSES or len(address) != 1:
+            raise ValueError(f"Pump address must be one of {ADDRESSES!r} (switch 0 = '1'), got {address!r}")
+        if resolution_mode not in (0, 1):
+            raise ValueError("resolution_mode must be 0 (standard) or 1 (fine positioning)")
+        self.t = transport
+        self.address = address
+        self.syringe_ul = float(syringe_ul)
+        self.model_name, default_steps = MODELS.get(model, (model, 0))
+        self.standard_steps = int(standard_steps or default_steps)
+        if self.standard_steps <= 0:
+            raise ValueError(f"Unknown pump model {model!r}; give the steps per stroke explicitly")
+        self.resolution_mode = resolution_mode
+        self._terminate = threading.Event()
+
+    # ------------------------------------------------------------ low level
+
+    def send(self, cmd: str, timeout: float | None = None) -> Reply:
+        """Send one DT command string and parse the answer block (errors are returned, not raised)."""
+        raw = self.t.query(f"/{self.address}{cmd}", timeout)
+        start = raw.rfind("/0")
+        if start < 0 or len(raw) < start + 3:
+            raise InstrumentProtocolError(
+                f"Unexpected answer to {cmd!r}: {raw!r} (expected '/0<status>...'). Check the pump "
+                "address switch and that the pump uses the DT protocol at this baud rate."
+            )
+        status = ord(raw[start + 2])
+        if status & 0xD0 != 0x40:  # bits 7..6 must be 01 and bit 4 must be 0
+            raise InstrumentProtocolError(f"Invalid status byte {status:#04x} in answer to {cmd!r}: {raw!r}")
+        return Reply(status, raw[start + 3 :])
+
+    def command(self, cmd: str, timeout: float | None = None) -> Reply:
+        """Send ``cmd`` and raise :class:`CavroError` if the answer carries an error code."""
+        reply = self.send(cmd, timeout)
+        if reply.error:
+            raise CavroError(reply.error, f"in reply to {cmd!r}")
+        return reply
+
+    def query_status(self) -> Reply:
+        """``Q``: the only authoritative ready/busy report (manual 3.6.1). Errors are returned."""
+        return self.send("Q")
+
+    def report(self, cmd: str) -> str:
+        return self.command(cmd).data.strip()
+
+    def _report_int(self, cmd: str) -> int:
+        data = self.report(cmd)
+        try:
+            return int(data)
+        except ValueError as exc:
+            raise InstrumentProtocolError(f"Expected an integer in answer to {cmd!r}, got {data!r}") from exc
+
+    def wait_ready(self, timeout: float, poll: float = 0.1, context: str = "") -> None:
+        """Poll ``Q`` until the pump is ready; raise on any error code."""
+        deadline = time.monotonic() + timeout
+        while True:
+            reply = self.query_status()
+            if reply.error:
+                raise CavroError(reply.error, context or "while waiting for the pump")
+            if reply.ready:
+                return
+            if time.monotonic() > deadline:
+                raise InstrumentTimeout(
+                    f"Pump still busy after {timeout:.0f} s {context}. Call `terminate` if it should stop."
+                )
+            time.sleep(poll)
+
+    # ------------------------------------------------------------ reports
+
+    def plunger_steps(self) -> int:
+        return self._report_int("?")
+
+    def valve_position(self) -> str:
+        return self.report("?6")
+
+    def mode(self) -> int:
+        return self._report_int("?28")
+
+    def top_speed(self) -> int:
+        return self._report_int("?2")
+
+    def firmware(self) -> str:
+        return self.report("&")
+
+    def steps_per_stroke(self, mode: int | None = None) -> int:
+        mode = self.mode() if mode is None else mode
+        return self.standard_steps * (8 if mode in (1, 2) else 1)
+
+    def identify(self) -> dict[str, str]:
+        info = {"manufacturer": "Tecan (Cavro)", "model": self.model_name, "pump_address": self.address}
+        with contextlib.suppress(InstrumentProtocolError):
+            info["firmware"] = self.firmware()
+        info["syringe_ul"] = f"{self.syringe_ul:g}"
+        info["steps_per_stroke_standard"] = str(self.standard_steps)
+        return info
+
+    # ------------------------------------------------------------ actions
+
+    def initialize(
+        self,
+        kind: str = "Z",
+        force: int | None = None,
+        input_port: int | None = None,
+        output_port: int | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        """``Z`` (valve homes CW), ``Y`` (CCW) or ``W`` (plunger only), then set N mode."""
+        if kind not in {"Z", "Y", "W"}:
+            raise ValueError("kind must be 'Z', 'Y' or 'W'")
+        force = force_for_syringe(self.syringe_ul) if force is None else force
+        if kind == "W" or (input_port is None and output_port is None):
+            cmd = f"{kind}{force}R"
+        else:
+            cmd = f"{kind}{force},{input_port or 0},{output_port or 0}R"
+        self._require_ready("initialize")
+        reply = self.send(cmd)
+        # Errors 1/7/9/10 describe the state initialization is meant to clear; the outcome is read
+        # from Q afterwards (manual 3.6.3 "Initialization Errors").
+        if reply.error and reply.error not in {1, 7, 9, 10}:
+            raise CavroError(reply.error, f"in reply to {cmd!r}")
+        self.wait_ready(timeout, context="during initialization")
+        self.command(f"N{self.resolution_mode}R")
+        self.wait_ready(5.0, context="after setting the resolution mode")
+
+    def _require_ready(self, action: str) -> None:
+        reply = self.query_status()
+        if not reply.ready:
+            raise InstrumentProtocolError(f"Cannot {action}: the pump is busy. Wait, or call `terminate`.")
+
+    def move_plunger(self, kind: str, steps: int, top_speed: int, timeout: float) -> MoveResult:
+        """``A`` absolute, ``P`` pick-up (down) or ``D`` dispense (up) at top speed ``V``."""
+        if kind not in {"A", "P", "D"}:
+            raise ValueError("kind must be 'A', 'P' or 'D'")
+        if not TOP_SPEED_MIN <= top_speed <= TOP_SPEED_MAX:
+            raise ValueError(f"top speed must be {TOP_SPEED_MIN}-{TOP_SPEED_MAX} pulses/s")
+        self._require_ready("move the plunger")
+        self._terminate.clear()
+        self.command(f"V{top_speed}{kind}{steps}R")
+        self.wait_ready(timeout, context=f"during the plunger move {kind}{steps}")
+        return MoveResult(steps, top_speed, self.plunger_steps(), self._terminate.is_set())
+
+    def move_valve(self, code: str, timeout: float = 10.0) -> str:
+        """Valve command: ``I``/``O``/``B``/``E`` (non-distribution) or ``I<n>``/``O<n>`` (distribution)."""
+        self._require_ready("move the valve")
+        self.command(f"{code}R")
+        self.wait_ready(timeout, context=f"during the valve move {code}")
+        return self.valve_position()
+
+    def terminate(self) -> Reply:
+        """``T``: stop plunger moves, loops and delays immediately (valve moves finish)."""
+        self._terminate.set()
+        return self.send("T")
+
+    def close(self) -> None:
+        self.t.close()