TeCoLab Control Tools

Introduction to Control Tools

TeCoLab offers a collection of Python scripts, called modules, that are designed to simplify the development of classic control algorithms. These modules progressively add new attributes, methods, and functionalities to the Controller class, following the in the structured approach shown in the Structure of Control Modules.

The structure is divided in three layers, each one located in a different folder.

• The base layer, found in TeCoLab/Software/Modules, defines the core TeCoLab Controller class, providing access to data from the TeCoLab board.
• The middle layer, found in TeCoLab/Sofware/Modules/Utils, provides tools like transfer functions to support building control algorithms.
• The top layer consists of your own custom control scripts, which should be saved in TeCoLab/Software/Controllers. These scripts can use modules from the lower layers but are not required to.

Regardless of how much of the toolkit you choose to use, every custom controller must define three essential methods: control_signal(), control_setup(), and control_action().

In the script file of each module, the code structure shown below is followed. The concept is that every script creates a class named Controller, inheriting from the imported Controller class from the previous module. It's crucial for each subsequent script, including your custom ones, to create a class with the identical name (Controller).

from the_previous_module import Controller

class Controller(Controller):
	# Your control algorithm is coded inside this class.

tecolab_controller Module

The tecolab_controller module serves as the fundamental controller class in TeCoLab. Other classes build upon this base to provide additional attributes, methods and functionalities. This module defines the class Controller, which has attributes that receive values from the experiment table during the execution of an experiment, receive values from the sensors of the TeCoLab board or set values as control actions to the heaters and the fan. Next, the specifications of the class Controller defined by this module are given.

• Parameters: None
• Attributes:
  • setpoint_abs_1 (float): Absolute setpoint temperature (in °C) for heater 1, obtained from the experiment file.
  • setpoint_abs_2 (float): Absolute setpoint temperature (in °C) for heater 2, obtained from the experiment file.
  • setpoint_rel_1 (float): Relative setpoint temperature (in °C) for heater 1, obtained from the experiment file.
  • setpoint_rel_2 (float): Relative setpoint temperature (in °C) for heater 2, obtained from the experiment file.
  • temperature_heater_1 (float): Measured temperature (in °C) for heater 1, obtained from the sensors.
  • temperature_heater_2 (float): Measured temperature (in °C) for heater 2, obtained from the sensors.
  • temperature_ambient (float): Measured ambiente temperature (in °C), obtained from the sensors.
  • actuator_heater_1 (float): Control action for heater 1 (in % of maximum power), which will be applied by the TeCoLab software to the board.
  • actuator_heater_2 (float): Control action for heater 2 (in % of maximum power), which will be applied by the TeCoLab software to the board.
  • actuator_fan: Control action for the fan (in % of maximum power), which will be applied by the TeCoLab software to the board.
• Methods:
  • _control_compute(setPoints, temperatures): Used by the TeCoLab to call other methods of the class during the experiment to compute the control actions. As a user, never use this method in your code.

To incorporate this module into your Python script, use the following line of code:

from Modules.tecolab_controller import Controller

periodic_controller Module

The periodic_controller module builds upon the base controller class to facilitate the creation of periodic controllers within TeCoLab. These controllers compute new control actions at regular time intervals, defined by the period attribute signal_period, which is added by this module. The period is given in multiples of the base period of a TeCoLab experiment, which is by default 200 ms. For instance, setting signal_period to 5 results in a control action computed every 5 x 200 ms = 1 s. Next, the specifications of the class Controller defined by this module are given.

• Parameters: None
• Attributes:
  • signal_period (int, default value 1): The period for computing control actions, specified in multiples of the base TeCoLab period.
• Methods:
  • set_signal_period(period): Set the signal_period attribute. It checks if the argument is a number, throwing an error if it is not. Moreover, if the argument is not an integer, it is rounded to the closest integer.
    • Parameters: period (integer): The value to be assigned to the signal_period attribute.
    • Returns: None
  • control_signal(): Computes the periodic control signal to determine whether a new control action should be computed.

To incorporate this module into your Python script, use the following line of code:

from Modules.Utils.periodic_controller import Controller

discrete_time_LTI Module

The discrete_time_LTI module provides the base class for creating controllers based on discrete-time Linear Time Invariant (LTI) systems, such as transfer functions or state space representations. It allows you to create LTI objects using the standard Python control library and store them within the Controller class. Then, you can compute the output of the stored LTI systems based on a given input. Next, the specifications of the class Controller defined by this module are given.

• Parameters: None
• Attributes:
  • discrete_time_LTI_list (list, default value None): The list of internally saved discrete-time LTI systems.
• Methods:
  • set_LTI(system): Store a discrete-time LTI system, which can be created using the TransferFunction or the StateSpace functions from Python standard control library. The method returns an integer representing the index of the stored LTI system, which is used to identify one specific system within the list of stored systems.
    • Parameters: system (LTI): LTI object that can be created using the TransferFunction or the StateSpace functions from Python standard control library.
    • Returns: int: The index that identifies the stored LTI system.
  • get_LTI(index): Get a previously stored discrete-time LTI system based on its index. The method returns the LTI system used for output computation in the state-space representation. Note that this representation is usually different from the original system stored (although equivalent).
    • Parameters: index (int): The index that identifies the stored LTI system.
    • Returns: system (LTI): state space representation of the stored LTI object. This is the representation that the Controller class uses for output computation.
  • LTI_compute(index, u): Computes the output of a previously created and stored LTI system.
    • Parameters: index (int): The index that identifies the stored LTI system; u (float): The input of the LTI system.
    • Returns: Float: The computed output of the LTI system.

To incorporate this module into your Python script, use the following line of code:

from Modules.Utils.discrete_time_LTI import Controller

continuous_time_LTI Module

The continuous_time_LTI module provides the base class for creating controllers based on continuous-time LTI systems within TeCoLab. It allows you to create transfer functions or state space objects which are internally stored and then compute their output based on a given input. Note that, since TeCoLab is a digital plataform, the continuous-time LTI objects are later converted to discrete-time LTI objects in order to compute outputs. In order to have the correct behavior, your custom control algorithm should not change the signal_period attribute, which will be automatically set to 1. Next, the specifications of the class Controller defined by this module are given.

• Parameters: None
• Attributes:
  • discretization_period (float, default value 0.2): Period used in the discretization of the continuous-time LTI systems. To achieve the correct performance, this value must be equal to the TeCoLab iteration period (see Chapter~\ref{chap:AdvancedConfigs} for more information).
  • continuous_time_LTI_list (list, default value None): The list of internally saved continuous-time LTI systems.
• Methods:
  • set_discretization_period(period): Set the discretization period used to convert the continuous-time LTI objects into discrete-time LTI objects. To achieve the correct performance, this value must be equal to the TeCoLab iteration period.
    • parameters: period (float): Period used in the discretization process.
    • Returns: None.
  • set_LTI(system, **kwargs): Store a continuous-time LTI system, which can be created using the TransferFunction or the StateSpace functions from Python standard control library. The method discretizes the continuous-time LTI system, stores it internally and returns an integer representing the index of the stored LTI system, which is used to identify one specific system within the list of stored systems.
    • Parameters: system (LTI): continuous-time LTI object that can be created using the TransferFunction or the StateSpace functions from Python standard control library; **kwargs: The additional arguments of the control.sample_system() function from the standard Python control library.
    • Returns: int: The index that identifies the stored LTI system.
  • get_LTI(index): Get a previously stored continuous-time LTI system and its discretized version based on its index. The method returns the two LTI systems.
    • Parameters: index (int): The index that identifies the stored LTI system.
    • Returns: system (LTI): The original continuous-time LTI object stored; system (LTI): The discretized LTI object. This is the representation used for computing the output of LTI objects.

To incorporate this module into your Python script, use the following line of code:

from Modules.Utils.continuous_time_LTI import Controller

continuous_time_PID Module

The continuous_time_PID module provides the base class for creating continuous-time PID controllers. Next, the specifications of the class Controller defined by this module are given.

• Parameters: None
• Attributes: None
• Methods:
  • set_PID(Kp, Ki, Kd, p, **kwargs):

Creates a continuous-time PID transfer function and internally saves it. The PID format is given by

$$C(s) = K_p\left(1 + \frac{K_i}{s} + sK_d\frac{p}{s+p}\right)$$

  * Parameters: Kp (float): Proportional gain; Ki (float): Integral gain; Kd (float): Derivative gain; p (float, default value 100): Pole for the low-pass filter used to make the derivative part causal; \*\*kwargs: The additional arguments of the **control.sample\_system()** function from the Python control module.
  * Returns: int: The index that identifies the stored LTI system.

To incorporate this module into your Python script, use the following line of code:

from Modules.Utils.continuous_time_PID import Controller