Status

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

The Basics

In the Python API, Status lets you get information about what the Automation1 controller is doing at this current moment in time. The pieces of information that you can get are known as status items. They are categorized into axis, task, and system categories. See The Three Categories: Axis, Task, and System.

All status items return floats in Python, which are double-precision, floating-point numbers. Some status items represent enumerations or masks. Use status to get axis positions, axis-homed states, axis faults, I/O values, task states, task errors, and more.

The Python API gives you a way to retrieve multiple status items from an Automation1 controller during runtime. Retrieved status represents a moment in time. Status is different from Data Collection because status is not real-time, and it is not time-series data. Status also has variable latency when you retrieve it. You can get status at any time. But you can collect only one set of data at a time. See the Data Collection page.

When you get status, this process has some quantity of fixed overhead. Thus, it is better for you to get status less often and get more status items in each call.

For Example

Instead of getting status for each axis through 32 separate method calls, get all status for all 32 axes in one call.

How to Use

In the Python API, Status 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 get status. For more information about this property, see the Controller page.

To get status by using the Python API, you must:

Configure the status items that you want to get.
Specify the axes or tasks from which to get the status items.

First, create a new StatusItemConfiguration object. This class represents a configuration of status items to retrieve from an Automation1 controller. The StatusItemConfiguration class is one of the few classes in the Python API that you must construct. Refer to the example that follows.

Copy

status_item_configuration = a1.StatusItemConfiguration()

After you make a configuration object, you can add the status items that you want to retrieve. All status items are categorized into axis, task, and system categories:

Axis status items require you to specify the axis from which to get the status items. You can specify an axis by its axis name or axis index.
Task status items require you to specify the task from which to get the status items. You can specify a task by its task name or task index.
The Automation1 controller is the only system. The system property does not require you to specify a system from which to get the status items.

Add the status items that you want to retrieve to the configuration. To do this, use the axis, task, system, and industrial_ethernet properties with the add method.

Copy

status_item_configuration.axis.add(axis_status_item, axis_name)
status_item_configuration.task.add(task_status_item, task_name)
status_item_configuration.system.add(system_status_item)
status_item_configuration.industrial_ethernet.add(industrial_ethernet_mapping_name)

After you add all the status items that you want to retrieve to the configuration, you can get their values by using the Controller.runtime.status.get_status_items method. Call this method and pass in the StatusItemConfiguration object that you constructed to retrieve the values of those status items. Refer to the example that follows.

Copy

status_item_results = controller.runtime.status.get_status_items(status_item_configuration)

The StatusItemResults object that is returned represents the status at the moment in time it was retrieved from an Automation1 controller, based on the specified StatusItemConfiguration object.

To get the value for each status item or Industrial Ethernet mapping, use the axis, task, and system or industrial_ethernet properties. You can use the get method on these properties by doing one of the options that follow:

Specify the status item and the corresponding axis or task, if applicable.
Specify an Industrial Ethernet mapping.

Copy

axis_value = status_item_results.axis.get(axis_status_item, axis).value
task_value = status_item_results.task.get(task_status_item, task).value
system_value = status_item_results.system.get(system_status_item).value
industrial_ethernet_value = status_item_results.industrial_ethernet.get(industrial_ethernet_mapping_name).value

The double-precision floating-point number that is returned by the value property is the value of the status item at the point in time when the StatusItemConfiguration object was retrieved.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
# Configure the status items that you want to get.
status_item_configuration = a1.StatusItemConfiguration()
status_item_configuration.axis.add(a1.AxisStatusItem.PositionCommand, "X")
status_item_configuration.task.add(a1.TaskStatusItem.TaskState, "Task 1")
status_item_configuration.system.add(a1.SystemStatusItem.Timer)

# Get the status from the controller.
results = controller.runtime.status.get_status_items(status_item_configuration)

# Get the values out of the results object.
position_command_x = results.axis.get(a1.AxisStatusItem.PositionCommand, "X").value
task_state_1 = results.task.get(a1.TaskStatusItem.TaskState, "Task 1").value
system_timer = results.system.get(a1.SystemStatusItem.Timer).value

How to Get an Axis Position

You can get an axis position. You can also get its homed state, enabled state, and faults. Refer to the example that follows:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import automation1 as a1

controller = a1.Controller.connect()
controller.start()

# DriveStatus is a series of bits that can be masked. You will use it to get the axis "enabled" bit.
# AxisStatus is a series of bits that can be masked. You will use it to get the axis "homed" bit.
status_item_configuration = a1.StatusItemConfiguration()
status_item_configuration.axis.add(a1.AxisStatusItem.ProgramPosition, "X")
status_item_configuration.axis.add(a1.AxisStatusItem.DriveStatus, "X")
status_item_configuration.axis.add(a1.AxisStatusItem.AxisStatus, "X")
status_item_configuration.axis.add(a1.AxisStatusItem.AxisFault, "X")
results = controller.runtime.status.get_status_items(status_item_configuration)

program_position = results.axis.get(a1.AxisStatusItem.ProgramPosition, "X").value
print(program_position)

# DriveStatus is a series of status bits that you can mask to get various information about the state of the drive.
# It is acquired as a float. But you need to interpret it as a series of maskable bits. To do this, you must convert it
# to an integer. Then apply the "Enabled" mask from the enum and check to see if the result equals the mask to determine
# if the drive axis is enabled.
drive_status = int(results.axis.get(a1.AxisStatusItem.DriveStatus, "X").value)
is_enabled = (drive_status & a1.DriveStatus.Enabled) == a1.DriveStatus.Enabled
print(is_enabled)

# AxisStatus is similar to DriveStatus because you can mask it to get information about the state of the axis.
# It is also acquired as a float. But you need to interpret it as a series of maskable bits. To do this, you must repeat
# the process outlined for DriveStatus.
axis_status = int(results.axis.get(a1.AxisStatusItem.AxisStatus, "X").value)
is_homed = (axis_status & a1.AxisStatus.Homed) == a1.AxisStatus.Homed
print(is_homed)

# Finally, AxisFault is also a status item that you can mask to get information about the faults on the axis.
# It is also acquired as a float. But you need to interpret it as a series of maskable bits. To do this, you must repeat
# the process outlined for DriveStatus and AxisStatus.
axis_faults = int(results.axis.get(a1.AxisStatusItem.AxisFault, "X").value)
print(axis_faults)

Retrieve Industrial Ethernet Mappings

In the Python API, you can use Status to retrieve the values of Industrial Ethernet mappings. To do this, use the StatusItemConfiguration.industrial_ethernet property.

Copy

configuration = StatusItemConfiguration()
configuration.industrial_ethernet.add(“myMapping”); // Configured to retrieve the value of “$myMapping”.
configuration.industrial_ethernet.add(“myMappingArray”, 2); // Configured to retrieve the value of “$myMappingArray[2]”.

After you use the Status.get_status_items() function to retrieve status, you can use the StatusItemResults.industrial_ethernet property to access the values that were retrieved for your configured Industrial Ethernet mappings.

Copy

results = controller.runtime.status.get_status_items(configuration);

firstResult = results.industrial_ethernet.get(“myMapping”).value;
secondResult = results.industrial_ethernet.get(“myMappingArray”, 2).value;

Thread Safety

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

The StatusItemConfiguration class is not thread safe. Only one thread at a time can access an instance of this class. If it is necessary for two or more threads to access or modify an instance of this class, you must use locks to limit the access.

All methods and properties on the Controller.runtime.status property are thread safe. You can call these methods and properties from two or more threads without interference.

The StatusItemResults class is thread safe. You can access an instance of this class and its properties from two or more threads without interference.

The axis, task, system, and industrial_ethernet properties on the StatusItemResults class are collections of StatusItemResults objects that can be iterated over.

WARNING: While you can call the iter function on the axis, task, system , or industrial_ethernet property, it is not recommended. If you do this, the iter function will return an iterator object that is not thread safe.

Full Reference

For more information about the methods, constructors, and properties that are available for Status, refer to the lists that follow.

Controller.runtime.status Methods

StatusItemConfiguration Constructors

StatusItemConfiguration Properties

StatusItemConfiguration Methods