minute read

On this API page:

Controller Variables

You are reading our Automation1 API documentation for the Python™ programming language.

The Basics

In the Python API, Controller Variables lets you get and set controller global variables, controller task variables on a task, and the values of Industrial Ethernet mappings on an Automation1 controller. Refer to the sections that follow for more information.

Global Variables

In the Python API, Global Variables lets you get and set global variables on an Automation1 controller. You can access controller global variables from all tasks on the controller. This makes the variables useful when you share information between tasks or between the controller and your custom application.

There are three types of global variables:

  • Global integer array ($iglobal in AeroScript)
  • Global real array ($rglobal in AeroScript)
  • Global string array ($sglobal in AeroScript)

AeroScript integers are 64-bit signed integers. They are represented in Python by the int data type. AeroScript reals are double-precision floating-point numbers. They are represented in Python by the float data type.

The strings in the AeroScript global-string array have a maximum length of 255 bytes. ASCII characters consume one byte. But the use of multi-byte characters, such as Unicode characters, results in multiple bytes of the string being consumed for individual characters.

How to Use

In the Python API, Global Variables is part of the Controller.runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with global variables. For more information about this property, see the Controller page. The methods and properties that you use to work with global variables exist under the Controller.runtime.variables.global_ property. This property is suffixed with an underscore because “global” is a reserved word in the Python language.

You can get a single global variable. Use one of the methods that follow:

Copy 
global_integer = controller.runtime.variables.global_.get_integer(global_int_index)
global_real = controller.runtime.variables.global_.get_real(global_real_index)
global_string = controller.runtime.variables.global_.get_string(global_string_index)

You can also get two or more global variables at the same time from the same contiguous segment in the global variable array. Use one of the methods that follow:

Copy 
global_integers = controller.runtime.variables.global_.get_integers(starting_global_real_index, number_of_ints)
global_reals = controller.runtime.variables.global_.get_reals(starting_global_real_index, number_of_reals)

Task Variables

In the Python API, Task Variables let you get and set task variables on a task on an Automation1 controller. You can access task variables from AeroScript and every API but only from the same task. You can use task variables to share information between iterations of a program running on the same task.

There are three types of task variables, and every task on an Automation1 controller has a set of these task variable arrays: 

  • Task integer array ($itask in AeroScript)

  • Task real array ($rtask in AeroScript)

  • Task string array ($stask in AeroScript)

AeroScript integers are 64-bit.They are represented by the int data type. AeroScript reals are double-precision floating points. They are represented by the float data type.

The strings in an AeroScript task string array have a maximum length of 255 bytes. ASCII characters use just one byte. But, multi-byte characters, such as Unicode characters, use multiple bytes of the string.

The TaskIntegers Parameter, TaskReals Parameter, and TaskStrings Parameter specify the number of variables that are available to the task for which this parameter is set.

How to Use

In the Python API, Task Variables is part of the Controller.runtime property. The Automation1 controller must be running before you can do work with task variables. Refer to Controller for more information.

You can get and set a single task variable with one of the methods that follow.

Copy 
integer_value = controller.runtime.variables.task.get_integer(task_name_or_index, task_int_array_index)
real_value = controller.runtime.variables.task.get_real(task_name_or_index, task_real_array_index)
string_value = controller.runtime.variables.task.get_string(task_name_or_index, task_string_array_index)

controller.runtime.variables.task.set_integer(task_name_or_index, task_int_array_index, integer_value)
controller.runtime.variables.task.set_real(task_name_or_index, task_real_array_index, real_value)
controller.runtime.variables.task.set_string(task_name_or_index, task_string_array_index, string_value)

You can also get and set a contiguous segment of values in the integer and real task variable arrays using the methods that follow.

Copy 
int_values = controller.runtime.variables.task.get_integers(task_name_or_index, task_int_array_starting_index, number_of_ints)
real_values = controller.runtime.variables.task.get_reals(task_name_or_index, task_real_array_starting_index, number_of_reals)

controller.runtime.variables.task.set_integers(task_name_or_index, task_int_array_starting_index, int_values)
controller.runtime.variables.task.set_reals(task_name_or_index, task_real_array_starting_index, real_values)

Industrial Ethernet Variables

In the Python API, Industrial Ethernet Variables lets you get and set the values of Industrial Ethernet mappings on an Automation1 controller. Automation1 exposes the memory blocks of Industrial Ethernet protocols, such as Modbus and EtherCAT, through Industrial Ethernet mappings. These Industrial Ethernet mappings let you map memory regions used by Industrial Ethernet protocols to arbitrary controller data types. For more information, see Modbus TCP/IP Overview and EtherCAT Overview.

Industrial Ethernet mappings can be AeroScript integers or reals. AeroScript integers are 64-bit. They are represented in Python by the int data type. AeroScript reals are double-precision floating-point numbers. They are represented in Python by the float data type.

How to Use

In the Python API, Industrial Ethernet Variables is part of the Controller.runtime property. For all the APIs that operate under this property, the Automation1 controller must be running before you can do work with Industrial Ethernet mappings. For more information about this property, see the Controller page.

You can get and set the value of a single Industrial Ethernet mapping by using the methods that follow:

Copy 
integer_value = controller.runtime.variables.industrial_ethernet.get_integer(industrial_ethernet_mapping_name)
real_value = controller.runtime.variables.industrial_ethernet.get_real(industrial_ethernet_mapping_name)
controller.runtime.variables.industrial_ethernet.set_integer(industrial_ethernet_mapping_name, value)
controller.runtime.variables.industrial_ethernet.set_real(industrial_ethernet_mapping_name, value)

You can also get and set a contiguous segment of values within a single Industrial Ethernet mapping array by using the methods that follow:

Copy 
integer_values = controller.runtime.variables.industrial_ethernet.get_integers(industrial_ethernet_mapping_array_name, starting_industrial_ethernet_mapping_array_index, number_of_ints)
real_values = controller.runtime.variables.industrial_ethernet.get_reals(industrial_ethernet_mapping_array_name, starting_industrial_ethernet_mapping_array_index, number_of_reals)
controller.runtime.variables.industrial_ethernet.set_integers(industrial_ethernet_mapping_array_name, starting_industrial_ethernet_mapping_array_index, values)
controller.runtime.variables.industrial_ethernet.set_reals(industrial_ethernet_mapping_array_name, starting_industrial_ethernet_mapping_array_index, values)

Thread Safety

The threading library is the only multithreading library that is officially supported by the Automation1 Python API.

All the methods and properties that operate under the Controller.runtime.variables.global_ and Controller.runtime.variables.task properties are thread safe. You can call them from two or more threads without interference.

Full Reference

For more information about the methods that are available for Global Variables, Task Variables, and Industrial Ethernet Variables, refer to the lists that follow.

Controller.runtime.variables.global_ Methods

Returns the value of an integer controller global variable ($iglobal in AeroScript), at the specified global integer array index. The value is returned as an AeroScript integer value (which is a 64-bit long integer).

global_int_index: The global integer array index to return the value of.

Returns: The value of an integer controller global variable, which is a 64-bit long integer.

Gets the values of a contiguous segment of integer controller global variables ($iglobal in AeroScript), starting at the specified global integer array index and with the specified number of variables to get. The values are returned as AeroScript integer values (which are 64-bit integers). You can access these controller global variables from each task on the controller and from each API.

starting_global_int_index: The global integer array index that starts the segment of global variables to get.

number_of_ints: The number of variables to get from the controller.

Returns: A list of the acquired integers.

Returns the value of a real controller global variable ($rglobal in AeroScript), at the specified global real array index. The value is returned as an AeroScript real value (which is a double-precision floating-point number).

global_real_index: The global real array index to return the value of.

Returns: The value of a real controller global variable.

Gets the values of a contiguous segment of real controller global variables ($rglobal in AeroScript), starting at the specified global real array index and with the specified number of variables to get. The values are returned as AeroScript real values (which are double-precision floating-point numbers). You can access these controller global variables from each task on the controller and from each API.

starting_global_real_index: The global real array index that starts the segment of global variables to get.

number_of_reals: The number of variables to get from the controller.

Returns: A list of the acquired reals.

Gets the value of a single string controller global variable ($sglobal in AeroScript), at the specified global string array index. You can access these controller global variables from each task on the controller and from each API. All the string global variables have a capacity of 256 characters, which includes a null terminator.

global_string_index: The global string array index to return the value of.

Returns: The acquired string.

Sets the value of an integer controller global variable ($iglobal in AeroScript), at the specified global integer array index. The value to set is an AeroScript integer value (which is a 64-bit long integer).

global_integer_index: The global integer array index to set the value of.

integer_value: The AeroScript integer value (which is a 64-bit long integer) to set on the controller.

Sets the values of a contiguous segment of integer controller global variables ($iglobal in AeroScript), starting at the specified global integer array index. The values to set are AeroScript integer values (which are 64-bit integers). You can access these controller global variables from each task on the controller and from each API.

starting_global_int_index: The global integer array index that starts the segment of global variables to set.

int_values: The list of AeroScript integer values (which are 64-bit long integers) to set on the controller.

Sets the value of a real controller global variable ($rglobal in AeroScript), at the specified global real array index. The value to set is an AeroScript real value (which is a double-precision floating-point number).

global_real_index: The global real array index to set the value of.

real_value: The AeroScript real value (which is a double-precision floating-point number) to set on the controller.

Sets the values of a contiguous segment of real controller global variables ($rglobal in AeroScript), starting at the specified global real array index. The values to set are AeroScript real values (which are double-precision floating-point numbers). You can access these controller global variables from each task on the controller and from each API.

starting_global_real_index: The global real array index that starts the segment of global variables to set.

real_values: The list of AeroScript real values (which are double-precision floating-point numbers) to set on the controller.

Sets the value of a single string controller global variable ($sglobal in AeroScript), at the specified global string array index. You can access these controller global variables from each task on the controller and from each API. All the string global variables have a capacity of 256 characters, which includes a null terminator. This means that the maximum length of the string_value argument is 255 characters.

global_string_index: The global string array index to set the value of.

string_value: The string value to set for the string controller global variable.

Controller.runtime.variables.task Methods

Returns the value of an controller task variable ($itask in AeroScript), at the specified task integer array index. The value is returned as an AeroScript integer value (which is a 64-bit long integer).

task_name_or_index: The name or index of the task to get the integer task variable from.

task_int_array_index: The task integer array index to return the value of.

Returns: The acquired integer.

Gets the values of a contiguous segment of integer controller task variables ($itask in AeroScript), starting at the specified task integer array index and with the specified number of variables to get. The values are returned as AeroScript integer values (which are 64-bit integers). These controller task variables are accessible from every task on the controller and from every API.

task_name_or_index: The name or index of the task to get the integer task variables from.

task_int_array_starting_index: The task integer array index that starts the segment of task variables to get.

number_of_ints: The number of variables to get from the controller.

Returns: A list of the acquired integers.

Returns the value of a real controller task variable ($rtask in AeroScript), at the specified task real array index. The value is returned as an AeroScript real value (which is a double precision floating point number).

task_name_or_index: The name or index of the task to get the real task variable from.

task_real_array_index: The task real array index to return the value of.

Returns:The acquired real.

Gets the values of a contiguous segment of real controller task variables ($rtask in AeroScript), starting at the specified task real array index and with the specified number of variables to get. The values are returned as AeroScript real values (which are double precision floating point numbers). These controller task variables are accessible from every task on the controller and from every API.

task_name_or_index: The name or index of the task to get the real task variables from.

task_real_array_starting_index: The task real array index that starts the segment of task variables to get.

number_of_reals: The number of variables to get from the controller.

Returns: A list of the acquired reals.

Gets the value of a single string controller task variable ($stask in AeroScript), at the specified task string array index. These controller task variables are accessible from every task on the controller and from every API. Each string task variable has a capacity of 256 characters including a null terminator.

task_name_or_index: The name or index of the task to get the string task variable from.

task_string_array_index: The task string array index to get the value of.

Returns: The acquired string.

Sets the value of an integer controller task variable ($itask in AeroScript), at the specified task integer array index. The value to set is an AeroScript integer value (which is a 64-bit long integer).

task_name_or_index: The name or index of the task on which to set the integer task variable.

task_integer_index: The task integer array index to set the value of.

integer_value: The AeroScript integer value (which is a 64-bit long integer) to set on the controller.

Sets the values of a contiguous segment of integer controller task variables ($itask in AeroScript), starting at the specified task integer array index. The values to set are AeroScript integer values (which are 64-bit integers). These controller task variables are accessible from every task on the controller and from every API.

task_name_or_index: The name or index of the task on which to set the integer task variables.

task_int_array_starting_index: The task integer array index that starts the segment of task variables to set.

int_values: The list of AeroScript integer values (which are 64-bit long integers) to set on the controller.

Sets the value of a real controller task variable ($rtask in AeroScript), at the specified task real array index. The value to set is an AeroScript real value (which is a double precision floating point number).

task_name_or_index: The name or index of the task on which to set the real task variable.

task_real_array_index: The task real array index to set the value of.

real_value: The AeroScript real value (which is a double precision floating point number) to set on the controller.

Sets the values of a contiguous segment of real controller task variables ($rtask in AeroScript), starting at the specified task real array index. The values to set are AeroScript real values (which are double precision floating point numbers). These controller task variables are accessible from every task on the controller and from every API.

task_name_or_index: The name or index of the task on which to set the real task variables.

task_real_array_starting_index: The task real array index that starts the segment of task variables to set.

real_values: The list of AeroScript real values (which are double precision floating point numbers) to set on the controller.

Sets the value of a single string controller task variable ($stask in AeroScript), at the specified task string array index. These controller task variables are accessible from every task on the controller and from every API. Each string task variable has a capacity of 256 characters including a null terminator, meaning that the maximum length of string_value is 255.

task_name_or_index: The name or index of the task on which to set the string task variable.

task_string_array_index: The task string array index to set the value of.

string_value: The string value to set for the string controller task variable.

Controller.runtime.variables.industrial_ethernet Methods

Gets the value of an Industrial Ethernet mapping. The value is returned as an AeroScript integer value, which is a 64-bit long integer.

industrial_ethernet_mapping_name: The name of the Industrial Ethernet mapping to get the value of.

Returns: The integer value of the specified Industrial Ethernet mapping.

Gets a list of values for a segment of an Industrial Ethernet mapping array, starting at the specified index. The values are returned as an array of AeroScript integer values, which are 64-bit long integers.

industrial_ethernet_mapping_array_name: The name of the Industrial Ethernet mapping array to get the values from.

starting_industrial_ethernet_mapping_array_index: The index of the Industrial Ethernet mapping array that starts the segment of values to get.

number_of_ints: The length of the segment to get.

Returns: A list of integer values for a segment of an Industrial Ethernet mapping array.

Gets the value of an Industrial Ethernet mapping. The value is returned as an AeroScript real value, which is a double-precision floating-point number.

industrial_ethernet_mapping_name: The name of the Industrial Ethernet mapping to get the value of.

Returns: The real value of the specified Industrial Ethernet mapping.

Gets a list of values for a segment of an Industrial Ethernet mapping array, starting at the specified index. The values are returned as an array of AeroScript real values, which are double-precision floating-point numbers.

industrial_ethernet_mapping_array_name: The name of the Industrial Ethernet mapping array to get the values from.

starting_industrial_ethernet_mapping_array_index: The index of the Industrial Ethernet mapping array that starts the segment of values to get.

number_of_ints: The length of the segment to get.

Returns: A list of real values for a segment of an Industrial Ethernet mapping array.

Sets the value of an Industrial Ethernet mapping as an AeroScript integer value, which is a 64-bit long integer.

industrial_ethernet_mapping_name: The name of the Industrial Ethernet mapping to set the value of.

value: The value to set for the Industrial Ethernet mapping.

execution_task_index: The task to use to set the value.

Sets the values of a segment of an Industrial Ethernet mapping array, as AeroScript integer values (which are 64-bit long integers), starting at the specified index.

industrial_ethernet_mapping_array_name: The name of the Industrial Ethernet mapping array to set the segment of values.

starting_industrial_ethernet_mapping_array_index: The index in the Industrial Ethernet mapping array that starts the segment of values to set.

values: The values to set for the segment of the Industrial Ethernet mapping array.

execution_task_index: The task to use to set the values.

Sets the value of an Industrial Ethernet mapping as an AeroScript real value (which is a double-precision floating-point number).

industrial_ethernet_mapping_name: The name of the Industrial Ethernet mapping to set the value of.

value: The value to set for the Industrial Ethernet mapping.

execution_task_index: The task to use to set the value.

Sets the values of a segment of an Industrial Ethernet mapping array, as AeroScript real values (which are double-precision floating-point numbers), starting at the specified index.

industrial_ethernet_mapping_array_name: The name of the Industrial Ethernet mapping array to set the segment of values.

starting_industrial_ethernet_mapping_array_index: The index in the Industrial Ethernet mapping array that starts the segment of values to set.

values: The values to set for the segment of the Industrial Ethernet mapping array.

execution_task_index: The task to use to set the values.