labmcp-sartorius 0.1.0__tar.gz

labmcp_sartorius-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_sartorius-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: labmcp-sartorius
+Version: 0.1.0
+Summary: MCP server for Sartorius laboratory balances (SBI protocol): weigh, tare, zero, log drift, internal adjustment.
+Project-URL: Homepage, https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/sartorius-balance
+Author: K-Dense and LabMCP contributors
+License-Expression: Apache-2.0
+Keywords: balance,lab-instrument,mcp,sartorius,sbi,weighing
+Requires-Python: >=3.10
+Requires-Dist: labmcp<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# Sartorius Balance — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-sartorius -->
+
+Let an AI agent weigh samples, tare containers, log drift and evaporation, and run internal adjustments on **Sartorius laboratory balances** through the documented **SBI** (Sartorius Balance Interface) ASCII protocol.
+
+| | |
+|---|---|
+| **Package** | `labmcp-sartorius` |
+| **Instruments** | Cubis MSE, Cubis II MCA, Secura, Quintix, Practum, Entris II; older CP/CPA-series balances with `--option legacy=true`. Other SBI balances are likely to work |
+| **Interfaces** | RS-232, USB (virtual COM port, "PC-SBI"), Ethernet (Cubis II "serial transmission via Ethernet", or any serial-to-Ethernet adapter) |
+| **Protocol** | SBI: [Entris II interface description](https://www.sartorius.hr/media/dypfvdsn/entris-ii-technical-note-en-sartorius.pdf) (technical note 10/2020), [Secura/Quintix/Practum user manual](https://api.sartorius.com/document-hub/dam/download/21625/Manual_Secura_Quintix_Practum_WSE6004-e181008.pdf) §10.3 (WSE6004), [Cubis MSE operating instructions](https://api.sartorius.com/document-hub/dam/download/20494/Manual_Cubis_MSE_WMS6004-e.pdf) (WMS6004), [Cubis MCA operating instructions](https://www.sartorius.com/download/920578/manual-cubis-mca-micro-balances-wmc6028-e-pdf-data.pdf) (WMC6028), [SBI interface description](https://api.sartorius.com/document-hub/dam/download/22650/MAN-CC_Interface-e.pdf) (98647-000-53) |
+| **Status** | 🧪 **simulated**: tested against a wire-level SBI 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-sartorius --simulate --check
+```
+
+## Connect your balance
+
+1. **Balance setup:** set the interface you use (RS232, USB-B / "PC-SBI", or Ethernet) to the **SBI** protocol, and set SBI data output to **manual, without stability** with **automatic output off** (factory settings on Cubis II and Entris II). With auto print on, `ESC P` toggles the automatic output instead of sending one reading. Either line format works (16 characters, or 22 with ID code).
+2. **Serial settings:** factory settings are **9600 baud, 8 data bits, odd parity, 1 stop bit**, hardware handshake (Cubis II/MSE, Secura/Quintix/Practum, Entris II). The server uses these but does not enforce RTS/CTS (it keeps RTS asserted, which lets the balance transmit; USB virtual COM ports often never assert CTS). Add `?rtscts=true` to enforce it, or e.g. `?bytesize=7&parity=E` if your balance is set differently.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-sartorius --address /dev/ttyUSB0 --check                 # Linux
+   uvx labmcp-sartorius --address /dev/tty.usbmodem14201 --check       # macOS
+   uvx labmcp-sartorius --address COM4 --check                         # Windows
+   uvx labmcp-sartorius --address tcp://192.168.1.61:49155 --check     # Cubis II via Ethernet (port as configured)
+   ```
+   `--check` prints the model, serial number and software version (`ESC x1_`, `x2_`, `x3_`) when the balance supports them.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add balance -- uvx labmcp-sartorius --address /dev/ttyUSB0
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "balance": {
+      "command": "uvx",
+      "args": ["labmcp-sartorius", "--address", "/dev/ttyUSB0"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow weighing but block taring, zeroing and adjustment. For other clients: `uvx labmcp config sartorius-balance --address /dev/ttyUSB0 --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. |
+| `lock_keypad` | 🎛 control | Block or unblock the balance keys, e.g. so nobody tares by accident during a long logging run. |
+| `log_weight_series` | 👁 read | Record a series of immediate (unfiltered) readings to monitor drift, evaporation, moisture uptake or stabilisation. Returns every reading plus summary statistics. |
+| `read_weight` | 👁 read | Read the current net weight from the balance (ESC P). With stable=True the server polls until the balance reports a stable value; if it cannot settle (draughts, vibration, evaporation) you get an error; retry, or use stable=false for the current value. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `run_internal_adjustment` | 🎛 control | Adjust (calibrate) the balance with its built-in weight (ESC Z; isoCAL models only). The pan must be empty and the balance undisturbed. SBI sends no completion message, so the server watches for the adjustment status and waits until the balance weighs again; check `observed_adjustment` and the balance display or GLP printout for the result. |
+| `set_ambient_conditions` | 🎛 control | Adapt the balance's filter to the ambient conditions (ESC K/L/M/N). Use 'unstable' or 'very_unstable' for draughty or vibrating benches (slower but steadier readings). |
+| `tare` | 🎛 control | Tare the balance (ESC U, or ESC T on legacy balances): the current load (e.g. an empty container) becomes the tare. Then waits for a stable reading and checks that it is ~0; returns that reading. |
+| `zero` | 🎛 control | Zero the balance (ESC V). Only works with the pan (nearly) empty, within the balance's zero-setting range; clears the tare. Confirms by reading ~0 afterwards. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_series_duration_s` | 600 s | Longest weight-logging series an agent may start |
+
+Override at launch: `--limit max_series_duration_s=3600`. No tool of this server moves anything or heats, so there are no hazard tools.
+
+## Example prompts
+
+- "Tare the balance, then tell me the weight once it's stable after I add the sample."
+- "Log the weight every 10 s for 5 minutes and tell me the evaporation rate in mg/min."
+- "Weigh out ~250 mg: tell me how much more to add, reading every few seconds, until I'm within ±2 mg."
+- "The bench is vibrating today; switch the balance filter to unstable conditions and lock the keypad."
+- "Run an internal adjustment before we start the calibration curve and tell me whether it ran."
+
+## Notes
+
+- **Stability comes from the unit symbol.** SBI has no explicit stability flag: the balance only sends the unit symbol (positions 12–14) when the reading is stable ("If the weighing system has not stabilized, no unit symbol is output", interface description 98647-000-53; the newer manuals list those positions as "unit symbol or space"). `read_weight(stable=true)` therefore polls `ESC P` until a reading with a unit arrives. Unstable readings report the last unit seen.
+- **Line formats.** The parser follows the documented fixed-width layouts: 16 characters (sign, value in positions 2–10, unit in 12–14, CR LF) and 22 characters (6-character ID code such as `N`, `G#`, `T`, `Stat`, then the same 16). It also accepts the Cubis II "one line with full length" format, a decimal comma, and a G#/T/N weighing block (the `N` line is reported). `High`, `Low`, `Err ###`, `APP.ERR`, `DIS.ERR` and `PRT.ERR` are reported as clear errors.
+- **No acknowledgements.** SBI control commands (`ESC U` tare, `ESC V` zero, `ESC Z` adjust, `ESC K`–`N` filter, `ESC O`/`R` keys) produce no reply, so a balance that does not support one silently ignores it. `tare` and `zero` therefore wait for a stable reading and check it is ~0, and report an error otherwise.
+- **Zero vs tare.** `ESC V` only zeroes within the balance's zero-setting range (nearly empty pan); `ESC U` tares any load. Older balances (CP/CPA, LE, ...) only have `ESC T` (the tare key): start the server with `--option legacy=true`.
+- **Internal adjustment (unverified).** `ESC Z` starts isoCAL on balances with a built-in weight. SBI sends no completion or result message; the server watches for the `Cal.` status (or a balance too busy to answer) and waits for a stable weight again, and reports `observed_adjustment=false` if it never sees one. Confirm the result on the display or GLP printout. The exact status output during adjustment could not be verified in the manuals.
+- **Identity replies (unverified format).** `ESC x1_`/`x2_`/`x3_` print the model, serial number and software version; their exact layout is not documented, so the text is passed through as sent.
+- The command log shows SBI traffic as hex (`1b 50 0d 0a` = `ESC P CR LF`) because of the ESC character.
+- Not implemented: draft-shield and ionizer commands (Cubis MSE only), external adjustment (`ESC W`, needs a reference weight), `ESC S` restart and the function-key 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_sartorius-0.1.0/README.md

@@ -0,0 +1,104 @@
+# Sartorius Balance — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-sartorius -->
+
+Let an AI agent weigh samples, tare containers, log drift and evaporation, and run internal adjustments on **Sartorius laboratory balances** through the documented **SBI** (Sartorius Balance Interface) ASCII protocol.
+
+| | |
+|---|---|
+| **Package** | `labmcp-sartorius` |
+| **Instruments** | Cubis MSE, Cubis II MCA, Secura, Quintix, Practum, Entris II; older CP/CPA-series balances with `--option legacy=true`. Other SBI balances are likely to work |
+| **Interfaces** | RS-232, USB (virtual COM port, "PC-SBI"), Ethernet (Cubis II "serial transmission via Ethernet", or any serial-to-Ethernet adapter) |
+| **Protocol** | SBI: [Entris II interface description](https://www.sartorius.hr/media/dypfvdsn/entris-ii-technical-note-en-sartorius.pdf) (technical note 10/2020), [Secura/Quintix/Practum user manual](https://api.sartorius.com/document-hub/dam/download/21625/Manual_Secura_Quintix_Practum_WSE6004-e181008.pdf) §10.3 (WSE6004), [Cubis MSE operating instructions](https://api.sartorius.com/document-hub/dam/download/20494/Manual_Cubis_MSE_WMS6004-e.pdf) (WMS6004), [Cubis MCA operating instructions](https://www.sartorius.com/download/920578/manual-cubis-mca-micro-balances-wmc6028-e-pdf-data.pdf) (WMC6028), [SBI interface description](https://api.sartorius.com/document-hub/dam/download/22650/MAN-CC_Interface-e.pdf) (98647-000-53) |
+| **Status** | 🧪 **simulated**: tested against a wire-level SBI 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-sartorius --simulate --check
+```
+
+## Connect your balance
+
+1. **Balance setup:** set the interface you use (RS232, USB-B / "PC-SBI", or Ethernet) to the **SBI** protocol, and set SBI data output to **manual, without stability** with **automatic output off** (factory settings on Cubis II and Entris II). With auto print on, `ESC P` toggles the automatic output instead of sending one reading. Either line format works (16 characters, or 22 with ID code).
+2. **Serial settings:** factory settings are **9600 baud, 8 data bits, odd parity, 1 stop bit**, hardware handshake (Cubis II/MSE, Secura/Quintix/Practum, Entris II). The server uses these but does not enforce RTS/CTS (it keeps RTS asserted, which lets the balance transmit; USB virtual COM ports often never assert CTS). Add `?rtscts=true` to enforce it, or e.g. `?bytesize=7&parity=E` if your balance is set differently.
+3. **Find the port:** `uvx labmcp ports`
+4. **Test the connection:**
+   ```bash
+   uvx labmcp-sartorius --address /dev/ttyUSB0 --check                 # Linux
+   uvx labmcp-sartorius --address /dev/tty.usbmodem14201 --check       # macOS
+   uvx labmcp-sartorius --address COM4 --check                         # Windows
+   uvx labmcp-sartorius --address tcp://192.168.1.61:49155 --check     # Cubis II via Ethernet (port as configured)
+   ```
+   `--check` prints the model, serial number and software version (`ESC x1_`, `x2_`, `x3_`) when the balance supports them.
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add balance -- uvx labmcp-sartorius --address /dev/ttyUSB0
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "balance": {
+      "command": "uvx",
+      "args": ["labmcp-sartorius", "--address", "/dev/ttyUSB0"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow weighing but block taring, zeroing and adjustment. For other clients: `uvx labmcp config sartorius-balance --address /dev/ttyUSB0 --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. |
+| `lock_keypad` | 🎛 control | Block or unblock the balance keys, e.g. so nobody tares by accident during a long logging run. |
+| `log_weight_series` | 👁 read | Record a series of immediate (unfiltered) readings to monitor drift, evaporation, moisture uptake or stabilisation. Returns every reading plus summary statistics. |
+| `read_weight` | 👁 read | Read the current net weight from the balance (ESC P). With stable=True the server polls until the balance reports a stable value; if it cannot settle (draughts, vibration, evaporation) you get an error; retry, or use stable=false for the current value. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `run_internal_adjustment` | 🎛 control | Adjust (calibrate) the balance with its built-in weight (ESC Z; isoCAL models only). The pan must be empty and the balance undisturbed. SBI sends no completion message, so the server watches for the adjustment status and waits until the balance weighs again; check `observed_adjustment` and the balance display or GLP printout for the result. |
+| `set_ambient_conditions` | 🎛 control | Adapt the balance's filter to the ambient conditions (ESC K/L/M/N). Use 'unstable' or 'very_unstable' for draughty or vibrating benches (slower but steadier readings). |
+| `tare` | 🎛 control | Tare the balance (ESC U, or ESC T on legacy balances): the current load (e.g. an empty container) becomes the tare. Then waits for a stable reading and checks that it is ~0; returns that reading. |
+| `zero` | 🎛 control | Zero the balance (ESC V). Only works with the pan (nearly) empty, within the balance's zero-setting range; clears the tare. Confirms by reading ~0 afterwards. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_series_duration_s` | 600 s | Longest weight-logging series an agent may start |
+
+Override at launch: `--limit max_series_duration_s=3600`. No tool of this server moves anything or heats, so there are no hazard tools.
+
+## Example prompts
+
+- "Tare the balance, then tell me the weight once it's stable after I add the sample."
+- "Log the weight every 10 s for 5 minutes and tell me the evaporation rate in mg/min."
+- "Weigh out ~250 mg: tell me how much more to add, reading every few seconds, until I'm within ±2 mg."
+- "The bench is vibrating today; switch the balance filter to unstable conditions and lock the keypad."
+- "Run an internal adjustment before we start the calibration curve and tell me whether it ran."
+
+## Notes
+
+- **Stability comes from the unit symbol.** SBI has no explicit stability flag: the balance only sends the unit symbol (positions 12–14) when the reading is stable ("If the weighing system has not stabilized, no unit symbol is output", interface description 98647-000-53; the newer manuals list those positions as "unit symbol or space"). `read_weight(stable=true)` therefore polls `ESC P` until a reading with a unit arrives. Unstable readings report the last unit seen.
+- **Line formats.** The parser follows the documented fixed-width layouts: 16 characters (sign, value in positions 2–10, unit in 12–14, CR LF) and 22 characters (6-character ID code such as `N`, `G#`, `T`, `Stat`, then the same 16). It also accepts the Cubis II "one line with full length" format, a decimal comma, and a G#/T/N weighing block (the `N` line is reported). `High`, `Low`, `Err ###`, `APP.ERR`, `DIS.ERR` and `PRT.ERR` are reported as clear errors.
+- **No acknowledgements.** SBI control commands (`ESC U` tare, `ESC V` zero, `ESC Z` adjust, `ESC K`–`N` filter, `ESC O`/`R` keys) produce no reply, so a balance that does not support one silently ignores it. `tare` and `zero` therefore wait for a stable reading and check it is ~0, and report an error otherwise.
+- **Zero vs tare.** `ESC V` only zeroes within the balance's zero-setting range (nearly empty pan); `ESC U` tares any load. Older balances (CP/CPA, LE, ...) only have `ESC T` (the tare key): start the server with `--option legacy=true`.
+- **Internal adjustment (unverified).** `ESC Z` starts isoCAL on balances with a built-in weight. SBI sends no completion or result message; the server watches for the `Cal.` status (or a balance too busy to answer) and waits for a stable weight again, and reports `observed_adjustment=false` if it never sees one. Confirm the result on the display or GLP printout. The exact status output during adjustment could not be verified in the manuals.
+- **Identity replies (unverified format).** `ESC x1_`/`x2_`/`x3_` print the model, serial number and software version; their exact layout is not documented, so the text is passed through as sent.
+- The command log shows SBI traffic as hex (`1b 50 0d 0a` = `ESC P CR LF`) because of the ESC character.
+- Not implemented: draft-shield and ionizer commands (Cubis MSE only), external adjustment (`ESC W`, needs a reference weight), `ESC S` restart and the function-key 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_sartorius-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "labmcp-sartorius"
+version = "0.1.0"
+description = "MCP server for Sartorius laboratory balances (SBI protocol): weigh, tare, zero, log drift, internal adjustment."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "K-Dense and LabMCP contributors" }]
+keywords = ["mcp", "lab-instrument", "balance", "sartorius", "sbi", "weighing"]
+dependencies = ["labmcp>=0.1,<0.2"]
+
+[project.scripts]
+labmcp-sartorius = "labmcp_sartorius.server:main"
+
+[project.urls]
+Homepage = "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/sartorius-balance"
+
+[tool.labmcp]
+name = "Sartorius Balance"
+domain = "chemistry"
+category = "Weighing"
+vendor = "Sartorius"
+models = ["Cubis MSE", "Cubis II MCA", "Secura", "Quintix", "Practum", "Entris II", "CP/CPA (legacy)"]
+interfaces = ["RS-232", "USB (virtual COM)", "Ethernet (Cubis II)"]
+protocol = "SBI (Sartorius Balance Interface)"
+summary = "Weigh (stable/immediate), tare, zero, log drift series, internal adjustment, ambient filter, keypad lock."
+status = "simulated"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labmcp_sartorius"]

labmcp_sartorius-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-sartorius",
+  "title": "Sartorius Balance",
+  "description": "MCP server for Sartorius laboratory balances (SBI protocol): weigh, tare, zero, log drift, internal ",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/K-Dense-AI/lab-instrument-mcps",
+    "source": "github",
+    "subfolder": "servers/chemistry/sartorius-balance"
+  },
+  "websiteUrl": "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/sartorius-balance",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "labmcp-sartorius",
+      "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_sartorius-0.1.0/src/labmcp_sartorius/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for Sartorius laboratory balances (SBI protocol)."""

labmcp_sartorius-0.1.0/src/labmcp_sartorius/driver.py

@@ -0,0 +1,241 @@
+"""SBI (Sartorius Balance Interface) driver for Sartorius laboratory balances.
+
+Commands, data formats and interface settings were verified in:
+
+* "Entris II - Description of the Interface", Sartorius Technical Note (10/2020),
+  https://www.sartorius.hr/media/dypfvdsn/entris-ii-technical-note-en-sartorius.pdf
+* "User Manual Secura, Quintix, Practum" (WSE6004-e181008), chapter 10.3 "Interface Specification",
+  https://api.sartorius.com/document-hub/dam/download/21625/Manual_Secura_Quintix_Practum_WSE6004-e181008.pdf
+* "Operating Instructions Cubis Series MSE" (WMS6004-e190715), "Data Interfaces",
+  https://api.sartorius.com/document-hub/dam/download/20494/Manual_Cubis_MSE_WMS6004-e.pdf
+* "Operating Instructions Cubis MCA" (WMC6028-e211007), "Connections / SBI Protocol" menu,
+  https://www.sartorius.com/download/920578/manual-cubis-mca-micro-balances-wmc6028-e-pdf-data.pdf
+* "Sartorius Comparator Interface Description for the CC Model Series" (98647-000-53),
+  https://api.sartorius.com/document-hub/dam/download/22650/MAN-CC_Interface-e.pdf
+  (source of the rule "If the weighing system has not stabilized, no unit symbol is output")
+
+Commands are ``ESC <char> [CR LF]`` (format 1, e.g. ``ESC P``) or ``ESC <char><digit>_ [CR LF]``
+(format 2, e.g. ``ESC x1_``). Only ``ESC P`` (print) and the ``ESC x#_`` info commands produce
+output; the others (tare, zero, adjustment, filter, key lock) are silent.
+
+A weight line is 16 characters (14 + CR LF)::
+
+    pos 1      sign (+, - or space)
+    pos 2-10   value, right-aligned, leading zeros as spaces
+    pos 11     space
+    pos 12-14  unit symbol, or spaces while the reading is not stable
+    pos 15-16  CR LF
+
+or 22 characters, where a 6-character ID code (``N``, ``G#``, ``T``, ``Stat``...) precedes
+the same 16 characters. Special lines report ``High`` (overload), ``Low`` (underload),
+``Cal.Ext.``/``Cal.Int.`` (adjustment) and errors ``Err ###``, ``APP.ERR``, ``DIS.ERR``,
+``PRT.ERR``.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+
+from labmcp import InstrumentProtocolError, InstrumentTimeout, Transport
+
+ESC = "\x1b"
+
+AMBIENT_FILTERS = {"very_stable": "K", "stable": "L", "unstable": "M", "very_unstable": "N"}
+
+_VALUE_RE = re.compile(r"^[+-]?(?:\d+(?:[.,]\d*)?|[.,]\d+)$")
+# Position-independent fallback, e.g. for "output in one line with full length" (Cubis II).
+_LOOSE_RE = re.compile(
+    r"^(?P<id>.*?)\s*(?P<sign>[+-])?\s*(?P<value>\d+(?:[.,]\d*)?|[.,]\d+)\s*(?P<unit>[^\s\d.,+\-]\S{0,3})?\s*$"
+)
+_ERR_RE = re.compile(r"\bErr\s*(\d+)", re.IGNORECASE)
+_APP_ERR_RE = re.compile(r"\b(APP|DIS|PRT)\.ERR", re.IGNORECASE)
+
+_SPECIAL = {
+    "High": "the balance is overloaded (High): remove weight from the pan",
+    "Low": "the balance is in underload (Low): is the weighing pan in place and free?",
+}
+_APP_ERR = {"APP": "application error", "DIS": "display error", "PRT": "printer/output error"}
+
+
+@dataclass
+class SBIReading:
+    value: float
+    unit: str | None  # None when the balance sent no unit (it omits it while unstable)
+    stable: bool
+    ident: str  # 6-character ID code of the 22-character format ("" for 16 characters)
+    decimals: int
+    raw: str
+
+
+class BalanceBusy(InstrumentProtocolError):
+    """The balance sent an adjustment status line (``Cal.Int.`` / ``Cal.Ext.``) instead of a weight."""
+
+
+def parse_sbi_line(line: str) -> SBIReading:
+    """Parse one SBI data line (without CR LF) into a reading, or raise a helpful error."""
+    raw = line.rstrip("\r\n")
+    if not raw.strip():
+        raise InstrumentProtocolError("The balance sent an empty line.")
+    for word, meaning in _SPECIAL.items():
+        if re.search(rf"\b{word}\b", raw):
+            raise InstrumentProtocolError(f"Balance sent {raw.strip()!r}: {meaning}.")
+    if m := _ERR_RE.search(raw):
+        raise InstrumentProtocolError(
+            f"Balance sent {raw.strip()!r}: error {m.group(1)}; see the troubleshooting table in the "
+            "balance's operating instructions."
+        )
+    if m := _APP_ERR_RE.search(raw):
+        raise InstrumentProtocolError(f"Balance sent {raw.strip()!r}: {_APP_ERR[m.group(1).upper()]}.")
+    if "Cal." in raw:
+        raise BalanceBusy(f"Balance sent {raw.strip()!r}: an adjustment/calibration is in progress.")
+
+    if len(raw) in (14, 20):  # the documented fixed-width 16- and 22-character formats
+        ident, body = (raw[:6].strip(), raw[6:]) if len(raw) == 20 else ("", raw)
+        sign, number, gap, unit = body[0], body[1:10].replace(" ", ""), body[10], body[11:14].strip()
+        if sign in "+- " and gap == " " and _VALUE_RE.match(number):
+            return _reading(sign, number, unit, ident, raw)
+    m = _LOOSE_RE.match(raw)
+    if not m or m["id"].strip().startswith("Stat"):
+        raise InstrumentProtocolError(f"Unexpected SBI data from the balance: {raw!r}")
+    return _reading(m["sign"] or "+", m["value"], (m["unit"] or "").strip(), m["id"].strip(), raw)
+
+
+def _reading(sign: str, number: str, unit: str, ident: str, raw: str) -> SBIReading:
+    number = number.replace(",", ".")
+    value = float(number)
+    if sign == "-" and not number.startswith("-"):
+        value = -value
+    decimals = len(number.split(".")[1]) if "." in number else 0
+    return SBIReading(value, unit or None, bool(unit), ident, decimals, raw)
+
+
+class SBIBalance:
+    def __init__(self, transport: Transport, legacy: bool = False) -> None:
+        self.t = transport
+        #: Older balances (CP/CPA, LE...) only know ESC T for taring and have no ESC U / ESC V.
+        self.legacy = legacy
+        #: Last unit symbol seen (the balance omits it in unstable readings).
+        self.last_unit: str | None = None
+
+    # ------------------------------------------------------------ low level
+
+    def send(self, command: str) -> None:
+        """Send ``ESC <command> CR LF``. SBI control commands have no reply."""
+        self.t.write(ESC + command)
+
+    def _lines(self, command: str, timeout: float | None = None) -> list[str]:
+        """Send a command and collect its output: one line, plus up to 5 more that follow within
+        0.15 s of each other (e.g. the date/time line or a G#/T/N weighing block)."""
+        with self.t.lock:
+            self.t.flush_input()
+            self.send(command)
+            try:
+                lines = [self.t.read(timeout)]
+            except InstrumentTimeout as exc:
+                raise InstrumentTimeout(
+                    f"No reply to ESC {command}. Check that the balance's interface is set to SBI with "
+                    "matching baud rate/parity, and that data output is 'manual without stability' "
+                    f"(with 'after stability' the balance waits until the reading settles). ({exc})"
+                ) from exc
+            for _ in range(5):  # bounded, in case the balance is streaming (auto print on)
+                try:
+                    lines.append(self.t.read(0.15))
+                except InstrumentTimeout:
+                    break
+            return lines
+
+    # ------------------------------------------------------------ identity
+
+    def info(self, number: int) -> str | None:
+        """``ESC x#_``: 1 = model, 2 = serial number, 3 = balance software version."""
+        try:
+            lines = self._lines(f"x{number}_", timeout=1.5)
+        except InstrumentTimeout:
+            return None
+        return " ".join(line.strip() for line in lines if line.strip()) or None
+
+    def identify(self) -> dict[str, str]:
+        info = {"manufacturer": "Sartorius", "protocol": "SBI"}
+        for key, number in (("model", 1), ("serial", 2), ("software", 3)):
+            value = self.info(number)
+            if value:
+                info[key] = value
+        return info
+
+    # ------------------------------------------------------------ weighing
+
+    def print_reading(self, timeout: float | None = None) -> SBIReading:
+        """``ESC P``: one reading, stable or not (as configured, 'without stability')."""
+        lines = [line for line in self._lines("P", timeout) if line.strip()]
+        if not lines:
+            raise InstrumentProtocolError("The balance answered ESC P with an empty line.")
+        readings = [parse_sbi_line(line) for line in lines if not _is_info_line(line)]
+        if not readings:
+            raise InstrumentProtocolError(f"No weight value in the balance's output: {lines!r}")
+        # A G#/T/N weighing block: report the net value.
+        reading = next((r for r in readings if r.ident == "N"), readings[-1])
+        if reading.unit:
+            self.last_unit = reading.unit
+        return reading
+
+    def weight(self, stable: bool = True, timeout: float = 20.0) -> SBIReading:
+        """Read the weight. With ``stable=True``, poll ``ESC P`` until the balance reports a
+        stable value (unit symbol present) or ``timeout`` expires."""
+        if not stable:
+            return self.print_reading()
+        deadline = time.monotonic() + timeout
+        last: SBIReading | None = None
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            try:
+                last = self.print_reading(timeout=max(0.5, remaining))
+            except BalanceBusy:
+                last = None
+            else:
+                if last.stable:
+                    return last
+            time.sleep(min(0.2, max(0.0, deadline - time.monotonic())))
+        where = f" (last reading {last.value:g}, unstable)" if last else ""
+        raise InstrumentProtocolError(
+            f"The balance did not report a stable reading within {timeout:g} s{where}. Check for "
+            "draughts, vibration or a sample that is evaporating, or read with stable=false."
+        )
+
+    def tare(self) -> None:
+        """``ESC U`` (tare key); ``ESC T`` on legacy balances."""
+        self.send("T" if self.legacy else "U")
+
+    def zero(self) -> None:
+        """``ESC V`` (zero key). Not available on legacy balances."""
+        if self.legacy:
+            raise InstrumentProtocolError(
+                "Legacy SBI balances have no separate zero command; use tare (ESC T), which zeroes "
+                "when the pan is empty."
+            )
+        self.send("V")
+
+    def start_internal_adjustment(self) -> None:
+        """``ESC Z``: internal calibration/adjustment (balances with a built-in weight only)."""
+        self.send("Z")
+
+    def set_ambient_filter(self, level: str) -> None:
+        """``ESC K/L/M/N``: adapt the filter to very stable ... very unstable conditions."""
+        self.send(AMBIENT_FILTERS[level])
+
+    def lock_keys(self, locked: bool) -> None:
+        """``ESC O`` blocks the keypad, ``ESC R`` unblocks it."""
+        self.send("O" if locked else "R")
+
+    def close(self) -> None:
+        self.t.close()
+
+
+def _is_info_line(line: str) -> bool:
+    """Date/time lines of the 'date & time, value' output format."""
+    return bool(re.search(r"\d{1,2}[./-]\d{1,2}[./-]\d{2,4}|\d{1,2}:\d{2}", line)) and not re.search(
+        r"\s(?:g|mg|kg|ct|lb|oz|ozt)\s*$", line
+    )

labmcp_sartorius-0.1.0/src/labmcp_sartorius/server.py

@@ -0,0 +1,293 @@
+"""MCP server for Sartorius laboratory balances (SBI protocol)."""
+
+from __future__ import annotations
+
+import statistics
+import time
+from datetime import datetime, timezone
+from typing import Annotated, Literal
+
+from labmcp import (
+    CONTROL,
+    READ,
+    ConnectContext,
+    InstrumentProtocolError,
+    InstrumentServer,
+    InstrumentTimeout,
+    Limit,
+)
+from pydantic import BaseModel, Field
+
+from labmcp_sartorius.driver import BalanceBusy, SBIBalance, SBIReading
+from labmcp_sartorius.simulator import SBISimulator
+
+#: Seconds between status polls while an internal adjustment runs.
+ADJUST_POLL_S = 1.0
+#: If no adjustment status is seen within this time, assume the balance did not start one.
+ADJUST_NO_SIGN_S = 15.0
+
+
+def connect(ctx: ConnectContext) -> SBIBalance:
+    # Factory settings of Cubis II/MSE, Secura/Quintix/Practum and Entris II: 9600 baud,
+    # 8 data bits, odd parity, 1 stop bit; commands and replies end with CR LF.
+    # The balances default to hardware handshake on RS-232; rtscts stays off by default
+    # because pyserial keeps RTS asserted (all the balance needs to transmit) and USB
+    # virtual COM ports may never raise CTS.
+    transport = ctx.open_transport(
+        simulator=SBISimulator,
+        baudrate=9600,
+        bytesize=8,
+        parity="O",
+        stopbits=1,
+        rtscts=False,
+        read_termination="\r\n",
+        write_termination="\r\n",
+        timeout=3.0,
+    )
+    legacy = (ctx.option("legacy", "false") or "false").lower() in {"1", "true", "yes", "on"}
+    return SBIBalance(transport, legacy=legacy)
+
+
+server = InstrumentServer(
+    "Sartorius Balance (SBI)",
+    connect=connect,
+    package="labmcp-sartorius",
+    instructions="""
+Controls a Sartorius laboratory balance over SBI (Cubis MSE / Cubis II MCA, Secura, Quintix,
+Practum, Entris II; older CP/CPA with --option legacy=true).
+- `read_weight` with stable=True polls until the balance reports a stable value (SBI marks a
+  stable reading by sending its unit symbol); stable=False returns the current value at once.
+- Weights are net weights (gross minus tare) in the unit shown on the balance.
+- Tare before weighing into a container; `zero` only works when the load is within the balance's
+  zero-setting range (near empty pan).
+- SBI commands are not acknowledged: `tare` and `zero` confirm by reading the balance afterwards.
+- Internal adjustment only exists on balances with a built-in weight, and SBI does not report
+  success; check the returned message.
+""",
+    limits=[
+        Limit("max_series_duration_s", 600, "s", "Longest allowed weight-logging series"),
+    ],
+    address_help="""\
+  serial:///dev/ttyUSB0            RS-232 or USB virtual COM (defaults 9600 baud, 8 data bits, odd parity)
+  serial://COM4?parity=N&bytesize=8  Windows, balance set to no parity
+  tcp://192.168.1.61:49155         Cubis II "Serial transmission via Ethernet" (port as configured)""",
+    option_help={
+        "legacy": "true for older balances (CP/CPA, LE...) that only have ESC T for tare/zero",
+    },
+)
+mcp = server.mcp
+
+
+class WeightReading(BaseModel):
+    value: float = Field(description="Net weight value")
+    unit: str | None = Field(
+        description="Unit sent by the balance (e.g. 'g'). SBI omits it for unstable readings; then this "
+        "is the last unit seen, or None"
+    )
+    stable: bool = Field(description="True if the balance marked the reading as stable")
+    id_code: str = Field(description="SBI 22-character-format ID code (e.g. 'N' = net); '' in 16-character format")
+    timestamp: str = Field(description="UTC time the reading was taken (ISO 8601)")
+
+
+class WeightSeries(BaseModel):
+    readings: list[WeightReading]
+    unit: str | None
+    count: int
+    mean: float
+    stdev: float
+    minimum: float
+    maximum: float
+    drift_per_min: float = Field(description="Least-squares slope of weight vs time, in unit/min")
+
+
+class AdjustmentResult(BaseModel):
+    observed_adjustment: bool = Field(
+        description="True if the balance reported an adjustment in progress (Cal.* status or busy)"
+    )
+    duration_s: float
+    final_reading: WeightReading | None
+    message: str
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+def _reading(r: SBIReading, last_unit: str | None) -> WeightReading:
+    return WeightReading(
+        value=r.value, unit=r.unit or last_unit, stable=r.stable, id_code=r.ident, timestamp=_now()
+    )
+
+
+def _drv() -> SBIBalance:
+    return server.driver
+
+
+def _settled_near_zero(what: str, timeout_s: float) -> WeightReading:
+    """After an (unacknowledged) tare/zero command, wait for a stable reading of ~0."""
+    drv = _drv()
+    deadline = time.monotonic() + timeout_s
+    while True:
+        # The first stable reading may still be the one from before the command was processed.
+        r = drv.weight(stable=True, timeout=max(1.0, deadline - time.monotonic()))
+        if abs(r.value) <= 5 * 10 ** (-r.decimals):  # within 5 digits of zero
+            return _reading(r, drv.last_unit)
+        if time.monotonic() >= deadline:
+            break
+        time.sleep(0.3)
+    hint = (
+        "Older balances (CP/CPA, LE, ...) only understand ESC T: start the server with --option legacy=true."
+        if not drv.legacy
+        else "The balance may not have accepted the command."
+    )
+    zero_hint = (
+        "For zero, the load must be within the zero-setting range (near an empty pan); use tare instead. "
+        if what == "zero"
+        else ""
+    )
+    raise InstrumentProtocolError(
+        f"Sent the {what} command but the balance still reads {r.value:g} {r.unit or ''} (stable). "
+        + zero_hint
+        + hint
+    )
+
+
+@mcp.tool(**READ, timeout=90)
+def read_weight(
+    stable: Annotated[bool, Field(description="Wait for a stable reading (recommended)")] = True,
+    timeout_s: Annotated[float, Field(ge=1, le=60, description="Max. seconds to wait for stability")] = 20,
+) -> WeightReading:
+    """Read the current net weight from the balance (ESC P). With stable=True the server polls
+    until the balance reports a stable value; if it cannot settle (draughts, vibration,
+    evaporation) you get an error; retry, or use stable=false for the current value."""
+    drv = _drv()
+    r = drv.weight(stable=stable, timeout=timeout_s)
+    return _reading(r, drv.last_unit)
+
+
+@mcp.tool(**READ, timeout=900)
+def log_weight_series(
+    count: Annotated[int, Field(ge=2, le=1000, description="Number of readings")] = 10,
+    interval_s: Annotated[float, Field(ge=0.5, le=600, description="Seconds between readings")] = 1.0,
+) -> WeightSeries:
+    """Record a series of immediate (unfiltered) readings to monitor drift, evaporation,
+    moisture uptake or stabilisation. Returns every reading plus summary statistics."""
+    server.check("max_series_duration_s", (count - 1) * interval_s, "series duration")
+    drv = _drv()
+    readings: list[WeightReading] = []
+    times: list[float] = []
+    t0 = time.monotonic()
+    for i in range(count):
+        delay = t0 + i * interval_s - time.monotonic()
+        if delay > 0:
+            time.sleep(delay)
+        times.append(time.monotonic() - t0)
+        readings.append(_reading(drv.weight(stable=False), drv.last_unit))
+    values = [r.value for r in readings]
+    tbar, vbar = statistics.fmean(times), statistics.fmean(values)
+    denom = sum((t - tbar) ** 2 for t in times)
+    slope = sum((t - tbar) * (v - vbar) for t, v in zip(times, values, strict=True)) / denom if denom else 0.0
+    return WeightSeries(
+        readings=readings,
+        unit=drv.last_unit,
+        count=count,
+        mean=vbar,
+        stdev=statistics.stdev(values),
+        minimum=min(values),
+        maximum=max(values),
+        drift_per_min=slope * 60.0,
+    )
+
+
+@mcp.tool(**CONTROL, timeout=90)
+def tare(
+    timeout_s: Annotated[float, Field(ge=1, le=60, description="Max. seconds to wait for the tared reading")] = 10,
+) -> WeightReading:
+    """Tare the balance (ESC U, or ESC T on legacy balances): the current load (e.g. an empty
+    container) becomes the tare. Then waits for a stable reading and checks that it is ~0;
+    returns that reading."""
+    _drv().tare()
+    return _settled_near_zero("tare", timeout_s)
+
+
+@mcp.tool(**CONTROL, timeout=90)
+def zero(
+    timeout_s: Annotated[float, Field(ge=1, le=60, description="Max. seconds to wait for the zeroed reading")] = 10,
+) -> WeightReading:
+    """Zero the balance (ESC V). Only works with the pan (nearly) empty, within the balance's
+    zero-setting range; clears the tare. Confirms by reading ~0 afterwards."""
+    _drv().zero()
+    return _settled_near_zero("zero", timeout_s)
+
+
+@mcp.tool(**CONTROL, timeout=330)
+def run_internal_adjustment(
+    timeout_s: Annotated[float, Field(ge=30, le=300, description="Max. seconds for the adjustment")] = 240,
+) -> AdjustmentResult:
+    """Adjust (calibrate) the balance with its built-in weight (ESC Z; isoCAL models only).
+    The pan must be empty and the balance undisturbed. SBI sends no completion message, so the
+    server watches for the adjustment status and waits until the balance weighs again; check
+    `observed_adjustment` and the balance display or GLP printout for the result."""
+    drv = _drv()
+    drv.start_internal_adjustment()
+    t0 = time.monotonic()
+    busy_seen = False
+    final: SBIReading | None = None
+    while time.monotonic() - t0 < timeout_s:
+        time.sleep(ADJUST_POLL_S)
+        try:
+            r = drv.print_reading(timeout=2.0)
+        except (BalanceBusy, InstrumentTimeout):  # "Cal.Int." status, or too busy to answer
+            busy_seen = True
+            continue
+        if busy_seen and r.stable:
+            final = r
+            break
+        if not busy_seen and time.monotonic() - t0 > ADJUST_NO_SIGN_S:
+            final = r
+            break
+    elapsed = time.monotonic() - t0
+    if busy_seen and final is not None:
+        message = f"The balance reported an adjustment and returned to weighing after {elapsed:.0f} s."
+    elif busy_seen:
+        message = f"The balance was still adjusting after {timeout_s:g} s; check its display."
+    else:
+        message = (
+            f"No sign of an adjustment was seen within {ADJUST_NO_SIGN_S:g} s: the balance may have no "
+            "internal weight, "
+            "adjustment may be disabled or locked in its menu (verified models), or it adjusts without "
+            "reporting a status over SBI. Check the display."
+        )
+    return AdjustmentResult(
+        observed_adjustment=busy_seen,
+        duration_s=round(elapsed, 1),
+        final_reading=_reading(final, drv.last_unit) if final else None,
+        message=message,
+    )
+
+
+@mcp.tool(**CONTROL)
+def set_ambient_conditions(
+    conditions: Literal["very_stable", "stable", "unstable", "very_unstable"],
+) -> str:
+    """Adapt the balance's filter to the ambient conditions (ESC K/L/M/N). Use 'unstable' or
+    'very_unstable' for draughty or vibrating benches (slower but steadier readings)."""
+    _drv().set_ambient_filter(conditions)
+    return f"Ambient filter set to '{conditions}'."
+
+
+@mcp.tool(**CONTROL)
+def lock_keypad(
+    locked: Annotated[bool, Field(description="True blocks the balance keys (ESC O), False unblocks (ESC R)")],
+) -> str:
+    """Block or unblock the balance keys, e.g. so nobody tares by accident during a long logging run."""
+    _drv().lock_keys(locked)
+    return "Keypad locked." if locked else "Keypad unlocked."
+
+
+def main() -> None:
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

labmcp_sartorius-0.1.0/src/labmcp_sartorius/simulator.py

@@ -0,0 +1,127 @@
+"""Wire-level SBI simulator of a Sartorius analytical balance (220 g x 0.1 mg, internal weight).
+
+``ESC P`` returns a 22-character line (``fmt=22``: 6-character ID code + 16 characters) or a
+16-character line (``fmt=16``), laid out exactly as in the interface descriptions. While
+the reading is settling (after a load change, tare or zero) the unit symbol is replaced by
+spaces, as real balances do. Control commands are silent; unknown commands are ignored.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+
+from labmcp import LineSimulator
+
+CAPACITY_G = 220.0
+SETTLE_S = 1.5
+ADJUST_S = 8.0
+
+
+class SBISimulator(LineSimulator):
+    def __init__(
+        self,
+        load_g: float = 52.18734,
+        fmt: int = 22,
+        seed: int | None = 0,
+        time_scale: float = 1.0,
+        clock: Callable[[], float] = time.monotonic,
+        internal_weight: bool = True,
+        adjust_s: float = ADJUST_S,
+    ) -> None:
+        self.rng = random.Random(seed)
+        self.fmt = fmt
+        self.time_scale = time_scale
+        self.clock = clock
+        self._t0 = clock()
+        self.load_g = load_g  # what is physically on the pan
+        self.zero_g = 0.0
+        self.tare_g = 0.0
+        self.internal_weight = internal_weight
+        self.adjust_s = adjust_s
+        self.keys_locked = False
+        self.ambient = "L"
+        self._settled_at = 0.0
+        self._adjusting_until = -1.0
+        self.adjustments = 0
+
+    # helpers ---------------------------------------------------------------
+
+    def now(self) -> float:
+        return (self.clock() - self._t0) * self.time_scale
+
+    def place(self, load_g: float) -> None:
+        """Put a load on the pan (test/demo helper): the reading settles over ~1.5 s."""
+        self.load_g = load_g
+        self._settled_at = self.now() + SETTLE_S
+
+    def _net(self) -> float:
+        return self.load_g - self.zero_g - self.tare_g
+
+    def _line(self, body: str, ident: str = "N") -> str:
+        return f"{ident:<6}{body}" if self.fmt == 22 else body
+
+    def _weight_line(self) -> str:
+        stable = self.now() >= self._settled_at
+        value = self._net()
+        if stable:
+            value += self.rng.gauss(0, 0.00003)
+        else:  # settling: noisy, drifting towards the final value
+            value += (self._settled_at - self.now()) * 0.002 + self.rng.gauss(0, 0.0003)
+        value = round(value, 4)
+        sign = "-" if value < 0 else "+"
+        unit = "g" if stable else ""
+        return self._line(f"{sign} {abs(value):>8.4f} {unit:<3}")
+
+    def _special(self, text: str, position: int) -> str:
+        # Special codes start at a fixed position of the 16-character block; the
+        # 22-character format prefixes the ID code "Stat".
+        return self._line((" " * (position - 1) + text).ljust(14), ident="Stat")
+
+    # protocol --------------------------------------------------------------
+
+    def handle(self, command: str) -> str | list[str] | None:
+        if not command.startswith("\x1b"):
+            return None
+        cmd = command[1:]
+        adjusting = self.now() < self._adjusting_until
+        match cmd:
+            case "P" | "kP_":
+                if adjusting:
+                    return self._special("Cal.Int.", 4)
+                if self.load_g - self.zero_g > CAPACITY_G * 1.02:
+                    return self._special("High", 7)
+                if self.load_g - self.zero_g < -CAPACITY_G * 0.02:
+                    return self._special("Low", 7)
+                return self._weight_line()
+            case "T":  # tare or zero: zeroes within the zero range, tares otherwise
+                if abs(self.load_g - self.zero_g) <= CAPACITY_G * 0.02:
+                    self.zero_g, self.tare_g = self.load_g, 0.0
+                else:
+                    self.tare_g = self.load_g - self.zero_g
+                self._settled_at = self.now() + 0.5
+            case "U":
+                self.tare_g = self.load_g - self.zero_g
+                self._settled_at = self.now() + 0.5
+            case "V":  # zero key: only within the zero-setting range (here +-2 % of capacity)
+                if abs(self.load_g - self.zero_g) <= CAPACITY_G * 0.02:
+                    self.zero_g, self.tare_g = self.load_g, 0.0
+                    self._settled_at = self.now() + 0.5
+            case "Z":
+                if self.internal_weight:
+                    self._adjusting_until = self.now() + self.adjust_s
+                    self.adjustments += 1
+            case "K" | "L" | "M" | "N":
+                self.ambient = cmd
+            case "O":
+                self.keys_locked = True
+            case "R":
+                self.keys_locked = False
+            case "x1_":
+                return "QUINTIX224-1S"
+            case "x2_":
+                return "0037402012"
+            case "x3_":
+                return "00-20-12.01"
+        return None

labmcp_sartorius-0.1.0/tests/test_server.py

@@ -0,0 +1,242 @@
+import labmcp_sartorius.server as server_module
+import pytest
+from labmcp import InstrumentProtocolError, InstrumentTimeout, SafetyLimitError, SimulatedTransport
+from labmcp.testing import simulated_client, tool_names
+from labmcp_sartorius.driver import BalanceBusy, SBIBalance, parse_sbi_line
+from labmcp_sartorius.server import server
+from labmcp_sartorius.simulator import SBISimulator
+
+
+@pytest.fixture(autouse=True)
+def _default_options():
+    server.configure(options={})  # --option values persist between configure() calls
+    yield
+    server.configure(options={})
+
+
+class RecordingSimulator(SBISimulator):
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.received: list[str] = []
+
+    def handle(self, command: str):
+        self.received.append(command)
+        return super().handle(command)
+
+
+def make_driver(legacy: bool = False, **kwargs) -> tuple[SBIBalance, RecordingSimulator]:
+    kwargs.setdefault("time_scale", 10.0)  # settle in 0.15 s instead of 1.5 s
+    sim = RecordingSimulator(**kwargs)
+    t = SimulatedTransport(sim, read_termination="\r\n", write_termination="\r\n")
+    return SBIBalance(t, legacy=legacy), sim
+
+
+# ---------------------------------------------------------------- SBI line parsing
+
+
+@pytest.mark.parametrize(
+    "line, value, unit, stable, ident",
+    [
+        ("+   123.56 g  ", 123.56, "g", True, ""),  # 16 characters, stable
+        ("+   123.56    ", 123.56, None, False, ""),  # no unit symbol = not stable
+        ("-   0.0012 g  ", -0.0012, "g", True, ""),
+        ("   111.255 g  ", 111.255, "g", True, ""),  # position 1 blank = positive
+        ("N     +   123.56 g  ", 123.56, "g", True, "N"),  # 22 characters with ID code
+        ("G#    +  52.1873 mg ", 52.1873, "mg", True, "G#"),
+        ("Qnt   +      253 pcs", 253, "pcs", True, "Qnt"),
+        ("N + 123.56 g", 123.56, "g", True, "N"),  # Cubis II "one line with full length"
+        ("+   123,56 g  ", 123.56, "g", True, ""),  # decimal comma
+    ],
+)
+def test_parse_weight_lines(line, value, unit, stable, ident):
+    r = parse_sbi_line(line)
+    assert (r.value, r.unit, r.stable, r.ident) == (pytest.approx(value), unit, stable, ident)
+
+
+@pytest.mark.parametrize(
+    "line, match",
+    [
+        ("      High    ", "overloaded"),
+        ("Stat        High    ", "overloaded"),
+        ("      Low     ", "underload"),
+        ("   Err 101    ", "error 101"),
+        ("Stat     ERR 320    ", "error 320"),
+        ("   APP.ERR    ", "application error"),
+        ("garbage", "Unexpected SBI data"),
+    ],
+)
+def test_parse_special_and_error_lines(line, match):
+    with pytest.raises(InstrumentProtocolError, match=match):
+        parse_sbi_line(line)
+
+
+def test_calibration_status_is_busy():
+    with pytest.raises(BalanceBusy):
+        parse_sbi_line("Stat     Cal.Int.   ")
+
+
+# ---------------------------------------------------------------- driver against the simulator
+
+
+def test_commands_are_esc_sequences():
+    bal, sim = make_driver()
+    bal.print_reading()
+    bal.tare()
+    bal.zero()
+    bal.set_ambient_filter("unstable")
+    bal.lock_keys(True)
+    assert sim.received == ["\x1bP", "\x1bU", "\x1bV", "\x1bM", "\x1bO"]
+    assert bal.t.write_termination == "\r\n"
+
+
+def test_stable_weight_and_unit_memory():
+    bal, sim = make_driver()
+    w = bal.weight(stable=True)
+    assert w.value == pytest.approx(52.1873, abs=2e-4) and w.unit == "g" and w.stable
+    assert w.ident == "N"
+    sim.place(80.0)
+    w = bal.weight(stable=False)
+    assert not w.stable and w.unit is None and bal.last_unit == "g"
+    w = bal.weight(stable=True, timeout=5)
+    assert w.value == pytest.approx(80.0, abs=2e-4) and w.stable
+
+
+def test_16_character_format():
+    bal, _ = make_driver(fmt=16)
+    w = bal.weight()
+    assert w.ident == "" and w.unit == "g"
+    assert len(bal.t.simulator._weight_line()) == 14  # 16 characters incl. CR LF
+
+
+def test_tare_and_zero():
+    bal, sim = make_driver(load_g=25.0)
+    bal.tare()
+    assert bal.weight().value == pytest.approx(0, abs=2e-4)
+    sim.place(30.5)
+    assert bal.weight(timeout=5).value == pytest.approx(5.5, abs=2e-4)
+    sim.place(0.001)  # container removed, pan nearly empty
+    bal.zero()
+    assert bal.weight(timeout=5).value == pytest.approx(0, abs=2e-4)
+
+
+def test_overload_raises():
+    bal, sim = make_driver()
+    sim.place(500)
+    with pytest.raises(InstrumentProtocolError, match="overloaded"):
+        bal.weight(stable=False)
+
+
+def test_no_reply_gives_configuration_hint():
+    bal, _ = make_driver()
+    with pytest.raises(InstrumentTimeout, match="set to SBI"):
+        bal._lines("Y", timeout=0.3)
+
+
+def test_identify():
+    bal, _ = make_driver()
+    assert bal.identify() == {
+        "manufacturer": "Sartorius",
+        "protocol": "SBI",
+        "model": "QUINTIX224-1S",
+        "serial": "0037402012",
+        "software": "00-20-12.01",
+    }
+
+
+def test_legacy_mode_uses_esc_t():
+    bal, sim = make_driver(legacy=True, load_g=12.0)
+    bal.tare()
+    assert sim.received[-1] == "\x1bT"
+    with pytest.raises(InstrumentProtocolError, match="no separate zero"):
+        bal.zero()
+
+
+def test_unstable_timeout():
+    bal, sim = make_driver(time_scale=1.0)
+    sim.place(10.0)
+    with pytest.raises(InstrumentProtocolError, match="did not report a stable reading"):
+        bal.weight(stable=True, timeout=0.5)
+
+
+# ---------------------------------------------------------------- MCP level
+
+
+async def test_tools_via_mcp():
+    async with simulated_client(server) as client:
+        info = (await client.call_tool("get_connection_info", {})).data
+        assert info["simulated"] is True and info["connected"] is True
+        assert info["instrument"]["model"] == "QUINTIX224-1S"
+
+        reading = (await client.call_tool("read_weight", {"stable": True})).structured_content
+        assert reading["unit"] == "g" and reading["stable"] is True
+        assert reading["value"] == pytest.approx(52.18734, abs=2e-4)
+
+        tared = (await client.call_tool("tare", {})).structured_content
+        assert tared["value"] == pytest.approx(0, abs=2e-4)
+
+        series = (
+            await client.call_tool("log_weight_series", {"count": 3, "interval_s": 0.5})
+        ).structured_content
+        assert series["count"] == 3 and series["unit"] == "g"
+
+        await client.call_tool("set_ambient_conditions", {"conditions": "very_unstable"})
+        await client.call_tool("lock_keypad", {"locked": True})
+        sim = server.driver.t.simulator
+        assert sim.ambient == "N" and sim.keys_locked
+
+        log = (await client.call_tool("get_command_log", {"limit": 100})).data
+        assert any(entry["data"].startswith("<ESC>P") for entry in log)  # control bytes are named
+
+
+async def test_zero_outside_range_is_reported():
+    async with simulated_client(server) as client:
+        with pytest.raises(Exception, match="zero-setting range"):
+            await client.call_tool("zero", {"timeout_s": 1})
+
+
+async def test_internal_adjustment(monkeypatch):
+    monkeypatch.setattr(server_module, "ADJUST_POLL_S", 0.05)
+    async with simulated_client(server) as client:
+        server.driver.t.simulator.adjust_s = 0.5
+        result = (await client.call_tool("run_internal_adjustment", {"timeout_s": 30})).structured_content
+        assert result["observed_adjustment"] is True
+        assert result["final_reading"]["stable"] is True
+        assert server.driver.t.simulator.adjustments == 1
+
+
+async def test_internal_adjustment_not_supported(monkeypatch):
+    monkeypatch.setattr(server_module, "ADJUST_POLL_S", 0.05)
+    monkeypatch.setattr(server_module, "ADJUST_NO_SIGN_S", 0.5)
+    async with simulated_client(server) as client:
+        server.driver.t.simulator.internal_weight = False
+        result = (await client.call_tool("run_internal_adjustment", {"timeout_s": 30})).structured_content
+        assert result["observed_adjustment"] is False
+        assert "No sign of an adjustment" in result["message"]
+
+
+async def test_legacy_option_via_mcp():
+    async with simulated_client(server, options={"legacy": "true"}) as client:
+        tared = (await client.call_tool("tare", {})).structured_content  # ESC T tares a loaded pan
+        assert tared["value"] == pytest.approx(0, abs=2e-4)
+        with pytest.raises(Exception, match="no separate zero"):
+            await client.call_tool("zero", {})
+
+
+async def test_read_only_hides_control_tools():
+    async with simulated_client(server, read_only=True) as client:
+        names = await tool_names(client)
+        assert {"read_weight", "log_weight_series", "reconnect"} <= names
+        for hidden in ("tare", "zero", "run_internal_adjustment", "set_ambient_conditions", "lock_keypad"):
+            assert hidden not in names
+
+
+async def test_series_duration_limit():
+    async with simulated_client(server, limits={"max_series_duration_s": 1}) as client:
+        with pytest.raises(Exception, match="max_series_duration_s"):
+            await client.call_tool("log_weight_series", {"count": 5, "interval_s": 1})
+
+
+def test_limit_error_type():
+    server.configure(simulate=True, limits={"max_series_duration_s": 1})
+    with pytest.raises(SafetyLimitError):
+        server.check("max_series_duration_s", 5)