minute read

On this API page:

Data Collection

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

The Basics

In the .NET API, Data Collection lets you collect a snapshot of data over a specified period of time from an Automation1 controller. Data collection is a way to gather a set of time-series data in a real-time, deterministic way. Only one set of data can be collected at a time on an Automation1 controller. The pieces of information that you can collect are called data signals. They are categorized into axis, task, and system categories. See The Three Controller Categories: Axis, Task, and System. All data signals return arrays of points, which are double-precision floating-point numbers. Some data signals represent enumerations or masks.

Data collection is different from status 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 Status page.

How to Use

In the .NET API, Data Collection 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 collect data. For more information about this property, see the Controller page.

To collect data by using the .NET API, you must:

Configure the data signals that you want to collect.
Specify the axes or tasks from which you want to collect the data signals.
Specify how many points of data you want to collect and the frequency at which to collect them.

First, create a new DataCollectionConfiguration object and specify the number of points to collect and the frequency at which to collect them. The number of points to collect and the frequency of data collection control the quantity of time that is necessary for data collection to complete. This class represents a configuration of data signals to collect from an Automation1 controller. The DataCollectionConfiguration class is one of the few classes in the .NET API that you must construct. Refer to the example that follows.

Copy

DataCollectionConfiguration dataCollectionConfiguration = new DataCollectionConfiguration(int numberOfPointsToCollect, DataCollectionFrequency frequency);

The maximum number of points that you can collect is controlled by the DataCollectionPoints and DataCollectionItems controller parameters.

The typical data collection frequency is 1 kHz, which means there is 1 millisecond of time between each collected data point. You can collect data at frequencies that are faster than 1 kHz. They include 5 kHz, 10 kHz, 20 kHz, 100 kHz, and 200 kHz. But if you use a faster frequency, it will decrease the number of signals that you can collect.

After you create a configuration object, you can add the data signals that you want to collect. All data signals are categorized into axis, task, and system categories.

Axis data signals require you to specify the axis from which to collect the data signal. You can specify an axis by its axis name or axis index.
Task data signals require you to specify the task from which to collect the data signal. 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 collect the data signal.

To add the data signals that you want to collect, use the Axis, Task, System, and IndustrialEthernet properties with the Add method.

Copy

dataCollectionConfiguration.Axis.Add(AxisDataSignal axisDataSignal, string axisName);
dataCollectionConfiguration.Task.Add(TaskDataSignal taskDataSignal, string taskName);
dataCollectionConfiguration.System.Add(SystemDataSignal systemDataSignal);
dataCollectionConfiguration.IndustrialEthernet.Add(string industrialEthernetMappingName);

After you add all the data signals that you want to collect to the configuration, you can start data collection. You can collect one snapshot of data or collect data continuously.

A snapshot of data - Collects the number of points specified in the configuration, blocking until the data collection completes or is stopped. Then the collected data is returned to you.

Continuous data collection - Does not collect a set number of points. Instead, it will collect data indefinitely and will periodically give you results through a delegate when new data is available. For more information and examples, refer to the Continuous Data Collection section.

Copy

DataCollectionResults results = controller.Runtime.DataCollection.CollectSnapshot(DataCollectionConfiguration dataCollectionConfiguration);

The DataCollectionResults object that is returned represents the time-series data that is collected from an Automation1 controller based on the specified DataCollectionConfiguration class.

To get the points for each data signal 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 data signals and the corresponding axis or task, if applicable.
Specify an Industrial Ethernet mapping.

Copy

double[] axisPoints = results.Axis[AxisDataSignal axisDataSignal, string axisName].Points;
double[] taskPoints = results.Task[TaskDataSignal taskDataSignal, string taskName].Points;
double[] systemPoints = results.System[SystemDataSignal systemDataSignal].Points;
double[] industrialEthernetPoints = results.IndustrialEthernet[string industrialEthernetMappingName].Points;

The double-precision floating-point array that is returned by the Points property contains the individual samples of the data signal from over the course of data collection. The time between each sample point was controlled by the frequency that you specified in the configuration.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Configure data collection for 1 second worth of data and add the data signals that you want to collect.
DataCollectionConfiguration dataCollectionConfiguration = new DataCollectionConfiguration(1000, DataCollectionFrequency.Frequency1kHz);
dataCollectionConfiguration.Axis.Add(AxisDataSignal.PositionCommand, "X");
dataCollectionConfiguration.Task.Add(TaskDataSignal.TaskState, "Task 1");
dataCollectionConfiguration.System.Add(SystemDataSignal.Timer);
 
// Start data collection, which will block until all the data is collected or data collection is stopped.
DataCollectionResults dataCollectionResults = controller.Runtime.DataCollection.CollectSnapshot(dataCollectionConfiguration);
 
// Get the points for each collected data signal. You will get back 1000 points in each array, which
// represents 1 second worth of data collected at 1 kHz or 1 millisecond between each point.
double[] positionCommandAxisX = dataCollectionResults.Axis[AxisDataSignal.PositionCommand, "X"].Points;
double[] taskStateTask1 = dataCollectionResults.Task[TaskDataSignal.TaskState, "Task 1"].Points;
double[] systemTimer = dataCollectionResults.System[SystemDataSignal.Timer].Points;

Continuous Data Collection

Instead of collecting one snapshot of data, you can collect data continuously. Continuous data collection does not collect a set number of points. It collects data indefinitely and will periodically give you results through a delegate when new data is available.

The CollectContinuous method will block until you explicitly stop data collection. You can stop data collection from a different thread or from within the newResultsAction delegate. Refer to the example that follows.

Copy

controller.Runtime.DataCollection.CollectContinuous(DataCollectionConfiguration dataCollectionConfiguration, Action<DataCollectionResults> newResultsAction)

The number of points to collect that you specified in the DataCollectionConfiguration object controls how often the newResultsAction delegate is invoked. This delegate will be invoked on the same thread that called the method. When you specify the number of points to collect, this becomes a balancing act between getting results more frequently and having a sufficient quantity of time between each set of results to process the previous results.

If you specify a number of points to collect that is too small, your custom application will get results too frequently. Thus, it might not be able to keep up with continuous data collection. As a result, an overflow error will occur and data collection will stop.

Tip: For a good starting point, specify 250 to 500 milliseconds worth of points. This quantity of points prevents an overflow error from occurring by giving your custom application sufficient time to process the results.

It is important to keep your delegate fast. If you do not, your custom application might not be able to keep up with continuous data collection. As a result, an overflow error will occur and data collection will stop.

Example Code

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Start continuous data collection, which will block until continuous data collection is explicitly stopped from within the delegate.
controller.Runtime.DataCollection.CollectContinuous(dataCollectionConfiguration, (dataCollectionResults) =>
{
    // Get the points from the last 250 milliseconds of continuous data collection. You will get back
    // 250 points in each array because you are collecting at 1 kHz or 1 millisecond between each point.
    double[] positionCommandAxisX = dataCollectionResults.Axis[AxisDataSignal.PositionCommand, "X"].Points;
    double[] taskStateTask1 = dataCollectionResults.Task[TaskDataSignal.TaskState, "Task 1"].Points;
    double[] systemTimer = dataCollectionResults.System[SystemDataSignal.Timer].Points;
 
    // Here you might append the above points to an existing list of points, or you might update your UI.
    // Remember that this delegate must be fast, otherwise your custom application might not be able to
    // keep up with continuous data collection and data collection will stop with an overflow error.
 
    // In this example, you want continuous data collection because your process can take any quantity of time.
    // Thus you stop continuous data collection when the program on Task 1 completes, which means your process is done.
    if (taskStateTask1.Select((point) => (TaskState)point).Any((taskState) => taskState == TaskState.ProgramComplete || taskState == TaskState.Error))
{
    controller.Runtime.DataCollection.Stop();
}
});

Collect Industrial Ethernet Mappings

You can use Data Collection to collect the values of Industrial Ethernet mappings. To do this, use the DataCollectionConfiguration.IndustrialEthernet property.

Copy

DataCollectionConfiguration configuration = new DataCollectionConfiguration(1000, DataCollectionFrequency.Frequency1kHz)
configuration.IndustrialEthernet.Add(“myMapping”); // Configured to collect the value of $myMapping.
configuration.IndustrialEthernet.Add(“myMappingArray”, 2); // Configured to collect the value of $myMapping[2].

After you use the DataCollection.CollectSnapshot() or DataCollection.CollectContinuous() method to collect points, you can use the DataCollectionResults.IndustrialEthernet property to access the points that were collected for your configured Industrial Ethernet mappings.

Copy

DataCollectionResults results = controller.Runtime.DataCollection.CollectSnapshot(configuration);
double[] firstResults = results.IndustrialEthernet[“myMapping”].Points;
double[] secondResults = results.IndustrialEthernet[“myMappingArray”, 2].Points;

Thread Safety

The DataCollectionConfiguration 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.

The Controller.Runtime.DataCollection property is not thread safe. Only one set of data can be collected at a time on an Automation1 controller. Thus only one thread at a time can access data collection. If it is necessary for two or more threads to access or modify data collection, you must use locks to limit the access.

The DataCollectionResults 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 properties and methods that are available for Data Collection, refer to the lists that follow.

Controller.Runtime.DataCollection Properties

Controller.Runtime.DataCollection Methods