Skip to content

Commit f48aa99

Browse files
BioCamBioCam
authored
Update Temperature Controller Docs (#641)
1 parent bd3bdac commit f48aa99

File tree

8 files changed

+301
-23
lines changed

8 files changed

+301
-23
lines changed

‎docs/contributor_guide/new-concrete-backend.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,7 @@
22

33
This guide explains how to add support for a new machine of an existing type. For example, if you want to add support for a new liquid handler, you should read this guide. If you want to add support for a new type of machine, you should read {doc}`this guide <new-machine-type>` first.
44

5-
The machine types that are currently supported are:
6-
7-
- [Liquid handlers](/user_guide/00_liquid-handling/hamilton-star/basic)
8-
- [Plate readers](/user_guide/02_analytical/plate-reading/plate-reading)
9-
- [Pumps](/user_guide/00_liquid-handling/pumps/_pumps)
10-
- [Temperature controllers](/user_guide/01_material-handling/temperature)
11-
- [Heater shakers](/user_guide/01_material-handling/heating_shaking/heating_shaking)
5+
The machine types that are currently can be found [here](/user_guide/machines).
126

137
Two documents that you can read before you start are:
148

‎docs/contributor_guide/new-machine-type.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,6 @@
11
# Contributing a new type of machine to PLR
22

3-
PyLabRobot supports a number of different types of machines. Currently, these are:
4-
5-
- [Liquid handlers](/user_guide/00_liquid-handling/hamilton-star/basic)
6-
- [Plate readers](/user_guide/02_analytical/plate-reading/plate-reading)
7-
- [Pumps](/user_guide/00_liquid-handling/pumps/_pumps)
8-
- [Temperature controllers](/user_guide/01_material-handling/temperature)
9-
- [Heater shakers](/user_guide/01_material-handling/heating_shaking/heating_shaking)
3+
PyLabRobot supports a number of different types of machines. They can be found [here](/user_guide/machines).
104

115
If you want to add support for a new type of machine, this guide will explain the process. If you want to add a new machine for a type that already exists, you should read {doc}`this guide <new-concrete-backend>` instead.
126

‎docs/user_guide/01_material-handling/_material-handling.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ This includes machines for temperature and motion control (as neither machines p
1515
centrifuge/_centrifuge
1616
heating_shaking/heating_shaking
1717
fans/fans
18-
temperature
1918
sealers/sealers
19+
temperature-controllers/temperature-controllers
2020
storage/storage
2121
tilting
2222
thermocycling/thermocycling

‎docs/user_guide/01_material-handling/temperature-controllers/hamilton-heater-cooler.ipynb‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "18708b66",
6+
"metadata": {},
7+
"source": [
8+
"\n",
9+
"# Hamilton Heater Cooler (HHC)\n",
10+
"\n",
11+
"| Summary | Photo |\n",
12+
"|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|\n",
13+
"| - [OEM Link](https://www.hamiltoncompany.com/temperature-control/hamilton-heater-cooler)<br>- **Communication Protocol / Hardware**: ? / ?<br>- **Communication Level**: Firmware <br><br>- **Temperature range**: 0 to 110°C<br> | ![quadrants](img/hamilton_heater_cooler.png) |\n"
14+
]
15+
},
16+
{
17+
"cell_type": "markdown",
18+
"id": "a73f89dd",
19+
"metadata": {},
20+
"source": [
21+
"---\n",
22+
"## Setup Instructions (Physical)\n",
23+
"\n",
24+
"WIP"
25+
]
26+
},
27+
{
28+
"cell_type": "markdown",
29+
"id": "adb29364",
30+
"metadata": {},
31+
"source": [
32+
"---\n",
33+
"## Setup Instructions (Programmatic)\n",
34+
"\n",
35+
"WIP"
36+
]
37+
},
38+
{
39+
"cell_type": "code",
40+
"execution_count": null,
41+
"id": "34531f2c",
42+
"metadata": {},
43+
"outputs": [],
44+
"source": [
45+
"%load_ext autoreload\n",
46+
"%autoreload 2"
47+
]
48+
},
49+
{
50+
"cell_type": "code",
51+
"execution_count": null,
52+
"id": "30720acb",
53+
"metadata": {},
54+
"outputs": [],
55+
"source": [
56+
"await hhc.setup()"
57+
]
58+
},
59+
{
60+
"cell_type": "markdown",
61+
"id": "7d2e9ed2",
62+
"metadata": {},
63+
"source": [
64+
"---\n",
65+
"\n",
66+
"## Usage\n",
67+
"\n",
68+
"### Temperature control\n",
69+
"\n",
70+
"WIP"
71+
]
72+
},
73+
{
74+
"cell_type": "code",
75+
"execution_count": null,
76+
"id": "97dbe69e",
77+
"metadata": {},
78+
"outputs": [],
79+
"source": [
80+
"await hhc.set_temperature(70)"
81+
]
82+
},
83+
{
84+
"cell_type": "code",
85+
"execution_count": null,
86+
"id": "0004d35d",
87+
"metadata": {},
88+
"outputs": [],
89+
"source": [
90+
"await hhc.wait_for_temperature()"
91+
]
92+
},
93+
{
94+
"cell_type": "code",
95+
"execution_count": null,
96+
"id": "bb2de16b",
97+
"metadata": {},
98+
"outputs": [],
99+
"source": [
100+
"await hhc.get_temperature()"
101+
]
102+
},
103+
{
104+
"cell_type": "code",
105+
"execution_count": null,
106+
"id": "4e9e17d7",
107+
"metadata": {},
108+
"outputs": [],
109+
"source": [
110+
"await hhc.deactivate()"
111+
]
112+
}
113+
],
114+
"metadata": {
115+
"kernelspec": {
116+
"display_name": "env (3.10.15)",
117+
"language": "python",
118+
"name": "python3"
119+
},
120+
"language_info": {
121+
"codemirror_mode": {
122+
"name": "ipython",
123+
"version": 3
124+
},
125+
"file_extension": ".py",
126+
"mimetype": "text/x-python",
127+
"name": "python",
128+
"nbconvert_exporter": "python",
129+
"pygments_lexer": "ipython3",
130+
"version": "3.10.15"
131+
}
132+
},
133+
"nbformat": 4,
134+
"nbformat_minor": 5
135+
}

‎docs/user_guide/01_material-handling/temperature-controllers/img/hamilton_heater_cooler.png‎

279 KB
Loading

‎docs/user_guide/01_material-handling/temperature-controllers/img/ot_temperature_module_gen2.webp‎

9.96 KB
Loading

‎docs/user_guide/01_material-handling/temperature.ipynb‎ renamed to ‎docs/user_guide/01_material-handling/temperature-controllers/ot-temperature-controller.ipynb‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,31 @@
44
"cell_type": "markdown",
55
"metadata": {},
66
"source": [
7-
"# Temperature controllers (heaters and coolers)\n",
7+
"# Opentrons Temperature Module\n",
88
"\n",
9-
"PyLabRobot supports the following temperature controllers:\n",
10-
"\n",
11-
"- Opentrons Temperature Module V2\n",
12-
"\n",
13-
"Temperature controllers are controlled by the {class}`~pylabrobot.temperature_controlling.temperature_controller.TemperatureController` class. This class takes a backend as an argument. The backend is responsible for communicating with the scale and is specific to the hardware being used.\n",
9+
"| Summary | Photo |\n",
10+
"|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|\n",
11+
"| - [OEM Link](https://opentrons.com/products/temperature-module-gen2?sku=991-00350-0)<br>- **Communication Protocol / Hardware**: ? / USB-A (currently only supported via direct connection into OT-2)<br>- **Communication Level**: ?<br><br>- **OEM version**: GEN2<br>- **Temperature range**: 4 to 95°C<br> | ![quadrants](img/ot_temperature_module_gen2.webp) |\n",
12+
"\n"
13+
]
14+
},
15+
{
16+
"cell_type": "markdown",
17+
"metadata": {},
18+
"source": [
19+
"---\n",
20+
"## Setup Instructions (Physical)\n",
1421
"\n",
15-
"The {class}`~pylabrobot.temperature_controlling.opentrons.OpentronsTemperatureModuleV2` is a TemperatureController subclass initialized with a tube rack."
22+
"WIP"
23+
]
24+
},
25+
{
26+
"cell_type": "markdown",
27+
"metadata": {},
28+
"source": [
29+
"---\n",
30+
"## Setup Instructions (Programmatic)\n",
31+
"\n"
1632
]
1733
},
1834
{
@@ -148,6 +164,17 @@
148164
"lh.deck.assign_child_at_slot(t, slot=3)"
149165
]
150166
},
167+
{
168+
"cell_type": "markdown",
169+
"metadata": {},
170+
"source": [
171+
"---\n",
172+
"\n",
173+
"## Usage\n",
174+
"\n",
175+
"### Temperature control"
176+
]
177+
},
151178
{
152179
"cell_type": "markdown",
153180
"metadata": {},
@@ -227,7 +254,7 @@
227254
"cell_type": "markdown",
228255
"metadata": {},
229256
"source": [
230-
"## Pipetting from the OT-2 temperature module"
257+
"### Pipetting from the OT-2 temperature module"
231258
]
232259
},
233260
{

‎docs/user_guide/01_material-handling/temperature-controllers/temperature-controllers.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
Temperature Controllers
2+
=======================
3+
4+
Temperature controllers are defined as **machines with one or both** of these **features**:
5+
6+
- `heating`
7+
- `actively cooling`
8+
9+
a **material** or **enclosed volume** from a room-temperature baseline (≈20-25°C).
10+
11+
Based on this definition machines that include temperature control, but are not primarily temperature controllers, should build on top of the `TemperatureController` definition.
12+
13+
These multi-functional machines can be described as "composite machines".
14+
Examples of such machines include:
15+
16+
- Heater shakers: `shake` + `heat` (e.g. Inheco Thermoshake)
17+
- qPCR machines: `measure fluorescence` + `heat` + `cool` (e.g. Thermo Fisher Scientific QuantStudio 5)
18+
- Smart storage machines: `store` + `heat` + (`cool`) (e.g. Thermo Fisher Scientific Cytomats)
19+
20+
Temperature Controller machines can be implemented with a variety of heating/cooling technologies suited to different workflows.
21+
22+
------------------------------------------
23+
24+
Actuation technologies
25+
----------------------
26+
27+
Multiple technologies can be used to implement temperature control, each with its own advantages and limitations.
28+
The two most common types are:
29+
30+
1. **Thermoelectric (Peltier) modules**
31+
are solid-state devices that pump heat via the Peltier effect, enabling both heating and cooling by reversing current flow.
32+
Compact and modular, they mount directly on robotic decks.
33+
34+
*Examples:*
35+
36+
- Inheco Cold Plate Air Cooled (CPAC) Heater/Cooler (not yet supported in PLR)
37+
- Hamilton Heater Cooler (HHC)
38+
- Opentrons Temperature Module GEN2
39+
40+
- **Pros:** Bidirectional control; fast response; minimal footprint
41+
- **Cons:** Limited ΔT from ambient (±65°C max); efficiency drops near extremes; requires heatsinking/ventilation
42+
43+
2. **Liquid-circulation systems**
44+
use external chillers or heaters to pump fluid (water or glycol) through channels around a sample block, delivering uniform, stable temperatures well below and above ambient.
45+
46+
*Examples:*
47+
48+
- Inheco Cold Plate Liquid Cooled (CPLC) Heater/Cooler (not yet supported in PLR)
49+
50+
- **Pros:** Broad temperature range; excellent uniformity; precise PID control
51+
- **Cons:** Bulky; requires plumbing and space; higher cost
52+
53+
------------------------------------------
54+
55+
Implementation
56+
--------------
57+
58+
Backend
59+
^^^^^^^
60+
61+
PyLabRobot programmatically defines Temperature Controller machines based on the :class:`~pylabrobot.temperature_controlling.temperature_controller.TemperatureController` base class.
62+
63+
e.g.:
64+
65+
.. code-block:: python
66+
67+
from pylabrobot.temperature_controlling.temperature_controller import (
68+
TemperatureControllerBackend
69+
)
70+
71+
hhc_backend = HamiltonHeaterCoolerBackend(device_address="/dev/ttyUSB0")
72+
73+
Resource Model
74+
^^^^^^^^^^^^^^
75+
76+
Physically speaking, PLR models most standalone temperature controllers as either `ResourceHolder` or `PlateHolder` objects.
77+
I.e. these machines have physical dimensions and can hold plates or other resources in a specified `child_location`.
78+
79+
e.g.:
80+
81+
.. code-block:: python
82+
83+
def Hamilton_heater_cooler_resource(name: str) -> PlateHolder:
84+
"""
85+
Hamilton cat. no.: 6601900-01
86+
"""
87+
return PlateHolder(
88+
name=name,
89+
size_x=145.5,
90+
size_y=104.0,
91+
size_z=67.8,
92+
child_location=Coordinate(11.5, 8.0, 67.8),
93+
model="hamilton_heater_cooler",
94+
pedestal_size_z=0,
95+
)
96+
97+
hhc_resource_model = Hamilton_heater_cooler_resource(
98+
name="Hamilton Heater Cooler no1"
99+
)
100+
101+
Frontend
102+
^^^^^^^^
103+
104+
The frontend then enables fast and user-friendly access to the temperature controller's functionality and storing of complete machine interfaces using familiar names.
105+
106+
e.g.:
107+
108+
.. code-block:: python
109+
110+
Hamilton_heater_cooler = TemperatureController(
111+
backend=hhc_backend,
112+
resource_model=hhc_resource_model
113+
)
114+
115+
116+
# Action command:
117+
Hamilton_heater_cooler.set_temperature(37)
118+
119+
# Read command:
120+
current = Hamilton_heater_cooler.get_temperature()
121+
122+
123+
.. toctree::
124+
:maxdepth: 1
125+
:hidden:
126+
127+
ot-temperature-controller
128+
hamilton-heater-cooler

0 commit comments

Comments
 (0)