minute read

On this API page:

Status

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

The Basics

In the .NET 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 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 .NET 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 .NET 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 .NET 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 .NET API that you must construct.

Copy

StatusItemConfiguration statusItemConfiguration = new 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 item. 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 item. 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 IndustrialEthernet properties with the Add method.

Copy

statusItemConfiguration.Axis.Add(AxisStatusItem axisStatusItem, string axisName);
statusItemConfiguration.Task.Add(TaskStatusItem taskStatusItem, string taskName);
statusItemConfiguration.System.Add(SystemStatusItem systemStatusItem);
statusItemConfiguration.IndustrialEthernet.Add(string industrialEthernetMappingName);

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.GetStatusItems method. Call this method and pass in the StatusItemConfiguration object that you constructed to retrieve the values of those status items.

Copy

StatusItemResults statusItemResults = controller.Runtime.Status.GetStatusItems(StatusItemConfiguration statusItemConfiguration);

The StatusItemResults object that is returned represents the status at the moment in time that 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 IndustrialEthernet properties. You can index 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

double axisValue = statusItemResults.Axis[AxisStatusItem axisStatusItem, string axisName].Value;
double taskValue = statusItemResults.Task[TaskStatusItem taskStatusItem, string taskName].Value;
double systemValue = statusItemResults.System[SystemStatusItem systemStatusItem].Value;
double industrialEthernetValue = statusItemResults.IndustrialEthernet[string industrialEthernetMappingName].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.
StatusItemConfiguration statusItemConfiguration = new StatusItemConfiguration();
statusItemConfiguration.Axis.Add(AxisStatusItem.PositionCommand, "X");
statusItemConfiguration.Task.Add(TaskStatusItem.TaskState, "Task 1");
statusItemConfiguration.System.Add(SystemStatusItem.Timer);
 
// Get the status from the controller.
StatusItemResults results = controller.Runtime.Status.GetStatusItems(statusItemConfiguration);
 
// Get the values out of the results object.
Console.WriteLine("X Position Command: {0}", results.Axis[AxisStatusItem.PositionCommand, "X"].Value);
Console.WriteLine("Task 1 Task State: {0}", results.Task[TaskStatusItem.TaskState, "Task 1"].Value);
Console.WriteLine("Timer: {0}", results.System[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
// 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.
StatusItemConfiguration statusItemConfiguration = new StatusItemConfiguration();
statusItemConfiguration.Axis.Add(AxisStatusItem.ProgramPosition, "X");
statusItemConfiguration.Axis.Add(AxisStatusItem.DriveStatus, "X");
statusItemConfiguration.Axis.Add(AxisStatusItem.AxisStatus, "X");
statusItemConfiguration.Axis.Add(AxisStatusItem.AxisFault, "X");
StatusItemResults result = controller.Runtime.Status.GetStatusItems(statusItemConfiguration);
 
double programPosition = result.Axis[AxisStatusItem.ProgramPosition, "X"].Value;
Console.WriteLine($"Position: {programPosition}");
 
// 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 double. But you need to interpret it as a series of maskable bits. To do this, you must cast it to the
// correct enum type. 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.
DriveStatus driveStatus = (DriveStatus)result.Axis[AxisStatusItem.DriveStatus, "X"].Value;
bool isEnabled = (driveStatus & DriveStatus.Enabled) == DriveStatus.Enabled;
Console.WriteLine($"Enabled: {isEnabled}");
 
// 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 double. 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.
AxisStatus axisStatus = (AxisStatus)result.Axis[AxisStatusItem.AxisStatus, "X"].Value;
bool isHomed = (axisStatus & AxisStatus.Homed) == AxisStatus.Homed;
Console.WriteLine($"Homed: {isHomed}");
 
// 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 double. 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.
AxisFault axisFaults = (AxisFault)result.Axis[AxisStatusItem.AxisFault, "X"].Value;
Console.WriteLine($"Faults: {axisFaults}");

Automatic Status

Instead of using the Controller.Runtime.Status.GetStatusItems method to poll for status manually, you can make the .NET API poll for status automatically by using the Controller.Runtime.Status.Automatic.NewStatusRetrieved event. Automatic status will continuously and automatically retrieve status from the Automation1 controller. When you subscribe to this event, it will be raised periodically with the latest status information from the controller.

By default, automatic status gets common status items for all the axes and tasks every 100 milliseconds. But you can customize the status items that are retrieved by using the SetConfiguration method and the Period property. Automatic status will automatically pause.

To pause and resume automatic status, use the Pause and Resume methods. Automatic status will automatically pause and resume if you reset or stop the controller.

Example Code for Automatic Status

Copy

1
2
3
4
5
// Subscribe to the automatic status event that will be raised periodically.
controller.Runtime.Status.Automatic.NewStatusRetrieved += (sender, args) =>
{
    Console.WriteLine("X Position Command: {0}", args.Results.Axis[AxisStatusItem.PositionCommand, "X"].Value);
};

Retrieve Industrial Ethernet Mappings

You can use Status to retrieve the values of Industrial Ethernet mappings. To do this, use the StatusItemConfiguration.IndustrialEthernet property.

Copy

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

After you use the Status.GetStatusItems() method to retrieve status, you can use the StatusItemResults.IndustrialEthernet property to access the values that you retrieved for your configured Industrial Ethernet mappings.

Copy

StatusItemResults results = controller.Runtime.Status.GetStatusItems(configuration);
double firstResult = results.IndustrialEthernet[“myMapping”].Value;
double secondResult = results.IndustrialEthernet[“myMappingArray”, 2].Value;

Thread Safety

The StatusItemConfiguration class is not thread safe. Only one thread at a time can access an instance of this class. If two or more threads must 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.

All methods and properties on the Controller.Runtime.Status.Automatic 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.

Full Reference

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

Controller.Runtime.Status Methods

Controller.Runtime.Status.Automatic Properties

Controller.Runtime.Status.Automatic Events

Controller.Runtime.Status.Automatic Methods

Controller.Runtime.Status.Automatic.GetDefaultConfiguration()

Gets the default status item configuration, which is used if you do not change the configuration through the Controller.Runtime.Status.Automatic.SetConfiguration method. This default status item configuration will retrieve common status items for each axis and task.

The default status item configuration configures the following axis status items

for each axis:

AxisStatusItem.PositionCommand
AxisStatusItem.PositionFeedback
AxisStatusItem.PositionError
AxisStatusItem.AuxiliaryFeedback
AxisStatusItem.CurrentCommand
AxisStatusItem.CurrentFeedback
AxisStatusItem.CurrentError
AxisStatusItem.ProgramPositionCommand
AxisStatusItem.ProgramPositionFeedback
AxisStatusItem.VelocityCommand
AxisStatusItem.VelocityFeedback
AxisStatusItem.VelocityError
AxisStatusItem.AccelerationCommand
AxisStatusItem.AccelerationFeedback
AxisStatusItem.AccelerationError
AxisStatusItem.DriveStatus
AxisStatusItem.AxisStatus
AxisStatusItem.AxisFault

The default status item configuration configures the following task status items

for each task:

TaskStatusItem.ProgramLineNumber
TaskStatusItem.MotionLineNumber
TaskStatusItem.TaskStatus0
TaskStatusItem.TaskStatus1
TaskStatusItem.TaskStatus2
TaskStatusItem.TaskMode
TaskStatusItem.TaskState
TaskStatusItem.TaskError
TaskStatusItem.TaskWarning
TaskStatusItem.ExecutionMode
TaskStatusItem.Mfo

Returns: The default status item configuration.

StatusItemConfiguration Constructors

StatusItemConfiguration Properties

StatusItemConfiguration Methods