Using OPC Toolbox™ software, you can exchange data with the
OPC server using individual items, or using the dagroup
object
to perform the operation on multiple items. The reading and writing
operation can be performed synchronously, so
that your MATLAB® session will wait for the operation to complete,
or asynchronously, allowing your MATLAB session
to continue processing while the operation takes place in the background.
You can read data from any item that is associated with a connected client. When you perform the read operation on an item, the server will return information about the server item associated with that item ID. The read operation can be performed synchronously or asynchronously:
Use Synchronous Read Operations describes how to perform synchronous read operations. Synchronous read operations can request data from the server's cache, or directly from the device.
Use Asynchronous Read Operations describes how to perform asynchronous read operations.
A synchronous read operation means that MATLAB will wait for the server to return data from a read request before continuing processing. The data returned by the server can come from the server's cache, or you can request that the server read values from the device that the server item refers to.
You use the read
function
to perform synchronous read operations, passing the daitem
object
associated with the server item you want to read. If the read operation
is successful, the data is returned in a structure containing information
about the read operation, including the value of the server item,
the quality of that value, and the time that the server obtained that
value. The item's Value
, Quality
and Timestamp
properties
are also updated to reflect the values obtained from the read operation.
The following example creates an opcda
client
object and configures a group with one item, 'Random.Real8'
.
A synchronous read operation is then performed on the item.
da = opcda('localhost','Matrikon.OPC.Simulation.1'); connect(da); grp = addgroup(da); itm1 = additem(grp,'Random.Real8'); r = read(itm1)
r = ItemID: 'Random.Real8' Value: 4.3252e+003 Quality: 'Good: Non-specific' TimeStamp: [2004 3 2 9 50 26.6710] Error: ''
Specify the Source of the Read Operation. By default, a synchronous read operation will return data from
the OPC server's cache. By reading from the cache, you do not have
to wait for a possibly slow device to provide data to the server.
You can specify the source of the synchronous read operation as the
second parameter to the read
function. If the source
is specified as 'device'
, the server will read
a value from the device, and return that value to you (as well as
updating the server cache with that value).
Note
Reading from the device may be slow. If the read operation generates
a time-out error, you may need to increase the value of the Timeout
property
of the opcda
client object associated with the
group or item in order to support synchronous reads from the device.
The following example reads data from the device associated
with itm1
.
r = read(itm1,'device')
r = ItemID: 'Random.Real8' Value: 9.1297e+003 Quality: 'Good: Non-specific' TimeStamp: [2004 3 2 10 8 20.2650] Error: ''
Read from the Cache with Inactive Items. In order to reduce communication traffic and speed up data access,
OPC servers do not store all server item values in their cache. Only
those server items that are active will be stored
in the server cache. Therefore, synchronous read operations from the
cache on an inactive item will return data that may not correspond
to the current device value. If you attempt to read data from an inactive
item using the read
function, and do not specify 'device'
as
the source, the Quality
will be set to 'Bad:
Out of Service'
.
You control the active status of an item using the Active
property.
The following example sets the Active
property
of the item to 'off'
and attempts to read from
the cache.
itm1.Active = 'off';
r = read(itm1)
Warning: One or more items is inactive. (Type "warning off opc:read:iteminactive" to suppress this warning.) r = ItemID: 'Random.Real8' Value: 8.4278e+003 Quality: 'Bad: Out of Service' TimeStamp: [2004 3 2 10 17 19.9370] Error: ''
An asynchronous read operation creates a request to read data, and then sends that request to the server. Once the request has been accepted, MATLAB continues processing the next instruction without waiting to receive any values from the server. When the data is ready to be returned, the server sends the data back to MATLAB by generating a read async event. MATLAB will handle that event as soon as it is able to perform that task.
Asynchronous read operations always return data from the device.
By using an asynchronous read operation, you can continue performing tasks in MATLAB while the value is being read from the device, and then process the returned value when the server is able to provide it back to MATLAB.
You perform asynchronous read operations using the readasync
function,
passing the daitem
object that you want to read
from. If successful, the function will return a transaction
ID, a unique identifier for that asynchronous transaction.
You can use that transaction ID to identify the read operation when
it is returned through the read async event.
When an asynchronous read operation is processed in MATLAB, the item's Value
, Quality
and
Timestamp
properties are also updated to reflect the values obtained
from the asynchronous read operation.
The following example of using an asynchronous read operation
uses the default callback for a read async event. The default callback
is set to the opccallback
function, which displays
information about the event in the command line.
tid = readasync(itm1)
tid = 3
The transaction ID for this operation is 3. A little while later, the default callback function displays the following information at the command line.
OPC ReadAsync event occurred at local time 10:44:49 Transaction ID: 3 Group Name: Group0 1 items read.
You can change the read async event callback function by setting
the ReadAsyncFcn
property of the dagroup
object.
You can write data to individual items, or to groups of items.
This section describes how to write data to individual items. See Read and Write Multiple Values for information on using dagroup
objects
to write data to multiple items.
You can write data to an OPC server using a synchronous write operation, in which case MATLAB will wait for the server to acknowledge that the write operation succeeds, or using an asynchronous write operation, in which case MATLAB is free to continue performing other tasks while the write operation takes place. Because write operations always apply directly to the device, a synchronous write operation may take a significant amount of time, particularly if the device that you are writing to has a slow connection to the OPC server.
You use the write
function
to perform synchronous write operations. The first argument is the daitem
object
that represents the server item you want to write to. The second argument
is the value that you want to write to that server item. The write
function
does not return any results, but will generate an error if the write
operation is not successful.
The following example creates an item with item ID 'Bucket
Brigade.Real8'
and writes the value 10.34
to
the item. The value is then read using a synchronous read operation.
itm2 = additem(grp,'Bucket Brigade.Real8'); write(itm2, 10.34) r = read(itm2,'device')
You do not need to ensure that the data type of the value you
are writing, and the data type of the daitem
object,
are the same. OPC Toolbox software relies on the server to perform
the conversion from the data type you provide, to the data type required
for that server item. For information on how the toolbox handles different
data types, see Work with Different Data Types.
An asynchronous write operation creates a request to write data, and then sends that request to the server. Once the request has been accepted, MATLAB continues processing the next instruction without waiting for the data to be written. When the write operation completes on the server, the server notifies MATLAB that the operation completed by generating a write async event containing information on whether the write operation succeeded, and an error message if applicable. MATLAB will handle that event as soon as it is able to perform that task.
You use the writeasync
function
to write values to the server asynchronously. The first argument is
the daitem
object that represents the server item
you want to write to. The second argument is the value you want to
write to that server item. The return value is the transaction
ID of the operation. You can use the transaction ID to
identify the write operation when it is returned through the write
async event.
The following example uses asynchronous operations to write
the value 57.8
to the item 'Bucket Brigade.Real8'
created
earlier.
tid = writeasync(itm2, 57.8)
tid = 4
A while later, the standard callback (opccallback
)
will display the results of the write operation to the command line.
OPC WriteAsync event occurred at local time 11:15:27 Transaction ID: 4 Group Name: Group0 1 items written.
You can change the write async event callback function by setting
the WriteAsyncFcn
property of the dagroup
object.
When you use the read and write operation on a single daitem
object,
you read or write a single value per transaction. OPC Toolbox software
allows you to perform one operation to read multiple item values,
or to write multiple values. You can also use a dagroup
object
to read and write values using all items in the group, or you can
perform read and write operations on item object vectors.
A daitem
object vector is a single variable
in the MATLAB workspace containing more than one daitem
object.
You can construct item vectors using any of the standard concatenation
techniques available in MATLAB. See Create OPC Toolbox Data Access Object Vectors for
information on creating and working with toolbox object vectors.
When you perform any read or write operation on a dagroup
object,
it is the equivalent of performing the operation on the Item
property
of that group, which is a daitem
object vector
representing all items that are contained within the dagroup
object.
The following sections describe how to perform read and write operations on multiple items:
Read Multiple Values describes how to read multiple values
from an item vector or dagroup
object.
Write Multiple Values describes how to write multiple values
to an item vector or dagroup
object.
Error Handling for Multiple Item Read and Write Operations explains how OPC Toolbox software deals with errors when performing read and write operations on multiple objects.
The following sections describe how synchronous read operations and asynchronous read operations behave for multiple items.
Synchronous Read Operations. When you read multiple values using the read
function,
the returned value will be a structure array. Each element of the
structure will contain the same fields. One of the fields is the item
ID that the information in that element of the structure refers to.
The following example performs a synchronous read operation
on the dagroup
object created in the previous examples
in this section.
r = read(grp)
r = 2x1 struct array with fields: ItemID Value Quality TimeStamp Error
To display the first record in the structure array, use indexing into the structure.
r(1)
ans = ItemID: 'Random.Real8' Value: 3.7068e+003 Quality: 'Good: Non-specific' TimeStamp: [2004 3 2 11 49 52.5460] Error: ''
To display all values of a particular field, you can use the list generation syntax in MATLAB. Enclosing that list in a cell array groups the values into one variable.
{r.Value}
ans = {3.7068e+003 10}
Asynchronous Read Operations. When you read multiple values using the readasync
function,
the return value is still a single transaction ID. The multiple values
will be returned in the read async event structure passed to the ReadAsyncFcn
callback.
For information on the structure of the read async event, see Event Types.
When you perform a write operation on multiple items you need to specify multiple values, one for each item you are writing to. OPC Toolbox software requires these multiple values to be in a cell array, since the data types for each value may be different. For information on constructing cell arrays, see MATLAB Programming.
Note
Even if you are using the same data type for every value being
written to the dagroup
object or daitem
object
vector, you must still use a cell array to specify the individual
values. Use the num2cell
function
to convert numeric arrays to cell arrays.
The following example writes values to a dagroup
object
containing two items.
write(grp, {1.234, 5.43})
When reading and writing with multiple items, an error generated by performing the operation on one item will not automatically generate an error in MATLAB. The following rules apply to reading and writing with multiple items:
If all items fail the operation, an error will be generated. The error message will contain specific information for each item about why the item failed.
If some items fail but some succeed, the operation does not error, but generates a warning, listing which items failed and the reason for failure.
Note that for asynchronous read and write operations, items may fail early (during the request for the operation) or late (when the information is returned from the server). If any items fail late, an error event will be generated in addition to the read async event or write async event.