Access Data with the OPC Data Access Explorer

Procedure Overview

This section illustrates the basic steps required to create an OPC Data Access application by visualizing the Triangle Wave and Saw-toothed Wave signals provided with the Matrikon™ OPC Simulation Server. The application logs data to memory and plots that data, highlighting uncertain or bad data points. By visualizing the data you can more clearly see the relationships between the signals.

Note

To run the sample code in the following examples, you must have the Matrikon OPC Simulation Server available on your local machine. For information on installing this, see Install an OPC DA or HDA Simulation Server for OPC Classic Examples. The code requires only minor changes to work with other servers.

The example in this topic uses the OPC Data Access Explorer app. In addition, each step contains information on how to complete that step using command-line code. The entire example is contained in the example file opcdemo_quickstart.

Step 1: Open the OPC Data Access Explorer

Double-click the OPC Data Access Explorer in the Apps menu. The app opens with no hosts, servers, or toolbox objects created. The following figure shows the main components of the OPC Data Access Explorer.

In the following steps, you will fill each of the panes with information required to log data, and you will log the data, by creating and interacting with OPC objects.

Command-Line Equivalent

To open the OPC Data Access Explorer from the command line, type opcDataAccessExplorer at the MATLAB^® prompt.

Step 2: Locate Your OPC Server

In this step, you obtain two pieces of information that the toolbox needs to uniquely identify the OPC server that you want to access. You use this information when you create an OPC Data Access Client object (opcda client object), described in Step 3: Create an OPC Data Access Client Object.

The first piece of information that you require is the hostname of the server computer. The hostname (a descriptive name like PlantServer or an IP address such as 192.168.16.32) qualifies that computer on the network, and is used by the OPC Data Access protocols to determine the available OPC servers on that computer, and to communicate with the computer to establish a connection to the server. In any OPC application, you must know the name of the OPC server’s host, so that a connection with that host can be established. Your network administrator will be able to provide you with a list of hostnames that provide OPC servers on your network. In this example, you will use localhost as the hostname, because you will connect to the OPC server on the same machine as the client.

The second piece of information that you require is the OPC server’s server ID. Each OPC server on a particular host is identified by a unique server ID (also called the Program ID or ProgID), which is allocated to that server on installation. The server ID is a character vector, usually containing periods.

Although your network administrator will be able to provide you with a list of server IDs for a particular host, you can query the host for all available OPC servers. Discover Available Data Access Servers discusses how to query hosts from the command line.

Using the OPC Data Access Explorer you can browse a host using the following steps:

1. In the Hosts and OPC Servers pane, click the Add host icon to open the Host name dialog, shown below.

   

2. In the Host name dialog, enter the name of the host. In this case, you can use the "localhost" alias.

   localhost

   Click OK. The hostname will be added to the OPC Network tree view, and the OPC servers installed on that host will automatically be found and added to the tree view. Your Hosts and OPC Servers pane should look similar to the one shown below.

   

   Note that the local host in this example provides three OPC servers. The Server ID for this example is 'Matrikon.OPC.Simulation.1'.

Command-Line Equivalent

The command-line equivalent for this step uses the function opcserverinfo.

hostInfo = opcserverinfo('localhost')

hostInfo = 
                 Host: 'localhost'
             ServerID: {1x3 cell}
    ServerDescription: {1x3 cell}
     OPCSpecification: {'DA2'  'DA2'  'DA2'}
    ObjectConstructor: {1x3 cell}

Examining the returned structure in more detail provides the server IDs of each OPC server.

allServers = hostInfo.ServerID'

allServers = 
    'Matrikon.OPC.Simulation.1'
    'ICONICS.Simulator.1'
    'Softing.OPCToolboxDemo_ServerDA.1'

Step 3: Create an OPC Data Access Client Object

Once you have determined the hostname and server ID of the OPC server you want to connect to, you can create an opcda client object. The client controls the connection status to the server, and stores any events that take place from that server (such as notification of data changing state, which is called a data change event) in the event log. The opcda client object also contains any Data Access Group objects that you create on the client. For more information on the OPC object hierarchy, see Toolbox Object Hierarchy for the Data Access Standard.

With the OPC Data Access Explorer, you can create a client directly from the Hosts and OPC Servers pane.

Right-click the Matrikon server node and choose Create client. A client will be created in the OPC Toolbox Objects pane, as shown in the following figure.

The name of the client (displayed in the OPC Toolbox Objects pane) is Host/ServerID, where Host is the hostname and ServerID is the Server ID associated with that client. In this example, the client’s name is 'localhost/Matrikon.OPC.Simulation.1'

Once you have created the client, you can view the properties of the client object in the Object Properties pane, as shown in the next figure.

Alternative Methods for Creating Clients

You can create a client in the OPC Data Access Explorer by using any of the following methods:

• Select the MATLAB OPC Clients node in the OPC Toolbox Objects pane and click Add Client in the OPC Toolbox Objects toolbar.

• Choose Add from the Client menu.

• Right-click the MATLAB OPC Clients node in the OPC Toolbox Objects tree and select Create Client.

If you select one of these methods, a dialog appears requesting the hostname and server ID.

When you supply a hostname, you will be able to select the Server ID from a list, by clicking Select. Using the Add client dialog, you can also automatically attempt to connect to the server when the client is created, by checking Connect after creating OPC Client before clicking OK.

Command-Line Equivalent

The command-line equivalent of this step involves using the opcda function, specifying the hostname and Server ID arguments.

da = opcda('localhost', 'Matrikon.OPC.Simulation.1')

da =
   OPC Data Access Object: localhost/Matrikon.OPC.Simulation.1
      Server Parameters
         Host:           localhost
         ServerID:       Matrikon.OPC.Simulation.1
         Status:         disconnected
      Object Parameters
         Group:          0-by-1 dagroup object

For more information on creating clients, see Create OPC Data Access Objects.

Step 4: Connect to the OPC Server

OPC Data Access Client objects are not automatically connected to the server when they are created. This allows you to fully configure an OPC object hierarchy (a client with groups and items) prior to connecting to the server, or without a server even being present.

Note

The Add Client dialog described in Alternative Methods for Creating Clients can connect the client to the server after creating the client object.

To connect the client to the server, you can use the OPC Toolbox Objects toolbar, shown in the following figure.

Click Connect in the OPC Toolbox Objects toolbar. If the client is able to connect to the server, the icon for that client in the OPC Toolbox Objects tree will change to show that the client is connected. If the client could not connect to the server, an error dialog will show any error message returned. See Troubleshooting OPC Issues for information on why a client may not be able to connect to a server.

When you connect an opcda client object to the server associated with that client, the server node in the Hosts and OPC Servers pane also updates to show that the server has a connection to a client in the app. With that connection, the properties of the server are displayed in the Hosts and OPC Servers pane. For this example, a typical view of the app after connecting to a client is shown in the next figure.

The OPC server properties include diagnostic information, such as the supported OPC Data Access interfaces, the time the server was started, and the current server status.

Command-Line Equivalent

You use the connect function to connect an opcda client object to the server at the command line.

connect(da)

Step 5: Create an OPC Data Access Group Object

You create Data Access Group objects (dagroup objects) to control and contain a collection of Data Access Item objects (daitem objects). A dagroup object controls how often the server must notify you of any changes in the item values, control the activation status of the items in that group, and define, start, and stop logging tasks.

To create a dagroup object, click Add group in the OPC Toolbox Objects toolbar. A group is created and automatically named, either by the OPC server or by the toolbox.

On their own, dagroup objects are not useful. Once you add items to a group, you can control those items, read values from the server for all the items in a group, and log data for those items, using the dagroup object. In Step 6 you browse the OPC server for available tags. Step 7 involves adding the items associated with those tags to the dagroup object.

Command-Line Equivalent

To create dagroup objects from the command line, you use the addgroup function. This example adds a group to the opcda client object already created.

grp = addgroup(da)

grp =
   OPC Group Object: Group0
      Object Parameters
         GroupType:        private
         Item:             0-by-1 daitem object
         Parent:           localhost/Matrikon.OPC.Simulation.1
         UpdateRate:       0.5
         DeadbandPercent:  0
      Object Status
         Active:           on
         Subscription:     on
         Logging:          off
         LoggingMode:      memory

See Create Data Access Group Objects for more information on creating group objects from the command line.

Step 6: Browse the Server Name Space

All OPC servers provide access to server items via a server name space. The name space is an ordered list of the server items, usually arranged in a hierarchical format for easy access. A server item (also known as a tag) is a measurement or data point on a server, providing information from a device (such as a pressure sensor) or from another software package that supplies data through OPC Data Access (such as a SCADA package).

Note

If you know the item IDs of the server items you are interested in, you can skip this section and proceed to Step 7: Add OPC Data Access Items to the Group. In this example, assume that you do not know the exact item IDs, although you do know that you want to log information from the Saw-toothed Waves and Triangular Waves provided by the Matrikon Simulation Server.

The Namespace tab of the Hosts and Servers pane allows you to graphically browse a server’s name space. Because most OPC servers contain thousands of server items, retrieving a name space can be time consuming. When you connect to a server for the first time, the name space is not automatically retrieved. You have to request the name space using one of the View buttons in the Server Namespace toolbar, as shown in the following figure.

Click View hierarchical namespace to retrieve the hierarchical name space for the Matrikon OPC Server. A tree view containing the Matrikon name space is shown in the pane. Your pane should look similar to the following figure.

Note

If you choose to view the name space as flat, you get a single list of all server items in the name space, expanded to their fully qualified names. A fully qualified name can be used to create a daitem object.

Browsing the name space using the app also provides some property information for each server item. The properties include the published OPC Item properties such as Value, Quality, and Timestamp, plus additional properties published by the OPC server that may provide more information on that particular server item. For a list of standard OPC properties and an explanation of their use, see OPC DA Server Item Properties.

In this example, you need to locate the Saw-toothed Waves and Triangle Waves signals in the Matrikon Simulation Server. You can achieve this using the following steps:

1. Ensure that you are viewing the hierarchical name space.

2. Expand the Simulation items node. You will see all the signal types that the Matrikon Server simulates.

3. Expand the Saw-toothed Waves node. A number of leaf nodes appear. A leaf node contains no other nodes, and usually signifies a tag on an OPC server.

4. Select the Real8 leaf node. The properties of the server item appear in the properties table below the name space tree, as shown in the following figure.

   

   Note the Item Canonical DataType property, which is double. The Canonical DataType is the data type that the server uses to store the server item’s value.

5. Select the UInt2 leaf node. You will notice that the properties update, and the Item Canonical Datatype property for this server item is uint16. (MATLAB denotes integers with the number of bits in the integer, such as uint16; the Matrikon Server uses the COM Variant convention denoting the number of bytes, such as UInt2.)

You can continue browsing the server name space using the Server Namespace pane in the app. One unique characteristic of the Matrikon Simulation Server is that you can view the connected clients through the name space, by selecting the Clients node in the root of the name space.

In Step 7, you add three items to your newly created group object, using the Server Namespace pane.

Command-Line Equivalent

From the command line, you can browse the server name space using the serveritems function. You need to supply a connected opcda client object to the serveritems function, and an optional character vector argument to limit the returned results. The character vector can contain wildcard characters (*). An example of using serveritems is as follows.

sawtoothItems = serveritems(da, '*Saw*')

sawtoothItems = 
    'Saw-toothed Waves.'
    'Saw-toothed Waves.Int1'
    'Saw-toothed Waves.Int2'
    'Saw-toothed Waves.Int4'
    'Saw-toothed Waves.Money'
    'Saw-toothed Waves.Real4'
    'Saw-toothed Waves.Real8'
    'Saw-toothed Waves.UInt1'
    'Saw-toothed Waves.UInt2'
    'Saw-toothed Waves.UInt4'

The command-line equivalent for obtaining the server item properties is serveritemprops. See the serveritemprops reference page for more information on using the function.

Step 7: Add OPC Data Access Items to the Group

Now that you have found the server items in the name space, you can add Data Access Item objects (daitem object) for those tags to the dagroup object you created in Step 5. A daitem object is a link to a tag in the name space, providing the tag value, and additional information on that item, such as the Canonical Data Type.

Using the app, you create items directly from the name space tree, using a context menu on each node in the tree.

Browse to Simulated Items > Saw-toothed Waves > Real8, and right-click that node to bring up the context menu. Selecting Add to from the context menu provides you with a list of created groups for the item associated with that server, and a menu item to create a New group (and add the item to that group).

The menu displayed for this example is shown in the following figure.

Click Group0 to add the item to the already existing group that you created in Step 5. A daitem object is created in the OPC Toolbox Objects pane. The following figure shows the newly created item highlighted, with the properties of the item shown in the Properties pane.

Read a Value from the Server

A daitem object initially contains no information about the server item that it represents. The daitem object only updates when the server notifies the client of a change in status for that item (the notification is called a data change event) or the client specifically reads a value from the server. Using the app, you can force a read of the item by clicking Read in the Properties pane of the required item.

Click Read. The Value, Quality, and Timestamp fields in the app will update. Value contains the last value that the server read from that particular item. Quality provides a measure of how meaningful Value is. If Quality is Good, then the Value can be trusted to be the same as the device or object to which the item refers, but only at the time provided by the Timestamp field. If Quality is anything other than Good, then the Value of the item is questionable.

Each time you read or obtain data from the server through a data change event, the server will provide you with updated Value, Quality, and Timestamp values.

Add More Items to the Group

Using the Namespace pane, expand the Triangle Waves node and add items for the Real8 and UInt2 server items. You will then have three items associated with your dagroup object. In Step 8, you configure a logging session for that group. You then log data in Step 9 from the three items you just created, and visualize the data in Step 10.

Command-Line Equivalent

You use the additem function to add items to a dagroup object. You need to pass the dagroup object to which the items will be added, and the fully qualified item ID as a character vector. The item IDs were found using the serveritems function in Step 6.

itm1 = additem(grp, 'Saw-toothed Waves.Real8')

itm1 =
   OPC Item Object: Saw-toothed Waves.Real8
      Object Parameters
         Parent:           Group0
         AccessRights:     read/write
         DataType:         double
      Object Status
         Active:           on
      Data:
         Value:   
         Quality: 
         Timestamp:

You can add multiple items to the group in one additem call, by specifying multiple ItemID values in a cell array.

itms = additem(grp, {'Triangle Waves.Real8', ...
'Triangle Waves.UInt2'})

itms =
   OPC Item Object Array:
   Index:  DataType:  Active:  ItemID:
   1       double     on       Triangle Waves.Real8
   2       uint16     on       Triangle Waves.UInt2

For more information on adding items to groups, see Create Data Access Item Objects.

Step 8: View All Item Values

You can view the Value, Quality, and Timestamp for each item using the item properties pane. However, that view only provides access to one item at a time. The group object is designed to allow you to read and write values from all items in the group, and to log data to memory and/or disk. You use the Group Read/Write pane to view the values of the items you created in Step 7 to determine the approximate range of values that each item value varies over. The information from this pane will help you to verify that the data is updating, and whether you can plot the data in one set of axes or in subplots.

Click Group0 in the OPC Toolbox Objects pane. Select the Read/Write tab in the top of the Group properties pane. The OPC Toolbox Objects pane should now look similar to the one shown in the following figure.

The Value, Quality, and Timestamp values in the table of items will continually update as long as you have Subscription enabled. Subscription controls whether data change events are sent by the OPC server to the toolbox, for items whose values change. UpdateRate and DeadbandPercent define how often the items must be queried for a new value, and whether all value changes or only changes of a specified magnitude are sent to the toolbox. For more information on Subscription, see Data Change Events and Subscription.

By observing the data for a while, you will see that the three signals appear to have similar ranges. This indicates that you can visualize the data in the same axes when you plot it in Step 11.

You can also use the Group Read/Write pane for writing values to many items simultaneously. Specify a value in the Write column of the Item data table for each item you want to write to, and click Write, to be able to write to those items.

In Step 10 you will configure a logging task and log data for the three items.

Command-Line Equivalent

You can use the read function with a group object as the first parameter to read values from all items in a group. The read function is discussed in more detail in Read and Write Data on OPC DA Server.

Step 9: Configure Group Properties for Logging

Now that your dagroup object contains items, you can use the group to control the interaction of those items with the server. In this step, you configure the group to log data from those items for 2 minutes at 0.2-second intervals. You will use the logged data in Step 11 to visualize the signals produced by the Matrikon Simulation Server.

OPC Data Access Servers provide access only to "live" data (the last known value of each server item in their name space). In many cases, a single value of a signal is not useful, and a time series containing the signal value over a period of time is helpful in analyzing that signal or signal set. Industrial Communication Toolbox™ allows you to log all OPC items in a group to disk or memory, and to retrieve that data for analysis in MATLAB.

You configure a logging session using the dagroup object. By modifying the properties associated with logging, you control how often the data must be sent from the server to the client, how many records the group must log, and where to log the data. This information is summarized in the Logging pane of the dagroup object properties in the app.

Select the Logging tab in the Properties pane. The following figure shows the Logging pane for the dagroup object created in this example.

Using the Logging pane, configure the logging session using the following steps:

1. Set Update rate to 0.2.

2. Set Number of records to log to 600. Because you want to log for 2 minutes (120 seconds) at 0.2-second update rates, you need 600 (i.e., 120/0.2) records.

You can leave the rest of the logging properties at their default values, because this example uses data logged to memory.

In Step 10 you log the data. In Step 11 you will visualize the data.

Command-Line Equivalent

You use the set function to set OPC object properties. From the MATLAB command line, you can calculate the number of records required for the logging task.

logDuration = 2*60;
logRate = 0.2;
numRecords = ceil(logDuration./logRate)
set(grp, 'UpdateRate',logRate,'RecordsToAcquire',numRecords);

Step 10: Log OPC Server Data

In Step 9 you configured the dagroup object logging properties. Your object is now ready to log the required amount of data to memory.

Click Start in the Logging tab. The logging task begins, and the toolbox engine receives and stores the data from the OPC server. The progress bar indicates the status of the logging task, as shown in the following figure.

Note

The logging task occurs in the background. You can continue working in MATLAB while a logging task is in operation. The logging task is not affected by any other computation taking place in MATLAB, and MATLAB is not blocked from processing by the logging task.

Wait for the task to complete before continuing with Step 11.

Command-Line Equivalent

You use the start function with the required dagroup object to start a logging task.

start(grp)

Although the logging operation takes place in the background, you can instruct MATLAB to wait for the logging task to complete, using the wait function.

wait(grp)

Step 11: Plot the Data

In this introductory example, you use the app to visualize the data logged in Step 10. In a more complex task, you would export the logged data to the workspace and use MATLAB functions to analyze and interpret the logged data.

When the logging task stops, the Logging pane will update to show that the task is complete. An example of the logging status portion of the Logging pane after a completed task is shown in the following figure.

To view the data from the app, click Plot. The logged data will be retrieved from the toolbox engine and displayed in a MATLAB figure window. The format of the displayed data and annotation options are controlled by settings in the Plot options frame of the Logging pane. By default, the plot will be annotated with any data points that have a Quality other than Good. Values whos Quality is Bad are annotated with a large red circle with a black border, and Values with Quality of Repeat are annotated with a yellow star. You should always view the Quality returned with the Value of an item to determine if the Value is meaningful or not. The relationship between the Value and Quality of an item is discussed in OPC Data: Value, Quality, and TimeStamp.

An example of the plotted data is shown in the next figure.

Note

Your plotted data will almost certainly not look like the one shown here, because the logging task was executed at a different time.

Notice how the three signals seem almost completely unrelated, except for the period of the two Real8 signals. The peak values for each signal are different, as are the periods for the two Triangle Waves signals. By visualizing the data, you can gain some insight into the way the Matrikon OPC Simulation Server simulates each tag. In this case, it is apparent that Real8 and UInt2 signals have a different period.

Command-Line Equivalent

When your logging task has completed you transfer data from the toolbox engine to the MATLAB workspace using the getdata function, which provides two types of output, depending on the 'datatype' argument. For more information see getdata in the reference pages. In this case you retrieve the data into separate arrays, and plot the data.

The example below reproduces the figure display that you get when you click Plot.

[logIDs, logVal,logQual,logTime,logEvtTime] = ...
 getdata(grp,'double');
plot(logTime,logVal);
axis tight
datetick('x','keeplimits')
legend(logIDs)

Step 12: Clean Up

When you are finished with an OPC task, you should remove the task objects from memory and clear the MATLAB workspace of the variables associated with these objects. The OPC Data Access Explorer app automatically deletes all objects that it creates from the toolbox engine. If you work only in the OPC Data Access Explorer, you do not need to perform any further cleanup other than to close the app. You close the app by using the Exit option in the File menu, or by using the Close button in the title bar. You will be prompted to save the OPC Data Access Explorer session. You can choose to save the session to an OPC session file (.osf file) for later use, or exit without saving.

Command-Line Equivalent

When you use OPC objects from the MATLAB command line, or from your own functions, you must remove them from the OPC software engine using the delete function. Note that when you delete a toolbox object, the children of that object are automatically removed from the toolbox engine. In the following example, there is no need to delete grp and itm, as they are children of da.

disconnect(da)
delete(da)
clear da grp itm
close(gcf)

For more details about OPC object management, see Delete Objects.