Read OPC Historical Data
After creating an OPC HDA client object (Create OPC HDA Client Object) and connecting it to a server (Connect to OPC HDA Server), you can access an array of functions that enable you to retrieve historical data. The function you use depends on the type and range of the data as well as on whether you need to aggregate or process the data. This topic describes how to retrieve data from an OPC HDA server into MATLAB®.
Read Historical Data over a Time Range
Use the readRaw function to request the
value, quality, and timestamp data for a list of items over a specified duration.
Define the duration by indicating start and end times for the sampling. This
function returns all data stored on the historian within the specified
duration.
By default, historians return data starting with the first data point after the
specified start time and up to the last data point before the specified end time.
You can set the optional 'ExtendedBounds' argument to
true to include the bounding values. If no data exists at the
specified bounds, the server returns a value that is closest to the bounds but
outside the specified duration.
This function is useful if you want to retrieve raw values from the server and process that data using MATLAB rather than relying on the server to perform the processing for you.
For example, this code reads values between 17 November 2010 and 18 November 2010
in the 'Int2' items under the 'Random' branch
of an OPC HDA server, including the bounding values.
DataObject = ReadRaw(HdaClient, 'Random.Int2', ...
datetime(2010,11,17), datetime(2010,11,18), true)Read Historical Data at Specific Times
The readAtTime function reads the values
for a list of item IDs at specific times. This function is useful if your analysis
routine requires regularly sampled data and you can accept the interpolation scheme
used by your server. If no value exists on the server at the specified timestamp,
the function interpolates the value from the surrounding data values.
For example, this code retrieves the current values of two items and their values at the same time yesterday.
itemList = {'Random.Int1', 'Random.Boolean'}
timeStamps = [datetime("now"); datetime("now")-days(1)];
dataObject = readAtTime(hdaClient, itemList, timeStamps)
You can also returns the historical data over a specified time in a data type supported by MATLAB. See Native MATLAB Data Types from Read Operations.
You can specify the MATLAB data type as the fourth argument. This function call returns all the data values as 8-bit signed integers.
dataObject = readAtTime(HdaClient, ItemList, TimeStamps, 'int8')
The function returns the read data as a data object. You can use the data object for further analysis or read the data values as described in Display Data Objects.
Read Processed Aggregate Data
Use the readProcessed function to read
aggregated data from the server if your server supports processing of raw data.
Historians can process raw data in a variety of ways before returning it. Most
servers support processing techniques such as interpolation of data points, time
averaging, and standard deviation calculations. Processing of data is very useful
when there is a large amount of data on the server. Instructing the server to return
only a processed data set can reduce the time and volume of data transferred.
To find which aggregates are supported by the server use the
Aggregates property of a HDA client object connected to a
server. The server in this example supports six types of aggregates.
aggTypes = clientObject.Aggregates
aggTypes =
OPC HDA Aggregate Types:
Name ID Description
----------------- -- -------------------------------------------------------------------------------------------
INTERPOLATIVE 1 Retrieve interpolated values.
TIMEAVERAGE 4 Retrieve the time weighted average data over the resample interval.
MINIMUMACTUALTIME 7 Retrieve the minimum value in the resample interval and the timestamp of the minimum value.
MINIMUM 8 Retrieve the minimum value in the resample interval.
MAXIMUMACTUALTIME 9 Retrieve the maximum value in the resample interval and the timestamp of the maximum value.
MAXIMUM 10 Retrieve the maximum value in the resample interval.Use the readProcessed function with the
property ID of the aggregate type to get processed data. You can retrieve the
property ID using the data object and the aggregate type. In this example, the
readProcessed function splits the time domain into
intervals based on the specified aggregateInterval and
calculates the aggregate values over these intervals.
clientObject.Aggregates.TIMEAVERAGE
4
hdareadProcessed = readProcessed(clientObject, ItemList, clientObject.Aggregates.TIMEAVERAGE, ...
AggregateInterval, StartTime, EndTime)
hdareadProcessed =
1-by-5 OPC HDA Data object:
ItemID Value Start TimeStamp End TimeStamp Quality
------------ -------------- ----------------------- ----------------------- -----------------------------
Random.Int1 1 int8 value 2010-11-28 13:56:40.666 2010-11-29 13:56:40.666 1 unique quality [Calculated]
Random.Boolean 1 logical value 2010-11-28 13:56:40.666 2010-11-29 13:56:40.666 1 unique quality [Calculated]You can also return the aggregated data in a data type supported by MATLAB. See Native MATLAB Data Types from Read Operations.
Reading Modified Data
To track changes in historical data on the server, use the readModified function. This
function returns the timestamps for the changes made by the server and the item
values before the modifications.
For example, this code reads data modified on the previous day for two items.
dataObject = readModified(hdaObj,{'Random.Real8','Random.Real4'},datetime("now")-days(1),datetime("now"));If readRaw, readAtTime, or readProcessed return a quality value of
OPCHDA_EXTRADATA when the server modifies an item. Use
readModified with the item IDs and a time range to retrieve
the details of the changes made by the server.
Native MATLAB Data Types from Read Operations
The default format of returned data is an
M-by-1 OPC HDA data object. This
object contains data values whose type is defined by the OPC variant type used by
the server to store them. In readAtTime and readProcessed, you can specify that the read operations return data
in native MATLAB data types, including structures and cell arrays.
For example, you can return the same set of data as a structure, MATLAB data type, or cell array.
Return Data as Structure
Use this code to return the read data as a structure containing four fields.
struct = HDAObject.readAtTime('Random.Int1', TimeStamps, 'struct')
struct =
ItemID: 'Random.Int1'
Timestamp: [8x1 double]
Quality: [8x1 double]
Value: [8x1 int8]Return Data as MATLAB Data Type
When you request MATLAB numeric types as output, the read operation returns four outputs: Item ID, Value, Quality, and Timestamp. The Value output is converted into the MATLAB data type requested. This example returns all Value data as unsigned 32-bit integers:
[itmId, val, Q, ts] = HDAObject.readAtTime('Random.Int1', TimeStamps, 'uint32');Return Data as Cell Array
When requesting cell array output, the read operation returns four outputs: Item ID, Value, Quality, and Timestamp. The Value output is a cell array, preserving the original data type of the item on the server.
[cItemId, cVal, cQ, cTimes] = HDAObject.readAtTime('Random.Int1', TimeStamps, 'cell')
