Restructuring and updates to STAR Documentation

docs/conf.py

@@ -42,6 +42,7 @@
   "IPython.sphinxext.ipython_console_highlighting",
   "sphinx_reredirects",
   "sphinx_sitemap",
+  "sphinx_tabs.tabs"
 ]
 
 intersphinx_mapping = {

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:
 
 <iframe width="720" height="405" src="https://www.youtube.com/embed/_uPf9hyTBog" title="YouTube video player" frameborder="0" allow="autoplay; encrypted-media; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 

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 <https://www.hamiltoncompany.com/automated-liquid-handling/platforms/microlab-star>`_
+             * **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 <https://www.hamiltoncompany.com/automated-liquid-handling/platforms/microlab-starlet>`_
+             * **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
+

docs/user_guide/00_liquid-handling/hamilton-star/basic.ipynb → 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",

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 <basic>
+   Hamilton Liquid Classes <hamilton-liquid-classes>
+   Liquid Level Detection <star_lld>
+   surface-following
+   core-grippers
+

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

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
+}

docs/user_guide/00_liquid-handling/hamilton-star/96head.ipynb → 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",
+    "| <ul style=\"font-size:15px; line-height:1.6; margin-top:0;\"><li><b>Feature:</b> CO-RE 96 Probe Head for high-throughput parallel pipetting</li><li><b>Variants:</b> stop discs: CO-RE I or CO-RE II; standard or TADM (Total Aspiration and Dispensing Monitoring); Generation: Legacy or Fluid Motion</li><li><b>Operation:</b> Simultaneous aspiration and dispensing across 96 wells in standard microplate format</li><li><b>Liquid Detection:</b> Capacitive liquid level detection on channels A1-B1 and/or G11-H12</li><li><b>Volume Range:</b> 1-1,000µL</li><li><b>Workflow Benefit:</b> Dramatic throughput increase, throughput adaptiveness, accelerated tip sorting</li></ul> | <div style=\"width:320px; text-align:center;\">![96head](img/96head/96head_banner.png)<br><i>Figure: Hamilton STAR 96-Head</i></div> ||"
+   ]
+  },
+  {
+   "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."
    ]

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 <autoload_and_1d_barcode_reader>
+   iSWAP <iswap>