Status

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

The Basics

In the C API, Status lets you get information about what the Automation1 controller is doing at this current moment in time. The pieces of information 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 C 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 function calls, get all status for all 32 axes in one call.

How to Use

Status is part of the controller runtime. Thus the Automation1 controller must be running before you can get status. For more information, see the Controller page.

To get status by using the C 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 Automation1StatusConfig handle. This handle stores a configuration of status items to retrieve from an Automation1 controller. When you use this handle, make sure that you do the steps that follow:

To create an Automation1StatusConfig handle, use the Automation1_StatusConfig_Create() function. You must do this before you try to use the handle.
Add all the status items that you want to retrieve to the configuration. For more information, refer to the additional documentation in this section.
Include an Automation1StatusConfig handle with each C API status function that you use. All the C API status functions require this handle.
When you are done getting status, you must free the configuration. To do this, use the Automation1_StatusConfig_Destroy() function.

Copy

Automation1_StatusConfig_Create(Automation1StatusConfig* configOut);
Automation1_StatusConfig_Destroy(Automation1StatusConfig config);

After you make a configuration, 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 must specify an axis by its axis index.
Task status items require you to specify the task from which to get the status item. You must specify a task by its task index.
The Automation1 controller is the only system. It is not necessary for 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 specific functions.

Copy

Automation1_StatusConfig_AddAxisStatusItem(Automation1StatusConfig config, int32_t axisIndex, Automation1AxisStatusItem axisStatusItem, int32_t argument);
Automation1_StatusConfig_AddTaskStatusItem(Automation1StatusConfig config, int32_t taskIndex, Automation1TaskStatusItem taskStatusItem, int32_t argument);
Automation1_StatusConfig_AddSystemStatusItem(Automation1StatusConfig config, Automation1SystemStatusItem systemStatusItem, int32_t argument);
bool Automation1_StatusConfig_AddIndustrialEthernetMapping(Automation1StatusConfig config, const char* industrialEthernetMappingName);
bool Automation1_StatusConfig_AddIndustrialEthernetMappingArray(Automation1StatusConfig config, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingArrayIndex);

After you add all the status items that you want to retrieve to the configuration, you can get their values by using the Automation1_Status_GetResults() function. Call this function and pass in the Automation1StatusConfig handle that you created to retrieve the values of those status items.

Copy

Automation1_Status_GetResults(Automation1Controller controller, Automation1StatusConfig config, double* allResultsOut, int32_t allResultsMaxLength);

The double-precision floating-point array that is set represents the status at the moment in time that it was retrieved from an Automation1 controller, based on the specified Automation1StatusConfig handle.

To get the value for each status item or Industrial Ethernet mapping, use the axis, task, and system or Industrial Ethernet specific functions. You can use these functions 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

Automation1_Status_GetAxisResult(Automation1StatusConfig config, double* allResults, int32_t allResultsLength, int32_t axisIndex, Automation1AxisStatusItem axisStatusItem, int32_t argument, double* axisResultOut);
Automation1_Status_GetTaskResult(Automation1StatusConfig config, double* allResults, int32_t allResultsLength, int32_t taskIndex, Automation1TaskStatusItem taskStatusItem, int32_t argument, double* taskResultOut);
Automation1_Status_GetSystemResult(Automation1StatusConfig config, double* allResults, int32_t allResultsLength, Automation1SystemStatusItem systemStatusItem, int32_t argument, double* systemResultOut);
bool Automation1_Status_GetIndustrialEthernetResult(Automation1StatusConfig config, double* allResults, int32_t allResultsLength, const char* industrialEthernetMappingName, double* industrialEthernetResultOut);
bool Automation1_Status_GetIndustrialEthernetArrayResult(Automation1StatusConfig config, double* allResults, int32_t allResultsLength, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingArrayIndex, double* industrialEthernetResultOut);

The double-precision floating-point number that is set by theses functions is the value of the status item at the point in time when the Automation1StatusConfig handle was retrieved.

As an alternative, you can index directly into the double array that you passed into the Automation1_Status_GetResults() function for the allResultsOut argument.

Example Code

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
// Declare the handle for the status configuration and the variables for the status results.
Automation1StatusConfig statusConfig = NULL;
double results[3];
double positionCommand0, taskState1, timer;

// Configure the status items that you want to get.
if (!Automation1_StatusConfig_Create(&statusConfig)) { /* handle error */ }
if (!Automation1_StatusConfig_AddAxisStatusItem(statusConfig, 0, Automation1AxisStatusItem_PositionCommand, 0)) { /* handle error */ }
if (!Automation1_StatusConfig_AddTaskStatusItem(statusConfig, 1, Automation1TaskStatusItem_TaskState, 0)) { /* handle error */ }
if (!Automation1_StatusConfig_AddSystemStatusItem(statusConfig, Automation1SystemStatusItem_Timer, 0)) { /* handle error */ }

// Get the status from the controller.
if (!Automation1_Status_GetResults(controller, statusConfig, results, 3)) { /* handle error */ }

// Get the values out of the results array.
if (!Automation1_Status_GetAxisResult(statusConfig, results, 3, 0, Automation1AxisStatusItem_PositionCommand, 0, &positionCommand0)) { /* handle error */ }
if (!Automation1_Status_GetTaskResult(statusConfig, results, 3, 1, Automation1TaskStatusItem_TaskState, 0, &taskState1)) { /* handle error */ }
if (!Automation1_Status_GetSystemResult(statusConfig, results, 3, Automation1SystemStatusItem_Timer, 0, &timer)) { /* handle error */ }
printf("Axis 0 Position Command: %f\n", positionCommand0);
printf("Task 1 Task State: %f\n", taskState1);
printf("Timer: %f\n", timer);

// Destroy the statusConfig. This process frees up all memory that is associated with it.
if (!Automation1_StatusConfig_Destroy(statusConfig)) { /* handle error */ }

// Set the configuration handle to null because it is not valid after you destroy the status item configuration.
statusConfig = NULL;

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
38
39
40
41
42
43
44
45
46
47
48
49
50
// Declare the handle for the status configuration and for the status results.
Automation1StatusConfig statusConfig = NULL;
double results[4];
double programPosition, driveStatusDouble, axisStatusDouble, axisFaultDouble;
Automation1DriveStatus driveStatus;
Automation1AxisStatus axisStatus;
Automation1AxisFault axisFault;

// 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.
if (!Automation1_StatusConfig_Create(&statusConfig)) { /* handle error */ }
if (!Automation1_StatusConfig_AddAxisStatusItem(statusConfig, 0, Automation1AxisStatusItem_ProgramPosition, 0)) { /* handle error */ }
if (!Automation1_StatusConfig_AddAxisStatusItem(statusConfig, 0, Automation1AxisStatusItem_DriveStatus, 0)) { /* handle error */ }
if (!Automation1_StatusConfig_AddAxisStatusItem(statusConfig, 0, Automation1AxisStatusItem_AxisStatus, 0)) { /* handle error */ }
if (!Automation1_StatusConfig_AddAxisStatusItem(statusConfig, 0, Automation1AxisStatusItem_AxisFault, 0)) { /* handle error */ }
if (!Automation1_Status_GetResults(controller, statusConfig, results, 4)) { /* handle error */ }
if (!Automation1_Status_GetAxisResult(statusConfig, results, 4, 0, Automation1AxisStatusItem_ProgramPosition, 0, &programPosition)) { /* handle error */ }
if (!Automation1_Status_GetAxisResult(statusConfig, results, 4, 0, Automation1AxisStatusItem_DriveStatus, 0, &driveStatusDouble)) { /* handle error */ }
if (!Automation1_Status_GetAxisResult(statusConfig, results, 4, 0, Automation1AxisStatusItem_AxisStatus, 0, &axisStatusDouble)) { /* handle error */ }
if (!Automation1_Status_GetAxisResult(statusConfig, results, 4, 0, Automation1AxisStatusItem_AxisFault, 0, &axisFaultDouble)) { /* handle error */ }

printf("Position: %f\n", 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 examine the result to see if it equals the mask to determine
// if the drive axis is enabled.
driveStatus = (Automation1DriveStatus)driveStatusDouble;
if ((driveStatus & Automation1DriveStatus_Enabled) == Automation1DriveStatus_Enabled) { printf("Enabled\n"); }
else { printf("Disabled\n"); }

// 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 that is used for DriveStatus and AxisStatus.
axisStatus = (Automation1AxisStatus)axisStatusDouble;
if ((axisStatus & Automation1AxisStatus_Homed) == Automation1AxisStatus_Homed) { printf("Homed\n"); }
else { printf("Not homed\n"); }

// 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 that is used for DriveStatus and AxisStatus.
axisFault = (Automation1AxisFault)axisFaultDouble;
if ((axisFault & Automation1AxisFault_PositionErrorFault) == Automation1AxisFault_PositionErrorFault) { printf("Position error fault\n"); }
else { printf("No position error fault\n"); }

// Destroy the statusConfig. This process frees up all memory that is associated with it.
Automation1_StatusConfig_Destroy(statusConfig);

// Set the configuration handle to null because it is not valid after you destroy the status item configuration.
statusConfig = NULL;

Retrieve Industrial Ethernet Mappings

In the C API, you can use Status to retrieve the values of Industrial Ethernet mappings. To do this, use the Automation1_StatusConfig_AddIndustrialEthernetMapping() and Automation1_StatusConfig_AddIndustrialEthernetMappingArray() functions:

Copy

Automation1StatusConfig configuration;
Automation1_StatusConfig_Create(&configuration);
Automation1_StatusConfig_AddIndustrialEthernetMapping(configuration, “myMapping”);
Automation1_StatusConfig_AddIndustrialEthernetMappingArray(configuration, “myMappingArray”, 2);

After you use the Automation1_Status_GetResults() function to retrieve status, you can use the Automation1_Status_GetIndustrialEthernetResult() and Automation1_Status_GetIndustrialEthernetArrayResult() functions to get the values that were retrieved for your configured Industrial Ethernet mappings.

Copy

double allResults[2];
Automation1_Status_GetResults(controller, configuration, allResults, 2);
double industrialEthernetResult;
Automation1_Status_GetIndustrialEthernetResult(configuration, allResults, 2, “myMapping”, &industrialEthernetResult);
double industrialEthernetArrayResult;
Automation1_Status_GetIndustrialEthernetArrayResult(configuration, allResults, 2, “myMappingArray”, 2, &industrialEthernetArrayResult);

Thread Safety

The Automation1_StatusConfig_ functions and the Automation1StatusConfig handle are not thread safe. Only one thread at a time can call these functions or access this handle. If it is necessary for two or more threads to call these functions or access this handle, you must use locks to limit the access.

The Automation1_Status_ functions are thread safe. You can call them from two or more threads without interference.

Full Reference

For more information about the functions that are available for Status, refer to the list that follows.

Functions