opentron-glulac-readout-module 2.0.3__tar.gz

opentron_glulac_readout_module-2.0.3/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 WisTex TechSero Ltd. Co.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opentron_glulac_readout_module-2.0.3/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: opentron_glulac_readout_module
+Version: 2.0.3
+Summary: A TU Vienna university project, building a system that allow plugging a Jobst SIX Biotransmitter into the Opentron OT2 automated liquid handler system and then automates measurements with a custom printed labware
+Author-email: Michael Höller <pypi.capably513@passmail.net>
+License-Expression: MIT
+Project-URL: Homepage, https://www.cellchipgroup.org/
+Keywords: tuvienna,opentron,cellchip
+Requires-Python: <3.11
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: opentrons>=9.0.0
+Dynamic: license-file
+
+# opentron_glulac_readout_module
+
+A Python library for reading amperometric sensor data from the **Jobst Six Biotransmitter** when connected to an **Opentrons OT-2** automatic liquid handler (ALH).
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Modules](#modules)
+  - [opentrons_photo_module](#opentrons_photo_module)
+  - [opentron_glulac_readout](#opentron_glulac_readout)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Typical Protocol Flow](#typical-protocol-flow)
+- [API Reference](#api-reference)
+  - [SensorHandlerModule](#sensorhandlermodule)
+  - [opentrons_photo_module](#opentrons_photo_module-1)
+- [Simulation](#simulation)
+
+---
+
+## Overview
+
+This library bridges the Opentrons OT-2 liquid handler with the Jobst Six Biotransmitter, enabling automated amperometric measurements within OT-2 protocols.
+
+**Key features:**
+
+- Continuous background sensor readout written incrementally to CSV — data is preserved even if the protocol is interrupted.
+- Built-in wash cycles with configurable buffer sources and waste destinations.
+- Replicate measurement support with consistent UUID grouping for downstream analysis.
+- Integrated camera capture via the OT-2's built-in video device.
+- Simulation-safe: all functions degrade gracefully when run in Opentrons simulation mode.
+
+---
+
+## Installation
+
+> **Requirement:** Python 3.10 — the Opentrons library only supports this version.
+
+### 1. Create and activate a virtual environment
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+```
+
+### 2. Install the package
+
+```bash
+pip install opentron_glulac_readout_module
+```
+
+---
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `opentrons_photo_module` | Capture images using the OT-2's built-in camera |
+| `opentron_glulac_readout` | Manage sensor readout, measurement cycles, and wash steps |
+
+---
+
+## Usage
+
+### Quick Start
+
+```python
+from opentron_glulac_readout_module import SensorHandlerModule
+from opentrons import protocol_api
+
+# ... opentron definitions ...
+def run(protocol: protocol_api.ProtocolContext):
+  
+  # custom manufactured measurement holder for the sensor that can be placed within the OT-2 
+  glulac = protocol.load_labware(...) 
+  pipette300 = protocol.load_instrument(...)
+  
+  with SensorHandlerModule(
+      protocol=protocol,
+      measuring_well=glulac["A1"],
+      pipette=pipette300,
+  ) as sensor_handler:
+  
+      sensor_handler.add_trash_volume(trash_well)
+      sensor_handler.add_buffer_volume_for_washing(buffer_well)
+      sensor_handler.validate_pipette_clearance_and_sensor()
+  
+      csv_path = sensor_handler.start_measurement()
+  
+      sensor_handler.measure(source_well=plate["A1"])
+```
+
+### Typical Protocol Flow
+
+The following order must be respected when setting up a measurement session:
+
+```
+1. Create SensorHandlerModule (via context manager)
+2. add_trash_volume()               — register waste wells
+3. add_buffer_volume_for_washing()  — register buffer wells
+4. validate_pipette_clearance_and_sensor()  — optional, but must precede start_measurement()
+5. start_measurement()              — opens CSV and starts background readout
+6. measure() / measure_replicate()  — one call per sample
+```
+
+> **Note:** `validate_pipette_clearance_and_sensor()` cannot be called after `start_measurement()` — doing so raises a `RuntimeError`.
+
+---
+
+## API Reference
+
+### SensorHandlerModule
+
+The central class for managing sensor readout. Must be used as a **context manager** to ensure background threads and CSV writers are properly started and stopped.
+
+```python
+with SensorHandlerModule(
+    protocol=protocol,
+    measuring_well=glulac["A1"],
+    pipette=pipette300,
+) as sensor_handler:
+    ...
+```
+
+---
+
+#### `add_trash_volume(well, ...)`
+
+Registers a well as a waste destination for discarded liquid.
+
+Multiple trash wells can be registered; they are filled in registration order as capacity is consumed. Must be called before `start_measurement()`.
+
+> Not required if only `start_measurement()` is used with no wash steps.
+
+---
+
+#### `add_buffer_volume_for_washing(well, ...)`
+
+Registers a well as a buffer source for wash steps.
+
+Multiple buffer wells can be registered; they are drawn from in registration order as volume is consumed. Must be called before `start_measurement()`.
+
+> Not required if only `start_measurement()` is used with no wash steps.
+
+---
+
+#### `validate_pipette_clearance_and_sensor(...)`
+
+Moves the pipette through all configured positions so the operator can visually confirm there are no crash risks before the protocol runs.
+
+Optionally verifies that:
+- The sensor produces a valid readout.
+- The camera module is functional.
+
+Each individual check can be disabled if only a subset of positions need to be verified.
+
+**Constraints:**
+- Must be called before `start_measurement()`.
+- Calling it after `start_measurement()` raises a `RuntimeError`.
+
+---
+
+#### `start_measurement() -> str`
+
+Opens the output CSV file and starts continuous background sensor readout.
+
+The CSV is written incrementally (one row per sensor reading), so data is preserved even if the protocol is interrupted mid-run.
+
+**Returns:** The absolute path of the CSV file being written to.
+
+**Must be called after:**
+- `add_buffer_volume_for_washing()` / `add_trash_volume()` (if used)
+- `validate_pipette_clearance_and_sensor()` (if used)
+
+---
+
+#### `measure(source_well, ...)`
+
+Performs a single complete measurement cycle:
+
+1. Aspirates sample from `source_well` and dispenses it into the measuring well.
+2. Waits for the sensor signal to stabilize (slope detection followed by rolling standard deviation threshold).
+3. Washes the measuring well with buffer for `SensorSettings.wash_iterations` cycles, waiting for signal stability after each wash.
+
+The background CSV is annotated with `is_measuring_sample` and `is_washing` flags on each row, enabling precise time-windowing in downstream analysis.
+
+Each call generates a unique `sample_uuid` that groups all CSV rows for the measurement (including wash rows).
+
+---
+
+#### `measure_replicate(source_well, ...)`
+
+Runs a replicate measurement series on the sample.
+
+The number of replicates defaults to `3` and can be configured via `SensorSettings.replicate_iterations`.
+
+All repetitions share the same `sample_uuid` for grouping in downstream analysis and are stamped with an incrementing `replicate_count` column (starting at `1`).
+
+This is equivalent to calling `measure()` multiple times manually, but guarantees consistent UUID grouping and replicate bookkeeping.
+
+---
+
+### opentrons_photo_module
+
+Photography functions do **not** require a `SensorHandlerModule` instance.
+
+---
+
+#### `take_picture(directory, filename, ...)`
+
+Captures a single JPEG frame using the OT-2's built-in video device (`/dev/video0`) via FFmpeg.
+
+- The output directory is created automatically if it does not exist.
+- In **simulation mode**, no image is captured; a comment is logged to the protocol indicating where the photo would have been saved.
+
+---
+
+## Simulation
+
+To test whether a protocol will run correctly without executing it on real hardware, use the `opentrons_simulate` CLI from within your virtual environment:
+
+```bash
+opentrons_simulate -L /Local_Path/toLabwareFolder protocol_name.py
+```
+
+> The `-L` flag points to your custom labware directory. Using the same path as the Opentrons App reduces the risk of labware definition mismatches.
+> You find this Location by going to the Opentrons App, press on preferences (bottom left), Advanced 'Additional Custom Labware Source Folder'. Here you can see the current folder, fill this one here

opentron_glulac_readout_module-2.0.3/README.md

@@ -0,0 +1,230 @@
+# opentron_glulac_readout_module
+
+A Python library for reading amperometric sensor data from the **Jobst Six Biotransmitter** when connected to an **Opentrons OT-2** automatic liquid handler (ALH).
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Modules](#modules)
+  - [opentrons_photo_module](#opentrons_photo_module)
+  - [opentron_glulac_readout](#opentron_glulac_readout)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Typical Protocol Flow](#typical-protocol-flow)
+- [API Reference](#api-reference)
+  - [SensorHandlerModule](#sensorhandlermodule)
+  - [opentrons_photo_module](#opentrons_photo_module-1)
+- [Simulation](#simulation)
+
+---
+
+## Overview
+
+This library bridges the Opentrons OT-2 liquid handler with the Jobst Six Biotransmitter, enabling automated amperometric measurements within OT-2 protocols.
+
+**Key features:**
+
+- Continuous background sensor readout written incrementally to CSV — data is preserved even if the protocol is interrupted.
+- Built-in wash cycles with configurable buffer sources and waste destinations.
+- Replicate measurement support with consistent UUID grouping for downstream analysis.
+- Integrated camera capture via the OT-2's built-in video device.
+- Simulation-safe: all functions degrade gracefully when run in Opentrons simulation mode.
+
+---
+
+## Installation
+
+> **Requirement:** Python 3.10 — the Opentrons library only supports this version.
+
+### 1. Create and activate a virtual environment
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+```
+
+### 2. Install the package
+
+```bash
+pip install opentron_glulac_readout_module
+```
+
+---
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `opentrons_photo_module` | Capture images using the OT-2's built-in camera |
+| `opentron_glulac_readout` | Manage sensor readout, measurement cycles, and wash steps |
+
+---
+
+## Usage
+
+### Quick Start
+
+```python
+from opentron_glulac_readout_module import SensorHandlerModule
+from opentrons import protocol_api
+
+# ... opentron definitions ...
+def run(protocol: protocol_api.ProtocolContext):
+  
+  # custom manufactured measurement holder for the sensor that can be placed within the OT-2 
+  glulac = protocol.load_labware(...) 
+  pipette300 = protocol.load_instrument(...)
+  
+  with SensorHandlerModule(
+      protocol=protocol,
+      measuring_well=glulac["A1"],
+      pipette=pipette300,
+  ) as sensor_handler:
+  
+      sensor_handler.add_trash_volume(trash_well)
+      sensor_handler.add_buffer_volume_for_washing(buffer_well)
+      sensor_handler.validate_pipette_clearance_and_sensor()
+  
+      csv_path = sensor_handler.start_measurement()
+  
+      sensor_handler.measure(source_well=plate["A1"])
+```
+
+### Typical Protocol Flow
+
+The following order must be respected when setting up a measurement session:
+
+```
+1. Create SensorHandlerModule (via context manager)
+2. add_trash_volume()               — register waste wells
+3. add_buffer_volume_for_washing()  — register buffer wells
+4. validate_pipette_clearance_and_sensor()  — optional, but must precede start_measurement()
+5. start_measurement()              — opens CSV and starts background readout
+6. measure() / measure_replicate()  — one call per sample
+```
+
+> **Note:** `validate_pipette_clearance_and_sensor()` cannot be called after `start_measurement()` — doing so raises a `RuntimeError`.
+
+---
+
+## API Reference
+
+### SensorHandlerModule
+
+The central class for managing sensor readout. Must be used as a **context manager** to ensure background threads and CSV writers are properly started and stopped.
+
+```python
+with SensorHandlerModule(
+    protocol=protocol,
+    measuring_well=glulac["A1"],
+    pipette=pipette300,
+) as sensor_handler:
+    ...
+```
+
+---
+
+#### `add_trash_volume(well, ...)`
+
+Registers a well as a waste destination for discarded liquid.
+
+Multiple trash wells can be registered; they are filled in registration order as capacity is consumed. Must be called before `start_measurement()`.
+
+> Not required if only `start_measurement()` is used with no wash steps.
+
+---
+
+#### `add_buffer_volume_for_washing(well, ...)`
+
+Registers a well as a buffer source for wash steps.
+
+Multiple buffer wells can be registered; they are drawn from in registration order as volume is consumed. Must be called before `start_measurement()`.
+
+> Not required if only `start_measurement()` is used with no wash steps.
+
+---
+
+#### `validate_pipette_clearance_and_sensor(...)`
+
+Moves the pipette through all configured positions so the operator can visually confirm there are no crash risks before the protocol runs.
+
+Optionally verifies that:
+- The sensor produces a valid readout.
+- The camera module is functional.
+
+Each individual check can be disabled if only a subset of positions need to be verified.
+
+**Constraints:**
+- Must be called before `start_measurement()`.
+- Calling it after `start_measurement()` raises a `RuntimeError`.
+
+---
+
+#### `start_measurement() -> str`
+
+Opens the output CSV file and starts continuous background sensor readout.
+
+The CSV is written incrementally (one row per sensor reading), so data is preserved even if the protocol is interrupted mid-run.
+
+**Returns:** The absolute path of the CSV file being written to.
+
+**Must be called after:**
+- `add_buffer_volume_for_washing()` / `add_trash_volume()` (if used)
+- `validate_pipette_clearance_and_sensor()` (if used)
+
+---
+
+#### `measure(source_well, ...)`
+
+Performs a single complete measurement cycle:
+
+1. Aspirates sample from `source_well` and dispenses it into the measuring well.
+2. Waits for the sensor signal to stabilize (slope detection followed by rolling standard deviation threshold).
+3. Washes the measuring well with buffer for `SensorSettings.wash_iterations` cycles, waiting for signal stability after each wash.
+
+The background CSV is annotated with `is_measuring_sample` and `is_washing` flags on each row, enabling precise time-windowing in downstream analysis.
+
+Each call generates a unique `sample_uuid` that groups all CSV rows for the measurement (including wash rows).
+
+---
+
+#### `measure_replicate(source_well, ...)`
+
+Runs a replicate measurement series on the sample.
+
+The number of replicates defaults to `3` and can be configured via `SensorSettings.replicate_iterations`.
+
+All repetitions share the same `sample_uuid` for grouping in downstream analysis and are stamped with an incrementing `replicate_count` column (starting at `1`).
+
+This is equivalent to calling `measure()` multiple times manually, but guarantees consistent UUID grouping and replicate bookkeeping.
+
+---
+
+### opentrons_photo_module
+
+Photography functions do **not** require a `SensorHandlerModule` instance.
+
+---
+
+#### `take_picture(directory, filename, ...)`
+
+Captures a single JPEG frame using the OT-2's built-in video device (`/dev/video0`) via FFmpeg.
+
+- The output directory is created automatically if it does not exist.
+- In **simulation mode**, no image is captured; a comment is logged to the protocol indicating where the photo would have been saved.
+
+---
+
+## Simulation
+
+To test whether a protocol will run correctly without executing it on real hardware, use the `opentrons_simulate` CLI from within your virtual environment:
+
+```bash
+opentrons_simulate -L /Local_Path/toLabwareFolder protocol_name.py
+```
+
+> The `-L` flag points to your custom labware directory. Using the same path as the Opentrons App reduces the risk of labware definition mismatches.
+> You find this Location by going to the Opentrons App, press on preferences (bottom left), Advanced 'Additional Custom Labware Source Folder'. Here you can see the current folder, fill this one here

opentron_glulac_readout_module-2.0.3/opentron_glulac_readout_module/__init__.py

@@ -0,0 +1,5 @@
+from opentron_glulac_readout_module.opentron_glulac_readout.opentron_readout import SensorHandlerModule, SensorExpectedConcentrations, SensorMetadata, SensorType, SensorSettings
+from opentron_glulac_readout_module.opentrons_photo_module.opentron_photo import take_picture
+
+# Version of the opentron_glulac_readout_module package
+__version__ = "2.0.3"

opentron_glulac_readout_module-2.0.3/opentron_glulac_readout_module/opentron_glulac_readout/jobst_sensor_module.py

@@ -0,0 +1,118 @@
+import time
+import serial
+
+
+class JobstSensorModule:
+    HEADER = bytes([0x68, 0x13, 0x13, 0x68, 0x04])  # wire order
+    PAYLOAD_LENGTH = 18
+    FOOTER_LENGTH = 2  # [checksum, 0x16]
+    GAIN = 50 / (2 ** 15 - 1)  # nA per LSB
+    INTER_FRAME_LENGTH = 15
+
+    def __init__(self, com_port: str = "/dev/ttyUSB0", baud: int = 9600):
+        self.com_port = com_port
+        self.baud = baud
+
+    def readout_stream(self):
+        """
+        A generator that yields processed sensor data frames.
+
+        Each yielded dict contains:
+            - timestamp       (str)   : wall-clock time of the frame
+            - currents        (list)  : 6 current readings in nanoamperes
+            - temp            (float) : temperature in degrees Celsius
+            - frames_received (int)   : running count of valid frames
+            - frames_skipped  (int)   : running count of invalid/incomplete frames
+        """
+        with serial.Serial(self.com_port, baudrate=self.baud, timeout=2.0) as ser:
+            # Double-flush: discard any partial frame that arrived before open
+            ser.reset_input_buffer()
+            time.sleep(1.6)  # wait one full sensor cycle
+            ser.reset_input_buffer()  # flush bytes that arrived during the wait
+
+            frames_received = 0
+            frames_skipped = 0
+
+            while True:
+                # ── 1. seek header ─────────────────────────────────────────
+                buf = ser.read_until(self.HEADER)
+
+                if not buf.endswith(self.HEADER):
+                    frames_skipped += 1
+                    continue
+
+                # ── 2. read payload + footer ───────────────────────────────
+                frame = ser.read(self.PAYLOAD_LENGTH + self.FOOTER_LENGTH)
+
+                if len(frame) < self.PAYLOAD_LENGTH + self.FOOTER_LENGTH:
+                    frames_skipped += 1
+                    continue
+
+                payload = frame[:self.PAYLOAD_LENGTH]
+                checksum_byte = frame[self.PAYLOAD_LENGTH]  # second-to-last
+                footer_byte = frame[self.PAYLOAD_LENGTH + 1]  # last byte = 0x16
+
+                # ── 3. validate footer ─────────────────────────────────────
+                if footer_byte != 0x16:
+                    frames_skipped += 1
+                    continue
+
+                # ── 4. validate checksum ───────────────────────────────────
+                # Covers the 18 payload bytes plus the trailing 0x04 header byte
+                cks = (sum(payload) + 0x04) & 0xFF
+                if cks != checksum_byte:
+                    frames_skipped += 1
+                    continue
+
+                # ── 5. decode payload ──────────────────────────────────────
+                it = iter(payload)
+                out_data = [
+                    int.from_bytes(bytes([x, next(it)]), 'big', signed=True)
+                    for x in it
+                ]
+
+                currents = [round(x * self.GAIN, 3) for x in out_data[0:6]]
+                temperature = round(out_data[6] / 16, 3)
+                frames_received += 1
+
+                yield {
+                    "timestamp": time.strftime('%Y-%m-%d %H:%M:%S'),
+                    "currents": currents,
+                    "temp": temperature,
+                    "frames_received": frames_received,
+                    "frames_skipped": frames_skipped,
+                }
+
+                # ── 6. consume inter-frame bytes (natural ~1.5s pause) ─────
+                ser.read(self.INTER_FRAME_LENGTH)
+
+    def validate_sensor(self, frames_required: int = 3, timeout_seconds: float = 10.0) -> bool:
+        """
+        Opens the serial connection briefly, attempts to read `frames_required`
+        valid frames, then closes it. Returns True if successful.
+        Raises SerialException if the port cannot be opened at all.
+        """
+        received = 0
+        deadline = time.time() + timeout_seconds
+        package_length = 25
+        data_block = [b'\x00'] * package_length
+
+        with serial.Serial(self.com_port, baudrate=self.baud, timeout=2) as ser:
+            while time.time() < deadline:
+                data = ser.read() if ser.inWaiting() else None
+                if data:
+                    data_block.insert(0, data)
+                    data_block.pop()
+
+                    header = [b'\x04', b'\x68', b'\x13', b'\x13', b'\x68']
+                    cks = sum(int.from_bytes(x, 'big') for x in data_block[2:-4]) & 0xFF
+
+                    if (data_block[-5:] == header
+                            and data_block[0] == b'\x16'
+                            and int.from_bytes(data_block[1], 'big') == cks):
+                        received += 1
+                        if received >= frames_required:
+                            return True
+                time.sleep(0.01)
+
+        return False  # timed out before receiving enough valid frames