Getting Started

What is TeCoLab?

TeCoLab (Temperature Control Laboratory) is an open-source tool comprising hardware, firmware and software, designed for experimenting with temperature control algorithms. Before delving into the details, let's embark on a step-by-step tutorial to implement a discrete-time PI (Proportional-Integral) controller with period of 1 second. Our objective is to regulate the temperature of Heater 1 to 15 °C above room temperature.

What do I need to run TeCoLab?

HARDWARE:

• TeCoLab hardware: You can assemble your own TeCoLab using the files and information available on our GitHub repository;
• Arduino Nano: The microcontroller used in this project;
• USB-B cable: The standard communication cable for the Arduino;
• 12 V DC power supply: A 12 V DC power supply with at least 2 A current capacity. Connect the power supply to jack J1 (with positive in the middle) or the bornier terminal J2.

SOFTWARE:

• TeCoLab files: Download from our GitHub repository;
• Python 3: Used to execute the TeCoLab program;
• Python 3 dependencies: Python modules described in the file requirements.txt;
• Arduino software: Required for loading the firmware to your Arduino (you will only need to perform this once);
• Spreadsheet editor: A spreadsheet editor, such as LibreOffice Calc, will be useful.

Downloading TeCoLab

To obtain TeCoLab, follow these steps:

• Visit the TeCoLab GitHub repository, click on Code and select Download ZIP;
• Unzip the downloaded content;
• Voilà! TeCoLab is now on your computer.

Programming your Arduino

In the folder TeCoLab/Firmware you'll find the firmware project named Firmware.ino. Follow these steps to program your Arduino:

• Open the Firmware.ino project using the Arduino software;
• Load the firmware into your Arduino. \end{enumerate}

No changes are needed in the firmware. This procedure is a one-time procedure.

Important files of TeCoLab

Three files are crucial in TeCoLab:

• Experiment File: A .csv file located in TeCoLab/Software/Experiments. In this file, you will define your experiment, including setpoints of temperature, desired disturbances, etc.;
• Control File: A .py file located in TeCoLab/Software/Controllers. In this file, you will define the control algorithm you want to test during the experiment;
• Log File: A .csv file. After defining the experiment and control files, you can execute an experiment. TeCoLab will record the data, such as the temperature evolution, in a log file saved at TeCoLab/Software/Logs.

Creating your experiment

Let's create our first experiment, aiming to regulate the temperature of Heater 1 to 15 °C above the ambient temperature.

1. Navigate to TeCoLab/Software/Experiments.
2. Copy the file Template.csv and rename it to MyFirstExperiment.csv.
3. Open the file. Although the header (first row) contains various fields, we will focus on only two: TIME (first column) and SP1_REL (fourth column).
4. Edit your file to resemble the table below. It will end with only three rows (besides the header). Do not fill in any other fields besides those specified in the example.

TIME	SP1_ABS	SP2_ABS	SP1_REL	SP2_REL	...
0			0		...
5000			15		...
900000			0		...

In the experiment file, the TIME column specifies the time (in ms) when the signals of the other columns will be applied to the experiment. The SP1_REL column specifies the relative temperature setpoint, that is, the temperature difference with respect to the ambient temperature (given in °C).

This proposed experiment file describes the following experiment: at time 0 (TIME = 0 ms), the relative setpoint is 0 °C (SP1_REL = 0 °C) for Heater 1, indicating no desired temperature change. At 5 seconds (TIME = 5000 ms), the relative setpoint for Heater 1 is set to 15 °C (SP1_REL = 15 °C). This value will be accessed by your control algorithm code to compute a control action for changing the temperature of Heater 1. The experiment concludes at 15 minutes (TIME = 900000 ms). Remember: for now, no changes are needed in any other columns not mentioned in this example.

Creating your controller

Let's create our first controller to implement a discrete-time transfer function with a period of 1 second.

1. Navigate to TeCoLab/Software/Controllers, copy the file Template.py, and rename it to MyFirstController.py.
2. Edit this file as shown in the following example:

from Modules.Utils.discrete_time_LTI import Controller
import control

class Controller(Controller):
	def __init__(self):
		super().__init__()

	def control_setup(self):
		self.set_signal_period(5)
		tf = control.tf([1, -0.95], [1, -1], True)
		self.index = self.set_LTI(tf)

	def control_action(self):
		temp = self.temperature_heater_1 - self.temperature_ambient
		error = self.setpoint_rel_1 - temp
		self.actuator_heater_1 = self.LTI_compute(self.index, error)

The first line imports tools from the TeCoLab discrete-time LTI (Linear Time Invariant) module, providing easier transfer function usage and access to experiment variables such as temperature sensor measurements and applied heater power. The second line imports the standard Python control library, which will be used to create our controller from the desired discrete-time transfer function. Moreover, in the initialization of our Controller class, we initialize the parent class, which sets the parents attributes to their default values.

The control_setup() method is created in this file and will be called once by the TeCoLab software at the beginning of your experiment to configure your controller. It sets the attribute signal_period to 5 (this attribute is defined by a TeCoLab module). This means that your control algorithm will compute a new control action every five iterations of the TeCoLab experiment. Since, by default, each experiment iteration occurs every 200 ms, the controller period is 5 x 200 ms = 1 second. We also create the variable tf, defined as the discrete-time transfer function

$$C(z) = \frac{z - 0.95}{z - 1}$$

by specifying the numerator and denominator of this transfer function.

The control_action() method is created to implement the control action computation. We created a temp variable, representing the difference between Heater 1's temperature and the ambient temperature. The second line computes the error. Then we compute the control action using the created transfer function and the error as its input, applying it to Heater 1's related output power variable. TeCoLab will have access to attributes like actuator_heater_1 and will apply them to the physical board. Note that the actuator values (that is, heater 1, heater 2 and fan output power) can range from 0 to 100, representing percentages of the maximum power. However, you need not worry about this in your controller algorithm, as the TeCoLab software handles the adjustment of these values before sending them to the physical board.

Configuring a Python environment

Before executing your TeCoLab experiment, you need to configure a Python virtual environment. Open a terminal, navigate to the folder containing TeCoLab.py, and run the following command:

python -m venv TCLenv

This will create a folder named TCLenv (short for TeCoLab environment), which allows you to manage project-specific dependencies without affecting your global Python setup. Once the environment is created, activate it with the appropriate command for your operating system:

LINUX

source TCLenv/bin/activate

WINDOWS

TCLenv\Scripts\activate

After activation, your terminal prompt should change to indicate that the environment is active. Finally, you can install the required packages using the following command:

pip install -r requirements.txt

Executing the Experiment

It's time to execute your experiment. Navigate to TeCoLab/Software. Open the terminal and type the following command:

python tecolab.py MyFirstExperiment MyFirstController

Now, you will have to wait a little bit since your experiment runs for 15 minutes. The blinking green LED will become fully on, indicating communication between your computer and TeCoLab. At some point, the red LED can start to blink, indicating that the heater elements are becoming warm. This is expected behavior. You will know that your experiment has finished when the green LED starts to blink again. If you experience any problem, check the FAQ page.

Checking the log file

When your experiment is complete, TeCoLab will save a log file in TeCoLab/Software/Logs. This file has the extension .csv and its name will be the date and time of the experiment execution.

Experiment's Log Figure

The log file includes all the columns from the experiment file, along with additional columns providing information about the experiment's execution. You can find the meanings of all columns in the Log File page. Currently, three columns are crucial: TIME, H1_TEMP and H1_C_PWM. These represent the time elapsed in the experiment (in ms), the temperature of Heater 1 (in °C) and the computed power for Heater 1 (in % of maximal power), respectively. These three columns are graphically summarized in the Experiment's Log Figure. In the upper sub-figure, the green line represents the ambient temperature, the cyan line is the setpoint (15 °C above ambient temperature) and the blue line is the temperature of Heater 1. In the lower sub-figure, the blue line indicates the computed power for Heater 1.

What's next?

How can we enhance the results depicted in the Experiment's Log Figure? We could think about reducing the settling time (which was approximately 11 minutes in this experiment), eliminating overshoot (which was approximately 50% in this experiment) or minimizing the energy expended by the controller to reach the reference temperature. Additionally, we could explore the behavior of our controller in the presence of disturbances in the computed control action, or subject to a more restricted saturation range or a limitation on the rate of change of the control action. TeCoLab provides a platform for delving into these aspects and experimenting with various configurations.