/// /// Copyright (c) Aerotech, Inc. /// #ifndef AUTOMATION1DATACOLLECTION_H_INCLUDED #define AUTOMATION1DATACOLLECTION_H_INCLUDED #if defined(_MSC_VER) #if defined(AUTOMATION1_CAPI_EXPORT) #define AUTOMATION1_CAPI __declspec(dllexport) #else #define AUTOMATION1_CAPI __declspec(dllimport) #endif #elif defined(__GNUC__) #define AUTOMATION1_CAPI __attribute__((visibility ("default"))) #endif #include #include #include "Automation1Controller.h" #include "Automation1DataSignal.h" #if defined(__cplusplus) extern "C" { #endif /// @brief Represents predefined data collection frequencies which correlate to 1 millisecond or sub-millisecond data collect periods. /// Data collection frequency defines how many points will be collection in one second. typedef enum Automation1DataCollectionFrequency { /// @brief A data collection frequency was not specified or a data collection period was specified that does not /// correlate to one of predefined data collection frequencies. Automation1DataCollectionFrequency_Undefined = 0, /// @brief Represents a data collection frequency of 1 kilohertz or a data collection period of 1 millisecond. /// 1000 points will be collected in one second. Automation1DataCollectionFrequency_1kHz, /// @brief Represents a data collection frequency of 10 kilohertz or a data collection period of 0.1 milliseconds. /// 10,000 points will be collected in one second. Automation1DataCollectionFrequency_10kHz, /// @brief Represents a data collection frequency of 20 kilohertz or a data collection period of 0.05 milliseconds. /// 20,000 points will be collected in one second. Automation1DataCollectionFrequency_20kHz, /// @brief Represents a data collection frequency of 100 kilohertz or a data collection period of 0.01 milliseconds. /// 100,000 points will be collected in one second. Automation1DataCollectionFrequency_100kHz, /// @brief Represents a data collection frequency of 200 kilohertz or a data collection period of 0.005 milliseconds. /// 200,000 points will be collected in one second. Automation1DataCollectionFrequency_200kHz, /// @brief Represents a data collection frequency of 5 kilohertz or a data collection period of 0.2 milliseconds. /// 5000 points will be collected in one second. Automation1DataCollectionFrequency_5kHz, } Automation1DataCollectionFrequency; /// @brief Represents the mode that data collection will use when collecting data from an Automation1 controller. typedef enum Automation1DataCollectionMode { /// @brief Data collection will start, collect a specified number of data points at a specified period, then stop. /// Data collection can be stopped prematurely by calling Automation1_DataCollection_Stop(). Automation1DataCollectionMode_Snapshot, /// @brief Data collection will start and collect data points forever at a specified period. /// Continuous data collection can be stopped by calling Automation1_DataCollection_Stop(). Automation1DataCollectionMode_Continuous, } Automation1DataCollectionMode; /// @brief Represents the status of any data collection on an Automation1 controller (both Automation1DataCollectionMode_Snapshot and Automation1DataCollectionMode_Continuous). typedef struct Automation1DataCollectionStatus { /// @brief Gets the number of points that data collection will collect. In Automation1DataCollectionMode_Snapshot this number is the total number of points to collect. /// In Automation1DataCollectionMode_Continuous this number is the size of each chunk of continuously collected points. int32_t NumberOfPointsToCollect; /// @brief Gets the number of points that data collection has collected for all configured data signals. int32_t NumberOfCollectedPoints; /// @brief Gets the number of points that data collection has collected and retrieved. At certain data collection periods NumberOfRetrievedPoints can be lower than NumberOfCollectedPoints /// because the points haven't been retrieved from the HyperWire devices yet. int32_t NumberOfRetrievedPoints; /// @brief Gets whether or not data collection is currently collecting points. bool IsCollecting; /// @brief Gets whether or not the internal data collection buffer has overflowed and stopped with an error. This can happen in Automation1DataCollectionMode_Continuous /// if points are not retrieved fast enough and a single chunk of data exceeds NumberOfPointsToCollect. bool HasOverflowed; /// @brief Gets the current mode of data collection. Automation1DataCollectionMode Mode; } Automation1DataCollectionStatus; /// @brief A handle representing a configuration of data signals to collect from an Automation1 controller /// To obtain a handle of this type, see Automation1_DataCollectionConfig_Create(). /// To add axis, task, or system data signals call the Automation1_DataCollectionConfig_AddAxisDataSignal(), /// Automation1_DataCollectionConfig_AddTaskDataSignal(), and Automation1_DataCollectionConfig_AddSystemDataSignal() functions. /// Make sure to destroy the configuration to avoid leaking memory using the Automation1_DataCollectionConfig_Destroy() function. typedef struct Automation1DataCollectionConfig_T* Automation1DataCollectionConfig; /// @brief Creates a new data collection configuration handle. /// Make sure to call Automation1_DataCollectionConfig_Destroy() to avoid leaking memory when you are done with the configuration. /// @param[In] frequency The frequency of data collection (the number of points to collect in one second). /// @param[In] numberOfPointsToCollect The number of points to collect for each configured data signal. /// @param[Out] configOut The created data collection configuration handle. Only use this if the function call was successful. /// @return Returns true if the configuration was successfully created otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_Create(Automation1DataCollectionFrequency frequency, int32_t numberOfPointsToCollect, Automation1DataCollectionConfig* configOut); /// @brief Creates a new data collection configuration handle. /// Make sure to call Automation1_DataCollectionConfig_Destroy() to avoid leaking memory when you are done with the configuration. /// @param[In] period The time in milliseconds between each point being collected. /// @param[In] numberOfPointsToCollect The number of points to collect for each configured data signal. /// @param[Out] configOut The created data collection configuration handle. Only use this if the function call was successful. /// @return Returns true if the configuration was successfully created otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_CreateWithPeriod(double period, int32_t numberOfPointsToCollect, Automation1DataCollectionConfig* configOut); /// @brief Destroys the data collection configuration handle. /// @param[In] config The data collection configuration to destroy. /// @return Returns true if the configuration handle was destroyed otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_Destroy(Automation1DataCollectionConfig config); /// @brief Adds an axis based data signal to be collected on a specific axis on the Automation1 controller. /// @param[In] config The data collection configuration to add the axis based data signal to. /// @param[In] axisIndex The axis to collect the data signal on. /// @param[In] axisSignal The axis based data signal to collect. /// @param[In] argument The argument for the data signal, if unsure set this to zero. /// @return Returns true if the data signal was successfully added to the configuration otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_AddAxisDataSignal(Automation1DataCollectionConfig config, int32_t axisIndex, Automation1AxisDataSignal axisSignal, int32_t argument); /// @brief Adds a task based data signal to be collected on a specific task on the Automation1 controller. /// @param[In] config The data collection configuration to add the task based data signal to. /// @param[In] taskIndex The task to collect the data signal on. /// @param[In] taskSignal The task based data signal to collect. /// @param[In] argument The argument for the data signal, if unsure set this to zero. /// @return Returns true if the data signal was successfully added to the configuration otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_AddTaskDataSignal(Automation1DataCollectionConfig config, int32_t taskIndex, Automation1TaskDataSignal taskSignal, int32_t argument); /// @brief Adds a system based data signal to be collected on the Automation1 controller. /// @param[In] config The data collection configuration to add the system based data signal to. /// @param[In] systemSignal The system based data signal to collect. /// @param[In] argument The argument for the data signal, if unsure set this to zero. /// @return Returns true if the data signal was successfully added to the configuration otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_AddSystemDataSignal(Automation1DataCollectionConfig config, Automation1SystemDataSignal systemSignal, int32_t argument); /// @brief Adds an Industrial Ethernet mapping to be collected on the Automation1 controller. /// @param[In] config The data collection configuration to add the Industrial Ethernet mapping to. /// @param[In] industrialEthernetMappingName The Industrial Ethernet mapping to collect. /// @return Returns true if the Industrial Ethernet mapping was successfully added to the configuration otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_AddIndustrialEthernetMapping(Automation1DataCollectionConfig config, const char* industrialEthernetMappingName); /// @brief Adds an Industrial Ethernet mapping array to be collected on the Automation1 controller. /// @param[In] config The data collection configuration to add the Industrial Ethernet mapping array to. /// @param[In] industrialEthernetMappingName The Industrial Ethernet mapping array to collect. /// @param[In] industrialEthernetMappingArrayIndex The index of the Industrial Ethernet mapping array to collect. /// @return Returns true if the Industrial Ethernet mapping array was successfully added to the configuration otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_AddIndustrialEthernetMappingArray(Automation1DataCollectionConfig config, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingArrayIndex); /// @brief Removes all data signals from the data collection configuration so that they will not be collected from the Automation1 controller. /// @param[In] config The data collection configuration to remove all data signals from. /// @return Returns true if the data signals were successfully cleared otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollectionConfig_ClearAllDataSignals(Automation1DataCollectionConfig config); /// @brief Gets the current status of any data collection (both Automation1DataCollectionMode_Snapshot and Automation1DataCollectionMode_Continuous). /// @param[In] controller The Automation1 controller where data collection is running. /// @param[Out] statusOut The current status of any data collection. Only use this if the function call was successful. /// This argument must have memory preallocated before passing it into this function. /// @return Returns true if the status of data collection was successful obtained otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetStatus(Automation1Controller controller, Automation1DataCollectionStatus* statusOut); /// @brief Starts data collection on the Automation1 controller with the specified mode and using the specified data collection configuration. /// This function waits for data collection to start but it does not wait for data collection to complete. /// You can stop data collection by calling the Automation1_DataCollection_Stop() function and you can get the collected data by calling the /// Automation1_DataCollection_GetResults() function. /// @param[In] controller The Automation1 controller to start data collection on. /// @param[In] config What data to collect and at what frequency. /// @param[In] collectionMode The data collection mode to start. /// @return Returns true if data collection was successfully started on the controller otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_Start(Automation1Controller controller, Automation1DataCollectionConfig config, Automation1DataCollectionMode collectionMode); /// @brief Stops all data collection on the Automation1 controller, regardless of who started it. /// @param[In] controller The Automation1 controller to stop data collection on. /// @return Returns true if data collection was successfully stopped otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_Stop(Automation1Controller controller); /// @brief Gets results from data collection from the Automation1 controller. This function can return data from completed data collection or from data collection that is still /// occurring. This function waits for data collection to collect the specified number of points, blocking until they are available, and then returns them. /// The allResultsOut argument will be populated with all the points for the first data signal, then all the points for the second data signal, and so on. /// To get the results for a specific data signal see the Automation1_DataCollection_GetAxisResults(), Automation1_DataCollection_GetTaskResults(), /// and Automation1_DataCollection_GetSystemResults() functions. /// @param[In] controller The Automation1 controller to collect results from. /// @param[In] config The configuration that was used to start data collection. /// @param[Out] allResultsOut The out array of data collection results that were collected from the controller. /// This will be populated with all the points for the first data signal, then all the points for the second data signal, and so on. /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] allResultsMaxLength The maximum number of elements to copy to the allResultsOut argument. /// This length divided by the number of configured data signals determines how many points per data signal to get from the controller. If the array length /// provided is smaller than the number of available points then an equal number of points for each data signal will populate the allResultsOut array. /// For example, if there are 4 data signals and 100 points collected for each data signal but this length is set to 200 array elements, the allResultsOut /// array will be populated with the first 50 points for data signal 1, the first 50 points for data signal 2, and so on. /// This must be divisible by the number of signals and must not be greater than the length of the allResultsOut array. /// @return Returns true if results from data collection were collected successfully otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetResults(Automation1Controller controller, Automation1DataCollectionConfig config, double* allResultsOut, int32_t allResultsMaxLength); /// @brief Copies the results for a single axis-based data signal out of the already collected data collection results. /// To collect data collection results from an Automation1 controller see Automation1_DataCollection_GetResults(). /// @param[In] config The configuration that was used to start data collection. /// @param[In] allResults The array of already collected data collection results. /// @param[In] allResultsLength The number of elements in the allResults argument. /// @param[In] axisIndex The axis the data signal was collected on. /// @param[In] axisSignal The axis-based data signal to copy the results of. /// @param[In] argument The argument for the data signal. /// @param[Out] axisResultsOut The out array of axis results that were collected for the data signal on the specified axis (these are copied from the allResults array). /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] axisResultsMaxLength The maximum number of elements to copy to the axisResultsOut argument. This must not be greater than the length of the axisResultsOut array. /// @return Returns true if the axis results were successfully copied from the allResults argument otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetAxisResults(Automation1DataCollectionConfig config, double* allResults, int32_t allResultsLength, int32_t axisIndex, Automation1AxisDataSignal axisSignal, int32_t argument, double* axisResultsOut, int32_t axisResultsMaxLength); /// @brief Copies the results for a single task-based data signal out of the already collected data collection results. /// To collect data collection results see Automation1_DataCollection_GetResults(). /// @param[In] config The configuration that was used to start data collection. /// @param[In] allResults The array of already collected data collection results. /// @param[In] allResultsLength The number of elements in the allResults argument. /// @param[In] taskIndex The task the data signal was collected on. /// @param[In] taskSignal The task-based data signal to copy the results of. /// @param[In] argument The argument for the data signal. /// @param[Out] taskResultsOut The out array of task results that were collected for the data signal on the specified task (these are copied from the allResults array). /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] taskResultsMaxLength The maximum number of elements to copy to the taskResultsOut argument. This must not be greater than the length of the taskResultsOut array. /// @return Returns true if the task results were successfully copied from the allResults argument otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetTaskResults(Automation1DataCollectionConfig config, double* allResults, int32_t allResultsLength, int32_t taskIndex, Automation1TaskDataSignal taskSignal, int32_t argument, double* taskResultsOut, int32_t taskResultsMaxLength); /// @brief Copies the results for a single system-based data signal out of the already collected data collection results. /// To collect data collection results see Automation1_DataCollection_GetResults(). /// @param[In] config The configuration that was used to start data collection. /// @param[In] allResults The array of already collected data collection results. /// @param[In] allResultsLength The number of elements in the allResults argument. /// @param[In] systemSignal The system-based data signal to copy the results of. /// @param[In] argument The argument for the data signal. /// @param[Out] systemResultsOut The out array of system results that were collected for the data signal (these are copied from the allResults array). /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] systemResultsMaxLength The maximum number of elements to copy to the systemResultsOut argument. This must not be greater than the length of the systemResultsOut array. /// @return Returns true if the system results were successfully copied from the allResults argument otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetSystemResults(Automation1DataCollectionConfig config, double* allResults, int32_t allResultsLength, Automation1SystemDataSignal systemSignal, int32_t argument, double* systemResultsOut, int32_t systemResultsMaxLength); /// @brief Copies the results for a single Industrial Ethernet mapping out of the already collected data collection results. /// To collect data collection results see Automation1_DataCollection_GetResults(). /// @param[In] config The configuration that was used to start data collection. /// @param[In] allResults The array of already collected data collection results. /// @param[In] allResultsLength The number of elements in the allResults argument. /// @param[In] industrialEthernetMappingName The Industrial Ethernet mapping to copy the results of. /// @param[Out] industrialEthernetResultsOut The out array of results that were collected for the Industrial Ethernet mapping (these are copied from the allResults array). /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] industrialEthernetResultsMaxLength The maximum number of elements to copy to the industrialEthernetResultsOut argument. This must not be greater than the length of the industrialEthernetResultsOut array. /// @return Returns true if the Industrial Ethernet results were successfully copied from the allResults argument otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetIndustrialEthernetResults(Automation1DataCollectionConfig config, double* allResults, int32_t allResultsLength, const char* industrialEthernetMappingName, double* industrialEthernetResultsOut, int32_t industrialEthernetResultsMaxLength); /// @brief Copies the results for an Industrial Ethernet mapping array out of the already collected data collection results. /// To collect data collection results see Automation1_DataCollection_GetResults(). /// @param[In] config The configuration that was used to start data collection. /// @param[In] allResults The array of already collected data collection results. /// @param[In] allResultsLength The number of elements in the allResults argument. /// @param[In] industrialEthernetMappingName The Industrial Ethernet mapping array to copy the results of. /// @param[In] industrialEthernetMappingArrayIndex The index of the Industrial Ethernet mapping array. /// @param[Out] industrialEthernetResultsOut The out array of results that were collected for the Industrial Ethernet mapping array (these are copied from the allResults array). /// Only use this if the function call was successful. This argument must have memory preallocated before passing it into this function. /// @param[In] industrialEthernetResultsMaxLength The maximum number of elements to copy to the industrialEthernetResultsOut argument. This must not be greater than the length of the industrialEthernetResultsOut array. /// @return Returns true if the Industrial Ethernet results were successfully copied from the allResults argument otherwise returns false. /// See Automation1_GetLastError() and Automation1_GetLastErrorMessage() for more information. AUTOMATION1_CAPI bool Automation1_DataCollection_GetIndustrialEthernetArrayResults(Automation1DataCollectionConfig config, double* allResults, int32_t allResultsLength, const char* industrialEthernetMappingArrayName, int32_t industrialEthernetMappingArrayIndex, double* industrialEthernetResultsOut, int32_t industrialEthernetResultsMaxLength); #if defined(__cplusplus) } #endif #endif // AUTOMATION1DATACOLLECTION_H_INCLUDED