diff --git a/docs/conf.py b/docs/conf.py index 88bd5b3e383..1796ff109c2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,7 @@ "IPython.sphinxext.ipython_console_highlighting", "sphinx_reredirects", "sphinx_sitemap", + "sphinx_tabs.tabs" ] intersphinx_mapping = { diff --git a/docs/resources/resource-holder/plate-holder.md b/docs/resources/resource-holder/plate-holder.md index dae3089ba62..cee16566f8d 100644 --- a/docs/resources/resource-holder/plate-holder.md +++ b/docs/resources/resource-holder/plate-holder.md @@ -24,7 +24,7 @@ To explain what is happening in the image above: you measure the difference betw #### Measurement with z probing -To measure the height of a surface, you might find [z probing](/user_guide/00_liquid-handling/hamilton-star/z-probing) useful. Z-probing is an automated way, using a pipetting channel, to find the z height of an object. You can see a video of automated measurement on our YouTube channel: +To measure the height of a surface, you might find [z probing](/user_guide/00_liquid-handling/hamilton-star/probing/z-probing) useful. Z-probing is an automated way, using a pipetting channel, to find the z height of an object. You can see a video of automated measurement on our YouTube channel: diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/_hamilton-star.rst b/docs/user_guide/00_liquid-handling/hamilton-star/_hamilton-star.rst index b0f65a7049a..5c362f884a2 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/_hamilton-star.rst +++ b/docs/user_guide/00_liquid-handling/hamilton-star/_hamilton-star.rst @@ -1,21 +1,83 @@ Hamilton STAR ============= -Tools for working with Hamilton-STAR specific functions. +.. tabs:: + + .. tab:: STAR (54 tracks) + + .. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Summary + - Image + * - * **OEM Link:** `Hamilton Company `_ + * **Communication Protocol / Hardware:** USB / USB-A/B + * **Communication Level:** Firmware + * **VID:PID:** 0x08AF:0x8000 + * **Deck Size:** 54 tracks + - .. figure:: img/star_old.png + :width: 320px + :align: center + + STAR with 54-track deck + + .. tab:: STARlet (30 tracks) + + .. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Summary + - Image + * - * **OEM Link:** `Hamilton Company `_ + * **Communication Protocol / Hardware:** USB / USB-A/B + * **Communication Level:** Firmware + * **VID:PID:** 0x08AF:0x8000 + * **Deck Size:** 30 tracks + - .. figure:: img/starlet_old.png + :width: 320px + :align: center + + STARlet with 30-track deck + +About the Machine(s) +-------------------- + +The Hamilton Microlab STAR is a modular liquid handling workstation designed for high-throughput laboratory automation. +(The STARlet is a smaller version of the STAR that uses the exact same commands.) + +It is particularly popular in the PyLabRobot community due to its flexibility, robustness, extensive sensor systems, and well-documented firmware. +Both the STAR and the STARlet share the same modular architecture and can be configured with: + +* **Pipetting Tools:** + * 1000µL channels (4-16) + * 5ml channels (1-4) +* **Optional Modules:** + * "Multi-Probe Head": 96-Head / 384-Head + * Autoload with barcode reading (1D / 2D reader) + * iSWAP (for plate handling) + * Imaging Channel + * Tube Twister & Decapper +* **Key Technologies:** + * CO-RE (Compression-induced O-Ring Expansion) tip attachment + * dual liquid level detection (capacitive and pressure-based) + * monitored air displacement (MAD) + * anti-droplet control (ADC, for volatile solvents) + * x/y/z motor resolution = 0.1 mm + +---------------------- + +Table of Contents +----------------- .. toctree:: - :maxdepth: 1 - - basic - 96head - autoload_and_1d_barcode_reader - iswap-module - star_lld - y-probing - z-probing + :maxdepth: 2 + + core-features/intro + modules/intro + probing/intro foil debug hardware/index - hamilton-liquid-classes - core-grippers - surface-following + diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/basic.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/basic.ipynb similarity index 99% rename from docs/user_guide/00_liquid-handling/hamilton-star/basic.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/basic.ipynb index 7fb3bda2d2d..25b21790d74 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/basic.ipynb +++ b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/basic.ipynb @@ -10,7 +10,7 @@ "\n", "**Note: before running this notebook, you should have**:\n", "\n", - "- Installed PyLabRobot and the USB driver as described in [the installation guide](../../_getting-started/installation).\n", + "- Installed PyLabRobot and the USB driver as described in [the installation guide](../../../_getting-started/installation).\n", "- Connected the Hamilton to your computer using the USB cable.\n", "\n", "Video of what this code does:\n", diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/core-grippers.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/core-grippers.ipynb similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/core-grippers.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/core-grippers.ipynb diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/hamilton-liquid-classes.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/hamilton-liquid-classes.ipynb similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/hamilton-liquid-classes.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/hamilton-liquid-classes.ipynb diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/core-grippers/core-gripper-types.jpg b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/img/core-grippers/core-gripper-types.jpg similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/core-grippers/core-gripper-types.jpg rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/img/core-grippers/core-gripper-types.jpg diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/surface_following/surface_following_distance.svg b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/img/surface_following/surface_following_distance.svg similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/surface_following/surface_following_distance.svg rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/img/surface_following/surface_following_distance.svg diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/core-features/intro.rst b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/intro.rst new file mode 100644 index 00000000000..23f6988f8f0 --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/intro.rst @@ -0,0 +1,14 @@ +Core Features +============= + +Tools for working with Hamilton-STAR specific functions. + +.. toctree:: + :maxdepth: 1 + + Getting Started + Hamilton Liquid Classes + Liquid Level Detection + surface-following + core-grippers + diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/star_lld.md b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/star_lld.md similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/star_lld.md rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/star_lld.md diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/surface-following.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/core-features/surface-following.ipynb similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/surface-following.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/core-features/surface-following.ipynb diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/hardware/index.md b/docs/user_guide/00_liquid-handling/hamilton-star/hardware/index.md index 8a498cfb3aa..49cc46190b5 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/hardware/index.md +++ b/docs/user_guide/00_liquid-handling/hamilton-star/hardware/index.md @@ -1,4 +1,4 @@ -# Hamilton STAR Hardware Guide +# STAR Hardware Guide ```{toctree} :maxdepth: 1 diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/star_old.png b/docs/user_guide/00_liquid-handling/hamilton-star/img/star_old.png new file mode 100644 index 00000000000..2d3a457539f Binary files /dev/null and b/docs/user_guide/00_liquid-handling/hamilton-star/img/star_old.png differ diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/starlet_old.png b/docs/user_guide/00_liquid-handling/hamilton-star/img/starlet_old.png new file mode 100644 index 00000000000..6f873b62079 Binary files /dev/null and b/docs/user_guide/00_liquid-handling/hamilton-star/img/starlet_old.png differ diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/modules/384head.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/modules/384head.ipynb new file mode 100644 index 00000000000..4d46e43255c --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/modules/384head.ipynb @@ -0,0 +1,74 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Using the 384-Head\n", + "\n", + "work in progress\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Background\n", + "\n", + "amazing stuff to come" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Rocket Tips\n", + "\n", + "versatile" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "env", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.2" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/96head.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/modules/96head.ipynb similarity index 82% rename from docs/user_guide/00_liquid-handling/hamilton-star/96head.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/96head.ipynb index fa6809c59b6..7af15992123 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/96head.ipynb +++ b/docs/user_guide/00_liquid-handling/hamilton-star/modules/96head.ipynb @@ -4,21 +4,34 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Using the 96 head\n", + "# Using the 96-Head\n", "\n", - "![star supported](https://img.shields.io/badge/STAR-supported-blue)\n", - "![Vantage supported](https://img.shields.io/badge/Vantage-supported-blue)\n", - "![OT2 not supported](https://img.shields.io/badge/OT-not%20supported-red)\n", - "![EVO not implemented](https://img.shields.io/badge/EVO-not%20implemented-orange)\n", + "| Summary | Image |\n", + "|--------|--------|\n", + "|
  • Feature: CO-RE 96 Probe Head for high-throughput parallel pipetting
  • Variants: stop discs: CO-RE I or CO-RE II; standard or TADM (Total Aspiration and Dispensing Monitoring); Generation: Legacy or Fluid Motion
  • Operation: Simultaneous aspiration and dispensing across 96 wells in standard microplate format
  • Liquid Detection: Capacitive liquid level detection on channels A1-B1 and/or G11-H12
  • Volume Range: 1-1,000µL
  • Workflow Benefit: Dramatic throughput increase, throughput adaptiveness, accelerated tip sorting
|
![96head](img/96head/96head_banner.png)
Figure: Hamilton STAR 96-Head
||" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Background: Architecture of the 96-Head Module\n", "\n", - "Some liquid handling robots have a 96 head, which can be used to pipette 96 samples at once. This notebook shows how to use the 96 head in PyLabRobot." + "The 96-head uses the same tips as the 1000uL channels." ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Example: Hamilton STARLet\n", + "## Setup\n", "\n", "Here, we'll use a Hamilton STARLet as an example. For other robots, simply change the deck layout, making sure that you have at least a tip rack and a plate to use." ] diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/autoload_and_1d_barcode_reader.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/modules/autoload_and_1d_barcode_reader.ipynb similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/autoload_and_1d_barcode_reader.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/autoload_and_1d_barcode_reader.ipynb diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/96head/96head_banner.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/96head/96head_banner.png new file mode 100644 index 00000000000..049f083afb9 Binary files /dev/null and b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/96head/96head_banner.png differ diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/96head/quadrants.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/96head/quadrants.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/96head/quadrants.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/96head/quadrants.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_correct_1d_barcode_height.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_correct_1d_barcode_height.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_correct_1d_barcode_height.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_correct_1d_barcode_height.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_overview.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_overview.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_overview.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_overview.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_state_transfer.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_state_transfer.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_autoload_state_transfer.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_autoload_state_transfer.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_star_autoload.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_star_autoload.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/img/autoload/hamilton_star_autoload.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/autoload/hamilton_star_autoload.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/iswap/iswap_old_banner.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/iswap/iswap_old_banner.png new file mode 100644 index 00000000000..22bde4d241a Binary files /dev/null and b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/iswap/iswap_old_banner.png differ diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/iswap_positions.png b/docs/user_guide/00_liquid-handling/hamilton-star/modules/img/iswap/iswap_positions.png similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/iswap_positions.png rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/img/iswap/iswap_positions.png diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/modules/intro.rst b/docs/user_guide/00_liquid-handling/hamilton-star/modules/intro.rst new file mode 100644 index 00000000000..606aba77ccd --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/modules/intro.rst @@ -0,0 +1,12 @@ +Modules/Extensions +================== + +Tools for working with Hamilton-STAR specific functions. + +.. toctree:: + :maxdepth: 1 + + 96-Head <96head> + 384-Head <384head> + Autoload & Barcode Reader + iSWAP diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap.ipynb new file mode 100644 index 00000000000..1add6a2dc49 --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap.ipynb @@ -0,0 +1,218 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Using the iSWAP\n", + "\n", + "| Summary | Image |\n", + "|--------|--------|\n", + "|
  • Feature: Automated movement of resources on deck, and off-deck (90 mm to the left, 20 mm to the right)
  • Grip Mechanism: Motorized gripper with adjustable grip force and position feedback
  • Workflow Benefit: Enables automated plate stacking, restacking, and movement between instruments without manual intervention
  • Best For: Automated workflows requiring plate transfers, integration with incubators/readers, or dynamic deck management
|
![iswap](img/iswap/iswap_old_banner.png)
Figure: Hamilton STAR iSWAP
|" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Background: Architecture of the iSWAP\n", + "\n", + "The \"internal SWivel Arm Plate handler\" (iSWAP)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pylabrobot.liquid_handling import LiquidHandler, STARBackend\n", + "from pylabrobot.resources import STARDeck\n", + "from pylabrobot.resources import (\n", + " TIP_CAR_480_A00,\n", + " PLT_CAR_L5AC_A00,\n", + " hamilton_96_tiprack_50uL,\n", + " Cor_96_wellplate_360ul_Fb\n", + ")\n", + "\n", + "star = STARBackend()\n", + "lh = LiquidHandler(backend=star, deck=STARDeck())\n", + "await lh.setup()\n", + "\n", + "# assign a tip rack carrier\n", + "tip_carrier = TIP_CAR_480_A00(name=\"tip_carrier\")\n", + "tip_carrier[1] = tip_rack = hamilton_96_tiprack_50uL(name=\"tip_rack\")\n", + "lh.deck.assign_child_resource(tip_carrier, rails=10)\n", + "\n", + "# assign a plate carrier\n", + "plt_carrier = PLT_CAR_L5AC_A00(name=\"plt_carrier\")\n", + "plt_carrier[0] = plate = Cor_96_wellplate_360ul_Fb(name=\"plt\")\n", + "lh.deck.assign_child_resource(plt_carrier, rails=30)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Querying iSWAP state\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "star.iswap_installed" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await star.iswap_installed()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Simple Plate Pickup/Drop" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Slow-move Pickup/Drop" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Manually moving the 96-Head" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await lh.backend.request_position_of_core_96_head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await lh.backend.move_core_96_head_x(100)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## ...for Teaching/Calibrating Pickup-/Drop-Positions" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await lh.backend.move_core_96_head_y(120)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await lh.backend.move_core_96_head_z(300)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Pickup/Drop from a Plate Hotel/Vertical Carrier" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "env", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.2" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/iswap-module.md b/docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap_OLD.md similarity index 99% rename from docs/user_guide/00_liquid-handling/hamilton-star/iswap-module.md rename to docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap_OLD.md index 9562610409d..d5c9688e211 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/iswap-module.md +++ b/docs/user_guide/00_liquid-handling/hamilton-star/modules/iswap_OLD.md @@ -1,4 +1,4 @@ -# iSWAP Module +# iSWAP The `R0` module allows fine grained control of the iSWAP gripper. @@ -38,7 +38,7 @@ You can rotate the iSWAP to 12 predefined positions using {meth}`~pylabrobot.liq the positions and their corresponding integer specifications are shown visually here. -![alt text](iswap_positions.png) +![alt text](./img/iswap/iswap_positions.png) The `iswap_rotate` method can be used to move the wrist drive and the rotation drive simultaneously in one smooth motion. It takes a parameter for the rotation drive, and the final `grip_direction` of the iswap. The `grip_direction` is the same parameter used by {meth}`~pylabrobot.liquid_handling.liquid_handler.LiquidHandler.pick_up_resource` and {meth}`~pylabrobot.liquid_handling.liquid_handler.LiquidHandler.drop_resource`, and is with respect to the deck. This is easier than controlling the rotation drive, which is with respect to the wrist drive. diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/probing/clld-probing.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/probing/clld-probing.ipynb new file mode 100644 index 00000000000..c80364a215c --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/probing/clld-probing.ipynb @@ -0,0 +1,158 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# cLLD-Probing (x/y/z)\n", + "\n", + "With PyLabRobot, \n", + "\n", + "\n", + "```{warning}\n", + "This example uses the teaching tips. These are metal tips that are not forgiving. Be particularly careful when moving the channels around to avoid collisions.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Background" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup\n", + "\n", + "If you are mapping a capacitive surface, you can use the cLLD sensor to detect the surface.\n", + "\n", + "```{warning}\n", + "This example uses the teaching tips. These are metal tips that are not forgiving. Be particularly careful when moving the channels around to avoid collisions.\n", + "```" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "protocol_mode = \"simulation\" # \"execution\" or \"simulation\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pylabrobot.liquid_handling import LiquidHandler, STARBackend\n", + "from pylabrobot.resources import STARDeck\n", + "from pylabrobot.resources import (\n", + " TIP_CAR_480_A00,\n", + " PLT_CAR_L5AC_A00,\n", + " hamilton_96_tiprack_50uL,\n", + " Cor_96_wellplate_360ul_Fb\n", + ")\n", + "\n", + "star = STARBackend()\n", + "lh = LiquidHandler(backend=star, deck=STARDeck())\n", + "await lh.setup()\n", + "\n", + "# assign a tip rack carrier\n", + "tip_carrier = TIP_CAR_480_A00(name=\"tip_carrier\")\n", + "tip_carrier[1] = tip_rack = hamilton_96_tiprack_50uL(name=\"tip_rack\")\n", + "lh.deck.assign_child_resource(tip_carrier, rails=10)\n", + "\n", + "# assign a plate carrier\n", + "plt_carrier = PLT_CAR_L5AC_A00(name=\"plt_carrier\")\n", + "plt_carrier[0] = plate = Cor_96_wellplate_360ul_Fb(name=\"plt\")\n", + "lh.deck.assign_child_resource(plt_carrier, rails=30)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await star.prepare_for_manual_channel_operation(0)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# TODO: change this to a position that works for you\n", + "await star.move_channel_x(0, 500)\n", + "await star.move_channel_y(0, 300)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Use `STARBackend.clld_probe_y_position_using_channel` to probe the y-position of a single point at the current xz plane. This function will slowly move the channel until the liquid level sensor detects a change in capacitance. The y-point of the point of the tip is then returned." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await star.clld_probe_y_position_using_channel(\n", + " channel_idx=0,\n", + " probing_direction=\"forward\",\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await star.clld_probe_y_position_using_channel(\n", + " channel_idx=0,\n", + " probing_direction=\"backward\",\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await lh.return_tips()" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "env", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.15" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/probing/intro.rst b/docs/user_guide/00_liquid-handling/hamilton-star/probing/intro.rst new file mode 100644 index 00000000000..6ec97af874a --- /dev/null +++ b/docs/user_guide/00_liquid-handling/hamilton-star/probing/intro.rst @@ -0,0 +1,11 @@ +Probing +======= + +Tools for working with Hamilton-STAR specific functions. + +.. toctree:: + :maxdepth: 1 + + cLLD-Probing (x/y/z) + Y-Probing + Z-Probing diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/y-probing.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/probing/y-probing.ipynb similarity index 100% rename from docs/user_guide/00_liquid-handling/hamilton-star/y-probing.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/probing/y-probing.ipynb diff --git a/docs/user_guide/00_liquid-handling/hamilton-star/z-probing.ipynb b/docs/user_guide/00_liquid-handling/hamilton-star/probing/z-probing.ipynb similarity index 99% rename from docs/user_guide/00_liquid-handling/hamilton-star/z-probing.ipynb rename to docs/user_guide/00_liquid-handling/hamilton-star/probing/z-probing.ipynb index cc4dc2244dd..517eb4389a7 100644 --- a/docs/user_guide/00_liquid-handling/hamilton-star/z-probing.ipynb +++ b/docs/user_guide/00_liquid-handling/hamilton-star/probing/z-probing.ipynb @@ -86,7 +86,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "For more information on manually moving channels, see [Manually moving channels around](../moving-channels-around.ipynb)." + "For more information on manually moving channels, see [Manually moving channels around](../../moving-channels-around.ipynb)." ] }, { diff --git a/docs/user_guide/machine-agnostic-features/using-the-visualizer.ipynb b/docs/user_guide/machine-agnostic-features/using-the-visualizer.ipynb index 3706e8a1b29..4e7050b6da5 100644 --- a/docs/user_guide/machine-agnostic-features/using-the-visualizer.ipynb +++ b/docs/user_guide/machine-agnostic-features/using-the-visualizer.ipynb @@ -20,7 +20,7 @@ "source": [ "## Setting up a connection with the robot\n", "\n", - "As described in the [basic liquid handling tutorial](../00_liquid-handling/hamilton-star/basic), we will use the {class}`~pylabrobot.liquid_handling.liquid_handler.LiquidHandler` class to control the robot. This time, however, instead of using the Hamilton {class}`~pylabrobot.liquid_handling.backends.hamilton.STAR_backend.STAR` backend, we are using the software-only {class}`~pylabrobot.liquid_handling.backends.chatterbox.ChatterboxBackend` backend. This means that liquid handling will work exactly the same, but commands are simply printed out to the console instead of being sent to a physical robot. We are still using the same deck." + "As described in the [basic liquid handling tutorial](../00_liquid-handling/hamilton-star/core-features/basic), we will use the {class}`~pylabrobot.liquid_handling.liquid_handler.LiquidHandler` class to control the robot. This time, however, instead of using the Hamilton {class}`~pylabrobot.liquid_handling.backends.hamilton.STAR_backend.STAR` backend, we are using the software-only {class}`~pylabrobot.liquid_handling.backends.chatterbox.ChatterboxBackend` backend. This means that liquid handling will work exactly the same, but commands are simply printed out to the console instead of being sent to a physical robot. We are still using the same deck." ] }, { @@ -329,7 +329,7 @@ "source": [ "## Liquid handling\n", "\n", - "Once the layout is complete, you can run the same commands as described in the [basic liquid handling tutorial](../00_liquid-handling/hamilton-star/basic).\n", + "Once the layout is complete, you can run the same commands as described in the [basic liquid handling tutorial](../00_liquid-handling/hamilton-star/core-features/basic).\n", "\n", "It is important that both tip tracking and volume tracking are enabled globally, so that the visualizer can keep track of the state of the tips and the volumes of the liquids." ]