Access Data at the Command Line

DA Programming Overview

This section illustrates the basic steps to create an OPC Data Access application by visualizing the Triangle Wave and Saw-toothed Wave signals provided by 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 steps you need the Matrikon OPC Simulation Server on your local machine. For installation details, see Install an OPC DA or HDA Simulation Server for OPC Classic Examples. The code requires only minor changes to work with other servers.

Step 1: Locate Your OPC Data Access Server

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

The first piece of information is the host name of the server computer. The host name (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 can provide a list of host names that provide OPC servers on your network. In this example, you will use localhost as the host name, because you will connect to the OPC server on the same machine as the client.

The second piece of information 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 text character vector, usually containing periods.

Although your network administrator can provide 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.

Use the opcserverinfo function to make a query from the command line.

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 2: Create an OPC Data Access Client Object

After determining the host name and server ID of the OPC server to connect to, you can create an opcda client object. The client controls the connection status to the server, and stores any events that occur 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 details on the OPC object hierarchy, see Toolbox Object Hierarchy for the Data Access Standard.

Use the opcda function to specify the host name and Server ID.

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 details on creating clients, see Create OPC Data Access Objects.

Step 3: Connect to the OPC Data Access 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) before connecting to the server, or without a server even being present.

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

connect(da)

Step 4: 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, controls the activation status of the items in that group, and defines, starts, and stops logging tasks.

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 5 you browse the OPC server for available tags. Step 6 involves adding the items associated with those tags to the dagroup object.

Use the addgroup function to create dagroup objects from the command line. 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 5: 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 go directly to Step 6: 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.

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 for obtaining the server item properties is serveritemprops. See the serveritemprops reference page for details.

Step 6: 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 4. 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.

Reading 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.

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

Adding More Items to the Group

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 5.

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 details on adding items to groups, see Create Data Access Item Objects.

Step 7: View All Item Values

The group object lets you read and write values from all items in the group, and log data to memory and/or disk.

The Value, Quality, and Timestamp values of items 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 details 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 10.

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

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 detail in Read and Write Data on OPC DA Server.

Step 8: Configure Group Properties for Logging

Now that your dagroup object contains items, use the group to control the interaction of those items with the server. In this step, configure the group to log data from those items for 2 minutes at 0.2-second intervals. You can use the logged data in Step 9 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 DA 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.

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

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

Step 9: Log OPC Server Data

Now that you configured the dagroup object's logging properties, your object can log the required amount of data to memory.

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

start(grp)

The logging task occurs in the background. You can continue working in MATLAB while a logging task is in operation. The logging task is unaffected by other computations occurring in MATLAB, and MATLAB processing is not blocked by the logging task. You can instruct MATLAB to wait for the logging task to complete, using the wait function.

wait(grp)

Step 10: Plot the Data

After logging finishes, transfer data from the toolbox engine to the MATLAB workspace using the getdata function, which provides two types of output, depending on its 'datatype' argument. For details, see the getdata reference page. In this case you retrieve the data into separate arrays, and plot the data.

This example produces the figure:

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

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.

Step 11: Clean Up

After finishing an OPC task, you should remove the task objects from memory and clear the MATLAB workspace of the variables associated with these objects.

When using OPC objects at the MATLAB command line or from your own functions, you must remove them from the toolbox 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 this 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)

OPC object management is discussed in detail in Delete Objects.