{ "cells": [ { "cell_type": "markdown", "id": "6bb6b592", "metadata": {}, "source": [ "# CERTUS FLEX\n", "\n", "```{device-card} gyger-certus-flex\n", "```\n", "\n", "**Hardware verified on C196069** (firmware 1.0.7.378-trunk, angled FLEX8, direct Ethernet): identity/status reads, plate motion, 0.2 bar regulation/discharge, timed water dispensing, native prime/purge, and the clean cycle. Water flow was observed from both connected channels. Volume-to-time conversion is checked against the vendor algorithm. See [verification scope](protocol.md#verification-scope) for the tested configuration and operations. Run this notebook one cell at a time.\n", "\n", "| Property | Value |\n", "| --- | --- |\n", "| Connection | Direct controller UDP 1964; optional INCO server TCP 7979 |\n", "| Heads | FLEX5, FLEX8, angled FLEX4, angled FLEX8 |\n", "| Units | mm, seconds, µL; pressure explicitly in bar |\n", "| Supported | Identity/status, reference/position/park, pressure, timed and calibrated valve dispensing, prime/purge/clean cycle |\n", "\n", "## How it connects\n", "\n", "PLR connects directly to the controller over Ethernet, without a vendor DLL or control PC. Put the wired interface on the controller's subnet. The tested controller used `192.168.1.3`, with the computer at `192.168.1.2/24`; confirm your machine's addresses. To use an existing INCO server instead, set `CERTUS_INCO_TARGET` to its configured target name and use the server PC's address as `CERTUS_HOST`. See [protocol and verification notes](protocol.md).\n", "\n", "## Physical setup\n", "\n", "Confirm the installed head type and channel labels. Set up the machine, compatible vessels, valves, tubing, compressed air supply, and waste collection according to its manual. Use water for the first fluid test. Ensure the axes and clamp have clearance. Finish any run in CERTUS CONTROL and use only one controlling application at a time.\n", "\n", "Set `CERTUS_HOST` and `CERTUS_HEAD` in the notebook environment. Head values are `flex5`, `flex8`, `flex4_angled`, or `flex8_angled`. For direct Ethernet, leave `CERTUS_INCO_TARGET` unset. Optionally set `CERTUS_SOURCE_IP` to the local wired interface's IPv4 address.\n", "\n", "## Configure\n", "\n", "Constructing the object does not connect to the machine." ] }, { "cell_type": "code", "execution_count": null, "id": "1f72a697", "metadata": {}, "outputs": [], "source": [ "import os\n", "from pylabrobot.gyger import CertusFlex, ValveCalibration\n", "\n", "certus = CertusFlex(\n", " host=os.environ[\"CERTUS_HOST\"],\n", " target=os.environ.get(\"CERTUS_INCO_TARGET\"),\n", " head=os.environ[\"CERTUS_HEAD\"],\n", " source_ip=os.environ.get(\"CERTUS_SOURCE_IP\"),\n", " timeout=60,\n", ")" ] }, { "cell_type": "markdown", "id": "0dee2e8f", "metadata": {}, "source": [ "## Connect and capture identity\n", "\n", "`setup()` only connects and reads serial number and firmware. Capture the first exchange for diagnosis; this cell does not request motion or pressure changes." ] }, { "cell_type": "code", "execution_count": null, "id": "6545532b", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.io import start_capture, stop_capture\n", "\n", "start_capture(\"certus-first-read\")\n", "try:\n", " await certus.setup()\n", " print(certus.serial_number, certus.firmware_version)\n", "finally:\n", " stop_capture()" ] }, { "cell_type": "markdown", "id": "38abbd6b", "metadata": {}, "source": [ "## Read status\n", "\n", "Compare these states with the control software before attempting motion. Resolve machine faults using the normal operator procedure; the driver does not automatically acknowledge them." ] }, { "cell_type": "code", "execution_count": null, "id": "8cef3310", "metadata": {}, "outputs": [], "source": [ "await certus.get_status()" ] }, { "cell_type": "markdown", "id": "1d8b62a6", "metadata": {}, "source": [ "## Read position\n", "\n", "These are controller X/Y/Z coordinates in mm. They are not PLR deck or well coordinates." ] }, { "cell_type": "code", "execution_count": null, "id": "e8fbfb7c", "metadata": {}, "outputs": [], "source": [ "await certus.get_position()" ] }, { "cell_type": "markdown", "id": "199df47b", "metadata": {}, "source": [ "## Read pressure\n", "\n", "The result is actual dispensing pressure in bar." ] }, { "cell_type": "code", "execution_count": null, "id": "f51705e2", "metadata": {}, "outputs": [], "source": [ "await certus.get_pressure()" ] }, { "cell_type": "markdown", "id": "46815e65", "metadata": {}, "source": [ "## Initialize\n", "\n", "Continue only after the read-only checks match the machine. Clear the workspace before running this cell: initialization can start the dispenser and reference its axes." ] }, { "cell_type": "code", "execution_count": null, "id": "d7faffe7", "metadata": {}, "outputs": [], "source": [ "await certus.initialize()" ] }, { "cell_type": "markdown", "id": "4717f798", "metadata": {}, "source": [ "## Park\n", "\n", "This raises Z to the configured park height before moving XY to park." ] }, { "cell_type": "code", "execution_count": null, "id": "7eaf6112", "metadata": {}, "outputs": [], "source": [ "await certus.park()" ] }, { "cell_type": "markdown", "id": "bcdcffa1", "metadata": {}, "source": [ "## Position over waste\n", "\n", "Check that the configured prime location is over the waste collector. This moves Z to park, XY to prime, and Z to prime. It does not open a valve." ] }, { "cell_type": "code", "execution_count": null, "id": "d1a9572e", "metadata": {}, "outputs": [], "source": [ "await certus.move_to_prime()" ] }, { "cell_type": "markdown", "id": "360d9281", "metadata": {}, "source": [ "## Set pressure\n", "\n", "Confirm that the connected vessels and installed valves are suitable for 0.2 bar, or edit the value to the verified operating pressure. This setting was exercised with water; it is not a universal valve default. The cell pressurizes the supply and waits for the measured pressure." ] }, { "cell_type": "code", "execution_count": null, "id": "fe5221af", "metadata": {}, "outputs": [], "source": [ "await certus.set_pressure(0.2)" ] }, { "cell_type": "markdown", "id": "ab0e79c0", "metadata": {}, "source": [ "## Deliver a timed test pulse\n", "\n", "Confirm channel 1 is prepared with water and aimed into waste. `valves[0]` is the first printed head channel. This requests one 1 ms pulse and waits for completion. A pulse is not a known volume without calibration. Do not rerun a failed dispense automatically; it may already have delivered liquid." ] }, { "cell_type": "code", "execution_count": null, "id": "94dc2e8f", "metadata": {}, "outputs": [], "source": [ "await certus.valves[0].dispense_for(0.001)" ] }, { "cell_type": "markdown", "id": "eb4b6b7c", "metadata": {}, "source": [ "## Optional: measured volume calibration\n", "\n", "Skip this section until a calibration has been measured for this exact valve, fluid, and pressure. Prepare `measured-calibration.json` with `pressure` in bar and a `points` list of `[volume_in_uL, duration_in_seconds]` pairs. Both values must increase, with at least two points. This cell only loads calibration; it does not dispense." ] }, { "cell_type": "code", "execution_count": null, "id": "829c9507", "metadata": {}, "outputs": [], "source": [ "import json\n", "from pathlib import Path\n", "\n", "measured = json.loads(Path(\"measured-calibration.json\").read_text())\n", "certus.valves[0].calibration = ValveCalibration(\n", " points=tuple(tuple(point) for point in measured[\"points\"]),\n", " pressure=measured[\"pressure\"],\n", ")" ] }, { "cell_type": "markdown", "id": "64ec6921", "metadata": {}, "source": [ "## Optional: dispense a calibrated volume\n", "\n", "Keep the valve aimed into waste for validation. Enter a volume within the measured calibration range and confirm the measured pressure matches the calibration. This cell delivers liquid.\n", "\n", "The optional `correction_factor` argument matches the channel volume correction in CERTUS CONTROL (0.5–1.5, default 1.0). It multiplies the requested volume before interpolation. Use the factor for your setup; PLR does not read it from the vendor application. Physical volume accuracy comes from the valve/fluid calibration and is separate from verifying the driver's calculation." ] }, { "cell_type": "code", "execution_count": null, "id": "ba3d1690", "metadata": {}, "outputs": [], "source": [ "volume = float(input(\"Verified test volume in µL: \"))\n", "await certus.valves[0].dispense(volume)" ] }, { "cell_type": "markdown", "id": "0291fa43", "metadata": {}, "source": [ "## Prime a channel\n", "\n", "The head must be over waste and pressure regulated. This opens channel 1 continuously for 100 ms using the native Prime command and waits for completion. The controller's prime timeout is checked before opening. A timed opening is not a calibrated priming volume." ] }, { "cell_type": "code", "execution_count": null, "id": "07163209", "metadata": {}, "outputs": [], "source": [ "await certus.valves[0].prime(0.1)" ] }, { "cell_type": "markdown", "id": "6c3f05ef", "metadata": {}, "source": [ "## Purge a channel\n", "\n", "Keep the head over waste. This requests 20 ms of cumulative opening time as 1 ms pulses. Pulse timing is enforced by firmware; total elapsed time also includes the firmware's inter-pulse waits." ] }, { "cell_type": "code", "execution_count": null, "id": "11ef0d5e", "metadata": {}, "outputs": [], "source": [ "await certus.valves[0].purge(0.02, pulse_duration=0.001)" ] }, { "cell_type": "markdown", "id": "9c5038c7", "metadata": {}, "source": [ "## Optional: import a vendor calibration\n", "\n", "Use a measured CERTUS CONTROL calibration for the installed water valve. Choose the\n", "map ID if the file contains several maps. Enter the actual valve serial; it is an\n", "operator declaration, because the controller does not report individual valve IDs." ] }, { "cell_type": "code", "execution_count": null, "id": "f551fd76", "metadata": {}, "outputs": [], "source": [ "from pathlib import Path\n", "\n", "calibration = ValveCalibration.from_vendor_xml(\n", " Path(\"water-calibration.xml\").read_text(),\n", " calibration_id=input(\"Calibration map ID: \"),\n", ")\n", "await certus.configure_channel(\n", " 1, calibration=calibration, fluid=\"Water\",\n", " valve_serial=input(\"Installed channel 2 valve serial: \"),\n", ")\n", "certus.save_configuration(\"certus-water.json\")" ] }, { "cell_type": "markdown", "id": "72754a48", "metadata": {}, "source": [ "## Optional: restore channel configuration\n", "\n", "After `setup()`, load a configuration for this controller and head. Check that its\n", "specified valves and liquids are still installed. This cell does not dispense." ] }, { "cell_type": "code", "execution_count": null, "id": "81a24da6", "metadata": {}, "outputs": [], "source": [ "await certus.load_configuration(\"certus-water.json\")" ] }, { "cell_type": "markdown", "id": "88c03d02", "metadata": {}, "source": [ "## Park before loading a plate\n", "\n", "Raise and park before placing the lidless Corning 96-well plate. Align A1 with the\n", "holder's marked corner; clear the motion area before the positioning cells." ] }, { "cell_type": "code", "execution_count": null, "id": "01c87a13", "metadata": {}, "outputs": [], "source": [ "await certus.park()" ] }, { "cell_type": "markdown", "id": "5ce61185", "metadata": {}, "source": [ "## Register the plate\n", "\n", "Use the mounted plate's exact PLR resource. Enter a verified X/Y/Z motion envelope\n", "in machine mm; these values are not inferred from plate size. Registration reads\n", "the active controller plate geometry and checks its grid and the installed head." ] }, { "cell_type": "code", "execution_count": null, "id": "3a560f8a", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.gyger import DispenseStep, MotionBounds, RunControl\n", "from pylabrobot.resources import cor_96_wellplate_360uL_Fb\n", "\n", "plate = cor_96_wellplate_360uL_Fb(\"water_plate\")\n", "bounds = MotionBounds(\n", " minimum=tuple(map(float, input(\"Verified minimum X,Y,Z (mm): \").split(\",\"))),\n", " maximum=tuple(map(float, input(\"Verified maximum X,Y,Z (mm): \").split(\",\"))),\n", ")\n", "registration = await certus.read_plate_registration(plate, bounds=bounds)" ] }, { "cell_type": "markdown", "id": "cdafbb68", "metadata": {}, "source": [ "## Position a channel over a well\n", "\n", "This raises to clearance, moves XY, lowers channel 2 over B2, and verifies the\n", "reported position. It does not dispense." ] }, { "cell_type": "code", "execution_count": null, "id": "a97dee9a", "metadata": {}, "outputs": [], "source": [ "await certus.move_to_well(registration, plate.get_item(\"B2\"), channel=1)" ] }, { "cell_type": "markdown", "id": "0ca6cf5d", "metadata": {}, "source": [ "## Run a small water plate plan\n", "\n", "Prepare and prime water on physical channels 2 and 3, regulate pressure, and verify\n", "that the plate can accept a short test pulse in B2/C2/B3/C3. Indexes are zero-based.\n", "Timed commissioning pulses do not imply a measured volume. For calibrated work,\n", "replace `duration` with `volume` in µL after configuring each channel's curve." ] }, { "cell_type": "code", "execution_count": null, "id": "b2cd8079", "metadata": {}, "outputs": [], "source": [ "steps = [\n", " DispenseStep(plate.get_item(well), channel, duration=0.001)\n", " for well, channel in [(\"B2\", 1), (\"C2\", 2), (\"B3\", 1), (\"C3\", 2)]\n", "]\n", "plan = certus.plan_dispense(registration, steps)\n", "control = RunControl()\n", "await certus.execute_plan(plan, control=control)\n", "control.progress" ] }, { "cell_type": "markdown", "id": "291a892b", "metadata": {}, "source": [ "## Controlled flush into waste\n", "\n", "Confirm waste collection and prepared channels. This moves to prime waste, flushes\n", "continuously for 50 ms per channel, and parks. Firmware enforces the duration.\n", "To stop early, start the flush in an asyncio task and call `await certus.abort()`." ] }, { "cell_type": "code", "execution_count": null, "id": "cf77ded9", "metadata": {}, "outputs": [], "source": [ "await certus.flush([1, 2], duration=0.05)" ] }, { "cell_type": "markdown", "id": "f32f8961", "metadata": {}, "source": [ "## Idle purge\n", "\n", "This finite schedule waits 10 seconds, then waits for any current plate operation,\n", "purges into waste, and parks. It does not install a persistent controller timer." ] }, { "cell_type": "code", "execution_count": null, "id": "a5456c32", "metadata": {}, "outputs": [], "source": [ "await certus.idle_purge(\n", " [1, 2], interval=10, cycles=1, duration=0.002, pulse_duration=0.001,\n", ")" ] }, { "cell_type": "markdown", "id": "b4f5ea2d", "metadata": {}, "source": [ "## Read detailed faults\n", "\n", "Read pending controller messages without acknowledging them. The driver never clears\n", "an error automatically to continue a run." ] }, { "cell_type": "code", "execution_count": null, "id": "b17ad0af", "metadata": {}, "outputs": [], "source": [ "await certus.get_faults()" ] }, { "cell_type": "markdown", "id": "f0b12ef1", "metadata": {}, "source": [ "## Clean cycle\n", "\n", "Confirm waste collection and select the prepared channels. Indexes `[1, 2]` mean physical channels 2 and 3. This moves to the purge position, purges each channel, waits 250 ms, primes each channel, and parks. It performs one cycle at the existing pressure. These timings test functionality; they are not a validated cleaning recipe. Discharge is explicit in `finally`. This one-cycle sequence is hardware-verified with water on channels 2 and 3 at 0.2 bar." ] }, { "cell_type": "code", "execution_count": null, "id": "f6e07501", "metadata": {}, "outputs": [], "source": [ "try:\n", " await certus.clean_cycle(\n", " channels=[1, 2],\n", " prime_duration=0.1,\n", " purge_duration=0.02,\n", " purge_pulse_duration=0.001,\n", " cycles=1,\n", " )\n", "finally:\n", " await certus.set_pressure(0)" ] }, { "cell_type": "markdown", "id": "69d51af1", "metadata": {}, "source": [ "## Discharge pressure\n", "\n", "Explicitly discharge the vessels before disconnecting. Disconnecting alone does not change machine state." ] }, { "cell_type": "code", "execution_count": null, "id": "6e2a0289", "metadata": {}, "outputs": [], "source": [ "await certus.set_pressure(0)" ] }, { "cell_type": "markdown", "id": "701f6668", "metadata": {}, "source": [ "## Disconnect\n", "\n", "This closes the connection. It does not abort motion, stop a queued pulse, or operate an emergency stop." ] }, { "cell_type": "code", "execution_count": null, "id": "6677e754", "metadata": {}, "outputs": [], "source": [ "await certus.stop()" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 5 }