Accessing the Temperature Control Laboratory

Importing tclab

Once installed the package can be imported into Python and an instance created with the Python statements

import tclab
lab = tclab.TCLab()

TCLab provides access to temperature measurements, heaters, and LED on board the Temperature Control Laboratory. When called with no arguments, attempts to find a device connected to a serial port and returns a connection. An error is generated if no device is found. The connection should be closed with

lab.close()

when no longer in use. The following cell demonstrates this process, and uses the tclab LED() function to flash the LED on the Temperature Control Lab for a period of 10 seconds at a 100% brightness level.

!pip install tclab

Collecting tclab
  Downloading https://files.pythonhosted.org/packages/b5/5a/751cc39b1b90c8a8fcce83d8aa498345752effe8a22eead6e4420bacbaac/tclab-0.4.6-py2.py3-none-any.whl
Collecting pyserial (from tclab)
  Downloading https://files.pythonhosted.org/packages/0d/e4/2a744dd9e3be04a0c0907414e2a01a7c88bb3915cbe3c8cc06e209f59c30/pyserial-3.4-py2.py3-none-any.whl (193kB)
    100% |████████████████████████████████| 194kB 4.1MB/s ta 0:00:01
Installing collected packages: pyserial, tclab
Successfully installed pyserial-3.4 tclab-0.4.6

import tclab

lab = tclab.TCLab()
lab.LED(100)
lab.close()

TCLab version 0.4.6
Arduino Leonardo connected on port /dev/cu.usbmodemWUART1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
TCLab disconnected successfully.

A note on terminology

TCLab is a class. We instantiate the class by calling TCLab(). What is returned is an instance of the TCLab class. So in the above code, we would say lab is an instance of TCLab.

Using TCLab with Python’s with statement

The Python with statement provides a simple means of setting up and closing a connection to the Temperature Control Laboratory. The with statement establishes a context where a TCLab instance is created, assigned to a variable, and automatically closed upon completion.

import tclab

with tclab.TCLab() as lab:
    lab.LED(100)

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
TCLab disconnected successfully.

The with statement is likely to be the most common way to connect the Temperature Control Laboratory for most uses.

Reading Temperatures

Once a TCLab instance is created and connected to a device, the temperature sensors on the temperature control lab can be acccessed with the attributes .T1 and .T2. For example, given an instance lab, the temperatures are accessed as

T1 = lab.T1
T2 = a.T2

Note that lab.T1 and lab.T2 are read-only properties. Any attempt to set them to a value will return a Python error.

import tclab

with tclab.TCLab() as lab:
    print("Temperature 1: {0:0.2f} °C".format(lab.T1))
    print("Temperature 2: {0:0.2f} °C".format(lab.T2))

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
Temperature 1: 27.67 °C
Temperature 2: 27.03 °C
TCLab disconnected successfully.

Setting Heaters

The heaters are controlled by functions .Q1() and .Q2() of a TCLab instance. For example, both heaters can be set to 100% power with the functions

lab.Q1(100)
lab.Q2(100)

The device firmware limits the heaters to a range of 0 to 100%. The current value of attributes may be accessed via

Q1 = lab.Q1()
Q2 = lab.Q2()

Note that the retrieved values may be different due to the range-limiting enforced by the device firmware.

Alternatively, the heaters can also be specified with the properties .U1 and .U2. Thus setting

lab.U1 = 100
lab.U2 = 100

would set both heaters to 100% power. The current value of the heaters can be accessed as

print("Current setting of heater 1 is", lab.U1, "%")
print("Current setting of heater 2 is", lab.U2, "%")

The choice to use a function (i.e, .Q1() and .Q2()) or a property (i.e, .U1 or .U2) to set and access heater settings is a matter of user preference.

import tclab
import time

with tclab.TCLab() as lab:
    print("\nStarting Temperature 1: {0:0.2f} °C".format(lab.T1),flush=True)
    print("Starting Temperature 2: {0:0.2f} °C".format(lab.T2),flush=True)

    lab.Q1(100)
    lab.Q2(100)
    print("\nSet Heater 1:", lab.Q1(), "%",flush=True)
    print("Set Heater 2:", lab.Q2(), "%",flush=True)

    t_heat = 20
    print("\nHeat for", t_heat, "seconds")
    time.sleep(t_heat)

    print("\nTurn Heaters Off")
    lab.Q1(0)
    lab.Q2(0)
    print("\nSet Heater 1:", lab.Q1(), "%",flush=True)
    print("Set Heater 2:", lab.Q2(), "%",flush=True)

    print("\nFinal Temperature 1: {0:0.2f} °C".format(lab.T1))
    print("Final Temperature 2: {0:0.2f} °C".format(lab.T2))

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.

Starting Temperature 1: 27.67 °C
Starting Temperature 2: 27.03 °C

Set Heater 1: 100.0 %
Set Heater 2: 100.0 %

Heat for 20 seconds

Turn Heaters Off

Set Heater 1: 0.0 %
Set Heater 2: 0.0 %

Final Temperature 1: 28.96 °C
Final Temperature 2: 29.29 °C
TCLab disconnected successfully.

Setting Maximum Heater Power

The control inputs to the heaters power is normally set with functions .Q1() and .Q2() (or properties .U1 and .U2) specifying a value in a range from 0 to 100% of maximum heater power.

The values of maximum heater power are specified in firmware with values in the range from 0 to 255. The default values are 200 for heater 1 and 100 for heater 2. The maximum heater power can be retrieved and set by properties P1 and P2. The following code, for example, sets both heaters to a maximum power of 100.

import tclab

with tclab.TCLab() as lab:
    print("Maximum power of heater 1 = ", lab.P1)
    print("Maximum power of heater 2 = ", lab.P2)

    print("Adjusting the maximum power of heater 1.")
    lab.P1 = 100

    print("Maximum power of heater 1 = ", lab.P1)
    print("Maximum power of heater 2 = ", lab.P2)

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
Maximum power of heater 1 =  200.0
Maximum power of heater 2 =  100.0
Adjusting the maximum power of heater 1.
Maximum power of heater 1 =  100.0
Maximum power of heater 2 =  100.0
TCLab disconnected successfully.

The actual power supplied to the heaters is a function of the power supply voltage applied to the Temperature Control Lab shield,

The maximum power applied to the heaters is a product of the settings (P1,P2) and of the power supply used with the TCLab hardware. The TCLab hardware is normally used with a 5 watt USB power supply capable of supply up to 1 amp at 5 volts.

The TCLab hardware actually draws more than 1 amp when both P1 and P2 are set to 255 and Q1 and Q2 are at 100%. This situation will overload the power supply and result in the power supply shutting down. Normally the power supply will reset itself after unplugging from the power mains.

Experience with the device shows keeping the sum P1 and P2 to a value less than 300 will avoid problems with the 5 watt power supply. If you have access to larger power supplies, then you can adjust P1 and P2 accordingly to achieve a wider range of temperatures.

tclab Sampling Speed

There are limits to how quickly the board can be sampled. The following examples show values for a particular type of board. You can run them to see how quick your board is.

Temperature Sampling Speed

import time
import tclab

TCLab = tclab.setup(connected=True)

N = 100
meas = []
with TCLab() as lab:
    tic = time.time()
    for k in range(0,N):
        meas.append(lab.T1)
    toc = time.time()

print('Reading temperature at', round(N/(toc-tic),1), 'samples per second.')

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
TCLab disconnected successfully.
Reading temperature at 12.3 samples per second.

Heater Sampling Speed

import time
import tclab

TCLab = tclab.setup(connected=True)

N = 100
with TCLab() as lab:
    tic = time.time()
    for k in range(0,N):
        lab.Q1(100)
    toc = time.time()

print('Setting heater at', round(N/(toc-tic),1), 'samples per second.')

Arduino Leonardo connected on port /dev/cu.usbmodemWUAR1 at 115200 baud.
TCLab Firmware 1.3.0 Arduino Leonardo/Micro.
TCLab disconnected successfully.
Setting heater at 8.2 samples per second.