labmcp-julabo 0.1.0__tar.gz

labmcp_julabo-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_julabo-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: labmcp-julabo
+Version: 0.1.0
+Summary: MCP server for JULABO heating and refrigerated circulators (CORIO, MAGIO, DYNEO): read temperatures, set setpoint, start/stop, alarms.
+Project-URL: Homepage, https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/julabo-circulator
+Author: K-Dense and LabMCP contributors
+License-Expression: Apache-2.0
+Keywords: chiller,circulator,julabo,lab-instrument,mcp,temperature-control,thermostat
+Requires-Python: >=3.10
+Requires-Dist: labmcp<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# JULABO Circulator — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-julabo -->
+
+Let an AI agent run **JULABO heating and refrigerated circulators** through JULABO's documented interface commands: read the bath and external temperatures and the heating/cooling power, set the setpoint, start and stop temperature control, decode status and alarm messages, and wait until the bath is stable at temperature.
+
+| | |
+|---|---|
+| **Package** | `labmcp-julabo` |
+| **Instruments** | CORIO CD, CORIO CP, MAGIO MS (and MX), DYNEO DD circulators. PRESTO and older JULABO models use a similar command set but are unverified |
+| **Interfaces** | USB (virtual COM port), RS-232 (CORIO CP, MAGIO, DYNEO) |
+| **Protocol** | JULABO interface commands, appendix "Interface commands" of the original operating manuals: [CORIO CD](https://pim-resources.coleparmer.com/instruction-manual/corio-cd-circulator-manual.pdf) (1.950.0800.us.V10), [CORIO CP](https://pim-resources.coleparmer.com/instruction-manual/corio-cp-operating-manual-1-950-0900-us.pdf) (1.950.0900.us.V04), [MAGIO MS](https://pim-resources.coleparmer.com/instruction-manual/magio-ms-operating-manual-1-950-1700-us-v05.pdf) (1.950.1700.us.V05), [DYNEO DD](https://pim-resources.coleparmer.com/instruction-manual/dyneo-dd-operating-manual-1-950-1300-us-v03.pdf) (1.950.1300.us.V03). Official downloads: [julabo.com](https://www.julabo.com/en/service/downloads/operating-manuals) |
+| **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-julabo --simulate --check
+```
+
+## Connect your circulator
+
+1. **Enable remote control on the circulator.** Without it the circulator answers queries but ignores every setting command.
+   - CORIO CD/CP: `MENU` → `IntE` → `rEM` → `USb` (or `232` for RS-232). `rOFF` appears in standby.
+   - MAGIO / DYNEO: Main menu → Connect unit → Remote control → USB or RS232. An "R" appears in the status bar.
+2. **Cable:** USB-B (the circulator appears as a virtual COM port; on Windows install JULABO's USB driver) or a **null-modem** RS-232 cable. RS-232 factory settings: **4800 baud, 7 data bits, even parity, 1 stop bit, hardware handshake (RTS/CTS)**. Interface parameters can only be changed while remote control is off. The server uses these settings but does not enforce the handshake by default (it keeps RTS asserted, which lets the circulator transmit, and USB virtual COM ports often never assert CTS); add `?rtscts=true` to the address to enforce it.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-julabo --address /dev/ttyACM0 --check                  # Linux (USB)
+   uvx labmcp-julabo --address /dev/tty.usbmodem1101 --check         # macOS
+   uvx labmcp-julabo --address COM3 --check                          # Windows
+   uvx labmcp-julabo --address "serial://COM3?baudrate=9600" --check # RS-232, non-default baud rate
+   ```
+   `--check` prints the firmware string (`version`) and the current status, e.g. `02 REMOTE STOP`.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add julabo -- uvx labmcp-julabo --address /dev/ttyACM0
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "julabo": {
+      "command": "uvx",
+      "args": ["labmcp-julabo", "--address", "/dev/ttyACM0", "--limit", "max_temperature_c=120"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow monitoring only (`stop_circulation` stays available). For other clients: `uvx labmcp config julabo-circulator --address /dev/ttyACM0 --client vscode`.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `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_setpoint` | 👁 read | Read the current temperature setpoint and whether temperature control is running. |
+| `get_status` | 👁 read | Report the circulator's status message (decoded: operating state, rejected command or alarm), whether temperature control is running, the setpoint, the device's own excess-temperature protection setting and warning limits, and the firmware version. |
+| `read_temperatures` | 👁 read | Read the bath temperature, the heating/cooling power in % and the safety-sensor temperature, and optionally the external Pt100 sensor. |
+| `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_setpoint` | ⚠️ hazard | Set the circulator's temperature setpoint (out_sp_00). If temperature control is running, the circulator starts heating or cooling to it immediately. Refused outside `min_temperature_c`..`max_temperature_c`; the circulator itself also rejects values outside its range or warning limits (reported as an error). Needs remote control enabled. |
+| `start_circulation` | ⚠️ hazard | Start temperature control (out_mode_05 1): the pump runs and the bath heats or cools to the setpoint, which is checked against the safety limits first (it may have been changed on the front panel). Make sure the bath is filled and any external hoses are connected and secured. Needs remote control enabled. |
+| `stop_circulation` | 🛑 safety | Stop temperature control and the pump (out_mode_05 0), then confirm with in_mode_05. Also ends a running `wait_for_temperature`. The bath stays hot/cold after stopping. |
+| `wait_for_temperature` | 👁 read | Poll the bath (or external) temperature until it has been within `tolerance_c` of the target for `stable_for_s` seconds, or `timeout_s` passes. Does not change anything; start circulation first. Stops early (reached = false) if the circulator raises an alarm or a stop command is sent. Returns a short temperature trace. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_temperature_c` | 90 °C | Highest setpoint an agent may set (also checked before `start_circulation`) |
+| `min_temperature_c` | 5 °C | Lowest setpoint an agent may set (also checked before `start_circulation`) |
+| `max_wait_s` | 7200 s | Longest `wait_for_temperature` |
+
+The defaults suit a **water** bath. Set them to your bath fluid's working range, e.g. `--limit min_temperature_c=-30 --limit max_temperature_c=150` for a silicone oil / glycol-rated setup. The circulator additionally enforces its own working range, warning limits and excess-temperature protection; rejections come back as errors such as `-11 VALUE TOO LARGE`.
+
+## Example prompts
+
+- "Set the circulator to 37 °C, start it and tell me when the bath has been stable within ±0.1 °C for five minutes."
+- "What's the bath temperature and how hard is the circulator working right now?"
+- "Cool the jacketed reactor to 10 °C using the external Pt100 as the reference and let me know when it gets there."
+- "Is there any alarm on the circulator? Explain what it means."
+- "Stop the circulator."
+
+## Notes
+
+- **Remote control is a front-panel setting.** In manual mode (`00 MANUAL STOP` / `01 MANUAL START`) the server refuses to send settings and tells you how to enable remote control.
+- **Every setting is verified.** OUT commands have no reply, so after each one the server queries `status` (to catch `-08 INVALID COMMAND`, `-09 COMMAND NOT ALLOWED IN CURRENT OPERATING MODE`, `-10 VALUE TOO SMALL`, `-11 VALUE TOO LARGE`, `-13 VALUE EXCEEDS TEMPERATURE LIMITS`) and reads the setpoint or `in_mode_05` back. `stop_circulation` retries once and reports an error if the circulator still says it is running.
+- **Model differences.** CORIO CD has only the basic set (actual value, power, safety sensor, setpoint, start/stop). Warning limits (`in_sp_03/04`) need CORIO CP, MAGIO or DYNEO; the external Pt100 (`in_pv_02`) needs MAGIO or DYNEO. The server detects missing commands (no reply) and reports those values as `null`.
+- **Command pacing (unverified).** The manuals give no minimum time between commands. The server waits `command_delay_s` (default 0.25 s) after each setting command before checking `status`; change it with `--option command_delay_s=0.5` if your circulator misses commands.
+- **Watchdog.** MAGIO/DYNEO circulators have a watchdog configured in their own menu (mode, timeout, fallback setpoint, reset on "setpoint only" or "all valid commands"). The server does not configure it. With restart mode "all valid commands" you can keep it fed while the server runs with `--option keepalive_s=10` (queries `status` every 10 s). JULABO's alarm list notes that it expects the setpoint at least every 30 s in "setpoint" restart mode, which this keep-alive does not do.
+- Status and alarm texts are decoded from the code (`-01`, `-14`, `-63`, ...) using the alarm tables in the manuals; the exact wording the circulator sends is passed through unchanged.
+- Not implemented: pump stage/capacity (`out_sp_07/27`), warning-limit writes (`out_sp_03/04`), controller parameters (`out_par_*`), external/internal control switch (`out_mode_04`), EPROG and ATC calibration commands.
+
+## 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_julabo-0.1.0/README.md

@@ -0,0 +1,107 @@
+# JULABO Circulator — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-julabo -->
+
+Let an AI agent run **JULABO heating and refrigerated circulators** through JULABO's documented interface commands: read the bath and external temperatures and the heating/cooling power, set the setpoint, start and stop temperature control, decode status and alarm messages, and wait until the bath is stable at temperature.
+
+| | |
+|---|---|
+| **Package** | `labmcp-julabo` |
+| **Instruments** | CORIO CD, CORIO CP, MAGIO MS (and MX), DYNEO DD circulators. PRESTO and older JULABO models use a similar command set but are unverified |
+| **Interfaces** | USB (virtual COM port), RS-232 (CORIO CP, MAGIO, DYNEO) |
+| **Protocol** | JULABO interface commands, appendix "Interface commands" of the original operating manuals: [CORIO CD](https://pim-resources.coleparmer.com/instruction-manual/corio-cd-circulator-manual.pdf) (1.950.0800.us.V10), [CORIO CP](https://pim-resources.coleparmer.com/instruction-manual/corio-cp-operating-manual-1-950-0900-us.pdf) (1.950.0900.us.V04), [MAGIO MS](https://pim-resources.coleparmer.com/instruction-manual/magio-ms-operating-manual-1-950-1700-us-v05.pdf) (1.950.1700.us.V05), [DYNEO DD](https://pim-resources.coleparmer.com/instruction-manual/dyneo-dd-operating-manual-1-950-1300-us-v03.pdf) (1.950.1300.us.V03). Official downloads: [julabo.com](https://www.julabo.com/en/service/downloads/operating-manuals) |
+| **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-julabo --simulate --check
+```
+
+## Connect your circulator
+
+1. **Enable remote control on the circulator.** Without it the circulator answers queries but ignores every setting command.
+   - CORIO CD/CP: `MENU` → `IntE` → `rEM` → `USb` (or `232` for RS-232). `rOFF` appears in standby.
+   - MAGIO / DYNEO: Main menu → Connect unit → Remote control → USB or RS232. An "R" appears in the status bar.
+2. **Cable:** USB-B (the circulator appears as a virtual COM port; on Windows install JULABO's USB driver) or a **null-modem** RS-232 cable. RS-232 factory settings: **4800 baud, 7 data bits, even parity, 1 stop bit, hardware handshake (RTS/CTS)**. Interface parameters can only be changed while remote control is off. The server uses these settings but does not enforce the handshake by default (it keeps RTS asserted, which lets the circulator transmit, and USB virtual COM ports often never assert CTS); add `?rtscts=true` to the address to enforce it.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-julabo --address /dev/ttyACM0 --check                  # Linux (USB)
+   uvx labmcp-julabo --address /dev/tty.usbmodem1101 --check         # macOS
+   uvx labmcp-julabo --address COM3 --check                          # Windows
+   uvx labmcp-julabo --address "serial://COM3?baudrate=9600" --check # RS-232, non-default baud rate
+   ```
+   `--check` prints the firmware string (`version`) and the current status, e.g. `02 REMOTE STOP`.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add julabo -- uvx labmcp-julabo --address /dev/ttyACM0
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "julabo": {
+      "command": "uvx",
+      "args": ["labmcp-julabo", "--address", "/dev/ttyACM0", "--limit", "max_temperature_c=120"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow monitoring only (`stop_circulation` stays available). For other clients: `uvx labmcp config julabo-circulator --address /dev/ttyACM0 --client vscode`.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `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_setpoint` | 👁 read | Read the current temperature setpoint and whether temperature control is running. |
+| `get_status` | 👁 read | Report the circulator's status message (decoded: operating state, rejected command or alarm), whether temperature control is running, the setpoint, the device's own excess-temperature protection setting and warning limits, and the firmware version. |
+| `read_temperatures` | 👁 read | Read the bath temperature, the heating/cooling power in % and the safety-sensor temperature, and optionally the external Pt100 sensor. |
+| `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_setpoint` | ⚠️ hazard | Set the circulator's temperature setpoint (out_sp_00). If temperature control is running, the circulator starts heating or cooling to it immediately. Refused outside `min_temperature_c`..`max_temperature_c`; the circulator itself also rejects values outside its range or warning limits (reported as an error). Needs remote control enabled. |
+| `start_circulation` | ⚠️ hazard | Start temperature control (out_mode_05 1): the pump runs and the bath heats or cools to the setpoint, which is checked against the safety limits first (it may have been changed on the front panel). Make sure the bath is filled and any external hoses are connected and secured. Needs remote control enabled. |
+| `stop_circulation` | 🛑 safety | Stop temperature control and the pump (out_mode_05 0), then confirm with in_mode_05. Also ends a running `wait_for_temperature`. The bath stays hot/cold after stopping. |
+| `wait_for_temperature` | 👁 read | Poll the bath (or external) temperature until it has been within `tolerance_c` of the target for `stable_for_s` seconds, or `timeout_s` passes. Does not change anything; start circulation first. Stops early (reached = false) if the circulator raises an alarm or a stop command is sent. Returns a short temperature trace. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_temperature_c` | 90 °C | Highest setpoint an agent may set (also checked before `start_circulation`) |
+| `min_temperature_c` | 5 °C | Lowest setpoint an agent may set (also checked before `start_circulation`) |
+| `max_wait_s` | 7200 s | Longest `wait_for_temperature` |
+
+The defaults suit a **water** bath. Set them to your bath fluid's working range, e.g. `--limit min_temperature_c=-30 --limit max_temperature_c=150` for a silicone oil / glycol-rated setup. The circulator additionally enforces its own working range, warning limits and excess-temperature protection; rejections come back as errors such as `-11 VALUE TOO LARGE`.
+
+## Example prompts
+
+- "Set the circulator to 37 °C, start it and tell me when the bath has been stable within ±0.1 °C for five minutes."
+- "What's the bath temperature and how hard is the circulator working right now?"
+- "Cool the jacketed reactor to 10 °C using the external Pt100 as the reference and let me know when it gets there."
+- "Is there any alarm on the circulator? Explain what it means."
+- "Stop the circulator."
+
+## Notes
+
+- **Remote control is a front-panel setting.** In manual mode (`00 MANUAL STOP` / `01 MANUAL START`) the server refuses to send settings and tells you how to enable remote control.
+- **Every setting is verified.** OUT commands have no reply, so after each one the server queries `status` (to catch `-08 INVALID COMMAND`, `-09 COMMAND NOT ALLOWED IN CURRENT OPERATING MODE`, `-10 VALUE TOO SMALL`, `-11 VALUE TOO LARGE`, `-13 VALUE EXCEEDS TEMPERATURE LIMITS`) and reads the setpoint or `in_mode_05` back. `stop_circulation` retries once and reports an error if the circulator still says it is running.
+- **Model differences.** CORIO CD has only the basic set (actual value, power, safety sensor, setpoint, start/stop). Warning limits (`in_sp_03/04`) need CORIO CP, MAGIO or DYNEO; the external Pt100 (`in_pv_02`) needs MAGIO or DYNEO. The server detects missing commands (no reply) and reports those values as `null`.
+- **Command pacing (unverified).** The manuals give no minimum time between commands. The server waits `command_delay_s` (default 0.25 s) after each setting command before checking `status`; change it with `--option command_delay_s=0.5` if your circulator misses commands.
+- **Watchdog.** MAGIO/DYNEO circulators have a watchdog configured in their own menu (mode, timeout, fallback setpoint, reset on "setpoint only" or "all valid commands"). The server does not configure it. With restart mode "all valid commands" you can keep it fed while the server runs with `--option keepalive_s=10` (queries `status` every 10 s). JULABO's alarm list notes that it expects the setpoint at least every 30 s in "setpoint" restart mode, which this keep-alive does not do.
+- Status and alarm texts are decoded from the code (`-01`, `-14`, `-63`, ...) using the alarm tables in the manuals; the exact wording the circulator sends is passed through unchanged.
+- Not implemented: pump stage/capacity (`out_sp_07/27`), warning-limit writes (`out_sp_03/04`), controller parameters (`out_par_*`), external/internal control switch (`out_mode_04`), EPROG and ATC calibration commands.
+
+## 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_julabo-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "labmcp-julabo"
+version = "0.1.0"
+description = "MCP server for JULABO heating and refrigerated circulators (CORIO, MAGIO, DYNEO): read temperatures, set setpoint, start/stop, alarms."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "K-Dense and LabMCP contributors" }]
+keywords = ["mcp", "lab-instrument", "julabo", "circulator", "thermostat", "chiller", "temperature-control"]
+dependencies = ["labmcp>=0.1,<0.2"]
+
+[project.scripts]
+labmcp-julabo = "labmcp_julabo.server:main"
+
+[project.urls]
+Homepage = "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/julabo-circulator"
+
+[tool.labmcp]
+name = "JULABO Circulator"
+domain = "chemistry"
+category = "Temperature control"
+vendor = "JULABO"
+models = ["CORIO CD", "CORIO CP", "MAGIO MS", "DYNEO DD"]
+interfaces = ["USB (virtual COM)", "RS-232"]
+protocol = "JULABO interface commands (in_/out_/status/version)"
+summary = "Read bath/external temperature and heating power, set setpoint, start/stop tempering, decode status and alarms, wait for temperature."
+status = "simulated"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labmcp_julabo"]

labmcp_julabo-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-julabo",
+  "title": "JULABO Circulator",
+  "description": "MCP server for JULABO heating and refrigerated circulators (CORIO, MAGIO, DYNEO): read temperatures,",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/K-Dense-AI/lab-instrument-mcps",
+    "source": "github",
+    "subfolder": "servers/chemistry/julabo-circulator"
+  },
+  "websiteUrl": "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/julabo-circulator",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "labmcp-julabo",
+      "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_julabo-0.1.0/src/labmcp_julabo/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for JULABO heating and refrigerated circulators."""

labmcp_julabo-0.1.0/src/labmcp_julabo/driver.py

@@ -0,0 +1,320 @@
+"""Driver for JULABO heating and refrigerated circulators (JULABO interface commands).
+
+Commands, status messages, alarm codes and interface settings were verified in the
+"Interface commands" appendix (chapter 11) of these JULABO original operating manuals:
+
+* CORIO CD, 1.950.0800.us.V10 (03/2022),
+  https://pim-resources.coleparmer.com/instruction-manual/corio-cd-circulator-manual.pdf
+* CORIO CP, 1.950.0900.us.V04 (04/2022),
+  https://pim-resources.coleparmer.com/instruction-manual/corio-cp-operating-manual-1-950-0900-us.pdf
+* MAGIO MS, 1.950.1700.us.V05 (05/2022),
+  https://pim-resources.coleparmer.com/instruction-manual/magio-ms-operating-manual-1-950-1700-us-v05.pdf
+* DYNEO DD, 1.950.1300.us.V03 (05/2022),
+  https://pim-resources.coleparmer.com/instruction-manual/dyneo-dd-operating-manual-1-950-1300-us-v03.pdf
+
+Wire format: a command is sent as ``command CR`` or ``command SPACE parameter CR``
+(e.g. ``out_sp_00 55.5``); IN commands answer with one line ending in CR LF (``55.5``).
+OUT commands send no reply and are only accepted in remote-control mode; whether one was
+rejected is reported by the next ``status`` query (``-08 INVALID COMMAND``, ``-10 VALUE TOO
+SMALL``...), which also reports pending alarms. RS-232 factory settings: 4800 baud, 7 data
+bits, even ("straight") parity, 1 stop bit, hardware (RTS/CTS) handshake. On USB the
+circulator is a virtual COM port and these settings do not matter.
+
+Command availability differs by family: CORIO CD only has in_pv_00/01/03/04, in_sp_00,
+in_mode_05, out_sp_00, out_mode_05, version and status. CORIO CP adds the warning limits
+(in_sp_03/04); MAGIO and DYNEO add the external Pt100 sensor (in_pv_02) and more.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import re
+import threading
+import time
+from dataclasses import dataclass
+
+from labmcp import InstrumentError, InstrumentProtocolError, InstrumentTimeout, Transport
+
+log = logging.getLogger("labmcp.julabo")
+
+_STATUS_RE = re.compile(r"^\s*(-?\d+)\s*(.*?)\s*$")
+_NUMBER_RE = re.compile(r"^\s*[-+]?(?:\d+(?:\.\d*)?|\.\d+)\s*$")
+
+#: Status messages (manual 11.1.4). Codes >= 0 are operating states.
+STATES = {
+    0: ("MANUAL STOP", "standby, manual operation (remote control is not enabled)"),
+    1: ("MANUAL START", "running, manual operation (remote control is not enabled)"),
+    2: ("REMOTE STOP", "standby, remote control operation"),
+    3: ("REMOTE START", "running, remote control operation"),
+}
+
+#: Replies to a rejected command (manual 11.1.4).
+COMMAND_ERRORS = {
+    -8: "the circulator did not recognise the last command",
+    -9: "the last command is not permitted in the current operating mode (is remote control enabled?)",
+    -10: "the last value sent was too small",
+    -11: "the last value sent was too large",
+    -13: "the value is not within the temperature limits set on the circulator",
+}
+
+#: Alarms and warnings (manual 11.2; the list depends on the model).
+ALARMS = {
+    -1: "bath fluid level too low; top up the bath fluid and check the hoses",
+    -3: "measured temperature is above the high-temperature warning limit",
+    -4: "measured temperature is below the low-temperature warning limit",
+    -5: "working temperature sensor cable broken or short-circuited",
+    -6: "temperature difference between working sensor and high-temperature protection sensor too large "
+    "(increase pump capacity)",
+    -14: "the set excess-temperature protection value has been exceeded",
+    -15: "external temperature sensor line short-circuited or interrupted",
+    -33: "high-temperature protection sensor line short-circuited or interrupted",
+    -38: "setpoint is set to the external sensor but no signal is available",
+    -40: "low-level early warning: bath fluid level is critical",
+    -41: "high-level early warning: bath fluid level is critical",
+    -60: "internal read/write error; switch off at the mains, wait 4 s, switch on",
+    -61: "communication (CAN bus) error between circulator and refrigeration unit",
+    -62: "CAN bus error; switch off at the mains, wait 4 s, switch on",
+    -63: "the watchdog function has responded",
+    -70: "units with incompatible voltage/frequency variants connected, or incorrectly configured",
+    -72: "configuration between circulator and refrigeration unit failed",
+    -83: "excessive power consumption via the USB-A port",
+    -108: "alarm latch of the protective equipment is still active; power-cycle the unit",
+    -116: "alarm latch of the protective equipment is still active; power-cycle the unit",
+    -143: "over-temperature alarm limit exceeded",
+    -144: "under-temperature alarm limit exceeded",
+    -421: "ambient temperature outside the specification",
+    -427: "pressure sensor detects excessive condensation pressure",
+    -431: "maximum permissible compressor current exceeded",
+    -503: "external setpoint via EPROG selected but no analog module connected",
+    -504: "external actuating variable via EPROG selected but no analog module connected",
+    -505: "the analog module transmits an invalid setpoint",
+    -1109: "bath fluid viscosity too high or circulation rate too low",
+    -1305: "pump speed limit of the heating block not reached (motor defective or fluid too viscous)",
+    -1427: "pressure sensor detects excessive condensation pressure",
+    -1431: "compressor current below the permissible minimum",
+    -1501: "timeout on the serial interface (watchdog: send the setpoint at least every 30 s)",
+    -2426: "evaporation temperature below the warning threshold",
+}
+
+
+@dataclass
+class Status:
+    code: int
+    text: str
+    kind: str  # "state" | "command_error" | "alarm"
+    meaning: str
+
+    @property
+    def label(self) -> str:
+        """The code and text as the circulator shows them, e.g. ``03 REMOTE START`` / ``-08 ...``."""
+        return f"{self.code:03d} {self.text}" if self.code < 0 else f"{self.code:02d} {self.text}"
+
+    @property
+    def remote(self) -> bool | None:
+        return self.code in (2, 3) if self.kind == "state" else None
+
+    @property
+    def running(self) -> bool | None:
+        return self.code in (1, 3) if self.kind == "state" else None
+
+
+def parse_status(reply: str) -> Status:
+    """Parse a ``status`` reply such as ``03 REMOTE START`` or ``-01 ...``."""
+    m = _STATUS_RE.match(reply)
+    if not m:
+        raise InstrumentProtocolError(f"Unexpected reply to 'status': {reply!r}")
+    code, text = int(m.group(1)), m.group(2)
+    if code in STATES:
+        return Status(code, text or STATES[code][0], "state", STATES[code][1])
+    if code in COMMAND_ERRORS:
+        return Status(code, text, "command_error", COMMAND_ERRORS[code])
+    if code < 0:
+        return Status(code, text, "alarm", ALARMS.get(code, "alarm/warning not listed in the manual"))
+    return Status(code, text, "state", "unknown operating state")
+
+
+class JulaboCirculator:
+    def __init__(self, transport: Transport, command_delay_s: float = 0.25) -> None:
+        self.t = transport
+        #: Pause after each OUT command before the next command (see README "Notes").
+        self.command_delay_s = command_delay_s
+        #: Set by :meth:`stop` so a running wait loop ends early.
+        self.abort = threading.Event()
+        self._keepalive_stop = threading.Event()
+        self._keepalive_thread: threading.Thread | None = None
+        #: Optional commands this model did not answer (e.g. in_sp_03 on a CORIO CD).
+        self.unsupported: set[str] = set()
+
+    # ------------------------------------------------------------ low level
+
+    def query(self, cmd: str, timeout: float | None = None) -> str:
+        with self.t.lock:
+            self.t.flush_input()  # the circulator never sends unsolicited data
+            reply = self.t.query(cmd, timeout).strip()
+        if not reply:
+            raise InstrumentProtocolError(f"Circulator sent an empty reply to {cmd!r}.")
+        return reply
+
+    def query_number(self, cmd: str) -> float:
+        reply = self.query(cmd)
+        if not _NUMBER_RE.match(reply):
+            if _STATUS_RE.match(reply) and any(c.isalpha() for c in reply):
+                st = parse_status(reply)
+                raise InstrumentProtocolError(f"Circulator replied {reply!r} to {cmd!r}: {st.meaning}.")
+            raise InstrumentProtocolError(f"Circulator replied {reply!r} to {cmd!r}; expected a number.")
+        return float(reply)
+
+    def optional_number(self, cmd: str) -> float | None:
+        """Query a command that not every model has; ``None`` if this circulator lacks it."""
+        if cmd in self.unsupported:
+            return None
+        try:
+            return self.query_number(cmd)
+        except (InstrumentTimeout, InstrumentProtocolError):
+            self.unsupported.add(cmd)
+        # Read (and so clear) the "-08 INVALID COMMAND" the device may now report.
+        with contextlib.suppress(InstrumentError):
+            self.status()
+        return None
+
+    def send(self, cmd: str) -> Status:
+        """Send an OUT command, then query ``status`` and raise if the command was rejected."""
+        with self.t.lock:
+            self.t.write(cmd)
+            if self.command_delay_s:
+                time.sleep(self.command_delay_s)
+            st = self.status()
+        if st.kind == "command_error":
+            raise InstrumentProtocolError(
+                f"Circulator rejected {cmd!r}: '{st.label}' ({st.meaning}). Nothing was changed."
+            )
+        return st
+
+    # ------------------------------------------------------------ identity / status
+
+    def version(self) -> str:
+        return self.query("version")
+
+    def status(self) -> Status:
+        return parse_status(self.query("status"))
+
+    def identify(self) -> dict[str, str]:
+        info = {"manufacturer": "JULABO"}
+        try:
+            info["version"] = self.version()
+        except InstrumentError as exc:
+            info["version"] = f"unknown ({exc})"
+        try:
+            st = self.status()
+            info["status"] = st.label
+        except InstrumentError:
+            pass
+        return info
+
+    def require_remote(self) -> Status:
+        st = self.status()
+        if st.kind == "state" and st.remote is False:
+            raise InstrumentProtocolError(
+                f"The circulator is in manual mode ('{st.label}'), so it ignores remote "
+                "commands. Enable remote control on the circulator first (CORIO: MENU > IntE > rEM > "
+                "USb or 232; MAGIO/DYNEO: Main menu > Connect unit > Remote control)."
+            )
+        return st
+
+    # ------------------------------------------------------------ readings
+
+    def bath_temperature_c(self) -> float:
+        """``in_pv_00``: actual (bath/internal) temperature."""
+        return self.query_number("in_pv_00")
+
+    def heating_power_pct(self) -> float:
+        """``in_pv_01``: current actuating variable in % (negative = cooling)."""
+        return self.query_number("in_pv_01")
+
+    def external_temperature_c(self) -> float:
+        """``in_pv_02``: external Pt100 sensor (MAGIO, DYNEO; not CORIO)."""
+        return self.query_number("in_pv_02")
+
+    def safety_sensor_temperature_c(self) -> float:
+        """``in_pv_03``: temperature of the high-temperature safety sensor."""
+        return self.query_number("in_pv_03")
+
+    def excess_temperature_protection_c(self) -> float:
+        """``in_pv_04``: current setting of the high-temperature safety function."""
+        return self.query_number("in_pv_04")
+
+    def setpoint_c(self) -> float:
+        return self.query_number("in_sp_00")
+
+    def warning_limits_c(self) -> tuple[float | None, float | None]:
+        """``in_sp_03`` / ``in_sp_04``: (high, low) temperature warning limits (not on CORIO CD)."""
+        return self.optional_number("in_sp_03"), self.optional_number("in_sp_04")
+
+    def is_running(self) -> bool:
+        """``in_mode_05``: 1 = temperature control started, 0 = stopped."""
+        value = self.query_number("in_mode_05")
+        if value not in (0, 1):
+            raise InstrumentProtocolError(f"Unexpected in_mode_05 value {value:g}; expected 0 or 1.")
+        return value == 1
+
+    # ------------------------------------------------------------ control
+
+    def set_setpoint(self, celsius: float) -> Status:
+        self.require_remote()
+        st = self.send(f"out_sp_00 {celsius:.2f}")
+        reported = self.setpoint_c()
+        if abs(reported - celsius) > 0.051:
+            raise InstrumentProtocolError(
+                f"Setpoint not accepted: circulator reports {reported:g} °C after 'out_sp_00 {celsius:.2f}'."
+            )
+        return st
+
+    def start(self) -> Status:
+        self.require_remote()
+        self.abort.clear()
+        st = self.send("out_mode_05 1")
+        if not self.is_running():
+            raise InstrumentProtocolError(
+                f"The circulator did not start (status '{st.label}': {st.meaning})."
+            )
+        return st
+
+    def stop(self) -> bool:
+        """Stop temperature control. Retries once; returns True if in_mode_05 confirms it."""
+        self.abort.set()
+        for _ in range(2):
+            try:
+                with self.t.lock:
+                    self.t.write("out_mode_05 0")
+                    if self.command_delay_s:
+                        time.sleep(self.command_delay_s)
+                    if not self.is_running():
+                        return True
+            except InstrumentError as exc:
+                log.warning("Stop attempt failed: %s", exc)
+        return False
+
+    # ------------------------------------------------------------ keep-alive (device watchdog)
+
+    def start_keepalive(self, interval_s: float) -> None:
+        """Query ``status`` every ``interval_s`` so a watchdog configured on the circulator
+        (MAGIO/DYNEO, restart mode "all valid commands") sees continuous traffic."""
+        self._keepalive_stop.clear()
+        self._keepalive_thread = threading.Thread(
+            target=self._keepalive, args=(interval_s,), name="julabo-keepalive", daemon=True
+        )
+        self._keepalive_thread.start()
+
+    def _keepalive(self, interval_s: float) -> None:
+        while not self._keepalive_stop.wait(interval_s):
+            try:
+                self.status()
+            except InstrumentError as exc:
+                log.warning("JULABO keep-alive query failed: %s", exc)
+
+    def close(self) -> None:
+        self._keepalive_stop.set()
+        if self._keepalive_thread is not None:
+            self._keepalive_thread.join(timeout=5)
+        self.t.close()