Docs Update: Hamilton HEPA Fan (old) (#664)

Author: BioCam

docs/user_guide/01_material-handling/fans/fans.ipynb

@@ -0,0 +1,23 @@
+# Fans (Air Filtration Systems)
+
+In PyLabRobot, fans refer to air filtration units that condition air within or around the deck to protect the sample from contamination.
+
+Their main purpose is to maintain a clean environment for experiments by ensuring consistent airflow and particle removal, reducing risks from dust, aerosols, and microorganisms.
+These systems are not primarily designed for operator safety; separate equipment like fume extractors or biosafety cabinets serves that role.
+
+Common filter technologies include:
+
+- **HEPA filters**: Capture ≥99.97% of airborne particles ≥0.3 µm, widely used to keep samples clean.
+
+- **ULPA filters**: Capture even smaller particles for higher-level cleanroom requirements.
+
+- **Activated carbon filters**: Remove volatile organic compounds (VOCs) and chemical fumes.
+
+- **Prefilters**: Trap larger particles to extend the lifespan of HEPA/ULPA filters.
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+hamilton_hepa_scap
+```

docs/user_guide/01_material-handling/fans/fans.md

@@ -0,0 +1,121 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Hamilton HEPA Fan\n",
+    "\n",
+    "| Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Photo                                            |\n",
+    "|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|\n",
+    "| - OEM Link (none exists?)<br>- **Communication Protocol / Hardware**: Serial (FTDI)/ USB-A<br>- **Communication Level**: Firmware<br>- Old HEPA CAP discontinued in 2020, replaced with Clean Air Protection (CAP) Fan (Hamilton cat. no.: 92173-22)<br>- Old HEPA CAP VID:PID 0856:ac11 \"USOPTL4\"<br>- Adds 321 mm to height of STAR(let)<br>- Takes in ambient air, filters it and supplies it to the inside of the STAR(let) | ![quadrants](img/hamilton-old-hepa-cap.png) |"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Setup Instructions (Physical)\n",
+    "\n",
+    "The Hamilton HEPA Fan for a STAR or STARlet liquid handling workstation has to be placed on top of the machines chassis.\n",
+    "\n",
+    "It requires two cable connections to be operational:\n",
+    "1. Power cord (standard IEC C13); if you are using an older HEPA Fan model ensure that the voltage switch is set to your country's mains voltage!\n",
+    "2. USB cable (USB-B with at fan end; USB-A at control PC end)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "## Setup Instructions (Programmatic)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pylabrobot.only_fans import Fan\n",
+    "from pylabrobot.only_fans import HamiltonHepaFanBackend"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fan = Fan(backend=HamiltonHepaFanBackend()) \n",
+    "# NB.: fans are only machines, they are not modelled as resources -> require no str name\n",
+    "\n",
+    "await fan.setup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "## Usage / Machine Features"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Running for 60 seconds:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await fan.turn_on(intensity=100, duration=30)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Running until stop:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await fan.turn_on(intensity=100)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "await fan.turn_off()"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}